AgUiServer
Serves Agent User Interaction (AG-UI) runs over HTTP.
AG-UI clients POST a RunAgentInput as JSON and read the run's events as
Server-Sent Events, one JSON event per data: line. This module defines that
binding as an HttpApiEndpoint, so it can join an existing HttpApi, and
provides a layer that mounts a single run handler on an HttpRouter. The
agent constructor serves a LanguageModel with server tools, frontend
tools, and multiple model rounds.
Example Serving a model as an AG-UI agent
import { AgUi, AgUiServer, LanguageModel } from "effect/ai"
const AgentRoute = AgUiServer.layerHttp({ path: "/agent", run: (input) => LanguageModel.streamText({ prompt: AgUi.toPrompt(input) }).pipe( AgUi.fromStreamParts )})Constructors
Creates an AG-UI agent that answers each run with the current
LanguageModel and a toolkit.
Details
- The prompt is
system, if given, followed by the run's conversation as converted byAgUi.toPrompt, which drops client-supplied instructions. - The model is offered the server toolkit and each of the run's tools as a
client-executed tool. A run whose tools reuse a server tool's name is
rejected with
400. - Rounds follow
Chat.streamTextwithmaxSteps, so server tool results go back to the model until a round needs no tools,maxStepsrounds have run, or a tool call is left for the application. - The run finishes with the token usage summed over every round. Frontend
tool calls left for the application are listed as
pendingToolCallIds, and the application answers them with tool messages in its next run. - Server tool handlers can read the run's input from RunInput.
See
- layerHttp for serving the agent
Signature
declare function agent<Tools extends Record<string, Any>>(options: { readonly maxSteps?: number; readonly system?: string; readonly toolkit: Toolkit<Tools>;}): Agent<LanguageModel | HandlersFor<Tools> | Exclude<SchemaServices<Tools[keyof Tools]>, RunInput> | Exclude<Requirements<Tools[keyof Tools]>, RunInput>>Example Serving a model with server tools
import { Effect, Schema } from "effect"import { AgUiServer, Tool, Toolkit } from "effect/ai"
const GetTime = Tool.make("GetTime", { success: Schema.String })const Tools = Toolkit.make(GetTime)
const AgentRoute = AgUiServer.layerHttp({ path: "/agent", agent: AgUiServer.agent({ toolkit: Tools, system: "Be brief", maxSteps: 5 })})
const ToolsLayer = Tools.toLayer({ GetTime: () => Effect.sync(() => new Date().toISOString())}) Since v4.1.0 Source
When to use
Use to serve an agent from an endpoint in an existing HttpApi.
Yield it while building the HttpApiBuilder.group that implements the
endpoint.
Details
The services the agent needs are captured when the handler is created. Each
request first runs the agent's validation, so a rejected input is answered
with 400 before the event stream opens. The events are then served as
described in handler.
See
- handler for serving a function that streams events
Signature
declare function agentHandler<R>(agent: Agent<R>): Effect<(__namedParameters: { readonly payload: { readonly context: readonly Array<{ readonly description: string; readonly value: string; }>; readonly forwardedProps?: unknown; readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "developer"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "system"; readonly subagentRunId?: string; } | { readonly content?: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "assistant"; readonly subagentRunId?: string; readonly toolCalls?: readonly Array<{ readonly encryptedValue?: ... | ...; readonly function: { readonly arguments: ...; readonly name: ...; }; readonly id: string; readonly metadata?: ... | ...; readonly type: "function"; }>; } | { readonly content: string | readonly Array<{ readonly id?: ...; readonly metadata?: ...; readonly text: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; }>; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "user"; readonly subagentRunId?: string; } | { readonly content: string | readonly Array<{ readonly id?: ...; readonly metadata?: ...; readonly text: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; }>; readonly encryptedValue?: string; readonly error?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "tool"; readonly subagentRunId?: string; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "activity"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "reasoning"; readonly subagentRunId?: string; }>; readonly parentRunId?: string; readonly protocolVersion?: string; readonly resume?: readonly Array<{ readonly interruptId: string; readonly metadata?: { [key: string]: unknown; }; readonly payload?: unknown; readonly status: "resolved" | "cancelled"; }>; readonly runId: string; readonly state?: unknown; readonly threadId: string; readonly tools: readonly Array<{ readonly description: string; readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly parameters?: unknown; }>; };}) => Effect<withHeaders<Stream<{ readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly rawEvent?: unknown; readonly role?: "developer" | "system" | "assistant" | "user"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_START";} | { readonly delta: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_CONTENT";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_END";} | { readonly delta?: string; readonly messageId?: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly rawEvent?: unknown; readonly role?: "developer" | "system" | "assistant" | "user"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_CHUNK";} | { readonly metadata?: { [key: string]: unknown; }; readonly parentMessageId?: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly toolCallName: string; readonly type: "TOOL_CALL_START";} | { readonly delta: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_ARGS";} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_END";} | { readonly delta?: string; readonly metadata?: { [key: string]: unknown; }; readonly parentMessageId?: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId?: string; readonly toolCallName?: string; readonly type: "TOOL_CALL_CHUNK";} | { readonly content: string | readonly Array<{ readonly id?: ...; readonly metadata?: ...; readonly text: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; }>; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly role?: "tool"; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_RESULT";} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly snapshot: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STATE_SNAPSHOT";} | { readonly delta: readonly Array<{ readonly op: "add"; readonly path: string; readonly value: unknown; } | { readonly op: "remove"; readonly path: string; } | { readonly op: "replace"; readonly path: string; readonly value: unknown; } | { readonly from: string; readonly op: "move"; readonly path: string; } | { readonly from: string; readonly op: "copy"; readonly path: string; } | { readonly op: "test"; readonly path: string; readonly value: unknown; }>; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STATE_DELTA";} | { readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly name?: ... | ...; readonly role: "developer"; readonly subagentRunId?: ... | ...; } | { readonly content: string; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly name?: ... | ...; readonly role: "system"; readonly subagentRunId?: ... | ...; } | { readonly content?: ... | ...; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly name?: ... | ...; readonly role: "assistant"; readonly subagentRunId?: ... | ...; readonly toolCalls?: ... | ...; } | { readonly content: ... | ...; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly name?: ... | ...; readonly role: "user"; readonly subagentRunId?: ... | ...; } | { readonly content: ... | ...; readonly encryptedValue?: ... | ...; readonly error?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly role: "tool"; readonly subagentRunId?: ... | ...; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: ...]: ...; }; readonly id: string; readonly metadata?: ... | ...; readonly role: "activity"; readonly subagentRunId?: ... | ...; } | { readonly content: string; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly role: "reasoning"; readonly subagentRunId?: ... | ...; }>; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly timestamp?: number; readonly type: "MESSAGES_SNAPSHOT";} | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly replace?: boolean; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "ACTIVITY_SNAPSHOT";} | { readonly activityType: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly patch: readonly Array<{ readonly op: "add"; readonly path: string; readonly value: unknown; } | { readonly op: "remove"; readonly path: string; } | { readonly op: "replace"; readonly path: string; readonly value: unknown; } | { readonly from: string; readonly op: "move"; readonly path: string; } | { readonly from: string; readonly op: "copy"; readonly path: string; } | { readonly op: "test"; readonly path: string; readonly value: unknown; }>; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "ACTIVITY_DELTA";} | { readonly event: unknown; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly source?: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "RAW";} | { readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "CUSTOM"; readonly value: unknown;} | { readonly input?: { readonly context: readonly Array<{ readonly description: ...; readonly value: ...; }>; readonly forwardedProps?: unknown; readonly messages: readonly Array<... | ... | ... | ... | ... | ... | ...>; readonly parentRunId?: string; readonly protocolVersion?: string; readonly resume?: readonly Array<...>; readonly runId: string; readonly state?: unknown; readonly threadId: string; readonly tools: readonly Array<{ readonly description: ...; readonly metadata?: ...; readonly name: ...; readonly parameters?: ...; }>; }; readonly metadata?: { [key: string]: unknown; }; readonly parentRunId?: string; readonly protocolVersion?: string; readonly rawEvent?: unknown; readonly runId: string; readonly threadId: string; readonly timestamp?: number; readonly type: "RUN_STARTED";} | { readonly metadata?: { [key: string]: unknown; }; readonly outcome?: { readonly pendingToolCallIds?: readonly Array<...>; readonly type: "success"; } | { readonly interrupts: readonly [{ readonly expiresAt?: ...; readonly id: ...; readonly message?: ...; readonly metadata?: ...; readonly reason: ...; readonly responseSchema?: ...; readonly subagentRunId?: ...; readonly toolCallId?: ...; }, { readonly expiresAt?: ...; readonly id: ...; readonly message?: ...; readonly metadata?: ...; readonly reason: ...; readonly responseSchema?: ...; readonly subagentRunId?: ...; readonly toolCallId?: ...; }]; readonly type: "interrupt"; } | { readonly type: "cancelled"; }; readonly rawEvent?: unknown; readonly result?: unknown; readonly runId: string; readonly threadId: string; readonly timestamp?: number; readonly type: "RUN_FINISHED"; readonly usage?: readonly Array<{ readonly cachedInputTokens?: ... | ...; readonly cacheWriteInputTokens?: ... | ...; readonly inputTokens?: ... | ...; readonly model?: ... | ...; readonly outputTokens?: ... | ...; readonly provider?: ... | ...; readonly reasoningTokens?: ... | ...; readonly totalTokens?: ... | ...; }>;} | { readonly code?: string; readonly message: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly timestamp?: number; readonly type: "RUN_ERROR"; readonly usage?: readonly Array<{ readonly cachedInputTokens?: ... | ...; readonly cacheWriteInputTokens?: ... | ...; readonly inputTokens?: ... | ...; readonly model?: ... | ...; readonly outputTokens?: ... | ...; readonly provider?: ... | ...; readonly reasoningTokens?: ... | ...; readonly totalTokens?: ... | ...; }>;} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly stepName: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STEP_STARTED";} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly stepName: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STEP_FINISHED";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_START";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly role: "reasoning"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_START";} | { readonly delta: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_CONTENT";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_END";} | { readonly delta?: string; readonly messageId?: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_CHUNK";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_END";} | { readonly encryptedValue: string; readonly entityId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly subtype: "message" | "tool-call"; readonly timestamp?: number; readonly type: "REASONING_ENCRYPTED_VALUE";} | { readonly description?: string; readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly parentMessageId?: string; readonly parentSubagentRunId?: string; readonly parentToolCallId?: string; readonly rawEvent?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_STARTED";} | { readonly metadata?: { [key: string]: unknown; }; readonly outcome?: { readonly type: "success"; } | { readonly interruptIds?: readonly Array<...>; readonly type: "suspended"; }; readonly rawEvent?: unknown; readonly result?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_FINISHED";} | { readonly code?: string; readonly message: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_ERROR";}, never, Exclude<R, R>>, { "cache-control": "no-cache";}>, BadRequest, never>, never, R>Creates the POST endpoint declaration for AG-UI runs.
When to use
Use to add an AG-UI agent to an existing HttpApi, and implement it with
handler.
Details
The payload is a JSON RunAgentInput, so an invalid body is rejected with
400 before the event stream opens, as is input an agent rejects.
The success response is a text/event-stream of AG-UI events sent as
data: lines, with Cache-Control: no-cache and a keepalive comment every
15 seconds.
See
Signature
declare function endpoint<Name extends string, Path extends PathInput>(name: Name, path: Path): HttpApiEndpoint<Name, "POST", Path, never, never, toCodecJson<Struct<{ readonly context: withDecodingDefaultTypeKey<$Array<Struct<{ readonly description: String; readonly value: String; }>>, never>; readonly forwardedProps: optionalKey<Unknown>; readonly messages: decodeTo<$Array<toType<Union<readonly [Struct<{ readonly content: ...; readonly encryptedValue: ...; readonly id: ...; readonly metadata: ...; readonly name: ...; readonly role: ...; readonly subagentRunId: ...; }>, Struct<{ readonly content: ...; readonly encryptedValue: ...; readonly id: ...; readonly metadata: ...; readonly name: ...; readonly role: ...; readonly subagentRunId: ...; }>, Struct<{ readonly content: ...; readonly encryptedValue: ...; readonly id: ...; readonly metadata: ...; readonly name: ...; readonly role: ...; readonly subagentRunId: ...; readonly toolCalls: ...; }>, Struct<{ readonly content: ...; readonly encryptedValue: ...; readonly id: ...; readonly metadata: ...; readonly name: ...; readonly role: ...; readonly subagentRunId: ...; }>, Struct<{ readonly content: ...; readonly encryptedValue: ...; readonly error: ...; readonly id: ...; readonly metadata: ...; readonly role: ...; readonly subagentRunId: ...; readonly toolCallId: ...; }>, Struct<{ readonly activityType: ...; readonly content: ...; readonly id: ...; readonly metadata: ...; readonly role: ...; readonly subagentRunId: ...; }>, Struct<{ readonly content: ...; readonly encryptedValue: ...; readonly id: ...; readonly metadata: ...; readonly role: ...; readonly subagentRunId: ...; }>]>>>, $Array<Union<readonly [Union<readonly [Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>]>, Any]>>, never, never>; readonly parentRunId: optionalKey<String>; readonly protocolVersion: optionalKey<String>; readonly resume: optionalKey<decodeTo<$Array<toType<Struct<{ readonly interruptId: String; readonly metadata: optionalKey<...>; readonly payload: optionalKey<...>; readonly status: Literals<...>; }>>>, $Array<Union<readonly [Struct<{ readonly interruptId: ...; readonly metadata: ...; readonly payload: ...; readonly status: ...; }>, Any]>>, never, never>>; readonly runId: String; readonly state: optionalKey<Unknown>; readonly threadId: String; readonly tools: withDecodingDefaultTypeKey<$Array<Struct<{ readonly description: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: String; readonly parameters: optionalKey<Unknown>; }>>, never>;}>>, never, WithHeaders<StreamSse<SseEventFromData<Union<readonly [Struct<{ readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: optionalKey<String>; readonly rawEvent: optionalKey<Unknown>; readonly role: optionalKey<Literals<readonly [..., ..., ..., ...]>>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"TEXT_MESSAGE_START">;}>, Struct<{ readonly delta: String; readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"TEXT_MESSAGE_CONTENT">;}>, Struct<{ readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"TEXT_MESSAGE_END">;}>, Struct<{ readonly delta: optionalKey<String>; readonly messageId: optionalKey<String>; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: optionalKey<String>; readonly rawEvent: optionalKey<Unknown>; readonly role: optionalKey<Literals<readonly [..., ..., ..., ...]>>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"TEXT_MESSAGE_CHUNK">;}>, Struct<{ readonly metadata: optionalKey<$Record<String, Unknown>>; readonly parentMessageId: optionalKey<String>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly toolCallId: String; readonly toolCallName: String; readonly type: Literal<"TOOL_CALL_START">;}>, Struct<{ readonly delta: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly toolCallId: String; readonly type: Literal<"TOOL_CALL_ARGS">;}>, Struct<{ readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly toolCallId: String; readonly type: Literal<"TOOL_CALL_END">;}>, Struct<{ readonly delta: optionalKey<String>; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly parentMessageId: optionalKey<String>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly toolCallId: optionalKey<String>; readonly toolCallName: optionalKey<String>; readonly type: Literal<"TOOL_CALL_CHUNK">;}>, Struct<{ readonly content: Union<readonly [String, decodeTo<..., ..., ..., ...>]>; readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly role: optionalKey<Literal<"tool">>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly toolCallId: String; readonly type: Literal<"TOOL_CALL_RESULT">;}>, Struct<{ readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly snapshot: Unknown; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"STATE_SNAPSHOT">;}>, Struct<{ readonly delta: $Array<Union<readonly [..., ..., ..., ..., ..., ...]>>; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"STATE_DELTA">;}>, Struct<{ readonly messages: decodeTo<$Array<toType<...>>, $Array<Union<...>>, never, never>; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"MESSAGES_SNAPSHOT">;}>, Struct<{ readonly activityType: String; readonly content: $Record<String, Unknown>; readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly replace: optionalKey<Boolean>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"ACTIVITY_SNAPSHOT">;}>, Struct<{ readonly activityType: String; readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly patch: $Array<Union<readonly [..., ..., ..., ..., ..., ...]>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"ACTIVITY_DELTA">;}>, Struct<{ readonly event: Unknown; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly source: optionalKey<String>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"RAW">;}>, Struct<{ readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: String; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"CUSTOM">; readonly value: Unknown;}>, Struct<{ readonly input: optionalKey<Struct<{ readonly context: ...; readonly forwardedProps: ...; readonly messages: ...; readonly parentRunId: ...; readonly protocolVersion: ...; readonly resume: ...; readonly runId: ...; readonly state: ...; readonly threadId: ...; readonly tools: ...; }>>; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly parentRunId: optionalKey<String>; readonly protocolVersion: optionalKey<String>; readonly rawEvent: optionalKey<Unknown>; readonly runId: String; readonly threadId: String; readonly timestamp: optionalKey<Int>; readonly type: Literal<"RUN_STARTED">;}>, Struct<{ readonly metadata: optionalKey<$Record<String, Unknown>>; readonly outcome: optionalKey<Union<readonly [..., ..., ...]>>; readonly rawEvent: optionalKey<Unknown>; readonly result: optionalKey<Unknown>; readonly runId: String; readonly threadId: String; readonly timestamp: optionalKey<Int>; readonly type: Literal<"RUN_FINISHED">; readonly usage: optionalKey<$Array<Struct<...>>>;}>, Struct<{ readonly code: optionalKey<String>; readonly message: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"RUN_ERROR">; readonly usage: optionalKey<$Array<Struct<...>>>;}>, Struct<{ readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly stepName: String; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"STEP_STARTED">;}>, Struct<{ readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly stepName: String; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"STEP_FINISHED">;}>, Struct<{ readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"REASONING_START">;}>, Struct<{ readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly role: Literal<"reasoning">; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"REASONING_MESSAGE_START">;}>, Struct<{ readonly delta: String; readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"REASONING_MESSAGE_CONTENT">;}>, Struct<{ readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"REASONING_MESSAGE_END">;}>, Struct<{ readonly delta: optionalKey<String>; readonly messageId: optionalKey<String>; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"REASONING_MESSAGE_CHUNK">;}>, Struct<{ readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"REASONING_END">;}>, Struct<{ readonly encryptedValue: String; readonly entityId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly subtype: Literals<readonly ["tool-call", "message"]>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"REASONING_ENCRYPTED_VALUE">;}>, Struct<{ readonly description: optionalKey<String>; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: String; readonly parentMessageId: optionalKey<String>; readonly parentSubagentRunId: optionalKey<String>; readonly parentToolCallId: optionalKey<String>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: String; readonly timestamp: optionalKey<Int>; readonly type: Literal<"SUBAGENT_STARTED">;}>, Struct<{ readonly metadata: optionalKey<$Record<String, Unknown>>; readonly outcome: optionalKey<Union<readonly [..., ...]>>; readonly rawEvent: optionalKey<Unknown>; readonly result: optionalKey<Unknown>; readonly subagentRunId: String; readonly timestamp: optionalKey<Int>; readonly type: Literal<"SUBAGENT_FINISHED">;}>, Struct<{ readonly code: optionalKey<String>; readonly message: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: String; readonly timestamp: optionalKey<Int>; readonly type: Literal<"SUBAGENT_ERROR">;}>]>>, Never, { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly rawEvent?: unknown; readonly role?: "developer" | "system" | "assistant" | "user"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_START";} | { readonly delta: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_CONTENT";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_END";} | { readonly delta?: string; readonly messageId?: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly rawEvent?: unknown; readonly role?: "developer" | "system" | "assistant" | "user"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_CHUNK";} | { readonly metadata?: { [key: string]: unknown; }; readonly parentMessageId?: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly toolCallName: string; readonly type: "TOOL_CALL_START";} | { readonly delta: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_ARGS";} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_END";} | { readonly delta?: string; readonly metadata?: { [key: string]: unknown; }; readonly parentMessageId?: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId?: string; readonly toolCallName?: string; readonly type: "TOOL_CALL_CHUNK";} | { readonly content: string | readonly Array<{ readonly id?: string; readonly metadata?: unknown; readonly text: string; readonly type: "text"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "image"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "audio"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "video"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "document"; }>; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly role?: "tool"; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_RESULT";} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly snapshot: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STATE_SNAPSHOT";} | { readonly delta: readonly Array<{ readonly op: "add"; readonly path: string; readonly value: unknown; } | { readonly op: "remove"; readonly path: string; } | { readonly op: "replace"; readonly path: string; readonly value: unknown; } | { readonly from: string; readonly op: "move"; readonly path: string; } | { readonly from: string; readonly op: "copy"; readonly path: string; } | { readonly op: "test"; readonly path: string; readonly value: unknown; }>; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STATE_DELTA";} | { readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "developer"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "system"; readonly subagentRunId?: string; } | { readonly content?: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "assistant"; readonly subagentRunId?: string; readonly toolCalls?: readonly Array<{ readonly encryptedValue?: ...; readonly function: ...; readonly id: ...; readonly metadata?: ...; readonly type: ...; }>; } | { readonly content: string | readonly Array<... | ... | ... | ... | ...>; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "user"; readonly subagentRunId?: string; } | { readonly content: string | readonly Array<... | ... | ... | ... | ...>; readonly encryptedValue?: string; readonly error?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "tool"; readonly subagentRunId?: string; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "activity"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "reasoning"; readonly subagentRunId?: string; }>; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly timestamp?: number; readonly type: "MESSAGES_SNAPSHOT";} | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly replace?: boolean; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "ACTIVITY_SNAPSHOT";} | { readonly activityType: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly patch: readonly Array<{ readonly op: "add"; readonly path: string; readonly value: unknown; } | { readonly op: "remove"; readonly path: string; } | { readonly op: "replace"; readonly path: string; readonly value: unknown; } | { readonly from: string; readonly op: "move"; readonly path: string; } | { readonly from: string; readonly op: "copy"; readonly path: string; } | { readonly op: "test"; readonly path: string; readonly value: unknown; }>; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "ACTIVITY_DELTA";} | { readonly event: unknown; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly source?: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "RAW";} | { readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "CUSTOM"; readonly value: unknown;} | { readonly input?: { readonly context: readonly Array<{ readonly description: string; readonly value: string; }>; readonly forwardedProps?: unknown; readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly name?: ... | ...; readonly role: "developer"; readonly subagentRunId?: ... | ...; } | { readonly content: string; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly name?: ... | ...; readonly role: "system"; readonly subagentRunId?: ... | ...; } | { readonly content?: ... | ...; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly name?: ... | ...; readonly role: "assistant"; readonly subagentRunId?: ... | ...; readonly toolCalls?: ... | ...; } | { readonly content: ... | ...; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly name?: ... | ...; readonly role: "user"; readonly subagentRunId?: ... | ...; } | { readonly content: ... | ...; readonly encryptedValue?: ... | ...; readonly error?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly role: "tool"; readonly subagentRunId?: ... | ...; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: ...]: ...; }; readonly id: string; readonly metadata?: ... | ...; readonly role: "activity"; readonly subagentRunId?: ... | ...; } | { readonly content: string; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly role: "reasoning"; readonly subagentRunId?: ... | ...; }>; readonly parentRunId?: string; readonly protocolVersion?: string; readonly resume?: readonly Array<{ readonly interruptId: string; readonly metadata?: ... | ...; readonly payload?: unknown; readonly status: ... | ...; }>; readonly runId: string; readonly state?: unknown; readonly threadId: string; readonly tools: readonly Array<{ readonly description: string; readonly metadata?: { [key: ...]: ...; }; readonly name: string; readonly parameters?: unknown; }>; }; readonly metadata?: { [key: string]: unknown; }; readonly parentRunId?: string; readonly protocolVersion?: string; readonly rawEvent?: unknown; readonly runId: string; readonly threadId: string; readonly timestamp?: number; readonly type: "RUN_STARTED";} | { readonly metadata?: { [key: string]: unknown; }; readonly outcome?: { readonly pendingToolCallIds?: readonly Array<string>; readonly type: "success"; } | { readonly interrupts: readonly [{ readonly expiresAt?: string; readonly id: string; readonly message?: string; readonly metadata?: { [key: ...]: ...; }; readonly reason: string; readonly responseSchema?: { [key: ...]: ...; }; readonly subagentRunId?: string; readonly toolCallId?: string; }, { readonly expiresAt?: string; readonly id: string; readonly message?: string; readonly metadata?: { [key: ...]: ...; }; readonly reason: string; readonly responseSchema?: { [key: ...]: ...; }; readonly subagentRunId?: string; readonly toolCallId?: string; }]; readonly type: "interrupt"; } | { readonly type: "cancelled"; }; readonly rawEvent?: unknown; readonly result?: unknown; readonly runId: string; readonly threadId: string; readonly timestamp?: number; readonly type: "RUN_FINISHED"; readonly usage?: readonly Array<{ readonly cachedInputTokens?: number; readonly cacheWriteInputTokens?: number; readonly inputTokens?: number; readonly model?: string; readonly outputTokens?: number; readonly provider?: string; readonly reasoningTokens?: number; readonly totalTokens?: number; }>;} | { readonly code?: string; readonly message: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly timestamp?: number; readonly type: "RUN_ERROR"; readonly usage?: readonly Array<{ readonly cachedInputTokens?: number; readonly cacheWriteInputTokens?: number; readonly inputTokens?: number; readonly model?: string; readonly outputTokens?: number; readonly provider?: string; readonly reasoningTokens?: number; readonly totalTokens?: number; }>;} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly stepName: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STEP_STARTED";} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly stepName: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STEP_FINISHED";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_START";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly role: "reasoning"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_START";} | { readonly delta: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_CONTENT";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_END";} | { readonly delta?: string; readonly messageId?: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_CHUNK";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_END";} | { readonly encryptedValue: string; readonly entityId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly subtype: "message" | "tool-call"; readonly timestamp?: number; readonly type: "REASONING_ENCRYPTED_VALUE";} | { readonly description?: string; readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly parentMessageId?: string; readonly parentSubagentRunId?: string; readonly parentToolCallId?: string; readonly rawEvent?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_STARTED";} | { readonly metadata?: { [key: string]: unknown; }; readonly outcome?: { readonly type: "success"; } | { readonly interruptIds?: readonly Array<string>; readonly type: "suspended"; }; readonly rawEvent?: unknown; readonly result?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_FINISHED";} | { readonly code?: string; readonly message: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_ERROR";}>, toCodecStringTree<Struct<{ "cache-control": Literal<"no-cache">;}>>>, toCodecJson<typeof BadRequest>, never, never>Creates an HttpApiBuilder handler for an endpoint from a function
that streams the events of one run.
Details
The stream returned by run is wrapped with AgUi.withRunLifecycle, so the
client receives RUN_STARTED first and exactly one RUN_FINISHED or
RUN_ERROR last. Failures of the stream, including events that cannot be
encoded as JSON, are logged and reported, and reach the client as a
RUN_ERROR without error details. The stream runs with the
services available to the handler.
See
- endpoint for declaring the endpoint
Signature
declare function handler<E, R>(run: (input: { readonly context: readonly Array<{ readonly description: string; readonly value: string; }>; readonly forwardedProps?: unknown; readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "developer"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "system"; readonly subagentRunId?: string; } | { readonly content?: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "assistant"; readonly subagentRunId?: string; readonly toolCalls?: readonly Array<{ readonly encryptedValue?: string; readonly function: { readonly arguments: string; readonly name: string; }; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly type: "function"; }>; } | { readonly content: string | readonly Array<{ readonly id?: string; readonly metadata?: unknown; readonly text: string; readonly type: "text"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "image"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "audio"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "video"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "document"; }>; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "user"; readonly subagentRunId?: string; } | { readonly content: string | readonly Array<{ readonly id?: string; readonly metadata?: unknown; readonly text: string; readonly type: "text"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "image"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "audio"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "video"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "document"; }>; readonly encryptedValue?: string; readonly error?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "tool"; readonly subagentRunId?: string; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "activity"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "reasoning"; readonly subagentRunId?: string; }>; readonly parentRunId?: string; readonly protocolVersion?: string; readonly resume?: readonly Array<{ readonly interruptId: string; readonly metadata?: { [key: string]: unknown; }; readonly payload?: unknown; readonly status: "resolved" | "cancelled"; }>; readonly runId: string; readonly state?: unknown; readonly threadId: string; readonly tools: readonly Array<{ readonly description: string; readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly parameters?: unknown; }>;}) => Stream<{ readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly rawEvent?: unknown; readonly role?: "developer" | "system" | "assistant" | "user"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_START";} | { readonly delta: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_CONTENT";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_END";} | { readonly delta?: string; readonly messageId?: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly rawEvent?: unknown; readonly role?: "developer" | "system" | "assistant" | "user"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_CHUNK";} | { readonly metadata?: { [key: string]: unknown; }; readonly parentMessageId?: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly toolCallName: string; readonly type: "TOOL_CALL_START";} | { readonly delta: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_ARGS";} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_END";} | { readonly delta?: string; readonly metadata?: { [key: string]: unknown; }; readonly parentMessageId?: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId?: string; readonly toolCallName?: string; readonly type: "TOOL_CALL_CHUNK";} | { readonly content: string | readonly Array<{ readonly id?: string; readonly metadata?: unknown; readonly text: string; readonly type: "text"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: string; readonly type: "data"; readonly value: string; } | { readonly mimeType?: ... | ...; readonly type: "url"; readonly value: string; } | { readonly mimeType?: ... | ...; readonly provider?: ... | ...; readonly type: "file"; readonly value: string; }; readonly type: "image"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: string; readonly type: "data"; readonly value: string; } | { readonly mimeType?: ... | ...; readonly type: "url"; readonly value: string; } | { readonly mimeType?: ... | ...; readonly provider?: ... | ...; readonly type: "file"; readonly value: string; }; readonly type: "audio"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: string; readonly type: "data"; readonly value: string; } | { readonly mimeType?: ... | ...; readonly type: "url"; readonly value: string; } | { readonly mimeType?: ... | ...; readonly provider?: ... | ...; readonly type: "file"; readonly value: string; }; readonly type: "video"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: string; readonly type: "data"; readonly value: string; } | { readonly mimeType?: ... | ...; readonly type: "url"; readonly value: string; } | { readonly mimeType?: ... | ...; readonly provider?: ... | ...; readonly type: "file"; readonly value: string; }; readonly type: "document"; }>; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly role?: "tool"; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_RESULT";} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly snapshot: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STATE_SNAPSHOT";} | { readonly delta: readonly Array<{ readonly op: "add"; readonly path: string; readonly value: unknown; } | { readonly op: "remove"; readonly path: string; } | { readonly op: "replace"; readonly path: string; readonly value: unknown; } | { readonly from: string; readonly op: "move"; readonly path: string; } | { readonly from: string; readonly op: "copy"; readonly path: string; } | { readonly op: "test"; readonly path: string; readonly value: unknown; }>; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STATE_DELTA";} | { readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "developer"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "system"; readonly subagentRunId?: string; } | { readonly content?: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "assistant"; readonly subagentRunId?: string; readonly toolCalls?: readonly Array<{ readonly encryptedValue?: ... | ...; readonly function: { readonly arguments: ...; readonly name: ...; }; readonly id: string; readonly metadata?: ... | ...; readonly type: "function"; }>; } | { readonly content: string | readonly Array<{ readonly id?: ...; readonly metadata?: ...; readonly text: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; }>; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "user"; readonly subagentRunId?: string; } | { readonly content: string | readonly Array<{ readonly id?: ...; readonly metadata?: ...; readonly text: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; } | { readonly id?: ...; readonly metadata?: ...; readonly source: ...; readonly type: ...; }>; readonly encryptedValue?: string; readonly error?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "tool"; readonly subagentRunId?: string; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "activity"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "reasoning"; readonly subagentRunId?: string; }>; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly timestamp?: number; readonly type: "MESSAGES_SNAPSHOT";} | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly replace?: boolean; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "ACTIVITY_SNAPSHOT";} | { readonly activityType: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly patch: readonly Array<{ readonly op: "add"; readonly path: string; readonly value: unknown; } | { readonly op: "remove"; readonly path: string; } | { readonly op: "replace"; readonly path: string; readonly value: unknown; } | { readonly from: string; readonly op: "move"; readonly path: string; } | { readonly from: string; readonly op: "copy"; readonly path: string; } | { readonly op: "test"; readonly path: string; readonly value: unknown; }>; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "ACTIVITY_DELTA";} | { readonly event: unknown; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly source?: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "RAW";} | { readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "CUSTOM"; readonly value: unknown;} | { readonly input?: { readonly context: readonly Array<{ readonly description: string; readonly value: string; }>; readonly forwardedProps?: unknown; readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly name?: string; readonly role: "developer"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly name?: string; readonly role: "system"; readonly subagentRunId?: string; } | { readonly content?: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly name?: string; readonly role: "assistant"; readonly subagentRunId?: string; readonly toolCalls?: readonly Array<...>; } | { readonly content: string | readonly Array<...>; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly name?: string; readonly role: "user"; readonly subagentRunId?: string; } | { readonly content: string | readonly Array<...>; readonly encryptedValue?: string; readonly error?: string; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly role: "tool"; readonly subagentRunId?: string; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly role: "activity"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly role: "reasoning"; readonly subagentRunId?: string; }>; readonly parentRunId?: string; readonly protocolVersion?: string; readonly resume?: readonly Array<{ readonly interruptId: string; readonly metadata?: { [key: ...]: ...; }; readonly payload?: unknown; readonly status: "resolved" | "cancelled"; }>; readonly runId: string; readonly state?: unknown; readonly threadId: string; readonly tools: readonly Array<{ readonly description: string; readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly parameters?: unknown; }>; }; readonly metadata?: { [key: string]: unknown; }; readonly parentRunId?: string; readonly protocolVersion?: string; readonly rawEvent?: unknown; readonly runId: string; readonly threadId: string; readonly timestamp?: number; readonly type: "RUN_STARTED";} | { readonly metadata?: { [key: string]: unknown; }; readonly outcome?: { readonly pendingToolCallIds?: readonly Array<string>; readonly type: "success"; } | { readonly interrupts: readonly [{ readonly expiresAt?: string; readonly id: string; readonly message?: string; readonly metadata?: { [key: string]: unknown; }; readonly reason: string; readonly responseSchema?: { [key: string]: unknown; }; readonly subagentRunId?: string; readonly toolCallId?: string; }, { readonly expiresAt?: string; readonly id: string; readonly message?: string; readonly metadata?: { [key: string]: unknown; }; readonly reason: string; readonly responseSchema?: { [key: string]: unknown; }; readonly subagentRunId?: string; readonly toolCallId?: string; }]; readonly type: "interrupt"; } | { readonly type: "cancelled"; }; readonly rawEvent?: unknown; readonly result?: unknown; readonly runId: string; readonly threadId: string; readonly timestamp?: number; readonly type: "RUN_FINISHED"; readonly usage?: readonly Array<{ readonly cachedInputTokens?: number; readonly cacheWriteInputTokens?: number; readonly inputTokens?: number; readonly model?: string; readonly outputTokens?: number; readonly provider?: string; readonly reasoningTokens?: number; readonly totalTokens?: number; }>;} | { readonly code?: string; readonly message: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly timestamp?: number; readonly type: "RUN_ERROR"; readonly usage?: readonly Array<{ readonly cachedInputTokens?: number; readonly cacheWriteInputTokens?: number; readonly inputTokens?: number; readonly model?: string; readonly outputTokens?: number; readonly provider?: string; readonly reasoningTokens?: number; readonly totalTokens?: number; }>;} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly stepName: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STEP_STARTED";} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly stepName: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STEP_FINISHED";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_START";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly role: "reasoning"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_START";} | { readonly delta: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_CONTENT";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_END";} | { readonly delta?: string; readonly messageId?: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_CHUNK";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_END";} | { readonly encryptedValue: string; readonly entityId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly subtype: "message" | "tool-call"; readonly timestamp?: number; readonly type: "REASONING_ENCRYPTED_VALUE";} | { readonly description?: string; readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly parentMessageId?: string; readonly parentSubagentRunId?: string; readonly parentToolCallId?: string; readonly rawEvent?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_STARTED";} | { readonly metadata?: { [key: string]: unknown; }; readonly outcome?: { readonly type: "success"; } | { readonly interruptIds?: readonly Array<string>; readonly type: "suspended"; }; readonly rawEvent?: unknown; readonly result?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_FINISHED";} | { readonly code?: string; readonly message: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_ERROR";}, E, R>): (__namedParameters: { readonly payload: { readonly context: readonly Array<{ readonly description: string; readonly value: string; }>; readonly forwardedProps?: unknown; readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "developer"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "system"; readonly subagentRunId?: string; } | { readonly content?: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "assistant"; readonly subagentRunId?: string; readonly toolCalls?: readonly Array<{ readonly encryptedValue?: string; readonly function: { readonly arguments: string; readonly name: string; }; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly type: "function"; }>; } | { readonly content: string | readonly Array<{ readonly id?: ... | ...; readonly metadata?: unknown; readonly text: string; readonly type: "text"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "image"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "audio"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "video"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "document"; }>; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "user"; readonly subagentRunId?: string; } | { readonly content: string | readonly Array<{ readonly id?: ... | ...; readonly metadata?: unknown; readonly text: string; readonly type: "text"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "image"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "audio"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "video"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "document"; }>; readonly encryptedValue?: string; readonly error?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "tool"; readonly subagentRunId?: string; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "activity"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "reasoning"; readonly subagentRunId?: string; }>; readonly parentRunId?: string; readonly protocolVersion?: string; readonly resume?: readonly Array<{ readonly interruptId: string; readonly metadata?: { [key: string]: unknown; }; readonly payload?: unknown; readonly status: "resolved" | "cancelled"; }>; readonly runId: string; readonly state?: unknown; readonly threadId: string; readonly tools: readonly Array<{ readonly description: string; readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly parameters?: unknown; }>; };}) => Effect<withHeaders<Stream<{ readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly rawEvent?: unknown; readonly role?: "developer" | "system" | "assistant" | "user"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_START";} | { readonly delta: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_CONTENT";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_END";} | { readonly delta?: string; readonly messageId?: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly rawEvent?: unknown; readonly role?: "developer" | "system" | "assistant" | "user"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_CHUNK";} | { readonly metadata?: { [key: string]: unknown; }; readonly parentMessageId?: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly toolCallName: string; readonly type: "TOOL_CALL_START";} | { readonly delta: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_ARGS";} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_END";} | { readonly delta?: string; readonly metadata?: { [key: string]: unknown; }; readonly parentMessageId?: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId?: string; readonly toolCallName?: string; readonly type: "TOOL_CALL_CHUNK";} | { readonly content: string | readonly Array<{ readonly id?: ... | ...; readonly metadata?: unknown; readonly text: string; readonly type: "text"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "image"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "audio"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "video"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "document"; }>; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly role?: "tool"; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_RESULT";} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly snapshot: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STATE_SNAPSHOT";} | { readonly delta: readonly Array<{ readonly op: "add"; readonly path: string; readonly value: unknown; } | { readonly op: "remove"; readonly path: string; } | { readonly op: "replace"; readonly path: string; readonly value: unknown; } | { readonly from: string; readonly op: "move"; readonly path: string; } | { readonly from: string; readonly op: "copy"; readonly path: string; } | { readonly op: "test"; readonly path: string; readonly value: unknown; }>; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STATE_DELTA";} | { readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly name?: string; readonly role: "developer"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly name?: string; readonly role: "system"; readonly subagentRunId?: string; } | { readonly content?: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly name?: string; readonly role: "assistant"; readonly subagentRunId?: string; readonly toolCalls?: readonly Array<...>; } | { readonly content: string | readonly Array<...>; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly name?: string; readonly role: "user"; readonly subagentRunId?: string; } | { readonly content: string | readonly Array<...>; readonly encryptedValue?: string; readonly error?: string; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly role: "tool"; readonly subagentRunId?: string; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly role: "activity"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly role: "reasoning"; readonly subagentRunId?: string; }>; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly timestamp?: number; readonly type: "MESSAGES_SNAPSHOT";} | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly replace?: boolean; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "ACTIVITY_SNAPSHOT";} | { readonly activityType: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly patch: readonly Array<{ readonly op: "add"; readonly path: string; readonly value: unknown; } | { readonly op: "remove"; readonly path: string; } | { readonly op: "replace"; readonly path: string; readonly value: unknown; } | { readonly from: string; readonly op: "move"; readonly path: string; } | { readonly from: string; readonly op: "copy"; readonly path: string; } | { readonly op: "test"; readonly path: string; readonly value: unknown; }>; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "ACTIVITY_DELTA";} | { readonly event: unknown; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly source?: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "RAW";} | { readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "CUSTOM"; readonly value: unknown;} | { readonly input?: { readonly context: readonly Array<{ readonly description: string; readonly value: string; }>; readonly forwardedProps?: unknown; readonly messages: readonly Array<{ readonly content: ...; readonly encryptedValue?: ...; readonly id: ...; readonly metadata?: ...; readonly name?: ...; readonly role: ...; readonly subagentRunId?: ...; } | { readonly content: ...; readonly encryptedValue?: ...; readonly id: ...; readonly metadata?: ...; readonly name?: ...; readonly role: ...; readonly subagentRunId?: ...; } | { readonly content?: ...; readonly encryptedValue?: ...; readonly id: ...; readonly metadata?: ...; readonly name?: ...; readonly role: ...; readonly subagentRunId?: ...; readonly toolCalls?: ...; } | { readonly content: ...; readonly encryptedValue?: ...; readonly id: ...; readonly metadata?: ...; readonly name?: ...; readonly role: ...; readonly subagentRunId?: ...; } | { readonly content: ...; readonly encryptedValue?: ...; readonly error?: ...; readonly id: ...; readonly metadata?: ...; readonly role: ...; readonly subagentRunId?: ...; readonly toolCallId: ...; } | { readonly activityType: ...; readonly content: ...; readonly id: ...; readonly metadata?: ...; readonly role: ...; readonly subagentRunId?: ...; } | { readonly content: ...; readonly encryptedValue?: ...; readonly id: ...; readonly metadata?: ...; readonly role: ...; readonly subagentRunId?: ...; }>; readonly parentRunId?: string; readonly protocolVersion?: string; readonly resume?: readonly Array<{ readonly interruptId: ...; readonly metadata?: ...; readonly payload?: ...; readonly status: ...; }>; readonly runId: string; readonly state?: unknown; readonly threadId: string; readonly tools: readonly Array<{ readonly description: string; readonly metadata?: ... | ...; readonly name: string; readonly parameters?: unknown; }>; }; readonly metadata?: { [key: string]: unknown; }; readonly parentRunId?: string; readonly protocolVersion?: string; readonly rawEvent?: unknown; readonly runId: string; readonly threadId: string; readonly timestamp?: number; readonly type: "RUN_STARTED";} | { readonly metadata?: { [key: string]: unknown; }; readonly outcome?: { readonly pendingToolCallIds?: readonly Array<string>; readonly type: "success"; } | { readonly interrupts: readonly [{ readonly expiresAt?: ... | ...; readonly id: string; readonly message?: ... | ...; readonly metadata?: ... | ...; readonly reason: string; readonly responseSchema?: ... | ...; readonly subagentRunId?: ... | ...; readonly toolCallId?: ... | ...; }, { readonly expiresAt?: ... | ...; readonly id: string; readonly message?: ... | ...; readonly metadata?: ... | ...; readonly reason: string; readonly responseSchema?: ... | ...; readonly subagentRunId?: ... | ...; readonly toolCallId?: ... | ...; }]; readonly type: "interrupt"; } | { readonly type: "cancelled"; }; readonly rawEvent?: unknown; readonly result?: unknown; readonly runId: string; readonly threadId: string; readonly timestamp?: number; readonly type: "RUN_FINISHED"; readonly usage?: readonly Array<{ readonly cachedInputTokens?: number; readonly cacheWriteInputTokens?: number; readonly inputTokens?: number; readonly model?: string; readonly outputTokens?: number; readonly provider?: string; readonly reasoningTokens?: number; readonly totalTokens?: number; }>;} | { readonly code?: string; readonly message: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly timestamp?: number; readonly type: "RUN_ERROR"; readonly usage?: readonly Array<{ readonly cachedInputTokens?: number; readonly cacheWriteInputTokens?: number; readonly inputTokens?: number; readonly model?: string; readonly outputTokens?: number; readonly provider?: string; readonly reasoningTokens?: number; readonly totalTokens?: number; }>;} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly stepName: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STEP_STARTED";} | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly stepName: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STEP_FINISHED";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_START";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly role: "reasoning"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_START";} | { readonly delta: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_CONTENT";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_END";} | { readonly delta?: string; readonly messageId?: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_CHUNK";} | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_END";} | { readonly encryptedValue: string; readonly entityId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly subtype: "message" | "tool-call"; readonly timestamp?: number; readonly type: "REASONING_ENCRYPTED_VALUE";} | { readonly description?: string; readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly parentMessageId?: string; readonly parentSubagentRunId?: string; readonly parentToolCallId?: string; readonly rawEvent?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_STARTED";} | { readonly metadata?: { [key: string]: unknown; }; readonly outcome?: { readonly type: "success"; } | { readonly interruptIds?: readonly Array<string>; readonly type: "suspended"; }; readonly rawEvent?: unknown; readonly result?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_FINISHED";} | { readonly code?: string; readonly message: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_ERROR";}, never, Exclude<R, R>>, { "cache-control": "no-cache";}>, never, R>Layers
Creates a layer that serves AG-UI runs at path on the current
HttpRouter.
Details
The route follows endpoint, and each request is answered by run
as described in handler. The returned layer needs the services
HttpApiBuilder.layer needs, which HTTP server layers usually provide.
Gotchas
Every field of the input comes from the client. Convert it with
AgUi.toPrompt, which drops client-supplied instructions by default.
See
Signature
declare const layerHttp: { <R>(options: { readonly agent: Agent<R>; readonly path: HttpRouter.PathInput; }): Layer<never, never, FileSystem | Path | R | HttpRouter | Generator | HttpPlatform>; <E, R>(options: { readonly path: HttpRouter.PathInput; readonly run: (input: AgUiSchema.RunAgentInput) => Stream.Stream<AgUiSchema.Event, E, R>; }): Layer<never, never, FileSystem | Path | R | HttpRouter | Generator | HttpPlatform>;}Models
An AG-UI agent served by layerHttp.
Details
run either rejects the input, which answers the request with 400, or
returns the run's event stream. R is the services the agent needs.
See
- agent for creating a
LanguageModelagent
Signature
interface Agent<R> { readonly run: (input: { readonly context: readonly Array<{ readonly description: string; readonly value: string; }>; readonly forwardedProps?: unknown; readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "developer"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "system"; readonly subagentRunId?: string; } | { readonly content?: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "assistant"; readonly subagentRunId?: string; readonly toolCalls?: readonly Array<{ readonly encryptedValue?: string; readonly function: { readonly arguments: string; readonly name: string; }; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly type: "function"; }>; } | { readonly content: string | readonly Array<{ readonly id?: string; readonly metadata?: unknown; readonly text: string; readonly type: "text"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "image"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "audio"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "video"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "document"; }>; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "user"; readonly subagentRunId?: string; } | { readonly content: string | readonly Array<{ readonly id?: string; readonly metadata?: unknown; readonly text: string; readonly type: "text"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "image"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "audio"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "video"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "document"; }>; readonly encryptedValue?: string; readonly error?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "tool"; readonly subagentRunId?: string; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "activity"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "reasoning"; readonly subagentRunId?: string; }>; readonly parentRunId?: string; readonly protocolVersion?: string; readonly resume?: readonly Array<{ readonly interruptId: string; readonly metadata?: { [key: string]: unknown; }; readonly payload?: unknown; readonly status: "resolved" | "cancelled"; }>; readonly runId: string; readonly state?: unknown; readonly threadId: string; readonly tools: readonly Array<{ readonly description: string; readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly parameters?: unknown; }>; }) => Effect<Stream<{ readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly rawEvent?: unknown; readonly role?: "developer" | "system" | "assistant" | "user"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_START"; } | { readonly delta: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_CONTENT"; } | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_END"; } | { readonly delta?: string; readonly messageId?: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly rawEvent?: unknown; readonly role?: "developer" | "system" | "assistant" | "user"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "TEXT_MESSAGE_CHUNK"; } | { readonly metadata?: { [key: string]: unknown; }; readonly parentMessageId?: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly toolCallName: string; readonly type: "TOOL_CALL_START"; } | { readonly delta: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_ARGS"; } | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_END"; } | { readonly delta?: string; readonly metadata?: { [key: string]: unknown; }; readonly parentMessageId?: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId?: string; readonly toolCallName?: string; readonly type: "TOOL_CALL_CHUNK"; } | { readonly content: string | readonly Array<{ readonly id?: string; readonly metadata?: unknown; readonly text: string; readonly type: "text"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "image"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "audio"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "video"; } | { readonly id?: string; readonly metadata?: unknown; readonly source: { readonly mimeType: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly type: ...; readonly value: ...; } | { readonly mimeType?: ...; readonly provider?: ...; readonly type: ...; readonly value: ...; }; readonly type: "document"; }>; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly role?: "tool"; readonly subagentRunId?: string; readonly timestamp?: number; readonly toolCallId: string; readonly type: "TOOL_CALL_RESULT"; } | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly snapshot: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STATE_SNAPSHOT"; } | { readonly delta: readonly Array<{ readonly op: "add"; readonly path: string; readonly value: unknown; } | { readonly op: "remove"; readonly path: string; } | { readonly op: "replace"; readonly path: string; readonly value: unknown; } | { readonly from: string; readonly op: "move"; readonly path: string; } | { readonly from: string; readonly op: "copy"; readonly path: string; } | { readonly op: "test"; readonly path: string; readonly value: unknown; }>; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STATE_DELTA"; } | { readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "developer"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "system"; readonly subagentRunId?: string; } | { readonly content?: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "assistant"; readonly subagentRunId?: string; readonly toolCalls?: readonly Array<{ readonly encryptedValue?: ...; readonly function: ...; readonly id: ...; readonly metadata?: ...; readonly type: ...; }>; } | { readonly content: string | readonly Array<... | ... | ... | ... | ...>; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "user"; readonly subagentRunId?: string; } | { readonly content: string | readonly Array<... | ... | ... | ... | ...>; readonly encryptedValue?: string; readonly error?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "tool"; readonly subagentRunId?: string; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "activity"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "reasoning"; readonly subagentRunId?: string; }>; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly timestamp?: number; readonly type: "MESSAGES_SNAPSHOT"; } | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly replace?: boolean; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "ACTIVITY_SNAPSHOT"; } | { readonly activityType: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly patch: readonly Array<{ readonly op: "add"; readonly path: string; readonly value: unknown; } | { readonly op: "remove"; readonly path: string; } | { readonly op: "replace"; readonly path: string; readonly value: unknown; } | { readonly from: string; readonly op: "move"; readonly path: string; } | { readonly from: string; readonly op: "copy"; readonly path: string; } | { readonly op: "test"; readonly path: string; readonly value: unknown; }>; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "ACTIVITY_DELTA"; } | { readonly event: unknown; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly source?: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "RAW"; } | { readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "CUSTOM"; readonly value: unknown; } | { readonly input?: { readonly context: readonly Array<{ readonly description: string; readonly value: string; }>; readonly forwardedProps?: unknown; readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly name?: ... | ...; readonly role: "developer"; readonly subagentRunId?: ... | ...; } | { readonly content: string; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly name?: ... | ...; readonly role: "system"; readonly subagentRunId?: ... | ...; } | { readonly content?: ... | ...; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly name?: ... | ...; readonly role: "assistant"; readonly subagentRunId?: ... | ...; readonly toolCalls?: ... | ...; } | { readonly content: ... | ...; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly name?: ... | ...; readonly role: "user"; readonly subagentRunId?: ... | ...; } | { readonly content: ... | ...; readonly encryptedValue?: ... | ...; readonly error?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly role: "tool"; readonly subagentRunId?: ... | ...; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: ...]: ...; }; readonly id: string; readonly metadata?: ... | ...; readonly role: "activity"; readonly subagentRunId?: ... | ...; } | { readonly content: string; readonly encryptedValue?: ... | ...; readonly id: string; readonly metadata?: ... | ...; readonly role: "reasoning"; readonly subagentRunId?: ... | ...; }>; readonly parentRunId?: string; readonly protocolVersion?: string; readonly resume?: readonly Array<{ readonly interruptId: string; readonly metadata?: ... | ...; readonly payload?: unknown; readonly status: ... | ...; }>; readonly runId: string; readonly state?: unknown; readonly threadId: string; readonly tools: readonly Array<{ readonly description: string; readonly metadata?: { [key: ...]: ...; }; readonly name: string; readonly parameters?: unknown; }>; }; readonly metadata?: { [key: string]: unknown; }; readonly parentRunId?: string; readonly protocolVersion?: string; readonly rawEvent?: unknown; readonly runId: string; readonly threadId: string; readonly timestamp?: number; readonly type: "RUN_STARTED"; } | { readonly metadata?: { [key: string]: unknown; }; readonly outcome?: { readonly pendingToolCallIds?: readonly Array<string>; readonly type: "success"; } | { readonly interrupts: readonly [{ readonly expiresAt?: string; readonly id: string; readonly message?: string; readonly metadata?: { [key: ...]: ...; }; readonly reason: string; readonly responseSchema?: { [key: ...]: ...; }; readonly subagentRunId?: string; readonly toolCallId?: string; }, { readonly expiresAt?: string; readonly id: string; readonly message?: string; readonly metadata?: { [key: ...]: ...; }; readonly reason: string; readonly responseSchema?: { [key: ...]: ...; }; readonly subagentRunId?: string; readonly toolCallId?: string; }]; readonly type: "interrupt"; } | { readonly type: "cancelled"; }; readonly rawEvent?: unknown; readonly result?: unknown; readonly runId: string; readonly threadId: string; readonly timestamp?: number; readonly type: "RUN_FINISHED"; readonly usage?: readonly Array<{ readonly cachedInputTokens?: number; readonly cacheWriteInputTokens?: number; readonly inputTokens?: number; readonly model?: string; readonly outputTokens?: number; readonly provider?: string; readonly reasoningTokens?: number; readonly totalTokens?: number; }>; } | { readonly code?: string; readonly message: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly timestamp?: number; readonly type: "RUN_ERROR"; readonly usage?: readonly Array<{ readonly cachedInputTokens?: number; readonly cacheWriteInputTokens?: number; readonly inputTokens?: number; readonly model?: string; readonly outputTokens?: number; readonly provider?: string; readonly reasoningTokens?: number; readonly totalTokens?: number; }>; } | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly stepName: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STEP_STARTED"; } | { readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly stepName: string; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "STEP_FINISHED"; } | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_START"; } | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly role: "reasoning"; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_START"; } | { readonly delta: string; readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_CONTENT"; } | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_END"; } | { readonly delta?: string; readonly messageId?: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_MESSAGE_CHUNK"; } | { readonly messageId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly timestamp?: number; readonly type: "REASONING_END"; } | { readonly encryptedValue: string; readonly entityId: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId?: string; readonly subtype: "message" | "tool-call"; readonly timestamp?: number; readonly type: "REASONING_ENCRYPTED_VALUE"; } | { readonly description?: string; readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly parentMessageId?: string; readonly parentSubagentRunId?: string; readonly parentToolCallId?: string; readonly rawEvent?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_STARTED"; } | { readonly metadata?: { [key: string]: unknown; }; readonly outcome?: { readonly type: "success"; } | { readonly interruptIds?: readonly Array<string>; readonly type: "suspended"; }; readonly rawEvent?: unknown; readonly result?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_FINISHED"; } | { readonly code?: string; readonly message: string; readonly metadata?: { [key: string]: unknown; }; readonly rawEvent?: unknown; readonly subagentRunId: string; readonly timestamp?: number; readonly type: "SUBAGENT_ERROR"; }, unknown, R>, BadRequest>;}Services
Service holding the input of the AG-UI run being served.
When to use
Use to read the run's threadId, runId, state, or forwardedProps in
a server tool's handler. Declare it in the tool's dependencies, and the
agent provides it for each run.
Signature
declare class RunInput extends Shape<"effect/ai/AgUiServer/RunInput", { readonly context: readonly Array<{ readonly description: string; readonly value: string; }>; readonly forwardedProps?: unknown; readonly messages: readonly Array<{ readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "developer"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "system"; readonly subagentRunId?: string; } | { readonly content?: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "assistant"; readonly subagentRunId?: string; readonly toolCalls?: readonly Array<{ readonly encryptedValue?: string; readonly function: { readonly arguments: string; readonly name: string; }; readonly id: string; readonly metadata?: { [key: ...]: ...; }; readonly type: "function"; }>; } | { readonly content: string | readonly Array<{ readonly id?: ... | ...; readonly metadata?: unknown; readonly text: string; readonly type: "text"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "image"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "audio"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "video"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "document"; }>; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly name?: string; readonly role: "user"; readonly subagentRunId?: string; } | { readonly content: string | readonly Array<{ readonly id?: ... | ...; readonly metadata?: unknown; readonly text: string; readonly type: "text"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "image"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "audio"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "video"; } | { readonly id?: ... | ...; readonly metadata?: unknown; readonly source: ... | ... | ...; readonly type: "document"; }>; readonly encryptedValue?: string; readonly error?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "tool"; readonly subagentRunId?: string; readonly toolCallId: string; } | { readonly activityType: string; readonly content: { [key: string]: unknown; }; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "activity"; readonly subagentRunId?: string; } | { readonly content: string; readonly encryptedValue?: string; readonly id: string; readonly metadata?: { [key: string]: unknown; }; readonly role: "reasoning"; readonly subagentRunId?: string; }>; readonly parentRunId?: string; readonly protocolVersion?: string; readonly resume?: readonly Array<{ readonly interruptId: string; readonly metadata?: { [key: string]: unknown; }; readonly payload?: unknown; readonly status: "resolved" | "cancelled"; }>; readonly runId: string; readonly state?: unknown; readonly threadId: string; readonly tools: readonly Array<{ readonly description: string; readonly metadata?: { [key: string]: unknown; }; readonly name: string; readonly parameters?: unknown; }>;}, this> { constructor(_: never);}