wehub-resource-sync
689 lines
25 KiB
Markdown
689 lines
25 KiB
Markdown
# AG-UI Protocol Specification -- Event Type Reference
|
|
|
|
Complete reference for all AG-UI event types, derived from `@ag-ui/core` Zod schemas.
|
|
|
|
## Base Event Fields
|
|
|
|
All events extend `BaseEventSchema` and share these fields:
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------- | ------------------------- | -------- | ------------------------------------------------------ |
|
|
| `type` | `EventType` (string enum) | Yes | Event type discriminator |
|
|
| `timestamp` | `number` | No | Unix timestamp (ms) when event was created |
|
|
| `rawEvent` | `any` | No | Original event data if transformed from another format |
|
|
|
|
Events use `.passthrough()` so additional fields are preserved through parsing.
|
|
|
|
---
|
|
|
|
## Lifecycle Events
|
|
|
|
### RUN_STARTED
|
|
|
|
Emitted first when an agent begins processing. Establishes the run context.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ------------- | --------------- | -------- | ------------------------------------------ |
|
|
| `type` | `"RUN_STARTED"` | Yes | |
|
|
| `threadId` | `string` | Yes | Conversation thread ID |
|
|
| `runId` | `string` | Yes | Unique run ID |
|
|
| `parentRunId` | `string` | No | Lineage pointer for branching/time travel |
|
|
| `input` | `RunAgentInput` | No | The exact agent input payload for this run |
|
|
|
|
```json
|
|
{
|
|
"type": "RUN_STARTED",
|
|
"threadId": "thread-abc",
|
|
"runId": "run-123"
|
|
}
|
|
```
|
|
|
|
### RUN_FINISHED
|
|
|
|
Emitted when an agent run completes successfully. No further events for this run after this.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ---------- | ---------------- | -------- | ----------------------------- |
|
|
| `type` | `"RUN_FINISHED"` | Yes | |
|
|
| `threadId` | `string` | Yes | Conversation thread ID |
|
|
| `runId` | `string` | Yes | Run ID matching `RUN_STARTED` |
|
|
| `result` | `any` | No | Output data from the run |
|
|
|
|
```json
|
|
{
|
|
"type": "RUN_FINISHED",
|
|
"threadId": "thread-abc",
|
|
"runId": "run-123",
|
|
"result": { "summary": "Task completed" }
|
|
}
|
|
```
|
|
|
|
### RUN_ERROR
|
|
|
|
Emitted when an agent encounters an unrecoverable error. Terminates the run.
|
|
|
|
| Field | Type | Required | Description |
|
|
| --------- | ------------- | -------- | ----------------------------------------- |
|
|
| `type` | `"RUN_ERROR"` | Yes | |
|
|
| `message` | `string` | Yes | Error description |
|
|
| `code` | `string` | No | Error code (e.g., `"abort"`, `"timeout"`) |
|
|
|
|
```json
|
|
{
|
|
"type": "RUN_ERROR",
|
|
"message": "Model API rate limited",
|
|
"code": "rate_limit"
|
|
}
|
|
```
|
|
|
|
### STEP_STARTED
|
|
|
|
Emitted when a named step/phase begins within a run. Optional but recommended for progress visibility.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ---------- | ---------------- | -------- | ------------------------------------------------- |
|
|
| `type` | `"STEP_STARTED"` | Yes | |
|
|
| `stepName` | `string` | Yes | Name of the step (e.g., node name, function name) |
|
|
|
|
```json
|
|
{
|
|
"type": "STEP_STARTED",
|
|
"stepName": "retrieve_documents"
|
|
}
|
|
```
|
|
|
|
### STEP_FINISHED
|
|
|
|
Emitted when a named step completes. Must match a corresponding `STEP_STARTED`.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ---------- | ----------------- | -------- | ---------------- |
|
|
| `type` | `"STEP_FINISHED"` | Yes | |
|
|
| `stepName` | `string` | Yes | Name of the step |
|
|
|
|
```json
|
|
{
|
|
"type": "STEP_FINISHED",
|
|
"stepName": "retrieve_documents"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Text Message Events
|
|
|
|
### TEXT_MESSAGE_START
|
|
|
|
Begins a new streaming text message.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------- | -------------------------------------------------- | -------- | ------------------------- |
|
|
| `type` | `"TEXT_MESSAGE_START"` | Yes | |
|
|
| `messageId` | `string` | Yes | Unique message ID |
|
|
| `role` | `"developer" \| "system" \| "assistant" \| "user"` | No | Defaults to `"assistant"` |
|
|
| `name` | `string` | No | Optional sender name |
|
|
|
|
```json
|
|
{
|
|
"type": "TEXT_MESSAGE_START",
|
|
"messageId": "msg-1",
|
|
"role": "assistant"
|
|
}
|
|
```
|
|
|
|
### TEXT_MESSAGE_CONTENT
|
|
|
|
Delivers a chunk of text content. Multiple events build the complete message.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------- | ------------------------ | -------- | ----------------------------------------- |
|
|
| `type` | `"TEXT_MESSAGE_CONTENT"` | Yes | |
|
|
| `messageId` | `string` | Yes | Must match `TEXT_MESSAGE_START.messageId` |
|
|
| `delta` | `string` | Yes | Text chunk (must be non-empty) |
|
|
|
|
```json
|
|
{
|
|
"type": "TEXT_MESSAGE_CONTENT",
|
|
"messageId": "msg-1",
|
|
"delta": "Hello, how can "
|
|
}
|
|
```
|
|
|
|
### TEXT_MESSAGE_END
|
|
|
|
Signals that a text message is complete. No more content for this `messageId`.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------- | -------------------- | -------- | ----------------------------------------- |
|
|
| `type` | `"TEXT_MESSAGE_END"` | Yes | |
|
|
| `messageId` | `string` | Yes | Must match `TEXT_MESSAGE_START.messageId` |
|
|
|
|
```json
|
|
{
|
|
"type": "TEXT_MESSAGE_END",
|
|
"messageId": "msg-1"
|
|
}
|
|
```
|
|
|
|
### TEXT_MESSAGE_CHUNK (Convenience)
|
|
|
|
Auto-expands into `TEXT_MESSAGE_START` / `TEXT_MESSAGE_CONTENT` / `TEXT_MESSAGE_END` via the client's `transformChunks` pipeline. Simplifies backend implementation.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------- | -------------------------------------------------- | -------- | ------------------------------------------------ |
|
|
| `type` | `"TEXT_MESSAGE_CHUNK"` | Yes | |
|
|
| `messageId` | `string` | No | Required on first chunk; links subsequent chunks |
|
|
| `role` | `"developer" \| "system" \| "assistant" \| "user"` | No | Role for the message |
|
|
| `delta` | `string` | No | Text content chunk |
|
|
| `name` | `string` | No | Optional sender name |
|
|
|
|
The client transformer handles lifecycle:
|
|
|
|
- First chunk with a new `messageId` emits `TEXT_MESSAGE_START`
|
|
- Each chunk with `delta` emits `TEXT_MESSAGE_CONTENT`
|
|
- `TEXT_MESSAGE_END` is emitted when the stream switches to a new `messageId` or completes
|
|
|
|
```json
|
|
{
|
|
"type": "TEXT_MESSAGE_CHUNK",
|
|
"messageId": "msg-1",
|
|
"role": "assistant",
|
|
"delta": "Hello!"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Tool Call Events
|
|
|
|
### TOOL_CALL_START
|
|
|
|
Begins a new tool invocation.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------------- | ------------------- | -------- | --------------------------------------------- |
|
|
| `type` | `"TOOL_CALL_START"` | Yes | |
|
|
| `toolCallId` | `string` | Yes | Unique ID for this tool call |
|
|
| `toolCallName` | `string` | Yes | Name of the tool being called |
|
|
| `parentMessageId` | `string` | No | Links tool call to a parent assistant message |
|
|
|
|
```json
|
|
{
|
|
"type": "TOOL_CALL_START",
|
|
"toolCallId": "tc-1",
|
|
"toolCallName": "searchDatabase",
|
|
"parentMessageId": "msg-1"
|
|
}
|
|
```
|
|
|
|
### TOOL_CALL_ARGS
|
|
|
|
Streams argument data for a tool call. Arguments are JSON fragments that concatenate to form the complete arguments object.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ------------ | ------------------ | -------- | --------------------------------------- |
|
|
| `type` | `"TOOL_CALL_ARGS"` | Yes | |
|
|
| `toolCallId` | `string` | Yes | Must match `TOOL_CALL_START.toolCallId` |
|
|
| `delta` | `string` | Yes | Argument JSON fragment |
|
|
|
|
```json
|
|
{
|
|
"type": "TOOL_CALL_ARGS",
|
|
"toolCallId": "tc-1",
|
|
"delta": "{\"query\": \"recent orders\"}"
|
|
}
|
|
```
|
|
|
|
### TOOL_CALL_END
|
|
|
|
Signals that a tool call's arguments are complete.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ------------ | ----------------- | -------- | --------------------------------------- |
|
|
| `type` | `"TOOL_CALL_END"` | Yes | |
|
|
| `toolCallId` | `string` | Yes | Must match `TOOL_CALL_START.toolCallId` |
|
|
|
|
```json
|
|
{
|
|
"type": "TOOL_CALL_END",
|
|
"toolCallId": "tc-1"
|
|
}
|
|
```
|
|
|
|
### TOOL_CALL_RESULT
|
|
|
|
Delivers the result of a tool execution. Sent after the tool has been executed (typically by the client/frontend).
|
|
|
|
| Field | Type | Required | Description |
|
|
| ------------ | -------------------- | -------- | --------------------------------------------------------- |
|
|
| `type` | `"TOOL_CALL_RESULT"` | Yes | |
|
|
| `messageId` | `string` | Yes | Message ID for this result in conversation history |
|
|
| `toolCallId` | `string` | Yes | Must match the corresponding `TOOL_CALL_START.toolCallId` |
|
|
| `content` | `string` | Yes | Tool execution output |
|
|
| `role` | `"tool"` | No | Defaults to `"tool"` |
|
|
|
|
```json
|
|
{
|
|
"type": "TOOL_CALL_RESULT",
|
|
"messageId": "msg-tool-1",
|
|
"toolCallId": "tc-1",
|
|
"content": "{\"results\": [{\"orderId\": \"123\"}]}",
|
|
"role": "tool"
|
|
}
|
|
```
|
|
|
|
### TOOL_CALL_CHUNK (Convenience)
|
|
|
|
Auto-expands into `TOOL_CALL_START` / `TOOL_CALL_ARGS` / `TOOL_CALL_END` via the client's `transformChunks` pipeline.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------------- | ------------------- | -------- | ----------------------- |
|
|
| `type` | `"TOOL_CALL_CHUNK"` | Yes | |
|
|
| `toolCallId` | `string` | No | Required on first chunk |
|
|
| `toolCallName` | `string` | No | Required on first chunk |
|
|
| `parentMessageId` | `string` | No | Links to parent message |
|
|
| `delta` | `string` | No | Argument JSON fragment |
|
|
|
|
```json
|
|
{
|
|
"type": "TOOL_CALL_CHUNK",
|
|
"toolCallId": "tc-1",
|
|
"toolCallName": "searchDatabase",
|
|
"delta": "{\"query\":"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## State Management Events
|
|
|
|
### STATE_SNAPSHOT
|
|
|
|
Delivers a complete replacement of the agent's state. Frontend should discard existing state and use this snapshot.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ---------- | ------------------ | -------- | --------------------- |
|
|
| `type` | `"STATE_SNAPSHOT"` | Yes | |
|
|
| `snapshot` | `any` | Yes | Complete state object |
|
|
|
|
```json
|
|
{
|
|
"type": "STATE_SNAPSHOT",
|
|
"snapshot": {
|
|
"documents": [],
|
|
"currentStep": "planning",
|
|
"progress": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
### STATE_DELTA
|
|
|
|
Delivers incremental state updates as RFC 6902 JSON Patch operations. Applied to current state using `fast-json-patch`.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ------- | -------------------- | -------- | ------------------------------ |
|
|
| `type` | `"STATE_DELTA"` | Yes | |
|
|
| `delta` | `Array<JsonPatchOp>` | Yes | Array of JSON Patch operations |
|
|
|
|
JSON Patch operations:
|
|
|
|
- `{ "op": "add", "path": "/key", "value": ... }`
|
|
- `{ "op": "replace", "path": "/key", "value": ... }`
|
|
- `{ "op": "remove", "path": "/key" }`
|
|
- `{ "op": "move", "path": "/to", "from": "/from" }`
|
|
- `{ "op": "copy", "path": "/to", "from": "/from" }`
|
|
- `{ "op": "test", "path": "/key", "value": ... }`
|
|
|
|
```json
|
|
{
|
|
"type": "STATE_DELTA",
|
|
"delta": [
|
|
{ "op": "replace", "path": "/currentStep", "value": "executing" },
|
|
{ "op": "replace", "path": "/progress", "value": 0.5 }
|
|
]
|
|
}
|
|
```
|
|
|
|
### MESSAGES_SNAPSHOT
|
|
|
|
Delivers a complete snapshot of the conversation message history. Uses edit-based merge: existing messages present in the snapshot are replaced, activity messages are preserved, messages not in the snapshot are removed, and new messages from the snapshot are appended.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ---------- | --------------------- | -------- | ------------------------ |
|
|
| `type` | `"MESSAGES_SNAPSHOT"` | Yes | |
|
|
| `messages` | `Message[]` | Yes | Array of message objects |
|
|
|
|
```json
|
|
{
|
|
"type": "MESSAGES_SNAPSHOT",
|
|
"messages": [
|
|
{ "id": "m1", "role": "user", "content": "Hello" },
|
|
{ "id": "m2", "role": "assistant", "content": "Hi there!" }
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Activity Events
|
|
|
|
### ACTIVITY_SNAPSHOT
|
|
|
|
Delivers a complete snapshot of an activity (structured progress update displayed between chat messages).
|
|
|
|
| Field | Type | Required | Description |
|
|
| -------------- | --------------------- | -------- | ----------------------------------------------------------- |
|
|
| `type` | `"ACTIVITY_SNAPSHOT"` | Yes | |
|
|
| `messageId` | `string` | Yes | Activity message ID |
|
|
| `activityType` | `string` | Yes | Discriminator (e.g., `"PLAN"`, `"SEARCH"`, `"CODE"`) |
|
|
| `content` | `Record<string, any>` | Yes | Structured activity data |
|
|
| `replace` | `boolean` | No | Defaults to `true`. If `false`, ignored when message exists |
|
|
|
|
```json
|
|
{
|
|
"type": "ACTIVITY_SNAPSHOT",
|
|
"messageId": "activity-1",
|
|
"activityType": "SEARCH",
|
|
"content": {
|
|
"query": "CopilotKit setup",
|
|
"results": [],
|
|
"status": "searching"
|
|
}
|
|
}
|
|
```
|
|
|
|
### ACTIVITY_DELTA
|
|
|
|
Applies JSON Patch updates to an existing activity message's content.
|
|
|
|
| Field | Type | Required | Description |
|
|
| -------------- | -------------------- | -------- | --------------------------------------- |
|
|
| `type` | `"ACTIVITY_DELTA"` | Yes | |
|
|
| `messageId` | `string` | Yes | Must match an existing activity message |
|
|
| `activityType` | `string` | Yes | Activity discriminator |
|
|
| `patch` | `Array<JsonPatchOp>` | Yes | RFC 6902 JSON Patch operations |
|
|
|
|
```json
|
|
{
|
|
"type": "ACTIVITY_DELTA",
|
|
"messageId": "activity-1",
|
|
"activityType": "SEARCH",
|
|
"patch": [
|
|
{ "op": "replace", "path": "/status", "value": "complete" },
|
|
{
|
|
"op": "add",
|
|
"path": "/results/0",
|
|
"value": { "title": "Getting Started" }
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Reasoning Events
|
|
|
|
### REASONING_START
|
|
|
|
Marks the beginning of a reasoning process (chain-of-thought).
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------- | ------------------- | -------- | -------------------- |
|
|
| `type` | `"REASONING_START"` | Yes | |
|
|
| `messageId` | `string` | Yes | Reasoning context ID |
|
|
|
|
```json
|
|
{
|
|
"type": "REASONING_START",
|
|
"messageId": "reasoning-1"
|
|
}
|
|
```
|
|
|
|
### REASONING_MESSAGE_START
|
|
|
|
Begins a streaming reasoning message (visible portion of chain-of-thought).
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------- | --------------------------- | -------- | -------------------- |
|
|
| `type` | `"REASONING_MESSAGE_START"` | Yes | |
|
|
| `messageId` | `string` | Yes | Message ID |
|
|
| `role` | `"reasoning"` | Yes | Always `"reasoning"` |
|
|
|
|
```json
|
|
{
|
|
"type": "REASONING_MESSAGE_START",
|
|
"messageId": "reasoning-msg-1",
|
|
"role": "reasoning"
|
|
}
|
|
```
|
|
|
|
### REASONING_MESSAGE_CONTENT
|
|
|
|
Delivers a chunk of reasoning text.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------- | ----------------------------- | -------- | ---------------------------------------------- |
|
|
| `type` | `"REASONING_MESSAGE_CONTENT"` | Yes | |
|
|
| `messageId` | `string` | Yes | Must match `REASONING_MESSAGE_START.messageId` |
|
|
| `delta` | `string` | Yes | Reasoning text chunk (must be non-empty) |
|
|
|
|
```json
|
|
{
|
|
"type": "REASONING_MESSAGE_CONTENT",
|
|
"messageId": "reasoning-msg-1",
|
|
"delta": "Let me think about this..."
|
|
}
|
|
```
|
|
|
|
### REASONING_MESSAGE_END
|
|
|
|
Signals a reasoning message is complete.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------- | ------------------------- | -------- | ---------------------------------------------- |
|
|
| `type` | `"REASONING_MESSAGE_END"` | Yes | |
|
|
| `messageId` | `string` | Yes | Must match `REASONING_MESSAGE_START.messageId` |
|
|
|
|
```json
|
|
{
|
|
"type": "REASONING_MESSAGE_END",
|
|
"messageId": "reasoning-msg-1"
|
|
}
|
|
```
|
|
|
|
### REASONING_MESSAGE_CHUNK (Convenience)
|
|
|
|
Auto-expands into `REASONING_MESSAGE_START` / `CONTENT` / `END` via client transformer.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------- | --------------------------- | -------- | ----------------------- |
|
|
| `type` | `"REASONING_MESSAGE_CHUNK"` | Yes | |
|
|
| `messageId` | `string` | No | Required on first chunk |
|
|
| `delta` | `string` | No | Reasoning text chunk |
|
|
|
|
```json
|
|
{
|
|
"type": "REASONING_MESSAGE_CHUNK",
|
|
"messageId": "reasoning-msg-1",
|
|
"delta": "Analyzing the request..."
|
|
}
|
|
```
|
|
|
|
### REASONING_END
|
|
|
|
Marks the end of a reasoning process.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ----------- | ----------------- | -------- | -------------------------------------- |
|
|
| `type` | `"REASONING_END"` | Yes | |
|
|
| `messageId` | `string` | Yes | Must match `REASONING_START.messageId` |
|
|
|
|
```json
|
|
{
|
|
"type": "REASONING_END",
|
|
"messageId": "reasoning-1"
|
|
}
|
|
```
|
|
|
|
### REASONING_ENCRYPTED_VALUE
|
|
|
|
Attaches encrypted chain-of-thought to a message or tool call. Used for zero-data-retention (ZDR) scenarios where reasoning must be preserved across turns but not exposed to the client.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ---------------- | ----------------------------- | -------- | ------------------------------------- |
|
|
| `type` | `"REASONING_ENCRYPTED_VALUE"` | Yes | |
|
|
| `subtype` | `"message" \| "tool-call"` | Yes | Entity type this reasoning belongs to |
|
|
| `entityId` | `string` | Yes | ID of the message or tool call |
|
|
| `encryptedValue` | `string` | Yes | Opaque encrypted content blob |
|
|
|
|
```json
|
|
{
|
|
"type": "REASONING_ENCRYPTED_VALUE",
|
|
"subtype": "message",
|
|
"entityId": "msg-1",
|
|
"encryptedValue": "eyJhbGciOiJSU0..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Custom / Extension Events
|
|
|
|
### RAW
|
|
|
|
Passthrough container for events from external systems.
|
|
|
|
| Field | Type | Required | Description |
|
|
| -------- | -------- | -------- | ------------------------ |
|
|
| `type` | `"RAW"` | Yes | |
|
|
| `event` | `any` | Yes | Original event data |
|
|
| `source` | `string` | No | Source system identifier |
|
|
|
|
```json
|
|
{
|
|
"type": "RAW",
|
|
"event": { "vendor_type": "langchain_event", "data": {} },
|
|
"source": "langchain"
|
|
}
|
|
```
|
|
|
|
### CUSTOM
|
|
|
|
Application-specific extension events with named semantics.
|
|
|
|
| Field | Type | Required | Description |
|
|
| ------- | ---------- | -------- | ----------------- |
|
|
| `type` | `"CUSTOM"` | Yes | |
|
|
| `name` | `string` | Yes | Custom event name |
|
|
| `value` | `any` | Yes | Event payload |
|
|
|
|
```json
|
|
{
|
|
"type": "CUSTOM",
|
|
"name": "citation",
|
|
"value": { "url": "https://example.com", "title": "Reference" }
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Deprecated Events (Remove in 1.0.0)
|
|
|
|
These THINKING events are replaced by REASONING events:
|
|
|
|
| Deprecated | Replacement |
|
|
| ------------------------------- | --------------------------- |
|
|
| `THINKING_START` | `REASONING_START` |
|
|
| `THINKING_END` | `REASONING_END` |
|
|
| `THINKING_TEXT_MESSAGE_START` | `REASONING_MESSAGE_START` |
|
|
| `THINKING_TEXT_MESSAGE_CONTENT` | `REASONING_MESSAGE_CONTENT` |
|
|
| `THINKING_TEXT_MESSAGE_END` | `REASONING_MESSAGE_END` |
|
|
|
|
The client SDK includes `BackwardCompatibility_0_0_45` middleware that auto-converts these.
|
|
|
|
---
|
|
|
|
## Transport Encoding
|
|
|
|
### SSE (Server-Sent Events)
|
|
|
|
Default transport. Content-Type: `text/event-stream`.
|
|
|
|
Each event is encoded as:
|
|
|
|
```
|
|
data: <JSON>\n\n
|
|
```
|
|
|
|
The `@ag-ui/encoder` `EventEncoder` class produces this format:
|
|
|
|
```typescript
|
|
import { EventEncoder } from "@ag-ui/encoder";
|
|
|
|
const encoder = new EventEncoder();
|
|
const sseString = encoder.encode(event); // "data: {...}\n\n"
|
|
```
|
|
|
|
### Binary (Protobuf)
|
|
|
|
Optional binary transport using `@ag-ui/proto`. Content-Type: `application/x-ag-ui`.
|
|
|
|
Each message is length-prefixed: 4-byte big-endian uint32 length header followed by protobuf-encoded message bytes.
|
|
|
|
The `EventEncoder` auto-detects format from the `Accept` header:
|
|
|
|
```typescript
|
|
const encoder = new EventEncoder({ accept: req.headers.accept });
|
|
encoder.getContentType(); // "text/event-stream" or "application/x-ag-ui"
|
|
encoder.encodeBinary(event); // Uint8Array (SSE bytes or protobuf)
|
|
```
|
|
|
|
---
|
|
|
|
## Type Definitions (RunAgentInput)
|
|
|
|
The input payload sent to the agent on each run:
|
|
|
|
| Field | Type | Required | Description |
|
|
| ---------------- | ----------- | -------- | ------------------------ |
|
|
| `threadId` | `string` | Yes | Conversation thread ID |
|
|
| `runId` | `string` | Yes | Unique run ID |
|
|
| `parentRunId` | `string` | No | Parent run for branching |
|
|
| `state` | `any` | Yes | Current state |
|
|
| `messages` | `Message[]` | Yes | Conversation history |
|
|
| `tools` | `Tool[]` | Yes | Available tools |
|
|
| `context` | `Context[]` | Yes | Additional context |
|
|
| `forwardedProps` | `any` | Yes | Pass-through properties |
|
|
|
|
### Message Types
|
|
|
|
Messages are discriminated by `role`:
|
|
|
|
| Role | Fields | Description |
|
|
| ----------- | ------------------------------------------------------------------ | ----------------------------------- |
|
|
| `developer` | `id`, `role`, `content`, `name?`, `encryptedValue?` | Developer/system instructions |
|
|
| `system` | `id`, `role`, `content`, `name?`, `encryptedValue?` | System messages |
|
|
| `assistant` | `id`, `role`, `content?`, `toolCalls?`, `name?`, `encryptedValue?` | Agent responses |
|
|
| `user` | `id`, `role`, `content` (string or `InputContent[]`), `name?` | User messages (supports multimodal) |
|
|
| `tool` | `id`, `role`, `content`, `toolCallId`, `error?`, `encryptedValue?` | Tool results |
|
|
| `activity` | `id`, `role`, `activityType`, `content` (Record) | Activity progress |
|
|
| `reasoning` | `id`, `role`, `content`, `encryptedValue?` | Reasoning/thinking content |
|
|
|
|
### Tool Definition
|
|
|
|
```typescript
|
|
interface Tool {
|
|
name: string; // Tool name
|
|
description: string; // Human-readable description
|
|
parameters: any; // JSON Schema for parameters
|
|
}
|
|
```
|
|
|
|
### InputContent (Multimodal)
|
|
|
|
User messages can contain mixed content:
|
|
|
|
- `TextInputContent`: `{ type: "text", text: string }`
|
|
- `BinaryInputContent`: `{ type: "binary", mimeType: string, id?: string, url?: string, data?: string, filename?: string }` (requires at least one of `id`, `url`, or `data`)
|