AAI SDK
    Preparing search index...

    Type Alias ToolContext<S>

    Context passed to tool execute functions.

    Provides access to the session environment, state, database, and conversation history from within a tool's execute handler.

    import { tool } from "@alexkroman1/aai";
    import { z } from "zod";

    const lookupNote = tool({
      description: "Look up a note from the database",
      inputSchema: z.object({ id: z.string() }),
      execute: async ({ id }, ctx) => {
        const rows = await ctx.db.query("select body from notes where id = $1", [id]);
        return { id, note: rows[0] ?? null };
      },
    });
    type ToolContext<S = DefaultSessionState> = {
        db: Db;
        env: Readonly<Record<string, string>>;
        generate: GenerateFn;
        messages: readonly Message[];
        sessionId: string;
        signal?: AbortSignal;
        state: S;
        send(event: string, data: unknown): void;
    }

    Type Parameters

    • S = DefaultSessionState

      The shape of per-session state created by the agent's state factory. Defaults to DefaultSessionState; annotate the context (ctx: ToolContext<MyState>) to get real checking.

    Index
    db env generate messages sessionId signal? state
    send
    db: Db

    SQL database scoped to this app. Available when storage is enabled (aai storage enable, or Settings → Database in the studio); accessing it otherwise throws.

    env: Readonly<Record<string, string>>

    Environment variables available to this agent's tools (from .env under aai dev, aai secret in production). Custom keys a tool depends on should be declared in AgentDef.requiredEnv so a missing value fails at deploy time.

    generate: GenerateFn

    One-shot LLM generation, executed on the host (like db). Defaults to the agent's pipeline llm; pass llm in the options to use another provider (its API key must be in the agent's env). Throws when no LLM is configured or named. Pass a Zod schema for typed structured output (GenerateFn).

    messages: readonly Message[]

    Read-only snapshot of conversation messages so far.

    sessionId: string

    Unique identifier for the current session. Useful for correlating logs across concurrent sessions.

    signal?: AbortSignal

    Cooperative cancellation signal. Aborts when the turn that issued this tool call is cancelled (barge-in, reset, or session stop). Long-running tools should pass it to fetch etc. so their work stops promptly; absent in execution contexts that don't support cancellation.

    state: S

    Mutable per-session state created by the agent's state factory.

    • Push a custom event to the connected browser client. Fire-and-forget: events whose name exceeds MAX_CLIENT_EVENT_NAME_LENGTH or whose serialized payload exceeds MAX_CLIENT_EVENT_PAYLOAD_BYTES are dropped (with a warning log), not thrown.

      Parameters

      • event: string
      • data: unknown

      Returns void

    Settings
    Member Visibility

    On This Page
    Properties
    Methods