AAI SDK
    Preparing search index...

    Type Alias RuntimeOptions

    Configuration for createRuntime.

    Configures the agent, environment, database, logging, and S2S connection.

    type RuntimeOptions = {
        agent: AgentDef<any>;
        db?: Db;
        env: AgentEnv;
        fetch?: typeof globalThis.fetch;
        llm?: LlmProvider;
        logger?: Logger;
        onToolResult?: (
            msg: { error?: string; result: string; toolCallId: string },
        ) => void;
        providerEnv?: ProviderEnv;
        runCode?: (code: string) => Promise<string | { error: string }>;
        s2sConfig?: S2SConfig;
        sessionStartTimeoutMs?: number;
        shutdownTimeoutMs?: number;
        stt?: SttProvider;
        toolGuidance?: string[];
        tts?: TtsProvider;
    }
    Index
    agent db? env fetch? llm? logger? onToolResult? providerEnv? runCode? s2sConfig? sessionStartTimeoutMs? shutdownTimeoutMs? stt? toolGuidance? tts?
    agent: AgentDef<any>
    db?: Db

    SQL database exposed to tool code as ctx.db. When omitted, the runtime connects one itself from DATABASE_URL in the provider env (self-hosted aai dev parity with the platform's database switch); with neither, ctx.db access throws.

    env: AgentEnv

    The agent's own env — what tool code sees as ctx.env. Typed AgentEnv: a withHostCredentialFallback result (which may carry host/shell credentials) is a compile error here — pass it as RuntimeOptions.providerEnv instead.

    fetch?: typeof globalThis.fetch

    Override the fetch implementation used by built-in tools (web_search, visit_webpage, get_page_design, fetch_json). Defaults to builtinFetch(): SSRF-screened unless the spawner declared a real container around the process (AAI_SANDBOX_CONTAINED=1), in which case the sandbox is the boundary and the screen is skipped. Override only in tests.

    llm?: LlmProvider

    LLM provider descriptor, from a factory like anthropic(...).

    logger?: Logger

    Structured logger for runtime and session logs. Defaults to the console.

    onToolResult?: (
        msg: { error?: string; result: string; toolCallId: string },
    ) => void

    Host/relay mode hook. When set, inbound tool_result frames are routed to this handler (which settles the relay's pending call) and the session skips its own tool_call emit since the relay executeTool emits it. Paired with a relay executeTool + toolSchemas. See host-mode.ts.

    providerEnv?: ProviderEnv

    Environment used to resolve provider credentials (STT/TTS/LLM). Defaults to RuntimeOptions.env.

    Exists so a self-hosted caller can let shell-exported credentials reach the provider resolvers without also placing them in ctx.env, where agent tool code could read them and come to depend on host-level variables that do not exist in production. The platform passes neither — it resolves everything from the agent's own stored env.

    runCode?: (code: string) => Promise<string | { error: string }>

    In-sandbox executor for the run_code builtin. Only the platform's guest harness provides one — it runs inside the Modal sandbox, which is the security boundary. Without it, run_code refuses to evaluate code in this process (the self-hosted guard).

    s2sConfig?: S2SConfig

    S2S endpoint URL and audio sample rates. Defaults to DEFAULT_S2S_CONFIG.

    sessionStartTimeoutMs?: number

    Timeout in ms for session.start() (S2S connection setup). Defaults to 10 000 (10 s).

    shutdownTimeoutMs?: number

    Maximum time in milliseconds to wait for sessions to stop during shutdown(). Defaults to 30_000 (30 s).

    stt?: SttProvider

    STT provider descriptor (SttProvider). Must be set together with llm and tts to route sessions through the pipeline path; leave all three unset to fall back to the agent's own provider fields (which default to the all-AssemblyAI pipeline when the agent declares none).

    toolGuidance?: string[]

    System prompt guidance for builtin tools. Passed through in sandbox mode.

    tts?: TtsProvider

    TTS provider descriptor (TtsProvider).

    Settings
    Member Visibility

    On This Page
    Properties