AgUiSchema
Defines schemas for the Agent User Interaction (AG-UI) protocol.
AG-UI connects an agent backend to a user-facing application: the
application posts a RunAgentInput and the agent answers with a stream of
events describing the run. These schemas follow the AG-UI 1.0 specification
and describe the request body, the conversation messages it carries, and
every event type. Converting to and from effect/ai values lives in AgUi,
and the HTTP binding lives in AgUiServer.
See
Constants
Since v4.1.0 Source
AG-UI protocol version implemented by these schemas.
Signature
declare const protocolVersion: "1.0"Models
ActivityDeltaEvent
type Since v4.1.0 Source
Applies a JSON Patch to an activity message.
Signature
type ActivityDeltaEvent = typeof ActivityDeltaEvent.TypeActivityMessage
type Since v4.1.0 Source
Structured progress kept in the conversation as a message.
Signature
type ActivityMessage = typeof ActivityMessage.Type Since v4.1.0 Source
Sets the content of an activity message.
Signature
type ActivitySnapshotEvent = typeof ActivitySnapshotEvent.TypeAssistantMessage
type Since v4.1.0 Source
A message from the agent.
Signature
type AssistantMessage = typeof AssistantMessage.TypeAn audio content part.
Signature
type AudioPart = typeof AudioPart.TypeContentPart
type Since v4.1.0 Source
Any content part of a user or tool message.
Signature
type ContentPart = typeof ContentPart.TypeA named piece of ambient information given to the agent for a run.
Signature
type Context = typeof Context.TypeCustomEvent
type Since v4.1.0 Source
An application-defined event.
Signature
type CustomEvent = typeof CustomEvent.TypeDataSource
type Since v4.1.0 Source
Media bytes carried inline as base64 data.
Signature
type DataSource = typeof DataSource.TypeDeveloperMessage
type Since v4.1.0 Source
Instructions from the application developer.
Signature
type DeveloperMessage = typeof DeveloperMessage.TypeDocumentPart
type Since v4.1.0 Source
A document content part.
Signature
type DocumentPart = typeof DocumentPart.TypeAny AG-UI event, discriminated by type.
Signature
type Event = typeof Event.TypeFileSource
type Since v4.1.0 Source
Media bytes already stored at a provider and named by a handle that provider issued.
Signature
type FileSource = typeof FileSource.TypeAn image content part.
Signature
type ImagePart = typeof ImagePart.TypeSomething a run needs from outside before it can continue, such as an approval.
Signature
type Interrupt = typeof Interrupt.TypeJsonPatchOperation
type Since v4.1.0 Source
One RFC 6902 JSON Patch operation.
Signature
type JsonPatchOperation = typeof JsonPatchOperation.TypeAny message in an AG-UI conversation, discriminated by role.
Signature
type Message = typeof Message.Type Since v4.1.0 Source
Replaces the conversation the agent owns.
Signature
type MessagesSnapshotEvent = typeof MessagesSnapshotEvent.TypeOpen-ended metadata attached to events, messages, tools, and other protocol values.
Signature
type Metadata = typeof Metadata.TypePartSource
type Since v4.1.0 Source
Source of a media content part.
Signature
type PartSource = typeof PartSource.TypePasses through an event from an external system.
Signature
type RawEvent = typeof RawEvent.Type Since v4.1.0 Source
Attaches provider-encrypted reasoning to a message or tool call.
Signature
type ReasoningEncryptedValueEvent = typeof ReasoningEncryptedValueEvent.TypeReasoningEndEvent
type Since v4.1.0 Source
Closes a span of reasoning.
Signature
type ReasoningEndEvent = typeof ReasoningEndEvent.TypeReasoningMessage
type Since v4.1.0 Source
A span of the agent's reasoning, kept in the conversation as a message.
Signature
type ReasoningMessage = typeof ReasoningMessage.Type Since v4.1.0 Source
Shorthand that stands in for a reasoning message's start, content, and end sequence.
Signature
type ReasoningMessageChunkEvent = typeof ReasoningMessageChunkEvent.Type Since v4.1.0 Source
Appends a fragment to a streamed reasoning message.
Signature
type ReasoningMessageContentEvent = typeof ReasoningMessageContentEvent.Type Since v4.1.0 Source
Closes a streamed reasoning message.
Signature
type ReasoningMessageEndEvent = typeof ReasoningMessageEndEvent.Type Since v4.1.0 Source
Opens a streamed reasoning message.
Signature
type ReasoningMessageStartEvent = typeof ReasoningMessageStartEvent.TypeReasoningStartEvent
type Since v4.1.0 Source
Opens a span of reasoning.
Signature
type ReasoningStartEvent = typeof ReasoningStartEvent.TypeResumeEntry
type Since v4.1.0 Source
An answer to an interrupt, sent on the run that continues from it.
Signature
type ResumeEntry = typeof ResumeEntry.TypeRunAgentInput
type Since v4.1.0 Source
The request body that starts an agent run.
Signature
type RunAgentInput = typeof RunAgentInput.TypeRunErrorEvent
type Since v4.1.0 Source
Ends a run that failed.
Signature
type RunErrorEvent = typeof RunErrorEvent.TypeRunFinishedEvent
type Since v4.1.0 Source
Closes a run that did not fail.
Signature
type RunFinishedEvent = typeof RunFinishedEvent.TypeRunFinishedOutcome
type Since v4.1.0 Source
Why a run ended.
Signature
type RunFinishedOutcome = typeof RunFinishedOutcome.TypeRunStartedEvent
type Since v4.1.0 Source
Opens a run.
Signature
type RunStartedEvent = typeof RunStartedEvent.TypeStateDeltaEvent
type Since v4.1.0 Source
Applies a JSON Patch to the agent state.
Signature
type StateDeltaEvent = typeof StateDeltaEvent.TypeStateSnapshotEvent
type Since v4.1.0 Source
Replaces the agent state.
Signature
type StateSnapshotEvent = typeof StateSnapshotEvent.TypeStepFinishedEvent
type Since v4.1.0 Source
Closes a named step.
Signature
type StepFinishedEvent = typeof StepFinishedEvent.TypeStepStartedEvent
type Since v4.1.0 Source
Opens a named step within a run.
Signature
type StepStartedEvent = typeof StepStartedEvent.TypeSubagentErrorEvent
type Since v4.1.0 Source
Reports a failed subagent invocation without ending the run.
Signature
type SubagentErrorEvent = typeof SubagentErrorEvent.Type Since v4.1.0 Source
Closes a subagent invocation that did not fail.
Signature
type SubagentFinishedEvent = typeof SubagentFinishedEvent.TypeSubagentStartedEvent
type Since v4.1.0 Source
Opens a subagent invocation within a run.
Signature
type SubagentStartedEvent = typeof SubagentStartedEvent.TypeSystemMessage
type Since v4.1.0 Source
Instructions from the system.
Signature
type SystemMessage = typeof SystemMessage.Type Since v4.1.0 Source
Shorthand that stands in for a text message's start, content, and end sequence.
Signature
type TextMessageChunkEvent = typeof TextMessageChunkEvent.Type Since v4.1.0 Source
Appends a fragment to a streamed text message.
Signature
type TextMessageContentEvent = typeof TextMessageContentEvent.TypeTextMessageEndEvent
type Since v4.1.0 Source
Closes a streamed text message.
Signature
type TextMessageEndEvent = typeof TextMessageEndEvent.TypeTextMessageRole
type Since v4.1.0 Source
The role of a streamed text message.
Signature
type TextMessageRole = typeof TextMessageRole.Type Since v4.1.0 Source
Opens a streamed text message.
Signature
type TextMessageStartEvent = typeof TextMessageStartEvent.TypeA text content part.
Signature
type TextPart = typeof TextPart.TypeTokenUsage
type Since v4.1.0 Source
Token counts reported for one provider and model.
Signature
type TokenUsage = typeof TokenUsage.TypeA tool the application offers to the agent.
Signature
type Tool = typeof Tool.TypeA tool call made by an assistant message.
Signature
type ToolCall = typeof ToolCall.TypeToolCallArgsEvent
type Since v4.1.0 Source
Appends a fragment of a tool call's JSON arguments.
Signature
type ToolCallArgsEvent = typeof ToolCallArgsEvent.TypeToolCallChunkEvent
type Since v4.1.0 Source
Shorthand that stands in for a tool call's start, arguments, and end sequence.
Signature
type ToolCallChunkEvent = typeof ToolCallChunkEvent.TypeToolCallEndEvent
type Since v4.1.0 Source
Closes a tool call once its arguments are complete.
Signature
type ToolCallEndEvent = typeof ToolCallEndEvent.TypeToolCallResultEvent
type Since v4.1.0 Source
Delivers the result of a tool call as a new tool message.
Signature
type ToolCallResultEvent = typeof ToolCallResultEvent.TypeToolCallStartEvent
type Since v4.1.0 Source
Opens a tool call.
Signature
type ToolCallStartEvent = typeof ToolCallStartEvent.TypeToolMessage
type Since v4.1.0 Source
The result of a tool call, as a message in the conversation.
Signature
type ToolMessage = typeof ToolMessage.TypeMedia bytes referenced by URL.
Signature
type UrlSource = typeof UrlSource.TypeUserMessage
type Since v4.1.0 Source
A message from the person using the application.
Signature
type UserMessage = typeof UserMessage.TypeA video content part.
Signature
type VideoPart = typeof VideoPart.TypeSchemas
Since v4.1.0 Source
Schema for the event that applies a JSON Patch to an activity message.
Signature
declare const ActivityDeltaEvent: Struct<{ readonly activityType: String; readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly patch: $Array<Union<readonly [Struct<{ readonly op: Literal<"add">; readonly path: String; readonly value: Unknown; }>, Struct<{ readonly op: Literal<"remove">; readonly path: String; }>, Struct<{ readonly op: Literal<"replace">; readonly path: String; readonly value: Unknown; }>, Struct<{ readonly from: String; readonly op: Literal<"move">; readonly path: String; }>, Struct<{ readonly from: String; readonly op: Literal<"copy">; readonly path: String; }>, Struct<{ readonly op: Literal<"test">; readonly path: String; readonly value: Unknown; }>]>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"ACTIVITY_DELTA">;}> Since v4.1.0 Source
Schema for structured progress kept in the conversation as a message.
Signature
declare const ActivityMessage: Struct<{ readonly activityType: String; readonly content: $Record<String, Unknown>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly role: Literal<"activity">; readonly subagentRunId: optionalKey<String>;}> Since v4.1.0 Source
Schema for the event that sets the content of an activity message.
Signature
declare const ActivitySnapshotEvent: 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">;}> Since v4.1.0 Source
Schema for a message from the agent.
Signature
declare const AssistantMessage: Struct<{ readonly content: optionalKey<String>; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: optionalKey<String>; readonly role: Literal<"assistant">; readonly subagentRunId: optionalKey<String>; readonly toolCalls: optionalKey<decodeTo<$Array<toType<Struct<{ readonly encryptedValue: optionalKey<String>; readonly function: Struct<{ readonly arguments: String; readonly name: String; }>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly type: Literal<"function">; }>>>, $Array<Union<readonly [Struct<{ readonly encryptedValue: optionalKey<String>; readonly function: Struct<{ readonly arguments: ...; readonly name: ...; }>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly type: Literal<"function">; }>, Any]>>, never, never>>;}>Schema for an audio content part.
Signature
declare const AudioPart: Struct<{ readonly id: optionalKey<String>; readonly metadata: optionalKey<Unknown>; readonly source: Union<readonly [Struct<{ readonly mimeType: String; readonly type: Literal<"data">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly type: Literal<"url">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly provider: optionalKey<String>; readonly type: Literal<"file">; readonly value: String; }>]>; readonly type: Literal<"audio">;}> Since v4.1.0 Source
Schema for any content part of a user or tool message.
Signature
declare const ContentPart: Union<readonly [Struct<{ readonly id: optionalKey<String>; readonly metadata: optionalKey<Unknown>; readonly text: String; readonly type: Literal<"text">;}>, Struct<{ readonly id: optionalKey<String>; readonly metadata: optionalKey<Unknown>; readonly source: Union<readonly [Struct<{ readonly mimeType: String; readonly type: Literal<"data">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly type: Literal<"url">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly provider: optionalKey<String>; readonly type: Literal<"file">; readonly value: String; }>]>; readonly type: Literal<"image">;}>, Struct<{ readonly id: optionalKey<String>; readonly metadata: optionalKey<Unknown>; readonly source: Union<readonly [Struct<{ readonly mimeType: String; readonly type: Literal<"data">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly type: Literal<"url">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly provider: optionalKey<String>; readonly type: Literal<"file">; readonly value: String; }>]>; readonly type: Literal<"audio">;}>, Struct<{ readonly id: optionalKey<String>; readonly metadata: optionalKey<Unknown>; readonly source: Union<readonly [Struct<{ readonly mimeType: String; readonly type: Literal<"data">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly type: Literal<"url">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly provider: optionalKey<String>; readonly type: Literal<"file">; readonly value: String; }>]>; readonly type: Literal<"video">;}>, Struct<{ readonly id: optionalKey<String>; readonly metadata: optionalKey<Unknown>; readonly source: Union<readonly [Struct<{ readonly mimeType: String; readonly type: Literal<"data">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly type: Literal<"url">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly provider: optionalKey<String>; readonly type: Literal<"file">; readonly value: String; }>]>; readonly type: Literal<"document">;}>]>Schema for a named piece of ambient information given to the agent for a run.
Signature
declare const Context: Struct<{ readonly description: String; readonly value: String;}> Since v4.1.0 Source
Schema for an application-defined event.
Signature
declare const CustomEvent: 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;}> Since v4.1.0 Source
Schema for media bytes carried inline as base64 data.
Signature
declare const DataSource: Struct<{ readonly mimeType: String; readonly type: Literal<"data">; readonly value: String;}> Since v4.1.0 Source
Schema for instructions from the application developer.
Signature
declare const DeveloperMessage: Struct<{ readonly content: String; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: optionalKey<String>; readonly role: Literal<"developer">; readonly subagentRunId: optionalKey<String>;}> Since v4.1.0 Source
Schema for a document content part.
Signature
declare const DocumentPart: Struct<{ readonly id: optionalKey<String>; readonly metadata: optionalKey<Unknown>; readonly source: Union<readonly [Struct<{ readonly mimeType: String; readonly type: Literal<"data">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly type: Literal<"url">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly provider: optionalKey<String>; readonly type: Literal<"file">; readonly value: String; }>]>; readonly type: Literal<"document">;}>Schema for any AG-UI event, discriminated by type.
Signature
declare const Event: 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 ["developer", "system", "assistant", "user"]>>; 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 ["developer", "system", "assistant", "user"]>>; 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<$Array<toType<Union<readonly [..., ..., ..., ..., ...]>>>, $Array<Union<readonly [Union<...>, Any]>>, never, never>]>; 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 [Struct<{ readonly op: Literal<"add">; readonly path: String; readonly value: Unknown; }>, Struct<{ readonly op: Literal<"remove">; readonly path: String; }>, Struct<{ readonly op: Literal<"replace">; readonly path: String; readonly value: Unknown; }>, Struct<{ readonly from: String; readonly op: Literal<"move">; readonly path: String; }>, Struct<{ readonly from: String; readonly op: Literal<"copy">; readonly path: String; }>, Struct<{ readonly op: Literal<"test">; readonly path: String; readonly value: Unknown; }>]>>; 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<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 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 [Struct<{ readonly op: Literal<"add">; readonly path: String; readonly value: Unknown; }>, Struct<{ readonly op: Literal<"remove">; readonly path: String; }>, Struct<{ readonly op: Literal<"replace">; readonly path: String; readonly value: Unknown; }>, Struct<{ readonly from: String; readonly op: Literal<"move">; readonly path: String; }>, Struct<{ readonly from: String; readonly op: Literal<"copy">; readonly path: String; }>, Struct<{ readonly op: Literal<"test">; readonly path: String; readonly value: Unknown; }>]>>; 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: withDecodingDefaultTypeKey<$Array<Struct<{ readonly description: ...; readonly value: ...; }>>, never>; readonly forwardedProps: optionalKey<Unknown>; readonly messages: decodeTo<$Array<toType<Union<...>>>, $Array<Union<readonly [..., ...]>>, never, never>; readonly parentRunId: optionalKey<String>; readonly protocolVersion: optionalKey<String>; readonly resume: optionalKey<decodeTo<$Array<toType<...>>, $Array<Union<...>>, never, never>>; readonly runId: String; readonly state: optionalKey<Unknown>; readonly threadId: String; readonly tools: withDecodingDefaultTypeKey<$Array<Struct<{ readonly description: ...; readonly metadata: ...; readonly name: ...; readonly parameters: ...; }>>, never>; }>>; 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 [Struct<{ readonly pendingToolCallIds: optionalKey<$Array<...>>; readonly type: Literal<"success">; }>, Struct<{ readonly interrupts: NonEmptyArray<Struct<...>>; readonly type: Literal<"interrupt">; }>, Struct<{ readonly type: Literal<"cancelled">; }>]>>; 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<{ readonly cachedInputTokens: optionalKey<Int>; readonly cacheWriteInputTokens: optionalKey<Int>; readonly inputTokens: optionalKey<Int>; readonly model: optionalKey<String>; readonly outputTokens: optionalKey<Int>; readonly provider: optionalKey<String>; readonly reasoningTokens: optionalKey<Int>; readonly totalTokens: optionalKey<Int>; }>>>;}>, 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<{ readonly cachedInputTokens: optionalKey<Int>; readonly cacheWriteInputTokens: optionalKey<Int>; readonly inputTokens: optionalKey<Int>; readonly model: optionalKey<String>; readonly outputTokens: optionalKey<Int>; readonly provider: optionalKey<String>; readonly reasoningTokens: optionalKey<Int>; readonly totalTokens: optionalKey<Int>; }>>>;}>, 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 [Struct<{ readonly type: Literal<"success">; }>, Struct<{ readonly interruptIds: optionalKey<$Array<...>>; readonly type: Literal<"suspended">; }>]>>; 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">;}>]> Since v4.1.0 Source
Schema for media bytes already stored at a provider and named by a handle that provider issued.
Signature
declare const FileSource: Struct<{ readonly mimeType: optionalKey<String>; readonly provider: optionalKey<String>; readonly type: Literal<"file">; readonly value: String;}>Schema for an image content part.
Signature
declare const ImagePart: Struct<{ readonly id: optionalKey<String>; readonly metadata: optionalKey<Unknown>; readonly source: Union<readonly [Struct<{ readonly mimeType: String; readonly type: Literal<"data">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly type: Literal<"url">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly provider: optionalKey<String>; readonly type: Literal<"file">; readonly value: String; }>]>; readonly type: Literal<"image">;}>Schema for something a run needs from outside before it can continue, such as an approval.
Signature
declare const Interrupt: Struct<{ readonly expiresAt: optionalKey<String>; readonly id: String; readonly message: optionalKey<String>; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly reason: String; readonly responseSchema: optionalKey<$Record<String, Unknown>>; readonly subagentRunId: optionalKey<String>; readonly toolCallId: optionalKey<String>;}> Since v4.1.0 Source
Schema for one RFC 6902 JSON Patch operation.
Signature
declare const JsonPatchOperation: Union<readonly [Struct<{ readonly op: Literal<"add">; readonly path: String; readonly value: Unknown;}>, Struct<{ readonly op: Literal<"remove">; readonly path: String;}>, Struct<{ readonly op: Literal<"replace">; readonly path: String; readonly value: Unknown;}>, Struct<{ readonly from: String; readonly op: Literal<"move">; readonly path: String;}>, Struct<{ readonly from: String; readonly op: Literal<"copy">; readonly path: String;}>, Struct<{ readonly op: Literal<"test">; readonly path: String; readonly value: Unknown;}>]>Schema for any message in an AG-UI conversation, discriminated by role.
Signature
declare const Message: Union<readonly [Struct<{ readonly content: String; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: optionalKey<String>; readonly role: Literal<"developer">; readonly subagentRunId: optionalKey<String>;}>, Struct<{ readonly content: String; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: optionalKey<String>; readonly role: Literal<"system">; readonly subagentRunId: optionalKey<String>;}>, Struct<{ readonly content: optionalKey<String>; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: optionalKey<String>; readonly role: Literal<"assistant">; readonly subagentRunId: optionalKey<String>; readonly toolCalls: optionalKey<decodeTo<$Array<toType<Struct<{ readonly encryptedValue: optionalKey<...>; readonly function: Struct<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly type: Literal<...>; }>>>, $Array<Union<readonly [Struct<{ readonly encryptedValue: ...; readonly function: ...; readonly id: ...; readonly metadata: ...; readonly type: ...; }>, Any]>>, never, never>>;}>, Struct<{ readonly content: Union<readonly [String, decodeTo<$Array<toType<Union<readonly [..., ..., ..., ..., ...]>>>, $Array<Union<readonly [Union<...>, Any]>>, never, never>]>; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: optionalKey<String>; readonly role: Literal<"user">; readonly subagentRunId: optionalKey<String>;}>, Struct<{ readonly content: Union<readonly [String, decodeTo<$Array<toType<Union<readonly [..., ..., ..., ..., ...]>>>, $Array<Union<readonly [Union<...>, Any]>>, never, never>]>; readonly encryptedValue: optionalKey<String>; readonly error: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly role: Literal<"tool">; readonly subagentRunId: optionalKey<String>; readonly toolCallId: String;}>, Struct<{ readonly activityType: String; readonly content: $Record<String, Unknown>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly role: Literal<"activity">; readonly subagentRunId: optionalKey<String>;}>, Struct<{ readonly content: String; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly role: Literal<"reasoning">; readonly subagentRunId: optionalKey<String>;}>]> Since v4.1.0 Source
Schema for the event that replaces the conversation the agent owns.
Signature
declare const MessagesSnapshotEvent: Struct<{ readonly messages: decodeTo<$Array<toType<Union<readonly [Struct<{ readonly content: String; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly name: optionalKey<String>; readonly role: Literal<"developer">; readonly subagentRunId: optionalKey<String>; }>, Struct<{ readonly content: String; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly name: optionalKey<String>; readonly role: Literal<"system">; readonly subagentRunId: optionalKey<String>; }>, Struct<{ readonly content: optionalKey<String>; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly name: optionalKey<String>; readonly role: Literal<"assistant">; readonly subagentRunId: optionalKey<String>; readonly toolCalls: optionalKey<decodeTo<..., ..., ..., ...>>; }>, Struct<{ readonly content: Union<readonly [..., ...]>; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly name: optionalKey<String>; readonly role: Literal<"user">; readonly subagentRunId: optionalKey<String>; }>, Struct<{ readonly content: Union<readonly [..., ...]>; readonly encryptedValue: optionalKey<String>; readonly error: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly role: Literal<"tool">; readonly subagentRunId: optionalKey<String>; readonly toolCallId: String; }>, Struct<{ readonly activityType: String; readonly content: $Record<String, Unknown>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly role: Literal<"activity">; readonly subagentRunId: optionalKey<String>; }>, Struct<{ readonly content: String; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly role: Literal<"reasoning">; readonly subagentRunId: optionalKey<String>; }>]>>>, $Array<Union<readonly [Union<readonly [Struct<{ readonly content: String; readonly encryptedValue: optionalKey<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly name: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; }>, Struct<{ readonly content: String; readonly encryptedValue: optionalKey<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly name: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; }>, Struct<{ readonly content: optionalKey<...>; readonly encryptedValue: optionalKey<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly name: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; readonly toolCalls: optionalKey<...>; }>, Struct<{ readonly content: Union<...>; readonly encryptedValue: optionalKey<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly name: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; }>, Struct<{ readonly content: Union<...>; readonly encryptedValue: optionalKey<...>; readonly error: optionalKey<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; readonly toolCallId: String; }>, Struct<{ readonly activityType: String; readonly content: $Record<..., ...>; readonly id: String; readonly metadata: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; }>, Struct<{ readonly content: String; readonly encryptedValue: optionalKey<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; }>]>, Any]>>, never, never>; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"MESSAGES_SNAPSHOT">;}>Schema for open-ended metadata attached to events, messages, tools, and other protocol values.
Details
The ag-ui key is reserved for the protocol's own use.
Signature
declare const Metadata: $Record<String, Unknown> Since v4.1.0 Source
Schema for the source of a media content part.
Signature
declare const PartSource: Union<readonly [Struct<{ readonly mimeType: String; readonly type: Literal<"data">; readonly value: String;}>, Struct<{ readonly mimeType: optionalKey<String>; readonly type: Literal<"url">; readonly value: String;}>, Struct<{ readonly mimeType: optionalKey<String>; readonly provider: optionalKey<String>; readonly type: Literal<"file">; readonly value: String;}>]>Schema for the event that passes through an event from an external system.
Signature
declare const RawEvent: 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">;}> Since v4.1.0 Source
Schema for the event that attaches provider-encrypted reasoning to a message or tool call.
Signature
declare const ReasoningEncryptedValueEvent: 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">;}> Since v4.1.0 Source
Schema for the event that closes a span of reasoning.
Signature
declare const ReasoningEndEvent: 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">;}> Since v4.1.0 Source
Schema for a span of the agent's reasoning, kept in the conversation as a message.
Signature
declare const ReasoningMessage: Struct<{ readonly content: String; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly role: Literal<"reasoning">; readonly subagentRunId: optionalKey<String>;}> Since v4.1.0 Source
Schema for the shorthand event that stands in for a reasoning message's start, content, and end sequence.
Signature
declare const ReasoningMessageChunkEvent: 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">;}> Since v4.1.0 Source
Schema for the event that appends a fragment to a streamed reasoning message.
Signature
declare const ReasoningMessageContentEvent: 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">;}> Since v4.1.0 Source
Schema for the event that closes a streamed reasoning message.
Signature
declare const ReasoningMessageEndEvent: 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">;}> Since v4.1.0 Source
Schema for the event that opens a streamed reasoning message.
Signature
declare const ReasoningMessageStartEvent: 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">;}> Since v4.1.0 Source
Schema for the event that opens a span of reasoning.
Signature
declare const ReasoningStartEvent: 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">;}> Since v4.1.0 Source
Schema for an answer to an interrupt, sent on the run that continues from it.
Signature
declare const ResumeEntry: Struct<{ readonly interruptId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly payload: optionalKey<Unknown>; readonly status: Literals<readonly ["resolved", "cancelled"]>;}> Since v4.1.0 Source
Schema for the request body that starts an agent run.
Details
messages is the complete conversation so far, which lets an agent serve
runs without keeping its own history. Missing tools and context decode
to empty arrays. As AG-UI requires, messages, content parts, tool calls,
and resume entries of kinds or statuses this version does not recognise are
removed during decoding rather than rejected.
Gotchas
Every field comes from the client. Treat messages, tools, and context as untrusted input.
Signature
declare const RunAgentInput: 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: String; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly name: optionalKey<String>; readonly role: Literal<"developer">; readonly subagentRunId: optionalKey<String>; }>, Struct<{ readonly content: String; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly name: optionalKey<String>; readonly role: Literal<"system">; readonly subagentRunId: optionalKey<String>; }>, Struct<{ readonly content: optionalKey<String>; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly name: optionalKey<String>; readonly role: Literal<"assistant">; readonly subagentRunId: optionalKey<String>; readonly toolCalls: optionalKey<decodeTo<..., ..., ..., ...>>; }>, Struct<{ readonly content: Union<readonly [..., ...]>; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly name: optionalKey<String>; readonly role: Literal<"user">; readonly subagentRunId: optionalKey<String>; }>, Struct<{ readonly content: Union<readonly [..., ...]>; readonly encryptedValue: optionalKey<String>; readonly error: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly role: Literal<"tool">; readonly subagentRunId: optionalKey<String>; readonly toolCallId: String; }>, Struct<{ readonly activityType: String; readonly content: $Record<String, Unknown>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly role: Literal<"activity">; readonly subagentRunId: optionalKey<String>; }>, Struct<{ readonly content: String; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly role: Literal<"reasoning">; readonly subagentRunId: optionalKey<String>; }>]>>>, $Array<Union<readonly [Union<readonly [Struct<{ readonly content: String; readonly encryptedValue: optionalKey<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly name: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; }>, Struct<{ readonly content: String; readonly encryptedValue: optionalKey<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly name: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; }>, Struct<{ readonly content: optionalKey<...>; readonly encryptedValue: optionalKey<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly name: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; readonly toolCalls: optionalKey<...>; }>, Struct<{ readonly content: Union<...>; readonly encryptedValue: optionalKey<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly name: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; }>, Struct<{ readonly content: Union<...>; readonly encryptedValue: optionalKey<...>; readonly error: optionalKey<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; readonly toolCallId: String; }>, Struct<{ readonly activityType: String; readonly content: $Record<..., ...>; readonly id: String; readonly metadata: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; }>, Struct<{ readonly content: String; readonly encryptedValue: optionalKey<...>; readonly id: String; readonly metadata: optionalKey<...>; readonly role: Literal<...>; readonly subagentRunId: optionalKey<...>; }>]>, Any]>>, never, never>; readonly parentRunId: optionalKey<String>; readonly protocolVersion: optionalKey<String>; readonly resume: optionalKey<decodeTo<$Array<toType<Struct<{ readonly interruptId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly payload: optionalKey<Unknown>; readonly status: Literals<readonly ["resolved", "cancelled"]>; }>>>, $Array<Union<readonly [Struct<{ readonly interruptId: String; readonly metadata: optionalKey<$Record<..., ...>>; readonly payload: optionalKey<Unknown>; readonly status: Literals<readonly [..., ...]>; }>, 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>;}> Since v4.1.0 Source
Schema for the event that ends a run that failed.
Signature
declare const RunErrorEvent: 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<{ readonly cachedInputTokens: optionalKey<Int>; readonly cacheWriteInputTokens: optionalKey<Int>; readonly inputTokens: optionalKey<Int>; readonly model: optionalKey<String>; readonly outputTokens: optionalKey<Int>; readonly provider: optionalKey<String>; readonly reasoningTokens: optionalKey<Int>; readonly totalTokens: optionalKey<Int>; }>>>;}> Since v4.1.0 Source
Schema for the event that closes a run that did not fail.
Signature
declare const RunFinishedEvent: Struct<{ readonly metadata: optionalKey<$Record<String, Unknown>>; readonly outcome: optionalKey<Union<readonly [Struct<{ readonly pendingToolCallIds: optionalKey<$Array<String>>; readonly type: Literal<"success">; }>, Struct<{ readonly interrupts: NonEmptyArray<Struct<{ readonly expiresAt: optionalKey<...>; readonly id: String; readonly message: optionalKey<...>; readonly metadata: optionalKey<...>; readonly reason: String; readonly responseSchema: optionalKey<...>; readonly subagentRunId: optionalKey<...>; readonly toolCallId: optionalKey<...>; }>>; readonly type: Literal<"interrupt">; }>, Struct<{ readonly type: Literal<"cancelled">; }>]>>; 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<{ readonly cachedInputTokens: optionalKey<Int>; readonly cacheWriteInputTokens: optionalKey<Int>; readonly inputTokens: optionalKey<Int>; readonly model: optionalKey<String>; readonly outputTokens: optionalKey<Int>; readonly provider: optionalKey<String>; readonly reasoningTokens: optionalKey<Int>; readonly totalTokens: optionalKey<Int>; }>>>;}> Since v4.1.0 Source
Schema for why a run ended.
Details
A success outcome may name frontend tool calls the application still has
to answer. An interrupt outcome pauses the run until a later run resumes
it.
Signature
declare const RunFinishedOutcome: Union<readonly [Struct<{ readonly pendingToolCallIds: optionalKey<$Array<String>>; readonly type: Literal<"success">;}>, Struct<{ readonly interrupts: NonEmptyArray<Struct<{ readonly expiresAt: optionalKey<String>; readonly id: String; readonly message: optionalKey<String>; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly reason: String; readonly responseSchema: optionalKey<$Record<String, Unknown>>; readonly subagentRunId: optionalKey<String>; readonly toolCallId: optionalKey<String>; }>>; readonly type: Literal<"interrupt">;}>, Struct<{ readonly type: Literal<"cancelled">;}>]> Since v4.1.0 Source
Schema for the event that opens a run.
Signature
declare const RunStartedEvent: Struct<{ readonly input: optionalKey<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<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>]>>>, $Array<Union<readonly [Union<readonly [..., ..., ..., ..., ..., ..., ...]>, Any]>>, never, never>; readonly parentRunId: optionalKey<String>; readonly protocolVersion: optionalKey<String>; readonly resume: optionalKey<decodeTo<$Array<toType<Struct<{ readonly interruptId: ...; readonly metadata: ...; readonly payload: ...; readonly status: ...; }>>>, $Array<Union<readonly [Struct<...>, 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<..., ...>>; readonly name: String; readonly parameters: optionalKey<Unknown>; }>>, never>; }>>; 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">;}> Since v4.1.0 Source
Schema for the event that applies a JSON Patch to the agent state.
Signature
declare const StateDeltaEvent: Struct<{ readonly delta: $Array<Union<readonly [Struct<{ readonly op: Literal<"add">; readonly path: String; readonly value: Unknown; }>, Struct<{ readonly op: Literal<"remove">; readonly path: String; }>, Struct<{ readonly op: Literal<"replace">; readonly path: String; readonly value: Unknown; }>, Struct<{ readonly from: String; readonly op: Literal<"move">; readonly path: String; }>, Struct<{ readonly from: String; readonly op: Literal<"copy">; readonly path: String; }>, Struct<{ readonly op: Literal<"test">; readonly path: String; readonly value: Unknown; }>]>>; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly rawEvent: optionalKey<Unknown>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"STATE_DELTA">;}> Since v4.1.0 Source
Schema for the event that replaces the agent state.
Signature
declare const StateSnapshotEvent: 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">;}> Since v4.1.0 Source
Schema for the event that closes a named step.
Signature
declare const StepFinishedEvent: 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">;}> Since v4.1.0 Source
Schema for the event that opens a named step within a run.
Signature
declare const StepStartedEvent: 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">;}> Since v4.1.0 Source
Schema for the event that reports a failed subagent invocation without ending the run.
Signature
declare const SubagentErrorEvent: 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">;}> Since v4.1.0 Source
Schema for the event that closes a subagent invocation that did not fail.
Signature
declare const SubagentFinishedEvent: Struct<{ readonly metadata: optionalKey<$Record<String, Unknown>>; readonly outcome: optionalKey<Union<readonly [Struct<{ readonly type: Literal<"success">; }>, Struct<{ readonly interruptIds: optionalKey<$Array<String>>; readonly type: Literal<"suspended">; }>]>>; readonly rawEvent: optionalKey<Unknown>; readonly result: optionalKey<Unknown>; readonly subagentRunId: String; readonly timestamp: optionalKey<Int>; readonly type: Literal<"SUBAGENT_FINISHED">;}> Since v4.1.0 Source
Schema for the event that opens a subagent invocation within a run.
Signature
declare const SubagentStartedEvent: 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">;}> Since v4.1.0 Source
Schema for instructions from the system.
Signature
declare const SystemMessage: Struct<{ readonly content: String; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: optionalKey<String>; readonly role: Literal<"system">; readonly subagentRunId: optionalKey<String>;}> Since v4.1.0 Source
Schema for the shorthand event that stands in for a text message's start, content, and end sequence.
Signature
declare const TextMessageChunkEvent: 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 ["developer", "system", "assistant", "user"]>>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"TEXT_MESSAGE_CHUNK">;}> Since v4.1.0 Source
Schema for the event that appends a fragment to a streamed text message.
Signature
declare const TextMessageContentEvent: 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">;}> Since v4.1.0 Source
Schema for the event that closes a streamed text message.
Signature
declare const TextMessageEndEvent: 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">;}> Since v4.1.0 Source
Schema for the role of a streamed text message.
Signature
declare const TextMessageRole: Literals<readonly ["developer", "system", "assistant", "user"]> Since v4.1.0 Source
Schema for the event that opens a streamed text message.
Signature
declare const TextMessageStartEvent: Struct<{ readonly messageId: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: optionalKey<String>; readonly rawEvent: optionalKey<Unknown>; readonly role: optionalKey<Literals<readonly ["developer", "system", "assistant", "user"]>>; readonly subagentRunId: optionalKey<String>; readonly timestamp: optionalKey<Int>; readonly type: Literal<"TEXT_MESSAGE_START">;}>Schema for a text content part.
Signature
declare const TextPart: Struct<{ readonly id: optionalKey<String>; readonly metadata: optionalKey<Unknown>; readonly text: String; readonly type: Literal<"text">;}> Since v4.1.0 Source
Schema for token counts reported for one provider and model.
Signature
declare const TokenUsage: Struct<{ readonly cachedInputTokens: optionalKey<Int>; readonly cacheWriteInputTokens: optionalKey<Int>; readonly inputTokens: optionalKey<Int>; readonly model: optionalKey<String>; readonly outputTokens: optionalKey<Int>; readonly provider: optionalKey<String>; readonly reasoningTokens: optionalKey<Int>; readonly totalTokens: optionalKey<Int>;}>Schema for a tool the application offers to the agent.
Details
parameters is a JSON Schema describing the tool's arguments.
Signature
declare const Tool: Struct<{ readonly description: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: String; readonly parameters: optionalKey<Unknown>;}>Schema for a tool call made by an assistant message.
Details
function.arguments is the JSON text of the call's arguments.
Signature
declare const ToolCall: Struct<{ readonly encryptedValue: optionalKey<String>; readonly function: Struct<{ readonly arguments: String; readonly name: String; }>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly type: Literal<"function">;}> Since v4.1.0 Source
Schema for the event that appends a fragment of a tool call's JSON arguments.
Signature
declare const ToolCallArgsEvent: 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">;}> Since v4.1.0 Source
Schema for the shorthand event that stands in for a tool call's start, arguments, and end sequence.
Signature
declare const ToolCallChunkEvent: 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">;}> Since v4.1.0 Source
Schema for the event that closes a tool call once its arguments are complete.
Signature
declare const ToolCallEndEvent: 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">;}> Since v4.1.0 Source
Schema for the event that delivers the result of a tool call as a new tool message.
Signature
declare const ToolCallResultEvent: Struct<{ readonly content: Union<readonly [String, decodeTo<$Array<toType<Union<readonly [Struct<{ readonly id: ...; readonly metadata: ...; readonly text: ...; readonly type: ...; }>, Struct<{ readonly id: ...; readonly metadata: ...; readonly source: ...; readonly type: ...; }>, Struct<{ readonly id: ...; readonly metadata: ...; readonly source: ...; readonly type: ...; }>, Struct<{ readonly id: ...; readonly metadata: ...; readonly source: ...; readonly type: ...; }>, Struct<{ readonly id: ...; readonly metadata: ...; readonly source: ...; readonly type: ...; }>]>>>, $Array<Union<readonly [Union<readonly [Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>]>, Any]>>, never, never>]>; 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">;}> Since v4.1.0 Source
Schema for the event that opens a tool call.
Signature
declare const ToolCallStartEvent: 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">;}> Since v4.1.0 Source
Schema for the result of a tool call, as a message in the conversation.
Details
error is present when the tool call failed.
Signature
declare const ToolMessage: Struct<{ readonly content: Union<readonly [String, decodeTo<$Array<toType<Union<readonly [Struct<{ readonly id: ...; readonly metadata: ...; readonly text: ...; readonly type: ...; }>, Struct<{ readonly id: ...; readonly metadata: ...; readonly source: ...; readonly type: ...; }>, Struct<{ readonly id: ...; readonly metadata: ...; readonly source: ...; readonly type: ...; }>, Struct<{ readonly id: ...; readonly metadata: ...; readonly source: ...; readonly type: ...; }>, Struct<{ readonly id: ...; readonly metadata: ...; readonly source: ...; readonly type: ...; }>]>>>, $Array<Union<readonly [Union<readonly [Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>]>, Any]>>, never, never>]>; readonly encryptedValue: optionalKey<String>; readonly error: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly role: Literal<"tool">; readonly subagentRunId: optionalKey<String>; readonly toolCallId: String;}>Schema for media bytes referenced by URL.
Signature
declare const UrlSource: Struct<{ readonly mimeType: optionalKey<String>; readonly type: Literal<"url">; readonly value: String;}> Since v4.1.0 Source
Schema for a message from the person using the application.
Signature
declare const UserMessage: Struct<{ readonly content: Union<readonly [String, decodeTo<$Array<toType<Union<readonly [Struct<{ readonly id: ...; readonly metadata: ...; readonly text: ...; readonly type: ...; }>, Struct<{ readonly id: ...; readonly metadata: ...; readonly source: ...; readonly type: ...; }>, Struct<{ readonly id: ...; readonly metadata: ...; readonly source: ...; readonly type: ...; }>, Struct<{ readonly id: ...; readonly metadata: ...; readonly source: ...; readonly type: ...; }>, Struct<{ readonly id: ...; readonly metadata: ...; readonly source: ...; readonly type: ...; }>]>>>, $Array<Union<readonly [Union<readonly [Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>]>, Any]>>, never, never>]>; readonly encryptedValue: optionalKey<String>; readonly id: String; readonly metadata: optionalKey<$Record<String, Unknown>>; readonly name: optionalKey<String>; readonly role: Literal<"user">; readonly subagentRunId: optionalKey<String>;}>Schema for a video content part.
Signature
declare const VideoPart: Struct<{ readonly id: optionalKey<String>; readonly metadata: optionalKey<Unknown>; readonly source: Union<readonly [Struct<{ readonly mimeType: String; readonly type: Literal<"data">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly type: Literal<"url">; readonly value: String; }>, Struct<{ readonly mimeType: optionalKey<String>; readonly provider: optionalKey<String>; readonly type: Literal<"file">; readonly value: String; }>]>; readonly type: Literal<"video">;}>