@tanstack/ai/dist/esm/activities/chat/agents/bound.d.ts

Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.

import { embed } from '../../embed/index.js';
import { rerank } from '../../rerank/index.js';
import { decide } from '../../evaluate/index.js';
import { GenerationMiddleware } from '../../middleware/types.js';
import { InterruptDefinition } from '../../../interrupt-definition.js';
import { AnyChatMiddleware } from '../middleware/types.js';
import { PromptCacheRetention, RunAgentResumeItem, SchemaInput } from '../../../types.js';
import { DefinedAgent, SubagentContextExtension, SubagentRunContext, SubagentRunInput } from './define-agent.js';
import { SubagentBudget } from './limits.js';
import { ProviderKeys } from '../../../byok/keyed.js';
import { BoundTextActivityOptions, TextActivityOptions, TextActivityResult, WithOptionalThreadId } from '../index.js';
import { AnyTextAdapter } from '../adapter.js';
import { SummarizeActivityOptions, SummarizeActivityResult } from '../../summarize/index.js';
import { SummarizeAdapter } from '../../summarize/adapter.js';
import { ImageActivityOptions, ImageActivityResult } from '../../generateImage/index.js';
import { ImageAdapter } from '../../generateImage/adapter.js';
import { VideoActivityResult, VideoCreateOptions } from '../../generateVideo/index.js';
import { VideoAdapter } from '../../generateVideo/adapter.js';
import { AudioActivityOptions, AudioActivityResult, AudioProviderOptions } from '../../generateAudio/index.js';
import { AudioAdapter } from '../../generateAudio/adapter.js';
import { TTSActivityOptionsBase, TTSActivityResult, TTSProviderOptions, TTSTextOrTurns } from '../../generateSpeech/index.js';
import { TTSAdapter } from '../../generateSpeech/adapter.js';
import { VoiceActivityOptions, VoiceActivityResult, VoiceProviderOptions } from '../../generateVoice/index.js';
import { VoiceAdapter } from '../../generateVoice/adapter.js';
import { TranscriptionActivityOptions, TranscriptionActivityResult, TranscriptionProviderOptions } from '../../generateTranscription/index.js';
import { TranscriptionAdapter } from '../../generateTranscription/adapter.js';
import { WorldActivityOptions, WorldActivityResult, WorldProviderOptions } from '../../generateWorld/index.js';
import { WorldAdapter } from '../../generateWorld/adapter.js';
import { LiveVideoActivityOptions, LiveVideoActivityResult, LiveVideoProviderOptions } from '../../generateLiveVideo/index.js';
import { LiveVideoAdapter } from '../../generateLiveVideo/adapter.js';
import { DebugOption } from '../../../logger/types.js';
/**
 * The fields a child `chat()` needs, in one spread:
 * `chat({ adapter, messages, ...ctx.forward })`.
 */
export interface SubagentForward {
    threadId: string;
    runId: string;
    parentRunId: string;
    subagentRunId: string;
    /** The agent name. Middleware reads it as `ctx.subagentName`. */
    subagentName: string;
    /** The subagentRunId of the child that started this one, for a nested child. */
    parentSubagentRunId?: string;
    resume?: Array<RunAgentResumeItem>;
    /** Aborts when the parent run or the subagent group stops. */
    abortController: AbortController;
    /** The prompt cache retention of the parent call, when it has one. */
    promptCache?: PromptCacheRetention;
}
/**
 * What a host adds to every activity call an agent makes through `ctx`. Apps
 * using plain `chat({ subagents })` do not set it.
 *
 * @internal For hosts that run agents, such as `@tanstack/ai-harness`.
 */
export interface SubagentBinding {
    /**
     * Added before the call's own middleware on every `ctx.chat` call. A
     * child's `ctx.chat({ subagents })` passes it down to its own children.
     */
    chatMiddleware?: ReadonlyArray<AnyChatMiddleware>;
    /**
     * Added after the call's own middleware on every `ctx.chat` call, so it
     * sees the final config and tool results (for example a host middleware
     * that scrubs secrets or logs results). A child's `ctx.chat({ subagents })`
     * passes it down to its own children, after their own.
     */
    lastChatMiddleware?: ReadonlyArray<AnyChatMiddleware>;
    /**
     * Added before the call's own middleware on every generation call. A
     * child's `ctx.chat({ subagents })` passes it down to its own children.
     */
    generationMiddleware?: ReadonlyArray<GenerationMiddleware>;
    /**
     * Interrupt definitions added to every `ctx.chat` call, so the host
     * middleware in `chatMiddleware` can stop the child with them. The call's
     * own `interrupts` (for example, the agent's own definitions) win: a host
     * definition with the same id is not added. A child's
     * `ctx.chat({ subagents })` passes them down to its own children. A plain
     * `chat()` call does not get them.
     */
    interrupts?: ReadonlyArray<InterruptDefinition<any, any, any, any>>;
    /**
     * The subagent tree budget. A child's `ctx.chat({ subagents })` passes it
     * down, so limits hold across the whole tree.
     */
    budget?: SubagentBudget;
    /**
     * The provider keys an agent reads as `ctx.keys`. `subagents.keys` sets
     * them. A child's `ctx.chat({ subagents })` passes them down to its own
     * children. Without them, `ctx.keys` reads each provider's `env` names.
     */
    keys?: ProviderKeys;
    /**
     * The prompt cache retention of the parent call. A child's `ctx.chat()`
     * uses it when the call gives no `promptCache`.
     */
    promptCache?: PromptCacheRetention;
    /**
     * The `debug` option for the model calls of a child agent that set no
     * `debug` of their own. A child's `ctx.chat({ subagents })` passes it down
     * to its own children.
     */
    debug?: DebugOption;
    /**
     * Adds fields to the `ctx` of every run. A host declares their types by
     * augmenting `SubagentContextExtension`. It passes down to nested children.
     */
    extend?: (ctx: SubagentRunContext) => Partial<SubagentContextExtension>;
    /**
     * Starts a child without waiting for it and returns its id at once. The
     * agent tools call it for `background: true`. With
     * `wake: true`, the host starts a new parent turn when the child ends. It
     * does not pass down to nested children.
     */
    start?: (call: {
        agent: string;
        input?: unknown;
        prompt?: string;
        parentToolCallId?: string;
    }, options: {
        wake: true;
    }) => Promise<{
        subagentRunId: string;
        /** Settles when the child ends. `maxConcurrent` counts the child until then. */
        done: Promise<unknown>;
    }>;
}
/**
 * Activity functions bound to one child run. Each takes the same options as
 * the plain function, but `threadId` is optional: the child run fills it.
 * Options you pass win over the bound defaults.
 */
export interface BoundActivities {
    chat: <TAdapter extends AnyTextAdapter, TSchema extends SchemaInput | undefined = undefined, TStream extends boolean = boolean, const TTools extends TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'] = TextActivityOptions<TAdapter, TSchema, TStream, any>['tools'], const TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = [], TContext = unknown, const TMiddleware extends Array<unknown> | undefined = undefined, const TAgents extends ReadonlyArray<DefinedAgent> = ReadonlyArray<DefinedAgent>>(options: BoundTextActivityOptions<TAdapter, TSchema, TStream, TTools, TInterrupts, TContext, TMiddleware, TAgents>) => TextActivityResult<TSchema, TStream, TTools>;
    summarize: <TAdapter extends SummarizeAdapter<string, object>, TStream extends boolean = false>(options: WithOptionalThreadId<SummarizeActivityOptions<TAdapter, TStream>>) => SummarizeActivityResult<TStream>;
    generateImage: <TAdapter extends ImageAdapter<string, any, any, any>, TStream extends boolean = false>(options: WithOptionalThreadId<ImageActivityOptions<TAdapter, TStream>>) => ImageActivityResult<TStream>;
    generateVideo: <TAdapter extends VideoAdapter<string, any, any, any, any, any>, TStream extends boolean = false>(options: WithOptionalThreadId<VideoCreateOptions<TAdapter, TStream>>) => VideoActivityResult<'create', TStream>;
    generateAudio: <TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>, TStream extends boolean = false>(options: WithOptionalThreadId<AudioActivityOptions<TAdapter, TStream>>) => AudioActivityResult<TStream>;
    generateSpeech: <TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>, TStream extends boolean = false>(options: WithOptionalThreadId<TTSActivityOptionsBase<TAdapter, TStream>> & TTSTextOrTurns) => TTSActivityResult<TStream>;
    generateVoice: <TAdapter extends VoiceAdapter<string, VoiceProviderOptions<TAdapter>>, TStream extends boolean = false>(options: WithOptionalThreadId<VoiceActivityOptions<TAdapter, TStream>>) => VoiceActivityResult<TStream>;
    generateTranscription: <TAdapter extends TranscriptionAdapter<string, TranscriptionProviderOptions<TAdapter>>, TStream extends boolean = false>(options: WithOptionalThreadId<TranscriptionActivityOptions<TAdapter, TStream>>) => TranscriptionActivityResult<TStream>;
    generateWorld: <TAdapter extends WorldAdapter<string, WorldProviderOptions<TAdapter>>, TStream extends boolean = false>(options: WithOptionalThreadId<WorldActivityOptions<TAdapter, TStream>>) => WorldActivityResult<TStream>;
    generateLiveVideo: <TAdapter extends LiveVideoAdapter<string, LiveVideoProviderOptions<TAdapter>>, TStream extends boolean = false>(options: WithOptionalThreadId<LiveVideoActivityOptions<TAdapter, TStream>>) => LiveVideoActivityResult<TStream>;
    embed: typeof embed;
    rerank: typeof rerank;
    decide: typeof decide;
}
export declare function createBoundActivities(agentName: string, input: SubagentRunInput, abortController: AbortController, binding?: SubagentBinding): BoundActivities;