# MCP, A2A, and AG-UI
Source: https://docs.ag-ui.com/agentic-protocols

Understanding how AG-UI complements and works with MCP and A2A

## Agentic Protocols

The agentic ecosystem is rapidly organizing around a family of open, complementary protocols — each addressing a distinct layer of interaction.  AG-UI has emerged as the 3rd leg of the AI protocol landscape:

![AI Protocol Stack](https://mintcdn.com/tawkitai/p1KIIAcVU0goF39y/images/ai-protocol-stack.png?fit=max\&auto=format\&n=p1KIIAcVU0goF39y\&q=85\&s=934df9d29866b7e61d3f95a650cf456a)

You can connect your application to agents directly via **AG-UI**, **MCP**, and **A2A**.

* **MCP** (Model Context Protocol) Connects agents to tools and to context — but those tools are themselves becoming agentic.
* **A2A** (Agent to Agent) Connects agents to other agents.
* **AG-UI (Agent–User Interaction)** Connects agents to users (through user-facing applications).

  You can think of AG-UI as the **"kitchen sink" protocol** — informed by bottom-up, real-world needs for building best-in-class agentic applications.

These three agentic protocols are complementary and have distinct technical goals; a single agent can and often does use all 3 simultaneously.

## AG-UI Handshakes with MCP and A2A

AG-UI contributors have recently added handshakes, allowing AG-UI to "front for" agents through MCP and A2A protocols, which allows AG-UI client apps and libraries to seamlessly use MCP and A2A supporting agents.

AG-UI's mandate is to support the full set of building blocks required by modern agentic applications.

## Generative UI Specs

Recently several [generative ui specs](./concepts/generative-ui-specs) (including MCP-UI, Open JSON UI, and A2UI) have been released which allow agents to deliver UI widgets through the interaction protocols.  AG-UI works with all of these.  Visit our [generative ui specs page](./concepts/generative-ui-specs) to learn more.


# Agents
Source: https://docs.ag-ui.com/concepts/agents

Learn about agents in the Agent User Interaction Protocol

# Agents

Agents are the core components in the AG-UI protocol that process requests and
generate responses. They establish a standardized way for front-end applications
to communicate with AI services through a consistent interface, regardless of
the underlying implementation.

## What is an Agent?

In AG-UI, an agent is a class that:

1. Manages conversation state and message history
2. Processes incoming messages and context
3. Generates responses through an event-driven streaming interface
4. Follows a standardized protocol for communication

Agents can be implemented to connect with any AI service, including:

* Large language models (LLMs) like GPT-4 or Claude
* Custom AI systems
* Retrieval augmented generation (RAG) systems
* Multi-agent systems

## Agent Architecture

All agents in AG-UI extend the `AbstractAgent` class, which provides the
foundation for:

* State management
* Message history tracking
* Event stream processing
* Tool usage

```typescript theme={null}
import { AbstractAgent } from "@ag-ui/client"

class MyAgent extends AbstractAgent {
  run(input: RunAgentInput): RunAgent {
    // Implementation details
  }
}
```

### Core Components

AG-UI agents have several key components:

1. **Configuration**: Agent ID, thread ID, and initial state
2. **Messages**: Conversation history with user and assistant messages
3. **State**: Structured data that persists across interactions
4. **Events**: Standardized messages for communication with clients
5. **Tools**: Functions that agents can use to interact with external systems

## Agent Types

AG-UI provides different agent implementations to suit various needs:

### AbstractAgent

The base class that all agents extend. It handles core event processing, state
management, and message history.

### HttpAgent

A concrete implementation that connects to remote AI services via HTTP:

```typescript theme={null}
import { HttpAgent } from "@ag-ui/client"

const agent = new HttpAgent({
  url: "https://your-agent-endpoint.com/agent",
  headers: {
    Authorization: "Bearer your-api-key",
  },
})
```

### Custom Agents

You can create custom agents to integrate with any AI service by extending
`AbstractAgent`:

```typescript theme={null}
class CustomAgent extends AbstractAgent {
  // Custom properties and methods

  run(input: RunAgentInput): RunAgent {
    // Implement the agent's logic
  }
}
```

## Implementing Agents

### Basic Implementation

To create a custom agent, extend the `AbstractAgent` class and implement the
required `run` method:

```typescript theme={null}
import {
  AbstractAgent,
  RunAgent,
  RunAgentInput,
  EventType,
  BaseEvent,
} from "@ag-ui/client"
import { Observable } from "rxjs"

class SimpleAgent extends AbstractAgent {
  run(input: RunAgentInput): RunAgent {
    const { threadId, runId } = input

    return () =>
      new Observable<BaseEvent>((observer) => {
        // Emit RUN_STARTED event
        observer.next({
          type: EventType.RUN_STARTED,
          threadId,
          runId,
        })

        // Send a message
        const messageId = Date.now().toString()

        // Message start
        observer.next({
          type: EventType.TEXT_MESSAGE_START,
          messageId,
          role: "assistant",
        })

        // Message content
        observer.next({
          type: EventType.TEXT_MESSAGE_CONTENT,
          messageId,
          delta: "Hello, world!",
        })

        // Message end
        observer.next({
          type: EventType.TEXT_MESSAGE_END,
          messageId,
        })

        // Emit RUN_FINISHED event
        observer.next({
          type: EventType.RUN_FINISHED,
          threadId,
          runId,
        })

        // Complete the observable
        observer.complete()
      })
  }
}
```

## Agent Capabilities

Agents in the AG-UI protocol provide a rich set of capabilities that enable
sophisticated AI interactions:

### Interactive Communication

Agents establish bi-directional communication channels with front-end
applications through event streams. This enables:

* Real-time streaming responses character-by-character
* Immediate feedback loops between user and AI
* Progress indicators for long-running operations
* Structured data exchange in both directions

### Tool Usage

Agents can use tools to perform actions and access external resources.
Importantly, tools are defined and passed in from the front-end application to
the agent, allowing for a flexible and extensible system:

```typescript theme={null}
// Tool definition
const confirmAction = {
  name: "confirmAction",
  description: "Ask the user to confirm a specific action before proceeding",
  parameters: {
    type: "object",
    properties: {
      action: {
        type: "string",
        description: "The action that needs user confirmation",
      },
      importance: {
        type: "string",
        enum: ["low", "medium", "high", "critical"],
        description: "The importance level of the action",
      },
      details: {
        type: "string",
        description: "Additional details about the action",
      },
    },
    required: ["action"],
  },
}

// Running an agent with tools from the frontend
agent.runAgent({
  tools: [confirmAction], // Frontend-defined tools passed to the agent
  // other parameters
})
```

Tools are invoked through a sequence of events:

1. `TOOL_CALL_START`: Indicates the beginning of a tool call
2. `TOOL_CALL_ARGS`: Streams the arguments for the tool call
3. `TOOL_CALL_END`: Marks the completion of the tool call

Front-end applications can then execute the tool and provide results back to the
agent. This bidirectional flow enables sophisticated human-in-the-loop workflows
where:

* The agent can request specific actions be performed
* Humans can execute those actions with appropriate judgment
* Results are fed back to the agent for continued reasoning
* The agent maintains awareness of all decisions made in the process

This mechanism is particularly powerful for implementing interfaces where AI and
humans collaborate. For example, [CopilotKit](https://docs.copilotkit.ai/)
leverages this exact pattern with their
[`useCopilotAction`](https://docs.copilotkit.ai/guides/frontend-actions) hook,
which provides a simplified way to define and handle tools in React
applications.

By keeping the AI informed about human decisions through the tool mechanism,
applications can maintain context and create more natural collaborative
experiences between users and AI assistants.

### State Management

Agents maintain a structured state that persists across interactions. This state
can be:

* Updated incrementally through `STATE_DELTA` events
* Completely refreshed with `STATE_SNAPSHOT` events
* Accessed by both the agent and front-end
* Used to store user preferences, conversation context, or application state

```typescript theme={null}
// Accessing agent state
console.log(agent.state.preferences)

// State is automatically updated during agent runs
agent.runAgent().subscribe((event) => {
  if (event.type === EventType.STATE_DELTA) {
    // State has been updated
    console.log("New state:", agent.state)
  }
})
```

### Multi-Agent Collaboration

AG-UI supports agent-to-agent handoff and collaboration:

* Agents can delegate tasks to other specialized agents
* Multiple agents can work together in a coordinated workflow
* State and context can be transferred between agents
* The front-end maintains a consistent experience across agent transitions

For example, a general assistant agent might hand off to a specialized coding
agent when programming help is needed, passing along the conversation context
and specific requirements.

### Human-in-the-Loop Workflows

Agents support human intervention and assistance:

* Agents can request human input on specific decisions
* Front-ends can pause agent execution and resume it after human feedback
* Human experts can review and modify agent outputs before they're finalized
* Hybrid workflows combine AI efficiency with human judgment

This enables applications where the agent acts as a collaborative partner rather
than an autonomous system.

### Conversational Memory

Agents maintain a complete history of conversation messages:

* Past interactions inform future responses
* Message history is synchronized between client and server
* Messages can include rich content (text, structured data, references)
* The context window can be managed to focus on relevant information

```typescript theme={null}
// Accessing message history
console.log(agent.messages)

// Adding a new user message
agent.messages.push({
  id: "msg_123",
  role: "user",
  content: "Can you explain that in more detail?",
})
```

### Metadata and Instrumentation

Agents can emit metadata about their internal processes:

* Reasoning steps through custom events
* Performance metrics and timing information
* Source citations and reference tracking
* Confidence scores for different response options

This allows front-ends to provide transparency into the agent's decision-making
process and help users understand how conclusions were reached.

## Using Agents

Once you've implemented or instantiated an agent, you can use it like this:

```typescript theme={null}
// Create an agent instance
const agent = new HttpAgent({
  url: "https://your-agent-endpoint.com/agent",
})

// Add initial messages if needed
agent.messages = [
  {
    id: "1",
    role: "user",
    content: "Hello, how can you help me today?",
  },
]

// Run the agent
agent
  .runAgent({
    runId: "run_123",
    tools: [], // Optional tools
    context: [], // Optional context
  })
  .subscribe({
    next: (event) => {
      // Handle different event types
      switch (event.type) {
        case EventType.TEXT_MESSAGE_CONTENT:
          console.log("Content:", event.delta)
          break
        // Handle other events
      }
    },
    error: (error) => console.error("Error:", error),
    complete: () => console.log("Run complete"),
  })
```

## Agent Configuration

Agents accept configuration through the constructor:

```typescript theme={null}
interface AgentConfig {
  agentId?: string // Unique identifier for the agent
  description?: string // Human-readable description
  threadId?: string // Conversation thread identifier
  initialMessages?: Message[] // Initial messages
  initialState?: State // Initial state object
}

// Using the configuration
const agent = new HttpAgent({
  agentId: "my-agent-123",
  description: "A helpful assistant",
  threadId: "thread-456",
  initialMessages: [
    { id: "1", role: "system", content: "You are a helpful assistant." },
  ],
  initialState: { preferredLanguage: "English" },
})
```

## Agent State Management

AG-UI agents maintain state across interactions:

```typescript theme={null}
// Access current state
console.log(agent.state)

// Access messages
console.log(agent.messages)

// Clone an agent with its state
const clonedAgent = agent.clone()
```

## Conclusion

Agents are the foundation of the AG-UI protocol, providing a standardized way to
connect front-end applications with AI services. By implementing the
`AbstractAgent` class, you can create custom integrations with any AI service
while maintaining a consistent interface for your applications.

The event-driven architecture enables real-time, streaming interactions that are
essential for modern AI applications, and the standardized protocol ensures
compatibility across different implementations.


# Core architecture
Source: https://docs.ag-ui.com/concepts/architecture

Understand how AG-UI connects front-end applications to AI agents

Agent User Interaction Protocol (AG-UI) is built on a flexible, event-driven
architecture that enables seamless, efficient communication between front-end
applications and AI agents. This document covers the core architectural
components and concepts.

## Design Principles

AG-UI is designed to be lightweight and minimally opinionated, making it easy to
integrate with a wide range of agent implementations. The protocol's flexibility
comes from its simple requirements:

1. **Event-Driven Communication**: Agents need to emit any of the 16
   standardized event types during execution, creating a stream of updates that
   clients can process.

2. **Bidirectional Interaction**: Agents accept input from users, enabling
   collaborative workflows where humans and AI work together seamlessly.

The protocol includes a built-in middleware layer that maximizes compatibility
in two key ways:

* **Flexible Event Structure**: Events don't need to match AG-UI's format
  exactly—they just need to be AG-UI-compatible. This allows existing agent
  frameworks to adapt their native event formats with minimal effort.

* **Transport Agnostic**: AG-UI doesn't mandate how events are delivered,
  supporting various transport mechanisms including Server-Sent Events (SSE),
  webhooks, WebSockets, and more. This flexibility lets developers choose the
  transport that best fits their architecture.

This pragmatic approach makes AG-UI easy to adopt without requiring major
changes to existing agent implementations or frontend applications.

## Architectural Overview

AG-UI follows a client-server architecture that standardizes communication
between agents and applications:

```mermaid theme={null}
flowchart LR
    subgraph "Frontend"
        App["Application"]
        Client["AG-UI Client"]
    end

    subgraph "Backend"
        A1["AI Agent A"]
        P["Secure Proxy"]
        A2["AI Agent B"]
        A3["AI Agent C"]
    end

    App <--> Client
    Client <-->|"AG-UI Protocol"| A1
    Client <-->|"AG-UI Protocol"| P
    P <-->|"AG-UI Protocol"| A2
    P <-->|"AG-UI Protocol"| A3

    class P mintStyle;
    classDef mintStyle fill:#E0F7E9,stroke:#66BB6A,stroke-width:2px,color:#000000;

    style App rx:5, ry:5;
    style Client rx:5, ry:5;
    style A1 rx:5, ry:5;
    style P rx:5, ry:5;
    style A2 rx:5, ry:5;
    style A3 rx:5, ry:5;
```

* **Application**: User-facing apps (i.e. chat or any AI-enabled application).
* **AG-UI Client**: Generic communication clients like `HttpAgent` or
  specialized clients for connecting to existing protocols.
* **Agents**: Backend AI agents that process requests and generate streaming
  responses.
* **Secure Proxy**: Backend services that provide additional capabilities and
  act as a secure proxy.

## Core components

### Protocol layer

AG-UI's protocol layer provides a flexible foundation for agent communication.

* **Universal compatibility**: Connect to any protocol by implementing
  `run(input: RunAgentInput) -> Observable<BaseEvent>`

The protocol's primary abstraction enables applications to run agents and
receive a stream of events:

```typescript theme={null}
// Core agent execution interface
type RunAgent = () => Observable<BaseEvent>

class MyAgent extends AbstractAgent {
  run(input: RunAgentInput): RunAgent {
    const { threadId, runId } = input
    return () =>
      from([
        { type: EventType.RUN_STARTED, threadId, runId },
        {
          type: EventType.MESSAGES_SNAPSHOT,
          messages: [
            { id: "msg_1", role: "assistant", content: "Hello, world!" }
          ],
        },
        { type: EventType.RUN_FINISHED, threadId, runId },
      ])
  }
}
```

### Standard HTTP client

AG-UI offers a standard HTTP client `HttpAgent` that can be used to connect to
any endpoint that accepts POST requests with a body of type `RunAgentInput` and
sends a stream of `BaseEvent` objects.

`HttpAgent` supports the following transports:

* **HTTP SSE (Server-Sent Events)**

  * Text-based streaming for wide compatibility
  * Easy to read and debug

* **HTTP binary protocol**
  * Highly performant and space-efficient custom transport
  * Robust binary serialization for production environments

### Message types

AG-UI defines several event categories for different aspects of agent
communication:

* **Lifecycle events**

  * `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`
  * `STEP_STARTED`, `STEP_FINISHED`

* **Text message events**

  * `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END`

* **Tool call events**

  * `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END`

* **State management events**

  * `STATE_SNAPSHOT`, `STATE_DELTA`, `MESSAGES_SNAPSHOT`

* **Special events**
  * `RAW`, `CUSTOM`

## Running Agents

To run an agent, you create a client instance and execute it:

```typescript theme={null}
// Create an HTTP agent client
const agent = new HttpAgent({
  url: "https://your-agent-endpoint.com/agent",
  agentId: "unique-agent-id",
  threadId: "conversation-thread"
});

// Start the agent and handle events
agent.runAgent({
  tools: [...],
  context: [...]
}).subscribe({
  next: (event) => {
    // Handle different event types
    switch(event.type) {
      case EventType.TEXT_MESSAGE_CONTENT:
        // Update UI with new content
        break;
      // Handle other event types
    }
  },
  error: (error) => console.error("Agent error:", error),
  complete: () => console.log("Agent run complete")
});
```

## State Management

AG-UI provides efficient state management through specialized events:

* `STATE_SNAPSHOT`: Complete state representation at a point in time
* `STATE_DELTA`: Incremental state changes using JSON Patch format (RFC 6902)
* `MESSAGES_SNAPSHOT`: Complete conversation history

These events enable efficient client-side state management with minimal data
transfer.

## Tools and Handoff

AG-UI supports agent-to-agent handoff and tool usage through standardized
events:

* Tool definitions are passed in the `runAgent` parameters
* Tool calls are streamed as sequences of `TOOL_CALL_START` → `TOOL_CALL_ARGS` →
  `TOOL_CALL_END` events
* Agents can hand off to other agents, maintaining context continuity

## Events

All communication in AG-UI is based on typed events. Every event inherits from
`BaseEvent`:

```typescript theme={null}
interface BaseEvent {
  type: EventType
  timestamp?: number
  rawEvent?: any
}
```

Events are strictly typed and validated, ensuring reliable communication between
components.


# Capabilities
Source: https://docs.ag-ui.com/concepts/capabilities

Dynamic capability discovery for agents in the AG-UI protocol

# Capabilities

Agents in the AG-UI protocol can declare what they support at runtime through
**capability discovery**. This allows clients to query an agent and adapt their
behavior based on what features are available — without guessing or hardcoding
assumptions.

## How It Works

`AbstractAgent` declares an optional `getCapabilities()` method that returns a
typed snapshot of everything the agent currently supports. It is implemented by
agent subclasses that know their own capabilities — the LangGraph and ADK
integrations, or your own — not by the bare `HttpAgent`, which is a transport
and has no discovery endpoint to ask. The optional call below returns
`undefined` for an agent that does not implement it:

```typescript theme={null}
// Any AbstractAgent subclass that implements getCapabilities(); a plain
// HttpAgent does not, and would yield undefined here.
const agent = new LangGraphAgent({ url: "https://my-agent.example.com/api" })

const capabilities = await agent.getCapabilities?.()

if (capabilities?.tools?.supported) {
  console.log(`Agent provides ${capabilities.tools.items?.length} tools`)
}

if (capabilities?.reasoning?.supported) {
  // Show reasoning UI toggle
}
```

### Key Principles

* **Discovery only** — the agent declares what it can do, there is no
  negotiation
* **Dynamic** — returns the current state at the time of the call (e.g., if
  tools are added, the next call reflects them)
* **Optional** — agents that don't implement it return `undefined`
* **Absent = unknown** — only declare what you support, omitted fields mean the
  capability is not declared

## The AgentCapabilities Interface

Capabilities are organized into typed categories, each representing a different
aspect of agent functionality:

```typescript theme={null}
interface AgentCapabilities {
  /** Agent identity and metadata. */
  identity?: IdentityCapabilities
  /** Supported transport mechanisms (SSE, WebSocket, binary, etc.). */
  transport?: TransportCapabilities
  /** Tools the agent provides and tool calling configuration. */
  tools?: ToolsCapabilities
  /** Output format support (structured output, MIME types). */
  output?: OutputCapabilities
  /** State and memory management (snapshots, deltas, persistence). */
  state?: StateCapabilities
  /** Multi-agent coordination (delegation, handoffs, sub-agents). */
  multiAgent?: MultiAgentCapabilities
  /** Reasoning and thinking support (chain-of-thought, encrypted thinking). */
  reasoning?: ReasoningCapabilities
  /** Multimodal input/output support organized by direction (input vs output). */
  multimodal?: MultimodalCapabilities
  /** Execution control and limits (code execution, timeouts, iteration caps). */
  execution?: ExecutionCapabilities
  /** Human-in-the-loop support (approvals, interventions, feedback). */
  humanInTheLoop?: HumanInTheLoopCapabilities
  /** Integration-specific capabilities not covered by the standard categories. */
  custom?: Record<string, unknown>
}
```

The `custom` field is an escape hatch for integration-specific capabilities that
don't fit into the standard categories.

## Capability Categories

### Identity

Basic metadata about the agent. Useful for discovery UIs, agent marketplaces,
and debugging. Set these when you want clients to display agent information or
when multiple agents are available and users need to pick one.

```typescript theme={null}
interface IdentityCapabilities {
  /** Human-readable name shown in UIs and agent selectors. */
  name?: string
  /** The framework or platform powering this agent (e.g., "langgraph", "mastra", "crewai"). */
  type?: string
  /** What this agent does — helps users and routing logic decide when to use it. */
  description?: string
  /** Semantic version of the agent (e.g., "1.2.0"). Useful for compatibility checks. */
  version?: string
  /** Organization or team that maintains this agent. */
  provider?: string
  /** URL to the agent's documentation or homepage. */
  documentationUrl?: string
  /** Arbitrary key-value pairs for integration-specific identity info. */
  metadata?: Record<string, unknown>
}
```

### Transport

Declares which transport mechanisms the agent supports. Clients use this to pick
the best connection strategy. Only set flags to `true` for transports your agent
actually handles — omit or set `false` for unsupported ones.

```typescript theme={null}
interface TransportCapabilities {
  /** Set `true` if the agent streams responses via SSE. Most agents enable this. */
  streaming?: boolean
  /** Set `true` if the agent accepts persistent WebSocket connections. */
  websocket?: boolean
  /** Set `true` if the agent supports the AG-UI binary protocol (protobuf over HTTP). */
  httpBinary?: boolean
  /** Set `true` if the agent can send async updates via webhooks after a run finishes. */
  pushNotifications?: boolean
  /** Set `true` if the agent supports resuming interrupted streams via sequence numbers. */
  resumable?: boolean
}
```

### Tools

Tool calling capabilities. Distinguishes between tools the agent itself provides
(listed in `items`) and tools the client passes at runtime via
`RunAgentInput.tools`. Enable this when your agent can call functions, search the
web, execute code, etc.

```typescript theme={null}
interface ToolsCapabilities {
  /** Set `true` if the agent can make tool calls at all. Set `false` to explicitly
   *  signal tool calling is disabled even if items are present. */
  supported?: boolean
  /** The tools this agent provides on its own (full JSON Schema definitions).
   *  These are distinct from client-provided tools passed in `RunAgentInput.tools`. */
  items?: Tool[]
  /** Set `true` if the agent can invoke multiple tools concurrently within a single step. */
  parallelCalls?: boolean
  /** Set `true` if the agent accepts and uses tools provided by the client at runtime. */
  clientProvided?: boolean
}
```

### Output

Output format support. Enable `structuredOutput` when your agent can return
responses conforming to a JSON schema, which is useful for programmatic
consumption.

```typescript theme={null}
interface OutputCapabilities {
  /** Set `true` if the agent can produce structured JSON output matching a provided schema. */
  structuredOutput?: boolean
  /** MIME types the agent can produce (e.g., `["text/plain", "application/json"]`).
   *  Omit if the agent only produces plain text. */
  supportedMimeTypes?: string[]
}
```

### State

State and memory management capabilities. These tell the client how the agent
handles shared state and whether conversation context persists across runs.

```typescript theme={null}
interface StateCapabilities {
  /** Set `true` if the agent emits `STATE_SNAPSHOT` events (full state replacement). */
  snapshots?: boolean
  /** Set `true` if the agent emits `STATE_DELTA` events (JSON Patch incremental updates). */
  deltas?: boolean
  /** Set `true` if the agent has long-term memory beyond the current thread
   *  (e.g., vector store, knowledge base, or cross-session recall). */
  memory?: boolean
  /** Set `true` if state is preserved across multiple runs within the same thread.
   *  When `false`, state resets on each run. */
  persistentState?: boolean
}
```

### Multi-Agent

Multi-agent coordination capabilities. Enable these when your agent can
orchestrate or hand off work to other agents.

```typescript theme={null}
interface MultiAgentCapabilities {
  /** Set `true` if the agent participates in any form of multi-agent coordination. */
  supported?: boolean
  /** Set `true` if the agent can delegate subtasks to other agents while retaining control. */
  delegation?: boolean
  /** Set `true` if the agent can transfer the conversation entirely to another agent. */
  handoffs?: boolean
  /** List of sub-agents this agent can invoke. Helps clients build agent selection UIs. */
  subagents?: Array<{ name: string; description?: string }>
}
```

### Reasoning

Reasoning and thinking capabilities. Enable these when your agent exposes its
internal thought process (e.g., chain-of-thought, extended thinking).

```typescript theme={null}
interface ReasoningCapabilities {
  /** Set `true` if the agent produces reasoning/thinking tokens visible to the client. */
  supported?: boolean
  /** Set `true` if reasoning tokens are streamed incrementally (vs. returned all at once). */
  streaming?: boolean
  /** Set `true` if reasoning content is encrypted (zero-data-retention mode).
   *  Clients should expect opaque `encryptedValue` fields instead of readable content. */
  encrypted?: boolean
}
```

### Multimodal

Multimodal input and output support, organized into `input` and `output`
sub-objects so clients can independently query what the agent accepts versus what
it produces. Clients use this to show/hide file upload buttons, audio recorders,
image pickers, etc.

```typescript theme={null}
interface MultimodalInputCapabilities {
  /** Set `true` if the agent can process image inputs (e.g., screenshots, photos). */
  image?: boolean
  /** Set `true` if the agent can process audio inputs (speech, recordings). */
  audio?: boolean
  /** Set `true` if the agent can process video inputs. */
  video?: boolean
  /** Set `true` if the agent can process PDF documents. */
  pdf?: boolean
  /** Set `true` if the agent can process arbitrary file uploads. */
  file?: boolean
}

interface MultimodalOutputCapabilities {
  /** Set `true` if the agent can generate images as part of its response. */
  image?: boolean
  /** Set `true` if the agent can produce audio output (text-to-speech, audio files). */
  audio?: boolean
}

interface MultimodalCapabilities {
  /** Modalities the agent can accept as input (images, audio, video, PDFs, files). */
  input?: MultimodalInputCapabilities
  /** Modalities the agent can produce as output (images, audio). */
  output?: MultimodalOutputCapabilities
}
```

### Execution

Execution control and limits. Declare these so clients can set expectations about
how long or how many steps an agent run might take.

```typescript theme={null}
interface ExecutionCapabilities {
  /** Set `true` if the agent can execute code (e.g., Python, JavaScript) during a run. */
  codeExecution?: boolean
  /** Set `true` if code execution happens in a sandboxed/isolated environment.
   *  Only meaningful when `codeExecution` is `true`. */
  sandboxed?: boolean
  /** Maximum number of tool-call/reasoning iterations the agent will perform per run.
   *  Helps clients display progress or set timeout expectations. */
  maxIterations?: number
  /** Maximum wall-clock time (in milliseconds) the agent will run before timing out. */
  maxExecutionTime?: number
}
```

### Human-in-the-Loop

Human-in-the-loop interaction support. Enable these when your agent can pause
execution to request human input, approval, or feedback before continuing.

```typescript theme={null}
interface HumanInTheLoopCapabilities {
  /** Set `true` if the agent supports any form of human-in-the-loop interaction. */
  supported?: boolean
  /** Set `true` if the agent can pause and request explicit approval before
   *  performing sensitive actions (e.g., sending emails, deleting data). */
  approvals?: boolean
  /** Set `true` if the agent allows humans to intervene and modify its plan mid-execution. */
  interventions?: boolean
  /** Set `true` if the agent can incorporate user feedback (thumbs up/down, corrections)
   *  to improve its behavior within the current session. */
  feedback?: boolean
  /** Set `true` if the agent participates in the AG-UI interrupt protocol (emits
   *  `RunFinished` with `outcome: { type: "interrupt", interrupts: [...] }`,
   *  accepts `RunAgentInput.resume`). */
  interrupts?: boolean
  /** Set `true` if tool-call interrupts accept `editedArgs` in the resume payload.
   *  Only meaningful when `interrupts` is `true`. */
  approveWithEdits?: boolean
}
```

> [!NOTE]
>
> See [Interrupts](/concepts/interrupts) for the full protocol specification.

## Implementing getCapabilities()

### Custom Agents

Implement `getCapabilities()` on your agent subclass, returning only the
capabilities you actually support:

```typescript theme={null}
import { AbstractAgent, AgentCapabilities } from "@ag-ui/client"

class MyAgent extends AbstractAgent {
  async getCapabilities(): Promise<AgentCapabilities> {
    return {
      identity: {
        name: "my-agent",
        description: "A custom agent with tool support",
        version: "1.0.0",
      },
      transport: {
        streaming: true,
      },
      tools: {
        supported: true,
        items: this.getRegisteredTools(),
        clientProvided: true,
      },
      state: {
        snapshots: true,
        deltas: true,
      },
    }
  }

  // ... run() implementation
}
```

### Dynamic Capabilities

Since `getCapabilities()` returns a live snapshot, it reflects the agent's
current state:

```typescript theme={null}
const agent = new MyAgent(config)

let caps = await agent.getCapabilities()
console.log(caps.tools?.items?.length) // 5

// Register more tools at runtime
agent.registerTool(newTool)

caps = await agent.getCapabilities()
console.log(caps.tools?.items?.length) // 6
```

## Client Usage Patterns

### Adaptive UI

Render UI components based on what the agent supports:

```typescript theme={null}
const capabilities = await agent.getCapabilities?.()

// Only show reasoning panel if supported
if (capabilities?.reasoning?.supported) {
  showReasoningPanel()
}

// Only show sub-agent selector if available
if (capabilities?.multiAgent?.subagents?.length) {
  showSubAgentSelector(capabilities.multiAgent.subagents)
}

// Only show approval UI if HITL is supported
if (capabilities?.humanInTheLoop?.approvals) {
  enableApprovalWorkflow()
}
```

### Feature Gating

Disable features the agent doesn't support instead of failing at runtime:

```typescript theme={null}
const capabilities = await agent.getCapabilities?.()

// Gate on an explicit declaration: an omitted field means undeclared, not unsupported.
const canUseStructuredOutput = capabilities?.output?.structuredOutput === true
const canStream = capabilities?.transport?.streaming === true
```

### Custom Capabilities

Access integration-specific capabilities via the `custom` field:

```typescript theme={null}
const capabilities = await agent.getCapabilities?.()

const rateLimit = capabilities?.custom?.rateLimit as
  | { maxRequestsPerMinute: number }
  | undefined

if (rateLimit) {
  configureThrottling(rateLimit.maxRequestsPerMinute)
}
```


# Events
Source: https://docs.ag-ui.com/concepts/events

Understanding events in the Agent User Interaction Protocol

# Events

The Agent User Interaction Protocol uses a streaming event-based architecture.
Events are the fundamental units of communication between agents and frontends,
enabling real-time, structured interaction.

## Event Types Overview

Events in the protocol are categorized by their purpose:

| Category | Description |
| - | - |
| Lifecycle Events | Monitor the progression of agent runs |
| Text Message Events | Handle streaming textual content |
| Tool Call Events | Manage tool executions by agents |
| State Management Events | Synchronize state between agents and UI |
| Activity Events | Represent ongoing activity progress |
| Subagent Events | Track subagents and attribute their output |
| Special Events | Support custom functionality |
| Draft Events | Proposed events under development |

## Base Event Properties

All events share a common set of base properties:

| Property | Description |
| - | - |
| `type` | The specific event type identifier |
| `timestamp` | Optional timestamp indicating when the event was created |
| `rawEvent` | Optional field containing the original event data if transformed |
| `metadata` | Optional extra information attached to the event |

### Metadata

`metadata` is an optional, open-by-key object for attaching extra information to
an event — token usage, a trace id, a finish reason. It is declared once on the
base event, so every event type carries it.

Consumers merge an event's metadata into the message that event builds, key by
key, with the last write winning. That is what lets a producer send token usage
on the final event of a message rather than having to know it up front.

See [Metadata](/concepts/metadata) for the full rules: the reserved `ag-ui` key,
which events do and do not merge, how tool calls carry their own, and how the
object behaves across transports.

Most events additionally accept an optional `subagentRunId`, identifying the
subagent that produced them. An event without it belongs to the parent agent.
See [Subagents](/concepts/subagents).

## Lifecycle Events

These events represent the lifecycle of an agent run. A typical agent run
follows a predictable pattern: it begins with a `RunStarted` event, may contain
multiple optional `StepStarted`/`StepFinished` pairs, and concludes with either
a `RunFinished` event (success) or a `RunError` event (failure).

Lifecycle events provide crucial structure to agent runs, enabling frontends to
track progress, manage UI states appropriately, and handle errors gracefully.
They create a consistent framework for understanding when operations begin and
end, making it possible to implement features like loading indicators, progress
tracking, and error recovery mechanisms.

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Client

    Note over Agent,Client: Run begins
    Agent->>Client: RunStarted

    opt Sending steps is optional
        Note over Agent,Client: Step execution
        Agent->>Client: StepStarted
        Agent->>Client: StepFinished
    end

    Note over Agent,Client: Run completes
    alt
        Agent->>Client: RunFinished
    else
        Agent->>Client: RunError
    end
```

The `RunStarted` and either `RunFinished` or `RunError` events are mandatory,
forming the boundaries of an agent run. Step events are optional and may occur
multiple times within a run, allowing for structured, observable progress
tracking.

### RunStarted

Signals the start of an agent run.

The `RunStarted` event is the first event emitted when an agent begins
processing a request. It establishes a new execution context identified by a
unique `runId`. This event serves as a marker for frontends to initialize UI
elements such as progress indicators or loading states. It also provides crucial
identifiers that can be used to associate subsequent events with this specific
run.

| Property | Description |
| - | - |
| `threadId` | ID of the conversation thread |
| `runId` | ID of the agent run |
| `parentRunId` | (Optional) Lineage pointer for branching/time travel. If present, refers to a prior run within the same thread, creating a git-like append-only log |
| `input` | (Optional) The exact agent input payload that was sent to the agent for this run. May omit messages already present in history; compactEvents() will normalize |

### RunFinished

Signals the end of an agent run. Every run terminates with either `RunFinished`
or `RunError`.

`RunFinished` has an optional `outcome` discriminated union:

* **omitted** — legacy producer that has not yet adopted the interrupt-aware
  lifecycle. Treated as a normal completion.
* `outcome: { type: "success" }` — the run completed normally. The optional
  `result` stays at the root of the event for back-compat.
* `outcome: { type: "interrupt", interrupts: [...] }` — the run paused for human
  input. The non-empty `interrupts` array lives inside the outcome variant. The
  client resumes by starting a new run whose `RunAgentInput` includes a `resume`
  array addressing every open interrupt.

> [!NOTE]
>
> For the full interrupt lifecycle — the `Interrupt` type, contract rules, error
> handling, reason taxonomy, and worked examples — see
> [Interrupts](/concepts/interrupts).

### RunError

Signals an error during an agent run.

The `RunError` event indicates that the agent encountered an error it could not
recover from, causing the run to terminate prematurely. This event provides
information about what went wrong, allowing frontends to display appropriate
error messages and potentially offer recovery options. After a `RunError` event,
no further processing will occur in this run.

| Property | Description |
| - | - |
| `message` | Error message |
| `code` | Optional error code |

### StepStarted

Signals the start of a step within an agent run.

The `StepStarted` event indicates that the agent is beginning a specific subtask
or phase of its processing. Steps provide granular visibility into the agent's
progress, enabling more precise tracking and feedback in the UI. Steps are
optional but highly recommended for complex operations that benefit from being
broken down into observable stages. The `stepName` could be the name of a node
or function that is currently executing.

| Property | Description |
| - | - |
| `stepName` | Name of the step |

### StepFinished

Signals the completion of a step within an agent run.

The `StepFinished` event indicates that the agent has completed a specific
subtask or phase. When paired with a corresponding `StepStarted` event, it
creates a bounded context for a discrete unit of work. Frontends can use these
events to update progress indicators, show completion animations, or reveal
results specific to that step. The `stepName` must match the corresponding
`StepStarted` event to properly pair the beginning and end of the step.

| Property | Description |
| - | - |
| `stepName` | Name of the step |

## Text Message Events

These events represent the lifecycle of text messages in a conversation. Text
message events follow a streaming pattern, where content is delivered
incrementally. A message begins with a `TextMessageStart` event, followed by one
or more `TextMessageContent` events that deliver chunks of text as they become
available, and concludes with a `TextMessageEnd` event.

This streaming approach enables real-time display of message content as it's
generated, creating a more responsive user experience compared to waiting for
the entire message to be complete before showing anything.

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Client

    Note over Agent,Client: Message begins
    Agent->>Client: TextMessageStart

    loop Content streaming
        Agent->>Client: TextMessageContent
    end

    Note over Agent,Client: Message completes
    Agent->>Client: TextMessageEnd
```

The `TextMessageContent` events each contain a `delta` field with a chunk of
text. Frontends should concatenate these deltas in the order received to
construct the complete message. The `messageId` property links all related
events, allowing the frontend to associate content chunks with the correct
message.

### TextMessageStart

Signals the start of a text message.

The `TextMessageStart` event initializes a new text message in the conversation.
It establishes a unique `messageId` that will be referenced by subsequent
content chunks and the end event. This event allows frontends to prepare the UI
for an incoming message, such as creating a new message bubble with a loading
indicator. The `role` property identifies whether the message is coming from the
assistant or potentially another participant in the conversation.

| Property | Description |
| - | - |
| `messageId` | Unique identifier for the message |
| `role` | Role of the message sender ("developer", "system", "assistant", "user", "tool") |

### TextMessageContent

Represents a chunk of content in a streaming text message.

The `TextMessageContent` event delivers incremental parts of the message text as
they become available. Each event contains a small chunk of text in the `delta`
property that should be appended to previously received chunks. The streaming
nature of these events enables real-time display of content, creating a more
responsive and engaging user experience. Implementations should handle these
events efficiently to ensure smooth text rendering without visible delays or
flickering.

| Property | Description |
| - | - |
| `messageId` | Matches the ID from `TextMessageStart` |
| `delta` | Text content chunk (non-empty) |

### TextMessageEnd

Signals the end of a text message.

The `TextMessageEnd` event marks the completion of a streaming text message.
After receiving this event, the frontend knows that the message is complete and
no further content will be added. This allows the UI to finalize rendering,
remove any loading indicators, and potentially trigger actions that should occur
after message completion, such as enabling reply controls or performing
automatic scrolling to ensure the full message is visible.

| Property | Description |
| - | - |
| `messageId` | Matches the ID from `TextMessageStart` |

### TextMessageChunk

Convenience event that expands to Start → Content → End automatically.

The `TextMessageChunk` event lets you omit explicit `TextMessageStart` and
`TextMessageEnd` events. The client stream transformer expands chunks into the
standard triad:

* First chunk for a message must include `messageId` and will emit
  `TextMessageStart` (role defaults to `assistant` when not provided).
* Each chunk with a `delta` emits a `TextMessageContent` for the current
  `messageId`.
* `TextMessageEnd` is emitted automatically when the stream switches to a new
  message ID or when the stream completes.

| Property | Description |
| - | - |
| `messageId` | Optional unique identifier for the message; required on the first chunk of a message |
| `role` | Optional role of the sender ("developer", "system", "assistant", "user") |
| `delta` | Optional text content of the message |

## Tool Call Events

These events represent the lifecycle of tool calls made by agents. Tool calls
follow a streaming pattern similar to text messages. When an agent needs to use
a tool, it emits a `ToolCallStart` event, followed by one or more `ToolCallArgs`
events that stream the arguments being passed to the tool, and concludes with a
`ToolCallEnd` event.

This streaming approach allows frontends to show tool executions in real-time,
making the agent's actions transparent and providing immediate feedback about
what tools are being invoked and with what parameters.

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Client

    Note over Agent,Client: Tool call begins
    Agent->>Client: ToolCallStart

    loop Arguments streaming
        Agent->>Client: ToolCallArgs
    end

    Note over Agent,Client: Tool call completes
    Agent->>Client: ToolCallEnd

    Note over Agent,Client: Tool execution result
    Agent->>Client: ToolCallResult
```

The `ToolCallArgs` events each contain a `delta` field with a chunk of the
arguments. Frontends should concatenate these deltas in the order received to
construct the complete arguments object. The `toolCallId` property links all
related events, allowing the frontend to associate argument chunks with the
correct tool call.

### ToolCallStart

Signals the start of a tool call.

The `ToolCallStart` event indicates that the agent is invoking a tool to perform
a specific function. This event provides the name of the tool being called and
establishes a unique `toolCallId` that will be referenced by subsequent events
in this tool call. Frontends can use this event to display tool usage to users,
such as showing a notification that a specific operation is in progress. The
optional `parentMessageId` allows linking the tool call to a specific message in
the conversation, providing context for why the tool is being used.

| Property | Description |
| - | - |
| `toolCallId` | Unique identifier for the tool call |
| `toolCallName` | Name of the tool being called |
| `parentMessageId` | Optional ID of the parent message |

### ToolCallArgs

Represents a chunk of argument data for a tool call.

The `ToolCallArgs` event delivers incremental parts of the tool's arguments as
they become available. Each event contains a segment of the argument data in the
`delta` property. These deltas are often JSON fragments that, when combined,
form the complete arguments object for the tool. Streaming the arguments is
particularly valuable for complex tool calls where constructing the full
arguments may take time. Frontends can progressively reveal these arguments to
users, providing insight into exactly what parameters are being passed to tools.

| Property | Description |
| - | - |
| `toolCallId` | Matches the ID from `ToolCallStart` |
| `delta` | Argument data chunk |

### ToolCallEnd

Signals the end of a tool call.

The `ToolCallEnd` event marks the completion of a tool call. After receiving
this event, the frontend knows that all arguments have been transmitted and the
tool execution is underway or completed. This allows the UI to finalize the tool
call display and prepare for potential results. In systems where tool execution
results are returned separately, this event indicates that the agent has
finished specifying the tool and its arguments, and is now waiting for or has
received the results.

| Property | Description |
| - | - |
| `toolCallId` | Matches the ID from `ToolCallStart` |

### ToolCallResult

Provides the result of a tool call execution.

The `ToolCallResult` event delivers the output or result from a tool that was
previously invoked by the agent. This event is sent after the tool has been
executed by the system and contains the actual output generated by the tool.
Unlike the streaming pattern of tool call specification (start, args, end), the
result is delivered as a complete unit since tool execution typically produces a
complete output. Frontends can use this event to display tool results to users,
append them to the conversation history, or trigger follow-up actions based on
the tool's output.

| Property | Description |
| - | - |
| `messageId` | ID of the conversation message this result belongs to |
| `toolCallId` | Matches the ID from the corresponding `ToolCallStart` event |
| `content` | The actual result/output content from the tool execution |
| `role` | Optional role identifier, typically "tool" for tool results |

### ToolCallChunk

Convenience event that expands to Start → Args → End automatically.

The `ToolCallChunk` event lets you omit explicit `ToolCallStart` and
`ToolCallEnd` events. The client stream transformer expands chunks into the
standard tool-call triad:

* First chunk for a tool call must include `toolCallId` and `toolCallName` and
  will emit `ToolCallStart` (propagating any `parentMessageId`).
* Each chunk with a `delta` emits a `ToolCallArgs` for the current `toolCallId`.
* `ToolCallEnd` is emitted automatically when the stream switches to a new
  `toolCallId` or when the stream completes.

| Property | Description |
| - | - |
| `toolCallId` | Optional on later chunks; required on the first chunk of a tool call |
| `toolCallName` | Optional on later chunks; required on the first chunk of a tool call |
| `parentMessageId` | Optional ID of the parent message |
| `delta` | Optional argument data chunk (often a JSON fragment) |

## State Management Events

These events are used to manage and synchronize the agent's state with the
frontend. State management in the protocol follows an efficient snapshot-delta
pattern where complete state snapshots are sent initially or infrequently, while
incremental updates (deltas) are used for ongoing changes.

This approach optimizes for both completeness and efficiency: snapshots ensure
the frontend has the full state context, while deltas minimize data transfer for
frequent updates. Together, they enable frontends to maintain an accurate
representation of agent state without unnecessary data transmission.

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Client

    Note over Agent,Client: Initial state transfer
    Agent->>Client: StateSnapshot

    Note over Agent,Client: Incremental updates
    loop State changes over time
        Agent->>Client: StateDelta
        Agent->>Client: StateDelta
    end

    Note over Agent,Client: Occasional full refresh
    Agent->>Client: StateSnapshot

    loop More incremental updates
        Agent->>Client: StateDelta
    end

    Note over Agent,Client: Message history update
    Agent->>Client: MessagesSnapshot
```

The combination of snapshots and deltas allows frontends to efficiently track
changes to agent state while ensuring consistency. Snapshots serve as
synchronization points that reset the state to a known baseline, while deltas
provide lightweight updates between snapshots.

### StateSnapshot

Provides a complete snapshot of an agent's state.

The `StateSnapshot` event delivers a comprehensive representation of the agent's
current state. This event is typically sent at the beginning of an interaction
or when synchronization is needed. It contains all state variables relevant to
the frontend, allowing it to completely rebuild its internal representation.
Frontends should replace their existing state model with the contents of this
snapshot rather than trying to merge it with previous state.

| Property | Description |
| - | - |
| `snapshot` | Complete state snapshot |

### StateDelta

Provides a partial update to an agent's state using JSON Patch.

The `StateDelta` event contains incremental updates to the agent's state in the
form of JSON Patch operations (as defined in RFC 6902). Each delta represents
specific changes to apply to the current state model. This approach is
bandwidth-efficient, sending only what has changed rather than the entire state.
Frontends should apply these patches in sequence to maintain an accurate state
representation. If a frontend detects inconsistencies after applying patches, it
may request a fresh `StateSnapshot`.

| Property | Description |
| - | - |
| `delta` | Array of JSON Patch operations (RFC 6902) |

### MessagesSnapshot

Provides a snapshot of all messages in a conversation.

The `MessagesSnapshot` event delivers a complete history of messages in the
current conversation. Unlike the general state snapshot, this focuses
specifically on the conversation transcript. This event is useful for
initializing the chat history, synchronizing after connection interruptions, or
providing a comprehensive view when a user joins an ongoing conversation.
Frontends should use this to establish or refresh the conversational context
displayed to users.

| Property | Description |
| - | - |
| `messages` | Array of message objects |

`activity` and `reasoning` messages are all-or-nothing inside a
`MessagesSnapshot`. If the snapshot carries any message of that role, it is the
complete set for that role: entries it repeats replace the client's copies, and
ones it leaves out are removed. If it carries none, the snapshot says nothing
about that role and the client keeps the messages it already has.

Both roles are client-side by default, so leaving them out is safe. Activity
messages never travel back to the agent — they are stripped from `RunAgentInput`
— and reasoning usually exists only as streamed `Reasoning` events. A backend
that tracks neither simply omits them from the snapshot, and nothing the client
holds is lost.

## Activity Events

Activity Events expose structured, in-progress activity updates that occur
between chat messages. They follow the same snapshot/delta pattern as the state
system so that UIs can render a complete activity view immediately and then
incrementally update it as new information arrives.

An activity message occupies the same id space as every other message, so its
`messageId` must not be reused by a text or reasoning message, and vice versa.
Those carry different shapes of `content` — a structured object for activity, a
string for text and reasoning — so a shared id has no coherent meaning. A client
that receives a text or reasoning message under an id an activity message
already holds should leave the activity message untouched rather than overwrite
it.

### ActivitySnapshot

Delivers a complete snapshot of an activity message.

| Property | Description |
| - | - |
| `messageId` | Identifier for the `ActivityMessage` this event updates |
| `activityType` | Activity discriminator (for example `"PLAN"`, `"SEARCH"`) |
| `content` | Structured JSON payload representing the full activity state |
| `replace` | Optional. Defaults to `true`. When `false`, ignore the snapshot if the message already exists |

Frontends should either create a new `ActivityMessage` or replace the existing
one with the payload supplied by the snapshot.

### ActivityDelta

Applies incremental updates to an existing activity using JSON Patch operations.

| Property | Description |
| - | - |
| `messageId` | Identifier for the target activity message |
| `activityType` | Activity discriminator (mirrors the value from the most recent snapshot) |
| `patch` | Array of RFC 6902 JSON Patch operations to apply to the activity data |

Activity deltas should be applied in order to the previously synchronized
activity content. If an application detects divergence, it can request or emit a
fresh `ActivitySnapshot` to resynchronize.

## Special Events

Special events provide flexibility in the protocol by allowing for
system-specific functionality and integration with external systems. These
events don't follow the standard lifecycle or streaming patterns of other event
types but instead serve specialized purposes.

### Raw

Used to pass through events from external systems.

The `Raw` event acts as a container for events originating from external systems
or sources that don't natively follow the Agent UI Protocol. This event type
enables interoperability with other event-based systems by wrapping their events
in a standardized format. The enclosed event data is preserved in its original
form inside the `event` property, while the optional `source` property
identifies the system it came from. Frontends can use this information to handle
external events appropriately, either by processing them directly or by
delegating them to system-specific handlers.

| Property | Description |
| - | - |
| `event` | Original event data |
| `source` | Optional source identifier |

### Custom

Used for application-specific custom events.

The `Custom` event provides an extension mechanism for implementing features not
covered by the standard event types. Unlike `Raw` events which act as
passthrough containers, `Custom` events are explicitly part of the protocol but
with application-defined semantics. The `name` property identifies the specific
custom event type, while the `value` property contains the associated data. This
mechanism allows for protocol extensions without requiring formal specification
changes. Teams should document their custom events to ensure consistent
implementation across frontends and agents.

| Property | Description |
| - | - |
| `name` | Name of the custom event |
| `value` | Value associated with the event |

## Reasoning Events

Reasoning events support LLM reasoning visibility and continuity, enabling
chain-of-thought reasoning while maintaining privacy. These events allow agents
to surface reasoning signals (e.g., summaries) and support encrypted reasoning
items for state carry-over across turns—especially under `store:false` or zero
data retention policies—without exposing raw chain-of-thought.

See
[OpenAI ZTR documentation](https://developers.openai.com/cookbook/examples/responses_api/reasoning_items/#encrypted-reasoning-items),
[OpenAI store parameter documentation](https://platform.openai.com/docs/api-reference/responses/create#responses_create-store),
and
[Gemini Thought Signatures](https://ai.google.dev/gemini-api/docs/thought-signatures)
for the underlying concept of encrypted reasoning items, which inspired this
design.

See [Reasoning](/concepts/reasoning) for comprehensive documentation including
privacy considerations, compliance guidance, and implementation examples.

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Client

    Note over Agent,Client: Reasoning begins
    Agent->>Client: ReasoningStart

    Note over Agent,Client: Stream reasoning content
    Agent->>Client: ReasoningMessageStart
    Agent->>Client: ReasoningMessageContent
    Agent->>Client: ReasoningMessageEnd

    Note over Agent,Client: Reasoning completes
    Agent->>Client: ReasoningEnd
```

### ReasoningStart

Marks the start of reasoning.

The `ReasoningStart` event signals that the agent is beginning a reasoning
process. It establishes a reasoning context identified by a unique `messageId`.

| Property | Description |
| - | - |
| `messageId` | Unique identifier of this reasoning |

### ReasoningMessageStart

Signals the start of a reasoning message.

The `ReasoningMessageStart` event begins a streaming reasoning message. This
message will contain the visible portion of the agent's reasoning that should be
displayed to users (e.g., a summary or partial chain-of-thought).

| Property | Description |
| - | - |
| `messageId` | Unique identifier of the message |
| `role` | Role of the reasoning message (`"reasoning"`) |

### ReasoningMessageContent

Represents a chunk of content in a streaming reasoning message.

The `ReasoningMessageContent` event delivers incremental reasoning content to
the client. Multiple content events with the same `messageId` should be
concatenated to form the complete visible reasoning.

| Property | Description |
| - | - |
| `messageId` | Matches ID from ReasoningMessageStart |
| `delta` | Reasoning content chunk (non-empty string) |

### ReasoningMessageEnd

Signals the end of a reasoning message.

The `ReasoningMessageEnd` event indicates that all content for the specified
reasoning message has been sent. Clients should finalize any UI representing
this reasoning message.

| Property | Description |
| - | - |
| `messageId` | Matches ID from ReasoningMessageStart |

### ReasoningMessageChunk

A convenience event to auto start/close reasoning messages.

The `ReasoningMessageChunk` event simplifies implementation by automatically
managing message lifecycle. The first chunk with a `messageId` implicitly starts
the message. An empty `delta` or the next non-reasoning event implicitly closes
the message.

| Property | Description |
| - | - |
| `messageId` | Message ID (first event must be non-empty) |
| `delta` | Reasoning content chunk (empty string closes the message) |

### ReasoningEnd

Marks the end of reasoning.

The `ReasoningEnd` event signals that the agent has completed its reasoning
process for the given context. No further reasoning events with the same
`messageId` should be expected after this event.

| Property | Description |
| - | - |
| `messageId` | Unique identifier of this reasoning |

### ReasoningEncryptedValue

Attaches encrypted chain-of-thought reasoning to a message or tool call.

The `ReasoningEncryptedValue` event carries encrypted reasoning content that
represents the LLM's internal chain-of-thought related to a specific entity.
This allows the agent to preserve reasoning state across conversation turns
without exposing the raw content to the client. The client stores and forwards
these encrypted values opaquely—only the agent (or authorized backend) can
decrypt them.

| Property | Description |
| - | - |
| `subtype` | Entity type: `"message"` or `"tool-call"` |
| `entityId` | ID of the message or tool call this reasoning belongs to |
| `encryptedValue` | Encrypted chain-of-thought content blob |

Use cases:

* **Message reasoning**: Attach encrypted reasoning to an `AssistantMessage` or
  `ReasoningMessage` to preserve context for follow-up turns
* **Tool call reasoning**: Attach encrypted reasoning to a tool call to capture
  why the agent chose specific arguments or how it interpreted results

## Subagent Events

Subagent events let an agent report that it has delegated work to a child agent,
so a frontend can tell which subagent produced which output. Without them, three
subagents streaming concurrently arrive as one undifferentiated stream.

Attribution is carried by an optional `subagentRunId` on most other events; these
three bracket the subagent's activity and give it a name to display.

`subagentRunId` identifies **one invocation**, not a reusable subagent
definition — running the same subagent twice yields two different values. See
[Subagents](/concepts/subagents) for the full model, including nesting,
concurrency, and the rules clients enforce.

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Client

    Note over Agent,Client: Subagent begins
    Agent->>Client: SubagentStarted

    Note over Agent,Client: Attributed output
    Agent->>Client: TextMessageStart / Content / End

    Note over Agent,Client: Subagent concludes
    alt Success
        Agent->>Client: SubagentFinished
    else Failure
        Agent->>Client: SubagentError
    end
```

### SubagentStarted

Announces a new subagent invocation.

| Property | Description |
| - | - |
| `subagentRunId` | Opaque identifier for this invocation |
| `name` | The subagent's declared name or type, for display |
| `description` | Optional human-readable description |
| `parentSubagentRunId` | Optional enclosing subagent, when subagents nest |
| `parentToolCallId` | Optional tool call that spawned this subagent |
| `parentMessageId` | Optional message that held that tool call |

### SubagentFinished

Marks a subagent invocation as complete.

| Property | Description |
| - | - |
| `subagentRunId` | Matches ID from SubagentStarted |
| `result` | Optional completion payload, mirroring `RunFinished.result` |
| `outcome` | Optional discriminated union: `{ type: "success" }` or `{ type: "suspended", interruptIds?: string[] }`. Omitted means success (the legacy reading). `suspended` says the subagent is checkpointed mid-flight awaiting outside input — the run then ends with an interrupt outcome, and `interruptIds` names the run-level interrupts whose answers resume this subagent. |

### SubagentError

Marks a subagent invocation as failed.

| Property | Description |
| - | - |
| `subagentRunId` | Matches ID from SubagentStarted |
| `message` | Human-readable error message |
| `code` | Optional error code |

> [!NOTE]
>
> `StateSnapshot` and `StateDelta` are attributable, but attribution on them is
> **provenance, not ownership**: it records which subagent produced the update.
> State stays run-scoped and an attributed snapshot or delta is applied to the
> run's one state document, exactly as an unattributed one is. There is no
> per-subagent state.

## Deprecated Events

> [!WARNING]
>
> The following events are deprecated and will be removed in version 1.0.0. Use
> the corresponding Reasoning events instead.

### Thinking Events (Deprecated)

The `THINKING_*` events have been replaced by `REASONING_*` events:

| Deprecated Event | 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` |

See [Reasoning Migration](/concepts/reasoning#migration-from-thinking-events)
for detailed migration guidance.

## Draft Events

These events are currently in draft status and may change before finalization.
They represent proposed extensions to the protocol that are under active
development and discussion.

### Meta Events

DRAFT

[View Proposal](/drafts/meta-events)

Meta events provide annotations and signals independent of agent runs, such as
user feedback or external system events.

#### MetaEvent

A side-band annotation event that can occur anywhere in the stream.

| Property | Description |
| - | - |
| `metaType` | Application-defined type (e.g., "thumbs\_up", "tag") |
| `payload` | Application-defined payload |

### Modified Lifecycle Events

DRAFT

[View Specification](/concepts/interrupts)

Extensions to existing lifecycle events to support interrupts and branching.

#### RunFinished (Extended)

The `RunFinished` event gains new fields to support interrupt-aware workflows.

| Property | Description |
| - | - |
| `outcome` | Optional discriminated union: `{ type: "success" }` or `{ type: "interrupt", interrupts: [...] }`. Omitted on legacy producers. |
| `result` | Optional. Free-form completion payload. Lives at the event root for back-compat with legacy producers; coexists with any outcome. |

See [Serialization](/concepts/serialization) for lineage and input capture.

#### RunStarted (Extended)

The `RunStarted` event gains new fields to support branching and input tracking.

| Property | Description |
| - | - |
| `parentRunId` | Optional: Parent run ID for branching/time travel |
| `input` | Optional: The exact agent input for this run |

## Event Flow Patterns

Events in the protocol typically follow specific patterns:

1. **Start-Content-End Pattern**: Used for streaming content (text messages,
   tool calls)
   * `Start` event initiates the stream
   * `Content` events deliver data chunks
   * `End` event signals completion

2. **Snapshot-Delta Pattern**: Used for state synchronization
   * `Snapshot` provides complete state
   * `Delta` events provide incremental updates

3. **Lifecycle Pattern**: Used for monitoring agent runs
   * `Started` events signal beginnings
   * `Finished`/`Error` events signal endings

## Implementation Considerations

When implementing event handlers:

* Events should be processed in the order they are received
* Events with the same ID (e.g., `messageId`, `toolCallId`) belong to the same
  logical stream
* Implementations should be resilient to out-of-order delivery
* Custom events should follow the established patterns for consistency


# Generative UI
Source: https://docs.ag-ui.com/concepts/generative-ui-specs

Understanding AG-UI's relationship with generative UI specifications

## **AG-UI and Generative UI Specs**

Several recently released specs have enabled agents to return generative UI, increasing the power and flexibility of the Agent\<->User conversation.

A2UI, MCP-UI, and Open-JSON-UI are all **generative UI specifications.** Generative UIs allow agents to respond to users not only with text but also with dynamic UI components.

| **Specification** | **Origin / Maintainer** | **Purpose** |
| - | - | - |
| **A2UI** | Google | A declarative, LLM-friendly Generative UI spec. JSONL-based and streaming, designed for platform-agnostic rendering. |
| **Open-JSON-UI** | OpenAI | An open standardization of OpenAI's internal declarative Generative UI schema. |
| **MCP-UI** | Microsoft + Shopify | A fully open, iframe-based Generative UI standard extending MCP for user-facing experiences. |

Despite the naming similarities, **AG-UI is not a generative UI specification** — it's a **User Interaction protocol** that provides the **bi-directional runtime connection** between the agent and the application.

AG-UI natively supports all of the above generative UI specs and allows developers to define **their own custom generative UI standards** as well.


# Interrupts
Source: https://docs.ag-ui.com/concepts/interrupts

Human-in-the-loop pauses and resumes in the Agent User Interaction Protocol

Agents sometimes need to pause: to get human approval before executing a
sensitive action, to request structured input, to wait on an out-of-band policy
decision. AG-UI exposes this as an **interrupt-aware run lifecycle** — a
terminal model where the run ends with an interrupt outcome, and the client
starts a new run carrying per-interrupt responses.

## Lifecycle

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant Client as Client App

  Note over Agent,Client: Run 1 begins
  Agent-->>Client: RunStarted (runId: r1)
  Agent-->>Client: ...ToolCall* / TextMessage* / StateSnapshot...
  Note over Agent,Client: Agent needs user input — emit snapshot, then interrupt
  Agent-->>Client: RunFinished { outcome: { type: "interrupt", interrupts: [...] } }

  Note over Agent,Client: User resolves interrupts
  Client-->>Agent: RunAgentInput { threadId, resume: [{interruptId, status, payload?}, ...] }

  Note over Agent,Client: Run 2 begins; resume[].interruptId links back to run 1's interrupts
  Agent-->>Client: RunStarted (runId: r2)
  Agent-->>Client: ...continue / ToolCallResult / ...
  Agent-->>Client: RunFinished { outcome: { type: "success" }, result }
```

## Run outcomes

`RunFinished` carries an optional `outcome` field — a discriminated union with
the variant-specific data nested inside:

* **omitted** — legacy/back-compat. Treated as a normal completion. Pre-existing
  AG-UI clients that did not yet know about interrupts still emit this shape,
  and new readers should accept it.
* `{ type: "success" }` — the run completed normally. The optional `result`
  stays at the root of the event for back-compat.
* `{ type: "interrupt", interrupts: [...] }` — the run paused for user input.
  `interrupts` is a non-empty array, and it lives inside the outcome so it
  travels with the variant that needs it.

```typescript theme={null}
type RunFinishedOutcome =
  | { type: "success" }
  | { type: "interrupt"; interrupts: Interrupt[] }

type RunFinishedEvent = {
  type: "RUN_FINISHED"
  threadId: string
  runId: string
  result?: unknown
  outcome?: RunFinishedOutcome
}
```

Because `outcome` is optional, an old producer that has never heard of
interrupts (no `outcome` field) still validates as a `RunFinished` event under
the new schema — clients only need to inspect `outcome` when they care about the
interrupt-aware variant.

## The Interrupt type

```typescript theme={null}
type Interrupt = {
  id: string
  reason: string
  message?: string
  toolCallId?: string
  responseSchema?: JsonSchema
  expiresAt?: string
  metadata?: Record<string, any>
  subagentRunId?: string
}
```

| Field | Purpose |
| - | - |
| `id` | Correlation key across interrupt, resume, idempotency, and audit. |
| `reason` | Categorical routing hint — see [Reason taxonomy](#reason-taxonomy). |
| `message` | Human-readable prompt. Universal fallback UI content. |
| `toolCallId` | Binds the interrupt to a prior `ToolCall*` sequence. |
| `responseSchema` | JSON Schema for the expected `resume.payload`. |
| `expiresAt` | Optional ISO-8601 TTL. Stale resumes produce `RunError`. |
| `metadata` | Free-form framework-specific data. |
| `subagentRunId` | The subagent whose work raised this interrupt — absent for a root-raised one. Attribution lives per interrupt because one run can carry interrupts from several subagents. A producer that emits the subagent lifecycle events also closes the subagent with `outcome: { type: "suspended" }` — lifecycle events remain optional, so attribution here is valid on its own (see [Subagents](/concepts/subagents#suspension)). |

## Resuming a run

The next `RunAgentInput` on the same thread carries a `resume` array:

```typescript theme={null}
type RunAgentInput = {
  // ... existing fields
  resume?: Array<{
    interruptId: string
    status: "resolved" | "cancelled"
    payload?: any
    metadata?: Record<string, any>
  }>
}
```

* `resolved` — the user responded. `payload` carries the response, validated
  against the interrupt's `responseSchema`. Denials are expressed inside the
  payload (for example, `{ approved: false }`), not as a separate status.
* `cancelled` — the user abandoned without providing meaningful input. `payload`
  should be omitted.
* `metadata` — optional envelope data about the response (for example a
  signature proving the human decision was not tampered with, or routing keys),
  as opposed to `payload`, which is the answer the agent asked for and will act
  on. Open by key; any JSON value is allowed under a key, including `null`. The
  object itself is either absent or an object, never `null`. The `ag-ui` key is
  reserved for AG-UI's own use. Allowed on either status.

## Contract rules

1. **Same thread.** Resume requests must use the same `threadId` as the
   interrupted run.
2. **Resume linkage.** `resume[].interruptId` must reference an `id` from the
   interrupted run's `interrupts[]`. `parentRunId` is orthogonal — it retains
   its existing AG-UI branching/time-travel semantics.
3. **Cover all open interrupts.** A single `resume` array must address every
   open interrupt from the interrupted run. Partial resumes are not supported.
4. **Pending interrupts block new input.** If a thread has unresolved
   interrupts, any `RunAgentInput` on that thread must include a `resume`
   addressing them. Agents receiving a non-conforming input must emit
   `RunError`.
5. **Idempotency.** A resume with the same
   `(threadId, interruptId, status, payload)` must be safe to replay.
6. **Payload validation.** If an interrupt declares a `responseSchema`, the
   agent may validate the corresponding resume `payload` and emit `RunError` on
   mismatch. Clients should validate before submitting.
7. **Expiry enforcement.** Clients must not submit a resume past an interrupt's
   `expiresAt`. Stale resumes produce `RunError`.
8. **Graceful handling.** Agents should handle missing or invalid resume
   payloads via `RunError`, not silent failures.

## State at the interrupt boundary

At the moment of interrupt, the agent must emit any state required for resume
via `StateSnapshot` and `MessagesSnapshot` events **before** the `RunFinished`
event that carries the interrupt.

This rule makes the protocol resume-mode-agnostic: both replay-style
continuations (rebuild context from messages + state) and checkpoint-style
continuations (restore a suspended coroutine) must produce identical observable
behavior on resume. Framework-native checkpointing is an implementation
optimization, not a protocol contract.

## Error handling

`RunError` is the sole error event. The `outcome` enum does not carry an
`"error"` value. Interrupt-specific error conditions that produce `RunError`:

* A resume arrives past an interrupt's `expiresAt`.
* A resume payload fails validation against its `responseSchema`.
* A resume references an `interruptId` the agent cannot correlate.
* A resume fails to address every open interrupt (violates rule 3).
* A `RunAgentInput` on a thread with pending interrupts omits `resume` (violates
  rule 4).

## Reason taxonomy

`reason` is a required string. A small set of core values is spec-defined; any
other string is a valid extension.

### Core values

| Value | Semantics | Typical companion fields |
| - | - | - |
| `tool_call` | Interrupt bound to a specific tool call awaiting decision. | `toolCallId` must be set. |
| `input_required` | Agent needs structured input to continue. | `responseSchema` should be set. |
| `confirmation` | Free-standing yes/no decision not bound to a tool. | `responseSchema` optional; boolean default. |

### Custom reasons

Any other string is valid. Agents should namespace custom reasons as
`<framework>:<name>` (for example, `langgraph:database_modification`,
`mastra:workflow_suspend`). The `core:` prefix is reserved for future spec
additions.

### Client routing

* Clients should switch on known core values for dedicated UI.
* For unknown reasons, clients must not error. Render from `message`,
  `responseSchema`, and `metadata`.

## Tool-bound interrupts

When an interrupt carries `reason: "tool_call"` and a `toolCallId`, the tool
call and its resolution span two runs. The full audit trail is:

1. `ToolCallArgs` from the interrupted run (the agent's proposal).
2. `RunAgentInput.resume` payload from the resumed run (user decision and
   edits).
3. `ToolCallResult` from the resumed run (actual execution outcome).

The agent does **not** re-emit `ToolCallStart`/`ToolCallArgs`/`ToolCallEnd` in
the resumed run — it emits `ToolCallResult` against the original `toolCallId`.

### Server-owned tool execution

A producer can mark a tool-bound interrupt with
`metadata: { "ag-ui:tool-execution": "server" }` to explicitly identify a
server-owned tool. Clients send the user's approval or rejection in `resume` and
must not synthesize a tool-result message from that decision. The server
provides the actual execution outcome against the original `toolCallId`. The
.NET adapter emits this marker for native tool approval requests.

Keep this metadata when persisting or restoring pending interrupts. Its absence
does not establish tool ownership; existing frontend completion contracts remain
unchanged. The marker describes execution ownership to clients and is not an
authorization credential: servers must still validate decisions and reject
client-supplied results for server-owned tools.

### Approve with edits

The recommended `responseSchema` pattern for tool-bound interrupts that support
approve-with-edits:

```json theme={null}
{
  "type": "object",
  "properties": {
    "approved": { "type": "boolean" },
    "editedArgs": {
      "type": "object",
      "description": "Full replacement of the tool args. Not merged."
    }
  },
  "required": ["approved"]
}
```

`editedArgs` is a full replacement, not a partial merge. Its presence in the
schema is the **capability signal** that the client may offer edit UI.

## Examples

### Minimal tool approval

The agent interrupts after proposing `sendEmail`:

```json theme={null}
{
  "type": "RUN_FINISHED",
  "threadId": "thread-1",
  "runId": "run-1",
  "outcome": {
    "type": "interrupt",
    "interrupts": [
      {
        "id": "int-abc123",
        "reason": "tool_call",
        "message": "Send email to a@b.com with subject 'Hi'?",
        "toolCallId": "tc-001",
        "responseSchema": {
          "type": "object",
          "properties": { "approved": { "type": "boolean" } },
          "required": ["approved"]
        }
      }
    ]
  }
}
```

The client submits the resume:

```json theme={null}
{
  "threadId": "thread-1",
  "runId": "run-2",
  "resume": [
    {
      "interruptId": "int-abc123",
      "status": "resolved",
      "payload": { "approved": true }
    }
  ]
}
```

The agent continues in `run-2`, emits `ToolCallResult` against `tc-001`, then
`RunFinished { outcome: { type: "success" } }`.

### Approve with edits (full audit)

```json theme={null}
{
  "type": "RUN_FINISHED",
  "threadId": "thread-2",
  "runId": "run-10",
  "outcome": {
    "type": "interrupt",
    "interrupts": [
      {
        "id": "int-email-edit",
        "reason": "tool_call",
        "message": "Send email to a@b.com? You can edit the body before approving.",
        "toolCallId": "tc-42",
        "responseSchema": {
          "type": "object",
          "properties": {
            "approved": { "type": "boolean" },
            "editedArgs": {
              "type": "object",
              "properties": {
                "to": { "type": "string", "format": "email" },
                "subject": { "type": "string" },
                "body": { "type": "string" }
              }
            }
          },
          "required": ["approved"]
        },
        "metadata": {
          "langgraph": {
            "checkpointId": "ckpt-xyz",
            "nodeId": "tool_executor"
          }
        }
      }
    ]
  }
}
```

Client resume with edits:

```json theme={null}
{
  "threadId": "thread-2",
  "runId": "run-11",
  "resume": [
    {
      "interruptId": "int-email-edit",
      "status": "resolved",
      "payload": {
        "approved": true,
        "editedArgs": {
          "to": "a@b.com",
          "subject": "Hi",
          "body": "Hi (revised per my note)"
        }
      }
    }
  ]
}
```

Audit trail for `tc-42`:

* `run-10` `ToolCallArgs` — original proposal.
* `run-11` `RunAgentInput.resume[0].payload.editedArgs` — user edits.
* `run-11` `ToolCallResult` — actual outcome.

### Parallel interrupts

```json theme={null}
{
  "type": "RUN_FINISHED",
  "threadId": "thread-3",
  "runId": "run-20",
  "outcome": {
    "type": "interrupt",
    "interrupts": [
      {
        "id": "i-1",
        "reason": "tool_call",
        "toolCallId": "tc-a",
        "message": "Approve sendEmail to x@y.com?"
      },
      {
        "id": "i-2",
        "reason": "tool_call",
        "toolCallId": "tc-b",
        "message": "Approve sendEmail to y@z.com?"
      },
      {
        "id": "i-3",
        "reason": "tool_call",
        "toolCallId": "tc-c",
        "message": "Approve sendEmail to z@w.com?"
      }
    ]
  }
}
```

Client approves two, cancels one:

```json theme={null}
{
  "threadId": "thread-3",
  "runId": "run-21",
  "resume": [
    {
      "interruptId": "i-1",
      "status": "resolved",
      "payload": { "approved": true }
    },
    {
      "interruptId": "i-2",
      "status": "resolved",
      "payload": { "approved": true }
    },
    { "interruptId": "i-3", "status": "cancelled" }
  ]
}
```

In `run-21` the agent emits `ToolCallResult` for `tc-a` and `tc-b` and treats
`tc-c` as not-executed.

### Non-tool input request

```json theme={null}
{
  "type": "RUN_FINISHED",
  "threadId": "thread-4",
  "runId": "run-30",
  "outcome": {
    "type": "interrupt",
    "interrupts": [
      {
        "id": "int-form",
        "reason": "input_required",
        "message": "Please provide the quarterly filing details.",
        "responseSchema": {
          "type": "object",
          "properties": {
            "quarter": { "type": "string", "enum": ["Q1", "Q2", "Q3", "Q4"] },
            "year": { "type": "integer", "minimum": 2000 },
            "revenue": { "type": "number" }
          },
          "required": ["quarter", "year", "revenue"]
        },
        "expiresAt": "2026-04-20T17:00:00Z"
      }
    ]
  }
}
```

Client response:

```json theme={null}
{
  "threadId": "thread-4",
  "runId": "run-31",
  "resume": [
    {
      "interruptId": "int-form",
      "status": "resolved",
      "payload": { "quarter": "Q1", "year": 2026, "revenue": 4200000 }
    }
  ]
}
```

## Framework integrations

| Framework | Package | Interrupt support |
| - | - | - |
| LangGraph | `@ag-ui/langgraph` / `ag-ui-langgraph` | ✅ Accepts `RunAgentInput.resume[]`. Can emit `RunFinishedEvent.outcome = {type:"interrupt"}` — opt-in via `emitInterruptOutcome` / `emit_interrupt_outcome` (default off; legacy clients that resume via `command.resume` stop resuming once they see the structured outcome). Legacy `CustomEvent(name="on_interrupt")` emitted by default; disable via `enableLegacyOnInterruptEvent: false`. Subclass hooks available for custom HITL translation. |
| AWS Strands | `@ag-ui/aws-strands` | ✅ Forwards native Strands interrupts via `RunFinishedEvent.outcome`. |

## Related

* [Events](/concepts/events) — how `RunFinished` fits into the broader event
  stream.
* [Capabilities](/concepts/capabilities) — the `humanInTheLoop.interrupts` and
  `humanInTheLoop.approveWithEdits` flags agents declare.


# Messages
Source: https://docs.ag-ui.com/concepts/messages

Understanding message structure and communication in AG-UI

# Messages

Messages form the backbone of communication in the AG-UI protocol. They
represent the conversation history between users and AI agents, and provide a
standardized way to exchange information regardless of the underlying AI service
being used.

## Message Structure

AG-UI messages follow a vendor-neutral format, ensuring compatibility across
different AI providers while maintaining a consistent structure. This allows
applications to switch between AI services (like OpenAI, Anthropic, or custom
models) without changing the client-side implementation.

The basic message structure includes:

```typescript theme={null}
interface BaseMessage {
  id: string // Unique identifier for the message
  role: string // The role of the sender (user, assistant, system, tool, reasoning)
  content?: string // Optional text content of the message
  name?: string // Optional name of the sender
  encryptedContent?: string // Optional encrypted content for privacy-preserving state continuity
  metadata?: Record<string, any> // Optional extra information attached to the message
}
```

The `role` discriminator can be `"user"`, `"assistant"`, `"system"`, `"tool"`,
`"developer"`, `"activity"`, or `"reasoning"`. Concrete message types extend
this shape with the fields they need.

Every message type carries `metadata`, an optional open-by-key object that
accumulates as the message is built from its events. Tool calls carry one of
their own. See [Metadata](/concepts/metadata) for the rules.

> The `encryptedContent` field enables privacy-preserving workflows where
> sensitive content (such as reasoning chains) can be passed across turns
> without exposing the raw content. This is particularly useful for zero data
> retention (ZDR) compliance and `store:false` scenarios.

## Message Types

AG-UI supports several message types to accommodate different participants in a
conversation:

### User Messages

Messages from the end user to the agent:

```typescript theme={null}
interface UserMessage {
  id: string
  role: "user"
  content: string | ContentPart[] // Text or multimodal input from the user
  name?: string // Optional user identifier
}

type ContentPart =
  | TextPart
  | ImagePart
  | AudioPart
  | VideoPart
  | DocumentPart

interface DataSource {
  type: "data"
  value: string
  mimeType: string
}

interface UrlSource {
  type: "url"
  value: string
  mimeType?: string
}

interface FileSource {
  type: "file"
  value: string // a handle the provider issued; opaque, never fetched
  provider?: string // who issued it, e.g. "openai"
  mimeType?: string
}

type PartSource = DataSource | UrlSource | FileSource

interface TextPart {
  type: "text"
  text: string
}

interface ImagePart {
  type: "image"
  source: PartSource
  metadata?: Record<string, unknown>
}

interface AudioPart {
  type: "audio"
  source: PartSource
  metadata?: Record<string, unknown>
}

interface VideoPart {
  type: "video"
  source: PartSource
  metadata?: Record<string, unknown>
}

interface DocumentPart {
  type: "document"
  source: PartSource
  metadata?: Record<string, unknown>
}
```

> In Python, the previous `BinaryInputContent` model is deprecated and remains
> temporarily available as a compatibility path.

This structure keeps traditional plain-text inputs working while enabling richer
payloads such as images, audio clips, or uploaded files in the same message.

### Assistant Messages

Messages from the AI assistant to the user:

```typescript theme={null}
interface AssistantMessage {
  id: string
  role: "assistant"
  content?: string // Text response from the assistant (optional if using tool calls)
  name?: string // Optional assistant identifier
  toolCalls?: ToolCall[] // Optional tool calls made by the assistant
  encryptedContent?: string // Optional encrypted content for state continuity
}
```

### System Messages

Instructions or context provided to the agent:

```typescript theme={null}
interface SystemMessage {
  id: string
  role: "system"
  content: string // Instructions or context for the agent
  name?: string // Optional identifier
}
```

### Tool Messages

Results from tool executions:

```typescript theme={null}
interface ToolMessage {
  id: string
  role: "tool"
  content: string // Result from the tool execution
  toolCallId: string // ID of the tool call this message responds to
  error?: string // Optional error message if the tool execution failed
  encryptedValue?: string // Optional encrypted reasoning for state continuity
}
```

Key points:

* The `toolCallId` links the result back to the original tool call
* Use `error` to indicate tool execution failures
* Use `encryptedValue` to attach encrypted chain-of-thought related to how the
  agent interpreted or processed the tool result

### Activity Messages

Structured UI messages that exist only on the frontend.  Used for progress,
status, or any custom visual element that shouldn’t be sent to the model:

```typescript theme={null}
interface ActivityMessage {
  id: string
  role: "activity"
  activityType: string // e.g. "PLAN", "SEARCH", "SCRAPE"
  content: Record<string, any> // Structured payload rendered by the frontend
}
```

Key points

* Emitted via `ACTIVITY_SNAPSHOT` and `ACTIVITY_DELTA` to support live,
  updateable UI (checklists, steps, search-in-progress, etc.).
* **Frontend-only:** never forwarded to the agent, so no filtering and no LLM
  confusion.
* **Customizable:** define your own `activityType` and `content` and render a
  matching UI component.
* **Streamable:** can be updated over time for long-running operations.
* Helps persist/restore custom events by turning them into durable message
  objects.

### Developer Messages

Internal messages used for development or debugging:

```typescript theme={null}
interface DeveloperMessage {
  id: string
  role: "developer"
  content: string
  name?: string
}
```

### Reasoning Messages

Messages representing the agent's internal reasoning or chain-of-thought
process:

```typescript theme={null}
interface ReasoningMessage {
  id: string
  role: "reasoning"
  content: string // Reasoning content (visible to client)
  encryptedValue?: string // Optional encrypted reasoning for state continuity
}
```

> [!TIP]
>
> Unlike Activity messages, Reasoning messages are intended to represent the
> agent's internal thought process and may be encrypted for privacy and are
> meant to be sent back to the agent for further processing on subsequent turns.

Key points:

* Emitted via `REASONING_MESSAGE_START`, `REASONING_MESSAGE_CONTENT`, and
  `REASONING_MESSAGE_END` events.
* **Visibility control:** Content may be visible to users (as a summary) or
  fully encrypted.
* **Encrypted values:** Use `REASONING_ENCRYPTED_VALUE` events to attach
  encrypted chain-of-thought to messages or tool calls without exposing content.
* **State continuity:** Encrypted reasoning items can be passed across
  conversation turns without exposing raw chain-of-thought.
* **Privacy-first:** Supports `store:false` and zero data retention (ZDR)
  policies while preserving reasoning capabilities.
* **Separate from assistant messages:** Reasoning is kept distinct from final
  responses to avoid polluting the conversation history.

See [Reasoning Events](/concepts/events#reasoning-events) for the streaming
event lifecycle.

## Vendor Neutrality

AG-UI messages are designed to be vendor-neutral, meaning they can be easily
mapped to and from proprietary formats used by various AI providers:

```typescript theme={null}
// Example: Converting AG-UI messages to OpenAI format
const openaiMessages = agUiMessages
  .filter((msg) => ["user", "system", "assistant"].includes(msg.role))
  .map((msg) => ({
    role: msg.role as "user" | "system" | "assistant",
    content: msg.content || "",
    // Map tool calls if present
    ...(msg.role === "assistant" && msg.toolCalls
      ? {
          tool_calls: msg.toolCalls.map((tc) => ({
            id: tc.id,
            type: tc.type,
            function: {
              name: tc.function.name,
              arguments: tc.function.arguments,
            },
          })),
        }
      : {}),
  }))
```

This abstraction allows AG-UI to serve as a common interface regardless of the
underlying AI service.

## Message Synchronization

Messages can be synchronized between client and server through two primary
mechanisms:

### Complete Snapshots

The `MESSAGES_SNAPSHOT` event provides a complete view of all messages in a
conversation:

```typescript theme={null}
interface MessagesSnapshotEvent {
  type: EventType.MESSAGES_SNAPSHOT
  messages: Message[] // Complete array of all messages
}
```

This is typically used:

* When initializing a conversation
* After connection interruptions
* When major state changes occur
* To ensure client-server synchronization

### Streaming Messages

For real-time interactions, new messages can be streamed as they're generated:

1. **Start a message**: Indicate a new message is being created

   ```typescript theme={null}
   interface TextMessageStartEvent {
     type: EventType.TEXT_MESSAGE_START
     messageId: string
     role: string
   }
   ```

2. **Stream content**: Send content chunks as they become available

   ```typescript theme={null}
   interface TextMessageContentEvent {
     type: EventType.TEXT_MESSAGE_CONTENT
     messageId: string
     delta: string // Text chunk to append
   }
   ```

3. **End a message**: Signal the message is complete
   ```typescript theme={null}
   interface TextMessageEndEvent {
     type: EventType.TEXT_MESSAGE_END
     messageId: string
   }
   ```

This streaming approach provides a responsive user experience with immediate
feedback.

## Tool Integration in Messages

AG-UI messages elegantly integrate tool usage, allowing agents to perform
actions and process their results:

### Tool Calls

Tool calls are embedded within assistant messages:

```typescript theme={null}
interface ToolCall {
  id: string // Unique ID for this tool call
  type: "function" // Type of tool call
  function: {
    name: string // Name of the function to call
    arguments: string // JSON-encoded string of arguments
  }
}
```

Example assistant message with tool calls:

```typescript theme={null}
{
  id: "msg_123",
  role: "assistant",
  content: "I'll help you with that calculation.",
  toolCalls: [
    {
      id: "call_456",
      type: "function",
      function: {
        name: "calculate",
        arguments: '{"expression": "24 * 7"}'
      }
    }
  ]
}
```

### Tool Results

Results from tool executions are represented as tool messages:

```typescript theme={null}
{
  id: "result_789",
  role: "tool",
  content: "168",
  toolCallId: "call_456" // References the original tool call
}
```

This creates a clear chain of tool usage:

1. Assistant requests a tool call
2. Tool executes and returns a result
3. Assistant can reference and respond to the result

## Streaming Tool Calls

Similar to text messages, tool calls can be streamed to provide real-time
visibility into the agent's actions:

1. **Start a tool call**:

   ```typescript theme={null}
   interface ToolCallStartEvent {
     type: EventType.TOOL_CALL_START
     toolCallId: string
     toolCallName: string
     parentMessageId?: string // Optional link to parent message
   }
   ```

2. **Stream arguments**:

   ```typescript theme={null}
   interface ToolCallArgsEvent {
     type: EventType.TOOL_CALL_ARGS
     toolCallId: string
     delta: string // JSON fragment to append to arguments
   }
   ```

3. **End a tool call**:
   ```typescript theme={null}
   interface ToolCallEndEvent {
     type: EventType.TOOL_CALL_END
     toolCallId: string
   }
   ```

This allows frontends to show tools being invoked progressively as the agent
constructs its reasoning.

## Practical Example

Here's a complete example of a conversation with tool usage:

```typescript theme={null}
// Conversation history
;[
  // User query
  {
    id: "msg_1",
    role: "user",
    content: "What's the weather in New York?",
  },

  // Assistant response with tool call
  {
    id: "msg_2",
    role: "assistant",
    content: "Let me check the weather for you.",
    toolCalls: [
      {
        id: "call_1",
        type: "function",
        function: {
          name: "get_weather",
          arguments: '{"location": "New York", "unit": "celsius"}',
        },
      },
    ],
  },

  // Tool result
  {
    id: "result_1",
    role: "tool",
    content:
      '{"temperature": 22, "condition": "Partly Cloudy", "humidity": 65}',
    toolCallId: "call_1",
  },

  // Assistant's final response using tool results
  {
    id: "msg_3",
    role: "assistant",
    content:
      "The weather in New York is partly cloudy with a temperature of 22°C and 65% humidity.",
  },
]
```

## Conclusion

The message structure in AG-UI enables sophisticated conversational AI
experiences while maintaining vendor neutrality. By standardizing how messages
are represented, synchronized, and streamed, AG-UI provides a consistent way to
implement interactive human-agent communication regardless of the underlying AI
service.

This system supports everything from simple text exchanges to complex tool-based
workflows, all while optimizing for both real-time responsiveness and efficient
data transfer.


# Metadata
Source: https://docs.ag-ui.com/concepts/metadata

Attaching extra information to events, messages and tool calls

Metadata is the sanctioned way to attach extra information to the protocol —
token usage, a trace id, a finish reason, anything your application needs to
carry alongside the conversation.

Before it existed, producers hung undeclared properties off events and hoped
consumers passed them through. That is why unknown properties reaching
subscribers is removed in 1.0: metadata replaces it with something declared and
typed that consumers are required to carry.

## Where it lives

Four places, all optional:

| Carries `metadata` | Notes |
| - | - |
| Every event | Declared once on the base event, so all event types have it |
| Every message | All seven roles: developer, system, assistant, user, tool, activity, reasoning |
| Every tool call | A tool call is not a message — see [Tool calls](#tool-calls) |
| Every resume entry | A request field, so nothing merges into it — see [Resume entries](#resume-entries) |

## Shape

The object is **open by key**. Any JSON value is allowed under a key, including
`null`. There is no schema for what you put in it.

```typescript theme={null}
{
  type: EventType.TEXT_MESSAGE_END,
  messageId: "msg_123",
  metadata: {
    "ag-ui": { usage: { input: 1200, output: 340 } },
    finishReason: "stop",
    traceId: "abc-123",
    retries: 0,
    labels: ["experimental"]
  }
}
```

The object itself is either **absent or an object — never `null`**. An empty
object is valid and means "nothing to say", which is the same as omitting it.

> [!NOTE]
>
> Producers never emit `"metadata": null`: an optional field with no value is
> omitted from the JSON entirely, in every official SDK. The TypeScript client
> enforces this and rejects a `null` metadata object — unlike some older
> optional fields, metadata has no legacy producers to tolerate. Note the
> asymmetry: a `null` **value under a key** is meaningful data and is always
> preserved. Only a `null` standing in for the whole object is invalid.

## The reserved key

The `ag-ui` key is reserved for AG-UI's own use. Every other key is yours.

Nothing rejects a write to `ag-ui` at runtime — enforcing it would contradict
the open-by-key rule — but treat it as off limits, since AG-UI may put its own
values there in future versions.

## Merging into messages

A message is assembled from a sequence of events, and the interesting values are
only known at the end: a provider does not know its token usage until it has
finished generating. So consumers **merge each event's metadata into the message
that event builds**, as the sequence arrives.

This describes clients that assemble messages from the stream, such as the
TypeScript client. The .NET client does not assemble AG-UI messages — see the
SDK notes below.

The rule is last write wins, key by key:

```typescript theme={null}
// TEXT_MESSAGE_START    metadata: { source: "openai", stage: "start" }
// TEXT_MESSAGE_CONTENT  metadata: { stage: "content" }
// TEXT_MESSAGE_END      metadata: { stage: "end", usage: { output: 340 } }

message.metadata
// { source: "openai", stage: "end", usage: { output: 340 } }
```

`source` survived because nothing later set it. `stage` ended on the last value
written. `usage` arrived only at the end, which is the whole point.

### Values are replaced, never blended

Merging never recurses. A key holding an array or an object is replaced whole:

```typescript theme={null}
// earlier: { tags: ["a", "b", "c"] }
// later:   { tags: ["z"] }
// result:  { tags: ["z"] }        not ["a", "b", "c", "z"]
```

This holds under `ag-ui` too. If you need to add to a nested structure, send the
complete new value.

### What does not merge

Metadata on an event that does not build a message stays on that event and never
reaches one:

* `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`
* `STEP_STARTED`, `STEP_FINISHED`
* `STATE_SNAPSHOT`, `STATE_DELTA`
* `RAW`, `CUSTOM`
* `REASONING_START`, `REASONING_END`, `REASONING_ENCRYPTED_VALUE`

`MESSAGES_SNAPSHOT` is a special case: the messages inside it carry their own
metadata and arrive with it already attached, so the event's own metadata is not
merged into any of them.

> [!TIP]
>
> Putting run-level totals on `RUN_FINISHED` is fine and often right — just read
> them from the event rather than expecting them on a message. If you want them
> on a specific message, send them on that message's `*_END` event.

## Tool calls

Tool call events — `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END` — merge
into the **tool call**, not into the assistant message that owns it.

```typescript theme={null}
assistantMessage.toolCalls[0].metadata
// { provider: "anthropic", latencyMs: 84 }
```

The reason is that several tool calls can share one parent assistant message.
Folding all of their metadata into that parent would make the result depend on
the order the calls happened to interleave — and stream transforms are allowed
to change that order. Giving each tool call its own metadata removes the shared
destination, so the outcome is the same however the stream is processed.

`TOOL_CALL_RESULT` is different: it creates a tool message, so its metadata
merges into that message like any other message-building event.

## Resume entries

Each entry in `RunAgentInput.resume` — the per-interrupt response a client sends
back after a run finished with an interrupt outcome — carries its own metadata.
It holds envelope data about the response, such as a signature proving the human
decision was not tampered with, or routing keys; the answer the agent asked for
belongs in `payload`.

A resume entry is a request field, not something assembled from a stream, so
there are **no merge semantics** — nothing accumulates into it. See
[Interrupts](/concepts/interrupts#resuming-a-run) for the full resume contract.

## Transports

Over JSON — which is what SSE carries, and what every SDK reads and writes —
metadata is a plain object, and every value shape round-trips exactly: nulls,
arrays, nested objects, strings and numbers.

The binary protobuf format carries it as a `google.protobuf.Struct`, whose value
type has a real null case, so a `null` under a key is preserved rather than
approximated and an absent object stays distinguishable from an empty one. Two
caveats apply there, and neither is specific to metadata:

* **Not every event has a protobuf representation.** The wire format covers a
  subset of the event types — the tool result, activity, reasoning and
  deprecated thinking events have no protobuf message, so they cannot cross that
  transport at all, with or without metadata. The .NET encoder rejects them
  outright; the TypeScript encoder produces an empty payload that decoding then
  rejects. Either way the event does not arrive, so do not rely on the binary
  transport for those events.
* **Numbers are IEEE-754 doubles.** `google.protobuf.Value` models every number
  as a double, so integers beyond 2^53 lose precision on the round trip. This is
  a property of the format and applies to `state` and every other dynamic
  payload equally.

Byte-for-byte output is not guaranteed between encoders: `Struct` is a
`map<string, Value>`, and protobuf map entry ordering is not canonical. What is
guaranteed is that both sides decode to the same value. In practice the
TypeScript and .NET encoders do emit identical bytes for every fixture in the
cross-language suite, which is asserted there, but do not depend on it.

## SDK reference

> [!NOTE]
>
> Metadata is open by key in every SDK, so the type is deliberately permissive.
> It is your responsibility to keep the contents JSON-serializable — a function
> or a `bigint` will be accepted at the type level and then fail when encoded.

**TypeScript** — `metadata?: Record<string, any>` on events, messages, tool
calls and resume entries. `mergeMetadata(existing, incoming)` is exported from
`@ag-ui/core` if you are assembling messages yourself, along with
`AGUI_METADATA_KEY` for the reserved key.

**Python** — `metadata: Optional[Dict[str, Any]]`. The base model omits any
unset optional field on every serialization path, so an absent object is omitted
rather than emitted as `null` — no `exclude_none=True` needed. `Metadata` and
`AGUI_METADATA_KEY` are exported from `ag_ui.core`.

**.NET** — `JsonElement? Metadata` on `BaseEvent`, `AGUIMessage`, `AGUIToolCall`
and `AGUIResume`, with `AGUIMetadata.ReservedKey` for the reserved key.

It is a **wire-level field**. It round-trips faithfully through JSON and
protobuf, so a server reading `RunAgentInput` or a client decoding the stream
sees it intact, and `AGUIMessage.Metadata` carries it on messages inside a
`MESSAGES_SNAPSHOT`. It is deliberately not surfaced on
`Microsoft.Extensions.AI`'s `ChatMessage`, matching how `encryptedValue` and
`AGUIToolMessage.Error` already behave.

If you consume the stream through `AGUIChatClient`, note what that means in
practice: `EventStreamConverter` emits no `ChatResponseUpdate` for
`TEXT_MESSAGE_START`, `TEXT_MESSAGE_END`, `TOOL_CALL_START` or `TOOL_CALL_ARGS`,
so metadata on those events — including usage placed on `TEXT_MESSAGE_END` as
recommended above — does not reach a `RawRepresentation` either. Read it from
the raw event stream rather than from the high-level chat client.

## Compaction

`compactEvents` in the TypeScript client squashes a run of streaming events into
fewer events for storage or replay, deliberately reordering them so each
stream's events stay together.

Metadata adds no new order sensitivity of its own: every merge destination is
unique — each message has its own, and each tool call carries its own rather
than folding into a parent it may share — so two events that merge into the same
target are never reordered relative to each other.

Compaction's reordering is not semantics-preserving in general, though, and that
predates metadata. An event that interrupts a stream is emitted after it, so a
`MESSAGES_SNAPSHOT` arriving mid-message is replayed after that message's own
events and overwrites what they produced — the appended content just as much as
the merged metadata. If you rely on exact replay equivalence, avoid interleaving
snapshots with an open stream.


# Middleware
Source: https://docs.ag-ui.com/concepts/middleware

Transform and intercept events in AG-UI agents

# Middleware

Middleware in AG-UI provides a powerful way to transform, filter, and augment the event streams that flow through agents. It enables you to add cross-cutting concerns like logging, authentication, rate limiting, and event filtering without modifying the core agent logic.

Examples below assume the relevant RxJS operators/utilities (`map`, `tap`, `catchError`, `switchMap`, `timer`, etc.) are imported.

## What is Middleware?

Middleware sits between the agent execution and the event consumer, allowing you to:

1. **Transform events** – Modify or enhance events as they flow through the pipeline
2. **Filter events** – Selectively allow or block certain events
3. **Add metadata** – Inject additional context or tracking information
4. **Handle errors** – Implement custom error recovery strategies
5. **Monitor execution** – Add logging, metrics, or debugging capabilities

## How Middleware Works

Middleware forms a chain where each middleware wraps the next, creating layers of functionality. When an agent runs, the event stream flows through each middleware in sequence.

```typescript theme={null}
import { AbstractAgent } from "@ag-ui/client"

const agent = new MyAgent()

// Middleware chain: logging -> auth -> filter -> agent
agent.use(loggingMiddleware, authMiddleware, filterMiddleware)

// When agent runs, events flow through all middleware
await agent.runAgent()
```

Middleware added with `agent.use(...)` is applied in `runAgent()`. `connectAgent()` currently calls `connect()` directly and does not run middleware.

## Function-Based Middleware

For simple transformations, you can use function-based middleware. This is the most concise way to add middleware:

```typescript theme={null}
import { MiddlewareFunction } from "@ag-ui/client"
import { EventType } from "@ag-ui/core"

const prefixMiddleware: MiddlewareFunction = (input, next) => {
  return next.run(input).pipe(
    map(event => {
      if (
        event.type === EventType.TEXT_MESSAGE_CHUNK ||
        event.type === EventType.TEXT_MESSAGE_CONTENT
      ) {
        return {
          ...event,
          delta: `[AI]: ${event.delta}`
        }
      }
      return event
    })
  )
}

agent.use(prefixMiddleware)
```

## Class-Based Middleware

For more complex scenarios requiring state or configuration, use class-based middleware:

```typescript theme={null}
import { Middleware } from "@ag-ui/client"
import { Observable } from "rxjs"
import { tap } from "rxjs/operators"

class MetricsMiddleware extends Middleware {
  private eventCount = 0

  constructor(private metricsService: MetricsService) {
    super()
  }

  run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent> {
    const startTime = Date.now()

    return this.runNext(input, next).pipe(
      tap(event => {
        this.eventCount++
        this.metricsService.recordEvent(event.type)
      }),
      finalize(() => {
        const duration = Date.now() - startTime
        this.metricsService.recordDuration(duration)
        this.metricsService.recordEventCount(this.eventCount)
      })
    )
  }
}

agent.use(new MetricsMiddleware(metricsService))
```

If you are writing class middleware, prefer the helper methods:

* `runNext(input, next)` normalizes chunk events into full `TEXT_MESSAGE_*`/`TOOL_CALL_*` sequences.
* `runNextWithState(input, next)` also provides accumulated `messages` and `state` after each event.

## Built-in Middleware

AG-UI provides several built-in middleware components for common use cases:

### FilterToolCallsMiddleware

Filter tool calls based on allowed or disallowed lists:

```typescript theme={null}
import { FilterToolCallsMiddleware } from "@ag-ui/client"

// Only allow specific tools
const allowedFilter = new FilterToolCallsMiddleware({
  allowedToolCalls: ["search", "calculate"]
})

// Or block specific tools
const blockedFilter = new FilterToolCallsMiddleware({
  disallowedToolCalls: ["delete", "modify"]
})

agent.use(allowedFilter)
```

`FilterToolCallsMiddleware` filters emitted `TOOL_CALL_*` events. It does not block tool execution in the upstream model/runtime.

## Middleware Patterns

Common patterns include logging, auth via `forwardedProps`, and rate limiting. See the [JS middleware reference](/sdk/js/client/middleware) for concrete implementations.

## Combining Middleware

You can combine multiple middleware to create sophisticated processing pipelines:

```typescript theme={null}
const logMiddleware: MiddlewareFunction = (input, next) => next.run(input)
const metricsMiddleware = new MetricsMiddleware(metricsService)
const filterMiddleware = new FilterToolCallsMiddleware({ allowedToolCalls: ["search"] })

agent.use(logMiddleware, metricsMiddleware, filterMiddleware)
```

## Execution Order

Middleware executes in the order it's added, with each middleware wrapping the next:

1. First middleware receives the original input
2. It can modify the input before passing to the next middleware
3. Each middleware processes events from the next in the chain
4. The final middleware calls the actual agent

```typescript theme={null}
agent.use(middleware1, middleware2, middleware3)

// Execution flow:
// → middleware1
//   → middleware2
//     → middleware3
//       → agent.run()
//     ← events flow back through middleware3
//   ← events flow back through middleware2
// ← events flow back through middleware1
```

## Protocol Version on `RUN_STARTED`

Each run's `RUN_STARTED.protocolVersion` names the version the run's stream
speaks, not who relays it
([Versioning](/spec/1.0/basic/versioning#version-negotiation)). For middleware
that means one rule, decided by who produced the run:

* **Forwarding a run.** When the `RUN_STARTED` comes from the next agent in the
  chain, pass it through with its `protocolVersion` untouched. Don't add one,
  overwrite it, or remove it. If the downstream agent predates the field, the
  missing declaration is the truthful one.
* **Synthesizing a run.** When the middleware answers the request itself and
  emits its own `RUN_STARTED` (no downstream agent runs), the middleware is the
  run's producer. Declare the version it was built against with the SDK's
  `PROTOCOL_VERSION` constant. Don't mirror the client's
  `RunAgentInput.protocolVersion` and don't omit the field.
* **Translating a run.** A middleware that rewrites the stream into a different
  protocol version declares the version it emits.

A synthesized run uses the input's `threadId` and `runId`, like any other
producer:

```typescript theme={null}
import { EventType, PROTOCOL_VERSION, type RunStartedEvent } from "@ag-ui/client"

const runStarted: RunStartedEvent = {
  type: EventType.RUN_STARTED,
  threadId: input.threadId,
  runId: input.runId,
  protocolVersion: PROTOCOL_VERSION,
}
```

## Best Practices

1. **Keep middleware focused** – Each middleware should have a single responsibility
2. **Handle errors gracefully** – Use RxJS error handling operators
3. **Avoid blocking operations** – Use async patterns for I/O operations
4. **Document side effects** – Clearly indicate if middleware modifies state
5. **Test middleware independently** – Write unit tests for each middleware
6. **Consider performance** – Be mindful of processing overhead in the event stream

## Advanced Use Cases

### Conditional Middleware

Apply middleware based on runtime conditions:

```typescript theme={null}
const conditionalMiddleware: MiddlewareFunction = (input, next) => {
  if (input.forwardedProps?.debug === true) {
    // Apply debug logging
    return next.run(input).pipe(
      tap(event => console.debug(event))
    )
  }
  return next.run(input)
}
```

For event transformation and stream-control variants, see the [JS middleware reference](/sdk/js/client/middleware).

## Conclusion

Middleware provides a flexible and powerful way to extend AG-UI agents without modifying their core logic. Whether you need simple event transformation or complex stateful processing, the middleware system offers the tools to build robust, maintainable agent applications.


# Reasoning
Source: https://docs.ag-ui.com/concepts/reasoning

Support for LLM reasoning visibility and continuity in AG-UI

# Reasoning

AG-UI provides first-class support for LLM reasoning, enabling chain-of-thought
visibility while maintaining privacy and state continuity across conversation
turns.

## Overview

Modern LLMs increasingly use chain-of-thought reasoning to improve response
quality. AG-UI's reasoning support addresses three key challenges:

* **Reasoning visibility**: Surface reasoning signals (e.g., summaries) to users
  without exposing raw chain-of-thought
* **State continuity**: Maintain reasoning context across turns using encrypted
  reasoning items, even under `store:false` or zero data retention (ZDR)
  policies
* **Privacy compliance**: Support enterprise privacy requirements while
  preserving reasoning capabilities

> [!TIP]
>
> Unlike Activity messages, Reasoning messages are intended to represent the
> agent's internal thought process and may be encrypted for privacy and are
> meant to be sent back to the agent for further processing on subsequent turns.

## ReasoningMessage

The `ReasoningMessage` type represents reasoning content in the message history:

```typescript theme={null}
interface ReasoningMessage {
  id: string
  role: "reasoning"
  content: string // Reasoning content (visible to client)
  encryptedValue?: string // Optional encrypted reasoning for state continuity
}
```

| Property | Type | Description |
| - | - | - |
| `id` | `string` | Unique identifier for the reasoning message |
| `role` | `"reasoning"` | Message role discriminator |
| `content` | `string` | Reasoning content visible to the client |
| `encryptedValue` | `string?` | Encrypted chain-of-thought blob for state continuity |

Key characteristics:

* **Separate from assistant messages**: Reasoning is kept distinct from final
  responses to avoid polluting conversation history
* **Streamable**: Content arrives via streaming events
* **Optional encryption**: When `encryptedValue` is present, it represents
  encrypted chain-of-thought that the client stores and forwards opaquely

## Reasoning Events

Reasoning events manage the lifecycle of reasoning messages. See
[Events](/concepts/events#reasoning-events) for the complete event reference.

### Event Flow

A typical reasoning flow follows this pattern:

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Client

    Note over Agent,Client: Reasoning begins
    Agent->>Client: ReasoningStart

    Note over Agent,Client: Stream visible reasoning
    Agent->>Client: ReasoningMessageStart
    Agent->>Client: ReasoningMessageContent (delta)
    Agent->>Client: ReasoningMessageContent (delta)
    Agent->>Client: ReasoningMessageEnd

    Note over Agent,Client: Attach encrypted chain-of-thought
    Agent->>Client: ReasoningEncryptedValue

    Note over Agent,Client: Reasoning completes
    Agent->>Client: ReasoningEnd
```

### Event Types

| Event | Purpose |
| - | - |
| `ReasoningStart` | Marks beginning of reasoning phase |
| `ReasoningMessageStart` | Begins a streaming reasoning message |
| `ReasoningMessageContent` | Delivers reasoning content chunks |
| `ReasoningMessageEnd` | Completes a reasoning message |
| `ReasoningMessageChunk` | Convenience event that auto-manages message lifecycle |
| `ReasoningEnd` | Marks completion of reasoning |
| `ReasoningEncryptedValue` | Attaches encrypted chain-of-thought to a message or tool call |

## Privacy and Compliance

AG-UI reasoning is designed with privacy-first principles:

### Zero Data Retention (ZDR)

For deployments requiring zero data retention:

1. **Encrypted reasoning values** can carry state across turns without storing
   decryptable content on the client
2. The client receives and forwards `encryptedValue` blobs opaquely via
   `ReasoningEncryptedValue` events
3. Only the agent (or authorized backend) can decrypt the reasoning content

### Visibility Control

Agents control what reasoning is visible to users:

* **Full visibility**: Stream the complete chain-of-thought via
  `ReasoningMessageContent` events
* **Summary only**: Emit a condensed summary while attaching detailed reasoning
  as encrypted values
* **Hidden**: Use only `ReasoningEncryptedValue` events with no visible
  streaming

### Compliance Considerations

| Requirement | Solution |
| - | - |
| GDPR right to erasure | Encrypted content can be discarded without losing reasoning capability |
| SOC 2 data handling | Reasoning content never stored in plaintext on client |
| HIPAA minimum necessary | Only summaries exposed; detailed reasoning stays encrypted |
| Audit logging | `ReasoningStart`/`ReasoningEnd` events provide audit trail without content exposure |

## Example Implementations

### Basic Reasoning Flow

A simple implementation showing visible reasoning:

```typescript theme={null}
// Agent emits reasoning start
yield {
  type: "REASONING_START",
  messageId: "reasoning-001",
}

// Stream visible reasoning content
yield {
  type: "REASONING_MESSAGE_START",
  messageId: "msg-123",
  role: "reasoning",
}

yield {
  type: "REASONING_MESSAGE_CONTENT",
  messageId: "msg-123",
  delta: "Let me ",
}

yield {
  type: "REASONING_MESSAGE_CONTENT",
  messageId: "msg-123",
  delta: "think through ",
}

yield {
  type: "REASONING_MESSAGE_CONTENT",
  messageId: "msg-123",
  delta: "this step ",
}

yield {
  type: "REASONING_MESSAGE_CONTENT",
  messageId: "msg-123",
  delta: "by step...",
}

yield {
  type: "REASONING_MESSAGE_END",
  messageId: "msg-123",
}

// End reasoning
yield {
  type: "REASONING_END",
  messageId: "reasoning-001",
}
```

### Encrypted Content for State Continuity

When maintaining reasoning state across turns without exposing content, use the
`ReasoningEncryptedValue` event to attach encrypted chain-of-thought to messages
or tool calls:

```typescript theme={null}
// Agent emits reasoning start
yield {
  type: "REASONING_START",
  messageId: "reasoning-002",
}

// Stream a visible summary for the user
yield {
  type: "REASONING_MESSAGE_START",
  messageId: "msg-456",
  role: "reasoning",
}

yield {
  type: "REASONING_MESSAGE_CONTENT",
  messageId: "msg-456",
  delta: "Analyzing your request...",
}

yield {
  type: "REASONING_MESSAGE_END",
  messageId: "msg-456",
}

// Attach encrypted chain-of-thought to the reasoning message
yield {
  type: "REASONING_ENCRYPTED_VALUE",
  subtype: "message",
  entityId: "msg-456",
  encryptedValue: "eyJhbGciOiJBMjU2R0NNIiwiZW5jIjoiQTI1NkdDTSJ9...",
}

yield {
  type: "REASONING_END",
  messageId: "reasoning-002",
}

// On subsequent turns, client sends back the message with encryptedValue
// which the agent can decrypt to restore reasoning context
```

### Attaching Encrypted Reasoning to Tool Calls

You can also attach encrypted reasoning to tool calls to capture why the agent
chose specific arguments or how it interpreted results:

```typescript theme={null}
// Tool call with encrypted reasoning
yield {
  type: "TOOL_CALL_START",
  toolCallId: "tool-123",
  toolCallName: "search_database",
  parentMessageId: "msg-789",
}

yield {
  type: "TOOL_CALL_ARGS",
  toolCallId: "tool-123",
  delta: '{"query": "user preferences"}',
}

yield {
  type: "TOOL_CALL_END",
  toolCallId: "tool-123",
}

// Attach encrypted reasoning explaining why this tool was called
yield {
  type: "REASONING_ENCRYPTED_VALUE",
  subtype: "tool-call",
  entityId: "tool-123",
  encryptedValue: "encrypted-reasoning-about-tool-selection...",
}
```

### ZDR-Compliant Implementation

For zero data retention scenarios:

```typescript theme={null}
// Server-side: encrypt reasoning before sending
const encryptedReasoning = await encrypt(detailedChainOfThought, secretKey)

yield {
  type: "REASONING_START",
  messageId: "reasoning-003",
}

// Only emit a high-level summary to the client
yield {
  type: "REASONING_MESSAGE_CHUNK",
  messageId: "summary-001",
  delta: "Processing your request securely...",
}

yield {
  type: "REASONING_MESSAGE_CHUNK",
  messageId: "summary-001",
  delta: "", // Empty delta closes the message
}

// Attach the encrypted chain-of-thought
yield {
  type: "REASONING_ENCRYPTED_VALUE",
  subtype: "message",
  entityId: "summary-001",
  encryptedValue: encryptedReasoning,
}

yield {
  type: "REASONING_END",
  messageId: "reasoning-003",
}

// Client stores only:
// - The encrypted blob (cannot decrypt)
// - The summary text (no sensitive details)
// Full reasoning is never persisted in plaintext
```

### Using the Convenience Chunk Event

The `ReasoningMessageChunk` event simplifies implementation by auto-managing
message lifecycle:

```typescript theme={null}
// First chunk with messageId starts the message automatically
yield {
  type: "REASONING_MESSAGE_CHUNK",
  messageId: "msg-789",
  delta: "Analyzing the problem space...",
}

// Subsequent chunks continue the stream
yield {
  type: "REASONING_MESSAGE_CHUNK",
  messageId: "msg-789",
  delta: " Considering multiple approaches...",
}

// Empty delta (or next non-reasoning event) closes automatically
yield {
  type: "REASONING_MESSAGE_CHUNK",
  messageId: "msg-789",
  delta: "",
}
```

## Client Integration

### Handling Reasoning Events

```typescript theme={null}
import { EventType, type BaseEvent } from "@ag-ui/core"

function handleEvent(event: BaseEvent) {
  switch (event.type) {
    case EventType.REASONING_START:
      // Initialize reasoning UI (e.g., "thinking" indicator)
      console.log("Agent is reasoning...")
      break

    case EventType.REASONING_MESSAGE_CONTENT:
      // Append visible reasoning to UI
      appendReasoningText(event.messageId, event.delta)
      break

    case EventType.REASONING_ENCRYPTED_VALUE:
      // Store encrypted value for the referenced entity
      if (event.subtype === "message") {
        storeMessageEncryptedValue(event.entityId, event.encryptedValue)
      } else if (event.subtype === "tool-call") {
        storeToolCallEncryptedValue(event.entityId, event.encryptedValue)
      }
      break

    case EventType.REASONING_END:
      // Finalize reasoning UI
      console.log("Reasoning complete")
      break
  }
}
```

### Passing Encrypted Reasoning Back

When making subsequent requests, include stored encrypted values:

```typescript theme={null}
const response = await agent.run({
  threadId: "thread-123",
  messages: [
    ...previousMessages,
    {
      id: "reasoning-002",
      role: "reasoning",
      content: "Analyzing your request...", // Visible summary
      encryptedValue: storedEncryptedBlob, // Opaque to client
    },
    {
      id: "user-msg-001",
      role: "user",
      content: "Follow up question...",
    },
  ],
})
```

## Migration from Thinking Events

> [!WARNING]
>
> The `THINKING_*` events are deprecated and will be removed in version 1.0.0.
> New implementations should use `REASONING_*` events.

### Deprecated Events

The following events are deprecated:

| Deprecated Event | 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` |

### Migration Steps

1. **Update event types**: Replace all `THINKING_*` event types with their
   `REASONING_*` equivalents
2. **Update message types**: Use `ReasoningMessage` with `role: "reasoning"`
   instead of any thinking-specific message types
3. **Add encrypted value support**: Consider using `ReasoningEncryptedValue`
   events for improved privacy compliance
4. **Test thoroughly**: Ensure existing functionality works with the new event
   types

### Example Migration

Before (deprecated):

```typescript theme={null}
// ❌ Deprecated - do not use
yield { type: "THINKING_START", messageId: "think-001" }
yield { type: "THINKING_TEXT_MESSAGE_START", messageId: "msg-001" }
yield { type: "THINKING_TEXT_MESSAGE_CONTENT", messageId: "msg-001", delta: "..." }
yield { type: "THINKING_TEXT_MESSAGE_END", messageId: "msg-001" }
yield { type: "THINKING_END", messageId: "think-001" }
```

After (current):

```typescript theme={null}
// ✅ Current implementation
yield { type: "REASONING_START", messageId: "reasoning-001" }
yield { type: "REASONING_MESSAGE_START", messageId: "msg-001", role: "assistant" }
yield { type: "REASONING_MESSAGE_CONTENT", messageId: "msg-001", delta: "..." }
yield { type: "REASONING_MESSAGE_END", messageId: "msg-001" }
yield { type: "REASONING_END", messageId: "reasoning-001" }
```

## Best Practices

1. **Always pair start/end events**: Every `ReasoningStart` should have a
   corresponding `ReasoningEnd`
2. **Use encrypted values for sensitive reasoning**: When chain-of-thought
   contains sensitive information, use `ReasoningEncryptedValue` to attach
   encrypted content to messages or tool calls
3. **Provide user feedback**: Even with encrypted reasoning, emit visible
   summaries so users know the agent is working
4. **Handle missing events gracefully**: Clients should be resilient to
   incomplete event streams
5. **Consider bandwidth**: For very long reasoning chains, consider emitting
   only summaries to reduce data transfer

## Related Documentation

* [Events](/concepts/events#reasoning-events) - Complete event type reference
* [Messages](/concepts/messages#reasoning-messages) - Message type documentation
* [Serialization](/concepts/serialization) - State continuity and lineage


# Serialization
Source: https://docs.ag-ui.com/concepts/serialization

Serialize event streams for history restore, branching, and compaction in AG-UI

# Serialization

Serialization in AG-UI provides a standard way to persist and restore the event
stream that drives an agent–UI session. With a serialized stream you can:

* Restore chat history and UI state after reloads or reconnects
* Attach to running agents and continue receiving events
* Create branches (time travel) from any prior run
* Compact stored history to reduce size without losing meaning

This page explains the model, the updated event fields, and practical usage
patterns with examples.

## Core Concepts

* Stream serialization – Convert the full event history to and from a portable
  representation (e.g., JSON) for storage in databases, files, or logs.
* Event compaction – Reduce verbose streams to snapshots while preserving
  semantics (e.g., merge content chunks, collapse deltas into snapshots).
* Run lineage – Track branches of conversation using a `parentRunId`, forming
  a git‑like append‑only log that enables time travel and alternative paths.

## Updated Event Fields

The `RunStarted` event includes additional optional fields:

```ts theme={null}
type RunStartedEvent = BaseEvent & {
  type: EventType.RUN_STARTED
  threadId: string
  runId: string
  /** Parent for branching/time travel within the same thread */
  parentRunId?: string
  /** Exact agent input for this run (may omit messages already in history) */
  input?: AgentInput
}
```

These fields enable lineage tracking and let implementations record precisely
what was passed to the agent, independent of previously recorded messages.

## Event Compaction

Compaction reduces noise in an event stream while keeping the same observable
outcome. A typical implementation provides a utility:

```ts theme={null}
declare function compactEvents(events: BaseEvent[]): BaseEvent[]
```

Common compaction rules include:

* Message streams – Combine `TEXT_MESSAGE_*` sequences into a single message
  snapshot; concatenate adjacent `TEXT_MESSAGE_CONTENT` for the same message.
* Tool calls – Collapse tool call start/content/end into a compact record.
* State – Merge consecutive `STATE_DELTA` events into a single final
  `STATE_SNAPSHOT` and discard superseded updates.
* Run input normalization – Remove from `RunStarted.input.messages` any
  messages already present earlier in the stream.

## Branching and Time Travel

Setting `parentRunId` on a `RunStarted` event creates a git‑like lineage. The
stream becomes an immutable append‑only log where each run can branch from any
previous run.

```mermaid theme={null}
gitGraph
    commit id: "run1"
    commit id: "run2"
    branch alternative
    checkout alternative
    commit id: "run3 (parent run2)"
    commit id: "run4"
    checkout main
    commit id: "run5 (parent run2)"
    commit id: "run6"
```

Benefits:

* Multiple branches in the same serialized log
* Immutable history (append‑only)
* Deterministic time travel to any point

## Examples

### Basic Serialization

```ts theme={null}
// Serialize event stream
const events: BaseEvent[] = [...];
const serialized = JSON.stringify(events);

await storage.save(threadId, serialized);

// Restore and compact later
const restored = JSON.parse(await storage.load(threadId));
const compacted = compactEvents(restored);
```

### Event Compaction

Before:

```ts theme={null}
[
  { type: "TEXT_MESSAGE_START", messageId: "msg1", role: "user" },
  { type: "TEXT_MESSAGE_CONTENT", messageId: "msg1", delta: "Hello " },
  { type: "TEXT_MESSAGE_CONTENT", messageId: "msg1", delta: "world" },
  { type: "TEXT_MESSAGE_END", messageId: "msg1" },
  { type: "STATE_DELTA", patch: { op: "add", path: "/foo", value: 1 } },
  { type: "STATE_DELTA", patch: { op: "replace", path: "/foo", value: 2 } },
]
```

After:

```ts theme={null}
[
  {
    type: "MESSAGES_SNAPSHOT",
    messages: [{ id: "msg1", role: "user", content: "Hello world" }],
  },
  {
    type: "STATE_SNAPSHOT",
    state: { foo: 2 },
  },
]
```

### Branching With `parentRunId`

```ts theme={null}
// Original run
{
  type: "RUN_STARTED",
  threadId: "thread1",
  runId: "run1",
  input: { messages: ["Tell me about Paris"] },
}

// Branch from run1
{
  type: "RUN_STARTED",
  threadId: "thread1",
  runId: "run2",
  parentRunId: "run1",
  input: { messages: ["Actually, tell me about London instead"] },
}
```

### Normalized Input

```ts theme={null}
// First run includes full message
{
  type: "RUN_STARTED",
  runId: "run1",
  input: { messages: [{ id: "msg1", role: "user", content: "Hello" }] },
}

// Second run omits already‑present message
{
  type: "RUN_STARTED",
  runId: "run2",
  input: { messages: [{ id: "msg2", role: "user", content: "How are you?" }] },
  // msg1 omitted; it already exists in history
}
```

## Metadata

Events and messages carry an optional [`metadata`](/concepts/metadata) object,
and it is part of what you are serializing — persist it alongside everything
else or a replayed stream will be missing token usage, trace ids and anything
else producers attached.

Two things to know when persisting:

* **Compaction folds it.** Collapsing deltas merges their metadata, last write
  wins. See [Event Compaction](#event-compaction) and the
  [compaction reference](/sdk/js/client/compaction) for the ordering caveats.
* **Binary is narrower than JSON.** Over protobuf, metadata is a
  `google.protobuf.Struct`, so nulls, arrays and nested objects survive — but
  numbers are IEEE-754 doubles, so integers beyond 2^53 lose precision, and
  several event types have no protobuf representation at all. JSON round-trips
  everything exactly. Prefer JSON for archival storage.

## Implementation Notes

* Provide SDK helpers for compaction and (de)serialization.
* Store streams append‑only; prefer incremental writes when possible.
* Consider compression when persisting long histories.
* Add indexes by `threadId`, `runId`, and timestamps for fast retrieval.

## See Also

* Concepts: [Events](/concepts/events), [Metadata](/concepts/metadata),
  [State Management](/concepts/state)
* SDKs: TypeScript encoder and core event types


# State Management
Source: https://docs.ag-ui.com/concepts/state

Understanding state synchronization between agents and frontends in AG-UI

# State Management

State management is a core feature of the AG-UI protocol that enables real-time
synchronization between agents and frontend applications. By providing efficient
mechanisms for sharing and updating state, AG-UI creates a foundation for
collaborative experiences where both AI agents and human users can work together
seamlessly.

## Shared State Architecture

In AG-UI, state is a structured data object that:

1. Persists across interactions with an agent
2. Can be accessed by both the agent and the frontend
3. Updates in real-time as the interaction progresses
4. Provides context for decision-making on both sides

This shared state architecture creates a bidirectional communication channel
where:

* Agents can access the application's current state to make informed decisions
* Frontends can observe and react to changes in the agent's internal state
* Both sides can modify the state, creating a collaborative workflow

## State Synchronization Methods

AG-UI provides two complementary methods for state synchronization:

### State Snapshots

The `STATE_SNAPSHOT` event delivers a complete representation of an agent's
current state:

```typescript theme={null}
interface StateSnapshotEvent {
  type: EventType.STATE_SNAPSHOT
  snapshot: any // Complete state object
}
```

Snapshots are typically used:

* At the beginning of an interaction to establish the initial state
* After connection interruptions to ensure synchronization
* When major state changes occur that require a complete refresh
* To establish a new baseline for future delta updates

When a frontend receives a `STATE_SNAPSHOT` event, it should replace its
existing state model entirely with the contents of the snapshot.

### State Deltas

The `STATE_DELTA` event delivers incremental updates to the state using JSON
Patch format (RFC 6902):

```typescript theme={null}
interface StateDeltaEvent {
  type: EventType.STATE_DELTA
  delta: JsonPatchOperation[] // Array of JSON Patch operations
}
```

Deltas are bandwidth-efficient, sending only what has changed rather than the
entire state. This approach is particularly valuable for:

* Frequent small updates during streaming interactions
* Large state objects where most properties remain unchanged
* High-frequency updates that would be inefficient to send as full snapshots

## JSON Patch Format

AG-UI uses the JSON Patch format (RFC 6902) for state deltas, which defines a
standardized way to express changes to a JSON document:

```typescript theme={null}
interface JsonPatchOperation {
  op: "add" | "remove" | "replace" | "move" | "copy" | "test"
  path: string // JSON Pointer (RFC 6901) to the target location
  value?: any // The value to apply (for add, replace)
  from?: string // Source path (for move, copy)
}
```

Common operations include:

1. **add**: Adds a value to an object or array

   ```json theme={null}
   { "op": "add", "path": "/user/preferences", "value": { "theme": "dark" } }
   ```

2. **replace**: Replaces a value

   ```json theme={null}
   { "op": "replace", "path": "/conversation_state", "value": "paused" }
   ```

3. **remove**: Removes a value

   ```json theme={null}
   { "op": "remove", "path": "/temporary_data" }
   ```

4. **move**: Moves a value from one location to another
   ```json theme={null}
   { "op": "move", "path": "/completed_items", "from": "/pending_items/0" }
   ```

Frontends should apply these patches in sequence to maintain an accurate state
representation. If inconsistencies are detected after applying patches, the
frontend can request a fresh `STATE_SNAPSHOT`.

## State Processing in AG-UI

In the AG-UI implementation, state deltas are applied using the
`fast-json-patch` library:

```typescript theme={null}
case EventType.STATE_DELTA: {
  const { delta } = event as StateDeltaEvent;

  try {
    // Apply the JSON Patch operations to the current state without mutating the original
    const result = applyPatch(state, delta, true, false);
    state = result.newDocument;
    return emitUpdate({ state });
  } catch (error: unknown) {
    console.warn(
      `Failed to apply state patch:\n` +
      `Current state: ${JSON.stringify(state, null, 2)}\n` +
      `Patch operations: ${JSON.stringify(delta, null, 2)}\n` +
      `Error: ${errorMessage}`
    );
    return emitNoUpdate();
  }
}
```

This implementation ensures that:

* Patches are applied atomically (all or none)
* The original state is not mutated during the application process
* Errors are caught and handled gracefully

## Human-in-the-Loop Collaboration

The shared state system is fundamental to human-in-the-loop workflows in AG-UI.
It enables:

1. **Real-time visibility**: Users can observe the agent's thought process and
   current status
2. **Contextual awareness**: The agent can access user actions, preferences, and
   application state
3. **Collaborative decision-making**: Both human and AI can contribute to the
   evolving state
4. **Feedback loops**: Humans can correct or guide the agent by modifying state
   properties

For example, an agent might update its state with a proposed action:

```json theme={null}
{
  "proposal": {
    "action": "send_email",
    "recipient": "client@example.com",
    "content": "Draft email content..."
  }
}
```

The frontend can display this proposal to the user, who can then approve,
reject, or modify it before execution.

## CopilotKit Implementation

[CopilotKit](https://docs.copilotkit.ai), a popular framework for building AI
assistants, leverages AG-UI's state management system through its "shared state"
feature. This implementation enables bidirectional state synchronization between
agents (particularly LangGraph agents) and frontend applications.

CopilotKit's shared state system is implemented through:

```jsx theme={null}
// In the frontend React application
const { state: agentState, setState: setAgentState } = useCoAgent({
  name: "agent",
  initialState: { someProperty: "initialValue" },
})
```

This hook creates a real-time connection to the agent's state, allowing:

1. Reading the agent's current state in the frontend
2. Updating the agent's state from the frontend
3. Rendering UI components based on the agent's state

On the backend, LangGraph agents can emit state updates using:

```python theme={null}
# In the LangGraph agent
async def tool_node(self, state: ResearchState, config: RunnableConfig):
    # Update state with new information
    tool_state = {
        "title": new_state.get("title", ""),
        "outline": new_state.get("outline", {}),
        "sections": new_state.get("sections", []),
        # Other state properties...
    }

    # Emit updated state to frontend
    await copilotkit_emit_state(config, tool_state)

    return tool_state
```

These state updates are transmitted using AG-UI's state snapshot and delta
mechanisms, creating a seamless shared context between agent and frontend.

## Best Practices

When implementing state management in AG-UI:

1. **Use snapshots judiciously**: Full snapshots should be sent only when
   necessary to establish a baseline.
2. **Prefer deltas for incremental changes**: Small state updates should use
   deltas to minimize data transfer.
3. **Structure state thoughtfully**: Design state objects to support partial
   updates and minimize patch complexity.
4. **Handle state conflicts**: Implement strategies for resolving conflicting
   updates from agent and frontend.
5. **Include error recovery**: Provide mechanisms to resynchronize state if
   inconsistencies are detected.
6. **Consider security implications**: Avoid storing sensitive information in
   shared state.

## Conclusion

AG-UI's state management system provides a powerful foundation for building
collaborative applications where humans and AI agents work together. By
efficiently synchronizing state between frontend and backend through snapshots
and JSON Patch deltas, AG-UI enables sophisticated human-in-the-loop workflows
that combine the strengths of both human intuition and AI capabilities.

The implementation in frameworks like CopilotKit demonstrates how this shared
state approach can create collaborative experiences that are more effective than
either fully autonomous systems or traditional user interfaces.


# Subagents
Source: https://docs.ag-ui.com/concepts/subagents

Attributing a run's output to the subagent that produced it

# Subagents

Many agent frameworks let an agent delegate work to child agents — a supervisor
dispatching research tasks, an agents-as-tools pattern where a tool call *is* a
nested agent, or a planner farming out subtasks in parallel.

To a frontend, all of that arrives as one event stream. Without extra
information there is no way to tell which subagent produced a given message, so
three concurrent researchers render as one undifferentiated wall of text.

AG-UI's subagent support solves exactly that problem and nothing more: it
**attributes** each event to the subagent that produced it, and reports when
subagents start and stop. It does not orchestrate, schedule, or define
subagents — that stays entirely with the framework.

## `subagentRunId` identifies an invocation, not a definition

This is the single most important thing to understand, and the easiest thing to
get wrong.

`subagentRunId` is an **opaque handle for one invocation** of a subagent. Run the
same subagent twice and you get two different values. It is not a stable
identifier for a reusable subagent definition, and it is not a name.

The symmetry with the top-level run makes the distinction clearer:

| Top level | Subagent |
| - | - |
| `agentId` — a configured, reusable agent | the subagent's `name` — a reusable subagent type |
| `runId` — one invocation's lifecycle | `subagentRunId` — one nested invocation's lifecycle |

So:

* **Do** key transient UI state — a collapsible group, a spinner, a progress row —
  by `subagentRunId`.
* **Do not** persist anything by `subagentRunId` expecting it to be meaningful on
  a later run, and do not treat two invocations of one subagent as sharing a
  value. Use `name` when you mean "which kind of subagent this is".
* **One exception**: a subagent that finished with `outcome: { type: "suspended" }`
  **may** reuse its id on a resuming run. Producers that can correlate the
  resumed work with the suspended invocation should do so, and a client must
  treat that later `SubagentStarted` as a continuation (waiting → running),
  never as a duplicate. A producer that cannot correlate mints a new id — the
  client's waiting state then resolves through the interrupt ids it answered,
  not through id reuse (see [Suspension](#suspension)).

> [!NOTE]
>
> This field was called `subagentId` in prerelease builds. It was renamed because
> the old name implied a reusable definition. If you are on a `canary` build that
> still uses `subagentId`, the value has the same meaning — only the name changed.

## Lifecycle events

Three events bracket a subagent's activity.

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Client

    Note over Agent,Client: Subagent begins
    Agent->>Client: SubagentStarted

    Note over Agent,Client: Attributed output
    Agent->>Client: TextMessageStart / Content / End
    Agent->>Client: ToolCallStart / Args / End

    Note over Agent,Client: Subagent concludes
    alt Success
        Agent->>Client: SubagentFinished
    else Failure
        Agent->>Client: SubagentError
    end
```

### SubagentStarted

Announces a new subagent invocation and gives it a name a UI can display.

| Property | Description |
| - | - |
| `subagentRunId` | Opaque id for this invocation. Required |
| `name` | The subagent's declared type or name, for display. Required |
| `description` | Optional human-readable description |
| `parentSubagentRunId` | Optional — the enclosing subagent, when subagents nest |
| `parentToolCallId` | Optional — the tool call that spawned this subagent |
| `parentMessageId` | Optional — the message that held that tool call |

`parentToolCallId` and `parentMessageId` exist for the agents-as-tools pattern.
They let a client correlate a subagent to the call that created it — to render
the subagent's output inside the tool-call card, for instance — without having to
inspect `rawEvent`.

### SubagentFinished

Closes a subagent invocation's stream segment for this run.

| Property | Description |
| - | - |
| `subagentRunId` | Matches the id from `SubagentStarted`. Required |
| `result` | Optional completion payload, mirroring `RunFinished.result` |
| `outcome` | Optional typed outcome, mirroring `RunFinished.outcome`: `{ type: "success" }` or `{ type: "suspended", interruptIds?: [...] }`. Omitted means success |

#### Suspension

A subagent can pause mid-task waiting for outside input — a human approval
raised inside it, say. The run then ends with an interrupt outcome (see
[Interrupts](/concepts/interrupts)), and because every started subagent closes
before `RunFinished`, the paused subagent still emits `SubagentFinished` — but
with `outcome: { type: "suspended" }`, so a UI can render "waiting" instead of
"done". `interruptIds` names the run-level interrupts this subagent directly
owns (each such `Interrupt` also carries `subagentRunId` back-reference); it
may be empty or omitted for an ancestor suspended because a *descendant*
interrupted.

Suspension is the one case where a `subagentRunId` may deliberately span
runs — with different obligations on each side:

* **Clients must accept** a later run's `SubagentStarted` that reuses a
  suspended invocation's id, and treat it as a *continuation* — transition the
  existing group from waiting back to running, never render a duplicate.
* **Producers should reuse the id when they can** correlate the resumed work
  with the suspended invocation. The LangGraph integration does: its ids
  derive from checkpoint task identity, which survives the pause. Reuse is
  what lets a client continue the group seamlessly.
* **Producers that cannot correlate mint a new id**, and that is valid. The
  client's waiting state does not dangle: the suspended outcome's
  `interruptIds` and the resume entries the client itself sent identify which
  approvals were answered, so the waiting badge resolves on that basis even if
  no continuation arrives under the old id.

### SubagentError

Marks a subagent invocation as failed.

| Property | Description |
| - | - |
| `subagentRunId` | Matches the id from `SubagentStarted`. Required |
| `message` | Human-readable error message. Required |
| `code` | Optional error code |

## Attribution

Beyond the lifecycle events, most events can carry an optional `subagentRunId`
saying who produced them.

An event with no `subagentRunId` belongs to the parent agent. Attribution is
additive: a stream that never sets the field behaves exactly as it did before
subagents existed.

Attribution also stands on its own. A producer may tag events without ever
emitting `SubagentStarted` / `SubagentFinished` — enough for a UI to group output
by producer, without committing to reporting lifecycle. Clients must accept an
identifier they have never seen announced; see
[Rules clients enforce](#rules-clients-enforce).

**Events that can carry attribution:** the text message family, the tool call
family, activity events, the reasoning family, step events, state events, and
`Raw`/`Custom`.

**Events that cannot:** `RunStarted`, `RunFinished`, `RunError` — these describe
the run as a whole — and `MessagesSnapshot`, which carries attribution
per-message instead, since one snapshot mixes messages from several producers.

### Attribution is provenance, not ownership

This distinction matters most on state events, so it is worth stating plainly.

`StateSnapshot` and `StateDelta` are attributable. Attribution on them records
**which subagent produced the update** — it does not mean the subagent has state
of its own. AG-UI state is run-scoped: there is one state document for the run,
and an attributed snapshot or delta is still applied to that one document. The
tag is provenance you can surface ("the researcher updated the shared
scratchpad"), not a separate scope.

That is exactly the meaning attribution carries on the other standalone events.
Nobody reads an attributed `Custom` event as the subagent having private custom
events, and state is no different.

> [!WARNING]
>
> There is no such thing as per-subagent state. If you attribute a snapshot
> expecting the parent's state to be left alone, it will not be — the snapshot
> replaces the run's state as any snapshot does. Use a distinct key inside the
> run state if you need to keep subagents' data apart.

Note that a producer is never *obliged* to attribute state. Some do not: the
LangGraph integration, for instance, does not emit state while a subagent is
active, because its state is one shared document and a mid-delegation snapshot
would carry a partial view. That is a reasonable producer-side choice, not a
protocol requirement.

### Attribution transfers to messages

When an attributed event creates a message, the `subagentRunId` transfers onto
that message. This is what lets a rendering layer group a conversation by
subagent without replaying the event stream — the messages themselves carry
their origin, and they keep it across turns and snapshots.

### Tool results carry their own attribution

`ToolCallResult` is attributed independently of the call it answers, and that is
intentional rather than an oversight: the party that *executes* a tool call can
differ from the subagent that *requested* it. A frontend-executed tool, or a
supervisor running a call on a subagent's behalf, both produce a result whose
owner is not the caller. Inheriting the caller's attribution would misreport
those cases, so each result states its own.

## Nesting and concurrency

Subagents nest. `parentSubagentRunId` on `SubagentStarted` links a child to its
enclosing subagent; a subagent with no parent link belongs directly to the run.

Subagents also run **concurrently**, and this is the case that separates a
working implementation from a plausible one. When three subagents stream at once,
their events interleave, and attribution is the only thing that disambiguates
them. In particular:

* Two subagents may have open text messages simultaneously. A client must track
  each independently rather than assuming one open message at a time.
* A subagent's `SubagentFinished` closes only that subagent's own open streams,
  never a sibling's or the parent's.
* A parent may finish before its child. `parentSubagentRunId` may therefore name
  a subagent that has already finished, which is valid.

### Concurrency and the chunk shorthand

The `TextMessageChunk` / `ToolCallChunk` / `ReasoningMessageChunk` events are a
shorthand: a client synthesizes the START/CONTENT/END boundaries, and a chunk
that omits its id means "the same as the previous one". Under concurrency,
"previous" is only meaningful **per subagent** — so the shorthand resolves it
within the sending subagent's own stream, not across the run.

The practical consequence is one rule for producers: a chunk that carries neither
an id nor a `subagentRunId` is resolved to the parent's open stream of that kind
if there is one — untagged means the parent — and otherwise to the sole open
stream of that kind. When several subagents' streams could all claim it, there is
nothing to resolve it against, and the client rejects it rather than guessing.
**When streaming concurrently, attribute every chunk**, or repeat the id.

## Rules clients enforce

Every rule below is *conditional on the events being present*. Attribution alone
is a complete, valid use of subagent support, so nothing here requires a stream
to send lifecycle events at all.

* `SubagentFinished` and `SubagentError` name a subagent that is currently
  active, and a subagent is not started twice within a run. The lifecycle
  events carry their schema-required fields (`subagentRunId` on all three,
  `name` on `SubagentStarted`, `message` on `SubagentError`) — clients enforce
  this even for in-process producers that bypass wire-level schema validation.
* Continuation and close events agree with the owner their entity was created
  under. A text message opened by one subagent cannot be continued by another.
* Ownership is also established by replayed history: a message in a
  `MessagesSnapshot` (and each tool call it carries) is owned by the
  `subagentRunId` it carries — absent means the parent — and a later event
  reopening that id under a different owner is rejected, exactly as a
  conflicting second opener is.
* A tool call belongs to the assistant message its `parentMessageId` names.
  `ToolCall` itself carries no attribution field, so a `ToolCallStart` whose
  explicit `subagentRunId` disagrees with that message's owner cannot be
  represented faithfully and is rejected; an untagged tool call inherits the
  parent message's owner.
* Steps are scoped to the agent that opened them: a subagent cannot close the
  parent's step, or a sibling's.
* Every started subagent is closed before `RunFinished`.

Several things are deliberately **not** enforced, because the protocol does not
require them:

* **A `subagentRunId` used for attribution need not have been started.**
  Attribution without lifecycle events is a supported mode, so a client must not
  treat an unannounced identifier as an error. UIs should group by whatever ids
  they see and fall back to the id when they have no `name`.
* `parentSubagentRunId` need only name a subagent that has been *started*, not
  one still active — a parent legitimately finishes before its child.
* Events attributed to an already-finished subagent are accepted. Continuation
  events carry the tag of the subagent they belong to even after it finishes.
* Closure is required before `RunFinished` only, not before `RunError`. An
  unclosed subagent is the expected shape of an aborted run.
* Attributed state events are accepted. A producer choosing not to emit them
  mid-delegation is a producer-side decision, not a rule — see
  [Attribution is provenance, not ownership](#attribution-is-provenance-not-ownership).

## Compatibility

> [!WARNING]
>
> **Older clients reject the lifecycle events outright.** Attribution is additive
> and safe — `subagentRunId` is an unknown *field*, which clients tolerate — but
> `SubagentStarted`, `SubagentFinished`, and `SubagentError` are unknown *event
> types*, and a client older than subagent support fails on them while decoding,
> before any application code runs. There is no way to filter them out
> client-side.
>
> If some of your consumers predate subagent support, the producer must not emit
> the lifecycle events to them.

The two directions are not symmetric, so they are worth separating.

### A new agent talking to an older client

The lifecycle events break it, so emitting them has to be **opt-in on the
producer**. Integrations that support subagents therefore expose a flag to enable
them, off by default — in the LangGraph integration it is `subagent_visibility`:

```python theme={null}
agent = LangGraphAgent(
    name="my-agent",
    graph=graph,
    subagent_visibility="attributed",
)
```

The value names what the client sees. `"inline"` (the default) emits no
lifecycle events and no `subagentRunId`, and nothing subagent-related reaches
`MessagesSnapshot` — the stream is exactly what it was before subagent support
existed, including the subagent's own text arriving as the parent's work.
`"attributed"` emits the full surface described in this document. `"hidden"`
suppresses the subagent's internal stream entirely: the client sees only the
parent's spawning tool call, its result, and the parent's own reply. Turn on
`"attributed"` once every consumer is new enough.

Attribution alone is the safer intermediate step, since the field is ignored by
clients that do not know it. A producer that wants grouping without a
compatibility break can attribute events and skip the lifecycle entirely.

### A new client talking to an older agent

Handled automatically. The TypeScript client inserts a compatibility shim based
on the agent's reported version, and it acts in **both** directions.

* **Client → agent.** The shim strips `subagentRunId` from the outgoing input
  messages, so an older agent never receives attribution it cannot interpret.
  This is the load-bearing half: a replayed message history, or a stored thread
  written by a newer client, really can carry the field.
* **Agent → client.** The shim also drops `SubagentStarted`, `SubagentFinished`
  and `SubagentError`, and strips `subagentRunId` from every remaining event
  (including `MessagesSnapshot` messages and the `RunStarted` input echo). This is
  defensive normalization rather than translation — an agent that reports a
  pre-subagent version should not be emitting either of those in the first place,
  so what it really guards is a mixed or proxied pipeline.

The consequence of the second direction is worth knowing: a consumer sitting
behind this shim sees a **flattened, unattributed stream**, even if something
upstream did attribute it. If you want attribution to reach your UI, the agent has
to report a version that supports subagents.

## Support

| SDK | Status |
| - | - |
| TypeScript | Events, attribution, verification, subscriber hooks, protobuf |
| Python | Events and attribution |
| .NET | Events, attribution, verification, protobuf |

The binary protobuf transport carries subagent attribution on both TypeScript
and .NET, generated from the same schema, so a subagent-attributed stream
survives a round trip across languages.

### Known limitations

* **Protobuf covers a subset of event types.** 19 of the 36 event types have a
  protobuf mapping: all three subagent events, plus the text message, tool call
  start/args/end, state, step and run families, and `MessagesSnapshot`, `Raw` and
  `Custom`. The rest cannot be encoded at all — and several of those carry
  attribution: `ToolCallResult`, the reasoning family, and the activity events.
  The chunk shorthand is unencodable too: `TextMessageChunk` and `ToolCallChunk`
  have message definitions carrying `subagent_run_id`, but no `EventType` enum
  entry to select them, and `ReasoningMessageChunk` has no proto message at all.
  All of this predates subagent support.
* **.NET loses the second owner on parallel tool calls from different subagents.**
  Converting a run to `Microsoft.Extensions.AI` messages merges consecutive tool
  calls into one `ChatMessage`, and AG-UI attributes per message, so only the
  first owner survives. It is a current limitation rather than an inherent
  conflict — the provider constraint is adjacency, which interleaving would also
  satisfy while preserving attribution.

## See also

* [Events](/concepts/events) — the full event catalogue, including the subagent events
* [Messages](/concepts/messages) — how attribution appears on messages
* [State](/concepts/state) — why state is run-scoped


# Tools
Source: https://docs.ag-ui.com/concepts/tools

Understanding tools and how they enable human-in-the-loop AI workflows

# Tools

Tools are a fundamental concept in the AG-UI protocol that enable AI agents to
interact with external systems and incorporate human judgment into their
workflows.

AG-UI distinguishes between tools that are defined by the agent backend and
tools that are provided by the client at runtime. Backend-defined tools stay in
the backend agent or framework configuration. Client-defined tools are passed in
`RunAgentInput.tools` so the agent can call back into application-specific
frontend behavior, such as UI actions, approvals, or user-mediated workflows.

## What Are Tools?

In AG-UI, tools are functions that agents can call to:

1. Request specific information
2. Perform actions in external systems
3. Ask for human input or confirmation
4. Access specialized capabilities

Tools bridge the gap between AI reasoning and real-world actions, allowing
agents to accomplish tasks that would be impossible through conversation alone.

## Tool Structure

Tools follow a consistent structure that defines their name, purpose, and
expected parameters:

```typescript theme={null}
interface Tool {
  name: string // Unique identifier for the tool
  description: string // Human-readable explanation of what the tool does
  parameters: {
    // JSON Schema defining the tool's parameters
    type: "object"
    properties: {
      // Tool-specific parameters
    }
    required: string[] // Array of required parameter names
  }
}
```

The `parameters` field uses [JSON Schema](https://json-schema.org/) to define
the structure of arguments that the tool accepts. This schema is used by both
the agent (to generate valid tool calls) and the frontend (to validate and parse
tool arguments).

## Frontend-Defined Tools

A key aspect of AG-UI's tool system is that tools are defined in the frontend
and passed to the agent during execution:

```typescript theme={null}
// Define tools in the frontend
const userConfirmationTool = {
  name: "confirmAction",
  description: "Ask the user to confirm a specific action before proceeding",
  parameters: {
    type: "object",
    properties: {
      action: {
        type: "string",
        description: "The action that needs user confirmation",
      },
      importance: {
        type: "string",
        enum: ["low", "medium", "high", "critical"],
        description: "The importance level of the action",
      },
    },
    required: ["action"],
  },
}

// Pass tools to the agent during execution
agent.runAgent({
  tools: [userConfirmationTool],
  // Other parameters...
})
```

This approach has several advantages:

1. **Frontend control**: The frontend determines what capabilities are available
   to the agent
2. **Dynamic capabilities**: Tools can be added or removed based on user
   permissions, context, or application state
3. **Separation of concerns**: Agents focus on reasoning while frontends handle
   tool implementation
4. **Security**: Sensitive operations are controlled by the application, not the
   agent

`RunAgentInput.tools` is only for these client-provided tools. It is not
intended to contain every tool available to the backend agent. If your
integration has backend tools, define them in the backend framework or advertise
them through agent capabilities instead of sending their schemas from the
client.

## Tool Call Lifecycle

When an agent needs to use a tool, it follows a standardized sequence of events:

1. **ToolCallStart**: Indicates the beginning of a tool call with a unique ID
   and tool name

   ```typescript theme={null}
   {
     type: EventType.TOOL_CALL_START,
     toolCallId: "tool-123",
     toolCallName: "confirmAction",
     parentMessageId: "msg-456" // Optional reference to a message
   }
   ```

2. **ToolCallArgs**: Streams the tool arguments as they're generated

   ```typescript theme={null}
   {
     type: EventType.TOOL_CALL_ARGS,
     toolCallId: "tool-123",
     delta: '{"act' // Partial JSON being streamed
   }
   ```

   ```typescript theme={null}
   {
     type: EventType.TOOL_CALL_ARGS,
     toolCallId: "tool-123",
     delta: 'ion":"Depl' // More JSON being streamed
   }
   ```

   ```typescript theme={null}
   {
     type: EventType.TOOL_CALL_ARGS,
     toolCallId: "tool-123",
     delta: 'oy the application to production"}' // Final JSON fragment
   }
   ```

3. **ToolCallEnd**: Marks the completion of the tool call
   ```typescript theme={null}
   {
     type: EventType.TOOL_CALL_END,
     toolCallId: "tool-123"
   }
   ```

The frontend accumulates these deltas to construct the complete tool call
arguments. Once the tool call is complete, the frontend can execute the tool and
provide results back to the agent.

### Tool call metadata

All three of these events can carry a `metadata` object, and it accumulates onto
the **tool call itself** rather than onto the assistant message that owns it:

```typescript theme={null}
assistantMessage.toolCalls[0].metadata
// { provider: "anthropic", latencyMs: 84 }
```

That is deliberate. One assistant message can own several tool calls, so folding
their metadata into the parent would make the result depend on the order the
calls happened to interleave. Giving each tool call its own keeps it
unambiguous.

`ToolCallResult` is different — it creates a tool message, so its metadata
merges into that message like any other message-building event. See
[Metadata](/concepts/metadata).

## Tool Results

After a tool has been executed, the result is sent back to the agent as a "tool
message":

```typescript theme={null}
{
  id: "result-789",
  role: "tool",
  content: "true", // Tool result as a string
  toolCallId: "tool-123" // References the original tool call
}
```

This message becomes part of the conversation history, allowing the agent to
reference and incorporate the tool's result in subsequent responses.

If the tool did not succeed, set `error` to the failure message:

```typescript theme={null}
{
  id: "result-789",
  role: "tool",
  content: "Deployment blocked: the production environment is locked",
  toolCallId: "tool-123",
  error: "the production environment is locked" // Marks this result as a failure
}
```

`error` is how the protocol expresses a client-side tool failure. Without it, a
tool that failed is indistinguishable from one that succeeded — whatever the
frontend happened to put in `content` is all the agent has to go on. See
[Messages](/concepts/messages) for the full `ToolMessage` shape.

## Human-in-the-Loop Workflows

The AG-UI tool system is especially powerful for implementing human-in-the-loop
workflows. By defining tools that request human input or confirmation,
developers can create AI experiences that seamlessly blend autonomous operation
with human judgment.

For example:

1. Agent needs to make an important decision
2. Agent calls the `confirmAction` tool with details about the decision
3. Frontend displays a confirmation dialog to the user
4. User provides their input
5. Frontend sends the user's decision back to the agent
6. Agent continues processing with awareness of the user's choice

This pattern enables use cases like:

* **Approval workflows**: AI suggests actions that require human approval
* **Data verification**: Humans verify or correct AI-generated data
* **Collaborative decision-making**: AI and humans jointly solve complex
  problems
* **Supervised learning**: Human feedback improves future AI decisions

## CopilotKit Integration

[CopilotKit](https://docs.copilotkit.ai/) provides a simplified way to work with
AG-UI tools in React applications through its
[`useCopilotAction`](https://docs.copilotkit.ai/guides/frontend-actions) hook:

```tsx theme={null}
import { useCopilotAction } from "@copilotkit/react-core"

// Define a tool for user confirmation
useCopilotAction({
  name: "confirmAction",
  description: "Ask the user to confirm an action",
  parameters: {
    type: "object",
    properties: {
      action: {
        type: "string",
        description: "The action to confirm",
      },
    },
    required: ["action"],
  },
  handler: async ({ action }) => {
    // Show a confirmation dialog
    const confirmed = await showConfirmDialog(action)
    return confirmed ? "approved" : "rejected"
  },
})
```

This approach makes it easy to define tools that integrate with your React
components and handle the tool execution logic in a clean, declarative way.

## Tool Examples

Here are some common types of tools used in AG-UI applications:

### User Confirmation

```typescript theme={null}
{
  name: "confirmAction",
  description: "Ask the user to confirm an action",
  parameters: {
    type: "object",
    properties: {
      action: {
        type: "string",
        description: "The action to confirm"
      },
      importance: {
        type: "string",
        enum: ["low", "medium", "high", "critical"],
        description: "The importance level"
      }
    },
    required: ["action"]
  }
}
```

### Data Retrieval

```typescript theme={null}
{
  name: "fetchUserData",
  description: "Retrieve data about a specific user",
  parameters: {
    type: "object",
    properties: {
      userId: {
        type: "string",
        description: "ID of the user"
      },
      fields: {
        type: "array",
        items: {
          type: "string"
        },
        description: "Fields to retrieve"
      }
    },
    required: ["userId"]
  }
}
```

### User Interface Control

```typescript theme={null}
{
  name: "navigateTo",
  description: "Navigate to a different page or view",
  parameters: {
    type: "object",
    properties: {
      destination: {
        type: "string",
        description: "Destination page or view"
      },
      params: {
        type: "object",
        description: "Optional parameters for the navigation"
      }
    },
    required: ["destination"]
  }
}
```

### Content Generation

```typescript theme={null}
{
  name: "generateImage",
  description: "Generate an image based on a description",
  parameters: {
    type: "object",
    properties: {
      prompt: {
        type: "string",
        description: "Description of the image to generate"
      },
      style: {
        type: "string",
        description: "Visual style for the image"
      },
      dimensions: {
        type: "object",
        properties: {
          width: { type: "number" },
          height: { type: "number" }
        },
        description: "Dimensions of the image"
      }
    },
    required: ["prompt"]
  }
}
```

## Best Practices

When designing tools for AG-UI:

1. **Clear naming**: Use descriptive, action-oriented names
2. **Detailed descriptions**: Include thorough descriptions to help the agent
   understand when and how to use the tool
3. **Structured parameters**: Define precise parameter schemas with descriptive
   field names and constraints
4. **Required fields**: Only mark parameters as required if they're truly
   necessary
5. **Error handling**: Implement robust error handling in tool execution code
6. **User experience**: Design tool UIs that provide appropriate context for
   human decision-making

## Conclusion

Tools in AG-UI bridge the gap between AI reasoning and real-world actions,
enabling sophisticated workflows that combine the strengths of AI and human
intelligence. By defining tools in the frontend and passing them to agents,
developers can create interactive experiences where AI and humans collaborate
efficiently.

The tool system is particularly powerful for implementing human-in-the-loop
workflows, where AI can suggest actions but defer critical decisions to humans.
This balances automation with human judgment, creating AI experiences that are
both powerful and trustworthy.


# Contributing
Source: https://docs.ag-ui.com/development/contributing

How to participate in Agent User Interaction Protocol development

# Naming conventions

Add your package under `integrations/` with docs and tests.

If your integration is work in progress, you can still add it to main branch.
You can prefix it with `wip-`, i.e.
(`integrations/wip-your-integration`) or if you're a third party
contributor use the `community` prefix, i.e.
(`integrations/community/your-integration`).

For questions and discussions, please use
[GitHub Discussions](https://github.com/ag-ui-protocol/ag-ui/discussions).


# Roadmap
Source: https://docs.ag-ui.com/development/roadmap

Our plans for evolving Agent User Interaction Protocol

You can follow the progress of the AG-UI Protocol on our
[public roadmap](https://github.com/orgs/ag-ui-protocol/projects/1).

## Get Involved

If you’d like to contribute ideas, feature requests, or bug reports to
the roadmap, please see the [Contributing Guide](https://github.com/ag-ui-protocol/ag-ui/blob/main/CONTRIBUTING.md)
for details on how to get involved.


# What's New
Source: https://docs.ag-ui.com/development/updates

The latest updates and improvements to AG-UI

**2025-04-09**

AG-UI repositories are now public

* Initial release of the Agent User Interaction Protocol


# Generative User Interfaces
Source: https://docs.ag-ui.com/drafts/generative-ui

AI-generated interfaces without custom tool renderers

# Generative User Interfaces

## Summary

### Problem Statement

Currently, creating custom user interfaces for agent interactions requires
programmers to define specific tool renderers. This limits the flexibility and
adaptability of agent-driven applications.

### Motivation

This draft describes an AG-UI extension that addresses **generative user
interfaces**—interfaces produced directly by artificial intelligence without
requiring a programmer to define custom tool renderers. The key idea is to
leverage our ability to send client-side tools to the agent, thereby enabling
this capability across all agent frameworks supported by AG-UI.

## Status

* **Status**: Draft
* **Author(s)**: Markus Ecker ([mail@mme.xyz](mailto:mail@mme.xyz))

## Challenges and Limitations

### Tool Description Length

OpenAI enforces a limit of 1024 characters for tool descriptions. Gemini and
Anthropic impose no such limit.

### Arguments JSON Schema Constraints

Classes, nesting, `$ref`, and `oneOf` are not reliably supported across LLM
providers.

### Context Window Considerations

Injecting a large UI description language into an agent may reduce its
performance. Agents dedicated solely to UI generation perform better than agents
combining UI generation with other tasks.

## Detailed Specification

### Two-Step Generation Process

```mermaid theme={null}
flowchart TD
    A[Agent needs UI] --> B["Step 1: <b>What?</b> <br/> Agent calls generateUserInterface <br/>(description, data, output)"]
    B --> C["Step 2: <b>How?</b> <br/> Secondary generator builds actual UI <br/>(JSON Schema, React, etc.)"]
    C --> D[Rendered UI shown to user]
    D --> E[Validated user input returned to Agent]
```

### Step 1: What to Generate?

Inject a lightweight tool into the agent:

**Tool Definition:**

* **Name:** `generateUserInterface`
* **Arguments:**
  * **description**: A high-level description of the UI (e.g., *"A form for
    entering the user's address"*)
  * **data**: Arbitrary pre-populated data for the generated UI
  * **output**: A description or schema of the data the agent expects the user
    to submit back (fields, required/optional, types, constraints)

**Example Tool Call:**

```json theme={null}
{
  "tool": "generateUserInterface",
  "arguments": {
    "description": "A form that collects a user's shipping address.",
    "data": {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "city": "London"
    },
    "output": {
      "type": "object",
      "required": [
        "firstName",
        "lastName",
        "street",
        "city",
        "postalCode",
        "country"
      ],
      "properties": {
        "firstName": { "type": "string", "title": "First Name" },
        "lastName": { "type": "string", "title": "Last Name" },
        "street": { "type": "string", "title": "Street Address" },
        "city": { "type": "string", "title": "City" },
        "postalCode": { "type": "string", "title": "Postal Code" },
        "country": {
          "type": "string",
          "title": "Country",
          "enum": ["GB", "US", "DE", "AT"]
        }
      }
    }
  }
}
```

### Step 2: How to Generate?

Delegate UI generation to a secondary LLM or agent:

* The CopilotKit user stays in control: Can make their own generators, add
  custom libraries, include additional prompts etc.
* On tool invocation, the secondary model consumes `description`, `data`, and
  `output` to generate the user interface
* This model is focused solely on UI generation, ensuring maximum fidelity and
  consistency
* The generation method can be swapped as needed (e.g., JSON, HTML, or other
  renderable formats)
* The UI format description is not subject to structural or length constraints,
  allowing arbitrarily complex specifications

## Implementation Examples

### Example Output: UISchemaGenerator

```json theme={null}
{
  "jsonSchema": {
    "title": "Shipping Address",
    "type": "object",
    "required": [
      "firstName",
      "lastName",
      "street",
      "city",
      "postalCode",
      "country"
    ],
    "properties": {
      "firstName": { "type": "string", "title": "First name" },
      "lastName": { "type": "string", "title": "Last name" },
      "street": { "type": "string", "title": "Street address" },
      "city": { "type": "string", "title": "City" },
      "postalCode": { "type": "string", "title": "Postal code" },
      "country": {
        "type": "string",
        "title": "Country",
        "enum": ["GB", "US", "DE", "AT"]
      }
    }
  },
  "uiSchema": {
    "type": "VerticalLayout",
    "elements": [
      {
        "type": "Group",
        "label": "Personal Information",
        "elements": [
          { "type": "Control", "scope": "#/properties/firstName" },
          { "type": "Control", "scope": "#/properties/lastName" }
        ]
      },
      {
        "type": "Group",
        "label": "Address",
        "elements": [
          { "type": "Control", "scope": "#/properties/street" },
          { "type": "Control", "scope": "#/properties/city" },
          { "type": "Control", "scope": "#/properties/postalCode" },
          { "type": "Control", "scope": "#/properties/country" }
        ]
      }
    ]
  },
  "initialData": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "city": "London",
    "country": "GB"
  }
}
```

### Example Output: ReactFormHookGenerator

```tsx theme={null}
import React from "react"
import { useForm } from "react-hook-form"
import { z } from "zod"
import { zodResolver } from "@hookform/resolvers/zod"

// ----- Schema (contract) -----
const AddressSchema = z.object({
  firstName: z.string().min(1, "Required"),
  lastName: z.string().min(1, "Required"),
  street: z.string().min(1, "Required"),
  city: z.string().min(1, "Required"),
  postalCode: z.string().regex(/^[A-Za-z0-9\\-\\s]{3,10}$/, "3–10 chars"),
  country: z.enum(["GB", "US", "DE", "AT", "FR", "IT", "ES"]),
})
export type Address = z.infer<typeof AddressSchema>

type Props = {
  initialData?: Partial<Address>
  meta?: { title?: string; submitLabel?: string }
  respond: (data: Address) => void // <-- called on successful submit
}

const COUNTRIES: Address["country"][] = [
  "GB",
  "US",
  "DE",
  "AT",
  "FR",
  "IT",
  "ES",
]

export default function AddressForm({ initialData, meta, respond }: Props) {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<Address>({
    resolver: zodResolver(AddressSchema),
    defaultValues: {
      firstName: "",
      lastName: "",
      street: "",
      city: "",
      postalCode: "",
      country: "GB",
      ...initialData,
    },
  })

  const onSubmit = (data: Address) => {
    // Guaranteed to match AddressSchema
    respond(data)
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      {meta?.title && <h2>{meta.title}</h2>}

      {/* Section: Personal Information */}
      <fieldset>
        <legend>Personal Information</legend>

        <div>
          <label>First name</label>
          <input {...register("firstName")} placeholder="Ada" autoFocus />
          {errors.firstName && <small>{errors.firstName.message}</small>}
        </div>

        <div>
          <label>Last name</label>
          <input {...register("lastName")} placeholder="Lovelace" />
          {errors.lastName && <small>{errors.lastName.message}</small>}
        </div>
      </fieldset>

      {/* Section: Address */}
      <fieldset>
        <legend>Address</legend>

        <div>
          <label>Street address</label>
          <input {...register("street")} />
          {errors.street && <small>{errors.street.message}</small>}
        </div>

        <div>
          <label>City</label>
          <input {...register("city")} />
          {errors.city && <small>{errors.city.message}</small>}
        </div>

        <div>
          <label>Postal code</label>
          <input {...register("postalCode")} />
          {errors.postalCode && <small>{errors.postalCode.message}</small>}
        </div>

        <div>
          <label>Country</label>
          <select {...register("country")}>
            {COUNTRIES.map((c) => (
              <option key={c} value={c}>
                {c}
              </option>
            ))}
          </select>
          {errors.country && <small>{errors.country.message}</small>}
        </div>
      </fieldset>

      <div>
        <button type="submit">{meta?.submitLabel ?? "Submit"}</button>
      </div>
    </form>
  )
}
```

## Implementation Considerations

### Client SDK Changes

TypeScript SDK additions:

* New `generateUserInterface` tool type
* UI generator registry for pluggable generators
* Validation layer for generated UI schemas
* Response handler for user-submitted data

Python SDK additions:

* Support for UI generation tool invocation
* Schema validation utilities
* Serialization for UI definitions

### Integration Impact

* All AG-UI integrations can leverage this capability without modification
* Frameworks emit standard tool calls; client handles UI generation
* Backward compatible with existing tool-based UI approaches

## Use Cases

### Dynamic Forms

Agents can generate forms on-the-fly based on conversation context without
pre-defined schemas.

### Data Visualization

Generate charts, graphs, or tables appropriate to the data being discussed.

### Interactive Workflows

Create multi-step wizards or guided processes tailored to user needs.

### Adaptive Interfaces

Generate different UI layouts based on user preferences or device capabilities.

## Testing Strategy

* Unit tests for tool injection and invocation
* Integration tests with multiple UI generators
* E2E tests demonstrating various UI types
* Performance benchmarks comparing single vs. two-step generation
* Cross-provider compatibility testing

## References

* [AG-UI Tools Documentation](/concepts/tools)
* [JSON Schema](https://json-schema.org/)
* [React Hook Form](https://react-hook-form.com/)
* [JSON Forms](https://jsonforms.io/)


# Meta Events
Source: https://docs.ag-ui.com/drafts/meta-events

Annotations and signals independent of agent runs

# Meta Events Proposal

## Summary

### Problem Statement

Currently, AG-UI events are tightly coupled to agent runs. There's no
standardized way to attach user feedback, annotations, or external signals to
the event stream that are independent of the agent's execution lifecycle.

### Motivation

AG-UI is extended with **MetaEvents**, a new class of events that can occur at
any point in the event stream, independent of agent runs. MetaEvents provide a
way to attach annotations, signals, or feedback to a serialized stream. They may
originate from users, clients, or external systems rather than from agents.
Examples include reactions such as thumbs up/down on a message.

## Status

* **Status**: Draft
* **Author(s)**: Markus Ecker ([mail@mme.xyz](mailto:mail@mme.xyz))

## Detailed Specification

### Overview

This proposal introduces:

* A new **MetaEvent** type for side-band annotations
* Events that can appear anywhere in the stream
* Support for user feedback, tags, and external annotations
* Extensible payload structure for application-specific data

## New Type: MetaEvent

```typescript theme={null}
type MetaEvent = BaseEvent & {
  type: EventType.META
  /**
   * Application-defined type of the meta event.
   * Examples: "thumbs_up", "thumbs_down", "tag", "note"
   */
  metaType: string

  /**
   * Application-defined payload.
   * May reference other entities (e.g., messageId) or contain freeform data.
   */
  payload: Record<string, unknown>
}
```

### Key Characteristics

* **Run-independent**: MetaEvents are not tied to any specific run lifecycle
* **Position-flexible**: Can appear before, between, or after runs
* **Origin-diverse**: May come from users, clients, or external systems
* **Extensible**: Applications define their own metaType values and payload
  schemas

## Implementation Examples

### User Feedback

**Thumbs Up:**

```json theme={null}
{
  "id": "evt_123",
  "ts": 1714063982000,
  "type": "META",
  "metaType": "thumbs_up",
  "payload": {
    "messageId": "msg_456",
    "userId": "user_789"
  }
}
```

**Thumbs Down with Reason:**

```json theme={null}
{
  "id": "evt_124",
  "ts": 1714063985000,
  "type": "META",
  "metaType": "thumbs_down",
  "payload": {
    "messageId": "msg_456",
    "userId": "user_789",
    "reason": "inaccurate",
    "comment": "The calculation seems incorrect"
  }
}
```

### Annotations

**User Note:**

```json theme={null}
{
  "id": "evt_789",
  "ts": 1714064001000,
  "type": "META",
  "metaType": "note",
  "payload": {
    "text": "Important question to revisit",
    "relatedRunId": "run_001",
    "author": "user_123"
  }
}
```

**Tag Assignment:**

```json theme={null}
{
  "id": "evt_890",
  "ts": 1714064100000,
  "type": "META",
  "metaType": "tag",
  "payload": {
    "tags": ["important", "follow-up"],
    "threadId": "thread_001"
  }
}
```

### External System Events

**Analytics Event:**

```json theme={null}
{
  "id": "evt_901",
  "ts": 1714064200000,
  "type": "META",
  "metaType": "analytics",
  "payload": {
    "event": "conversation_shared",
    "properties": {
      "shareMethod": "link",
      "recipientCount": 3
    }
  }
}
```

**Moderation Flag:**

```json theme={null}
{
  "id": "evt_902",
  "ts": 1714064300000,
  "type": "META",
  "metaType": "moderation",
  "payload": {
    "action": "flag",
    "messageId": "msg_999",
    "category": "inappropriate_content",
    "confidence": 0.95
  }
}
```

## Common Meta Event Types

While applications can define their own types, these are commonly used:

| MetaType | Description | Typical Payload |
| - | - | - |
| `thumbs_up` | Positive feedback | `{ messageId, userId }` |
| `thumbs_down` | Negative feedback | `{ messageId, userId, reason? }` |
| `note` | User annotation | `{ text, relatedId?, author }` |
| `tag` | Categorization | `{ tags[], targetId }` |
| `bookmark` | Save for later | `{ messageId, userId }` |
| `copy` | Content copied | `{ messageId, content }` |
| `share` | Content shared | `{ messageId, method }` |
| `rating` | Numeric rating | `{ messageId, rating, maxRating }` |

## Use Cases

### User Feedback Collection

Capture user reactions to agent responses for quality improvement.

### Conversation Annotation

Allow users to add notes, tags, or bookmarks to important parts of
conversations.

### Analytics and Tracking

Record user interactions and behaviors without affecting agent execution.

### Content Moderation

Flag or mark content for review by external moderation systems.

### Collaborative Features

Enable multiple users to annotate or comment on shared conversations.

### Audit Trail

Create a complete record of all interactions, not just agent responses.

## Implementation Considerations

### Client SDK Changes

TypeScript SDK:

* New `MetaEvent` type in `@ag-ui/core`
* Helper functions for common meta event types
* MetaEvent filtering and querying utilities

Python SDK:

* `MetaEvent` class implementation
* Meta event builders for common types
* Event stream filtering capabilities

## Testing Strategy

* Unit tests for MetaEvent creation and validation
* Integration tests with mixed event streams
* Performance tests with high-volume meta events
* Security tests for payload validation

## References

* [AG-UI Events Documentation](/concepts/events)
* [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html)
* [CQRS Pattern](https://martinfowler.com/bliki/CQRS.html)


# Overview
Source: https://docs.ag-ui.com/drafts/overview

Draft changes being considered for the AG-UI protocol

# Overview

This section contains draft changes being considered for the AG-UI protocol. These proposals are under internal review and may be modified or withdrawn before implementation.

## Current Drafts

> [card] [Reasoning](/drafts/reasoning)
>
> Support for LLM reasoning visibility and continuity with encrypted content

> [card] [Interrupt-Aware Run Lifecycle](/concepts/interrupts)
>
> Native support for agent pauses requiring human approval or input

> [card] [Generative User Interfaces](/drafts/generative-ui)
>
> AI-generated interfaces without requiring custom tool renderers

> [card] [Meta Events](/drafts/meta-events)
>
> Annotations and signals independent of agent runs

## Status Definitions

* **Draft** - Initial proposal under consideration
* **Under Review** - Active development and testing
* **Accepted** - Approved for implementation
* **Implemented** - Merged into the main protocol specification
* **Withdrawn** - Proposal has been withdrawn or superseded


# Integrations
Source: https://docs.ag-ui.com/integrations

A list of AG-UI integrations

This page showcases various Agent User Interaction Protocol (AG-UI) integrations
that demonstrate the protocol's capabilities and versatility.

## Frontend Integrations

* **[CopilotKit](https://copilotkit.ai)** - AI Copilots for your product.

## Agent Frameworks

* **[LangChain](https://www.langchain.com/langgraph)** - Balance agent control with agency
* **[Microsoft Agent Framework](https://github.com/microsoft/agent-framework)** - A framework for building, orchestrating, and deploying AI agents and multi-agent workflows with support for Python and .NET.
* **[Google ADK](https://google.github.io/adk-docs/)** - Google's Agent Development Kit for building AI agents with Gemini models. AG-UI supports both the [Python middleware](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/adk-middleware/python) and the [JavaScript runtime integration](/integrations/google-adk-js), with a [live ADK JavaScript demo](https://dojo.ag-ui.com/adk-js/feature/agentic_chat?openCopilot=true).
* **[Google Antigravity](https://github.com/google-antigravity/antigravity-sdk-python)** - Google's agent harness SDK, which runs the model, its tools and its sessions in a bundled local process
* **[AWS Strands Agents](https://github.com/strands-agents/sdk-python)** - A model-driven approach to building AI agents
* **[Mastra](https://mastra.ai)** - The TypeScript Agent Framework
* **[Pydantic AI](https://github.com/pydantic/pydantic-ai)** - Production-ready AI agents in Python
* **[Agno](https://agno.com)** - A full-stack framework for building Multi-Agent Systems
* **[LlamaIndex](https://www.llamaindex.ai)** - Data framework for LLM applications with RAG capabilities and workflow orchestration
* **[CrewAI](https://crewai.com)** - Streamline workflows across industries with
  powerful AI agents.
* **[AG2](https://ag2.ai)** - The Open-Source AgentOS
* **[Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)** - Anthropic's hosted agent sessions, bridged to AG-UI in TypeScript, Python, and .NET
* **[Claude Agent SDK](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/claude-agent-sdk)** - Anthropic's local agent SDK, served over AG-UI
* **[Langroid](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/langroid)** - Lightweight Python framework for building multi-agent LLM applications
* **[OpenAI Agents SDK](https://openai.github.io/openai-agents-python/)** - OpenAI’s Python framework for building agentic applications
* **[Cloudflare Agents](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/community/cloudflare-agents)** - Agents on Cloudflare Workers and Durable Objects, served over AG-UI
* **[Omnara](https://omnara.com)** - Open-source control plane for durable, hosted agents, bridged to AG-UI in TypeScript ([quickstart](/integrations/omnara))

## Infrastructure / Deployment

* **[Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/)** - Fully managed infrastructure for deploying AG-UI agents to production with native protocol support, managed authentication, session isolation, and auto-scaling. See the [deployment guide](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-agui.html) and the [announcement](https://aws.amazon.com/about-aws/whats-new/2026/03/amazon-bedrock-agentcore-runtime-ag-ui-protocol/).

## Specification (standard)

* **[Oracle Open Agent Spec](http://oracle.github.io/agent-spec/)** - A portable language for defining agentic systems
* **[A2A Middleware](https://a2a-protocol.org/)** - Provides the definitive common language for agent interoperability

## Generative UI

* **[A2UI](https://github.com/google/A2UI)** - Declarative generative UI for generating rich, interactive interfaces
* **[MCP Apps](https://blog.modelcontextprotocol.io/posts/2025-11-21-mcp-apps/)** - Render interactive UI components from MCP servers directly in your chat interface

## SDKs

\| [Kotlin](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/sdk/kotlin/overview.mdx)
\| [Golang](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/sdk/go/overview.mdx)
\| [Dart](https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/community/dart)
\| [Java](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/sdk/java/overview.mdx)
\| [Rust](https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/community/rust/crates/ag-ui-client)
\| [Ruby](https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/community/ruby)
\| [C++](https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/community/c%2B%2B)
\| [.NET](https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/dotnet/samples/GettingStarted)

#### (coming soon)

\| [Nim](https://github.com/ag-ui-protocol/ag-ui/pull/29)
\| [Flowise](https://github.com/ag-ui-protocol/ag-ui/issues/367)
\| [Langflow](https://github.com/ag-ui-protocol/ag-ui/issues/366)

### Clients

\| [CopilotKit](https://docs.copilotkit.ai/direct-to-llm/guides/quickstart)
\| [Terminal + Agent](https://docs.ag-ui.com/quickstart/clients)
\| [Chat platforms — Slack, Microsoft Teams](https://github.com/CopilotKit/channels-sdk)
\| [React Native](https://github.com/CopilotKit/CopilotKit/tree/main/examples/v2/react-native/demo)
\| [OpenBot](https://open.bot/builders)

Join [Discord](https://discord.gg/Jd3FzfdJa8) to engage with the AG-UI community.


# Google ADK JavaScript quickstart
Source: https://docs.ag-ui.com/integrations/google-adk-js

Run a native Google ADK JavaScript agent behind an AG-UI endpoint.

`@ag-ui/adk-js` adapts a server-side Google ADK JavaScript `Runner` to an AG-UI
`AbstractAgent`. Use it when the agent and web runtime run in Node.js. The
existing `@ag-ui/adk` package remains the HTTP client for the Python ADK
middleware.

## Prerequisites

* Node.js 20.19 or newer
* `@ag-ui/client` and `@ag-ui/core` 1.x (use a CopilotKit release that
  resolves the 1.x line)
* A Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey)

## Add ADK JavaScript to an application

Install the server dependencies:

```bash theme={null}
npm install @ag-ui/adk-js @google/adk @copilotkit/runtime hono
```

`@ag-ui/adk-js` requires `@google/adk` 2.x.

Set your Gemini key in the environment the server reads:

```dotenv theme={null}
GOOGLE_GENAI_API_KEY=your-api-key
GOOGLE_GENAI_USE_VERTEXAI=0
```

Create `app/api/copilotkit/route.ts`:

```typescript theme={null}
import { ADKJSAgent } from "@ag-ui/adk-js"
import {
  CopilotRuntime,
  InMemoryAgentRunner,
  createCopilotEndpointSingleRoute,
} from "@copilotkit/runtime/v2"
import { Agent, InMemorySessionService } from "@google/adk"
import { handle } from "hono/vercel"

export const runtime = "nodejs"

const rootAgent = new Agent({
  name: "assistant",
  model: "gemini-2.5-flash",
  instruction: "Be concise and use frontend tools when appropriate.",
})

const copilotRuntime = new CopilotRuntime({
  agents: {
    assistant: new ADKJSAgent({
      appName: "assistant_app",
      sessionService: new InMemorySessionService(),
      agent: rootAgent,
      userId: "user-123", // resolve from server-side auth
    }),
  },
  runner: new InMemoryAgentRunner(),
})

const endpoint = createCopilotEndpointSingleRoute({
  runtime: copilotRuntime,
  basePath: "/api/copilotkit",
})

export const POST = handle(endpoint)
```

The frontend can now select the `assistant` agent through any AG-UI client. A
CopilotKit React application uses `runtimeUrl="/api/copilotkit"` and
`agent="assistant"` on its `CopilotKit` provider.

## Runs and concurrency

Different threads run concurrently on one shared agent instance; a second run
on the same user and thread is refused with `THREAD_BUSY`. ADK closes every
toolset after each run, so give roots that share a closable toolset (or keep
per-run state) per-run instances with a factory
(`agent: () => new Workflow(...)`), or pass `runner:` to bring a fully
configured Runner. Failures after the client disconnected go to `logger`
(default `console`).

## Supported integration behavior

* Streaming assistant messages and lifecycle events
* Backend and frontend tool calls
* AG-UI state snapshots and RFC 6902 state deltas
* ADK input, confirmation, and credential requests as resumable interrupts.
  A tool that raises its own confirmation at runtime must also answer `true`
  from `checkRequireConfirmation` (or declare `requireConfirmation` on a
  `FunctionTool`), because ADK 2.x binds an approval to the tool it names.
* Restored message history with stable message IDs
* Provider/model token usage when ADK reports it
* A bare ADK `Workflow` as the `Runner` root (its workflow nodes are reported
  as sub-agents and their frontend tools are discovered)
* The AG-UI subagent protocol for ADK multi-agent trees (see below)

The integration is server-only. Never import `@ag-ui/adk-js` or `@google/adk`
from a browser component. See the
[live Dojo examples](https://dojo.ag-ui.com/adk-js/feature/agentic_chat?openCopilot=true)
for tools, shared state, generative UI, and interrupts.

## Sub-agents

`subagents: "steps"` emits `STEP_STARTED` / `STEP_FINISHED` (`agent:<name>`) and
`CUSTOM` `MultiAgentHandoff` events around ADK sub-agent work — safe for every
client and what the Dojo multi-agent page reads. `subagents: "attributed"` adds
the AG-UI subagent protocol (`SUBAGENT_STARTED/FINISHED/ERROR`, `subagentRunId`
on events, messages, and interrupts, continuation of a suspended sub-agent under
the same id on resume); the consuming client needs `@ag-ui/client` 1.x,
because older clients reject those event types before any application code
runs. The default is `off`.


# AG-UI Overview
Source: https://docs.ag-ui.com/introduction

# The Agent–User Interaction (AG-UI) Protocol

AG-UI is an **open**, **lightweight**, **event-based** protocol that standardizes how AI agents connect to user-facing applications.

AG-UI is designed to be the general-purpose, bi-directional connection between a user-facing application and any agentic backend.

Built for simplicity and flexibility, it standardizes how agent state, UI intents, and user interactions flow between your model/agent runtime and user-facing frontend applications—to allow application developers to ship reliable, debuggable, user‑friendly agentic features fast while focusing on application needs and avoiding complex ad-hoc wiring.

![AG-UI Overview](https://mintcdn.com/tawkitai/p1KIIAcVU0goF39y/images/ag-ui-overview-with-partners.png?fit=max\&auto=format\&n=p1KIIAcVU0goF39y\&q=85\&s=62e8ee85a2e1623d1bfbbea76227ca99)

***

## Agentic Protocols

> [!NOTE]
>
> **Confused about "A2UI" and "AG-UI"?**  That's understandable!  Despite the naming similarities, they are quite different and work well together.  A2UI is a [generative UI specification](./concepts/generative-ui-specs) - allowing agents to deliver UI widgets, where AG-UI is the Agent↔User Interaction protocol - which connects an agentic frontend to any agentic backend.  [Learn more](https://copilotkit.ai/ag-ui-and-a2ui)

AG-UI is one of three prominent open [agentic protocols](./agentic-protocols).

| **Layer** | **Protocol / Example** | **Purpose** |
| - | - | - |
| **Agent ↔ User Interaction** | **AG-UI (Agent–User Interaction Protocol)** | The open, event-based standard that connects agents to user-facing applications — enabling real-time, multimodal, interactive experiences. |
| **Agent ↔ Tools & Data** | **MCP (Model Context Protocol)** | Open standard (originated by Anthropic) that lets agents securely connect to external systems — tools, workflows, and data sources. |
| **Agent ↔ Agent** | **A2A (Agent to Agent)** | Open standard (originated by Google) which defines how agents coordinate and share work across distributed agentic systems. |

***

## Building blocks (today & upcoming)

Streaming chat

Live token and event streaming for responsive multi turn sessions, with cancel and resume.

Multimodality

Typed attachments and real time media (files, images, audio, transcripts); supports voice, previews, annotations, provenance.

Generative UI, static

Render model output as stable, typed components under app control.

Generative UI, declarative

Small declarative language for constrained yet open-ended agent UIs; agents propose trees and constraints, the app validates and mounts.

Shared state

(Read-only & read-write). Typed store shared between agent and app, with streamed event-sourced diffs and conflict resolution for snappy collaboration.

Thinking steps

Visualize intermediate reasoning from traces and tool events; no raw chain of thought.

Frontend tool calls

Typed handoffs from agent to frontend-executed actions, and back.

Backend tool rendering

Visualize backend tool outputs in app and chat, emit side effects as first-class events.

Interrupts (human in the loop)

Pause, approve, edit, retry, or escalate mid flow without losing state.

Sub-agents and composition

Nested delegation with scoped state, tracing, and cancellation.

Agent steering

Dynamically redirect agent execution with real-time user input to guide behavior and outcomes.

Tool output streaming

Stream tool results and logs so UIs can render long-running effects in real time.

Custom events

Open-ended data exchange for needs not covered by the protocol.

***

## Why Agentic Apps need AG-UI

Agentic applications break the simple request/response model that dominated frontend-backend development in the pre-agentic era: a client makes a request, the server returns data, the client renders it, and the interaction ends.

#### The requirements of user‑facing agents

While agents are just software, they exhibit characteristics that make them challenging to serve behind traditional REST/GraphQL APIs:

* Agents are **long‑running** and **stream** intermediate work—often across multi‑turn sessions.
* Agents are **nondeterministic** and can **control application UI nondeterministically**.
* Agents simultanously mix **structured + unstructured IO** (e.g. text & voice, alongside tool calls and state updates).
* Agents need user-interactive **composition**: e.g. they may call sub‑agents, often recursively.
* And more...

AG-UI is an event-based protocol that enables dynamic communication between agentic frontends and backends. It builds on top of the foundational protocols of the web (HTTP, WebSockets) as an abstraction layer designed for the agentic age—bridging the gap between traditional client-server architectures and the dynamic, stateful nature of AI agents.

***

## AG-UI in Action

<video>
  <source type="video/mp4" />

  Your browser does not support the video tag.
</video>

You can see demo apps of the AG-UI features with the framework of your choice, with preview, code, and walkthrough docs in the [AG-UI Dojo](https://dojo.ag-ui.com/)

***

## Supported Integrations

AG-UI was born from CopilotKit's initial **partnership** with LangChain and CrewAI - and brings the incredibly popular agent-user-interactivity infrastructure to the wider agentic ecosystem.

**1st party** = the platforms that have AG‑UI built in and provide documentation for guidance.

### Direct to LLM

| Framework | Status | AG-UI Resources |
| :- | - | - |
| Direct to LLM | Supported | [Docs](https://docs.copilotkit.ai/direct-to-llm) |

### Agent Framework - Partnerships

| Framework | Status | AG-UI Resources |
| :- | - | - |
| [LangChain](https://www.langchain.com/langgraph) | Supported | [Docs](https://docs.copilotkit.ai/langgraph/), [Demos](https://dojo.ag-ui.com/langgraph-fastapi/feature/shared_state) |
| [CrewAI](https://crewai.com/) | Supported | [Docs](https://docs.copilotkit.ai/crewai-flows), [Demos](https://dojo.ag-ui.com/crewai/feature/shared_state) |

### Agent Framework - 1st Party

| Framework | Status | AG-UI Resources |
| :- | - | - |
| [Microsoft Agent Framework](https://azure.microsoft.com/en-us/blog/introducing-microsoft-agent-framework/) | Supported | [Docs](https://docs.copilotkit.ai/microsoft-agent-framework), [Demos](https://dojo.ag-ui.com/microsoft-agent-framework-dotnet/feature/shared_state) |
| [Google ADK](https://google.github.io/adk-docs/get-started/) | Supported | [Docs](https://docs.copilotkit.ai/adk), [Demos](https://dojo.ag-ui.com/adk-middleware/feature/shared_state?openCopilot=true) |
| [Google ADK (JavaScript)](https://adk.dev/get-started/typescript/) | Supported | [Quickstart](/integrations/google-adk-js), [Demos](https://dojo.ag-ui.com/adk-js/feature/agentic_chat?openCopilot=true) |
| [Google Antigravity](https://github.com/google-antigravity/antigravity-sdk-python) | Supported | [Docs](https://docs.copilotkit.ai/google-antigravity), [Demos](https://dojo.ag-ui.com/antigravity/feature/shared_state) |
| [AWS Strands Agents](https://github.com/strands-agents/sdk-python) | Supported | [Docs](https://docs.copilotkit.ai/aws-strands), [Demos](https://dojo.ag-ui.com/aws-strands/feature/shared_state) |
| [AWS Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-agui-protocol-contract.html) | Supported | [Docs](https://github.com/awslabs/fullstack-solution-template-for-agentcore) |
| [Mastra](https://mastra.ai/) | Supported | [Docs](https://docs.copilotkit.ai/mastra/), [Demos](https://dojo.ag-ui.com/mastra/feature/tool_based_generative_ui) |
| [Pydantic AI](https://github.com/pydantic/pydantic-ai) | Supported | [Docs](https://docs.copilotkit.ai/pydantic-ai/), [Demos](https://dojo.ag-ui.com/pydantic-ai/feature/shared_state) |
| [Agno](https://github.com/agno-agi/agno) | Supported | [Docs](https://docs.copilotkit.ai/agno/), [Demos](https://dojo.ag-ui.com/agno/feature/tool_based_generative_ui) |
| [LlamaIndex](https://github.com/run-llama/llama_index) | Supported | [Docs](https://docs.copilotkit.ai/llamaindex/), [Demos](https://dojo.ag-ui.com/llamaindex/feature/shared_state) |
| [AG2](https://ag2.ai/) | Supported | [Docs](https://docs.copilotkit.ai/ag2/) [Demos](https://dojo.ag-ui.com/ag2/feature/shared_state) |
| [AWS Bedrock Agents](https://aws.amazon.com/bedrock/agents/) | In Progress | – |

### Agent Framework - Community

| Framework | Status | AG-UI Resources |
| :- | - | - |
| [Claude Agent SDK](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/claude-agent-sdk) | Supported | [Demos](https://dojo.ag-ui.com/claude-agent-sdk-python/feature/shared_state) |
| [Claude Managed Agents SDK](https://platform.claude.com/docs/en/managed-agents/overview) | Supported | [Integration](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/claude-managed-agents), [Demos](https://dojo.ag-ui.com/claude-managed-agents-python/feature/tool_based_generative_ui) |
| [Langroid](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/langroid) | Supported | [Demos](https://dojo.ag-ui.com/langroid/feature/shared_state) |
| [Omnara](https://omnara.com) | Supported | [Quickstart](/integrations/omnara), [Integration](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/community/omnara/typescript), [Demos](https://dojo.ag-ui.com/omnara/feature/tool_based_generative_ui) |
| [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/) | Supported | [Integration](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/openai-agents), [Demos](https://dojo.ag-ui.com/openai-agents-python/feature/tool_based_generative_ui) |
| [Cloudflare Agents](https://developers.cloudflare.com/agents/) | Supported | [Integration](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/community/cloudflare-agents) |

### Agent Interaction Protocols

| Protocol | Status | AG-UI Resources | Integrations |
| :- | - | - | - |
| [A2A Middleware](https://a2a-protocol.org/) | Supported | [Docs](https://docs.copilotkit.ai/a2a-protocol) | Partnership |

### Infrastructure / Deployment

| Platform | Status | AG-UI Resources | Integrations |
| :- | - | - | - |
| [Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) | Supported | [Docs](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-agui.html) | 1st Party |

### Specification (standard)

| Framework | Status | AG-UI Resources |
| :- | - | - |
| [Oracle Agent Spec](http://oracle.github.io/agent-spec/) | Supported | [Docs](https://go.copilotkit.ai/copilotkit-oracle-docs), [Demos](https://dojo.ag-ui.com/agent-spec-langgraph/feature/tool_based_generative_ui) |

### Generative UI

| Framework | Status | AG-UI Resources |
| :- | - | - |
| [A2UI](https://github.com/google/A2UI) | Supported | [Docs](./concepts/generative-ui-specs) |
| [MCP Apps](https://blog.modelcontextprotocol.io/posts/2025-11-21-mcp-apps/) | Supported | [Docs](https://docs.copilotkit.ai/generative-ui-specs/mcp-apps) |

### SDKs

| SDK | Status | AG-UI Resources | Integrations |
| :- | - | - | - |
| [Kotlin]() | Supported | [Getting Started](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/sdk/kotlin/overview.mdx) | Community |
| [Golang]() | Supported | [Getting Started](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/sdk/go/overview.mdx) | Community |
| [Dart]() | Supported | [Getting Started](https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/community/dart) | Community |
| [Java]() | Supported | [Getting Started](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/sdk/java/overview.mdx) | Community |
| [Rust]() | Supported | [Getting Started](https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/community/rust/crates/ag-ui-client) | Community |
| [Ruby]() | Supported | [Getting Started](https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/community/ruby) | Community |
| [C++]() | Supported | [GitHub Source](https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/community/c%2B%2B) | Community |
| [.NET]() | Supported | [Getting Started](https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/dotnet/samples/GettingStarted) | Community |
| [Nim]() | In Progress | [PR](https://github.com/ag-ui-protocol/ag-ui/pull/29) | Community |
| [Flowise]() | In Progress | [GitHub Source](https://github.com/ag-ui-protocol/ag-ui/issues/367) | Community |
| [Langflow]() | In Progress | [GitHub Source](https://github.com/ag-ui-protocol/ag-ui/issues/366) | Community |

### Clients

| Client | Status | AG-UI Resources | Integrations |
| :- | - | - | - |
| [CopilotKit](https://github.com/CopilotKit/CopilotKit) | Supported | [Getting Started](https://docs.copilotkit.ai/direct-to-llm/guides/quickstart) | 1st Party |
| [Terminal + Agent]() | Supported | [Getting Started](https://docs.ag-ui.com/quickstart/clients) | Community |
| Chat platforms (Slack, Microsoft Teams) | Supported | [Channels SDK](https://github.com/CopilotKit/channels-sdk), [OpenTag example](https://github.com/CopilotKit/OpenTag) | 1st Party |
| [React Native](https://reactnative.dev/) | Supported | [Example](https://github.com/CopilotKit/CopilotKit/tree/main/examples/v2/react-native/demo) | 1st Party |
| [OpenBot](https://open.bot) | Supported | [Getting Started](https://open.bot/builders), [Source](https://github.com/CopilotKit/OpenBot) | 1st Party |

An AG-UI client does not have to be a web application. The protocol describes an
event stream rather than a rendering target, so a terminal, a mobile app, or a
chat platform can each act as a client.

A chat-platform client is something anyone can build against AG-UI. The
[Channels SDK](https://github.com/CopilotKit/channels-sdk) is one implementation
of it, and [OpenTag](https://github.com/CopilotKit/OpenTag)
is a complete application built on it: a Python LangGraph agent served over AG-UI
into Slack and Microsoft Teams. In that application the agent and its runtime are
self-hosted, while platform credentials and message delivery are handled by
CopilotKit Intelligence — a hosted service, not part of the protocol.

[OpenBot](https://open.bot) is a complete application on the client side of
the protocol: an open-source workspace for AI coworkers that connects to any
AG-UI agent endpoint. Each coworker can get a computer of its own, with a
browser, files and tools, and every action it takes is checked against the
deployment's policy before it runs. You host the application yourself. It
keeps threads and memory in CopilotKit Intelligence, a separate service that
is not part of the protocol, which CopilotKit can host for you or you can run
yourself.

***

## Quick Start

Choose the path that fits your needs:

> [card] [Build agentic applications](/quickstart/applications)
>
> Build agentic applications powered by AG-UI compatible agents.

> [card] [Build new AG-UI integrations](/quickstart/introduction)
>
> Build integrations for new agent frameworks, custom in-house solutions, or use AG-UI without any agent framework.

> [card] [Build AG-UI compatible clients](/quickstart/clients)
>
> Build new clients for AG-UI-compatible agents (web, mobile, slack, messaging, etc.)

## Explore AG-UI

Dive deeper into AG-UI's core concepts and capabilities:

> [card] [Core architecture](/concepts/architecture)
>
> Understand how AG-UI connects agents, protocols, and front-ends

> [card] [Events](/concepts/events)
>
> Learn about AG-UI's event-driven protocol

## Resources

Explore guides, tools, and integrations to help you build, optimize, and extend
your AG-UI implementation. These resources cover everything from practical
development workflows to debugging techniques.

> [card] [Developing with Cursor](/tutorials/cursor)
>
> Use Cursor to build AG-UI implementations faster

> [card] [Troubleshooting AG-UI](/tutorials/debugging)
>
> Fix common issues when working with AG-UI servers and clients

## Contributing

Want to contribute? Check out our
[Contributing Guide](/development/contributing) to learn how you can help
improve AG-UI.

## Support and Feedback

Here's how to get help or provide feedback:

* For bug reports and feature requests related to the AG-UI specification, SDKs,
  or documentation (open source), please
  [create a GitHub issue](https://github.com/ag-ui-protocol/ag-ui/issues)
* For discussions or Q\&A about AG-UI, please join the
  [Discord community](https://discord.gg/Jd3FzfdJa8)
* For production architecture or implementation help, see
  [Production support](/talk-to-us)


# Migrating to 1.0
Source: https://docs.ag-ui.com/migrating-to-1-0

What changes for an application or integration moving to AG-UI 1.0, per SDK — and what does not

AG-UI 1.0 is the first release with a specification behind it: the
[schema](/spec/1.0/schema) is the single source of truth, every SDK's
protocol types are generated from it, and the behavioural rules that used to
live only in the TypeScript client are [written down](/spec/1.0). Most of
what changed is additive. This page is the part that is not — what you have to
touch, per SDK, and what keeps working on its own.

The protocol-level changes are listed in the specification's
[Key Changes](/spec/1.0/changelog); this page does not repeat them, it says
what each one means for code you already have.

## What keeps working

**A 0.x agent keeps working against a 1.0 client.** The TypeScript client
carries an always-on compatibility boundary that translates the retired shapes
it meets on an incoming stream — the five `THINKING_*` events become their
`REASONING_*` equivalents, a legacy `binary` content part becomes the media part
its media type names, and historically accepted whole optional `null` fields
become absent before validation. Every inbound translation warns. These shims
are recorded, with their replacements and their expiry, in
[`DEPRECATIONS.md`](https://github.com/ag-ui-protocol/ag-ui/blob/main/DEPRECATIONS.md).
Their expiry dates are provisional — twelve months from when each shim was
written, re-dated at the 1.0 release if it slips — after which the retired
shapes stop working entirely.

**A 1.0 agent keeps working against a 0.x client.** Everything 1.0 adds —
`RUN_FINISHED.outcome`, the subagent events, `protocolVersion`, activity
events — is optional or is a new event type, and a client from before the
version field ignores what it does not know.

**The wire is the same.** JSON over SSE and the protobuf binding are unchanged
in framing. The field names you send today are the field names 1.0 reads,
with the exceptions on this page.

***

## Producers: declare your version

A 1.0 producer MUST declare the protocol version it speaks on `RUN_STARTED`
([Versioning](/spec/1.0/basic/versioning)). The field is optional in the
schema, because its absence is how a pre-1.0 producer is recognised. That means
no SDK adds it for you when you build the event yourself. Use the SDK's
constant, never a hand-typed string, and never echo the version from
`RunAgentInput.protocolVersion`: the declaration states the producer's own
version.

**Python:** pass `protocol_version` when you construct the event.

```python theme={null}
from ag_ui.core import PROTOCOL_VERSION, RunStartedEvent

RunStartedEvent(
    thread_id=input.thread_id,
    run_id=input.run_id,
    protocol_version=PROTOCOL_VERSION,
)
```

**TypeScript:** set `protocolVersion` on the `RUN_STARTED` object.

```ts theme={null}
import { EventType, PROTOCOL_VERSION, type RunStartedEvent } from "@ag-ui/core";

const runStarted: RunStartedEvent = {
  type: EventType.RUN_STARTED,
  threadId: input.threadId,
  runId: input.runId,
  protocolVersion: PROTOCOL_VERSION,
};
```

**.NET:** `AGUI.Server` builds `RUN_STARTED` for you when it converts a
`ChatResponseUpdate` stream, and that event carries `AGUIProtocol.Version`.
There is nothing to add. If you emit your own `RunStartedEvent` (as an update's
`RawRepresentation`), it passes through unchanged, so set the field yourself:

```csharp theme={null}
new RunStartedEvent
{
    ThreadId = threadId,
    RunId = runId,
    ProtocolVersion = AGUIProtocol.Version,
};
```

**Middlewares and proxies** that pass a producer's `RUN_STARTED` through must
leave its `protocolVersion` untouched. Don't add one, overwrite it, or remove
it. The declaration names what the stream speaks, so a forwarder reports the
original producer's version. Only a layer that translates the stream into a
different version declares the version it emits.

***

## TypeScript

The TypeScript SDK takes the most change of the three, because it is where the
protocol's behaviour was previously defined.

### Omit whole optional null fields

Optional protocol fields must be absent instead of `null`, including `rawEvent`,
`RUN_FINISHED.result`, and `forwardedProps`. `EventEncoder` and outgoing HTTP
inputs omit these fields before transmission. Emit the canonical shape from
in-memory agents too.

Older producers remain compatible for a fixed set of whole optional `null`
fields. Before validation, the client translates each to an absent field and
warns once per field per run for `rawEvent` and `subagentRunId` on any event,
`RUN_STARTED.parentRunId`, `RUN_STARTED.input`, `RUN_FINISHED.result`,
`RUN_FINISHED.outcome.pendingToolCallIds`, `provider`, `reasoningTokens`,
`cachedInputTokens` and `cacheWriteInputTokens` in `RUN_FINISHED.usage[]`,
`RUN_ERROR.usage`, `SUBAGENT_FINISHED.result`, `TOOL_CALL_RESULT.role`,
resume-entry `payload`, media-part `metadata` (`image`, `audio`, `video`,
`document`), tool `parameters`, and `RunAgentInput.forwardedProps`. This applies
to in-memory runs, reconnects, SSE, and protobuf, including messages and input
echoes embedded in events. Subscribers receive the normalized event: for
example, an old `RUN_FINISHED.result: null` becomes an absent result. This is
client tolerance, not a protocol change: producers must still omit these
fields.

Direct schema validation remains strict and does not invoke the client's event
compatibility boundary. Request handlers accepting older `RunAgentInput` values
must locally omit historically accepted optional nulls before calling
`RunAgentInputSchema.parse`: `forwardedProps`, `tools[].parameters`,
`resume[].payload`, and `metadata` on image/audio/video/document parts in
`messages[].content[]`. Do not recursively strip nulls from application data or
remove nulls from fields that already rejected them. CopilotKit's shared
run/connect request parser handles this as a local compatibility exception;
AG-UI does not expose a public request-normalization helper. The existing
`RunAgentInput.state: null` parser tolerance still yields `undefined`.

This compatibility is limited to the fields listed above. Event or message
`metadata: null` remains invalid, as do other optional nulls such as
`TEXT_MESSAGE_START.name`, `RUN_ERROR.code`, `usage[].model`,
`RunAgentInput.parentRunId`, and a `subagentRunId: null` nested in a message. Required JSON payloads
such as `CUSTOM.value`, and null values inside state, metadata, or other
application data, remain valid and are preserved.

### zod is an optional peer dependency of `@ag-ui/core`

`@ag-ui/core`'s main entry is types and constants only and never loads zod.
The validators live on a subpath, and importing them requires zod (`3.25.18`
or newer, or any `4.x`):

```ts theme={null}
// before
import { EventSchemas, UserMessageSchema, EventType } from "@ag-ui/core";

// after
import { EventType } from "@ag-ui/core";
import { EventSchemas, UserMessageSchema } from "@ag-ui/core/schemas";
```

```bash theme={null}
npm install @ag-ui/core          # types only — nothing else to install
npm install @ag-ui/core zod      # if you use the validators
```

Every validator moves, including the historic aliases (`EventSchemas`, the
`*InputPartSchema` names, `OptionalMetadataSchema`) and the capability
schemas. `@ag-ui/client` no longer re-exports them either — it re-exports
core's main entry, and they are not on it. `@ag-ui/client` itself still
needs zod, because its enforcement stage validates with it. It takes zod as a
peer dependency (as do `@ag-ui/encoder` and `@ag-ui/proto`), so install zod
alongside it:

```bash theme={null}
npm install @ag-ui/client zod
```

### Unknown material no longer reaches your code

The client has one enforcement stage, after middleware, on every path. An
event whose type nothing recognises is dropped with a warning. An unknown
property on a known event is stripped with a warning naming its path. A
*malformed* value on a field the protocol defines — a number where a string
belongs — fails the run, as it always did.

If you were reading a non-standard property off an event in a subscriber, it
is gone before the subscriber sees it. The sanctioned channel for extra data
is `metadata`, which is open by key on every event and message and is never
stripped.

The same applies to what you send: unknown keys on `RunAgentInput` are
stripped before transmission. The field that exists for exactly that purpose
is `forwardedProps`, which carries any JSON to the agent untouched.

### Behaviour that is stricter in 1.0

Two rules the client used to apply loosely, or on one path only, now apply
everywhere. Each of them turns something that quietly succeeded into a run
that fails.

**Reasoning open/close discipline is verified.** A `REASONING_MESSAGE_CONTENT`
or `REASONING_MESSAGE_END` naming a message nothing opened, a reasoning span
closed without being opened, and a span or message still open when the run
finishes all fail the run. Orphaned fragments and reopens were rejected for
`THINKING_*` before 1.0; failing the run for a span or message left open at
`RUN_FINISHED` is new, and matches what text messages and tool calls already
did. Spans and reasoning messages are separate namespaces — unlike
`THINKING_*`, a reasoning message does not have to sit inside a span, and a
`REASONING_START` id does not open a reasoning message.

**The enforcement guarantee holds on every path.** Unknown material is
stripped *with* a warning and a malformed known value is fatal — and that is
now true with middleware installed and over the protobuf binding, not only on
the plain SSE path. Material that used to vanish silently on those paths —
an unrecognised property on a chunk expanded inside a middleware chain, an
unknown message role or patch operation crossing the protobuf decoder — now
rides through to enforcement and is reported where it is dropped.

**`RUN_ERROR` is unchanged, and that is deliberate.** A producer-sent
`RUN_ERROR` is a well-formed stream — an agent honestly reporting that its run
failed is not a protocol violation — so the client accepts it: the event is
delivered to `onRunErrorEvent`, the stream continues, and `runAgent()`
resolves, exactly as in 0.x. A `RUN_STARTED` after a `RUN_ERROR` begins a new
run in the same stream, and everything that run produces is applied. If you
need a rejected promise when a run reports its own failure, raise it from your
own `onRunErrorEvent` subscriber; the client will not do it for you.

### Retired from the public API

* The five `THINKING_*` events — enum members, types, schemas, factories.
  Emit `REASONING_*`; incoming `THINKING_*` streams are still translated by
  the boundary above.
* `BinaryInputContent` (`{ type: "binary" }`). Use the media parts — `image`,
  `audio`, `video`, `document` — with a `source`. Incoming legacy parts are
  still translated.
* `stripUnknown` and `StripResult` from `@ag-ui/client`. They were the
  enforcement stage's internals.

### Renames and type changes

* `SubAgentInfo` → `SubagentInfo`, and `multiAgent.subAgents` → `subagents`
  on `AgentCapabilities`. The wire key changes with it and there is no alias:
  a declaration still carrying `subAgents` has that key treated as unknown.
  The protocol spells the word as one everywhere (`subagentRunId`).
* `RunAgentInput.tools` and `.context` are non-optional on the TypeScript
  type. Absent on the wire still means empty; the SDK presents it as `[]` so
  nothing downstream has to narrow.
* `AbstractAgent.maxVersion` is deprecated in favour of `maxProtocolVersion`.
  An override of the old name still works and warns once per process.
* The content parts are named by what they are, not by direction:
  `InputContent` → `ContentPart`, `TextInputContent` → `TextPart`,
  `ImageInputContent` → `ImagePart` (audio, video, document alike),
  `InputContentSource` → `PartSource`, `InputContentDataSource` →
  `DataSource`, `InputContentUrlSource` → `UrlSource`, with the matching
  `...Schema` validators. The old names are exported as deprecated aliases of
  the same types and validators, so nothing breaks; the wire `type` values are
  unchanged.
* `PartSource` has a third arm, `FileSource` (`type: "file"`): a handle the
  model provider issued for bytes already uploaded to it. Code that switches
  exhaustively on `source.type` needs a case for it. Never treat its `value`
  as a URL; if your agent cannot hand the handle to its provider, skip the
  part with a warning, as for any part the model cannot take.
* `ToolMessage.content` and `ToolCallResultEvent.content` are
  `string | ContentPart[]`, as `UserMessage.content` already was. Code that
  passed a tool result straight into a string slot narrows it first;
  `contentToText()` from `@ag-ui/core` gives the text parts concatenated and
  `contentHasMedia()` says whether that flattening would lose anything. The
  legacy `ActionExecutionResult` bridge flattens this way and warns.
* Every content part has an optional `id`, and `TextPart` has the optional
  `metadata` the media parts already had.
* `execution.maxIterations` and `maxExecutionTime` on capabilities validate as
  non-negative integers within JavaScript's safe range.

### New, and worth knowing

The client declares `protocolVersion: "1.0"` on every `RunAgentInput` and
reads the producer's answer on `RUN_STARTED`, warning when a producer speaks
a newer or uninterpretable version. Pinning `maxProtocolVersion` below this
client package's own version omits the field, for a peer whose parser would
reject an unknown member.

Protobuf decoding merges repeated occurrences of a singular message field,
including nested messages, metadata, and run inputs. Later scalar values win,
repeated list entries append in order, and an omitted field preserves its
earlier value. TypeScript and .NET follow the same protobuf merging rules.

***

## Python

The Python SDK is producer-side: it defines the shapes an agent emits. The
changes are narrower, and one of them affects anyone parsing its output.

### Absent fields are omitted, never `null`

A field with no value is left out of the JSON rather than written as `null`.
This shipped ahead of 1.0, in `ag-ui-protocol` 0.1.20, so it is only a
migration step if you are coming from earlier than that — but it is the change
most likely to affect anything that parses an agent's output. A reader doing
`if payload["parentMessageId"] is None` or the equivalent needs
`"parentMessageId" not in payload`. A `null` that *is* a value — under a
metadata key, inside a state snapshot, a JSON Patch `add` of `null` — is
preserved exactly; only a `null` standing in for a whole absent field is gone.

### Generated models replace the hand-written ones

`ag_ui.core` keeps every name it exported except the ones retired and renamed
below, now re-exported from the generated source, and construction is
unchanged: snake\_case keyword arguments, aliases on the wire. Three behaviours
differ:

* Single-value literals (`type`, a fixed `role`) default to their only legal
  value; you no longer spell them.
* Fields with schema defaults (`role` on a text message, `replace` on a
  patch) parse to `None` when absent rather than to a materialised default.
* JSON Patch operations parse to typed operation models. The wire form is
  identical.

Validation stays as tolerant as it was: unknown keys are kept, pydantic's
default coercion applies. The strict contract is the specification's
[fixture corpus](/spec/1.0/schema-files), not the SDK models.

### Read JSON Patch entries as objects

Entries in `StateDeltaEvent.delta` and `ActivityDeltaEvent.patch` are typed
operation models, even when you construct the event with dictionaries. Replace
dictionary reads such as `patch["path"]` and `patch.get("op")` with `patch.path`
and `patch.op`. The JSON sent over the wire is unchanged.

If a patch library or other existing code needs dictionaries, convert each
operation with `model_dump(by_alias=True)`. Keeping aliases enabled preserves
wire keys such as `from` on move and copy operations.

```python theme={null}
from ag_ui.core import StateDeltaEvent

event = StateDeltaEvent(delta=[{"op": "replace", "path": "/count", "value": 1}])
operation = event.delta[0]
assert operation.path == "/count"  # Previously: event.delta[0]["path"]
assert operation.op == "replace"  # Previously: event.delta[0].get("op")

patches = [operation.model_dump(by_alias=True) for operation in event.delta]
assert patches == [{"op": "replace", "path": "/count", "value": 1}]
```

An adapter that supports both older SDK dictionaries and 1.0 models can keep a
dictionary entry as-is and call `model_dump(by_alias=True)` only when the entry
is a model.

### Retired

* `MetadataMixin`, from `ag_ui.core`, `ag_ui.core.types`, and
  `ag_ui.core.events`. Generated protocol models already carry their metadata
  fields, so the separate helper is no longer exported. Remove the import;
  for a custom model that inherited it, inherit `ConfiguredBaseModel` from
  `ag_ui.core.types` and declare `metadata: Optional[Metadata] = None`, importing
  `Optional` from `typing` and `Metadata` from `ag_ui.core`.
* The `THINKING_*` events. Emit `REASONING_*`. There is no producer-side
  shim; the TypeScript client translates old streams on its side.
* `BinaryInputContent` as a *part*: `ContentPart` has no `binary` member, and
  a message carrying one is rejected at `RunAgentInput` validation. The class
  itself stays importable from `ag_ui.core` for one release (see
  `DEPRECATIONS.md`), so an adapter written against 0.x still imports and its
  legacy branch simply never runs; the SDK never constructs one. Use the
  media parts.

### Renamed

* `SubAgentInfo` → `SubagentInfo`; `MultiAgentCapabilities.sub_agents` →
  `subagents` (wire key `subagents`). `SubAgentInfo` remains exported as an
  alias of the same class for one release; the old field and wire key do not.
* `ExecutionCapabilities.max_iterations` and `max_execution_time` now reject
  negative values.
* The content parts are named by what they are, not by direction:
  `InputContent` → `ContentPart`, `TextInputContent` → `TextPart`,
  `ImageInputContent` → `ImagePart` (audio, video, document alike),
  `InputContentSource` → `PartSource`, `InputContentDataSource` →
  `DataSource`, `InputContentUrlSource` → `UrlSource`. The old names remain
  exported from `ag_ui.core` as aliases of the same classes.
* `PartSource` has a third arm, `FileSource` (`type="file"`): a handle the
  model provider issued for bytes already uploaded to it. Code that branches on
  the source class needs a case for it. Never treat its `value` as a URL; if
  your agent cannot hand the handle to its provider, skip the part with a
  warning, as for any part the model cannot take.
* `ToolMessage.content` and `ToolCallResultEvent.content` are
  `Union[str, List[ContentPart]]`, as `UserMessage.content` already was. Code
  that treated a tool result as `str` narrows it first. Every part has an
  optional `id`, and `TextPart` has the optional `metadata` the media parts
  already had.

***

## .NET

The .NET SDK jumps furthest, because it was the last still hand-writing its
protocol types and because it gains a feature the other two already had.

### Generated models replace \~60 hand-written classes

The surface a consumer sees is the one it saw before, minus what the schema
retired: the same sealed classes, the same `[JsonPropertyName]` wire names,
absent members omitted on write. .NET's tolerance of unrecognised material is
unchanged — an unknown property is skipped, as `System.Text.Json` has always
done — so nobody should expect a strictness that is not there.

One behaviour is more tolerant than before: an event *type* the SDK has no
model for is now skipped with a trace warning by both stream readers, rather
than ending the stream. Decoding a single unknown event on its own still
throws `AGUIUnknownEventTypeException`.

### Subagents

`SUBAGENT_STARTED`, `SUBAGENT_FINISHED` and `SUBAGENT_ERROR` have models,
JSON handling and protobuf mappers. `SubagentRunId` is a property on the
events that can carry attribution — not on the base event — so a consumer
that switches on event type reads it from the concrete type. The
[subagent rules](/spec/1.0/events/subagents) say what a consumer must do
with it.

### Retired

* `AGUIBinaryInputContent`, its type constant, and its converter arms. A
  `DataContent` or `UriContent` crossing the Microsoft.Extensions.AI boundary
  becomes the media part its media type names, filename in the part's
  metadata. .NET has no middleware layer and nothing translates an incoming
  legacy part: a `{ "type": "binary" }` part is an unknown discriminator, and
  the converter throws a `JsonException` that fails deserialisation of the
  whole message — and of the snapshot or run input carrying it. A producer
  still emitting the legacy part must be upgraded before a 1.0 .NET consumer
  can read it.

### Renames and type changes

* `SubAgentInfo` → `SubagentInfo`; `MultiAgentCapabilities.SubAgents` →
  `Subagents` (wire key `subagents`). No alias; the old key is skipped.
* `AgentCapabilities.Custom` and `IdentityCapabilities.Metadata` are
  `JsonElement?` rather than `IDictionary<string, object?>?`. Build them with
  `JsonSerializer.SerializeToElement(...)`.
* `ExecutionCapabilities.MaxIterations` and `MaxExecutionTime` are `long?`
  rather than `int?`.
* `Tool.Parameters` and `RunAgentInput.ForwardedProperties` (wire key
  `forwardedProps`) are nullable `JsonElement?`, as the schema says; a
  message's `Id` is a non-nullable string that is always written.
* `AGUIUserContent` → `AGUIContent`: the string-or-parts union is no longer
  the user message's alone. `AGUIToolMessage.Content` and
  `ToolCallResultEvent.Content` are `AGUIContent` rather than `string`; a
  string still assigns implicitly, and reading one back is
  `Content.Value as string` or a walk over its parts. The part classes keep
  their `AGUI...InputContent` names even though the schema renamed them to
  `...Part`. Every part has an optional `Id`, and `AGUITextInputContent` has
  the optional `Metadata` the media parts already had.
* `AGUIInputContentSource` has a third subclass, `AGUIInputContentFileSource`
  (`type: "file"`, constant `AGUIInputContentSourceTypes.File`): a handle the
  model provider issued for bytes already uploaded to it, with optional
  `Provider` and `MimeType`. A `switch` over the source hierarchy needs a case
  for it. Never treat its `Value` as a URL; if your agent cannot hand the
  handle to its provider, skip the part with a warning, as for any part the
  model cannot take.

### AOT

The source-generated serializer context is the only resolver under
ahead-of-time compilation. Tool results are serialized by their runtime type,
and a result of a type the context does not register throws
`NotSupportedException`. `int` is registered explicitly in 1.0 — it had
previously been present only by accident.

***

## Where to look next

* The [Key Changes](/spec/1.0/changelog) page for the protocol-level
  differences, with links into the specification.
* [Capabilities](/spec/1.0/basic/capabilities) for what a declaration
  obliges now that it is specified.
* [Versioning and compatibility](/spec/1.0/basic/versioning) for how a
  1.0 peer talks to an older one.


# Build applications
Source: https://docs.ag-ui.com/quickstart/applications

Build agentic applications utilizing compatible event AG-UI event streams

# Introduction

AG-UI provides a concise, event-driven protocol that lets any agent stream rich,
structured output to any client. It can be used to connect any agentic system to
any client.

A client is defined as any system that can receieve, display, and respond to
AG-UI events. For more information on existing clients and integrations, see
the [integrations](/integrations) page.

# Automatic Setup

AG-UI provides a CLI tool to automatically create or scaffold a new application with any client and server.

```sh theme={null}
npx create-ag-ui-app@latest
```

![](https://copilotkit-public-assets.s3.us-east-1.amazonaws.com/docs/ag-ui/quickstart.gif)

Once the setup is done, start the server with

```sh theme={null}
npm run dev
```

For the CopilotKit example, open [http://localhost:3000](http://localhost:3000) to see the app in action.


# Build clients
Source: https://docs.ag-ui.com/quickstart/clients

Showcase: build a conversational CLI agent from scratch using AG-UI and Mastra

# Introduction

A client implementation allows you to **build conversational applications that
leverage AG-UI's event-driven protocol**. This approach creates a direct
interface between your users and AI agents, demonstrating direct access to the
AG-UI protocol.

A client does not have to be a web application. AG-UI describes an event stream
rather than a rendering target, so anything that can consume those events and
present them to a user is a client: a web app, the terminal client built below, a
mobile app, or a chat platform such as Slack or Microsoft Teams. The
[Channels SDK](https://github.com/CopilotKit/channels-sdk) is one chat-platform
implementation, with [OpenTag](https://github.com/CopilotKit/OpenTag) as a
worked example.

## When to use a client implementation

Building your own client is useful if you want to explore/hack on the AG-UI
protocol. For production use, use a full-featured client like
[CopilotKit](https://copilotkit.ai).

## What you'll build

In this guide, we'll create a CLI client that:

1. Uses the `MastraAgent` from `@ag-ui/mastra`
2. Connects to OpenAI's GPT-4o model
3. Implements a weather tool for real-world functionality
4. Provides an interactive chat interface in the terminal

Let's get started!

## Prerequisites

Before we begin, make sure you have:

* [Node.js](https://nodejs.org/) **22.13.0 or later**
* An **OpenAI API key**
* [pnpm](https://pnpm.io/) package manager

### 1. Provide your OpenAI API key

First, let's set up your API key:

```bash theme={null}
# Set your OpenAI API key
export OPENAI_API_KEY=your-api-key-here
```

### 2. Install pnpm

If you don't have pnpm installed:

```bash theme={null}
# Install pnpm
npm install -g pnpm
```

## Step 1 – Initialize your project

Create a new directory for your AG-UI client:

```bash theme={null}
mkdir my-ag-ui-client
cd my-ag-ui-client
```

Initialize a new Node.js project:

```bash theme={null}
pnpm init
```

### Set up TypeScript and basic configuration

Install TypeScript and essential development dependencies:

```bash theme={null}
pnpm add -D typescript @types/node tsx
```

Create a `tsconfig.json` file:

```json theme={null}
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

Update your `package.json` scripts:

```json theme={null}
{
  "scripts": {
    "start": "tsx src/index.ts",
    "dev": "tsx --watch src/index.ts",
    "build": "tsc",
    "clean": "rm -rf dist"
  }
}
```

## Step 2 – Install AG-UI and dependencies

Install the core AG-UI packages and dependencies:

```bash theme={null}
# Core AG-UI packages
pnpm add @ag-ui/client @ag-ui/core @ag-ui/mastra

# Mastra ecosystem packages
pnpm add @mastra/core @mastra/client-js @mastra/memory @mastra/libsql

# Mastra peer dependencies
pnpm add zod
```

## Step 3 – Create your agent

Let's create a basic conversational agent. Create `src/agent.ts`:

```typescript theme={null}
import { Agent } from "@mastra/core/agent"
import { MastraAgent } from "@ag-ui/mastra"
import { Memory } from "@mastra/memory"
import { LibSQLStore } from "@mastra/libsql"

export const agent = new MastraAgent({
  resourceId: "cliExample",
  agent: new Agent({
    id: "ag-ui-assistant",
    name: "AG-UI Assistant",
    instructions: `
      You are a helpful AI assistant. Be friendly, conversational, and helpful.
      Answer questions to the best of your ability and engage in natural conversation.
    `,
    model: "openai/gpt-4o",
    memory: new Memory({
      storage: new LibSQLStore({
        id: "storage-memory",
        url: "file:./assistant.db",
      }),
    }),
  }),
  threadId: "main-conversation",
})
```

### What's happening in the agent?

1. **MastraAgent** – We wrap a Mastra Agent with the AG-UI protocol adapter
2. **Model Configuration** – We use OpenAI's GPT-4o for high-quality responses
3. **Memory Setup** – We configure persistent memory using LibSQL for
   conversation context
4. **Instructions** – We give the agent basic guidelines for helpful
   conversation

## Step 4 – Create the CLI interface

Now let's create the interactive chat interface. Create `src/index.ts`:

```typescript theme={null}
import * as readline from "readline"
import { agent } from "./agent"
import { randomUUID } from "@ag-ui/client"

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
})

async function chatLoop() {
  console.log("🤖 AG-UI Assistant started!")
  console.log("Type your messages and press Enter. Press Ctrl+D to quit.\n")

  return new Promise<void>((resolve) => {
    const promptUser = () => {
      rl.question("> ", async (input) => {
        if (input.trim() === "") {
          promptUser()
          return
        }
        console.log("")

        // Pause input while processing
        rl.pause()

        // Add user message to conversation
        agent.messages.push({
          id: randomUUID(),
          role: "user",
          content: input.trim(),
        })

        try {
          // Run the agent with event handlers
          await agent.runAgent(
            {}, // No additional configuration needed
            {
              onTextMessageStartEvent() {
                process.stdout.write("🤖 Assistant: ")
              },
              onTextMessageContentEvent({ event }) {
                process.stdout.write(event.delta)
              },
              onTextMessageEndEvent() {
                console.log("\n")
              },
            }
          )
        } catch (error) {
          console.error("❌ Error:", error)
        }

        // Resume input
        rl.resume()
        promptUser()
      })
    }

    // Handle Ctrl+D to quit
    rl.on("close", () => {
      console.log("\n👋 Thanks for using AG-UI Assistant!")
      resolve()
    })

    promptUser()
  })
}

async function main() {
  await chatLoop()
}

main().catch(console.error)
```

### What's happening in the CLI interface?

1. **Readline Interface** – We create an interactive prompt for user input
2. **Message Management** – We add each user input to the agent's conversation
   history
3. **Event Handling** – We listen to AG-UI events to provide real-time feedback
4. **Streaming Display** – We show the agent's response as it's being generated

## Step 5 – Test your assistant

Let's run your new AG-UI client:

```bash theme={null}
pnpm dev
```

You should see:

```
🤖 AG-UI Assistant started!
Type your messages and press Enter. Press Ctrl+D to quit.

>
```

Try asking questions like:

* "Hello! How are you?"
* "What can you help me with?"
* "Tell me a joke"
* "Explain quantum computing in simple terms"

You'll see the agent respond with streaming text in real-time!

## Step 6 – Understanding the AG-UI event flow

Let's break down what happens when you send a message:

1. **User Input** – You type a question and press Enter
2. **Message Added** – Your input is added to the conversation history
3. **Agent Processing** – The agent analyzes your request and formulates a
   response
4. **Response Generation** – The agent streams its response back
5. **Streaming Output** – You see the response appear word by word

### Event types you're handling:

* `onTextMessageStartEvent` – Agent starts responding
* `onTextMessageContentEvent` – Each chunk of the response
* `onTextMessageEndEvent` – Response is complete

## Step 7 – Add tool functionality

Now that you have a working chat interface, let's add some real-world
capabilities by creating tools. We'll start with a weather tool.

### Create your first tool

Let's create a weather tool that your agent can use. Create the directory
structure:

```bash theme={null}
mkdir -p src/tools
```

Create `src/tools/weather.tool.ts`:

```typescript theme={null}
import { createTool } from "@mastra/core/tools"
import { z } from "zod"

interface GeocodingResponse {
  results: {
    latitude: number
    longitude: number
    name: string
  }[]
}

interface WeatherResponse {
  current: {
    time: string
    temperature_2m: number
    apparent_temperature: number
    relative_humidity_2m: number
    wind_speed_10m: number
    wind_gusts_10m: number
    weather_code: number
  }
}

export const weatherTool = createTool({
  id: "get-weather",
  description: "Get current weather for a location",
  inputSchema: z.object({
    location: z.string().describe("City name"),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    feelsLike: z.number(),
    humidity: z.number(),
    windSpeed: z.number(),
    windGust: z.number(),
    conditions: z.string(),
    location: z.string(),
  }),
  execute: async (inputData) => {
    return await getWeather(inputData.location)
  },
})

const getWeather = async (location: string) => {
  const geocodingUrl = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(
    location
  )}&count=1`
  const geocodingResponse = await fetch(geocodingUrl)
  const geocodingData = (await geocodingResponse.json()) as GeocodingResponse

  if (!geocodingData.results?.[0]) {
    throw new Error(`Location '${location}' not found`)
  }

  const { latitude, longitude, name } = geocodingData.results[0]

  const weatherUrl = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m,apparent_temperature,relative_humidity_2m,wind_speed_10m,wind_gusts_10m,weather_code`

  const response = await fetch(weatherUrl)
  const data = (await response.json()) as WeatherResponse

  return {
    temperature: data.current.temperature_2m,
    feelsLike: data.current.apparent_temperature,
    humidity: data.current.relative_humidity_2m,
    windSpeed: data.current.wind_speed_10m,
    windGust: data.current.wind_gusts_10m,
    conditions: getWeatherCondition(data.current.weather_code),
    location: name,
  }
}

function getWeatherCondition(code: number): string {
  const conditions: Record<number, string> = {
    0: "Clear sky",
    1: "Mainly clear",
    2: "Partly cloudy",
    3: "Overcast",
    45: "Foggy",
    48: "Depositing rime fog",
    51: "Light drizzle",
    53: "Moderate drizzle",
    55: "Dense drizzle",
    56: "Light freezing drizzle",
    57: "Dense freezing drizzle",
    61: "Slight rain",
    63: "Moderate rain",
    65: "Heavy rain",
    66: "Light freezing rain",
    67: "Heavy freezing rain",
    71: "Slight snow fall",
    73: "Moderate snow fall",
    75: "Heavy snow fall",
    77: "Snow grains",
    80: "Slight rain showers",
    81: "Moderate rain showers",
    82: "Violent rain showers",
    85: "Slight snow showers",
    86: "Heavy snow showers",
    95: "Thunderstorm",
    96: "Thunderstorm with slight hail",
    99: "Thunderstorm with heavy hail",
  }
  return conditions[code] || "Unknown"
}
```

### What's happening in the weather tool?

1. **Tool Definition** – We use `createTool` from Mastra to define the tool's
   interface
2. **Input Schema** – We specify that the tool accepts a location string
3. **Output Schema** – We define the structure of the weather data returned
4. **API Integration** – We fetch data from Open-Meteo's free weather API
5. **Data Processing** – We convert weather codes to human-readable conditions

### Update your agent

Now let's update our agent to use the weather tool. Update `src/agent.ts`:

```typescript theme={null}
import { weatherTool } from "./tools/weather.tool" // <--- Import the tool

export const agent = new MastraAgent({
  agent: new Agent({
    // ...

    tools: { weatherTool }, // <--- Add the tool to the agent

    // ...
  }),
  threadId: "main-conversation",
})
```

### Update your CLI to handle tools

Update your CLI interface in `src/index.ts` to handle tool events:

```typescript theme={null}
// Add these new event handlers to your agent.runAgent call:
await agent.runAgent(
  {}, // No additional configuration needed
  {
    // ... existing event handlers ...

    onToolCallStartEvent({ event }) {
      console.log("🔧 Tool call:", event.toolCallName)
    },
    onToolCallArgsEvent({ event }) {
      process.stdout.write(event.delta)
    },
    onToolCallEndEvent() {
      console.log("")
    },
    onToolCallResultEvent({ event }) {
      if (event.content) {
        console.log("🔍 Tool call result:", event.content)
      }
    },
  }
)
```

### Test your weather tool

Now restart your application and try asking about weather:

```bash theme={null}
pnpm dev
```

Try questions like:

* "What's the weather like in London?"
* "How's the weather in Tokyo today?"
* "Is it raining in Seattle?"

You'll see the agent use the weather tool to fetch real data and provide
detailed responses!

## Step 8 – Add more functionality

### Create a browser tool

Let's add a web browsing capability. First install the `open` package:

```bash theme={null}
pnpm add open
```

Create `src/tools/browser.tool.ts`:

```typescript theme={null}
import { createTool } from "@mastra/core/tools"
import { z } from "zod"
import { open } from "open"

export const browserTool = createTool({
  id: "open-browser",
  description: "Open a URL in the default web browser",
  inputSchema: z.object({
    url: z.url().describe("The URL to open"),
  }),
  outputSchema: z.object({
    success: z.boolean(),
    message: z.string(),
  }),
  execute: async (inputData) => {
    try {
      await open(inputData.url)
      return {
        success: true,
        message: `Opened ${inputData.url} in your default browser`,
      }
    } catch (error) {
      return {
        success: false,
        message: `Failed to open browser: ${error}`,
      }
    }
  },
})
```

### Update your agent with both tools

Update `src/agent.ts` to include both tools:

```typescript theme={null}
import { Agent } from "@mastra/core/agent"
import { MastraAgent } from "@ag-ui/mastra"
import { Memory } from "@mastra/memory"
import { LibSQLStore } from "@mastra/libsql"
import { weatherTool } from "./tools/weather.tool"
import { browserTool } from "./tools/browser.tool"

export const agent = new MastraAgent({
  resourceId: "cliExample",
  agent: new Agent({
    id: "ag-ui-assistant",
    name: "AG-UI Assistant",
    instructions: `
      You are a helpful assistant with weather and web browsing capabilities.

      For weather queries:
      - Always ask for a location if none is provided
      - Use the weatherTool to fetch current weather data

      For web browsing:
      - Always use full URLs (e.g., "https://www.google.com")
      - Use the browserTool to open web pages

      Be friendly and helpful in all interactions!
    `,
    model: "openai/gpt-4o",
    tools: { weatherTool, browserTool }, // Add both tools
    memory: new Memory({
      storage: new LibSQLStore({
        id: "storage-memory",
        url: "file:./assistant.db",
      }),
    }),
  }),
  threadId: "main-conversation",
})
```

Now you can ask your assistant to open websites: "Open Google for me" or "Show
me the weather website".

## Step 9 – Deploy your client

### Building your client

Create a production build:

```bash theme={null}
pnpm build
```

### Create a startup script

Add to your `package.json`:

```json theme={null}
{
  "bin": {
    "weather-assistant": "./dist/index.js"
  }
}
```

Add a shebang to your built `dist/index.js`:

```javascript theme={null}
#!/usr/bin/env node
// ... rest of your compiled code
```

Make it executable:

```bash theme={null}
chmod +x dist/index.js
```

### Link globally

Install your CLI globally:

```bash theme={null}
pnpm link --global
```

Now you can run `weather-assistant` from anywhere!

## Extending your client

Your AG-UI client is now a solid foundation. Here are some ideas for
enhancement:

### Add more tools

* **Calculator tool** – For mathematical operations
* **File system tool** – For reading/writing files
* **API tools** – For connecting to other services
* **Database tools** – For querying data

### Improve the interface

* **Rich formatting** – Use libraries like `chalk` for colored output
* **Progress indicators** – Show loading states for long operations
* **Configuration files** – Allow users to customize settings
* **Command-line arguments** – Support different modes and options

### Add persistence

* **Conversation history** – Save and restore chat sessions
* **User preferences** – Remember user settings
* **Tool results caching** – Cache expensive API calls

## Share your client

Built something useful? Consider sharing it with the community:

1. **Open source it** – Publish your code on GitHub
2. **Publish to npm** – Make it installable via `npm install`
3. **Create documentation** – Help others understand and extend your work
4. **Join discussions** – Share your experience in the
   [AG-UI GitHub Discussions](https://github.com/orgs/ag-ui-protocol/discussions)

## Conclusion

You've built a complete AG-UI client from scratch! Your weather assistant
demonstrates the core concepts:

* **Event-driven architecture** with real-time streaming
* **Tool integration** for real-world functionality
* **Conversation memory** for context retention
* **Interactive CLI interface** for user engagement

From here, you can extend your client to support any use case – from simple CLI
tools to complex conversational applications. The AG-UI protocol provides the
foundation, and your creativity provides the possibilities.

Happy building! 🚀


# Introduction
Source: https://docs.ag-ui.com/quickstart/introduction

Learn how to get started building an AG-UI integration

<video />

# What is an Integration?

An AG-UI integration makes your agent speak the AG-UI protocol. This means your agent can work with any AG-UI compatible client application - like chat interfaces, copilots, or custom AI tools.

Think of it like adding a universal translator to your agent. Instead of building custom APIs for each client, you implement AG-UI once and instantly work with any compatible application.

Agents integrating with AG-UI can:

* **Stream responses** - Real-time text that appears as it's generated
* **Call client-side tools** - Your agent can use functions and services defined by clients
* **Share state** - Your agent's state is bidirectional shared state
* **Execute universally** - Integrate with any AG-UI compatible client application
* **And much more!** - Check out the full specification [here](/concepts/events).

### When should I make any integration?

If the integration you're looking for is not listed on our [integrations page](/integrations), you'll need to make an integration. We've got a few guides on this below!

However, if you're looking to utilize an existing integration (like LangGraph, CrewAI, Mastra, etc.), you can skip this step and go straight to [building an application](/quickstart/applications).

# Types of Integrations

So you've decided you need an integration! Great, there are **two main ways** to implement an AG-UI integration:

> [card] [Server Implementation](/quickstart/server)
>
> Emit AG-UI events **directly from your agent** or server.

> [card] [Middleware Implementation](/quickstart/middleware)
>
> **Translate existing protocols** and applications to AG-UI events.

### When to use a server implementation

Server implementations allow you to directly emit AG-UI events from your agent or server. If you are not using an
agent framework or haven't created a protocol for your agent framework yet, this is the best way to get started.

Server implementations are also great for:

* Building a **new agent frameworks** from scratch
* **Maximum control** over how and what events are emitted
* Exposing your agent as a **standalone API**

### When to use a middleware implementation

Middleware is the flexible option. It allows you to translate existing protocols and applications to AG-UI events
creating a bridge between your existing system and AG-UI.

Middleware is great for:

* Taking your **existing protocol or API** and **translating it universally**
* Working within the confines of **an existing system or framework**
* **When you don't have direct control** over the agent framework or system


# Middleware
Source: https://docs.ag-ui.com/quickstart/middleware

Connect to existing protocols, in process agents or custom solutions via AG-UI

# Introduction

A middleware implementation allows you to **translate existing protocols and
applications to AG-UI events**. This approach creates a bridge between your
existing system and AG-UI, making it perfect for adding agent capabilities to
current applications.

## When to use a middleware implementation

Middleware is the flexible option. It allows you to translate existing protocols
and applications to AG-UI events creating a bridge between your existing system
and AG-UI.

Middleware is great for:

* Taking your **existing protocol or API** and **translating it universally**
* Working within the confines of **an existing system or framework**
* **When you don't have direct control** over the agent framework or system

## What you'll build

In this guide, we'll create a middleware agent that:

1. Extends the `AbstractAgent` class
2. Connects to OpenAI's GPT-4o model
3. Translates OpenAI responses to AG-UI events
4. Runs in-process with your application

This approach gives you maximum flexibility to integrate with existing codebases
while maintaining the full power of the AG-UI protocol.

Let's get started!

## Prerequisites

Before we begin, make sure you have:

* [Node.js](https://nodejs.org/) **v16 or later**
* An **OpenAI API key**

### 1. Provide your OpenAI API key

First, let's set up your API key:

```bash theme={null}
# Set your OpenAI API key
export OPENAI_API_KEY=your-api-key-here
```

### 2. Install build utilities

Install the following tools:

```bash theme={null}
brew install protobuf
```

```bash theme={null}
npm i nx
```

```bash theme={null}
curl -fsSL https://get.pnpm.io/install.sh | sh -
```

## Step 1 – Scaffold your integration

Start by cloning the repo

```bash theme={null}
git clone git@github.com:ag-ui-protocol/ag-ui.git
cd ag-ui/
```

Copy the middleware-starter template to create your OpenAI integration:

```bash theme={null}
cp -r integrations/middleware-starter integrations/openai
```

### Update metadata

Open `integrations/openai/package.json` and update the fields to match your new
folder:

```json theme={null}
{
  "name": "@ag-ui/openai",
  "author": "Your Name <your-email@example.com>",
  "version": "0.0.1",

  ... rest of package.json
}
```

Next, update the class name inside `integrations/openai/src/index.ts`:

```ts theme={null}
// change the name to OpenAIAgent
export class OpenAIAgent extends AbstractAgent {}
```

Finally, introduce your integration to the dojo by adding it to
`apps/dojo/src/menu.ts`:

```ts theme={null}
// ...
export const menuIntegrations: MenuIntegrationConfig[] = [
  // ...

  {
    id: "openai",
    name: "OpenAI",
    features: ["agentic_chat"],
  },
]
```

And `apps/dojo/src/agents.ts`:

```ts theme={null}
// ...
import { OpenAIAgent } from "@ag-ui/openai"

export const agentsIntegrations: AgentIntegrationConfig[] = [
  // ...

  {
    id: "openai",
    agents: async () => {
      return {
        agentic_chat: new OpenAIAgent(),
      }
    },
  },
]
```

## Step 2 – Add package to dojo dependencies

Open `apps/dojo/package.json` and add the package `@ag-ui/openai`:

```json theme={null}
{
  "name": "demo-viewer",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "@ag-ui/agno": "workspace:*",
    "@ag-ui/langgraph": "workspace:*",
    "@ag-ui/mastra": "workspace:*",
    "@ag-ui/middleware-starter": "workspace:*",
    "@ag-ui/server-starter": "workspace:*",
    "@ag-ui/server-starter-all-features": "workspace:*",
    "@ag-ui/vercel-ai-sdk": "workspace:*",
    "@ag-ui/openai": "workspace:*", <- Add this line

  ... rest of package.json
}
```

## Step 3 – Start the dojo

Now let's see your work in action:

```bash theme={null}
# Install dependencies
pnpm install

# Compile the project and run the dojo
pnpm dev
```

Head over to [http://localhost:3000](http://localhost:3000) and choose
**OpenAI** from the drop-down. You'll see the stub agent replies with **Hello
world!** for now.

Here's what's happening with that stub agent:

```ts theme={null}
// integrations/openai/src/index.ts
import {
  AbstractAgent,
  BaseEvent,
  EventType,
  RunAgentInput,
} from "@ag-ui/client"
import { Observable } from "rxjs"

export class OpenAIAgent extends AbstractAgent {
  run(input: RunAgentInput): Observable<BaseEvent> {
    const messageId = Date.now().toString()
    return new Observable<BaseEvent>((observer) => {
      observer.next({
        type: EventType.RUN_STARTED,
        threadId: input.threadId,
        runId: input.runId,
      } as any)

      observer.next({
        type: EventType.TEXT_MESSAGE_START,
        messageId,
      } as any)

      observer.next({
        type: EventType.TEXT_MESSAGE_CONTENT,
        messageId,
        delta: "Hello world!",
      } as any)

      observer.next({
        type: EventType.TEXT_MESSAGE_END,
        messageId,
      } as any)

      observer.next({
        type: EventType.RUN_FINISHED,
        threadId: input.threadId,
        runId: input.runId,
      } as any)

      observer.complete()
    })
  }
}
```

## Step 4 – Bridge OpenAI with AG-UI

Let's transform our stub into a real agent that streams completions from OpenAI.

### Install the OpenAI SDK

First, we need the OpenAI SDK:

```bash theme={null}
cd integrations/openai
pnpm install openai
```

### AG-UI recap

An AG-UI agent extends `AbstractAgent` and emits a sequence of events to signal:

* lifecycle events (`RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`)
* content events (`TEXT_MESSAGE_*`, `TOOL_CALL_*`, and more)

### Implement the streaming agent

Now we'll transform our stub agent into a real OpenAI integration. The key
difference is that instead of sending a hardcoded "Hello world!" message, we'll
connect to OpenAI's API and stream the response back through AG-UI events.

The implementation follows the same event flow as our stub, but we'll add the
OpenAI client initialization in the constructor and replace our mock response
with actual API calls. We'll also handle tool calls if they're present in the
response, making our agent fully capable of using functions when needed.

```typescript theme={null}
// integrations/openai/src/index.ts
import {
  AbstractAgent,
  RunAgentInput,
  EventType,
  BaseEvent,
} from "@ag-ui/client"
import { Observable } from "rxjs"

import { OpenAI } from "openai"

export class OpenAIAgent extends AbstractAgent {
  private openai: OpenAI

  constructor(openai?: OpenAI) {
    super()
    // Initialize OpenAI client - uses OPENAI_API_KEY from environment if not provided
    this.openai = openai ?? new OpenAI()
  }

  run(input: RunAgentInput): Observable<BaseEvent> {
    return new Observable<BaseEvent>((observer) => {
      // Same as before - emit RUN_STARTED to begin
      observer.next({
        type: EventType.RUN_STARTED,
        threadId: input.threadId,
        runId: input.runId,
      } as any)

      // NEW: Instead of hardcoded response, call OpenAI's API
      this.openai.chat.completions
        .create({
          model: "gpt-4o",
          stream: true, // Enable streaming for real-time responses
          // Convert AG-UI tools format to OpenAI's expected format
          tools: input.tools.map((tool) => ({
            type: "function",
            function: {
              name: tool.name,
              description: tool.description,
              parameters: tool.parameters,
            },
          })),
          // Transform AG-UI messages to OpenAI's message format
          messages: input.messages.map((message) => ({
            role: message.role as any,
            content: message.content ?? "",
            // Include tool calls if this is an assistant message with tools
            ...(message.role === "assistant" && message.toolCalls
              ? {
                  tool_calls: message.toolCalls,
                }
              : {}),
            // Include tool call ID if this is a tool result message
            ...(message.role === "tool"
              ? { tool_call_id: message.toolCallId }
              : {}),
          })),
        })
        .then(async (response) => {
          const messageId = Date.now().toString()

          // NEW: Stream each chunk from OpenAI's response
          for await (const chunk of response) {
            // Handle text content chunks
            if (chunk.choices[0].delta.content) {
              observer.next({
                type: EventType.TEXT_MESSAGE_CHUNK, // Chunk events open and close messages automatically
                messageId,
                delta: chunk.choices[0].delta.content,
              } as any)
            }
            // Handle tool call chunks (when the model wants to use a function)
            else if (chunk.choices[0].delta.tool_calls) {
              let toolCall = chunk.choices[0].delta.tool_calls[0]

              observer.next({
                type: EventType.TOOL_CALL_CHUNK,
                toolCallId: toolCall.id,
                toolCallName: toolCall.function?.name,
                parentMessageId: messageId,
                delta: toolCall.function?.arguments,
              } as any)
            }
          }

          // Same as before - emit RUN_FINISHED when complete
          observer.next({
            type: EventType.RUN_FINISHED,
            threadId: input.threadId,
            runId: input.runId,
          } as any)

          observer.complete()
        })
        // NEW: Handle errors from the API
        .catch((error) => {
          observer.next({
            type: EventType.RUN_ERROR,
            message: error.message,
          } as any)

          observer.error(error)
        })
    })
  }
}
```

### What happens under the hood?

Let's break down what your agent is doing:

1. **Setup** – We create an OpenAI client and emit `RUN_STARTED`
2. **Request** – We send the user's messages to `chat.completions` with
   `stream: true`
3. **Streaming** – We forward each chunk as either `TEXT_MESSAGE_CHUNK` or
   `TOOL_CALL_CHUNK`
4. **Finish** – We emit `RUN_FINISHED` (or `RUN_ERROR` if something goes wrong)
   and complete the observable

## Step 5 – Chat with your agent

Reload the dojo page and start typing. You'll see GPT-4o streaming its answer in
real-time, word by word.

## Bridging AG-UI to any protocol

The pattern you just implemented—translate inputs, forward streaming chunks,
emit AG-UI events—works for virtually any backend:

* REST or GraphQL APIs
* WebSockets
* IoT protocols such as MQTT

## Connect your agent to a frontend

Tools like [CopilotKit](https://docs.copilotkit.ai) already understand AG-UI and
provide plug-and-play React components. Point them at your agent endpoint and
you get a full-featured chat UI out of the box.

## Share your integration

Did you build a custom adapter that others could reuse? We welcome community
contributions!

1. Fork the [AG-UI repository](https://github.com/ag-ui-protocol/ag-ui)
2. Add your package under `integrations`. See
   [Contributing](../development/contributing) for more details and naming
   conventions.
3. Open a pull request describing your use-case and design decisions

If you have questions, need feedback, or want to validate an idea first, start a
thread in the GitHub Discussions board:
[AG-UI GitHub Discussions board](https://github.com/orgs/ag-ui-protocol/discussions).

Your integration might ship in the next release and help the entire AG-UI
ecosystem grow.

## Conclusion

You now have a fully-functional AG-UI adapter for OpenAI and a local playground
to test it. From here you can:

* Add tool calls to enhance your agent
* Publish your integration to npm
* Bridge AG-UI to any other model or service

Happy building!


# Server
Source: https://docs.ag-ui.com/quickstart/server

Implement AG-UI compatible servers

# Introduction

A server implementation allows you to **emit AG-UI events directly from your
agent or server**. This approach is ideal when you're building a new agent from
scratch or want a dedicated service for your agent capabilities.

## When to use a server implementation

Server implementations allow you to directly emit AG-UI events from your agent
or server. If you are not using an agent framework or haven't created a protocol
for your agent framework yet, this is the best way to get started.

Server implementations are also great for:

* Building a **new agent frameworks** from scratch
* **Maximum control** over how and what events are emitted
* Exposing your agent as a **standalone API**

## What you'll build

In this guide, we'll create a standalone HTTP server that:

1. Accepts AG-UI protocol requests
2. Connects to OpenAI's GPT-4o model
3. Streams responses back as AG-UI events
4. Handles tool calls and state management

Let's get started!

## Prerequisites

Before we begin, make sure you have:

* [Python](https://www.python.org/downloads/) **3.12 or later**
* [Poetry](https://python-poetry.org/docs/#installation) for dependency
  management
* An **OpenAI API key**

### 1. Provide your OpenAI API key

First, let's set up your API key:

```bash theme={null}
# Set your OpenAI API key
export OPENAI_API_KEY=your-api-key-here
```

### 2. Install build utilities

Install the following tools:

```bash theme={null}
brew install protobuf
```

```bash theme={null}
npm i nx
```

```bash theme={null}
curl -fsSL https://get.pnpm.io/install.sh | sh -
```

## Step 1 – Scaffold your server

Start by cloning the repo:

```bash theme={null}
git clone git@github.com:ag-ui-protocol/ag-ui.git
cd ag-ui
```

Copy the server-starter template to create your OpenAI server:

```bash theme={null}
cp -r integrations/server-starter integrations/openai-server
```

### Update metadata

Open `integrations/openai-server/package.json` and update the fields to match
your new folder:

```json theme={null}
{
  "name": "@ag-ui/openai-server",
  "author": "Your Name <your-email@example.com>",
  "version": "0.0.1",

  ... rest of package.json
}
```

Next, update the class name inside `integrations/openai-server/src/index.ts`:

```ts theme={null}
// Change the name to OpenAIServerAgent to add a minimal middleware for your integration.
// You can use this later on to add configuration etc.
export class OpenAIServerAgent extends HttpAgent {}
```

Finally, introduce your integration to the dojo by adding it to
`apps/dojo/src/menu.ts`:

```ts theme={null}
// ...
export const menuIntegrations: MenuIntegrationConfig[] = [
  // ...

  {
    id: "openai-server",
    name: "OpenAI Server",
    features: ["agentic_chat"],
  },
]
```

And `apps/dojo/src/agents.ts`:

```ts theme={null}
// ...
import { OpenAIServerAgent } from "@ag-ui/openai-server"

export const agentsIntegrations: AgentIntegrationConfig[] = [
  // ...

  {
    id: "openai-server",
    agents: async () => {
      return {
        agentic_chat: new OpenAIServerAgent(),
      }
    },
  },
]
```

## Step 2 – Add package to dojo dependencies

Open `apps/dojo/package.json` and add `"@ag-ui/openai-server": "workspace:*"` to
the `dependencies` object:

```json theme={null}
{
  "name": "demo-viewer",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "@ag-ui/agno": "workspace:*",
    "@ag-ui/langgraph": "workspace:*",
    "@ag-ui/mastra": "workspace:*",
    "@ag-ui/middleware-starter": "workspace:*",
    "@ag-ui/server-starter": "workspace:*",
    "@ag-ui/server-starter-all-features": "workspace:*",
    "@ag-ui/vercel-ai-sdk": "workspace:*",
    "@ag-ui/openai-server": "workspace:*"
  }
}
```

## Step 3 – Start the dojo and server

Now let's see your work in action. First, start your Python server:

```bash theme={null}
cd integrations/openai-server/server/python
poetry install && poetry run dev
```

In another terminal, start the dojo:

```bash theme={null}
# Install dependencies
pnpm install

# Compile the project and run the dojo
pnpm dev
```

Head over to [http://localhost:3000](http://localhost:3000) and choose
**OpenAI** from the drop-down. You'll see the stub server replies with **Hello
world!** for now.

Here's what's happening with that stub server:

```python theme={null}
# integrations/openai-server/server/python/example_server/__init__.py
@app.post("/")
async def agentic_chat_endpoint(input_data: RunAgentInput, request: Request):
    """Agentic chat endpoint"""
    # Get the accept header from the request
    accept_header = request.headers.get("accept")

    # Create an event encoder to properly format SSE events
    encoder = EventEncoder(accept=accept_header)

    async def event_generator():

        # Send run started event
        yield encoder.encode(
          RunStartedEvent(
            type=EventType.RUN_STARTED,
            thread_id=input_data.thread_id,
            run_id=input_data.run_id
          ),
        )

        message_id = str(uuid.uuid4())

    return StreamingResponse(
        event_generator(),
        media_type="text/event-stream"
    )

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

Awesome! We are already sending a `RunStartedEvent`, which is the first step
toward an AG-UI compliant endpoint. Now let's make it do something useful.

## Implementing Basic Chat

Let's enhance our endpoint to call OpenAI's API and stream the responses back as
AG-UI events:

```python theme={null}
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from ag_ui.core import (
    RunAgentInput,
    EventType,
    RunStartedEvent,
    RunFinishedEvent,
    TextMessageStartEvent,
    TextMessageContentEvent,
    TextMessageEndEvent
)
from ag_ui.encoder import EventEncoder
import uuid
from openai import OpenAI
import os

app = FastAPI(title="AG-UI Endpoint")

# Initialize OpenAI client
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

@app.post("/")
async def agentic_chat_endpoint(input_data: RunAgentInput, request: Request):
    accept_header = request.headers.get("accept")
    encoder = EventEncoder(accept=accept_header)

    async def event_generator():
        # Send run started event
        yield encoder.encode(
            RunStartedEvent(
                type=EventType.RUN_STARTED,
                thread_id=input_data.thread_id,
                run_id=input_data.run_id
            )
        )

        # Convert AG-UI messages to OpenAI messages format
        openai_messages = []
        for msg in input_data.messages:
            if msg.role in ["user", "system", "assistant"]:
                openai_messages.append({
                    "role": msg.role,
                    "content": msg.content or ""
                })

        # Call OpenAI with streaming enabled
        stream = client.chat.completions.create(
            model="gpt-4o",
            stream=True,
            messages=openai_messages,
        )

        # Generate a message ID for the assistant's response
        message_id = str(uuid.uuid4())

        # Send text message start event
        yield encoder.encode(
            TextMessageStartEvent(
                type=EventType.TEXT_MESSAGE_START,
                message_id=message_id,
                role="assistant"
            )
        )

        # Process the streaming response and send content events
        for chunk in stream:
            if (chunk.choices and
                len(chunk.choices) > 0 and
                chunk.choices[0].delta and
                hasattr(chunk.choices[0].delta, 'content') and
                chunk.choices[0].delta.content):

                content = chunk.choices[0].delta.content
                yield encoder.encode(
                    TextMessageContentEvent(
                        type=EventType.TEXT_MESSAGE_CONTENT,
                        message_id=message_id,
                        delta=content
                    )
                )

        # Send text message end event
        yield encoder.encode(
            TextMessageEndEvent(
                type=EventType.TEXT_MESSAGE_END,
                message_id=message_id
            )
        )

        # Send run finished event
        yield encoder.encode(
            RunFinishedEvent(
                type=EventType.RUN_FINISHED,
                thread_id=input_data.thread_id,
                run_id=input_data.run_id
            )
        )

    return StreamingResponse(
        event_generator(),
        media_type=encoder.get_content_type()
    )
```

## Step 4 – Bridge OpenAI with AG-UI

Let's transform our stub into a real server that streams completions from
OpenAI.

### Install the OpenAI SDK

First, we need the OpenAI SDK:

```bash theme={null}
cd integrations/openai-server/server/python
poetry add openai
```

### AG-UI recap

An AG-UI server implements the endpoint and emits a sequence of events to
signal:

* lifecycle events (`RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`)
* content events (`TEXT_MESSAGE_*`, `TOOL_CALL_*`, and more)

### Implement the streaming server

Now we'll transform our stub server into a real OpenAI integration. The key
difference is that instead of sending a hardcoded "Hello world!" message, we'll
connect to OpenAI's API and stream the response back through AG-UI events.

The implementation follows the same event flow as our stub, but we'll add the
OpenAI client initialization and replace our mock response with actual API
calls. We'll also handle tool calls if they're present in the response, making
our server fully capable of using functions when needed.

```python theme={null}
import os
import uuid
import uvicorn
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from ag_ui.core import (
    RunAgentInput,
    EventType,
    RunStartedEvent,
    RunFinishedEvent,
    RunErrorEvent,
    TextMessageChunkEvent,
    ToolCallChunkEvent,
)
from ag_ui.encoder import EventEncoder
from openai import OpenAI

app = FastAPI(title="AG-UI OpenAI Server")

# Initialize OpenAI client - uses OPENAI_API_KEY from environment
client = OpenAI()

@app.post("/")
async def agentic_chat_endpoint(input_data: RunAgentInput, request: Request):
    """OpenAI agentic chat endpoint"""
    accept_header = request.headers.get("accept")
    encoder = EventEncoder(accept=accept_header)

    async def event_generator():
        try:
            yield encoder.encode(
                RunStartedEvent(
                    type=EventType.RUN_STARTED,
                    thread_id=input_data.thread_id,
                    run_id=input_data.run_id
                )
            )

            # Call OpenAI's API with streaming enabled
            stream = client.chat.completions.create(
                model="gpt-4o",
                stream=True,
                # Convert AG-UI tools format to OpenAI's expected format
                tools=[
                    {
                        "type": "function",
                        "function": {
                            "name": tool.name,
                            "description": tool.description,
                            "parameters": tool.parameters,
                        }
                    }
                    for tool in input_data.tools
                ] if input_data.tools else None,
                # Transform AG-UI messages to OpenAI's message format
                messages=[
                    {
                        "role": message.role,
                        "content": message.content or "",
                        # Include tool calls if this is an assistant message with tools
                        **({"tool_calls": message.tool_calls} if message.role == "assistant" and hasattr(message, 'tool_calls') and message.tool_calls else {}),
                        # Include tool call ID if this is a tool result message
                        **({"tool_call_id": message.tool_call_id} if message.role == "tool" and hasattr(message, 'tool_call_id') else {}),
                    }
                    for message in input_data.messages
                ],
            )

            message_id = str(uuid.uuid4())

            # Stream each chunk from OpenAI's response
            for chunk in stream:
                # Handle text content chunks
                if chunk.choices[0].delta.content:
                    yield encoder.encode(
                        TextMessageChunkEvent(
                            type=EventType.TEXT_MESSAGE_CHUNK,
                            message_id=message_id,
                            delta=chunk.choices[0].delta.content,
                        )
                    )
                # Handle tool call chunks
                elif chunk.choices[0].delta.tool_calls:
                    tool_call = chunk.choices[0].delta.tool_calls[0]

                    yield encoder.encode(
                        ToolCallChunkEvent(
                            type=EventType.TOOL_CALL_CHUNK,
                            tool_call_id=tool_call.id,
                            tool_call_name=tool_call.function.name if tool_call.function else None,
                            parent_message_id=message_id,
                            delta=tool_call.function.arguments if tool_call.function else None,
                        )
                    )

            yield encoder.encode(
                RunFinishedEvent(
                    type=EventType.RUN_FINISHED,
                    thread_id=input_data.thread_id,
                    run_id=input_data.run_id
                )
            )

        except Exception as error:
            yield encoder.encode(
                RunErrorEvent(
                    type=EventType.RUN_ERROR,
                    message=str(error)
                )
            )

    return StreamingResponse(
        event_generator(),
        media_type=encoder.get_content_type()
    )

def main():
    """Run the uvicorn server."""
    port = int(os.getenv("PORT", "8000"))
    uvicorn.run(
        "example_server:app",
        host="0.0.0.0",
        port=port,
        reload=True
    )

if __name__ == "__main__":
    main()
```

### What happens under the hood?

Let's break down what your server is doing:

1. **Setup** – We create an OpenAI client and emit `RUN_STARTED`
2. **Request** – We send the user's messages to `chat.completions` with
   `stream=True`
3. **Streaming** – We forward each chunk as either `TEXT_MESSAGE_CHUNK` or
   `TOOL_CALL_CHUNK`
4. **Finish** – We emit `RUN_FINISHED` (or `RUN_ERROR` if something goes wrong)

Test your endpoint with:

```bash theme={null}
curl -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "threadId": "thread_123",
    "runId": "run_456",
    "state": {},
    "messages": [
      {
        "id": "msg_1",
        "role": "user",
        "content": "Hello, how are you?"
      }
    ],
    "tools": [],
    "context": [],
    "forwardedProps": {}
  }'
```

This implementation creates a fully functional AG-UI endpoint that processes
messages and streams back the responses in real-time.

## Step 5 – Chat with your server

Reload the dojo page and start typing. You'll see GPT-4o streaming its answer in
real-time, word by word.

Tools like [CopilotKit](https://docs.copilotkit.ai) already understand AG-UI and
provide plug-and-play React components. Point them at your server endpoint and
you get a full-featured chat UI out of the box.

## Share your integration

Did you build a custom server that others could reuse? We welcome community
contributions!

1. Fork the [AG-UI repository](https://github.com/ag-ui-protocol/ag-ui)
2. Add your package under `integrations/`. See
   [Contributing](../development/contributing) for more details and naming
   conventions.
3. Open a pull request describing your use-case and design decisions

If you have questions, need feedback, or want to validate an idea first, start a
thread in the GitHub Discussions board:
[AG-UI GitHub Discussions board](https://github.com/orgs/ag-ui-protocol/discussions).

Your integration might ship in the next release and help the entire AG-UI
ecosystem grow.

## Conclusion

You now have a fully-functional AG-UI server for OpenAI and a local playground
to test it. From here you can:

* Add tool calls to enhance your server
* Deploy your server to production
* Bring AG-UI to any other model or service

Happy building!


# AbstractAgent
Source: https://docs.ag-ui.com/sdk/js/client/abstract-agent

Base agent implementation with core event handling

# AbstractAgent

The `AbstractAgent` class provides the foundation for all agent implementations
in the Agent User Interaction Protocol. It handles the core event stream
processing, state management, and message history.

```typescript theme={null}
import { AbstractAgent } from "@ag-ui/client"
```

## Configuration

By default, all agents are configured by providing an optional `AgentConfig`
object to the constructor.

```typescript theme={null}
interface AgentConfig {
  agentId?: string // The identifier of the agent
  description?: string // A description of the agent, used by the LLM
  threadId?: string // The conversation thread identifier
  initialMessages?: Message[] // An array of initial messages
  initialState?: State // The initial state of the agent
  maxEnforcedEntries?: number // Entry limit per incoming event, and per outgoing input for HttpAgent (default 1,000,000; Infinity disables)
}
```

### Adding Configuration Options in your Subclass

To add additional configuration options, it is recommended to extend the
`AgentConfig` interface and call the super constructor with the extended config
from your subclass like this:

```typescript theme={null}
interface MyAgentConfig extends AgentConfig {
  myConfigOption: string
}

class MyAgent extends AbstractAgent {
  private myConfigOption: string

  constructor(config: MyAgentConfig) {
    super(config)
    this.myConfigOption = config.myConfigOption
  }
}
```

## Core Methods

### runAgent()

The primary method for executing an agent and processing the result.

```typescript theme={null}
runAgent(parameters?: RunAgentParameters, subscriber?: AgentSubscriber): Promise<RunAgentResult>
```

#### Parameters

```typescript theme={null}
interface RunAgentParameters {
  runId?: string // Unique ID for this execution run
  tools?: Tool[] // Available tools for the agent
  context?: Context[] // Contextual information
  forwardedProps?: Record<string, any> // Additional properties to forward
}
```

The optional `subscriber` parameter allows you to provide an
[AgentSubscriber](/sdk/js/client/subscriber) for handling events during this
specific run.

#### Return Value

```typescript theme={null}
interface RunAgentResult {
  result: any // The final result returned by the agent
  newMessages: Message[] // New messages added during this run
}
```

### subscribe()

Adds an [AgentSubscriber](/sdk/js/client/subscriber) to handle events across
multiple agent runs.

```typescript theme={null}
subscribe(subscriber: AgentSubscriber): { unsubscribe: () => void }
```

Returns an object with an `unsubscribe()` method to remove the subscriber when
no longer needed.

### use()

Adds middleware to the agent's event processing pipeline.

```typescript theme={null}
use(...middlewares: (Middleware | MiddlewareFunction)[]): this
```

Middleware can be either:

* **Function middleware**: Simple functions that transform the event stream
* **Class middleware**: Instances of the `Middleware` class for stateful operations

```typescript theme={null}
// Function middleware
agent.use((input, next) => {
  console.log("Processing:", input.runId);
  return next.run(input);
});

// Class middleware
agent.use(new FilterToolCallsMiddleware({
  allowedToolCalls: ["search"]
}));

// Chain multiple middleware
agent.use(loggingMiddleware, authMiddleware, filterMiddleware);
```

Middleware executes in the order added, with each wrapping the next. Middleware is applied in `runAgent()`; `connectAgent()` currently calls `connect()` directly. See the [Middleware documentation](/sdk/js/client/middleware) for more details.

### getCapabilities()

Returns the agent's current capabilities. Optional — subclasses implement this
to advertise what they support. Returns `undefined` if not implemented.

```typescript theme={null}
getCapabilities?(): Promise<AgentCapabilities>
```

See [Capabilities](/concepts/capabilities) for the full `AgentCapabilities`
type definition and usage patterns.

### abortRun()

Cancels the current agent execution.

```typescript theme={null}
abortRun(): void
```

### clone()

Creates a deep copy of the agent instance.

```typescript theme={null}
clone(): AbstractAgent
```

### connectAgent()

Establishes a persistent connection with an agent that implements the
`connect()` method.

```typescript theme={null}
connectAgent(parameters?: RunAgentParameters, subscriber?: AgentSubscriber): Promise<RunAgentResult>
```

Similar to `runAgent()` but uses the `connect()` method internally. The agent
must implement `connect()` or this functionality must be provided by a framework
like [CopilotKit](https://copilotkit.ai).

## Observable Properties

### events\$

An observable stream of all events emitted during agent execution.

```typescript theme={null}
events$: Observable<BaseEvent>
```

This property provides direct access to the agent's event stream. Events are
stored using a `ReplaySubject`, allowing late subscribers will receive all
historical events.

## Properties

* `agentId`: Unique identifier for the agent instance
* `description`: Human-readable description
* `threadId`: Conversation thread identifier
* `messages`: Array of conversation messages
* `state`: Current agent state object
* `events$`: Observable stream of all `BaseEvent` objects emitted during agent
  execution (replayed for late subscribers)

## Protected Methods

These methods are meant to be implemented or extended by subclasses:

### run()

Executes the agent and returns an observable event stream.

```typescript theme={null}
protected abstract run(input: RunAgentInput): RunAgent
```

### connect()

Establishes a persistent connection and returns an observable event stream.

```typescript theme={null}
protected connect(input: RunAgentInput): RunAgent
```

Override this method to implement persistent connections. Default implementation
throws `ConnectNotImplementedError`.

### apply()

Processes events from the run and updates the agent state.

```typescript theme={null}
protected apply(input: RunAgentInput): ApplyEvents
```

### prepareRunAgentInput()

Prepares the input parameters for the agent execution.

```typescript theme={null}
protected prepareRunAgentInput(parameters?: RunAgentParameters): RunAgentInput
```

### onError() and onFinalize()

Lifecycle hooks for error handling and cleanup operations.

```typescript theme={null}
protected onError(error: Error): void
protected onFinalize(): void
```


# Stream Compaction
Source: https://docs.ag-ui.com/sdk/js/client/compaction

compactEvents utility for reducing verbose streaming sequences

# compactEvents

`compactEvents` reduces verbose streaming sequences in an event array while
preserving semantics. Use it to shrink logs before persistence or to simplify
post‑processing of Server‑Sent Events (SSE) streams.

```ts theme={null}
import { compactEvents, EventType, type BaseEvent } from "@ag-ui/client"

const compacted: BaseEvent[] = compactEvents(events)
```

## API

```ts theme={null}
function compactEvents(events: BaseEvent[]): BaseEvent[]
```

## What it does

* Text messages: Groups `TEXT_MESSAGE_START` → `TEXT_MESSAGE_CONTENT*` →
  `TEXT_MESSAGE_END` for the same `messageId`, concatenating all `delta`
  chunks into a single `TEXT_MESSAGE_CONTENT` event.
* Tool calls: Groups `TOOL_CALL_START` → `TOOL_CALL_ARGS*` → `TOOL_CALL_END`
  for the same `toolCallId`, concatenating all `delta` chunks into a single
  `TOOL_CALL_ARGS` event.
* Interleaved events: Any events that occur between a start/end pair are moved
  after that sequence so the streaming block remains contiguous.
* Pass‑through: All other events (state, custom, etc.) are preserved unchanged.

## Example

Before:

```ts theme={null}
[
  { type: EventType.TEXT_MESSAGE_START, messageId: "m1", role: "assistant" },
  { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "m1", delta: "Hello" },
  { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "m1", delta: " " },
  { type: EventType.CUSTOM, name: "thinking" },
  { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "m1", delta: "world" },
  { type: EventType.TEXT_MESSAGE_END, messageId: "m1" },
]
```

After:

```ts theme={null}
[
  { type: EventType.TEXT_MESSAGE_START, messageId: "m1", role: "assistant" },
  { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "m1", delta: "Hello world" },
  { type: EventType.TEXT_MESSAGE_END, messageId: "m1" },
  { type: EventType.CUSTOM, name: "thinking" },
]
```

Tool call compaction works analogously for `TOOL_CALL_ARGS` chunks.

## When to use

* Persisting event history (store fewer frames with the same meaning)
* Preparing snapshots for analytics or export
* Reducing noise in tests or debugging output

## Metadata

Collapsing a run of delta events also folds their
[metadata](/concepts/metadata), key by key with the last write winning, so a
compacted stream produces the same metadata as the original. Metadata that
arrives after the first delta — from later deltas and from a replayed start
alike — rides the collapsed event in arrival order, because compaction emits
the start ahead of it.

Compaction reorders events so each stream's events stay together, and that
reordering is not semantics-preserving in general. Two parallel tool calls
whose ends arrive in the opposite order to their starts end up swapped in the
assistant message's `toolCalls` array, each still carrying its own metadata.
More significantly, an event that interrupts a stream is emitted after it, so a
`MESSAGES_SNAPSHOT` arriving mid-message is replayed after that message's own
events and overwrites what they produced — the appended content as much as the
merged metadata. Avoid interleaving snapshots with an open stream if you rely
on exact replay equivalence.

## Notes & limitations

* This utility focuses on message and tool‑call streams. It does not modify
  state events (`STATE_SNAPSHOT`/`STATE_DELTA`) or generate message snapshots.
* For background and broader patterns (branching, normalization), see
  [Serialization](/concepts/serialization).


# HttpAgent
Source: https://docs.ag-ui.com/sdk/js/client/http-agent

HTTP-based agent for connecting to remote AI agents

# HttpAgent

The `HttpAgent` extends `AbstractAgent` to provide HTTP-based connectivity to
remote AI agents. It handles the request/response cycle and transforms the HTTP
event stream into standard Agent User Interaction Protocol events.

```typescript theme={null}
import { HttpAgent } from "@ag-ui/client"
```

## Configuration

When creating an HTTP agent, you need to provide an `HttpAgentConfig` object:

```typescript theme={null}
interface HttpAgentConfig extends AgentConfig {
  url: string // Endpoint URL for the agent service
  headers?: Record<string, string> // Optional HTTP headers
}
```

## Creating an HttpAgent

```typescript theme={null}
const agent = new HttpAgent({
  url: "https://api.example.com/v1/agent",
  headers: {
    Authorization: "Bearer your-api-key",
  },
})
```

## Methods

### runAgent()

Executes the agent by making an HTTP request to the configured endpoint.

```typescript theme={null}
runAgent(parameters?: RunAgentParameters, subscriber?: AgentSubscriber): Promise<RunAgentResult>
```

#### Parameters

The `parameters` argument follows the standard `RunAgentParameters` interface.
The optional `subscriber` parameter allows you to provide an
[AgentSubscriber](/sdk/js/client/subscriber) for handling events during this
specific run.

#### Return Value

```typescript theme={null}
interface RunAgentResult {
  result: any // The final result returned by the agent
  newMessages: Message[] // New messages added during this run
}
```

### subscribe()

Adds an [AgentSubscriber](/sdk/js/client/subscriber) to handle events across
multiple agent runs.

```typescript theme={null}
subscribe(subscriber: AgentSubscriber): { unsubscribe: () => void }
```

Returns an object with an `unsubscribe()` method to remove the subscriber when
no longer needed.

### abortRun()

Cancels the current HTTP request using the AbortController.

```typescript theme={null}
abortRun(): void
```

## Protected Methods

### requestInit()

Configures the HTTP request. Override this method to customize how requests are
made.

```typescript theme={null}
protected requestInit(input: RunAgentInput): RequestInit
```

Default implementation:

```typescript theme={null}
{
  method: "POST",
  headers: {
    ...this.headers,
    "Content-Type": "application/json",
    Accept: "text/event-stream",
  },
  body: JSON.stringify(input),
  signal: this.abortController.signal,
}
```

### run()

Implements the abstract `run()` method from `AbstractAgent` using HTTP requests.

```typescript theme={null}
run(input: RunAgentInput): RunAgent
```

## Properties

* `url`: The endpoint URL for the agent service
* `headers`: HTTP headers to include with requests
* `abortController`: AbortController instance for request cancellation


# Middleware
Source: https://docs.ag-ui.com/sdk/js/client/middleware

Event stream transformation and filtering for AG-UI agents

# Middleware

The middleware system in `@ag-ui/client` provides a powerful way to transform, filter, and augment event streams flowing through agents. Middleware can intercept and modify events, add logging, implement authentication, filter tool calls, and more.

```typescript theme={null}
import {
  AbstractAgent,
  BaseEvent,
  EventType,
  FilterToolCallsMiddleware,
  Message,
  Middleware,
  MiddlewareFunction,
  RunAgentInput
} from "@ag-ui/client"
import { Observable } from "rxjs"
```

Examples below assume the relevant RxJS operators/utilities (`map`, `tap`, `filter`, `finalize`, `catchError`, `switchMap`, `timer`, `of`, etc.) are imported.

## Types

### MiddlewareFunction

A function that transforms the event stream.

```typescript theme={null}
type MiddlewareFunction = (
  input: RunAgentInput,
  next: AbstractAgent
) => Observable<BaseEvent>
```

Function middleware receives events exactly as emitted by the next middleware or agent.

### Middleware

Abstract base class for creating middleware.

```typescript theme={null}
interface EventWithState {
  event: BaseEvent
  messages: Message[]
  state: unknown
}

abstract class Middleware {
  abstract run(
    input: RunAgentInput,
    next: AbstractAgent
  ): Observable<BaseEvent>

  protected runNext(
    input: RunAgentInput,
    next: AbstractAgent
  ): Observable<BaseEvent>

  protected runNextWithState(
    input: RunAgentInput,
    next: AbstractAgent
  ): Observable<EventWithState>
}
```

* `runNext()` runs `next.run(...)` and normalizes chunk events into complete `TEXT_MESSAGE_*` / `TOOL_CALL_*` sequences.
* `runNextWithState()` does the same and also provides accumulated `messages` and `state` after each event is applied.

## Function-Based Middleware

The simplest way to create middleware is with a function. Function middleware is ideal for stateless transformations.

### Basic Example

```typescript theme={null}
const loggingMiddleware: MiddlewareFunction = (input, next) => {
  console.log(`[${new Date().toISOString()}] Starting run ${input.runId}`)

  return next.run(input).pipe(
    tap(event => console.log(`Event: ${event.type}`)),
    finalize(() => console.log(`Run ${input.runId} completed`))
  )
}

agent.use(loggingMiddleware)
```

### Transforming Events

```typescript theme={null}
const timestampMiddleware: MiddlewareFunction = (input, next) => {
  return next.run(input).pipe(
    map(event => {
      if (event.type === EventType.RUN_STARTED) {
        return {
          ...event,
          timestamp: Date.now()
        }
      }
      return event
    })
  )
}
```

### Error Handling

```typescript theme={null}
const errorMiddleware: MiddlewareFunction = (input, next) => {
  return next.run(input).pipe(
    catchError(error => {
      console.error("Agent error:", error)

      // Return error event
      return of({
        type: EventType.RUN_ERROR,
        message: error.message
      } as BaseEvent)
    })
  )
}
```

## Class-Based Middleware

For stateful operations or complex logic, extend the `Middleware` class.

### Basic Implementation

```typescript theme={null}
class CounterMiddleware extends Middleware {
  private totalEvents = 0

  run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent> {
    let runEvents = 0

    return this.runNext(input, next).pipe(
      tap(() => {
        runEvents++
        this.totalEvents++
      }),
      finalize(() => {
        console.log(`Run events: ${runEvents}, Total: ${this.totalEvents}`)
      })
    )
  }
}

agent.use(new CounterMiddleware())
```

### Configuration-Based Middleware

```typescript theme={null}
class AuthMiddleware extends Middleware {
  constructor(
    private apiKey: string,
    private headerName: string = "Authorization"
  ) {
    super()
  }

  run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent> {
    // Attach auth data in forwardedProps for downstream transport/agent logic
    const authenticatedInput: RunAgentInput = {
      ...input,
      forwardedProps: {
        ...input.forwardedProps,
        auth: {
          headerName: this.headerName,
          value: `Bearer ${this.apiKey}`
        }
      }
    }

    return this.runNext(authenticatedInput, next)
  }
}

const apiKey = process.env.API_KEY ?? ""
agent.use(new AuthMiddleware(apiKey))
```

## Accumulator Helpers (Class Middleware)

Class middleware can use helper methods from `Middleware` to work with normalized events and accumulated state.

### `runNext()`

`runNext()` forwards execution and normalizes chunk events into full `TEXT_MESSAGE_*` and `TOOL_CALL_*` events.

### `runNextWithState()`

`runNextWithState()` returns `{ event, messages, state }`, where `messages` and `state` are the accumulated values after each event has been applied.

```typescript theme={null}
class MetricsWithStateMiddleware extends Middleware {
  run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent> {
    return this.runNextWithState(input, next).pipe(
      tap(({ event, messages, state }) => {
        if (event.type === EventType.RUN_FINISHED) {
          const stateKeyCount =
            state && typeof state === "object" ? Object.keys(state).length : 0

          console.log("Assistant messages:", messages.filter(m => m.role === "assistant").length)
          console.log("Final state keys:", stateKeyCount)
        }
      }),
      map(({ event }) => event)
    )
  }
}
```

## Built-in Middleware

### FilterToolCallsMiddleware

Filters tool calls based on allowed or disallowed lists.

`FilterToolCallsMiddleware` filters emitted `TOOL_CALL_*` events (including args/results for blocked calls). It does not prevent tool execution in the upstream model/runtime.

```typescript theme={null}
import { FilterToolCallsMiddleware } from "@ag-ui/client"
```

#### Configuration

```typescript theme={null}
type FilterToolCallsConfig =
  | { allowedToolCalls: string[]; disallowedToolCalls?: never }
  | { disallowedToolCalls: string[]; allowedToolCalls?: never }
```

#### Allow Specific Tools

```typescript theme={null}
const allowFilter = new FilterToolCallsMiddleware({
  allowedToolCalls: ["search", "calculate", "summarize"]
})

agent.use(allowFilter)
```

#### Block Specific Tools

```typescript theme={null}
const blockFilter = new FilterToolCallsMiddleware({
  disallowedToolCalls: ["deleteFile", "sendEmail"]
})

agent.use(blockFilter)
```

You must specify exactly one of `allowedToolCalls` or `disallowedToolCalls`. The constructor throws if both or neither are provided.

## Middleware Patterns

### Timing Middleware

```typescript theme={null}
const timingMiddleware: MiddlewareFunction = (input, next) => {
  const startTime = performance.now()

  return next.run(input).pipe(
    finalize(() => {
      const duration = performance.now() - startTime
      console.log(`Execution time: ${duration.toFixed(2)}ms`)
    })
  )
}
```

### Rate Limiting

```typescript theme={null}
class RateLimitMiddleware extends Middleware {
  private lastCall = 0

  constructor(private minInterval: number) {
    super()
  }

  run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent> {
    const now = Date.now()
    const elapsed = now - this.lastCall

    if (elapsed < this.minInterval) {
      // Delay the execution
      return timer(this.minInterval - elapsed).pipe(
        switchMap(() => {
          this.lastCall = Date.now()
          return this.runNext(input, next)
        })
      )
    }

    this.lastCall = now
    return this.runNext(input, next)
  }
}

// Limit to one request per second
agent.use(new RateLimitMiddleware(1000))
```

Other common patterns include retry logic and response caching.

## Chaining Middleware

Multiple middleware can be combined to create sophisticated processing pipelines.

```typescript theme={null}
const logger = loggingMiddleware
const auth = new AuthMiddleware(apiKey)
const filter = new FilterToolCallsMiddleware({ allowedToolCalls: ["search"] })

agent.use(logger, auth, filter)

// Execution flow:
// logger → auth → filter → agent → filter → auth → logger
```

## Advanced Usage

### Conditional Middleware

```typescript theme={null}
const debugMiddleware: MiddlewareFunction = (input, next) => {
  const isDebug = input.forwardedProps?.debug === true

  if (!isDebug) {
    return next.run(input)
  }

  return next.run(input).pipe(
    tap(event => {
      console.debug("[DEBUG]", JSON.stringify(event, null, 2))
    })
  )
}
```

## Lifecycle Notes

Middleware added with `agent.use(...)` runs in `runAgent()` (and the legacy bridge path). `connectAgent()` currently calls `connect()` directly and does not run middleware.

## Best Practices

1. **Single Responsibility**: Each middleware should focus on one concern
2. **Error Handling**: Always handle errors gracefully and consider recovery strategies
3. **Performance**: Be mindful of processing overhead in high-throughput scenarios
4. **State Management**: Use class-based middleware when state is required
5. **Testing**: Write unit tests for each middleware independently
6. **Documentation**: Document middleware behavior and side effects

## TypeScript Support

The middleware system is fully typed for excellent IDE support:

```typescript theme={null}
import {
  AbstractAgent,
  BaseEvent,
  MiddlewareFunction,
  RunAgentInput
} from "@ag-ui/client"
import { Observable } from "rxjs"

// Type-safe middleware function
const typedMiddleware: MiddlewareFunction = (
  input: RunAgentInput,
  next: AbstractAgent
): Observable<BaseEvent> => {
  return next.run(input)
}
```


# Overview
Source: https://docs.ag-ui.com/sdk/js/client/overview

Client package overview

# @ag-ui/client

The Agent User Interaction Protocol Client SDK provides agent connectivity
options for AI systems. This package builds on the core types and events to
deliver flexible connection methods to agent implementations.

```bash theme={null}
npm install @ag-ui/client
```

## AbstractAgent

`AbstractAgent` is the base agent class for implementing custom agent
connectivity. Extending this class and implementing `run()` lets you bridge your
own service or agent implementation to AG-UI.

* [Configuration](/sdk/js/client/abstract-agent#configuration) - Setup with
  agent ID, messages, and state
* [Core Methods](/sdk/js/client/abstract-agent#core-methods) - Run, abort, and
  clone functionality
* [Protected Methods](/sdk/js/client/abstract-agent#protected-methods) -
  Extensible hooks for custom implementations
* [Properties](/sdk/js/client/abstract-agent#properties) - State and message
  tracking

> [card] [AbstractAgent Reference](/sdk/js/client/abstract-agent)
>
> Base class for creating custom agent connections

## HttpAgent

Concrete implementation for HTTP-based agent connectivity:

* [Configuration](/sdk/js/client/http-agent#configuration) - URL and header
  setup
* [Methods](/sdk/js/client/http-agent#methods) - HTTP-specific execution and
  cancellation
* [Protected Methods](/sdk/js/client/http-agent#protected-methods) -
  Customizable HTTP request handling
* [Properties](/sdk/js/client/http-agent#properties) - Connection management

> [card] [HttpAgent Reference](/sdk/js/client/http-agent)
>
> Ready-to-use HTTP implementation for agent connectivity, using a highly
> efficient event encoding format

## Middleware

Transform and intercept event streams flowing through agents with a flexible
middleware system:

* [Function Middleware](/sdk/js/client/middleware#function-based-middleware) - Simple
  transformations with plain functions
* [Class Middleware](/sdk/js/client/middleware#class-based-middleware) - Stateful
  middleware with configuration
* [Built-in Middleware](/sdk/js/client/middleware#built-in-middleware) -
  FilterToolCallsMiddleware and more
* [Middleware Patterns](/sdk/js/client/middleware#middleware-patterns) - Common
  use cases and examples

> [card] [Middleware Reference](/sdk/js/client/middleware)
>
> Powerful event stream transformation and filtering for AG-UI agents

## AgentSubscriber

Event-driven subscriber system for handling agent lifecycle events and state
mutations during agent execution:

* [Event Handlers](/sdk/js/client/subscriber#event-handlers) - Lifecycle,
  message, tool call, and state events
* [State Management](/sdk/js/client/subscriber#state-management) - Mutation
  control and propagation handling
* [Usage Examples](/sdk/js/client/subscriber#usage-examples) - Logging,
  persistence, and error handling patterns
* [Integration](/sdk/js/client/subscriber#integration-with-agents) - Registering
  and using subscribers with agents

> [card] [AgentSubscriber Reference](/sdk/js/client/subscriber)
>
> Comprehensive event system for reactive agent interaction and middleware-style
> functionality


# AgentSubscriber
Source: https://docs.ag-ui.com/sdk/js/client/subscriber

Event-driven subscriber system for agent lifecycle and event handling

# AgentSubscriber

The `AgentSubscriber` interface provides a comprehensive event-driven system for
handling agent lifecycle events, message updates, and state mutations during
agent execution. It allows you to hook into various stages of the agent's
operation and modify its behavior.

```typescript theme={null}
import { AgentSubscriber } from "@ag-ui/client"
```

## Overview

`AgentSubscriber` defines a collection of optional event handlers and lifecycle
hooks that can respond to different stages of agent execution. All methods in
the interface are optional, allowing you to implement only the events you need
to handle.

All subscriber methods can be either synchronous or asynchronous - if they
return a Promise, the agent will await their completion before proceeding.

## Adding Subscribers to Agents

Subscribers can be added to agents in two ways:

### Permanent Subscription

Use the `subscribe()` method to add a subscriber that will persist across
multiple agent runs:

```typescript theme={null}
const agent = new HttpAgent({ url: "https://api.example.com/agent" })

const subscriber: AgentSubscriber = {
  onTextMessageContentEvent: ({ textMessageBuffer }) => {
    console.log("Streaming text:", textMessageBuffer)
  },
}

// Add permanent subscriber
const subscription = agent.subscribe(subscriber)

// Later, remove the subscriber if needed
subscription.unsubscribe()
```

### Temporary Subscription

Pass a subscriber directly to `runAgent()` for one-time use:

```typescript theme={null}
const temporarySubscriber: AgentSubscriber = {
  onRunFinishedEvent: ({ result }) => {
    console.log("Run completed with result:", result)
  },
}

// Use subscriber for this run only
await agent.runAgent({ tools: [myTool] }, temporarySubscriber)
```

## Core Interfaces

### AgentSubscriber

The main interface that defines all available event handlers and lifecycle
hooks. All methods in the interface are optional, allowing you to implement only
the events you need to handle.

### AgentStateMutation

Event handlers can return an `AgentStateMutation` object to modify the agent's
state and control event processing:

```typescript theme={null}
interface AgentStateMutation {
  messages?: Message[] // Update the message history
  state?: State // Update the agent state
  stopPropagation?: boolean // Prevent further subscribers from processing this event
}
```

When a subscriber returns a mutation:

* **messages**: Replaces the current message history
* **state**: Replaces the current agent state
* **stopPropagation**: If `true`, prevents subsequent subscribers from handling
  the event (useful for overriding default behavior)

### AgentSubscriberParams

Common parameters passed to most subscriber methods:

```typescript theme={null}
interface AgentSubscriberParams {
  messages: Message[] // Current message history
  state: State // Current agent state
  agent: AbstractAgent // The agent instance
  input: RunAgentInput // The original input parameters
}
```

## Event Handlers

### Lifecycle Events

#### onRunInitialized()

Called when the agent run is first initialized, before any processing begins.

```typescript theme={null}
onRunInitialized?(params: AgentSubscriberParams): MaybePromise<Omit<AgentStateMutation, "stopPropagation"> | void>
```

#### onRunFailed()

Called when the agent run encounters an error.

```typescript theme={null}
onRunFailed?(params: { error: Error } & AgentSubscriberParams): MaybePromise<Omit<AgentStateMutation, "stopPropagation"> | void>
```

#### onRunFinalized()

Called when the agent run completes, regardless of success or failure.

```typescript theme={null}
onRunFinalized?(params: AgentSubscriberParams): MaybePromise<Omit<AgentStateMutation, "stopPropagation"> | void>
```

### Event Handlers

#### onEvent()

General event handler that receives all events during agent execution.

```typescript theme={null}
onEvent?(params: { event: BaseEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onRunStartedEvent()

Triggered when an agent run begins execution.

```typescript theme={null}
onRunStartedEvent?(params: { event: RunStartedEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onRunFinishedEvent()

Called when an agent run completes successfully.

```typescript theme={null}
onRunFinishedEvent?(params: { event: RunFinishedEvent; result?: any } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onRunErrorEvent()

Triggered when an agent run encounters an error.

```typescript theme={null}
onRunErrorEvent?(params: { event: RunErrorEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onStepStartedEvent()

Called when a step within an agent run begins.

```typescript theme={null}
onStepStartedEvent?(params: { event: StepStartedEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onStepFinishedEvent()

Triggered when a step within an agent run completes.

```typescript theme={null}
onStepFinishedEvent?(params: { event: StepFinishedEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

### Message Events

#### onTextMessageStartEvent()

Triggered when a text message starts being generated.

```typescript theme={null}
onTextMessageStartEvent?(params: { event: TextMessageStartEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onTextMessageContentEvent()

Called for each chunk of text content as it's generated.

```typescript theme={null}
onTextMessageContentEvent?(params: { event: TextMessageContentEvent; textMessageBuffer: string } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onTextMessageEndEvent()

Called when a text message generation is complete.

```typescript theme={null}
onTextMessageEndEvent?(params: { event: TextMessageEndEvent; textMessageBuffer: string } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

### Tool Call Events

#### onToolCallStartEvent()

Triggered when a tool call begins.

```typescript theme={null}
onToolCallStartEvent?(params: { event: ToolCallStartEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onToolCallArgsEvent()

Called as tool call arguments are being parsed, providing both raw and parsed
argument data.

```typescript theme={null}
onToolCallArgsEvent?(params: { event: ToolCallArgsEvent; toolCallBuffer: string; toolCallName: string; partialToolCallArgs: Record<string, any> } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onToolCallEndEvent()

Called when a tool call is complete with final arguments.

```typescript theme={null}
onToolCallEndEvent?(params: { event: ToolCallEndEvent; toolCallName: string; toolCallArgs: Record<string, any> } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onToolCallResultEvent()

Triggered when a tool call result is received.

```typescript theme={null}
onToolCallResultEvent?(params: { event: ToolCallResultEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

### State Events

#### onStateSnapshotEvent()

Called when a complete state snapshot is provided.

```typescript theme={null}
onStateSnapshotEvent?(params: { event: StateSnapshotEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onStateDeltaEvent()

Triggered when partial state changes are applied.

```typescript theme={null}
onStateDeltaEvent?(params: { event: StateDeltaEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onMessagesSnapshotEvent()

Called when a complete message history snapshot is provided.

```typescript theme={null}
onMessagesSnapshotEvent?(params: { event: MessagesSnapshotEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onActivitySnapshotEvent()

Called when an activity snapshot is received. The handler receives both the raw
event and any existing `ActivityMessage` (if present) so you can inspect or
replace it before the default client logic runs.

```typescript theme={null}
onActivitySnapshotEvent?(params: {
  event: ActivitySnapshotEvent
  activityMessage?: ActivityMessage
  existingMessage?: Message
} & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onActivityDeltaEvent()

Triggered for each activity delta. Use this hook to transform or debounce the
incoming JSON Patch operations before they update the conversation transcript.

```typescript theme={null}
onActivityDeltaEvent?(params: {
  event: ActivityDeltaEvent
  activityMessage?: ActivityMessage
} & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onRawEvent()

Handler for raw, unprocessed events.

```typescript theme={null}
onRawEvent?(params: { event: RawEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

#### onCustomEvent()

Handler for custom application-specific events.

```typescript theme={null}
onCustomEvent?(params: { event: CustomEvent } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>
```

### State Change Handlers

#### onMessagesChanged()

Called when the agent's message history is updated.

```typescript theme={null}
onMessagesChanged?(params: Omit<AgentSubscriberParams, "input"> & { input?: RunAgentInput }): MaybePromise<void>
```

#### onStateChanged()

Triggered when the agent's state is modified.

```typescript theme={null}
onStateChanged?(params: Omit<AgentSubscriberParams, "input"> & { input?: RunAgentInput }): MaybePromise<void>
```

#### onNewMessage()

Called when a new message is added to the conversation.

```typescript theme={null}
onNewMessage?(params: { message: Message } & Omit<AgentSubscriberParams, "input"> & { input?: RunAgentInput }): MaybePromise<void>
```

#### onNewToolCall()

Triggered when a new tool call is added to a message.

```typescript theme={null}
onNewToolCall?(params: { toolCall: ToolCall } & Omit<AgentSubscriberParams, "input"> & { input?: RunAgentInput }): MaybePromise<void>
```

### Messages and state are read-only

Treat the messages and state that handlers receive, and `agent.messages`, as
read-only. Copy a value before you change it.

* A message that did not change keeps the same object from one update to the
  next, so it can be compared by identity. Editing one in place also changes
  every earlier update that holds it.
* A changed message shares its unchanged nested values, such as metadata and
  multimodal content, with the reducer's working copy. Editing those in place
  can change what later updates contain.
* `agent.state` and activity message `content` are copied when emitted, so an
  edit to them does not reach later updates. An earlier update that holds the
  same object still sees the edit.

## Async Support

All subscriber methods support both synchronous and asynchronous execution:

```typescript theme={null}
const subscriber: AgentSubscriber = {
  // Synchronous handler
  onTextMessageContentEvent: ({ textMessageBuffer }) => {
    updateUI(textMessageBuffer)
  },

  // Asynchronous handler
  onStateChanged: async ({ state }) => {
    await saveStateToDatabase(state)
  },

  // Async handler with mutation
  onRunInitialized: async ({ messages, state }) => {
    const enrichedState = await loadUserPreferences()
    return {
      state: { ...state, ...enrichedState },
    }
  },
}
```

## Multiple Subscribers

Agents can have multiple subscribers, which are processed in the order they were
added:

```typescript theme={null}
// First subscriber modifies state
const stateEnricher: AgentSubscriber = {
  onRunInitialized: ({ state }) => ({
    state: { ...state, timestamp: new Date().toISOString() },
  }),
}

// Second subscriber sees the modified state
const logger: AgentSubscriber = {
  onRunInitialized: ({ state }) => {
    console.log("State after enrichment:", state)
  },
}

agent.subscribe(stateEnricher)
agent.subscribe(logger)
```

## Integration with Agents

Basic usage pattern:

```typescript theme={null}
const agent = new HttpAgent({ url: "https://api.example.com/agent" })

// Add persistent subscriber
agent.subscribe({
  onTextMessageContentEvent: ({ textMessageBuffer }) => {
    updateStreamingUI(textMessageBuffer)
  },
  onRunFinishedEvent: ({ result }) => {
    displayFinalResult(result)
  },
})

// Run agent (subscriber will be called automatically)
const result = await agent.runAgent({
  tools: [myTool],
})
```


# Events
Source: https://docs.ag-ui.com/sdk/js/core/events

Documentation for the events used in the Agent User Interaction Protocol SDK

# Events

The Agent User Interaction Protocol SDK uses a streaming event-based
architecture. Events are the fundamental units of communication between agents
and the frontend. This section documents the event types and their properties.

## EventType Enum

The `EventType` enum defines all possible event types in the system:

```typescript theme={null}
enum EventType {
  TEXT_MESSAGE_START = "TEXT_MESSAGE_START",
  TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT",
  TEXT_MESSAGE_END = "TEXT_MESSAGE_END",
  TOOL_CALL_START = "TOOL_CALL_START",
  TOOL_CALL_ARGS = "TOOL_CALL_ARGS",
  TOOL_CALL_END = "TOOL_CALL_END",
  TOOL_CALL_RESULT = "TOOL_CALL_RESULT",
  STATE_SNAPSHOT = "STATE_SNAPSHOT",
  STATE_DELTA = "STATE_DELTA",
  MESSAGES_SNAPSHOT = "MESSAGES_SNAPSHOT",
  ACTIVITY_SNAPSHOT = "ACTIVITY_SNAPSHOT",
  ACTIVITY_DELTA = "ACTIVITY_DELTA",
  RAW = "RAW",
  CUSTOM = "CUSTOM",
  RUN_STARTED = "RUN_STARTED",
  RUN_FINISHED = "RUN_FINISHED",
  RUN_ERROR = "RUN_ERROR",
  STEP_STARTED = "STEP_STARTED",
  STEP_FINISHED = "STEP_FINISHED",
  REASONING_START = "REASONING_START",
  REASONING_MESSAGE_START = "REASONING_MESSAGE_START",
  REASONING_MESSAGE_CONTENT = "REASONING_MESSAGE_CONTENT",
  REASONING_MESSAGE_END = "REASONING_MESSAGE_END",
  REASONING_MESSAGE_CHUNK = "REASONING_MESSAGE_CHUNK",
  REASONING_END = "REASONING_END",
  REASONING_ENCRYPTED_VALUE = "REASONING_ENCRYPTED_VALUE",
  SUBAGENT_STARTED = "SUBAGENT_STARTED",
  SUBAGENT_FINISHED = "SUBAGENT_FINISHED",
  SUBAGENT_ERROR = "SUBAGENT_ERROR",
}
```

## BaseEvent

All events inherit from the `BaseEvent` type, which provides common properties
shared across all event types.

```typescript theme={null}
type BaseEvent = {
  type: EventType // Discriminator field
  timestamp?: number
  rawEvent?: any
  metadata?: Record<string, any>
}
```

| Property | Type | Description |
| - | - | - |
| `type` | `EventType` | The type of event (discriminator field for the union) |
| `timestamp` | `number` (optional) | Timestamp when the event was created |
| `rawEvent` | `any` (optional) | Original event data if this event was transformed |
| `metadata` | `Record<string, any>` (optional) | Extra information attached to the event |

`metadata` is open by key: any JSON value is allowed under a key, including
`null`. The object may be absent, but a present one is never `null` — an
explicit `null` parses as absent. The `ag-ui` key is reserved for AG-UI's own
use. Use `mergeMetadata` from `@ag-ui/core` to fold event metadata into a
message; see [Metadata](/concepts/metadata).

## Lifecycle Events

These events represent the lifecycle of an agent run.

### RunStartedEvent

Signals the start of an agent run.

```typescript theme={null}
type RunStartedEvent = BaseEvent & {
  type: EventType.RUN_STARTED
  threadId: string
  runId: string
  parentRunId?: string
  input?: RunAgentInput
}
```

| Property | Type | Description |
| - | - | - |
| `threadId` | `string` | ID of the conversation thread |
| `runId` | `string` | ID of the agent run |
| `parentRunId` | `string` (optional) | (Optional) Lineage pointer for branching/time travel. If present, refers to a prior run within the same thread |
| `input` | `RunAgentInput` (optional) | (Optional) The exact agent input payload sent to the agent for this run. May omit messages already in history |

### TokenUsage

A reusable, numeric-only token usage summary carried on terminal run events.
It intentionally contains **only** provider/model labels and token counts — no
prompts, completions, messages, or identifiers. The counts follow the
protocol's [accounting](/spec/1.0/events/lifecycle#token-usage): the input
and output counts are totals, and the cache and reasoning counts are parts of
them, never additions.

```typescript theme={null}
type TokenUsage = {
  provider?: string
  model?: string
  inputTokens?: number
  outputTokens?: number
  totalTokens?: number
  reasoningTokens?: number
  cachedInputTokens?: number
  cacheWriteInputTokens?: number
}
```

| Property | Type | Description |
| - | - | - |
| `provider` | `string` (optional) | Provider that reported the usage (e.g. `openai`) |
| `model` | `string` (optional) | Model that produced the usage |
| `inputTokens` | `number` (optional) | All input tokens, cache reads and writes included |
| `outputTokens` | `number` (optional) | All output tokens, reasoning included |
| `totalTokens` | `number` (optional) | `inputTokens` plus `outputTokens` |
| `reasoningTokens` | `number` (optional) | Output tokens spent on reasoning; part of `outputTokens` |
| `cachedInputTokens` | `number` (optional) | Input tokens read from a prompt cache; part of `inputTokens` |
| `cacheWriteInputTokens` | `number` (optional) | Input tokens written to a prompt cache; part of `inputTokens` |

### RunFinishedEvent

Signals the successful completion of an agent run.

```typescript theme={null}
type RunFinishedEvent = BaseEvent & {
  type: EventType.RUN_FINISHED
  threadId: string
  runId: string
  result?: any
  usage?: TokenUsage[]
}
```

| Property | Type | Description |
| - | - | - |
| `threadId` | `string` | ID of the conversation thread |
| `runId` | `string` | ID of the agent run |
| `result` | `any` (optional) | Result data from the agent run |
| `usage` | `TokenUsage[]` (optional) | Per-(provider, model) token usage for the run, when reported |

### RunErrorEvent

Signals an error during an agent run.

```typescript theme={null}
type RunErrorEvent = BaseEvent & {
  type: EventType.RUN_ERROR
  message: string
  code?: string
  usage?: TokenUsage[]
}
```

| Property | Type | Description |
| - | - | - |
| `message` | `string` | Error message |
| `code` | `string` (optional) | Error code |
| `usage` | `TokenUsage[]` (optional) | Partial token usage from model calls that completed |

### StepStartedEvent

Signals the start of a step within an agent run.

```typescript theme={null}
type StepStartedEvent = BaseEvent & {
  type: EventType.STEP_STARTED
  stepName: string
}
```

| Property | Type | Description |
| - | - | - |
| `stepName` | `string` | Name of the step |

### StepFinishedEvent

Signals the completion of a step within an agent run.

```typescript theme={null}
type StepFinishedEvent = BaseEvent & {
  type: EventType.STEP_FINISHED
  stepName: string
}
```

| Property | Type | Description |
| - | - | - |
| `stepName` | `string` | Name of the step |

## Text Message Events

These events represent the lifecycle of text messages in a conversation.

### TextMessageStartEvent

Signals the start of a text message.

```typescript theme={null}
type TextMessageStartEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_START
  messageId: string
  role: "assistant"
}
```

| Property | Type | Description |
| - | - | - |
| `messageId` | `string` | Unique identifier for the message |
| `role` | `"assistant"` | Role is always "assistant" |

### TextMessageContentEvent

Represents a chunk of content in a streaming text message.

```typescript theme={null}
type TextMessageContentEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_CONTENT
  messageId: string
  delta: string // Non-empty string
}
```

| Property | Type | Description |
| - | - | - |
| `messageId` | `string` | Matches the ID from TextMessageStartEvent |
| `delta` | `string` | Text content chunk (non-empty) |

### TextMessageEndEvent

Signals the end of a text message.

```typescript theme={null}
type TextMessageEndEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_END
  messageId: string
}
```

| Property | Type | Description |
| - | - | - |
| `messageId` | `string` | Matches the ID from TextMessageStartEvent |

### TextMessageChunkEvent

Convenience event that expands to `TextMessageStart` → `TextMessageContent` →
`TextMessageEnd` automatically in the JS/TS client.

```typescript theme={null}
type TextMessageChunkEvent = BaseEvent & {
  type: EventType.TEXT_MESSAGE_CHUNK
  messageId?: string // required on the first chunk for a message
  role?: "developer" | "system" | "assistant" | "user"
  delta?: string
}
```

Behavior

* Omit start/end: The client transforms chunk sequences into the standard
  start/content/end triad, so you don’t need to emit them manually.
* First chunk requirements: The first chunk for a message must include
  `messageId`. When `role` is omitted, it defaults to `assistant`.
* Streaming: Subsequent chunks with the same `messageId` emit
  `TextMessageContent` events. `TextMessageEnd` is emitted automatically when a
  different message starts or when the stream completes.

## Tool Call Events

These events represent the lifecycle of tool calls made by agents.

### ToolCallStartEvent

Signals the start of a tool call.

```typescript theme={null}
type ToolCallStartEvent = BaseEvent & {
  type: EventType.TOOL_CALL_START
  toolCallId: string
  toolCallName: string
  parentMessageId?: string
}
```

| Property | Type | Description |
| - | - | - |
| `toolCallId` | `string` | Unique identifier for the tool call |
| `toolCallName` | `string` | Name of the tool being called |
| `parentMessageId` | `string` (optional) | ID of the parent message |

### ToolCallArgsEvent

Represents a chunk of argument data for a tool call.

```typescript theme={null}
type ToolCallArgsEvent = BaseEvent & {
  type: EventType.TOOL_CALL_ARGS
  toolCallId: string
  delta: string
}
```

| Property | Type | Description |
| - | - | - |
| `toolCallId` | `string` | Matches the ID from ToolCallStartEvent |
| `delta` | `string` | Argument data chunk |

### ToolCallEndEvent

Signals the end of a tool call.

```typescript theme={null}
type ToolCallEndEvent = BaseEvent & {
  type: EventType.TOOL_CALL_END
  toolCallId: string
}
```

| Property | Type | Description |
| - | - | - |
| `toolCallId` | `string` | Matches the ID from ToolCallStartEvent |

### ToolCallResultEvent

Provides the result of a tool call execution.

```typescript theme={null}
type ToolCallResultEvent = BaseEvent & {
  type: EventType.TOOL_CALL_RESULT
  messageId: string
  toolCallId: string
  content: string
  role?: "tool"
}
```

| Property | Type | Description |
| - | - | - |
| `messageId` | `string` | ID of the conversation message this result belongs to |
| `toolCallId` | `string` | Matches the ID from the corresponding ToolCallStartEvent |
| `content` | `string` | The actual result/output content from the tool execution |
| `role` | `"tool"` (optional) | Optional role identifier, typically "tool" for tool results |

## State Management Events

These events are used to manage agent state.

### StateSnapshotEvent

Provides a complete snapshot of an agent's state.

```typescript theme={null}
type StateSnapshotEvent = BaseEvent & {
  type: EventType.STATE_SNAPSHOT
  snapshot: any // StateSchema
}
```

| Property | Type | Description |
| - | - | - |
| `snapshot` | `any` | Complete state snapshot |

### StateDeltaEvent

Provides a partial update to an agent's state using JSON Patch.

```typescript theme={null}
type StateDeltaEvent = BaseEvent & {
  type: EventType.STATE_DELTA
  delta: any[] // JSON Patch operations (RFC 6902)
}
```

| Property | Type | Description |
| - | - | - |
| `delta` | `any[]` | Array of JSON Patch operations |

### MessagesSnapshotEvent

Provides a snapshot of all messages in a conversation.

```typescript theme={null}
type MessagesSnapshotEvent = BaseEvent & {
  type: EventType.MESSAGES_SNAPSHOT
  messages: Message[]
}
```

| Property | Type | Description |
| - | - | - |
| `messages` | `Message[]` | Array of message objects |

### ActivitySnapshotEvent

Delivers a complete snapshot of an activity message.

```typescript theme={null}
type ActivitySnapshotEvent = BaseEvent & {
  type: EventType.ACTIVITY_SNAPSHOT
  messageId: string
  activityType: string
  content: Record<string, any>
  replace?: boolean
}
```

| Property | Type | Description |
| - | - | - |
| `messageId` | `string` | Identifier for the target `ActivityMessage` |
| `activityType` | `string` | Activity discriminator such as `"PLAN"` or `"SEARCH"` |
| `content` | `Record<string, any>` | Structured payload describing the full activity state |
| `replace` | `boolean` (optional) | Defaults to `true`; when `false` the snapshot is ignored if a message with the same ID already exists |

### ActivityDeltaEvent

Provides incremental updates to an activity snapshot using JSON Patch.

```typescript theme={null}
type ActivityDeltaEvent = BaseEvent & {
  type: EventType.ACTIVITY_DELTA
  messageId: string
  activityType: string
  patch: any[] // RFC 6902 JSON Patch operations
}
```

| Property | Type | Description |
| - | - | - |
| `messageId` | `string` | Identifier for the target `ActivityMessage` |
| `activityType` | `string` | Activity discriminator mirroring the most recent snapshot |
| `patch` | `any[]` | JSON Patch operations applied to the structured activity payload |

## Reasoning Events

These events represent the lifecycle of reasoning/thinking processes within an
agent. Reasoning events allow agents to expose their internal thought process to
the frontend, creating `ReasoningMessage` objects that persist in the message
history with the role `"reasoning"`.

### ReasoningStartEvent

Signals the start of a reasoning phase. This is a pass-through event that
notifies subscribers but does not create messages.

```typescript theme={null}
type ReasoningStartEvent = BaseEvent & {
  type: EventType.REASONING_START
  messageId: string
}
```

| Property | Type | Description |
| - | - | - |
| `messageId` | `string` | Identifier for the reasoning phase |

### ReasoningMessageStartEvent

Signals the start of a reasoning message. Creates a new `ReasoningMessage` in
the message history.

```typescript theme={null}
type ReasoningMessageStartEvent = BaseEvent & {
  type: EventType.REASONING_MESSAGE_START
  messageId: string
  role: "reasoning"
}
```

| Property | Type | Description |
| - | - | - |
| `messageId` | `string` | Unique identifier for the message |
| `role` | `"reasoning"` | Role is always "reasoning" |

### ReasoningMessageContentEvent

Represents a chunk of content in a streaming reasoning message.

```typescript theme={null}
type ReasoningMessageContentEvent = BaseEvent & {
  type: EventType.REASONING_MESSAGE_CONTENT
  messageId: string
  delta: string
}
```

| Property | Type | Description |
| - | - | - |
| `messageId` | `string` | Matches the ID from ReasoningMessageStartEvent |
| `delta` | `string` | Reasoning content chunk |

### ReasoningMessageEndEvent

Signals the end of a reasoning message.

```typescript theme={null}
type ReasoningMessageEndEvent = BaseEvent & {
  type: EventType.REASONING_MESSAGE_END
  messageId: string
}
```

| Property | Type | Description |
| - | - | - |
| `messageId` | `string` | Matches the ID from ReasoningMessageStartEvent |

### ReasoningMessageChunkEvent

Convenience event that expands to `ReasoningMessageStart` →
`ReasoningMessageContent` → `ReasoningMessageEnd` automatically in the JS/TS
client.

```typescript theme={null}
type ReasoningMessageChunkEvent = BaseEvent & {
  type: EventType.REASONING_MESSAGE_CHUNK
  messageId?: string // required on the first chunk for a message
  delta?: string
}
```

Behavior

* Omit start/end: The client transforms chunk sequences into the standard
  start/content/end triad.
* First chunk requirements: The first chunk for a message must include
  `messageId`.
* Streaming: Subsequent chunks with the same `messageId` emit
  `ReasoningMessageContent` events. `ReasoningMessageEnd` is emitted
  automatically when a different message starts or when the stream completes.

### ReasoningEndEvent

Signals the end of a reasoning phase. This is a pass-through event that notifies
subscribers but does not modify messages.

```typescript theme={null}
type ReasoningEndEvent = BaseEvent & {
  type: EventType.REASONING_END
  messageId: string
}
```

| Property | Type | Description |
| - | - | - |
| `messageId` | `string` | Identifier for the reasoning phase |

### ReasoningEncryptedValueEvent

Attaches an encrypted value to a message or tool call. When this event is
emitted, it finds the referenced entity by `entityId` and sets its
`encryptedValue` field.

```typescript theme={null}
type ReasoningEncryptedValueEvent = BaseEvent & {
  type: EventType.REASONING_ENCRYPTED_VALUE
  subtype: "tool-call" | "message"
  entityId: string
  encryptedValue: string
}
```

| Property | Type | Description |
| - | - | - |
| `subtype` | `"tool-call" \| "message"` | The type of entity this value belongs to |
| `entityId` | `string` | ID of the tool call or message to attach the value |
| `encryptedValue` | `string` | The encrypted value to attach to the entity |

## Subagent Events

These events report that the agent delegated work to a child agent, so a frontend
can attribute output to the subagent that produced it. Attribution itself travels
as an optional `subagentRunId` on most other event types.

`subagentRunId` identifies **one invocation**, not a reusable subagent
definition — the same subagent run twice yields two different values. See
[Subagents](/concepts/subagents) for the full model.

### SubagentStartedEvent

Announces a new subagent invocation and names it for display.

```typescript theme={null}
type SubagentStartedEvent = BaseEvent & {
  type: EventType.SUBAGENT_STARTED
  subagentRunId: string
  name: string
  description?: string
  parentSubagentRunId?: string
  parentToolCallId?: string
  parentMessageId?: string
}
```

| Property | Type | Description |
| - | - | - |
| `subagentRunId` | `string` | Opaque identifier for this invocation |
| `name` | `string` | Declared subagent name or type, for display |
| `description` | `string` | Optional description |
| `parentSubagentRunId` | `string` | Optional enclosing subagent, when nesting |
| `parentToolCallId` | `string` | Optional tool call that spawned this subagent |
| `parentMessageId` | `string` | Optional message holding that tool call |

### SubagentFinishedEvent

Marks a subagent invocation as complete.

```typescript theme={null}
type SubagentFinishedEvent = BaseEvent & {
  type: EventType.SUBAGENT_FINISHED
  subagentRunId: string
  result?: any
  outcome?: { type: "success" } | { type: "suspended"; interruptIds?: string[] }
}
```

| Property | Type | Description |
| - | - | - |
| `subagentRunId` | `string` | Matches the id from `SubagentStartedEvent` |
| `result` | `any` | Optional payload, mirroring `RunFinishedEvent.result` |
| `outcome` | `SubagentFinishedOutcome` | Optional discriminated union; omitted means success (the legacy reading). `{ type: "suspended", interruptIds?: string[] }` says the subagent is checkpointed awaiting outside input; `interruptIds` names the run-level interrupts whose answers resume it. |

### SubagentErrorEvent

Marks a subagent invocation as failed.

```typescript theme={null}
type SubagentErrorEvent = BaseEvent & {
  type: EventType.SUBAGENT_ERROR
  subagentRunId: string
  message: string
  code?: string
}
```

| Property | Type | Description |
| - | - | - |
| `subagentRunId` | `string` | Matches the id from `SubagentStartedEvent` |
| `message` | `string` | Human-readable error message |
| `code` | `string` | Optional error code |

### Attribution on other events

Most event types accept an optional `subagentRunId`. An event without it belongs
to the parent agent, so a stream that never sets the field behaves exactly as it
did before subagents existed.

`RunStartedEvent`, `RunFinishedEvent` and `RunErrorEvent` are not attributable —
they describe the run as a whole. `MessagesSnapshotEvent` carries attribution
per-message instead, since one snapshot mixes messages from several producers.

`StateSnapshotEvent` and `StateDeltaEvent` are attributable, but attribution on
them is provenance rather than ownership — it records which subagent produced the
update. State stays run-scoped, so an attributed snapshot or delta is applied to
the run's one state document just as an unattributed one is. There is no
per-subagent state.

Subscribers can react to the lifecycle directly via `onSubagentStartedEvent`,
`onSubagentFinishedEvent` and `onSubagentErrorEvent`.

## Special Events

### RawEvent

Used to pass through events from external systems.

```typescript theme={null}
type RawEvent = BaseEvent & {
  type: EventType.RAW
  event: any
  source?: string
}
```

| Property | Type | Description |
| - | - | - |
| `event` | `any` | Original event data |
| `source` | `string` (optional) | Source of the event |

### CustomEvent

Used for application-specific custom events.

```typescript theme={null}
type CustomEvent = BaseEvent & {
  type: EventType.CUSTOM
  name: string
  value: any
}
```

| Property | Type | Description |
| - | - | - |
| `name` | `string` | Name of the custom event |
| `value` | `any` | Value associated with the event |

## Deprecated Events

> [!WARNING]
>
> The `THINKING_*` events are deprecated and will be removed in version 1.0.0.
> New implementations should use `REASONING_*` events instead.

### Thinking Events (Deprecated)

The following event types are deprecated:

| Deprecated Event | 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` |

See [Reasoning Migration](/concepts/reasoning#migration-from-thinking-events)
for detailed migration guidance.

## Event Schemas

The SDK uses Zod schemas to validate events:

```typescript theme={null}
const EventSchemas = z.discriminatedUnion("type", [
  TextMessageStartEventSchema,
  TextMessageContentEventSchema,
  TextMessageEndEventSchema,
  ToolCallStartEventSchema,
  ToolCallArgsEventSchema,
  ToolCallEndEventSchema,
  ToolCallResultEventSchema,
  StateSnapshotEventSchema,
  StateDeltaEventSchema,
  MessagesSnapshotEventSchema,
  ActivitySnapshotEventSchema,
  ActivityDeltaEventSchema,
  RawEventSchema,
  CustomEventSchema,
  RunStartedEventSchema,
  RunFinishedEventSchema,
  RunErrorEventSchema,
  StepStartedEventSchema,
  StepFinishedEventSchema,
  ReasoningStartEventSchema,
  ReasoningMessageStartEventSchema,
  ReasoningMessageContentEventSchema,
  ReasoningMessageEndEventSchema,
  ReasoningMessageChunkEventSchema,
  ReasoningEndEventSchema,
  ReasoningEncryptedValueEventSchema,
])
```

This allows for runtime validation of events and provides TypeScript type
inference.

### ToolCallChunkEvent

Convenience event that expands to `ToolCallStart` → `ToolCallArgs` →
`ToolCallEnd` automatically in the JS/TS client.

```typescript theme={null}
type ToolCallChunkEvent = BaseEvent & {
  type: EventType.TOOL_CALL_CHUNK
  toolCallId?: string // required on the first chunk for a tool call
  toolCallName?: string // required on the first chunk for a tool call
  parentMessageId?: string
  delta?: string
}
```

Behavior

* Omit start/end: The client transforms chunk sequences into the standard
  start/args/end triad.
* First chunk requirements: The first chunk must include both `toolCallId` and
  `toolCallName`; `parentMessageId` is propagated to `ToolCallStart` if given.
* Streaming: Subsequent chunks with the same `toolCallId` emit `ToolCallArgs`.
  `ToolCallEnd` is emitted automatically when the tool call changes or when the
  stream completes.


# Multimodal Inputs
Source: https://docs.ag-ui.com/sdk/js/core/multimodal-inputs

Use modality-specific user input parts with typed data/url sources in @ag-ui/core

# Multimodal Inputs

`UserMessage.content` accepts either plain text or an ordered array of
multimodal content parts.

```typescript theme={null}
import { UserMessage } from "@ag-ui/core"

const message: UserMessage = {
  id: "user-1",
  role: "user",
  content: [
    { type: "text", text: "Summarize this PDF and screenshot" },
    {
      type: "image",
      source: {
        type: "url",
        value: "https://example.com/screen.png",
        mimeType: "image/png",
      },
    },
    {
      type: "document",
      source: {
        type: "url",
        value: "https://example.com/report.pdf",
        mimeType: "application/pdf",
      },
    },
  ],
}
```

## Source Types

Use `source.type` to describe payload delivery:

* `data`: Inline base64 payload with required `mimeType`
* `url`: HTTP(S) or data URL, optional `mimeType`

## Common Use Cases

### Visual QA

```typescript theme={null}
{
  id: "q1",
  role: "user",
  content: [
    { type: "text", text: "What issue do you see in this UI?" },
    {
      type: "image",
      source: { type: "url", value: "https://example.com/ui.png", mimeType: "image/png" },
      metadata: { detail: "high" },
    },
  ],
}
```

### Audio transcription

```typescript theme={null}
{
  id: "q2",
  role: "user",
  content: [
    { type: "text", text: "Transcribe this recording." },
    {
      type: "audio",
      source: { type: "url", value: "https://example.com/meeting.wav", mimeType: "audio/wav" },
    },
  ],
}
```

### Mixed media comparison

```typescript theme={null}
{
  id: "q3",
  role: "user",
  content: [
    { type: "text", text: "Compare the screenshot with the spec." },
    {
      type: "image",
      source: { type: "data", value: "iVBORw0KGgo...", mimeType: "image/png" },
    },
    {
      type: "document",
      source: { type: "url", value: "https://example.com/spec.pdf", mimeType: "application/pdf" },
    },
  ],
}
```


# Overview
Source: https://docs.ag-ui.com/sdk/js/core/overview

Core concepts in the Agent User Interaction Protocol SDK

# @ag-ui/core

The Agent User Interaction Protocol SDK uses a streaming event-based
architecture with strongly typed data structures. This package provides the
foundation for connecting to agent systems.

```bash theme={null}
npm install @ag-ui/core
```

## Types

Core data structures that represent the building blocks of the system:

* [RunAgentInput](/sdk/js/core/types#runagentinput) - Input parameters for
  running agents
* [Message](/sdk/js/core/types#message-types) - User assistant communication and
  tool usage
* [Context](/sdk/js/core/types#context) - Contextual information provided to
  agents
* [Tool](/sdk/js/core/types#tool) - Defines functions that agents can call
* [State](/sdk/js/core/types#state) - Agent state management

> [card] [Types Reference](/sdk/js/core/types)
>
> Complete documentation of all types in the @ag-ui/core package

## Events

Events that power communication between agents and frontends:

* [Lifecycle Events](/sdk/js/core/events#lifecycle-events) - Run and step
  tracking
* [Text Message Events](/sdk/js/core/events#text-message-events) - Assistant
  message streaming
* [Tool Call Events](/sdk/js/core/events#tool-call-events) - Function call
  lifecycle
* [State Management Events](/sdk/js/core/events#state-management-events) - Agent
  state updates
* [Special Events](/sdk/js/core/events#special-events) - Raw and custom events

> [card] [Events Reference](/sdk/js/core/events)
>
> Complete documentation of all events in the @ag-ui/core package


# Types
Source: https://docs.ag-ui.com/sdk/js/core/types

Documentation for the core types used in the Agent User Interaction Protocol SDK

# Core Types

The Agent User Interaction Protocol SDK is built on a set of core types that
represent the fundamental structures used throughout the system. This page
documents these types and their properties.

## RunAgentInput

Input parameters for running an agent. In the HTTP API, this is the body of the
`POST` request.

`tools` contains tools provided by the client for this run. Backend-defined
tools should remain in the backend agent or framework configuration, and may be
advertised separately through agent capabilities.

```typescript theme={null}
type RunAgentInput = {
  threadId: string
  runId: string
  parentRunId?: string
  state?: any // absent means "no state"; a bare null is read as absent
  messages: Message[]
  tools: Tool[]
  context: Context[]
  forwardedProps: any
  resume?: ResumeEntry[]
}
```

| Property | Type | Description |
| - | - | - |
| `threadId` | `string` | ID of the conversation thread |
| `runId` | `string` | ID of the current run |
| `parentRunId` | `string (optional)` | ID of the run that spawned this run |
| `state` | `any (optional)` | Current state of the agent; absent means "no state", and a bare `null` is read as absent |
| `messages` | `Message[]` | Array of messages in the conversation |
| `tools` | `Tool[]` | Client-provided tools available for this run |
| `context` | `Context[]` | Array of context objects provided to the agent |
| `forwardedProps` | `any` | Additional properties forwarded to the agent |
| `resume` | `ResumeEntry[] (optional)` | Per-interrupt responses resuming a run that finished with an interrupt outcome |

## ResumeEntry

One per-interrupt response inside `RunAgentInput.resume`, addressing an
interrupt from the previous run. See
[Interrupts](/concepts/interrupts#resuming-a-run) for the full resume contract.

```typescript theme={null}
type ResumeEntry = {
  interruptId: string
  status: "resolved" | "cancelled"
  payload?: any
  metadata?: Record<string, any>
}
```

| Property | Type | Description |
| - | - | - |
| `interruptId` | `string` | ID of the interrupt this entry addresses |
| `status` | `"resolved" \| "cancelled"` | Whether the user responded or abandoned the interrupt |
| `payload` | `any (optional)` | The response itself, validated against the interrupt's `responseSchema` |
| `metadata` | `Record<string, any> (optional)` | Envelope data about the response — signatures, routing keys — never the answer itself |

`metadata` follows the same conventions as metadata everywhere else in the
protocol: open by key, any JSON value allowed under a key including `null`, the
object itself absent or an object but never `null`, and the `ag-ui` key
reserved. A resume entry is a request field, so nothing merges into it; see
[Metadata](/concepts/metadata#resume-entries).

## Message Types

The SDK includes several message types that represent different kinds of
messages in the system.

> [!NOTE]
>
> Every message type carries an optional `metadata` object
> (`Record<string, any>`), and so does `ToolCall`. Both are omitted from the
> per-type tables below for brevity.
> It is open by key — any JSON value is allowed under a key, including `null` —
> and the object itself may be absent but is never `null`. The `ag-ui` key is
> reserved for AG-UI's own use. Metadata accumulates as a message is built from
> its events; see [Metadata](/concepts/metadata) for the merge rules.

### Role

Represents the possible roles a message sender can have.

```typescript theme={null}
type Role =
  | "developer"
  | "system"
  | "assistant"
  | "user"
  | "tool"
  | "activity"
  | "reasoning"
```

### DeveloperMessage

Represents a message from a developer.

```typescript theme={null}
type DeveloperMessage = {
  id: string
  role: "developer"
  content: string
  name?: string
}
```

| Property | Type | Description |
| - | - | - |
| `id` | `string` | Unique identifier for the message |
| `role` | `"developer"` | Role of the message sender, fixed as "developer" |
| `content` | `string` | Text content of the message (required) |
| `name` | `string` | Optional name of the sender |

### SystemMessage

Represents a system message.

```typescript theme={null}
type SystemMessage = {
  id: string
  role: "system"
  content: string
  name?: string
}
```

| Property | Type | Description |
| - | - | - |
| `id` | `string` | Unique identifier for the message |
| `role` | `"system"` | Role of the message sender, fixed as "system" |
| `content` | `string` | Text content of the message (required) |
| `name` | `string` | Optional name of the sender |

### AssistantMessage

Represents a message from an assistant.

```typescript theme={null}
type AssistantMessage = {
  id: string
  role: "assistant"
  content?: string
  name?: string
  toolCalls?: ToolCall[]
}
```

| Property | Type | Description |
| - | - | - |
| `id` | `string` | Unique identifier for the message |
| `role` | `"assistant"` | Role of the message sender, fixed as "assistant" |
| `content` | `string` (optional) | Text content of the message |
| `name` | `string` (optional) | Name of the sender |
| `toolCalls` | `ToolCall[]` (optional) | Tool calls made in this message |

### UserMessage

Represents a message from a user.

```typescript theme={null}
type UserMessage = {
  id: string
  role: "user"
  content: string | ContentPart[]
  name?: string
}
```

| Property | Type | Description |
| - | - | - |
| `id` | `string` | Unique identifier for the message |
| `role` | `"user"` | Role of the message sender, fixed as "user" |
| `content` | `string \| ContentPart[]` | Either plain text or an ordered array of multimodal content fragments |
| `name` | `string` | Optional name of the sender |

### ContentPart

Union of supported content parts. The same parts appear on a `UserMessage`
and on a `ToolMessage`: a tool result is a string or a list of them. Every part
may carry an optional `id`; `metadata` is unconstrained and is where a text
search hit keeps its source and title.

```typescript theme={null}
type ContentPart = TextPart | ImagePart | AudioPart | VideoPart | DocumentPart
```

### PartSource

```typescript theme={null}
type PartSource = DataSource | UrlSource | FileSource

type DataSource = {
  type: "data"
  value: string
  mimeType: string
}

type UrlSource = {
  type: "url"
  value: string
  mimeType?: string
}

type FileSource = {
  type: "file"
  value: string // the handle, exactly as the provider issued it
  provider?: string // who issued it, e.g. "openai", "anthropic", "google"
  mimeType?: string
}
```

A `FileSource` names bytes that already live at the model provider — an
OpenAI or Anthropic file id, a Gemini file URI. Nothing is fetched and `value`
is opaque: an agent hands it to its provider or drops the part, and never
treats it as a URL.

### TextPart

```typescript theme={null}
type TextPart = {
  type: "text"
  id?: string
  text: string
  metadata?: unknown
}
```

### ImagePart

```typescript theme={null}
type ImagePart = {
  type: "image"
  id?: string
  source: PartSource
  metadata?: unknown
}
```

### AudioPart

```typescript theme={null}
type AudioPart = {
  type: "audio"
  id?: string
  source: PartSource
  metadata?: unknown
}
```

### VideoPart

```typescript theme={null}
type VideoPart = {
  type: "video"
  id?: string
  source: PartSource
  metadata?: unknown
}
```

### DocumentPart

```typescript theme={null}
type DocumentPart = {
  type: "document"
  id?: string
  source: PartSource
  metadata?: unknown
}
```

### ToolMessage

Represents a message from a tool.

```typescript theme={null}
type ToolMessage = {
  id: string
  content: string | ContentPart[]
  role: "tool"
  toolCallId: string
  error?: string
  encryptedValue?: string
}
```

| Property | Type | Description |
| - | - | - |
| `id` | `string` | Unique identifier for the message |
| `content` | `string` | Text content of the message |
| `role` | `"tool"` | Role of the message sender, fixed as "tool" |
| `toolCallId` | `string` | ID of the tool call this message responds to |
| `error` | `string` (optional) | Error message if the tool call failed |
| `encryptedValue` | `string` (optional) | Optional encrypted value attached via signature |

### ActivityMessage

Represents structured activity progress emitted between chat messages.

```typescript theme={null}
type ActivityMessage = {
  id: string
  role: "activity"
  activityType: string
  content: Record<string, any>
}
```

| Property | Type | Description |
| - | - | - |
| `id` | `string` | Unique identifier for the activity message |
| `role` | `"activity"` | Fixed discriminator identifying the message as activity |
| `activityType` | `string` | Activity discriminator used for renderer selection |
| `content` | `Record<string, any>` | Structured payload representing the activity state |

### ReasoningMessage

Represents a reasoning/thinking message from an agent's internal thought
process.

```typescript theme={null}
type ReasoningMessage = {
  id: string
  role: "reasoning"
  content: string
  encryptedValue?: string
}
```

| Property | Type | Description |
| - | - | - |
| `id` | `string` | Unique identifier for the reasoning message |
| `role` | `"reasoning"` | Fixed discriminator identifying the reasoning role |
| `content` | `string` | The reasoning/thinking content |
| `encryptedValue` | `string` (optional) | Optional encrypted value attached via signature |

### Message

A union type representing any type of message in the system.

```typescript theme={null}
type Message =
  | DeveloperMessage
  | SystemMessage
  | AssistantMessage
  | UserMessage
  | ToolMessage
  | ActivityMessage
  | ReasoningMessage
```

### ToolCall

Represents a tool call made by an agent.

```typescript theme={null}
type ToolCall = {
  id: string
  type: "function"
  function: FunctionCall
  encryptedValue?: string
}
```

| Property | Type | Description |
| - | - | - |
| `id` | `string` | Unique identifier for the tool call |
| `type` | `"function"` | Type of the tool call, always "function" |
| `function` | `FunctionCall` | Details about the function being called |
| `encryptedValue` | `string` (optional) | Optional encrypted value attached via signature |

#### FunctionCall

Represents function name and arguments in a tool call.

```typescript theme={null}
type FunctionCall = {
  name: string
  arguments: string
}
```

| Property | Type | Description |
| - | - | - |
| `name` | `string` | Name of the function to call |
| `arguments` | `string` | JSON-encoded string of arguments to the function |

## Context

Represents a piece of contextual information provided to an agent.

```typescript theme={null}
type Context = {
  description: string
  value: string
}
```

| Property | Type | Description |
| - | - | - |
| `description` | `string` | Description of what this context represents |
| `value` | `string` | The actual context value |

## Tool

Defines a tool that can be called by an agent.

```typescript theme={null}
type Tool = {
  name: string
  description: string
  parameters: any // JSON Schema
}
```

| Property | Type | Description |
| - | - | - |
| `name` | `string` | Name of the tool |
| `description` | `string` | Description of what the tool does |
| `parameters` | `any` | JSON Schema defining the parameters for the tool |

## State

Represents the state of an agent during execution.

```typescript theme={null}
type State = any
```

The state type is flexible and can hold any data structure needed by the agent
implementation.

## AgentCapabilities

Typed capability declaration returned by `getCapabilities()`. All fields are
optional — agents only declare what they support.

```typescript theme={null}
interface AgentCapabilities {
  identity?: IdentityCapabilities
  transport?: TransportCapabilities
  tools?: ToolsCapabilities
  output?: OutputCapabilities
  state?: StateCapabilities
  multiAgent?: MultiAgentCapabilities
  reasoning?: ReasoningCapabilities
  multimodal?: MultimodalCapabilities
  execution?: ExecutionCapabilities
  humanInTheLoop?: HumanInTheLoopCapabilities
  custom?: Record<string, unknown>
}
```

| Property | Type | Description |
| - | - | - |
| `identity` | `IdentityCapabilities` | Agent identity and metadata |
| `transport` | `TransportCapabilities` | Supported transport mechanisms |
| `tools` | `ToolsCapabilities` | Agent-provided tools and tool calling config |
| `output` | `OutputCapabilities` | Output format support |
| `state` | `StateCapabilities` | State and memory management |
| `multiAgent` | `MultiAgentCapabilities` | Multi-agent coordination |
| `reasoning` | `ReasoningCapabilities` | Reasoning and thinking support |
| `multimodal` | `MultimodalCapabilities` | Multimodal input/output support |
| `execution` | `ExecutionCapabilities` | Execution control and limits |
| `humanInTheLoop` | `HumanInTheLoopCapabilities` | Human-in-the-loop support |
| `custom` | `Record<string, unknown>` | Integration-specific capabilities |

See [Capabilities](/concepts/capabilities) for the full category type
definitions and usage patterns.


# @ag-ui/encoder
Source: https://docs.ag-ui.com/sdk/js/encoder



# @ag-ui/proto
Source: https://docs.ag-ui.com/sdk/js/proto



# Architecture
Source: https://docs.ag-ui.com/spec/1.0/architecture

The components, the run as the unit of interaction, and the principles behind both — 1.0

AG-UI connects agents to user-facing applications through one channel: an
ordered stream of typed events, answered to a single request. Everything the
user sees of the agent — text, tool calls, reasoning, state, progress — is in
the stream; there is no side channel.

## Core Components

```mermaid theme={null}
graph LR
    subgraph "Application"
        UI[User Interface]
        C[AG-UI Client<br/>middleware · enforcement · verification]
        UI --- C
    end
    subgraph "Agent side"
        E[Agent Endpoint]
        B[Framework Bridge]
        A[Agent / LLM framework]
        E --- B
        B --- A
    end
    C -- "RunAgentInput" --> E
    E -- "event stream" --> C
```

### The application

Owns the user. It renders the stream, executes the
[tool calls](/spec/1.0/events/tool-calls) it advertised, keeps the
[state](/spec/1.0/events/state) the agent shares with it, and decides what
requires the user's consent.

### The client

The consumer's protocol machinery, usually an SDK. It sends the
[run input](/spec/1.0/basic/run-input), runs the
[processing pipeline](/spec/1.0/basic/processing) over what comes back —
compatibility translation, middleware, enforcement, chunk expansion,
verification — and hands the application a stream it can trust.

### The agent endpoint and its bridge

The producer. A bridge translates a framework's native events into protocol
events; the endpoint speaks a [transport binding](/spec/1.0/basic/transports).
The protocol carries no framework concepts, which is what lets one client face
any framework.

### Middleware

Code either side installs into the client's pipeline. It sees every event
**before** enforcement strips anything, so a compatibility shim can translate a
[retired shape](/spec/1.0/basic/versioning#retired-shapes) and an extension
can act on material the current version does not define.

## The run

The unit of interaction. A consumer opens an exchange with one
`RunAgentInput`; the producer answers with events bracketed by the
[run lifecycle](/spec/1.0/events/lifecycle) — the requested run, possibly
preceded by replayed history; the conversation is a thread of such runs,
accumulating messages and state.

```mermaid theme={null}
sequenceDiagram
    participant Application
    participant Agent

    Application->>Agent: RunAgentInput (threadId, runId, messages, tools, state)
    Agent->>Application: RUN_STARTED
    Agent->>Application: … messages, tool calls, state, activity …
    Agent->>Application: RUN_FINISHED (outcome, usage)
    Note over Application: renders, executes, stores
    Application->>Agent: next RunAgentInput (same threadId)
```

## Design Principles

1. **Agents should be extremely easy to expose.** A bridge is a translation,
   not an implementation: whatever a framework emits maps onto a small set of
   event families, and everything optional is optional. The mandatory surface
   is the run lifecycle and nothing else.

2. **Everything observable is in the exchange.** Nothing about the agent's
   visible behaviour travels out of band: a recorder holding the exchanges —
   each run input and the events that answered it — reconstructs what the UI
   knew at every moment, which is what makes the protocol testable,
   replayable, and transport-agnostic.

3. **Tolerant reader, strict writer.** A producer MUST emit only what the
   schema defines; a consumer MUST survive what it does not recognise,
   stripping it with a warning rather than failing. The full asymmetry — and
   why a malformed known value is treated oppositely — is the
   [processing model](/spec/1.0/basic/processing).

4. **Middleware runs before enforcement.** Translation gets its chance
   before anything is stripped, so
   the protocol can evolve without stranding either side: yesterday's shapes
   are translated at the boundary, tomorrow's ride through to whoever knows
   them.

5. **Transports are bindings.** Semantics never vary by wire. The same events,
   the same rules, whether framed as SSE text or protobuf frames — with
   cross-implementation parity pinned by a shared byte corpus.


# Capabilities
Source: https://docs.ag-ui.com/spec/1.0/basic/capabilities

What an agent declares about itself before a run, what a declaration obliges, and what it does not — 1.0

A run shows a consumer what an agent *did*. Capabilities let a consumer learn
what an agent *can do* before asking it to do anything: whether it streams
reasoning, whether it will pause for approval, which modalities it accepts,
which subagents it may delegate to. An application uses them to shape the
interface it offers — a file picker only where files are accepted, an approval
affordance only where interrupts are supported — rather than discovering support
by trial.

The [schema](/spec/1.0/schema#agentcapabilities) defines the shape:
`AgentCapabilities`, a set of OPTIONAL groups, each an object of OPTIONAL
fields. This page states what a declaration obliges. It deliberately does not
specify how a consumer *obtains* a declaration — see [Retrieval](#retrieval).

## Declaring

Every group, and every field within a group, is OPTIONAL. A producer declares
what it has something to say about and omits the rest. Records a field
references keep their own requirements: a `SubagentInfo` needs its `name`, and
an entry in `tools.items` is a `Tool`.

**An omitted field means undeclared, not unsupported.** An agent that says
nothing about `reasoning` has not said it cannot reason; a consumer MUST NOT
infer the absence of a capability from the absence of its declaration. Where an
agent wants to state that something is *not* supported, the boolean fields exist
to carry `false` explicitly.

A producer SHOULD declare only what it does. A declaration is a statement to the
application about how to prepare for a run; a declaration the agent does not
honour misleads the interface built on it. There is no obligation to declare
everything true — a minimal declaration is conforming — but what is declared
SHOULD hold.

Declarations are informative, not binding. The event stream is authoritative: a
consumer MUST NOT reject a stream, or treat a run as failed, because an event
arrives that a declaration did not anticipate, or because a declared capability
went unexercised. A run that emits reasoning events under
`reasoning: { supported: false }` has a producer worth a complaint, not a stream
worth rejecting.

## The groups

The groups partition the protocol's features. Where a group describes an event
family, that family's page governs what the events themselves oblige; the
declaration only anticipates them.

| Group | Declares | Governed by |
| - | - | - |
| `identity` | Name, framework, version, provider, documentation, and an open `metadata` object | this page |
| `transport` | Which [transport bindings](/spec/1.0/basic/transports) the agent serves | [Transports](/spec/1.0/basic/transports) |
| `tools` | Whether the agent calls tools, the tools it *provides*, and whether it accepts the application's tools | [Tool calls](/spec/1.0/events/tool-calls) |
| `output` | Structured output and producible MIME types | — |
| `state` | Snapshots, deltas, persistence across runs, long-term memory | [State](/spec/1.0/events/state) |
| `multiAgent` | Delegation, handoffs, and the `subagents` it may invoke | [Subagents](/spec/1.0/events/subagents) |
| `reasoning` | Whether reasoning is emitted, streamed, or encrypted | [Reasoning](/spec/1.0/events/reasoning) |
| `multimodal` | Modalities accepted as `input` and produced as `output` | [Run input](/spec/1.0/basic/run-input#messages) for `input`; see note for `output` |
| `execution` | Code execution, sandboxing, iteration and time limits | — |
| `humanInTheLoop` | Approvals, interventions, feedback, and participation in interrupt–resume | [Interrupts and Resume](/spec/1.0/basic/patterns/interrupt-resume) |
| `custom` | Anything the standard groups do not cover | — |

Some fields deserve a note beyond their description in the schema.

`output.structuredOutput` declares that an agent can shape its answer to a
schema, but this version of the protocol has no field through which a consumer
supplies one and no event that identifies output as structured. The declaration
tells an application the agent is able; how a schema reaches the agent and how
the shaped answer comes back are integration-specific, and a consumer MUST NOT
expect a standard event to carry either.

`multimodal.output` declares what an agent can *produce*, but this version of
the protocol defines no image or audio output: assistant message content and
`TEXT_MESSAGE_CONTENT` deltas are text. The declaration is for the application
— which may receive such output through an integration-specific channel — and
nothing in this specification says how it travels. A consumer MUST NOT expect a
standard event to carry it.

`tools.items` lists the tools the *agent* provides — its own functions, search,
code execution — and is distinct from `RunAgentInput.tools`, which carries the
tools the *application* offers for one run. The two never merge: an agent's own
tools are not the application's to execute, and the application's are not
declared here.

`multiAgent.subagents` names the subagents an agent may invoke, for selection
interfaces. It is a list of definitions, not of invocations: the identifiers a
consumer meets on the wire are `subagentRunId` values, one per invocation,
minted at run time — [Subagents](/spec/1.0/events/subagents) governs those,
and nothing here predicts them.

Two `transport` flags likewise describe mechanisms this version does not
define. `transport.resumable` speaks of resuming an interrupted stream by
sequence number, and `transport.pushNotifications` of delivery after a run has
finished; neither [HTTP binding](/spec/1.0/basic/transports) carries sequence
numbers, resumes a stream, or defines a post-run channel. An agent MAY declare
them for a transport of its own; a consumer MUST NOT expect either of the
standard bindings to honour them.

## `identity.metadata` and `custom`

Two open objects carry what the standard fields do not. `identity.metadata` is
the protocol's [Metadata](/spec/1.0/basic/metadata) shape — open by key, any
JSON value under a key — for integration-specific identity information. `custom`
is the escape hatch for capabilities that fit no standard group. Both are open
by key: a consumer MUST preserve what it does not recognise inside them rather
than stripping it, exactly as for metadata elsewhere. The protocol attaches no
meaning to either.

## Retrieval

This specification defines the shape of a declaration and what it obliges. It
does not define how a consumer obtains one. No transport binding in this version
carries a capabilities exchange, and this page does not create one: whether an
agent's capabilities are read from a method on a client-side agent object,
fetched from an application-defined endpoint, or configured statically is the
implementation's business.

This is deliberate. A discovery protocol is a larger commitment than a
declaration shape, and the shape is useful without it. An implementation that
exposes capabilities by any means MUST use this shape for them.

## Error Handling

A capabilities object is not carried by the event pipeline, so the
[processing model](/spec/1.0/basic/processing)'s stripping obligation does not
apply to it; the distinction that model draws between *unrecognised* and
*malformed* does. Unrecognised members — a group
or field this version does not define — are the strict layer's concern, not the
consumer's: the schema closes every capability object, so such a document does
not validate against it, but a consumer MUST NOT reject a declaration for
carrying them, so a newer agent's declaration does not bounce off an older
consumer. Capabilities do not pass through the event pipeline's enforcement
stage, so whether a consumer keeps unrecognised members or drops them is the
implementation's business, and conforming implementations differ. A known field carrying a value the schema rejects
— a string where a boolean belongs — is malformed, and a consumer MUST NOT use a
declaration it cannot validate.

Because declarations are informative, a rejected or absent declaration MUST NOT
prevent a run. A consumer that cannot obtain or validate an agent's capabilities
proceeds as it would for an agent that declared nothing.


# The Event Model
Source: https://docs.ag-ui.com/spec/1.0/basic/index

The event envelope, its general fields, the identifiers, and the map of every event — 1.0

The base protocol is what every implementation speaks regardless of which
features it uses:

* **The event model** — this page: the envelope every event shares, its general
  fields, and the identifiers that tie events together.
* **[Run input](/spec/1.0/basic/run-input)** — the one message that travels
  the other way.
* **[Metadata](/spec/1.0/basic/metadata)** — the open channel on everything,
  and how it merges.
* **[Capabilities](/spec/1.0/basic/capabilities)** — what an agent declares
  about itself before a run, and what a declaration obliges.
* **[Event patterns](/spec/1.0/basic/patterns)** — the ways events compose
  into streams.
* **[Transports](/spec/1.0/basic/transports)** — how streams are framed and
  delivered.
* **[Processing model](/spec/1.0/basic/processing)** — what a consumer does
  with material it does not recognise.
* **[Versioning and compatibility](/spec/1.0/basic/versioning)** — talking to
  an older or newer peer.

All implementations MUST support the event model and the event patterns. The
[event families](/spec/1.0/events) beyond the run lifecycle are features: a
producer emits the ones it has something to say with.

## Events

Every event is a JSON object sharing one envelope, defined by the schema as
`BaseEvent`:

* `type` — REQUIRED. The discriminator, one of the 31 values of `EventType`.
  Every rule in this specification attaches to events through this field.
* `timestamp` — OPTIONAL. When the event was created. Informational: a consumer
  MUST NOT use it to order events — arrival order is the protocol's order. By
  convention the unit is milliseconds since the Unix epoch.
* `rawEvent` — OPTIONAL. The provider-native event this one was translated
  from, carried verbatim. A consumer MUST NOT derive protocol behaviour from
  it.
* `metadata` — OPTIONAL. See [General fields](#general-fields).

Events that can belong to a subagent's work additionally carry an OPTIONAL
`subagentRunId` (the schema's `Attributable`); the
[subagent rules](/spec/1.0/events/subagents) govern it. Run-scoped events —
`RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`, `MESSAGES_SNAPSHOT` — describe the
run or the conversation as a whole and carry no attribution.

## General fields

### `metadata`

The open channel on everything: open by key, any JSON value under a key,
accumulated across the events that build an item — key by key, last write
winning, no recursion — with per-family merge targets and a reserved `ag-ui`
key. It has its own page: [Metadata](/spec/1.0/basic/metadata).

### Absent means absent

An optional field that has no value MUST be omitted rather than sent as `null`.

This applies to every optional field, including fields that carry arbitrary JSON
such as `rawEvent`, `RUN_FINISHED.result`, and `forwardedProps`. A whole
optional field set to `null` MUST be omitted. A required JSON payload can be
`null`, for example `CUSTOM.value` or `STATE_SNAPSHOT.snapshot`.

> [!NOTE]
>
> This is not a style preference. A consumer that must accept both spellings
> has to treat them as equal everywhere, and every such tolerance is permanent
> once shipped. The protocol carries the one spelling every implementation can
> represent.

A `null` *value under an open-by-key object* — a metadata value, something
inside `state` — is data and MUST be preserved. Only a `null` standing in for a
whole absent field is prohibited.

Where the protocol has already shipped tolerance for a `null` in an optional
position, it is handled by a compatibility shim rather than by this rule. See
[Versioning and compatibility](/spec/1.0/basic/versioning).

## Identifiers

* `threadId` identifies a conversation. It is minted by the application and is
  stable across runs.
* `runId` identifies one run. It MUST NOT be reused for another run on the same
  thread.
* `messageId` identifies a message. It crosses run boundaries — a snapshot in a
  later run MAY restate a message by its id — so it MUST be unique within its
  thread.
* `toolCallId` identifies one tool call, and ties its result and any interrupt
  concerning it back to it.
* `subagentRunId` is an opaque handle for one subagent *invocation*, not a
  reusable name for a subagent definition: two invocations of the same subagent
  carry two different values.

All identifiers are opaque strings: a consumer MUST NOT parse structure out of
them.

## The events

Thirty-one event types, in eight families:

| Family | Events | Pattern |
| - | - | - |
| [Runs and steps](/spec/1.0/events/lifecycle) | `RUN_STARTED` `RUN_FINISHED` `RUN_ERROR` `STEP_STARTED` `STEP_FINISHED` | lifecycle |
| [Text messages](/spec/1.0/events/text-messages) | `TEXT_MESSAGE_START` `TEXT_MESSAGE_CONTENT` `TEXT_MESSAGE_END` `TEXT_MESSAGE_CHUNK` | [streaming](/spec/1.0/basic/patterns/streaming) |
| [Tool calls](/spec/1.0/events/tool-calls) | `TOOL_CALL_START` `TOOL_CALL_ARGS` `TOOL_CALL_END` `TOOL_CALL_CHUNK` `TOOL_CALL_RESULT` | [streaming](/spec/1.0/basic/patterns/streaming) |
| [Reasoning](/spec/1.0/events/reasoning) | `REASONING_START` `REASONING_END` `REASONING_MESSAGE_START` `REASONING_MESSAGE_CONTENT` `REASONING_MESSAGE_END` `REASONING_MESSAGE_CHUNK` `REASONING_ENCRYPTED_VALUE` | [streaming](/spec/1.0/basic/patterns/streaming) |
| [State](/spec/1.0/events/state) | `STATE_SNAPSHOT` `STATE_DELTA` `MESSAGES_SNAPSHOT` | [snapshot–delta](/spec/1.0/basic/patterns/snapshots) |
| [Activity](/spec/1.0/events/activity) | `ACTIVITY_SNAPSHOT` `ACTIVITY_DELTA` | [snapshot–delta](/spec/1.0/basic/patterns/snapshots) |
| [Subagents](/spec/1.0/events/subagents) | `SUBAGENT_STARTED` `SUBAGENT_FINISHED` `SUBAGENT_ERROR` | lifecycle |
| [Passthrough](/spec/1.0/events/passthrough) | `RAW` `CUSTOM` | standalone |

## Schema

The full structure of the protocol is defined by the JSON Schema at
[`/spec/1.0/schema.json`](/spec/1.0/schema.json). It is the source of
truth: the TypeScript, Python and .NET models are generated from it, and where
this document mentions a field it is naming something the schema defines, never
restating its shape.

The schema deliberately does not say what this document says: ordering,
lifecycle, attribution, error handling and compatibility are behavioural, and
the schema cannot express them. If the two ever disagree about structure, the
schema wins and this document has a bug.


# Metadata
Source: https://docs.ag-ui.com/spec/1.0/basic/metadata

The open channel on everything: what it carries, how it merges, and where it lands — 1.0

Nearly everything in the protocol carries an OPTIONAL `metadata` object —
events, messages, tool calls, tools, interrupts, resume entries. It is the
open channel for what the protocol does not model: provider names, latencies,
finish reasons, token counts, trace keys, whatever an application wants to
ride along with its data.

## The value

`metadata` is open by key. Any JSON value is allowed under a key, including
`null` — a `null` there is meaningful data. The object itself is either absent
or an object and MUST NOT be `null`.

Unknown metadata keys are protocol-legal, not unrecognised material: the
[processing model](/spec/1.0/basic/processing) never strips them, on any
key.

## Keys

The `ag-ui` key is reserved for the protocol's own use. Every other key is
application space; producers SHOULD prefix keys they invent with a vendor or
application name, so two parties extending the same stream do not collide.

## Merging

A streamed item is assembled from several events, and the interesting values —
token usage, a finish reason — are only known at the end. So metadata
accumulates rather than being fixed when the item opens: a consumer MUST merge
the metadata of every event making up an item, key by key, with the last write
winning for each key.

The merge MUST NOT recurse. A key's value is replaced outright, so an object
or array under a key is replaced wholesale rather than blended with what was
there before.

## Where each event's metadata lands

Merging needs a target, and the target is the thing the event builds — not
always the message:

| Event(s) | Merges into |
| - | - |
| `TEXT_MESSAGE_START` / `CONTENT` / `END` | the text message |
| `REASONING_MESSAGE_START` / `CONTENT` / `END` | the reasoning message |
| `TOOL_CALL_START` / `ARGS` / `END` | **the tool call itself** — not the assistant message that owns it |
| `TOOL_CALL_RESULT` | the tool message it creates |
| `ACTIVITY_SNAPSHOT` / `ACTIVITY_DELTA` | the activity message — accumulated metadata survives a replacing snapshot ([Activity](/spec/1.0/events/activity)) |
| chunks (`*_CHUNK`) | whatever their synthesized events merge into ([chunk metadata](/spec/1.0/basic/patterns/streaming#chunk-metadata)) |
| everything else (`RUN_*`, `STEP_*`, snapshots, `RAW`, `CUSTOM`, …) | nothing — see below |

> [!NOTE]
>
> Tool-call metadata landing on the call rather than its parent message is
> deliberate. One assistant message can own several tool calls, so folding
> their metadata into the parent would make the result depend on the order
> the calls happened to interleave. Each call keeping its own is what keeps it
> unambiguous.

An event that builds no durable item has no merge target: its metadata is the
event's own, visible to middleware and to whatever observes the stream, and
the protocol assigns it nowhere further. A consumer MAY surface it — a run's
`RUN_FINISHED` metadata in its own bookkeeping, say — but no rule requires it.

## Stored metadata

Messages, tool calls, tools, interrupts and resume entries carry `metadata` as
a plain stored field of their own. Nothing merges into those except the events
listed above; a tool's metadata in [run input](/spec/1.0/basic/run-input),
or an interrupt's, is simply data travelling with its carrier.

## Data Types

[`Metadata`](/spec/1.0/schema#metadata) is defined by the
[schema reference](/spec/1.0/schema), and every carrier's entry there lists
its `metadata` field.


# Event Patterns
Source: https://docs.ag-ui.com/spec/1.0/basic/patterns/index

The ways a producer composes events into a stream — 1.0

This page defines the event patterns of the core protocol: the ways a producer
composes events into a stream. Every
[transport](/spec/1.0/basic/transports) carries all of these patterns;
transports differ only in how events are framed and delivered.

The direction of the protocol is fixed. Events flow from producer to consumer;
the consumer speaks exactly once per exchange, by sending the
[run input](/spec/1.0/basic/run-input) that opens it. A producer MUST NOT
require any mid-run message from the consumer — a run that needs outside input
ends, and the answer arrives on the next run: through an interrupt and its
resume entries, or through a
[frontend tool call](/spec/1.0/events/tool-calls#frontend-tools) left
unanswered and answered in the next input's messages.

## Streaming

Long values arrive a piece at a time: a `*_START` opens an item, content
events extend it, a `*_END` closes it — or a chunked shorthand compresses the
three. Text messages, tool calls and reasoning messages all stream this way.

```mermaid theme={null}
sequenceDiagram
    participant Producer
    participant Consumer
    Producer->>Consumer: *_START (id)
    Producer->>Consumer: content (id, delta) ×N
    Producer->>Consumer: *_END (id)
```

See [Streaming Messages](/spec/1.0/basic/patterns/streaming).

## Snapshot and delta

Values that evolve — agent state, activities, the conversation itself — are
carried as a snapshot that replaces and deltas that amend, with deltas
expressed as RFC 6902 JSON Patch.

```mermaid theme={null}
sequenceDiagram
    participant Producer
    participant Consumer
    Producer->>Consumer: *_SNAPSHOT (the whole value)
    Producer->>Consumer: *_DELTA (a patch) ×N
    Producer->>Consumer: *_SNAPSHOT (resynchronise)
```

See [Snapshots and Deltas](/spec/1.0/basic/patterns/snapshots).

## Interrupt and resume

A run that needs something from outside — an approval, a missing value — ends
with an interrupt outcome, and the run that continues from it carries the
answers in its input.

```mermaid theme={null}
sequenceDiagram
    participant Application
    participant Agent
    Application->>Agent: RunAgentInput
    Agent->>Application: … events …
    Agent->>Application: RUN_FINISHED (outcome: interrupt)
    Note over Application: gathers the answer
    Application->>Agent: RunAgentInput (resume: answers)
    Agent->>Application: RUN_STARTED …
```

See [Interrupts and Resume](/spec/1.0/basic/patterns/interrupt-resume).

## Adding patterns

All protocol features are built from these patterns. A protocol revision that
adds a pattern defines it on this page. Transports carry new patterns without
changes, because patterns are expressed entirely in terms of events and the
run input.


# Interrupts and Resume
Source: https://docs.ag-ui.com/spec/1.0/basic/patterns/interrupt-resume

How a run asks for something from outside, and how the next run answers — 1.0

A run sometimes needs something only the outside world can give it — an
approval, a credential, a choice. The protocol has no mid-run channel from the
consumer, so the run does not wait: it ends, saying what it is waiting for, and
the run that continues from it carries the answers.

## Interrupting

A run that needs outside input ends with `RUN_FINISHED` whose `outcome` is the
interrupt outcome, carrying one or more `Interrupt` objects — at least one,
because an interrupt outcome with nothing to answer would leave a consumer
with nothing to do.

* A producer MUST NOT report an interrupted run as success: the interrupt
  outcome is the only conforming way to end a run that stopped to *ask* —
  where the producer names what it is waiting for and resume entries answer
  it. A run that stopped by calling a
  [frontend tool](/spec/1.0/events/tool-calls#frontend-tools) is the other,
  ordinary path: it finishes as success, naming the unanswered calls in the
  success outcome's `pendingToolCallIds`, and the answer rides the next
  input's messages. A run that stopped because it was *told to* is neither: it
  ends with the [cancelled outcome](/spec/1.0/events/lifecycle#cancelled-runs)
  and asks for nothing.
* Each interrupt's `id` MUST be unique within the run; a resume entry answers
  it by this id.
* An interrupt's `reason` is an open string — the protocol does not attempt to
  classify every reason an agent might need input. `message` is a
  human-readable prompt for whoever answers; `toolCallId` names the tool call
  an approval concerns; `responseSchema` describes the answer's expected shape,
  carried opaquely so a consumer can build a form for it.
* An interrupt raised inside a subagent MAY carry that subagent's
  `subagentRunId`; the [subagent rules](/spec/1.0/events/subagents) govern
  attribution and the suspended outcome that accompanies it.

An interrupted run is a closed run. Everything the
[run lifecycle](/spec/1.0/events/lifecycle) says about a closed run applies —
including the one late arrival it admits, a `RUN_ERROR` reporting a failure
that surfaced after the close — and continuing means a new run.

## Resuming

The run that continues carries its answers in the input's `resume` list, one
`ResumeEntry` per interrupt answered:

* Each entry's `interruptId` MUST name an interrupt from the run being
  continued — the most recent interrupted run on the thread.
* An entry's `status` says whether the interrupt was answered or abandoned;
  `payload` carries the answer the agent asked for, any JSON value; `metadata`
  is envelope information about the response, not part of the answer.
* The resume list MUST cover every interrupt of the run being continued: each
  one answered, or explicitly abandoned by an entry with the abandoned status.
  Omission is not abandonment. Coverage is the *consumer's* rule to enforce:
  the consumer holds the interrupts the closing `RUN_FINISHED` delivered and
  it assembles the resume list, so it is the one participant that can always
  tell whether the list is complete. A consumer MUST reject a resuming input
  that leaves an interrupt uncovered before the run starts — before anything
  is sent — and MUST NOT silently continue past an interrupt it has no entry
  for. The producer is not asked to check this, and needs to retain nothing
  from the interrupted run to be conformant; what it does when a defective
  consumer sends an incomplete list anyway is its error handling, below. What
  an abandoned interrupt means for the agent's work is the producer's
  business.
* `expiresAt` is deliberately format-unconstrained, so *whether* an interrupt
  has expired is the judging consumer's own reading of it — the reference
  reads it as a date and treats now-or-earlier as expired. The rule attaches
  to the judgment, not to a parse the schema refuses to specify: an interrupt
  the consumer judges expired can no longer be *answered* — the consumer
  rejects a resume entry resolving it before the run starts, as it rejects an
  uncovered interrupt. It can still be — and, coverage being mandatory, must
  be — abandoned, which is how a thread moves past an interrupt nobody
  answered in time.
* Thread and state continuity hold across the gap: the resuming run carries the
  same `threadId`, the accumulated messages, and the state the interrupted run
  left behind, exactly as any [sequential run](/spec/1.0/events/lifecycle)
  does.
* Token usage does not carry across the gap: the resuming run's `usage`
  [covers](/spec/1.0/events/lifecycle#token-usage) only the model calls it
  made itself. The interrupted run already reported its own on the
  `RUN_FINISHED` that interrupted it.

A producer receiving resume entries treats them as the answers it stopped for.
The list is the consumer's complete statement of what was decided, and the
producer takes it as such: it is not required to remember the interrupts of a
prior run, to compare the list against them, or to keep any state between
runs for that purpose. A producer that carries nothing across the gap is
conformant.

Two violations of the consumer's rules can nevertheless reach a producer. What
follows is the producer's error handling for them, not permission to send them.

* **An unrecognised entry** — one naming an interrupt the producer did not
  raise: the run SHOULD proceed without the entry, and the producer SHOULD
  surface a warning rather than fail a run over an answer it never asked for.

* **An uncovered interrupt** — one the producer can tell is still open and
  has no entry, because it kept the interrupted run's checkpoint, or because
  the messages carry an approval-gated tool call with neither a result nor an
  entry answering it.
  A producer MUST NOT perform the interrupted action on the strength of an
  absent entry, and MUST NOT treat the omission as abandonment — dropping the
  call with a warning and finishing as success would let a defective consumer
  abandon what nobody decided to abandon, which is the outcome the coverage
  rule exists to prevent. Having noticed, the producer keeps the interrupt
  open. It MAY reject the input before the run starts, as any invalid input
  (a stream opening with `RUN_ERROR`, or the transport's own rejection of the
  request); or it MAY run what the covered entries permit and end with the
  interrupt outcome again, carrying the still-open interrupt so the consumer
  gets another chance to answer it. Either way the run MUST NOT end as
  success while an interrupt the producer knows to be open stands
  unanswered. A producer that cannot tell — the stateless case above — is
  under no obligation here, because it has nothing to notice.

## Message Flow

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Application
    participant Agent

    Application->>Agent: RunAgentInput (runId: "run-1")
    Agent->>Application: RUN_STARTED
    Agent->>Application: TOOL_CALL_START ("transfer_funds") …
    Agent->>Application: RUN_FINISHED (outcome: interrupt,<br/>id: "int-1", toolCallId, responseSchema)
    Application->>User: renders the approval
    User->>Application: approves
    Application->>Agent: RunAgentInput (runId: "run-2",<br/>resume: [{interruptId: "int-1", payload}])
    Agent->>Application: RUN_STARTED … RUN_FINISHED
```

## Data Types

[`RunFinishedInterruptOutcome`](/spec/1.0/schema#runfinishedinterruptoutcome), [`Interrupt`](/spec/1.0/schema#interrupt) and [`ResumeEntry`](/spec/1.0/schema#resumeentry) are defined by the
[schema reference](/spec/1.0/schema). `expiresAt`, when present, conventionally
carries an ISO 8601 timestamp; the schema deliberately does not constrain its
format.

## Error Handling

A success outcome carrying interrupts is a contradiction the schema already
rejects — the success outcome is closed. A resume list on a run that does not
continue an interrupted run answers nothing; producers treat its entries as
unrecognised, as above.


# Snapshots and Deltas
Source: https://docs.ag-ui.com/spec/1.0/basic/patterns/snapshots

How evolving values travel: replacement wholesale, amendment by JSON Patch — 1.0

Some of what a producer reports is not a stream of text but a value that
evolves: the agent's state, an activity's content, the conversation itself.
These travel as **snapshots**, which replace, and **deltas**, which amend.

Three families use the pattern:
[state](/spec/1.0/events/state) (`STATE_SNAPSHOT`, `STATE_DELTA`, and
`MESSAGES_SNAPSHOT` for the conversation) and
[activity](/spec/1.0/events/activity) (`ACTIVITY_SNAPSHOT`,
`ACTIVITY_DELTA`). This page states what they share; the family pages state
what each replaces and amends.

## Snapshots

A snapshot carries the whole value. A consumer MUST replace its copy with the
snapshot's content — a snapshot is not a merge — unless the snapshot itself
opts out through a field its family defines
([activity](/spec/1.0/events/activity)'s `replace: false` is the one case).
Whatever deltas came before it are spent: the snapshot, applied or declined,
is the new baseline moment.

A producer MAY send a snapshot at any time, and SHOULD send one whenever it
cannot guarantee that the consumer's baseline matches its own — after an error,
after content a delta cannot express, or at the start of a run that continues
an old thread.

## Deltas

A delta amends the current value, expressed as an
[RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) JSON Patch: an array
of operations applied in order, atomically — if any operation fails, the
document is left as it was.

* A delta applies against the consumer's current value: the last snapshot as
  amended by every delta since. For state, the value a run starts from is the
  input's `state`, or the empty object when the input
  [carried none](/spec/1.0/basic/run-input#state).
* A producer MUST NOT send a delta for a value it has given the consumer no
  baseline for. What counts as a baseline is the family's business — state has
  one from the input, an activity only after its first snapshot.
* Patch operations are deliberately open objects: the schema marks them so, and
  a member RFC 6902 does not define is protocol-legal material the
  [processing model](/spec/1.0/basic/processing) MUST NOT strip.

## When a patch does not apply

Structural validity does not mean a patch applies: a well-formed operation may
point at a path that does not exist, and RFC 6902 leaves that to the applier. A
malformed *operation* — a patch that is not an array, an operation missing a
required member or carrying one of the wrong type — is a malformed known value
and fatal like any other. An operation whose `op` names something RFC 6902
does not define is not malformed but unrecognised — a member of a
discriminated union added after this consumer shipped — and the
[processing model](/spec/1.0/basic/processing)'s list rule applies: the
element is dropped from the patch with a warning and the run survives. A
well-formed patch that fails to apply is different again:

* The consumer MUST NOT keep a partially applied result — RFC 6902 application
  is atomic.
* The consumer MUST surface the failure — a warning that identifies what
  failed and why, well enough to diagnose — and MAY continue with its prior
  value rather than failing the run.
* A `test` operation that fails is this same case: the patch does not apply,
  and the consumer keeps its prior value.

From that point the consumer's value may have diverged from the producer's. A
producer that learns of it, or that cannot rule it out, SHOULD resynchronise
with a snapshot; a consumer MUST adopt the next snapshot regardless of what it
skipped before it — that is what makes recovery possible.

## Message Flow

```mermaid theme={null}
sequenceDiagram
    participant Producer
    participant Consumer

    Producer->>Consumer: STATE_SNAPSHOT {"items": []}
    Producer->>Consumer: STATE_DELTA add /items/0
    Producer->>Consumer: STATE_DELTA replace /items/0/status
    Note over Consumer: a delta fails to apply → warn, keep prior value
    Producer->>Consumer: STATE_SNAPSHOT (resynchronises)
```

## Data Types

The patch shape — [`JsonPatch`](/spec/1.0/schema#jsonpatch), its operations, [`JsonPointer`](/spec/1.0/schema#jsonpointer) — is defined by
the [schema reference](/spec/1.0/schema), by reference to RFC 6902.


# Streaming Messages
Source: https://docs.ag-ui.com/spec/1.0/basic/patterns/streaming

The open–content–close discipline, the chunked form, and the rules that bind them — 1.0

Three event families stream long values a piece at a time: text messages, tool
calls, and reasoning messages. All three follow one pattern with two spellings —
an explicit **open–content–close** triad, and a compact **chunked** form for
producers that would otherwise have to buffer. This page defines the pattern
once; the family pages ([text messages](/spec/1.0/events/text-messages),
[tool calls](/spec/1.0/events/tool-calls),
[reasoning](/spec/1.0/events/reasoning)) add only what is specific to each
family.

## Open, content, close

A streamed item is opened by its `*_START` event, extended by zero or more
content events, and closed by its `*_END` event, all matched by the item's
identifier (`messageId` for messages, `toolCallId` for tool calls).

* A producer MUST NOT open an item whose identifier is already open.
* A producer MUST NOT send a content or end event for an identifier that is
  not open.
* Every item a producer opens MUST be closed before the run finishes.

The opening event carries the fields that describe the item; content events
carry only the identifier and a `delta`. Deltas concatenate in arrival order to
form the item's value.

```mermaid theme={null}
sequenceDiagram
    participant Producer
    participant Consumer

    Producer->>Consumer: TEXT_MESSAGE_START (messageId: "msg-1")
    Producer->>Consumer: TEXT_MESSAGE_CONTENT (delta: "Hello, ")
    Producer->>Consumer: TEXT_MESSAGE_CONTENT (delta: "world.")
    Producer->>Consumer: TEXT_MESSAGE_END (messageId: "msg-1")
```

## Interleaving

Messages, tool calls, reasoning messages and steps are independent. A producer
MAY interleave them freely — a tool call MAY open while a message is still
streaming — provided each item respects its own open/close discipline.

Standalone events (`STATE_SNAPSHOT`, `STATE_DELTA`, `MESSAGES_SNAPSHOT`,
`ACTIVITY_SNAPSHOT`, `ACTIVITY_DELTA`, `CUSTOM`, `RAW`,
`REASONING_ENCRYPTED_VALUE`) open and close no items of their own, and MAY
appear anywhere within an open run. In the chunked form, some of them do end
an open chunk stream — arriving is what tells the consumer the shorthand can
no longer continue — as [Closing a chunk stream](#closing-a-chunk-stream)
lists.

## The chunked form

`TEXT_MESSAGE_CHUNK`, `TOOL_CALL_CHUNK` and `REASONING_MESSAGE_CHUNK` are a
compact spelling of the triad. A consumer MUST expand them into the
start/content/end form before verification and before application code, so
every rule of the triad applies to the expanded events. Where expansion sits
relative to enforcement and middleware is specified in the
[processing model](/spec/1.0/basic/processing); the invariant that holds on
every path is that a chunk is judged as the event it is — whichever stage
meets a malformed chunk first rejects it rather than repairs it.

```mermaid theme={null}
sequenceDiagram
    participant Producer
    participant Expansion
    participant Consumer

    Producer->>Expansion: TOOL_CALL_CHUNK (toolCallId, toolCallName, delta)
    Expansion->>Consumer: TOOL_CALL_START
    Expansion->>Consumer: TOOL_CALL_ARGS
    Producer->>Expansion: TOOL_CALL_CHUNK (delta)
    Expansion->>Consumer: TOOL_CALL_ARGS
    Producer->>Expansion: RUN_FINISHED
    Expansion->>Consumer: TOOL_CALL_END
    Expansion->>Consumer: RUN_FINISHED
```

The two spellings do not mix within one item. An item opened by a chunk is
continued and closed in chunk form — its `*_END` is synthesized, never sent —
and an item opened by a `*_START` is continued and closed explicitly. An
explicit event carrying an identifier a chunk stream is assembling is not a
continuation of it: it ends the shorthand, as
[Closing a chunk stream](#closing-a-chunk-stream) describes, and what follows
is judged by the triad rules — which makes mixing the forms within one item a
malformed sequence a producer MUST NOT emit.

### The first chunk

The first chunk of an item carries what opening it requires; later chunks MAY
omit those fields and continue what is already open.

* The first `TEXT_MESSAGE_CHUNK` for a message MUST carry `messageId`. It MAY
  carry `role`; an absent role means `assistant`, exactly as on
  `TEXT_MESSAGE_START`.
* The first `REASONING_MESSAGE_CHUNK` for a message MUST carry `messageId`.
* The first `TOOL_CALL_CHUNK` for a call MUST carry both `toolCallId` and
  `toolCallName`.

A consumer MUST treat a first chunk missing a required field as a protocol
violation rather than inventing an identifier.

### Continuation chunks

* A later chunk that carries an identifier MUST carry the same identifier it is
  continuing. A chunk that names a different identifier opens a new item, and
  the previous one closes first.
* A continuation chunk MAY repeat a field its opener established — `role` or
  `name` on a text message, `toolCallName` or `parentMessageId` on a tool call —
  but only with the same value. A consumer MUST treat a conflicting repeat as a
  protocol violation. This includes a value conflicting with one the opener
  established by omission: a message opened without a role is an `assistant`
  message, and a later chunk claiming another role contradicts it.

> [!NOTE]
>
> The conflicting-repeat rule is the same judgment the
> [subagent attribution rules](/spec/1.0/events/subagents) pass on a
> continuation that disagrees with its opener about `subagentRunId`: the
> producer has said two incompatible things about one item, and there is no
> correct way to choose between them.

### Closing a chunk stream

The chunked form has no explicit end event, so the consumer synthesizes the
`*_END` when the stream can no longer continue:

* when a chunk opens a different item in the same lane;
* when a message, tool-call, step, state, custom or reasoning event arrives in
  the item's lane — with four exceptions that stand aside from assembly and
  close nothing: `RAW`, `ACTIVITY_SNAPSHOT`, `ACTIVITY_DELTA`,
  `REASONING_ENCRYPTED_VALUE` (and `SUBAGENT_STARTED`, which opens a new lane
  rather than touching this one);
* when a run-level event arrives — `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`
  or `MESSAGES_SNAPSHOT` — which closes every lane, or when the subagent the
  item is attributed to terminates, which closes that subagent's lane.

Which lane a shorthand continuation belongs to — the parent agent's or a
subagent's — is decided by the [attribution rules](/spec/1.0/events/subagents),
and for a continuation carrying neither an identifier nor a tag, by
resolution: it continues the parent agent's open stream of its kind when one
exists, and otherwise the sole open stream of its kind. When several lanes
hold open streams of that kind and none of them is the parent's, the
continuation has no unique referent and MUST be rejected as ambiguous — a
producer running parallel subagents MUST attribute its continuations. A chunk
stream MUST NOT outlive its owner: an item opened by a subagent closes no
later than that subagent's terminal event.

### Chunk metadata

A chunk's `metadata` applies to the events synthesized from that chunk, and
merges into the item under the
[metadata rules](/spec/1.0/basic/metadata). A continuation chunk that
carries only metadata — a final chunk reporting usage and a finish reason — is
legal: it adds no content, and its metadata still reaches the item it
continues.


# Processing Model
Source: https://docs.ag-ui.com/spec/1.0/basic/processing

What survives, what is fatal, and where middleware sits relative to enforcement — 1.0

Two things look superficially alike and must never be confused: material the
protocol does not describe, and a value the protocol does describe that is
wrong. The first is how the protocol grows. The second is a bug.

## The rule

**Unrecognised material is not an error. A malformed known value is.**

* An event of a type this implementation does not recognise MUST NOT abort the
  run.
* A property that is not described on an event MUST NOT abort the run.
* A union member the implementation does not recognise — a content part of a new
  kind, an outcome named after it shipped — MUST NOT abort the run.
* A field the protocol DOES describe, carrying a value the schema rejects, MUST
  be fatal: the consumer MUST fail the run rather than repair, coerce or ignore
  the value.

The reasoning is asymmetric on purpose. An event type added after an
implementation shipped is expected — the sender is newer, and the older party
has no basis to call it invalid. But `messageId` holding a number is not a newer
protocol; it is a defect, and a consumer that quietly coerces it hides the defect
until it surfaces as something harder to diagnose.

## Every transport answers the same way

These rules bind the protocol, not a wire format. A consumer that supports more
than one transport MUST reach the same verdict on the same event however it
arrived: if a stream survives as JSON, it MUST survive as protobuf, and if it
fails, it MUST fail the same way — except where the binary encoding itself
cannot express the difference the verdict turns on, the two cases this page
names below (the unnameable envelope variant, and the absences protobuf
materialises).

That puts a limit on what a reader may decide for itself. Turning bytes into
events is the reader's whole job — a frame whose bytes map to no event at all is
a decode failure, and that judgement is properly the reader's. Whether a
successfully read event carries something the implementation recognises is not:
that question belongs to the one stage every transport shares. A reader that
also validates makes its transport strictly harsher than the others, and a
producer's choice of content type then decides whether a run survives.

The binary case needs one accommodation. A text reader can hand on an event of
an unknown type, because the type travels as a string and the shared stage can
drop it by name. A binary reader cannot: an envelope variant it was not compiled
against carries no name to hand on. Such a frame MUST be dropped, with a
warning, rather than failing the run — that is the same answer the shared stage
would have given, spelled for a transport that cannot defer the question.

> [!NOTE]
>
> A binary encoding cannot honour this wherever it gives a field no presence.
> In protobuf that covers required scalars and required lists alike: a required
> string a producer omitted arrives as an empty string, a required array as an
> empty array, and each is accepted where the same event as JSON is rejected as
> malformed. The schema already forbids omitting them, so this changes how a
> defective producer is diagnosed rather than what a conformant one may send.

## What a consumer does with unrecognised material

A consumer that exposes events to application code MUST NOT deliver unrecognised
material as though the protocol described it. Having read it, such a consumer
MUST do one of:

* **Drop it**, if the whole event is of an unrecognised type. The consumer
  SHOULD emit a warning naming the type.
* **Strip it**, if it is an unknown property or an unrecognised union member on
  an otherwise valid event. The consumer SHOULD emit a warning naming the path
  that was removed.

A consumer MUST NOT let a stripped property survive into the value application
code receives, and MUST NOT let a dropped event reach it at all.

This applies only where the schema closes an object, which is everywhere it
describes one of the protocol's own. Where the schema deliberately leaves an
object open, a member it does not describe is not unrecognised material at all
and MUST be preserved. The JSON Patch operations are the case: RFC 6902 section
4 requires an operation to ignore members it does not define rather than reject
them, so a `remove` carrying a leftover `value` is a valid patch and arrives
whole. A consumer that strips there deletes conformant data, and the warning it
emits is about nothing.

This binds the pipeline, not the parser. A library layer that only parses an
event — the generated models in each SDK, say — keeps unknown properties on
purpose, so that the middleware above it can still see them. An SDK that offers
such a parser without an enforcement stage does not yet satisfy this rule; today
that is Python and .NET, whose models parse leniently with no stage that strips
before application code.

> [!NOTE]
>
> One case is not yet met by the reference implementation: a field whose schema
> is a closed set of string values — a message `role`, for instance — is checked
> as a leaf, so an unrecognised value there is fatal rather than stripped. The
> .NET converters reject an unknown role or outcome the same way. The rule above
> is what the protocol requires; both are gaps against it rather than a softening
> of it.

Stripping reaches all the way down, and what it removes depends on where the
unrecognisable value sits:

* In an **optional** position, that field is removed and everything around it
  survives.
* In a **required** position, the value *containing* it is removed instead. A
  media part whose source is of a kind this implementation has never heard of is
  removed whole — leaving a part behind with no source would hand the validator
  something it must treat as malformed, turning an addition into a fatal error.
* Inside a **list**, the unrecognisable element is dropped and the list survives.

## Where middleware sits

Middleware — anything a consumer installs to translate, observe or rewrite the
stream — MUST run before enforcement, and enforcement MUST run before
verification and before application code sees anything.

```
producer → compatibility boundary → middleware → enforcement
         → chunk expansion → verification → application
```

The compatibility boundary is the always-on translator for shapes the protocol
has retired. It MUST see the stream first, because a retired shape can be a
chunk, and a stage that met it earlier would either fail on it or turn it into
something the boundary can no longer recognise. A middleware *chain* MAY
expand chunks between its own stages, so that each stage receives the
start/content/end form — the reference implementation's chaining helper does
exactly that. A middleware therefore MUST be prepared for either form: what it
sees depends on where in the chain it sits.

Expansion between stages narrows one guarantee, and the narrowing is stated
rather than hidden: expansion synthesizes events carrying only what the
protocol defines, so unrecognised fields *on a chunk* survive to enforcement —
and earn their warning — only on the canonical order above. A chain that
expands early loses them silently. A conforming producer never emits such
fields, so what is lost is material from a newer protocol version crossing a
chain that expands early. The material expansion exists to deliver — deltas,
opener fields, metadata, `rawEvent`, attribution — is carried through intact;
a chunk's `timestamp` is not, because the synthesized events are not the
chunk, and like unknown fields it is judged before expansion only on the
canonical order.

A chunk is an event in its own right, and it MUST be judged as one: whichever
stage meets a malformed chunk first — enforcement on the canonical order
above, expansion where a middleware chain expands early — MUST reject it
rather than repair it, and MUST NOT normalise, default or conceal a malformed
known value enforcement would reject. A consumer that substituted a default
for a malformed role made the same producer defect fatal when sent plainly and
invisible when sent as a chunk, so which form a producer happened to use
decided whether its bug was ever reported.

Verification MUST run after expansion, because what it checks — that messages
and calls open before they continue and close after — only exists once a chunk
has become the events it stands for.

The order is load-bearing in both directions:

* Middleware MUST see material before enforcement removes it. A shim exists
  precisely to translate a shape the current protocol does not describe; if
  enforcement stripped that shape first, the shim would receive an event with
  nothing left to translate and the run would lose data no one could recover.
* Application code MUST NOT see material enforcement would remove. Once the
  translators have had their chance, whatever is still unrecognised is
  unrecognised, and it stops there.

A consumer MUST apply this ordering on every path that produces events for
application code, including reconnection and replay. A path that skips
enforcement is a hole in the guarantee, not an optimisation.

## Outgoing material

The same boundary applies to what a consumer sends. Immediately before
transmission, a consumer MUST remove unrecognised material from the run input,
SHOULD warn about what it removed, and MUST treat a malformed known field as
fatal before anything is sent.

A producer receiving a run input MUST apply the same asymmetry to it:
unrecognised material does not make the input invalid, a malformed known field
does.

## What a producer must not do

A producer MUST NOT emit an event type the protocol does not describe in the
expectation that consumers will ignore it. Unrecognised events survive so the
protocol can add them, not so a producer can smuggle private signalling through
the stream; `CUSTOM` and `RAW` exist for that and are described by the schema.


# Run Input
Source: https://docs.ag-ui.com/spec/1.0/basic/run-input

The one message that travels from the application to the agent, and what each of its fields obliges — 1.0

Events flow from producer to consumer. Exactly one message flows the other way:
`RunAgentInput`, sent once to open each exchange. Everything the producer knows
about the conversation arrives through it. The run it requests is the exchange's
last; a stream that replays a thread's history carries the earlier runs
[without further input](/spec/1.0/basic/transports#the-binding-contract).

The [schema](/spec/1.0/schema#runagentinput) defines its shape; this page states what
each field obliges. A producer MAY echo the input back on `RUN_STARTED.input`,
so a consumer that did not make the request can still see what the agent was
asked.

## Identity

`threadId` names the conversation and `runId` names the run this input
requests; both are REQUIRED. Every run on the stream carries the input's
`threadId` on its boundary events — `RUN_STARTED` and `RUN_FINISHED`, the two
that carry identity — and each run's two boundary events MUST agree on their
`runId`. The requested run echoes this input's `runId`; a replayed run
carries its own. `parentRunId` is OPTIONAL and names the run that spawned
this one, when an agent starts another agent as a separate run.

## `protocolVersion`

OPTIONAL in the schema, because absence identifies a peer from before the
protocol carried a version — but a consumer implementing this version MUST
declare the version it speaks here, unless it knows its peer predates the
field and omits the member rather than risk an old parser rejecting it. The
producer answers with its own declaration on `RUN_STARTED`; the rules are in
[Versioning](/spec/1.0/basic/versioning#version-negotiation).

## `messages`

REQUIRED. The conversation so far, in order. A producer MUST treat it as the
complete history it is being shown — the protocol has no side channel through
which earlier turns arrive.

The message types and their content shapes — including multimodal
[`ContentPart`](/spec/1.0/schema#contentpart)s carrying text, images, audio,
video and documents by URL, as inline data or as a
[provider file handle](#provider-file-handles), on user messages and on the tool
messages that answer [frontend tool calls](/spec/1.0/events/tool-calls#frontend-tools) —
are the schema's business. Two behavioural rules attach:

* A producer that cannot use a content part — a model without vision handed an
  image — MUST NOT fail the run because of it. Skipping what it cannot use and
  continuing is the conforming behaviour; losing content on a downgraded
  *outgoing* path is different and obliges a warning
  ([Versioning](/spec/1.0/basic/versioning)).
* Activity messages never travel back to the producer: a consumer MUST strip
  them from `messages` before sending. They are the consumer's rendering
  material, not conversation the agent resumes from.

### Provider file handles

A media part's `source` says where its bytes are: carried inline (`data`),
fetchable by URL (`url`), or already at the model provider under a handle the
provider issued (`file`) — an OpenAI or Anthropic file id, a Gemini file URI,
a storage URL only that provider can read. The
[`file` source](/spec/1.0/schema#filesource) exists because a handle is
neither of the other two things: it carries no bytes, and it is not fetchable
by anyone but the provider that minted it, so putting it in `url` invites every
other peer to try.

* A `file` source's `value` is opaque. A peer MUST NOT fetch it, parse it or
  read a scheme out of it; it hands the handle to the provider, or it does not
  use the part.
* `provider` names who issued the handle, when the producer knows. It is
  OPTIONAL — an agent already knows which provider it talks to — and when
  present SHOULD be the lowercase vendor id that
  [`TokenUsage.provider`](/spec/1.0/schema#tokenusage) uses, so a peer can
  tell before sending whether a handle is one it can use.
* A producer handed a handle it cannot resolve — another provider's, an
  unknown provider's, one that has expired — is in the situation the first
  rule above already covers: it MUST NOT fail the run, it skips the part and
  continues, and it SHOULD say so. A handle's lifetime is the provider's
  business; a producer that wants to carry an expiry does so in the part's
  `metadata`.
* The source arms are a closed set: a source whose `type` a peer does not
  recognise fails validation rather than being carried through. That is why
  this arm is in 1.0 and not a later minor version — a consumer built to 1.0
  could never have passed it on.

## `tools`

OPTIONAL. The application's own tools — *frontend tools* — offered to the
agent for this run: name, description and, where the tool takes arguments, a
parameter schema. The
application executes them, not the agent; calling one hands control back
across the run boundary, the round-trip
[Tool calls](/spec/1.0/events/tool-calls#frontend-tools) specifies.

An absent list and an empty list mean the same thing: no tools. A producer
MUST treat a missing `tools` exactly as it would treat an empty one, and a
consumer MAY omit an empty list rather than sending `[]`.

## `context`

OPTIONAL. Information the application wants in the agent's context, as
description–value pairs. It exists to be *injected*: a producer SHOULD make
every entry available to the model as part of the run's grounding. How — a
system prompt, a preamble, whatever the framework does with context — is the
producer's business; the protocol says only that context is for the model to
see, not bookkeeping for the transport.

Absence means the same as emptiness, exactly as for `tools`.

## `state`

OPTIONAL. The state the run starts from — the consumer's last agreed value,
typically what the previous run's [state events](/spec/1.0/events/state)
left behind. An absent `state` means the empty object: nothing has been
agreed, and `{}` is nothing. A producer that emits state deltas MUST compute
them against this value until its own first snapshot replaces it.

## `forwardedProps`

OPTIONAL. An application-specific channel passed through to the agent untouched.
Any JSON value except a whole `null`, which means the field is omitted. Null
values inside the payload are preserved. The protocol attaches no meaning to the
payload, and intermediaries MUST NOT alter it.

## `resume`

OPTIONAL. Answers to the interrupts that ended a previous run, when this run
continues from one. The entries and their obligations are specified in
[Interrupts and Resume](/spec/1.0/basic/patterns/interrupt-resume).

## Error Handling

An input a producer cannot parse, or that is malformed — a known field
carrying a value the schema rejects — is rejected before `RUN_STARTED`,
through the transport's error path: the run never starts, and no stream
exists for a `RUN_ERROR` to travel on. How the rejection is delivered is each
[transport binding](/spec/1.0/basic/transports)'s business.

Unrecognised members of the input are not malformed. The
[processing model](/spec/1.0/basic/processing)'s asymmetry binds this
direction too: a producer meeting input material it does not recognise strips
it with a warning and runs, so a newer consumer's input does not bounce off
an older producer.


# HTTP + Protobuf
Source: https://docs.ag-ui.com/spec/1.0/basic/transports/http-protobuf

The binary binding: the same POST, a stream of length-prefixed protobuf frames back — 1.0

The binary binding, for consumers that want a compact wire. It shares the
[SSE binding](/spec/1.0/basic/transports/http-sse)'s request half entirely —
the run input is the same JSON POST — and differs only in the response.

## Negotiation

* A client that wants this binding includes
  `application/vnd.ag-ui.event+proto` in its `Accept` header, alongside
  `text/event-stream`. Admission is what opts in — a wildcard range
  (`*/*`, `application/*`) admits the media type too — so a client that
  cannot consume protobuf MUST send an explicit `Accept` naming what it can,
  rather than a wildcard or down-ranked entry: relative quality values
  between the two media types are not consulted.
* A producer that supports the binding SHOULD answer with it whenever the
  client's `Accept` admits the media type with a positive quality, and MUST
  answer SSE otherwise. A producer that does not support it ignores the media
  type — which is why a client MUST always be prepared to receive SSE.
* The response's `Content-Type` is exactly `application/vnd.ag-ui.event+proto`;
  the consumer selects its parser by this header.

## Framing

The response body is a sequence of frames, each one protocol event:

* A frame is a 4-byte length header — an unsigned 32-bit big-endian integer —
  followed by exactly that many bytes of one encoded event.
* Frames abut with no separator. A consumer MUST tolerate frames split across
  transport chunks and multiple frames within one chunk.
* A body that ends mid-frame is a
  [truncated run](/spec/1.0/basic/transports#truncation).

## The wire schema

The protobuf message definitions are generated from the same
[JSON Schema](/spec/1.0/schema-files) the SDKs are generated from; the wire
schema is not a second source of truth. Cross-implementation parity is part of
the conformance surface: a corpus of canonical events pins the encoded bytes,
and every first-party encoder MUST reproduce the corpus byte for byte. (The
corpus is the guarantee — two encoders handed the same *semantic* value may
still order the entries of an open JSON object differently, which protobuf
map encoding makes visible.)

Semantics stay as close to the SSE binding as a binary wire allows:

* An event decoded from a frame enters the same
  [processing pipeline](/spec/1.0/basic/processing) as an event parsed from
  SSE — middleware first, enforcement after, identically.
* Material the wire schema carries as open payloads — `RUN_FINISHED.outcome`,
  metadata, state, `rawEvent` — survives decoding and reaches that pipeline:
  an unrecognised outcome arriving on this binding is stripped by enforcement
  with a warning, exactly as on SSE, and the binding MUST NOT reject it at
  decode time.
* The binary wire is inherently narrower for the rest. A *field* this build's
  wire schema predates is skipped by protobuf decoding itself, silently — the
  stripped-with-warning behaviour is fully observable only on the JSON wire.
  The same narrowing covers protocol-legal open members the wire schema does
  not model: a JSON Patch operation's extension members, which the JSON wire
  MUST preserve, do not survive this one.
  An *event* whose envelope arm this build predates carries no type string to
  hand onward, so the binding drops the frame with a warning — the same
  answer enforcement gives, spelled at the transport.
* A frame whose bytes do not decode as a message is malformed transport
  material and fatal to the stream. A body that simply ends mid-frame is not:
  that is a [truncated run](/spec/1.0/basic/transports#truncation).

## Errors

Identical to the [SSE binding](/spec/1.0/basic/transports/http-sse#errors):
rejection before the stream is an HTTP error status; failure inside the stream
is `RUN_ERROR`, as a frame like any other.


# HTTP + Server-Sent Events
Source: https://docs.ag-ui.com/spec/1.0/basic/transports/http-sse

The default binding: a POST carrying the run input, a text/event-stream carrying the run — 1.0

The default binding. The application POSTs the run input to the agent's
endpoint; the response is a
[Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html)
stream carrying the run.

## Request

* The client sends `POST` to the agent endpoint. The body is the
  [`RunAgentInput`](/spec/1.0/basic/run-input) as a single JSON object,
  UTF-8 encoded, with `Content-Type: application/json`.
* The client sends `Accept: text/event-stream` (adding the
  [protobuf media type](/spec/1.0/basic/transports/http-protobuf) when it
  can consume that binding too).

## Response

* A run that starts answers `200` with `Content-Type: text/event-stream`.
* Each SSE event's `data` payload is exactly one protocol event as a JSON
  object — never more than one, never a fragment. Multi-line `data:` fields
  join as SSE specifies.
* A producer MUST frame the stream with LF (`\n`) line endings. The SSE
  grammar also admits CR and CRLF, but this binding pins the one form every
  consumer is known to parse; a consumer MAY additionally accept the full
  grammar.
* A consumer MUST ignore SSE fields other than `data` (`event:`, `id:`,
  `retry:`) and MUST tolerate SSE comment lines (`: keep-alive`), which
  producers MAY send at any cadence.
* The producer closes the response body after the last run's terminal event.
  One POST carries one request; a response MAY nevertheless carry
  [several runs](/spec/1.0/events/lifecycle#several-runs-on-one-stream) when
  the producer is replaying a thread's history ahead of the requested run — no
  further input travels for those, per the
  [binding contract](/spec/1.0/basic/transports#the-binding-contract).

## Errors

* Input rejected before the run starts — malformed JSON, failed validation,
  refused auth — is an HTTP error status with no event stream. The run never
  started.
* A failure after the stream opens travels in-stream, as `RUN_ERROR`. The HTTP
  status is already sent and cannot change; a consumer MUST NOT infer success
  from `200` alone.
* A connection that drops without a terminal event is a
  [truncated run](/spec/1.0/basic/transports#truncation).

## No resumption

The binding has no stream resumption: SSE's `Last-Event-ID` mechanism is not
used, and a broken stream cannot be re-entered. Re-running is a new run with a
new `runId`, whose input carries whatever the consumer retained.

## Example

```
POST /agent HTTP/1.1
Content-Type: application/json
Accept: text/event-stream

{"threadId":"thr-1","runId":"run-1","messages":[…]}

HTTP/1.1 200 OK
Content-Type: text/event-stream

data: {"type":"RUN_STARTED","threadId":"thr-1","runId":"run-1"}

data: {"type":"TEXT_MESSAGE_START","messageId":"msg-1","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-1","delta":"Hello."}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg-1"}

data: {"type":"RUN_FINISHED","threadId":"thr-1","runId":"run-1"}
```


# Transports
Source: https://docs.ag-ui.com/spec/1.0/basic/transports/index

What a transport must provide to carry AG-UI, and the standard bindings — 1.0

Protocol semantics are identical on every transport. A transport is a
**binding**: it defines how the [run input](/spec/1.0/basic/run-input) is
delivered, how events are framed and encoded, and how a stream terminates or
fails. It does not define what events mean — the
[event patterns](/spec/1.0/basic/patterns) and the
[processing model](/spec/1.0/basic/processing) are the same on every
binding.

## The binding contract

A binding MUST provide:

* **Ordered, complete delivery** of a run's events, in the order the producer
  emitted them. The protocol's order is arrival order; a transport that can
  reorder or drop events cannot carry AG-UI without a layer that restores both.
* **Delivery of the `RunAgentInput` that opens the exchange**, before any
  events. A stream that goes on to carry
  [further runs](/spec/1.0/events/lifecycle#several-runs-on-one-stream) —
  a replayed thread — delivers no further input for them: those runs are the
  producer restating history, and each `RUN_STARTED` MAY carry its own
  `input` echo.
* **A termination signal** a consumer can tell from truncation: a stream that
  ends cleanly after a terminal event is a closed run, and a connection that
  dies without one is a truncated run.
* **An error path for rejected input** — a structurally invalid
  `RunAgentInput` is refused before `RUN_STARTED`, outside the stream.

Authentication and authorization are properties of the binding and the
application, not of the protocol: AG-UI defines no credential, and a binding
carries whatever its channel uses (HTTP authentication, ambient process
identity, or nothing).

## Standard bindings

1. [HTTP + Server-Sent Events](/spec/1.0/basic/transports/http-sse): the run
   input is an HTTP POST; the events stream back as SSE frames carrying JSON.
2. [HTTP + Protobuf](/spec/1.0/basic/transports/http-protobuf): the same
   POST, negotiated to a binary response of length-prefixed protobuf frames.

Both bindings share the request half; they differ only in the response
encoding, selected by content negotiation. An implementation that speaks HTTP
MUST support the SSE binding; the protobuf binding is OPTIONAL.

## Truncation

A consumer whose stream ends without a terminal event has a truncated run: the
producer may have kept going, but this consumer will never see the rest. A
truncated run has no outcome. A consumer MUST NOT synthesize a `RUN_FINISHED`
for it and MUST NOT report it as having succeeded; everything the run
delivered before the break remains delivered. Whether and how to surface the
truncation beyond that — leaving the run unresolved, or raising a synthetic
failure — is the consumer's business; re-running is a new run with a new
`runId`.

## Custom transports

Implementations MAY carry AG-UI over other channels — WebSockets, message
buses, in-process pipes. A custom transport MUST preserve the event model, the
event patterns, and the processing rules, and MUST satisfy the binding
contract above. It SHOULD document its framing, its input delivery, and its
termination and error signals, to aid interoperability.

A custom transport that carries JSON SHOULD frame events exactly as the SSE
binding does — one event object per frame — rather than inventing a new
envelope: the SSE binding's framing is the protocol's JSON framing, and only
its HTTP mechanics are specific to HTTP.


# Versioning and Compatibility
Source: https://docs.ag-ui.com/spec/1.0/basic/versioning

Talking to an older peer, what may be dropped, and when losing content obliges a warning — 1.0

Two parties on one stream are rarely the same age. This page states what each
owes the other when they are not.

## The default: additions are safe

The protocol grows by adding — new event types, new optional fields, new members
of an open union. Every such addition MUST be safe for an older party to meet,
because [unrecognised material survives rather than aborting the
run](/spec/1.0/basic/processing).

It follows that a producer MUST NOT place in an addition alone anything the
protocol already has a described place for. Concretely: the run's outcome, the
content of a message, the identity of a tool call and the result of one MUST
travel in the fields the schema describes for them, never only in a new event
type or a new property that an older consumer will drop.

## Downgrading

A party that knows its peer is older MAY translate the stream into a shape the
peer understands. A downgrade removes or reshapes what is there; it MUST NOT
invent meaning. Supplying an empty value for a field the older schema requires —
an empty string where content is now absent — is reshaping and is permitted.
Supplying a non-empty value the producer never sent is inventing meaning and is
forbidden.

A downgrade MUST NOT repair a malformed value on the way past. A known field
carrying a value the schema rejects is fatal, and a shim that turns it into
something acceptable hides a defect that would otherwise have been reported.

Downgrades fall into two kinds, and the difference decides whether anyone has to
be told.

**Lossless.** The removed material adds nothing the older party could act on.
Stripping `subagentRunId` for a peer with no concept of subagents is lossless in
this sense: the events still arrive, they simply flatten into one thread. A
lossless downgrade MAY be silent.

**Lossy.** Content that carries meaning is dropped or degraded. Removing a
lifecycle event, dropping a content part a peer cannot represent, or collapsing
a structured value into a lesser one all lose something a reader would have seen.
A lossy downgrade MUST emit a warning that names what was lost and why.

The warning is for the developer, not the end user. It MUST identify the shape
that was dropped, and SHOULD say what to upgrade to remove it. An implementation
MAY offer a way to silence these warnings, and MUST NOT silence them by default.

## Retired shapes

A shape the protocol once described and no longer does is *retired*. Retirement
is not deletion: an older producer still sends it, and a consumer that simply
dropped it would break a working integration.

* A retired shape MUST be recorded in the deprecation registry, together with
  what replaces it, where the translation lives, and when the translation itself
  expires.
* A consumer SHOULD translate a retired shape into its replacement rather than
  drop it.
* That translation MUST run as middleware — before enforcement — because
  enforcement judges against the current protocol, in which the retired shape is
  simply unrecognised.
* A translation that loses content in the process MUST warn, by the rule above.

Once a retired shape's expiry has passed, an implementation MAY remove the
translation, after which the shape is unrecognised like anything else.

## Version negotiation

The version travels in-band, on the two messages that open each side of the
exchange, so a recorded exchange stays self-describing and no transport has to
carry it:

* A consumer declares the protocol version it speaks on
  [`RunAgentInput.protocolVersion`](/spec/1.0/basic/run-input#protocolversion).
* A producer declares the version *it* speaks on
  `RUN_STARTED.protocolVersion` — its own, never an echo of the input's. The
  pair is the whole negotiation: each side states itself once, and a consumer
  sees a downgrade the moment it happens.
* Both fields are optional in the schema because absence means something: a
  peer from before the protocol carried a version. An implementation of this
  version MUST send its declaration, except where the consumer knows its peer
  predates the field and omits it rather than hand an unknown input member to
  an old parser.
* The value is a version identifier this specification publishes — the
  segment a frozen version lives under, `MAJOR.MINOR`, compared numerically
  component by component (so `1.10` is newer than `1.9`). A declaration a
  party cannot interpret is handled like a newer one: proceed, and SHOULD
  warn.
* A producer meeting a **newer minor of a line it implements** MUST serve the
  run — additions are safe, by the rules above — answer with its own version,
  and SHOULD warn. It MAY reject, before `RUN_STARTED`, only a declaration
  from a major line it does not implement; a newer minor of its own line is
  serveable by construction and MUST NOT be rejected for its version. A
  consumer meeting a newer producer declaration proceeds under the
  [processing model](/spec/1.0/basic/processing) and SHOULD warn.
* The declaration names what the run's stream *speaks*, not who is relaying
  it: a proxy that forwards a run untranslated declares what the original
  producer spoke, and one that translates declares what it emits. On a
  [stream carrying several runs](/spec/1.0/events/lifecycle#several-runs-on-one-stream)
  each run's `RUN_STARTED` declares its own run, which is how a replay of
  mixed-age history stays truthful; a producer generating runs live does not
  change what it speaks mid-stream.
* A transport MAY mirror the declaration into its own envelope — a media-type
  parameter, say — for intermediaries that cannot read the body. The in-band
  field is authoritative; a binding that mirrors defines how a mismatch is
  treated.

Where a party knows the other's version — declared in-band, or configured — it
MAY select a downgrade on that basis. Where it does not, it MUST behave as
though the peer were current: guessing downward would degrade streams for no
reason.

A downgrade selected by version MUST be a pure transformation of the stream. It
MUST NOT change the run's outcome, alter identifiers, or reorder events.

## What a producer owes

* Declare the protocol version it speaks on `RUN_STARTED`.
* Emit only shapes the current protocol describes.
* Omit optional fields that have no value rather than sending `null`.
* Never depend on the consumer understanding an addition.

## What a consumer owes

* Declare the protocol version it speaks on the run input, except toward a
  peer it knows predates the field.
* Survive unrecognised events, properties and union members; fail on malformed
  known values.
* Run middleware before enforcement, and enforcement before application code.
* Warn when a translation loses content.
* Never present material to application code that enforcement would have
  removed.


# Key Changes
Source: https://docs.ag-ui.com/spec/1.0/changelog

What 1.0 changes against the 0.x line — 1.0

This page lists the behavioural changes 1.0 makes against the 0.x
line of the protocol, for reviewers who know 0.x and want the differences
rather than the whole document. It is informative: the linked pages are the
specification.

## Major changes

1. **The specification exists.** 0.x defined shapes; behaviour lived in the
   TypeScript client. The rules on these pages — sequencing, unknown versus
   malformed, warnings, attribution — are now normative, written in
   [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) language, with the
   [schema](/spec/1.0/schema) authoritative for structure and this
   document authoritative for behaviour.

2. **Runs report how they ended.** `RUN_FINISHED` carries an optional
   `outcome`: absent or success means success, the interrupt outcome carries
   what the run is waiting for, and the
   [cancelled outcome](/spec/1.0/events/lifecycle#cancelled-runs) marks a
   run stopped on purpose before it completed. With it come `Interrupt`,
   resume entries on the [run input](/spec/1.0/basic/run-input), and the
   [interrupt–resume pattern](/spec/1.0/basic/patterns/interrupt-resume).
   Every producer written before outcomes existed is already conformant.

3. **Subagents.** Delegated work is attributed with `subagentRunId` on the
   events that can carry it, optionally announced by `SUBAGENT_STARTED` and
   closed by `SUBAGENT_FINISHED` or `SUBAGENT_ERROR`, with
   [rules for ownership, nesting, parallelism and termination](/spec/1.0/events/subagents).

4. **Reasoning replaces thinking.** The 0.x `THINKING_*` events are retired in
   favour of the [reasoning family](/spec/1.0/events/reasoning): spans,
   streamed reasoning messages matched by `messageId`, and
   `REASONING_ENCRYPTED_VALUE` for provider artefacts a consumer stores and
   returns without reading. Retired shapes are translated at the
   [compatibility boundary](/spec/1.0/basic/versioning#retired-shapes), not
   dropped.

5. **Activity events.** `ACTIVITY_SNAPSHOT` and `ACTIVITY_DELTA` carry
   [structured progress](/spec/1.0/events/activity) as messages whose
   content is an object, amended by JSON Patch.

6. **Unknown versus malformed, normatively.** Unrecognised events, fields and
   union members survive translation to enforcement, which drops an unknown
   event and strips unknown members, warning as it goes; a malformed known
   value is fatal. Nothing is removed before
   the translators have had their chance, and both transports feed one
   [processing pipeline](/spec/1.0/basic/processing), which also states the
   pipeline's one admitted narrowing for chunk fields.

7. **The chunked form has rules.** First chunks MUST carry what opening
   requires (`messageId` and role semantics for text, `toolCallId` and
   `toolCallName` for tool calls); later chunks MAY omit them; a continuation
   repeating an opener field with a conflicting value is fatal
   ([streaming pattern](/spec/1.0/basic/patterns/streaming)).

8. **A binary wire.** The [HTTP + Protobuf binding](/spec/1.0/basic/transports/http-protobuf)
   is specified — negotiated by media type, 4-byte length-prefixed frames,
   generated from the same schema, with cross-implementation parity pinned by
   a shared byte corpus.

9. **Capabilities are in the schema.** The `AgentCapabilities` declaration
   the SDKs carried as three hand-written copies is now defined once, in the
   schema, and generated for every SDK. Its semantics are stated:
   omitted means undeclared, declarations are informative and the stream is
   authoritative, and retrieval is deliberately left to the implementation
   ([Capabilities](/spec/1.0/basic/capabilities)). The subagent list is
   spelled `subagents`, matching `subagentRunId`; the earlier `subAgents`
   key is not read.

10. **Tool results carry content parts.** `TOOL_CALL_RESULT.content` and the
    tool message it mints accept a string or an ordered list of the same
    parts a user message carries, so a tool can return a document, an image
    or a search hit without encoding it into a string
    ([Tool calls](/spec/1.0/events/tool-calls#result-content)). The parts
    are renamed for it — `InputContent` → `ContentPart`, `TextInputContent` →
    `TextPart`, `ImageInputContent` → `ImagePart` and so on, `InputContentSource`
    → `PartSource` with `DataSource` and `UrlSource` — because a part named by
    direction is misnamed the moment it travels the other way. The wire is
    unchanged: every `type` value is the same, only the definition names and
    anchors move, and the SDKs keep the old names as aliases. Every part gains
    an optional `id`, and the text part gains the `metadata` the media parts
    already had. `ReasoningPart`, `ToolCallPart` and `AssistantPart` are
    reserved for the release in which assistant messages carry parts too.

## Minor changes

1. `tools` and `context` on the run input are optional: absent and empty mean
   the same thing ([Run input](/spec/1.0/basic/run-input)).
2. Metadata merge semantics are normative: per key, last write wins, no
   recursion, per-family merge targets; the `ag-ui` key is reserved
   ([Metadata](/spec/1.0/basic/metadata)).
3. Absent means absent: optional fields are omitted, never `null`
   ([The event model](/spec/1.0/basic#absent-means-absent)).
4. `RUN_FINISHED` and `RUN_ERROR` MAY carry per-provider token usage, in one
   accounting: the input and output counts are totals, cached and reasoning
   tokens are parts of them, cache reads and cache writes are reported
   separately, and usage follows the run boundary — subagents' calls in,
   child and resumed runs' calls out
   ([Runs and steps](/spec/1.0/events/lifecycle#token-usage)).
5. A run that stops on a frontend tool call finishes as success, never as an
   interrupt, and the success outcome MAY name the calls it left unanswered
   in `pendingToolCallIds`
   ([Tool calls](/spec/1.0/events/tool-calls#frontend-tools)).
6. Input messages MAY carry multimodal content parts (text, image, audio,
   video, document), by URL, as inline data or as a provider file handle —
   the `file` source, new in 1.0, for bytes already uploaded to the model
   provider ([Run input](/spec/1.0/basic/run-input#provider-file-handles)).
7. `TOOL_CALL_RESULT` is a message in its own right and does not reopen the
   call it answers ([Tool calls](/spec/1.0/events/tool-calls)).
8. A late `RUN_ERROR` after `RUN_FINISHED` is admitted, reporting a failure
   that surfaced after success was already reported
   ([Runs and steps](/spec/1.0/events/lifecycle)).
9. A consumer keeps a stream it rejects apart from a run that reports its own
   failure, and "treat the run as failed" is defined: surface it, never report
   success, with the API shape left to the implementation
   ([Runs and steps](/spec/1.0/events/lifecycle#error-handling)).
10. The protocol version travels in-band: consumers declare theirs on
    `RunAgentInput.protocolVersion`, producers answer with their own on
    `RUN_STARTED.protocolVersion`, and absence identifies a pre-versioning
    peer ([Versioning](/spec/1.0/basic/versioning#version-negotiation)).


# Activity
Source: https://docs.ag-ui.com/spec/1.0/events/activity

Structured progress a UI renders as its own widget, kept in the message sequence — 1.0

Activity is structured progress that is not conversation content — a search
running, a checklist filling in, a step a UI renders as its own widget. It is
materialised as a message so it keeps its place in the sequence, but its
content is an object, not text.

## Events

Activity binds the [snapshot–delta pattern](/spec/1.0/basic/patterns/snapshots),
scoped per activity message and matched by `messageId`.

### `ACTIVITY_SNAPSHOT`

Creates or replaces one activity message.

```json theme={null}
{
  "type": "ACTIVITY_SNAPSHOT",
  "messageId": "act-1",
  "activityType": "web_search",
  "content": { "query": "…", "found": 3 }
}
```

* `activityType` is an open string: the set is the producer's, not the
  protocol's. A consumer MUST tolerate types it does not recognise.
* A snapshot for a `messageId` the consumer has not seen creates the activity
  message, in sequence position at the point of arrival.
* A snapshot for an existing activity replaces its content and its
  `activityType`. `replace` is OPTIONAL; absent means it does, and that
  meaning is normative. An explicit `replace: false` asks the consumer to
  leave the existing message as it stands — content *and* `activityType`; the
  snapshot's own values apply only when it creates the message. It is not a
  merge.
* Replacement replaces *content*, not the metadata accumulated so far —
  metadata keeps merging under the
  [metadata rules](/spec/1.0/basic/metadata). Attribution is the
  exception: a replacing snapshot re-mints the activity, so the message's
  `subagentRunId` becomes the snapshot's own, including becoming absent.
* A `replace: false` snapshot for an existing activity does not re-mint
  ownership: the established owner stands, and the snapshot's own attribution
  MUST agree with it. The producer duty is the same one the
  [subagent rules](/spec/1.0/events/subagents) put on streamed
  continuations; the consumer obligation is deliberately weaker — the
  established owner stands and a consumer is not required to reject the
  disagreement, where a streamed continuation's mismatch must be rejected.

### `ACTIVITY_DELTA`

Amends one activity message's content with an RFC 6902 patch against it. The
delta's `activityType` replaces the message's — a delta MAY retype the
activity it amends, and a delta that does not intend to MUST repeat the
current type, since the field is required.

* A producer MUST NOT send a delta for an activity message it has not created
  with a snapshot — the snapshot is the baseline the
  [pattern](/spec/1.0/basic/patterns/snapshots) requires.
* A delta naming a message that does not exist, or one that is not an activity
  message, is skipped; the consumer SHOULD surface a warning, and MUST NOT
  fail the run.
* The patched result MUST still be an object: `content` is one by schema, and
  a producer MUST NOT send a patch — a root replacement, say — whose
  application would make it anything else. A consumer is not required to
  detect the violation.
* Patch failure handling is the
  [pattern](/spec/1.0/basic/patterns/snapshots#when-a-patch-does-not-apply)'s,
  with resynchronisation by a fresh snapshot of the same `messageId`.

## Activity messages in the conversation

An activity message appears in history with the fixed role `activity`. It is
rendering material for the consumer, not conversation the agent resumes from:
a consumer MUST strip activity messages from the `messages` it sends in
[run input](/spec/1.0/basic/run-input). How activity messages survive a
`MESSAGES_SNAPSHOT` is specified with that
[event](/spec/1.0/events/state#messages_snapshot).

## Message Flow

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant UI

    Agent->>UI: ACTIVITY_SNAPSHOT (act-1, "web_search", {query, found: 0})
    Note over UI: search widget appears
    Agent->>UI: ACTIVITY_DELTA (act-1, replace /found → 3)
    Agent->>UI: ACTIVITY_DELTA (act-1, add /results/0 …)
    Note over UI: widget updates in place
```

## Data Types

[`ActivitySnapshotEvent`](/spec/1.0/schema#activitysnapshotevent), [`ActivityDeltaEvent`](/spec/1.0/schema#activitydeltaevent) and [`ActivityMessage`](/spec/1.0/schema#activitymessage) are defined
by the [schema reference](/spec/1.0/schema). [`ActivityMessage`](/spec/1.0/schema#activitymessage) stands alone rather
than composing the base message, because its content is an object rather than
a string.

## Error Handling

Malformed activity events are fatal as malformed known values. The two
tolerated failures — a delta against a missing or non-activity message, and a
well-formed patch that does not apply — warn and skip, as above; both leave
the producer and consumer possibly disagreed about that activity, which the
producer's next snapshot repairs.


# Event Streams
Source: https://docs.ag-ui.com/spec/1.0/events/index

The eight event families, and who reacts to each — 1.0

Everything a producer has to say arrives as events, in eight families. Each
family binds one of the [event patterns](/spec/1.0/basic/patterns) and adds
its own rules; each is addressed to a different part of the consumer:

| Family | Events | Pattern | Consumed by |
| - | - | - | - |
| [Runs and steps](/spec/1.0/events/lifecycle) | `RUN_STARTED` · `RUN_FINISHED` · `RUN_ERROR` · `STEP_STARTED` · `STEP_FINISHED` | lifecycle | the client itself |
| [Text messages](/spec/1.0/events/text-messages) | `TEXT_MESSAGE_*` | streaming | the UI |
| [Tool calls](/spec/1.0/events/tool-calls) | `TOOL_CALL_*` | streaming | the application |
| [Reasoning](/spec/1.0/events/reasoning) | `REASONING_*` | streaming | the UI |
| [State](/spec/1.0/events/state) | `STATE_SNAPSHOT` · `STATE_DELTA` · `MESSAGES_SNAPSHOT` | snapshot–delta | the application store |
| [Activity](/spec/1.0/events/activity) | `ACTIVITY_SNAPSHOT` · `ACTIVITY_DELTA` | snapshot–delta | the UI |
| [Subagents](/spec/1.0/events/subagents) | `SUBAGENT_STARTED` · `SUBAGENT_FINISHED` · `SUBAGENT_ERROR` | lifecycle | the client itself |
| [Passthrough](/spec/1.0/events/passthrough) | `RAW` · `CUSTOM` | standalone | the application, opt-in |

The thirty-one event types these families comprise are enumerated on
[The Event Model](/spec/1.0/basic), and their shapes are the
[schema](/spec/1.0/schema)'s. Only the run lifecycle is mandatory for a
producer — every other family is a feature it emits when it has something to
say with it. A consumer MUST accept all of them: an event from a family a
consumer has no use for is still a well-formed event, not
[unrecognised material](/spec/1.0/basic/processing).

> [card] [Runs and steps](/spec/1.0/events/lifecycle)
>
> When a run begins and ends, and how steps mark its phases.

> [card] [Text messages](/spec/1.0/events/text-messages)
>
> The conversation itself, streamed as it is generated.

> [card] [Tool calls](/spec/1.0/events/tool-calls)
>
> The agent proposes, the application disposes.

> [card] [Reasoning](/spec/1.0/events/reasoning)
>
> The model's thinking, streamed, and the encrypted artefacts that
> round-trip it.

> [card] [State](/spec/1.0/events/state)
>
> Shared state and the conversation, replaced and amended.

> [card] [Activity](/spec/1.0/events/activity)
>
> Structured progress a UI renders outside the transcript.

> [card] [Subagents](/spec/1.0/events/subagents)
>
> Attribution, ownership, nesting, and how delegated work terminates.

> [card] [Raw and custom events](/spec/1.0/events/passthrough)
>
> The escape hatches, and their limits.


# Runs and Steps
Source: https://docs.ag-ui.com/spec/1.0/events/lifecycle

When a run begins and ends, what may happen in between, and how steps mark its phases — 1.0

A consumer sends a [`RunAgentInput`](/spec/1.0/basic/run-input); a producer
answers with a stream of events carrying one or more runs — the requested run,
possibly preceded by replayed history. This page states when a run begins and
ends and what those boundaries mean; the ordering rules *inside* a run belong
to the [event patterns](/spec/1.0/basic/patterns).

## The run

A stream MUST begin with `RUN_STARTED` or `RUN_ERROR`. A producer MUST NOT emit
any other event first, and a consumer MUST treat a stream that opens with
anything else as a protocol violation. `RUN_ERROR` is admitted first because a
run can fail before it begins — a transport that cannot reach the agent has a
failure to report and no run to report it against.

```mermaid theme={null}
stateDiagram-v2
    [*] --> Active: RUN_STARTED
    [*] --> Failed: RUN_ERROR
    Active --> Closed: RUN_FINISHED
    Active --> Failed: RUN_ERROR
    Closed --> Active: RUN_STARTED (a new run)
    Closed --> Failed: RUN_ERROR (late failure)
    Failed --> Active: RUN_STARTED (a new run)
```

### `RUN_STARTED`

Opens the run. It carries the run's identifiers; the producer's own
`protocolVersion` declaration, per the
[versioning rules](/spec/1.0/basic/versioning#version-negotiation); and MAY
echo the input the run was started from, so a consumer that did not make the
request can still see what the agent was asked. `parentRunId` names the run that spawned this
one,
when an agent invokes another agent as a separate run rather than as a
[subagent](/spec/1.0/events/subagents) within one.

### `RUN_FINISHED`

Closes a run that did not fail, and reports how it ended:

* Its `outcome` distinguishes a run that completed from one interrupted
  awaiting outside input, and from one stopped before it completed; an absent
  outcome means success. The interrupt outcome and what follows it are
  specified in
  [Interrupts and Resume](/spec/1.0/basic/patterns/interrupt-resume); the
  cancelled outcome is specified [below](#cancelled-runs). The outcome reports
  what the producer knows about why the run ended: a run that stopped on a
  [frontend tool call](/spec/1.0/events/tool-calls#frontend-tools) is a
  completed run whose success outcome MAY name the calls it left unanswered in
  `pendingToolCallIds`, because whether the application continues the thread
  after such a call is the application's decision, not the producer's.
* A producer MUST NOT send an outcome value the schema does not describe.
* `result` is OPTIONAL and carries the run's return value, if it has one.
* `usage` is OPTIONAL and reports token usage, one entry per provider and
  model, under the [accounting below](#token-usage). A consumer that only
  wants totals sums across the entries.

An outcome a consumer does not recognise is unrecognised material like any
other, and is stripped on the same terms as the rest. Stripping an optional
field leaves it absent, and an absent outcome means success — so a consumer is
not required to tell a run that completed from one that ended for a reason
named after that consumer shipped.

> [!NOTE]
>
> This bounds how far the outcome set can usefully grow. A terminal state added
> in a later version reaches an older consumer as a successful run, so a version
> that needs older consumers to *notice* a new way of ending cannot say so
> through `outcome` alone — it needs a carrier those consumers already treat as
> significant. It is also why the cancelled outcome below is named in 1.0
> rather than left for later: added afterwards, a cancelled run would reach
> every 1.0 consumer as a completed one.

### Cancelled runs

A run can be stopped on purpose before it completes — by the person it is
running for, by the application's own code, by a limit the producer enforces.
It did not fail, and it is not waiting for anything, but it did not complete
either, and a consumer that cannot tell it from a completed run presents
partial work as the whole. The cancelled outcome names that ending.

* A producer that stops a run before completion, for a reason that is not a
  failure, MUST close it with `RUN_FINISHED` carrying the cancelled outcome.
  It MUST NOT report a stopped run as success — neither with the success
  outcome nor by omitting the outcome.
* Everything that holds for a closed run holds here. A producer MUST close
  what the run opened — messages, tool calls, steps, subagents — before the
  `RUN_FINISHED` that cancels it, exactly as before one that succeeds. Closing
  a tool call establishes that its argument text is complete, not that it is
  valid, so a call cut off mid-arguments closes like any other and what to do
  with arguments that do not parse is the application's decision, per the
  [tool call rules](/spec/1.0/events/tool-calls#tool_call_end). A producer
  that cannot close in order — the stop tore down the stream under it —
  reports `RUN_ERROR` instead: that run did not end cleanly, and `RUN_ERROR`
  is the event for a run that did not.
* A cancelled run has no return value: `result` SHOULD be absent. `usage` MAY
  report the tokens accrued before the stop.
* A cancelled run waits for nothing. Its outcome carries no interrupts, and
  the next run on the thread is an ordinary new run, not a resume.
* A consumer MUST NOT present a cancelled run as having succeeded, and MUST
  NOT present it as having failed — a stop the user asked for is not an error
  to show them. Everything the run delivered before the stop remains
  delivered, as after `RUN_ERROR`. How to surface the stop beyond that is the
  consumer's business.

Cancellation is a producer's report about a run it was running. A consumer
that abandons a stream — closes the connection, stops reading — has a
[truncated run](/spec/1.0/basic/transports#truncation), not a cancelled one:
it MUST NOT synthesize a `RUN_FINISHED`, cancelled or otherwise, for a run
whose ending it never received.

### `RUN_ERROR`

Ends a run that failed. `message` says what went wrong, for a person to read;
`code` is OPTIONAL and machine-readable, an open string the protocol defines no
vocabulary for; `usage` MAY report tokens accrued before the failure, under
the same [accounting](#token-usage) as on `RUN_FINISHED`.

A `RUN_ERROR` is a well-formed event: the producer is reporting its own
failure, not sending something a consumer should reject. Treating a run as
failed means a consumer MUST surface the failure to application code and MUST
NOT report the run as having succeeded. It does not prescribe how — whether the
call that started the run raises, resolves with the failure, or reports it
through a callback is the implementation's business, and two conforming
consumers may differ.

### Token usage

`usage` on `RUN_FINISHED` and `RUN_ERROR` reports what the run's model calls
cost, one [`TokenUsage`](/spec/1.0/schema#tokenusage) entry per provider and
model. Providers count differently — one folds cached prompt tokens into its
input count, another reports them beside it, a third reports reasoning apart
from the rest of the output — so the protocol fixes one accounting and the
producer translates into it. Every count is either a total or a named part of
one:

* `inputTokens` is every prompt token the call was charged for: cached or not,
  written to a cache or not, text or not. `outputTokens` is every generated
  token, reasoning included.
* `cachedInputTokens` (cache reads), `cacheWriteInputTokens` (cache writes) and
  `reasoningTokens` are parts of those totals, never additions to them. The two
  cache counts are disjoint. A producer whose provider reports one of these
  beside a smaller total MUST add it into the total before emitting the entry;
  a producer whose provider already includes it MUST NOT add it again.
* `totalTokens` is `inputTokens` plus `outputTokens`. A producer MAY compute it
  rather than copy a provider's total, and MUST NOT copy a provider's total
  that counts differently.
* An absent count means the provider did not report it; a zero means it
  reported zero. A producer MUST NOT emit a zero for a count it has no data
  for, and a consumer MUST NOT read an absent count as zero.

The run is the accounting boundary:

* Usage covers every model call made within the run, including calls made by
  its [subagents](/spec/1.0/events/subagents): subagent events carry no
  usage of their own, and a subagent's calls are the run's.
* An agent invoked as a separate run — named by `parentRunId` — reports its
  own usage on its own terminal event, and the run that spawned it MUST NOT
  include that usage in its own.
* A run that [resumes](/spec/1.0/basic/patterns/interrupt-resume) an
  interrupted one reports only the calls it made itself. The interrupted run
  already reported its own, and a consumer wanting a thread's total sums
  across the thread's runs.

Under this accounting a consumer that only wants a total sums `totalTokens`
across entries and runs, and a consumer computing cost has each part it needs
to price cache reads, cache writes and reasoning at their own rates, without
double-counting any of them.

### After a run closes

A run ends with `RUN_FINISHED` or `RUN_ERROR`, after which it is closed. Once a
run has closed:

* A producer MUST NOT emit any further event for that run, other than the two
  named below.
* A producer MAY emit `RUN_STARTED` to begin a new run on the same stream.
* A producer MAY emit `RUN_ERROR` after `RUN_FINISHED`, reporting a failure
  that surfaced after the run reported success — a transport error while
  flushing, say. A consumer MUST treat the run as failed in that case.
* A producer MUST NOT emit anything after `RUN_ERROR` except `RUN_STARTED`.

A consumer MUST reject any other event that arrives after a run has closed.

### Several runs on one stream

A single stream MAY carry several runs in sequence — a replayed thread is the
common case. A producer MUST close the current run before opening the next: a
`RUN_STARTED` while a run is still active is a violation.

Across runs within a stream, messages accumulate and
[state](/spec/1.0/events/state) persists unless an event replaces it. A
producer restating history — a replayed thread whose material the consumer's
input already carried — MUST restate it as snapshots: `MESSAGES_SNAPSHOT`
reconciles by id and `STATE_SNAPSHOT` replaces, so a restatement the consumer
already holds is idempotent. Re-streaming a message the consumer already has
appends to it rather than restating it, which is why the streaming triads are
for new material only.

Run-scoped tracking — open messages, open tool calls, open steps, active
subagents — does not cross the boundary: `RUN_FINISHED` requires everything the
run opened to be closed already, and `RUN_ERROR` ends whatever was still open
along with the run. A new run starts with nothing open.

## Steps

Steps mark a run's phases, for a UI that shows progress. `STEP_STARTED` opens a
step and `STEP_FINISHED` closes it, matched by `stepName`.

* A producer MUST NOT open a step whose name is already open, and MUST NOT
  finish a step that was never opened.
* Every step a producer opens MUST be closed before the run finishes.
* Steps MAY overlap each other and anything else in the run; a step is a label
  over a span of the stream, not a container.

## Data Types

The event shapes are defined by the [schema reference](/spec/1.0/schema):
[`RunStartedEvent`](/spec/1.0/schema#runstartedevent), [`RunFinishedEvent`](/spec/1.0/schema#runfinishedevent) (with [`RunFinishedOutcome`](/spec/1.0/schema#runfinishedoutcome)),
[`RunErrorEvent`](/spec/1.0/schema#runerrorevent), [`StepStartedEvent`](/spec/1.0/schema#stepstartedevent), [`StepFinishedEvent`](/spec/1.0/schema#stepfinishedevent), and [`TokenUsage`](/spec/1.0/schema#tokenusage).

## Error Handling

Two different things end a run badly, and a consumer keeps them apart.

A **stream the consumer rejects** is a protocol violation it detected:
everything on this page a producer MUST NOT do is fatal when a consumer sees
it — an event before `RUN_STARTED`, an event after close other than the two
admitted, a nested `RUN_STARTED`, an unbalanced step, or anything still open at
`RUN_FINISHED`. The producer is at fault and the stream is not trustworthy.

A **run that reports its own failure** with `RUN_ERROR` is the opposite: a
conforming producer saying its work did not succeed. The stream is well formed
and the consumer accepts it, per the rule above.

A consumer MUST NOT present one as the other. A failed run of either kind keeps
everything it delivered before failing — `RUN_ERROR` says the run did not
complete, not that its events did not happen.


# Raw and Custom Events
Source: https://docs.ag-ui.com/spec/1.0/events/passthrough

The two escape hatches, and the limits that keep them from becoming a second protocol — 1.0

Two event types carry what the protocol does not model: `RAW`, a
provider-native event passed through untranslated, and `CUSTOM`, an
application's own event. Both are standalone — they open and close no items of
their own and MAY appear anywhere within an open run, though `CUSTOM`, unlike
`RAW`, does end an open [chunk stream](/spec/1.0/basic/patterns/streaming#closing-a-chunk-stream)
in its lane. Their limits are the
point: everything on this page exists so the escape hatches cannot quietly
become a second protocol.

## `RAW`

Passes a provider-native event through untranslated, for consumers that need
detail the protocol does not model.

```json theme={null}
{
  "type": "RAW",
  "event": { "…the provider's own event…": true },
  "source": "openai"
}
```

* `event` is REQUIRED and is any JSON value; `source` is OPTIONAL and names the
  provider or framework it came from.
* A consumer MUST NOT derive protocol behaviour from a `RAW` event: nothing in
  it opens, closes, or amends anything this specification tracks.
* A producer SHOULD emit `RAW` alongside the standard events, never instead of
  them. A producer that expresses something *only* as `RAW` has not put it in
  the protocol.

The same payload also travels as the `rawEvent` field on ordinary events —
that spelling attaches provenance to one translated event, where `RAW` carries
material no translated event exists for.

## `CUSTOM`

The protocol's extension point for an application's own events.

```json theme={null}
{
  "type": "CUSTOM",
  "name": "com.example.cart-updated",
  "value": { "items": 3 }
}
```

* `name` and `value` are REQUIRED — without a name a consumer cannot route the
  value, and an event with no payload says nothing.
* A consumer that does not recognise a `name` MUST ignore the event. This is
  protocol-legal traffic, not
  [unrecognised material](/spec/1.0/basic/processing): nothing is stripped
  and nothing warns.
* Names are application space. Producers SHOULD prefix names they invent with
  a vendor or application identifier, so two parties extending the same stream
  do not collide; names without a prefix are reserved for the protocol's own
  future use.
* Anything a consumer does with a recognised `CUSTOM` event is outside the
  protocol. A producer MUST NOT rely on a `CUSTOM` event to carry semantics
  this specification assigns to a standard event — a custom "message" that a
  conforming consumer legally ignores is not a message.

## Data Types

[`RawEvent`](/spec/1.0/schema#rawevent) and [`CustomEvent`](/spec/1.0/schema#customevent) are defined by the
[schema reference](/spec/1.0/schema).

## Security Considerations

Passthrough content is unvalidated by definition: no schema constrains
`event` or `value`, and `RAW` payloads originate wherever the provider got
them. A consumer MUST treat both as untrusted input — never rendered as
markup, executed, or granted authority — and SHOULD treat a `RAW` payload with
the same suspicion as the network traffic it summarises.


# Reasoning
Source: https://docs.ag-ui.com/spec/1.0/events/reasoning

Streaming what the model is thinking, and round-tripping what it must not reveal — 1.0

Reasoning is what the model thinks before it answers. A producer streams it so
a UI can show work in progress, and — where a provider keeps the real chain of
thought private — carries an encrypted artefact the consumer stores and
returns without being able to read.

## User Interaction Model

Reasoning is typically rendered apart from the conversation — collapsed by
default, styled as thinking. The protocol does not mandate any presentation; a
consumer MAY hide reasoning entirely.

## Events

### Spans: `REASONING_START` and `REASONING_END`

A reasoning span brackets one stretch of thinking, opened by `REASONING_START`
and closed by `REASONING_END`, matched by `messageId`. A span MAY contain
several reasoning messages.

* A producer MUST NOT open a span whose `messageId` is already open, MUST
  close every span it opens before the run finishes, and MUST NOT close a
  span it did not open.
* The span's identifier namespaces nothing: the reasoning messages inside a
  span carry their own `messageId`s.

### Reasoning messages

Reasoning messages follow the
[streaming pattern](/spec/1.0/basic/patterns/streaming):
`REASONING_MESSAGE_START` opens one (its `role` is fixed, `reasoning`),
`REASONING_MESSAGE_CONTENT` extends it, `REASONING_MESSAGE_END` closes it, all
matched by `messageId` — and `REASONING_MESSAGE_CHUNK` is the compact spelling,
whose first chunk MUST carry `messageId`. The pattern's rules apply exactly as
for text messages.

A consumer MUST detect a violation of that discipline and fail the run, on
spans and on reasoning messages alike:

* A `REASONING_MESSAGE_CONTENT` or `REASONING_MESSAGE_END` naming a message
  nothing opened has no referent, and a consumer MUST NOT invent the message
  an orphaned fragment names. The same shape is rejected for a text message;
  reasoning is not the exception.
* A `REASONING_END` naming a span nothing opened is rejected the same way, as
  is a `REASONING_START` reopening a span already open.
* A `REASONING_MESSAGE_START` naming a reasoning message that is already open
  is rejected too — the message must be closed with `REASONING_MESSAGE_END`
  before its `messageId` is used again. A span and the message inside it MAY
  share an identifier, so each is checked against its own open set.
* A span or a reasoning message still open when the run finishes fails the
  run.

Spans and reasoning messages are separate namespaces: a `REASONING_START` opens
a span and no message, so a fragment naming a span's `messageId` is orphaned
like any other.

### `REASONING_ENCRYPTED_VALUE`

Carries a provider's opaque, encrypted reasoning artefact. `subtype` says what
kind of thing `entityId` names — a message or a tool call — which decides where
the value is stored.

* A consumer MUST treat `encryptedValue` as opaque: never parsed, never
  interpreted, never assumed to be any particular format.
* A consumer MUST store the value with the message or tool call it names and
  return it unmodified in later run input, so the producer can restore the
  reasoning context it stands for. The rule presumes a target that can hold
  it: activity messages carry no encrypted value by schema, so an event
  naming one is treated as naming nothing the consumer knows — the
  unknown-`entityId` case below.
* A consumer that cannot preserve it — a downgrade path, a store that cannot
  carry it — is losing content and MUST warn
  ([Versioning](/spec/1.0/basic/versioning)).
* The artefact rides its message. A [`MESSAGES_SNAPSHOT`](/spec/1.0/events/state)
  restating the message replaces it wholesale, `encryptedValue` included — so
  a producer that still needs the artefact MUST restate it in the snapshot's
  copy, and one that omits it has withdrawn its own artefact. The consumer's
  duty is to return what it holds once all events have applied, not to
  resurrect what a snapshot removed.

The event is standalone: it opens nothing, closes nothing, and MAY appear
anywhere within an open run, though it conventionally arrives inside the span
whose thinking it captures.

## Message Flow

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Client

    Agent->>Client: REASONING_START (span-1)
    Agent->>Client: REASONING_MESSAGE_START (msg-9, reasoning)
    Agent->>Client: REASONING_MESSAGE_CONTENT (delta) ×N
    Agent->>Client: REASONING_MESSAGE_END (msg-9)
    Agent->>Client: REASONING_ENCRYPTED_VALUE (message, msg-9)
    Agent->>Client: REASONING_END (span-1)
    Note over Client: stores msg-9 with its encrypted value,<br/>returns both in the next run's input
```

## Data Types

The event shapes are defined by the [schema reference](/spec/1.0/schema):
[`ReasoningStartEvent`](/spec/1.0/schema#reasoningstartevent), [`ReasoningEndEvent`](/spec/1.0/schema#reasoningendevent), [`ReasoningMessageStartEvent`](/spec/1.0/schema#reasoningmessagestartevent),
[`ReasoningMessageContentEvent`](/spec/1.0/schema#reasoningmessagecontentevent), [`ReasoningMessageEndEvent`](/spec/1.0/schema#reasoningmessageendevent),
[`ReasoningMessageChunkEvent`](/spec/1.0/schema#reasoningmessagechunkevent), [`ReasoningEncryptedValueEvent`](/spec/1.0/schema#reasoningencryptedvalueevent). In conversation
history a reasoning message is a [`ReasoningMessage`](/spec/1.0/schema#reasoningmessage).

## Error Handling

A `REASONING_ENCRYPTED_VALUE` whose `entityId` names nothing the consumer
knows cannot be stored where it belongs; a consumer SHOULD warn and MAY drop
it, and MUST NOT fail the run over it.

A malformed reasoning event — a missing required field, a `subtype` that is
not a string — is a malformed known value and fatal like any other. A
`subtype` that is a string the schema does not name is different: it is
unrecognised material — a member added after this consumer shipped — and the
[processing model](/spec/1.0/basic/processing) strips it with a warning,
which in a required position removes the event that carried it.

## Security Considerations

Reasoning content routinely contains material the producer chose not to say in
the answer. A consumer SHOULD treat it with the same confidentiality as the
conversation, and MUST NOT feed an `encryptedValue` to anything but the
producer that issued it — it is a capability for restoring context, not data
for the application.


# State
Source: https://docs.ag-ui.com/spec/1.0/events/state

The shared state and the conversation itself: replaced wholesale, amended by patch — 1.0

State is the value an agent and an application keep in sync — a plan, a form, a
document under construction. It travels by the
[snapshot–delta pattern](/spec/1.0/basic/patterns/snapshots); this page adds
what is specific to state and to the conversation's own snapshot.

## Events

### `STATE_SNAPSHOT`

Replaces the agent state wholesale. Sent when a delta cannot express the
change, or to resynchronise a consumer. A consumer MUST replace its state with
`snapshot` — no merging.

### `STATE_DELTA`

Amends the current state with an RFC 6902 patch. The baseline is the
consumer's current state: at the start of a run, the input's `state`; after
that, whatever the run's own snapshots and deltas have made of it. Everything
the [pattern](/spec/1.0/basic/patterns/snapshots) says about patches —
atomic application, open operations, failure handling, resynchronisation —
applies unchanged.

### `MESSAGES_SNAPSHOT`

The complete set of messages the producer owns, in order.

It is conversation-wide rather than a plain overwrite, because a consumer may
hold messages of its own that no producer tracks. Reconciliation:

* A message in the snapshot replaces the consumer's copy with the same id —
  *in place*: the consumer keeps its existing position for a message it
  already holds. A snapshot message the consumer has never seen is appended,
  in snapshot order. The snapshot's order is therefore authoritative only for
  messages the consumer meets for the first time; it does not reorder what the
  consumer already has.
* A consumer-held message *absent* from the snapshot is dropped — the producer
  is declaring the complete set — **except** client-only material the producer
  cannot know about: [activity](/spec/1.0/events/activity) messages, which
  never travel to the producer, and reasoning messages, which most producers
  do not track.
* The exception is per-role and self-revoking: a snapshot that itself carries
  any activity message is declaring the complete activity set, and the
  consumer's activity messages not in it are dropped like anything else. The
  same rule holds for reasoning messages.

Being conversation-wide, the snapshot carries no `subagentRunId` of its own;
it establishes each message's ownership through the messages it contains.

## Cross-run behaviour

State persists across runs on a thread until an event replaces it, and the
next run's input carries it back as the starting value — the loop that keeps
both sides agreed. Messages accumulate the same way;
`MESSAGES_SNAPSHOT` is the producer's way of restating that accumulation
outright.

## Message Flow

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Application

    Agent->>Application: STATE_SNAPSHOT {"draft": {"sections": []}}
    Agent->>Application: STATE_DELTA (add /draft/sections/0)
    Agent->>Application: STATE_DELTA (replace /draft/sections/0/status)
    Agent->>Application: RUN_FINISHED
    Application->>Agent: next RunAgentInput (state: the current value)
```

## Data Types

[`StateSnapshotEvent`](/spec/1.0/schema#statesnapshotevent), [`StateDeltaEvent`](/spec/1.0/schema#statedeltaevent) and [`MessagesSnapshotEvent`](/spec/1.0/schema#messagessnapshotevent) are defined
by the [schema reference](/spec/1.0/schema), with [`State`](/spec/1.0/schema#state) deliberately
unconstrained — any JSON value, not only an object — and deltas as
[`JsonPatch`](/spec/1.0/schema#jsonpatch).

## Error Handling

A structurally malformed patch is fatal; a well-formed patch that fails to
apply is warned about and skipped, per the
[pattern](/spec/1.0/basic/patterns/snapshots#when-a-patch-does-not-apply).

## Security Considerations

State events are remote writes into application state. An application MUST
validate what it reads out of state before acting on it — rendering it,
executing it, granting anything because of it — exactly as it would validate
any other input that crossed a trust boundary. A producer, in turn, SHOULD NOT
put secrets in state: it round-trips through the consumer and back on every
run.


# Subagents
Source: https://docs.ag-ui.com/spec/1.0/events/subagents

Attribution, ownership, nesting, parallel execution, state and termination — 1.0

An agent may delegate part of a run to another agent. Everything the delegate
produces travels in the same stream, so a consumer needs to know which work
belongs to whom without replaying the run.

## Attribution

`subagentRunId` identifies one invocation of a subagent. Events the subagent
produces carry it; events the parent agent produces do not. An absent
`subagentRunId` means the parent agent, and MUST NOT be spelled as `null`.

An id identifies an *invocation*, not an agent. A producer MUST NOT reuse a
`subagentRunId` for a second invocation within a run, even of the same subagent
— the second invocation gets its own id. An id MAY reappear in a later run, when
a suspended invocation is continued.

Which events can carry attribution is a structural question, and the
[schema](/spec/1.0/schema#attributable) answers it. Read a tag on a standalone event
— `STEP_*`, `CUSTOM`, `RAW`, the state events — as provenance: it records who
produced the event, not that the producer owns a private copy of what the event
touches.

## Lifecycle

`SUBAGENT_STARTED` announces an invocation, `SUBAGENT_FINISHED` closes it, and
`SUBAGENT_ERROR` reports that it failed. All three carry the `subagentRunId`
they concern, and a producer MUST NOT omit it.

* A producer that announces an invocation MUST do so before any event attributed
  to it.
* A producer MUST NOT announce an invocation whose id is already active.
* A producer MUST NOT reuse the id of an invocation that has already finished in
  this run.
* Every invocation a producer announces MUST be closed, by `SUBAGENT_FINISHED`
  or `SUBAGENT_ERROR`, before the run finishes.

A producer MAY attribute events without announcing anything. Such a stream tells
a consumer which work belongs together but not when an invocation began or
ended, and a consumer MUST accept it: `subagentRunId` is meaningful on its own,
and requiring the lifecycle events would make grouping unavailable to producers
that cannot report it. A producer that can report the lifecycle SHOULD, since a
consumer can then show an invocation as running rather than inferring it from
the events that happen to arrive.

`SUBAGENT_ERROR` ends the invocation, not the run. A parent agent MAY handle a
failed subagent and continue; that is why it is not `RUN_ERROR`.

A subagent's model calls are the run's: no subagent event carries token usage,
and the run's terminal event [reports](/spec/1.0/events/lifecycle#token-usage)
the whole run's usage, subagents included.

`SUBAGENT_FINISHED` reports why the segment ended. An absent outcome means
success. A suspended outcome means the invocation is paused awaiting outside
input — terminal for this stream but not for the invocation, which a later run
MAY continue under the same id. A producer MUST NOT send an outcome value the
schema does not describe, and MUST NOT attach interrupt ids to a success
outcome.

## Ownership

Attribution is not advisory. Once an entity is opened under an owner, every
event continuing it MUST agree about that owner.

* A `TEXT_MESSAGE_CONTENT` or `TEXT_MESSAGE_END` MUST NOT carry a
  `subagentRunId` that disagrees with the `TEXT_MESSAGE_START` that opened the
  message. It MAY omit the tag: an untagged continuation continues whatever the
  opener owns, and a producer that tags only the opener is still conformant.
* The same holds for reasoning messages, for tool calls against their
  `TOOL_CALL_START`, and for activity messages against the snapshot that opened
  them.
* A `STEP_FINISHED` MUST carry the same attribution as the `STEP_STARTED` it
  closes. Steps are per-owner: a parent and a subagent MAY each have a step of
  the same name open at once, and each closes its own.

A consumer MUST reject a continuation whose tag disagrees with its opener.
Accepting it would append one producer's content into another producer's
message, which no consumer can detect afterwards. A continuation carrying no tag
is not a disagreement and MUST be accepted.

A tool call inherits the attribution of the message that held it. A producer
MUST NOT attribute a tool call to one owner while the message carrying it is
attributed to another.

## Nesting and parallelism

A subagent MAY itself delegate. `parentSubagentRunId` on `SUBAGENT_STARTED`
names the invocation that spawned this one; absent means the parent agent
spawned it directly. A producer MUST NOT name a parent invocation that has not
been announced in this run.

Invocations MAY run in parallel, and their events MAY interleave arbitrarily.
Each invocation's entities are tracked separately, so two subagents MAY stream
messages at the same time. A consumer MUST NOT assume that one invocation's
events are contiguous, and MUST NOT close one invocation's entities because
another invocation ended.

## State

State is run-scoped. A `STATE_SNAPSHOT` or `STATE_DELTA` a subagent sends
updates the run's state exactly as one from the parent agent does, and a
consumer MUST apply it that way.

`subagentRunId` on a state event is provenance: it records which invocation
produced the update. It MUST NOT be read as the subagent owning a private state
of its own, and a consumer MUST NOT withhold the update from the run's state
because a subagent sent it. There is no per-subagent state in this protocol.

## Termination

A run MUST NOT finish while an invocation is still active. A producer that
reaches the end of its work with an invocation open has a bug: either the
invocation ended and was not reported, or it did not end and the run is not
over.

`RUN_ERROR` ends everything. A consumer MUST treat every open invocation as
abandoned when a run errors, and MUST NOT expect a closing event for any of
them.

When a run finishes with an interrupt outcome, the interrupts it carries MAY be
attributed. An interrupt tagged with a `subagentRunId` was raised inside that
invocation; an untagged one belongs to the parent agent. An invocation suspended
because a descendant interrupted owns no interrupt of its own, so a suspended
outcome MAY carry no interrupt ids at all.


# Text Messages
Source: https://docs.ag-ui.com/spec/1.0/events/text-messages

Streaming conversational text from the agent to the user — 1.0

Text messages are the conversation itself: the words a user reads. A producer
streams each message as it is generated, so a UI can render text as it arrives
rather than waiting for the message to finish.

## User Interaction Model

Text messages are typically rendered as a chat transcript, each message
appearing incrementally as its content streams. The protocol does not mandate
any particular presentation — a consumer MAY buffer a whole message before
showing it, or render token by token.

## Events

Text messages follow the [streaming pattern](/spec/1.0/basic/patterns/streaming),
matched by `messageId`. The pattern's rules — open before content, close before
the run finishes, no reopening an open id — apply as written there.

### `TEXT_MESSAGE_START`

Opens a message.

```json theme={null}
{
  "type": "TEXT_MESSAGE_START",
  "messageId": "msg-1",
  "role": "assistant"
}
```

* `role` is OPTIONAL; an absent role means `assistant`. The values a role may
  take are the [schema](/spec/1.0/schema#textmessagerole)'s business.
* `name` is OPTIONAL and labels the speaker within the role, for producers that
  distinguish several.

### `TEXT_MESSAGE_CONTENT`

Extends the open message. `delta` carries the next piece of the message's text;
deltas concatenate in arrival order.

```json theme={null}
{
  "type": "TEXT_MESSAGE_CONTENT",
  "messageId": "msg-1",
  "delta": "Hello, world."
}
```

### `TEXT_MESSAGE_END`

Closes the message. A closed message is closed, not sealed: a producer MAY
reopen the same `messageId` with a new `TEXT_MESSAGE_START`, and the message
continues, its further content appending to what was already there. A
reopening `TEXT_MESSAGE_START` MUST agree with the message it reopens — the
same owner, the same `role`, the same `name`; the message's established values
stand, and a consumer is not required to detect the disagreement. A later
[`MESSAGES_SNAPSHOT`](/spec/1.0/events/state) MAY also restate the message
wholesale. What no event can do is change a closed message's content by any
other means.

> [!NOTE]
>
> Within a run, a reopening under a different owner is the attribution
> mismatch the [subagent rules](/spec/1.0/events/subagents) already reject.
> Across runs the consumer's ownership tracking has reset, which is why
> detection of a cross-run mismatch is not required — the producer's
> obligation is the same either way.

### `TEXT_MESSAGE_CHUNK`

The compact spelling. A consumer MUST expand chunks into the three events above
as the [streaming pattern](/spec/1.0/basic/patterns/streaming#the-chunked-form)
specifies, including the first-chunk requirements and the conflicting-repeat
rule.

## Message Flow

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Client
    participant UI

    Agent->>Client: TEXT_MESSAGE_START (msg-1, assistant)
    Client->>UI: new message appears
    loop streaming
        Agent->>Client: TEXT_MESSAGE_CONTENT (delta)
        Client->>UI: text grows
    end
    Agent->>Client: TEXT_MESSAGE_END (msg-1)
    Client->>UI: message complete
```

## Data Types

The event shapes are defined by the [schema reference](/spec/1.0/schema):
[`TextMessageStartEvent`](/spec/1.0/schema#textmessagestartevent), [`TextMessageContentEvent`](/spec/1.0/schema#textmessagecontentevent), [`TextMessageEndEvent`](/spec/1.0/schema#textmessageendevent),
[`TextMessageChunkEvent`](/spec/1.0/schema#textmessagechunkevent). The assembled message appears in conversation history
as an [`AssistantMessage`](/spec/1.0/schema#assistantmessage), [`UserMessage`](/spec/1.0/schema#usermessage), [`SystemMessage`](/spec/1.0/schema#systemmessage) or [`DeveloperMessage`](/spec/1.0/schema#developermessage)
according to its role.

Metadata on any of a message's events merges into the message under the
[metadata rules](/spec/1.0/basic/metadata): key by key, last write
winning.

## Error Handling

A `TEXT_MESSAGE_CONTENT` or `TEXT_MESSAGE_END` for a `messageId` that is not
open, or a `TEXT_MESSAGE_START` for one that is, is a malformed sequence and
fatal to the run. A message left open when the run finishes is likewise a
violation. These are the [streaming pattern](/spec/1.0/basic/patterns/streaming)'s
rules; nothing about text messages softens them.


# Tool Calls
Source: https://docs.ag-ui.com/spec/1.0/events/tool-calls

How an agent proposes a call, streams its arguments, and receives its result — 1.0

A tool call is the agent asking for something to be done. When the tool is one
the application advertised in its [run input](/spec/1.0/basic/run-input), the
application executes it — which makes tool calls the protocol's
human-in-the-loop core: the agent proposes, the application disposes.

## User Interaction Model

Applications typically surface a tool call as it streams — a card naming the
tool, arguments filling in — and, for side-effectful tools, ask the user before
executing. The protocol does not mandate any particular interaction model, but
see [Security Considerations](#security-considerations) below.

## Events

Tool calls follow the [streaming pattern](/spec/1.0/basic/patterns/streaming),
matched by `toolCallId`.

### `TOOL_CALL_START`

Opens a call.

```json theme={null}
{
  "type": "TOOL_CALL_START",
  "toolCallId": "call-1",
  "toolCallName": "search",
  "parentMessageId": "msg-1"
}
```

* `toolCallName` names the tool being called.
* `parentMessageId` is OPTIONAL and attaches the call to the assistant message
  that carries it. When the parent message is attributed to a subagent, the
  call MUST agree with that attribution — a tool call belongs to the message
  that carries it (see [Subagents](/spec/1.0/events/subagents)).

### `TOOL_CALL_ARGS`

Extends the open call. `delta` carries the next piece of the call's arguments;
the concatenated deltas form the call's argument text, conventionally a JSON
document — but the protocol carries it as text and does not validate it, which
is deliberate: providers emit malformed argument strings, and the application
deciding what to do with one beats the transport killing the run.

A consumer MUST NOT act on the arguments before `TOOL_CALL_END`: until the call
closes, the text is a prefix of whatever the producer is sending, not the
thing itself.

### `TOOL_CALL_END`

Closes the call. The argument text is complete — closing establishes
completeness, not validity. Whoever executes the tool parses it, and what to
do with text that does not parse is the application's decision, not a
protocol violation.

A closed call, like a closed message, MAY be reopened by a new
`TOOL_CALL_START` with the same `toolCallId`, and further arguments append. A
reopening start MUST agree with the call it reopens — the same
`toolCallName`, the same `parentMessageId`, the same owner. A consumer is not
required to detect a disagreement, and unlike a
[reopened text message](/spec/1.0/events/text-messages#text_message_end),
the protocol makes no promise about which of the two values a consumer that
missed the violation ends up holding.

### `TOOL_CALL_CHUNK`

The compact spelling. A consumer MUST expand chunks as the
[streaming pattern](/spec/1.0/basic/patterns/streaming#the-chunked-form)
specifies: the first chunk MUST carry `toolCallId` and `toolCallName`, and a
continuation repeating `toolCallName` or `parentMessageId` with a conflicting
value is fatal.

### `TOOL_CALL_RESULT`

Carries the result of a call. It is a message in its own right — a tool message
with its own `messageId` — and does not reopen the call it answers.

```json theme={null}
{
  "type": "TOOL_CALL_RESULT",
  "messageId": "msg-2",
  "toolCallId": "call-1",
  "content": "3 results found."
}
```

A result MAY arrive in the same run as its call — an agent-executed tool — or
never arrive in the stream at all: a client-executed tool's result returns to
the producer as a tool message in the next run's input instead.

#### Result content

`content` MUST be either a string or an ordered list of
[`ContentPart`](/spec/1.0/schema#contentpart)s — the same parts a
[user message](/spec/1.0/basic/run-input#messages) carries: `text`, `image`,
`audio`, `video` and `document`, each media part with a `source` that is inline
data, a URL or a
[provider file handle](/spec/1.0/basic/run-input#provider-file-handles). The
tool message the event mints has the identical shape, so a result travels into
the next run's `messages` unchanged.

```json theme={null}
{
  "type": "TOOL_CALL_RESULT",
  "messageId": "msg-2",
  "toolCallId": "call-1",
  "content": [
    { "type": "text", "text": "Invoice INV-2291 attached." },
    {
      "type": "document",
      "source": { "type": "url", "value": "https://example.com/INV-2291.pdf", "mimeType": "application/pdf" },
      "metadata": { "title": "INV-2291" }
    }
  ]
}
```

* A tool returning structured data — a JSON object, say — serialises it into
  the string form or into a `text` part. The protocol has no JSON part: every
  provider accepts a tool result as text, and a typed object would have to
  become text at the provider boundary anyway.
* Anything a part does not model — a search hit's source and title, a
  document's filename — rides in the part's `metadata`. The protocol does not
  define provider-specific result blocks (a citation-enabled search result, a
  browser state); a producer that needs one maps it onto these parts or
  carries it as passthrough.
* A tool that uploaded its output to the model provider — a generated report
  now sitting in the provider's file store — returns the handle as a `file`
  source rather than re-sending the bytes; the
  [same rules](/spec/1.0/basic/run-input#provider-file-handles) apply as on
  input, and a consumer that renders the result treats the handle as opaque.
* A producer handed a part its model cannot take — an image to a text-only
  model, audio to a provider that accepts none in a tool result, a file handle
  another provider issued — MUST NOT fail
  the run because of it. It drops the part and continues, as the
  [run input rules](/spec/1.0/basic/run-input#messages) already say of user
  content, and it MUST still answer the call: a result whose every part was
  dropped is answered with the empty string, because a tool call left
  unanswered is one most models reject outright.
* A consumer that can only hold a string — a renderer, a store, a legacy
  bridge — renders a list of parts as its `text` parts concatenated in order
  and ignores the rest. Doing so is lossy and SHOULD be announced, the way any
  downgrade is ([Versioning](/spec/1.0/basic/versioning)).
* A peer from before content parts existed sends no `protocolVersion`; a
  producer that knows it is talking to one MAY flatten a result the same way
  before emitting it, and MUST warn when the flattening dropped a part. It
  MUST NOT put a placeholder in the dropped part's place: a downgrade
  reshapes, it does not invent.

## Frontend tools

The `tools` list in [run input](/spec/1.0/basic/run-input#tools) is the
application's: the agent proposes a call, the application executes it. The
protocol has no mid-run channel from the consumer, so the answer can only
cross a run boundary — which gives the round-trip its shape:

* A producer that calls a frontend tool MUST NOT answer it: no
  `TOOL_CALL_RESULT`, no fabricated tool message. The result is the
  application's to produce.
* The producer finishes the run with the call unanswered. It MUST use the
  success outcome, or none, and MUST NOT report the run as interrupted — and
  it SHOULD finish promptly once nothing remains that does not depend on the
  result. Several frontend calls MAY be left unanswered by one run; the
  application answers them all at once.
* The success outcome's `pendingToolCallIds` names the calls left unanswered,
  in the order they were made. A producer SHOULD send it when a run leaves
  calls pending; when it does, the list MUST contain exactly the tool calls
  the run started and did not answer with `TOOL_CALL_RESULT`. `RUN_FINISHED`
  alone does not say whether a run left work for the application: when the
  list is absent or empty, a consumer that needs to know derives it from the
  stream — every tool call the run started that received no result — and
  MUST NOT read absence as "nothing pending". On an interrupted run the
  pending calls are derived the same way; the interrupt outcome does not
  carry them.
* After the run finishes, the application disposes of each unanswered
  frontend call — executing it, or declining it, with whatever consent its
  own rules require. A thread that continues MUST answer every one of them
  first: the next
  run's `messages` carry a tool message per call, keyed by `toolCallId` — a
  failure is still an answer, as a tool message with `error` set, and a call
  the user declined is answered by saying so. The tool message's `content` is a
  string or a list of parts, exactly as on
  [`TOOL_CALL_RESULT`](#result-content): a frontend tool that produced a
  screenshot or picked a file answers with a media part rather than a
  description of one. An unanswered call leaves the
  agent mid-thought, and a history with a dangling call is one many models
  reject outright. Abandoning the thread answers nothing and violates
  nothing — the rule binds continuation, the same way resume coverage does.

This is a different round-trip from
[interrupts](/spec/1.0/basic/patterns/interrupt-resume): an interrupt is the
producer explicitly stopping to ask, answered by resume entries; a frontend
tool call rides the ordinary message loop, answered by conversation history.

> [!NOTE]
>
> A run that stops on a frontend tool call is a completed run, not an
> interrupted one, and it is not a third kind of ending either. The outcome
> reports what the producer knows about why the run ended, and here the
> producer does not know whether it is waiting: a frontend tool is often a
> terminal effect — render a chart, navigate, highlight — and whether its
> result starts another run is the application's decision, made by the
> application's rules for that tool. So the producer says what it does know —
> the run is complete, and these calls are unanswered — as detail on the
> success outcome, where an older consumer that strips the field still reads a
> successful run and derives the pending calls as it always has.

A producer SHOULD call frontend tools only from the advertised list; a call
naming a tool the input did not advertise is not by itself a protocol
violation — what to do with it is the consumer's decision. The producer's own
tools, executed agent-side, never needed advertising and answer in-stream via
`TOOL_CALL_RESULT`.

## Message Flow

A client-executed tool spans two runs:

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Application

    Agent->>Application: TOOL_CALL_START (call-1, "confirm_order")
    Agent->>Application: TOOL_CALL_ARGS (…)
    Agent->>Application: TOOL_CALL_END
    Agent->>Application: RUN_FINISHED
    Note over Application: executes the tool<br/>(with user consent where due)
    Application->>Agent: next RunAgentInput (messages include the tool result)
```

## Data Types

The event shapes are defined by the [schema reference](/spec/1.0/schema):
[`ToolCallStartEvent`](/spec/1.0/schema#toolcallstartevent), [`ToolCallArgsEvent`](/spec/1.0/schema#toolcallargsevent), [`ToolCallEndEvent`](/spec/1.0/schema#toolcallendevent),
[`ToolCallChunkEvent`](/spec/1.0/schema#toolcallchunkevent), [`ToolCallResultEvent`](/spec/1.0/schema#toolcallresultevent). In conversation history a call
appears as a [`ToolCall`](/spec/1.0/schema#toolcall) on an [`AssistantMessage`](/spec/1.0/schema#assistantmessage), and a result as a
[`ToolMessage`](/spec/1.0/schema#toolmessage) whose content is a string or a list of
[`ContentPart`](/spec/1.0/schema#contentpart)s. The advertised tools are [`Tool`](/spec/1.0/schema#tool) objects on [`RunAgentInput`](/spec/1.0/schema#runagentinput).

The parts are named by what they are — `TextPart`, `ImagePart` — rather than by
the direction they travel, because the same part goes into the model inside a
user message and comes out of the stream inside a tool result. The names
`ReasoningPart`, `ToolCallPart` and `AssistantPart` are reserved for a later
minor version, when assistant messages carry parts too; nothing defines them
yet, and a producer MUST NOT emit them.

## Error Handling

The [streaming pattern](/spec/1.0/basic/patterns/streaming)'s sequence rules
apply unchanged: continuing or closing a call that is not open, or reopening one
that is, is fatal. A call left open when the run finishes is a violation.

## Security Considerations

Tool calls are the protocol's largest attack surface, because they turn model
output into actions.

* Arguments are model-generated and MUST be treated as untrusted input:
  validated against the tool's declared parameter schema where one was
  advertised, scrutinised like any untrusted payload where none was, and
  never interpolated into shell commands, queries or markup unescaped.
* Applications SHOULD obtain user consent before executing a side-effectful
  tool call, and MUST NOT represent a call as user-approved when it was not.
* Tool results are data from wherever the tool got them. A consumer MUST NOT
  treat text inside a result as protocol material or as instructions carrying
  the user's authority.
* A call naming a tool that was not advertised SHOULD NOT be executed without
  the same scrutiny a new tool would get.


# Specification
Source: https://docs.ag-ui.com/spec/1.0/index

The behavioural specification for the AG-UI protocol — 1.0

AG-UI is an open protocol that standardizes how agents talk to user-facing
applications: one request in, one ordered stream of typed events out, carrying
everything the user sees of the agent — text, tool calls, reasoning, shared
state, progress.

This specification defines the authoritative protocol requirements, based on
the JSON Schema in [`schema.json`](/spec/1.0/schema.json), rendered readably
as the [Schema Reference](/spec/1.0/schema).

For implementation guides, concepts and examples, see the
[documentation](/introduction).

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
[BCP 14](https://datatracker.ietf.org/doc/html/bcp14)
\[[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)]
\[[RFC8174](https://datatracker.ietf.org/doc/html/rfc8174)] when, and only
when, they appear in all capitals, as shown here.

## What this document is

A JSON Schema says what an event looks like. It cannot say what order events
may arrive in, what an implementation does with something it does not
recognise, or when a warning has to be emitted. Those rules are the protocol,
and this document states them.

The division of authority is deliberate and absolute:

* **The [schema](/spec/1.0/schema) is authoritative for structure.**
  Which fields exist, which are required, what type each carries, which values
  a discriminator may take. Where this document mentions a field, it does so
  to give a rule meaning — never to restate the field's shape. If the two
  disagree about structure, the schema wins and this document has a bug.
* **This document is authoritative for behaviour.** Ordering, lifecycle,
  attribution, error handling, compatibility. The schema cannot express any of
  it. If an implementation disagrees with a rule here, the implementation has
  a bug.

## Roles

Every rule names who it binds. Two roles carry obligations:

* A **producer** is whatever emits the event stream — an agent, a proxy, a
  bridge, a test double.
* A **consumer** is whatever reads it — a client SDK, a UI, a recorder,
  another proxy.

A participant that does both is bound by both sets of rules, in each direction
separately.

## Conformance

An implementation conforms when it satisfies every MUST and MUST NOT that
applies to the roles it plays. SHOULD-level rules describe what a good
implementation does; departing from one is a decision that needs a reason, not
a violation.

Conformance is judged per stream. A producer that emits one malformed run does
not conform, whatever it does on other runs.

## Overview

The protocol decomposes into a base every implementation speaks and features a
producer emits when it has something to say with them:

* **[The event model](/spec/1.0/basic)** — the envelope, the general fields,
  the identifiers.
* **[Run input](/spec/1.0/basic/run-input)** — the one message that travels
  from application to agent.
* **[Metadata](/spec/1.0/basic/metadata)** — the open channel on everything,
  and how it merges.
* **[Event patterns](/spec/1.0/basic/patterns)** — streaming,
  snapshot–delta, interrupt–resume.
* **[Transports](/spec/1.0/basic/transports)** — HTTP + SSE, HTTP +
  Protobuf, and the contract custom bindings must meet.
* **[Processing model](/spec/1.0/basic/processing)** — middleware before
  enforcement; unrecognised material survives, malformed known values are
  fatal.
* **[Versioning and compatibility](/spec/1.0/basic/versioning)** — talking
  to older and newer peers, and what losing content obliges.
* **[Event streams](/spec/1.0/events)** — the eight event families.

## Security and Trust & Safety

AG-UI turns model output into things applications do: tool calls become
actions, state events become writes, streamed content becomes what the user
reads. With that come obligations the protocol cannot enforce at the wire
level but that implementors must address.

### Key principles

1. **User consent and control.** The application decides what runs. It SHOULD
   obtain explicit user consent before executing side-effectful
   [tool calls](/spec/1.0/events/tool-calls), and MUST NOT represent an
   action as user-approved when it was not.
2. **Model output is untrusted input.** Tool arguments, tool results,
   [state](/spec/1.0/events/state) content and
   [passthrough](/spec/1.0/events/passthrough) payloads cross a trust
   boundary. Applications MUST validate what they act on and MUST NOT render
   streamed content as executable markup.
3. **Data flows both ways.** State and messages round-trip through the
   consumer and back on every run. Producers SHOULD NOT put secrets in them;
   consumers SHOULD treat reasoning and encrypted artefacts with the same
   confidentiality as the conversation.

### Implementation guidelines

The protocol itself cannot enforce these principles. Implementors SHOULD build
consent flows for consequential actions, validate schema and semantics at
every trust boundary, isolate rendering from execution, and log enough to
audit what an agent did on a user's behalf.

## Scope

This document specifies the protocol: the event stream, the run input, and the
obligations of the parties exchanging them. It does not specify what any
particular integration does with an event after receiving it, how an agent
framework should be structured, or how a UI should render anything.

AG-UI is maintained with three first-party SDKs — TypeScript, Python and
.NET — and every rule here applies to all of them equally. Other language
bindings are community-maintained; they are bound by this document when they
claim conformance, but nothing here is derived from them.

## Learn More

> [card] [Architecture](/spec/1.0/architecture)
>
> The components, the run, and the design principles.

> [card] [Base Protocol](/spec/1.0/basic)
>
> The event model, run input, patterns, transports, processing, versioning.

> [card] [Event Streams](/spec/1.0/events)
>
> The eight event families and their rules.

> [card] [Key Changes](/spec/1.0/changelog)
>
> What 1.0 changes against the 0.x line.


# Schema Reference
Source: https://docs.ag-ui.com/spec/1.0/schema

Every definition of the 1.0 schema, one anchor each — generated, do not edit

This page is generated from the machine-readable schema at
[`/spec/1.0/schema.json`](/spec/1.0/schema.json) — the source of truth for
structure — so the prose specification can link a definition instead of
restating it. Do not edit it by hand: change the schema and regenerate.

Each definition's anchor is its name, lowercased.

## Events

The event union, its discriminator, and every event. The mixins their fields come from are listed under [Mixins](#mixins).

### `EventType`

The discriminator carried by every event.

**Values:**

`TEXT_MESSAGE_START` · `TEXT_MESSAGE_CONTENT` · `TEXT_MESSAGE_END` · `TEXT_MESSAGE_CHUNK` · `TOOL_CALL_START` · `TOOL_CALL_ARGS` · `TOOL_CALL_END` · `TOOL_CALL_CHUNK` · `TOOL_CALL_RESULT` · `STATE_SNAPSHOT` · `STATE_DELTA` · `MESSAGES_SNAPSHOT` · `ACTIVITY_SNAPSHOT` · `ACTIVITY_DELTA` · `RAW` · `CUSTOM` · `RUN_STARTED` · `RUN_FINISHED` · `RUN_ERROR` · `STEP_STARTED` · `STEP_FINISHED` · `REASONING_START` · `REASONING_MESSAGE_START` · `REASONING_MESSAGE_CONTENT` · `REASONING_MESSAGE_END` · `REASONING_MESSAGE_CHUNK` · `REASONING_END` · `REASONING_ENCRYPTED_VALUE` · `SUBAGENT_STARTED` · `SUBAGENT_FINISHED` · `SUBAGENT_ERROR`

### `TextMessageStartEvent`

Opens a streamed text message. The content arrives as TEXT\_MESSAGE\_CONTENT events and the message closes with TEXT\_MESSAGE\_END.

**Fields:**

* `type` — `"TEXT_MESSAGE_START"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, **required**. Identifies the message this stream builds, and ties the later content and end events to it.
* `role` — [`TextMessageRole`](#textmessagerole), optional. Who the message is from. An absent role means assistant; that meaning is normative and stated in the prose, because a validator treats a default as documentation rather than as behaviour. Default: `"assistant"`.
* `name` — `string`, optional. An optional display name for the author, for providers that distinguish several participants in one role.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `TextMessageContentEvent`

Appends a fragment to a streamed text message.

**Fields:**

* `type` — `"TEXT_MESSAGE_CONTENT"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, **required**. The message this fragment belongs to.
* `delta` — `string`, **required**. The fragment to append. May be the empty string: providers emit empty deltas as keep-alives and while a tool call is being decided, and rejecting them would kill runs that are working correctly.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `TextMessageEndEvent`

Closes a streamed text message.

**Fields:**

* `type` — `"TEXT_MESSAGE_END"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, **required**. The message being closed.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `TextMessageChunkEvent`

A shorthand that stands in for a start, content and end sequence, for producers that cannot know in advance where a message begins. Every field is optional because a continuation chunk omits what has not changed; which message a field-less chunk continues is a sequence question the prose specification answers.

**Fields:**

* `type` — `"TEXT_MESSAGE_CHUNK"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, optional. The message this chunk belongs to. Absent continues the message already open.
* `role` — [`TextMessageRole`](#textmessagerole), optional. Who the message is from, on the chunk that opens it.
* `delta` — `string`, optional. The fragment to append. May be the empty string.
* `name` — `string`, optional. An optional display name for the author.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ToolCallStartEvent`

Opens a tool call. The arguments arrive as TOOL\_CALL\_ARGS events and the call closes with TOOL\_CALL\_END.

**Fields:**

* `type` — `"TOOL_CALL_START"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `toolCallId` — `string`, **required**. Identifies the call, and ties the later args, end and result events to it.
* `toolCallName` — `string`, **required**. Which tool is being called.
* `parentMessageId` — `string`, optional. The assistant message that holds this call. Absent means the producer did not attribute it to one.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ToolCallArgsEvent`

Appends a fragment of a tool call's arguments.

**Fields:**

* `type` — `"TOOL_CALL_ARGS"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `toolCallId` — `string`, **required**. The call these arguments belong to.
* `delta` — `string`, **required**. A fragment of the arguments, which concatenate into the call's argument text — conventionally a JSON document, though the protocol does not validate it (see FunctionCall.arguments). Deliberately a string rather than parsed JSON: a fragment is not itself a document. May be the empty string.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ToolCallEndEvent`

Closes a tool call, meaning its arguments are complete.

**Fields:**

* `type` — `"TOOL_CALL_END"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `toolCallId` — `string`, **required**. The call being closed.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ToolCallChunkEvent`

A shorthand that stands in for a tool call's start, args and end sequence. Every field is optional for the same reason as TEXT\_MESSAGE\_CHUNK.

**Fields:**

* `type` — `"TOOL_CALL_CHUNK"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `toolCallId` — `string`, optional. The call this chunk belongs to. Absent continues the call already open.
* `toolCallName` — `string`, optional. Which tool is being called, on the chunk that opens it.
* `parentMessageId` — `string`, optional. The assistant message that holds this call.
* `delta` — `string`, optional. A fragment of the arguments. May be the empty string.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ToolCallResultEvent`

Carries what a tool returned. Mints a tool message rather than appending to an existing one, which is why it has its own messageId.

**Fields:**

* `type` — `"TOOL_CALL_RESULT"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, **required**. The tool message this result becomes.
* `toolCallId` — `string`, **required**. The call being answered.
* `content` — `string` | array of [`ContentPart`](#contentpart), **required**. What the tool returned: either plain text, or an ordered list of parts, exactly as on the tool message this event mints. A tool returning structured data serialises it into text; media travel as parts of their own.
* `role` — `"tool"`, optional. Present only for symmetry with the message it mints; the value is fixed, so a producer may leave it out.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `StateSnapshotEvent`

Replaces the agent state wholesale. Sent when a delta cannot express the change, or to resynchronise a consumer.

**Fields:**

* `type` — `"STATE_SNAPSHOT"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `snapshot` — [`State`](#state), **required**. The complete new state.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `StateDeltaEvent`

Changes the agent state incrementally.

**Fields:**

* `type` — `"STATE_DELTA"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `delta` — [`JsonPatch`](#jsonpatch), **required**. The change, as an RFC 6902 patch against the current state. Structural validity here does not mean the patch applies: a well-formed operation may point at a path that does not exist, which RFC 6902 leaves to the applier.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `MessagesSnapshotEvent`

The complete set of messages the producer owns, in order. Conversation-wide rather than a plain overwrite: a consumer may keep messages of its own that no producer tracks, so exactly how a snapshot reconciles with those is behavioural and belongs in the prose. Being conversation-wide it cannot belong to a single subagent, so it carries no attribution; it does establish which subagent owns each message it contains, through the messages themselves.

**Fields:**

* `type` — `"MESSAGES_SNAPSHOT"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `messages` — array of [`Message`](#message), **required**. The messages the producer is declaring, in order.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent); the composed fields are listed above.

### `ActivitySnapshotEvent`

Reports structured progress that is not conversation content, such as a step a UI renders as its own widget.

**Fields:**

* `type` — `"ACTIVITY_SNAPSHOT"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, **required**. The activity message this describes.
* `activityType` — `string`, **required**. What kind of activity this is. An open string: the set is the producer's, not the protocol's.
* `content` — `object`, open by key, **required**. The activity's payload, open by key.
* `replace` — `boolean`, optional. Whether this snapshot overwrites the activity's existing content. Absent means it does, and that meaning is normative; only an explicit false asks a consumer to leave what is already there. It does not ask for a merge — ACTIVITY\_DELTA is how content is changed incrementally. What a consumer does with a non-overwriting snapshot is behavioural and belongs in the prose. Default: `true`.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ActivityDeltaEvent`

Changes an activity message's content incrementally.

**Fields:**

* `type` — `"ACTIVITY_DELTA"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, **required**. The activity message being changed.
* `activityType` — `string`, **required**. What kind of activity this is.
* `patch` — [`JsonPatch`](#jsonpatch), **required**. The change, as an RFC 6902 patch against the activity's content.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `RawEvent`

Passes a provider-native event through untranslated, for consumers that need detail the protocol does not model.

**Fields:**

* `type` — `"RAW"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `event` — any JSON value, **required**. The provider's own event. Any JSON value, and required: an event whose only purpose is to carry this would say nothing without it.
* `source` — `string`, optional. Which provider or framework the event came from.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `CustomEvent`

The protocol's extension point for an application's own events. Anything a consumer does with one is outside the protocol.

**Fields:**

* `type` — `"CUSTOM"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `name` — `string`, **required**. What this custom event is. Required: without it a consumer cannot route the value.
* `value` — any JSON value, **required**. The payload. Any JSON value, and required.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `RunStartedEvent`

Opens a run. Run-scoped, so it carries no subagent attribution.

**Fields:**

* `type` — `"RUN_STARTED"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `threadId` — `string`, **required**. The conversation this run belongs to.
* `runId` — `string`, **required**. Identifies this run.
* `protocolVersion` — `string`, optional. The protocol version this producer speaks, such as "1.0" — the producer's own version, not an echo of the input's, which is what makes the pair a negotiation: each side declares itself and the consumer sees a downgrade the moment it happens. Absent means a producer from before the protocol carried a version.
* `parentRunId` — `string`, optional. The run that spawned this one, when an agent invokes another agent as a separate run rather than as a subagent within one.
* `input` — [`RunAgentInput`](#runagentinput), optional. The request this run was started from, echoed back so a consumer that did not make the request can still see what the agent was asked.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent); the composed fields are listed above.

### `RunFinishedEvent`

Closes a run that did not fail. Run-scoped, so it carries no subagent attribution.

**Fields:**

* `type` — `"RUN_FINISHED"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `threadId` — `string`, **required**. The conversation this run belongs to.
* `runId` — `string`, **required**. The run being closed.
* `result` — any JSON value except `null`, optional. The run's return value, if it has one. Any JSON value.
* `outcome` — [`RunFinishedOutcome`](#runfinishedoutcome), optional. Why the run ended. Absent means success, so every producer written before outcomes existed is already conformant.
* `usage` — array of [`TokenUsage`](#tokenusage), optional. Token usage for the run, one entry per provider and model, so a run that invoked several models keeps them separate. A consumer that only wants totals sums across the entries. The run is the accounting boundary: usage covers every model call made within the run, calls made by its subagents included; an agent invoked as a separate run under parentRunId reports its own usage on its own terminal event; and a run that resumes an interrupted one reports only the calls it made itself, not the interrupted run's.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent); the composed fields are listed above.

### `RunErrorEvent`

Ends a run that failed. Run-scoped, so it carries no subagent attribution; a subagent that fails without ending the run reports SUBAGENT\_ERROR instead.

**Fields:**

* `type` — `"RUN_ERROR"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `message` — `string`, **required**. What went wrong, for a person to read.
* `code` — `string`, optional. A machine-readable error code. An open string: the protocol defines no vocabulary.
* `usage` — array of [`TokenUsage`](#tokenusage), optional. Token usage accrued before the failure, for a run that completed one or more model calls before dying. Scoped as on RUN\_FINISHED: the run's own calls, subagents included.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent); the composed fields are listed above.

### `StepStartedEvent`

Opens a named step within a run, for producers whose frameworks have a step concept worth surfacing.

**Fields:**

* `type` — `"STEP_STARTED"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `stepName` — `string`, **required**. The step's name. Identifies it: the matching STEP\_FINISHED carries the same name.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `StepFinishedEvent`

Closes a named step.

**Fields:**

* `type` — `"STEP_FINISHED"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `stepName` — `string`, **required**. The step being closed.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ReasoningStartEvent`

Opens a span of reasoning. A span may contain several reasoning messages.

**Fields:**

* `type` — `"REASONING_START"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, **required**. The span being opened.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ReasoningMessageStartEvent`

Opens a streamed reasoning message.

**Fields:**

* `type` — `"REASONING_MESSAGE_START"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, **required**. The reasoning message this stream builds.
* `role` — `"reasoning"`, **required**. Fixed, and required rather than defaulted. The requirement is inherited from the SDKs rather than chosen.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ReasoningMessageContentEvent`

Appends a fragment to a streamed reasoning message.

**Fields:**

* `type` — `"REASONING_MESSAGE_CONTENT"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, **required**. The reasoning message this fragment belongs to.
* `delta` — `string`, **required**. The fragment to append. May be the empty string.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ReasoningMessageEndEvent`

Closes a streamed reasoning message.

**Fields:**

* `type` — `"REASONING_MESSAGE_END"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, **required**. The reasoning message being closed.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ReasoningMessageChunkEvent`

A shorthand that stands in for a reasoning message's start, content and end sequence.

**Fields:**

* `type` — `"REASONING_MESSAGE_CHUNK"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, optional. The reasoning message this chunk belongs to. Absent continues the one already open.
* `delta` — `string`, optional. The fragment to append. May be the empty string.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ReasoningEndEvent`

Closes a span of reasoning.

**Fields:**

* `type` — `"REASONING_END"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `messageId` — `string`, **required**. The span being closed.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `ReasoningEncryptedValueEvent`

Carries a provider's opaque, encrypted reasoning artefact, which a consumer stores and returns on a later turn without being able to read it.

**Fields:**

* `type` — `"REASONING_ENCRYPTED_VALUE"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `subtype` — [`ReasoningEncryptedValueSubtype`](#reasoningencryptedvaluesubtype), **required**. What kind of thing entityId names, which decides where the value is stored.
* `entityId` — `string`, **required**. What the value belongs to: a message id or a tool call id, according to subtype.
* `encryptedValue` — `string`, **required**. The provider's opaque artefact.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent), [`Attributable`](#attributable); the composed fields are listed above.

### `SubagentStartedEvent`

Announces that a subagent invocation has begun. Everything the subagent produces afterwards is attributed by carrying its subagentRunId, so a consumer can group the work without replaying the stream. Composed from BaseEvent alone rather than Attributable, because here subagentRunId identifies the subagent rather than attributing the event to one; attribution to an enclosing subagent is parentSubagentRunId.

**Fields:**

* `type` — `"SUBAGENT_STARTED"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), **required**. The invocation being announced.
* `name` — `string`, **required**. The subagent's name, which is reusable across invocations, unlike subagentRunId.
* `description` — `string`, optional. What this subagent is for, for a consumer to display.
* `parentSubagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation that spawned this one, for nested delegation. Absent means the parent agent spawned it directly.
* `parentToolCallId` — `string`, optional. The tool call that spawned this subagent, for the pattern where agents are exposed to a model as tools. Lets a consumer tie the subagent to the call without reading rawEvent.
* `parentMessageId` — `string`, optional. The message that held the spawning tool call.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent); the composed fields are listed above.

### `SubagentFinishedEvent`

Ends a subagent invocation's segment of this run, either because the work completed or because it is suspended awaiting outside input.

**Fields:**

* `type` — `"SUBAGENT_FINISHED"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), **required**. The invocation being closed.
* `result` — any JSON value except `null`, optional. The subagent's return value, if it has one. Any JSON value, mirroring RUN\_FINISHED.result.
* `outcome` — [`SubagentFinishedOutcome`](#subagentfinishedoutcome), optional. Why the segment ended. Absent means success. A suspended subagent is neither a success nor a failure, which is why saying so needs its own value rather than being inferred from a later interrupt.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent); the composed fields are listed above.

### `SubagentErrorEvent`

Reports that a subagent invocation failed. The run may continue: a parent agent is free to handle a failed subagent, which is why this is not RUN\_ERROR.

**Fields:**

* `type` — `"SUBAGENT_ERROR"` ([`EventType`](#eventtype)), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.
* `subagentRunId` — [`SubagentRunId`](#subagentrunid), **required**. The invocation that failed.
* `message` — `string`, **required**. What went wrong, for a person to read.
* `code` — `string`, optional. A machine-readable error code. An open string.

Closed object: the schema rejects members not listed here.

Composes [`BaseEvent`](#baseevent); the composed fields are listed above.

### `Event`

Any AG-UI event. Every member is normative: there is no optional tier and no event a consumer may decline to implement. Discriminated by the type property.

**Members:**

* [`TextMessageStartEvent`](#textmessagestartevent)
* [`TextMessageContentEvent`](#textmessagecontentevent)
* [`TextMessageEndEvent`](#textmessageendevent)
* [`TextMessageChunkEvent`](#textmessagechunkevent)
* [`ToolCallStartEvent`](#toolcallstartevent)
* [`ToolCallArgsEvent`](#toolcallargsevent)
* [`ToolCallEndEvent`](#toolcallendevent)
* [`ToolCallChunkEvent`](#toolcallchunkevent)
* [`ToolCallResultEvent`](#toolcallresultevent)
* [`StateSnapshotEvent`](#statesnapshotevent)
* [`StateDeltaEvent`](#statedeltaevent)
* [`MessagesSnapshotEvent`](#messagessnapshotevent)
* [`ActivitySnapshotEvent`](#activitysnapshotevent)
* [`ActivityDeltaEvent`](#activitydeltaevent)
* [`RawEvent`](#rawevent)
* [`CustomEvent`](#customevent)
* [`RunStartedEvent`](#runstartedevent)
* [`RunFinishedEvent`](#runfinishedevent)
* [`RunErrorEvent`](#runerrorevent)
* [`StepStartedEvent`](#stepstartedevent)
* [`StepFinishedEvent`](#stepfinishedevent)
* [`ReasoningStartEvent`](#reasoningstartevent)
* [`ReasoningMessageStartEvent`](#reasoningmessagestartevent)
* [`ReasoningMessageContentEvent`](#reasoningmessagecontentevent)
* [`ReasoningMessageEndEvent`](#reasoningmessageendevent)
* [`ReasoningMessageChunkEvent`](#reasoningmessagechunkevent)
* [`ReasoningEndEvent`](#reasoningendevent)
* [`ReasoningEncryptedValueEvent`](#reasoningencryptedvalueevent)
* [`SubagentStartedEvent`](#subagentstartedevent)
* [`SubagentFinishedEvent`](#subagentfinishedevent)
* [`SubagentErrorEvent`](#subagenterrorevent)

Discriminated by `type`.

## Messages

The message union and the message types conversation history holds.

### `TextMessageRole`

The roles a streamed text message may take. Excludes tool, which is carried by TOOL\_CALL\_RESULT rather than streamed as text.

**Values:**

`developer` · `system` · `assistant` · `user`

### `DeveloperMessage`

Instructions from the application developer.

**Fields:**

* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `id` — `string`, **required**. Identifies the message within the conversation.
* `role` — `"developer"`, **required**. Who the message is from. Each message definition narrows this to a single value.
* `name` — `string`, optional. An optional display name for the author.
* `encryptedValue` — `string`, optional. A provider's opaque artefact belonging to this message, stored by a consumer and returned on a later turn.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this message.
* `content` — `string`, **required**. The instructions. Required: a developer message with nothing in it says nothing.

Closed object: the schema rejects members not listed here.

Composes [`BaseMessage`](#basemessage), [`Attributable`](#attributable); the composed fields are listed above.

### `SystemMessage`

Instructions from the system.

**Fields:**

* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `id` — `string`, **required**. Identifies the message within the conversation.
* `role` — `"system"`, **required**. Who the message is from. Each message definition narrows this to a single value.
* `name` — `string`, optional. An optional display name for the author.
* `encryptedValue` — `string`, optional. A provider's opaque artefact belonging to this message, stored by a consumer and returned on a later turn.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this message.
* `content` — `string`, **required**. The instructions. Required.

Closed object: the schema rejects members not listed here.

Composes [`BaseMessage`](#basemessage), [`Attributable`](#attributable); the composed fields are listed above.

### `AssistantMessage`

A message from the agent. Content is optional because a turn may consist only of tool calls.

**Fields:**

* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `id` — `string`, **required**. Identifies the message within the conversation.
* `role` — `"assistant"`, **required**. Who the message is from. Each message definition narrows this to a single value.
* `name` — `string`, optional. An optional display name for the author.
* `encryptedValue` — `string`, optional. A provider's opaque artefact belonging to this message, stored by a consumer and returned on a later turn.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this message.
* `content` — `string`, optional. What the agent said, if it said anything.
* `toolCalls` — array of [`ToolCall`](#toolcall), optional. The tool calls this turn made.

Closed object: the schema rejects members not listed here.

Composes [`BaseMessage`](#basemessage), [`Attributable`](#attributable); the composed fields are listed above.

### `UserMessage`

A message from the person using the application.

**Fields:**

* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `id` — `string`, **required**. Identifies the message within the conversation.
* `role` — `"user"`, **required**. Who the message is from. Each message definition narrows this to a single value.
* `name` — `string`, optional. An optional display name for the author.
* `encryptedValue` — `string`, optional. A provider's opaque artefact belonging to this message, stored by a consumer and returned on a later turn.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this message.
* `content` — `string` | array of [`ContentPart`](#contentpart), **required**. What the person sent: either plain text, or an ordered list of parts for a multimodal message.

Closed object: the schema rejects members not listed here.

Composes [`BaseMessage`](#basemessage), [`Attributable`](#attributable); the composed fields are listed above.

### `ToolMessage`

What a tool returned, as a message in the conversation. Stands alone rather than composing BaseMessage, because it carries no name.

**Fields:**

* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `id` — `string`, **required**. Identifies the message.
* `role` — `"tool"`, **required**. Fixed. Declared here rather than inherited, because this message does not compose BaseMessage.
* `content` — `string` | array of [`ContentPart`](#contentpart), **required**. What the tool returned: either plain text, or an ordered list of parts. A tool returning structured data serialises it into text; media travel as parts of their own.
* `toolCallId` — `string`, **required**. The call this answers.
* `error` — `string`, optional. Why the tool failed, when it did. Present alongside content rather than instead of it, so a partial result survives a failure.
* `encryptedValue` — `string`, optional. A provider's opaque artefact belonging to this message.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this message.

Closed object: the schema rejects members not listed here.

Composes [`Attributable`](#attributable); the composed fields are listed above.

### `ActivityMessage`

Structured progress that is not conversation content, materialised as a message so it keeps its place in the sequence. Stands alone rather than composing BaseMessage, because its content is an object rather than a string.

**Fields:**

* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `id` — `string`, **required**. Identifies the message.
* `role` — `"activity"`, **required**. Fixed. Declared here rather than inherited, because this message does not compose BaseMessage.
* `activityType` — `string`, **required**. What kind of activity this is. An open string: the set is the producer's.
* `content` — `object`, open by key, **required**. The activity's payload, open by key.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this message.

Closed object: the schema rejects members not listed here.

Composes [`Attributable`](#attributable); the composed fields are listed above.

### `ReasoningMessage`

A span of the agent's reasoning, materialised as a message. Stands alone rather than composing BaseMessage, because it carries no name.

**Fields:**

* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `id` — `string`, **required**. Identifies the message.
* `role` — `"reasoning"`, **required**. Fixed. Declared here rather than inherited, because this message does not compose BaseMessage.
* `content` — `string`, **required**. The reasoning text.
* `encryptedValue` — `string`, optional. A provider's opaque reasoning artefact belonging to this message.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this message.

Closed object: the schema rejects members not listed here.

Composes [`Attributable`](#attributable); the composed fields are listed above.

### `Message`

Any message in a conversation. Discriminated by role.

**Members:**

* [`DeveloperMessage`](#developermessage)
* [`SystemMessage`](#systemmessage)
* [`AssistantMessage`](#assistantmessage)
* [`UserMessage`](#usermessage)
* [`ToolMessage`](#toolmessage)
* [`ActivityMessage`](#activitymessage)
* [`ReasoningMessage`](#reasoningmessage)

Discriminated by `role`.

### `Role`

Every role a materialised message may have.

**Values:**

`developer` · `system` · `assistant` · `user` · `tool` · `activity` · `reasoning`

## Run Input

The request that starts a run, and the types only it carries. Behaviour: [Run Input](/spec/1.0/basic/run-input).

### `TextPart`

A text part.

**Fields:**

* `type` — `"text"`, **required**. Discriminator.
* `id` — `string`, optional. Identifies this part within its message. Optional, and nothing reads it yet: reserved so that a streamed part can be matched to its entry in history once assistant messages carry parts too.
* `text` — `string`, **required**. The text.
* `metadata` — any JSON value except `null`, optional. Extra information about this part. Unconstrained, as on the media parts. This is where a text search hit carries its source and title, rather than the protocol modelling a search-result part of its own.

Closed object: the schema rejects members not listed here.

### `DataSource`

Bytes carried inline.

**Fields:**

* `type` — `"data"`, **required**. Discriminator.
* `value` — `string`, **required**. The bytes, base64-encoded. contentEncoding is an annotation rather than a constraint in 2020-12, so a malformed string still validates here; rejecting one is the decoder's job. Encoding: `base64`.
* `mimeType` — `string`, **required**. What the bytes are. Required here, unlike on a URL source, because nothing else can tell a consumer how to read them.

Closed object: the schema rejects members not listed here.

### `UrlSource`

Bytes referenced by URL, fetched by whoever needs them.

**Fields:**

* `type` — `"url"`, **required**. Discriminator.
* `value` — `string`, **required**. The URL. Deliberately not constrained to a URI format, so a scheme a producer already uses is not rejected here.
* `mimeType` — `string`, optional. What the resource is, when the producer knows. Optional, because the response can say.

Closed object: the schema rejects members not listed here.

### `FileSource`

Bytes already at the provider, named by a handle the provider issued: an OpenAI or Anthropic file id, a Gemini file URI, a storage URL only that provider can read. No bytes travel and nothing is fetched. Only the provider that minted the handle can resolve it; a peer that cannot drops the part as it drops any part it cannot use.

**Fields:**

* `type` — `"file"`, **required**. Discriminator.
* `value` — `string`, **required**. The handle, exactly as the provider issued it. Opaque: a consumer MUST NOT fetch it, parse it or read a scheme out of it.
* `provider` — `string`, optional. Who issued the handle, when the producer knows. Optional: an agent already knows which provider it talks to. When present, SHOULD be the lowercase vendor id (openai, anthropic, google) that TokenUsage.provider uses, so a peer can tell before sending whether a handle is one it can use.
* `mimeType` — `string`, optional. What the file is, when the producer knows. Optional, because the provider that holds the bytes knows.

Closed object: the schema rejects members not listed here.

### `PartSource`

Where a media part's bytes come from: carried inline, referenced by URL, or already at the provider under a handle it issued.

**Members:**

* [`DataSource`](#datasource)
* [`UrlSource`](#urlsource)
* [`FileSource`](#filesource)

Discriminated by `type`.

### `ImagePart`

An image part.

**Fields:**

* `type` — `"image"`, **required**. Discriminator.
* `id` — `string`, optional. Identifies this part within its message. Optional, and nothing reads it yet: reserved as on the text part.
* `source` — [`PartSource`](#partsource), **required**. Where the image comes from.
* `metadata` — any JSON value except `null`, optional. Extra information about this part. Unconstrained rather than an object: inherited from the SDKs, which declare it unknown rather than a record; listed under known divergences in the README rather than resolved here.

Closed object: the schema rejects members not listed here.

### `AudioPart`

An audio part.

**Fields:**

* `type` — `"audio"`, **required**. Discriminator.
* `id` — `string`, optional. Identifies this part within its message. Optional, and nothing reads it yet: reserved as on the text part.
* `source` — [`PartSource`](#partsource), **required**. Where the audio comes from.
* `metadata` — any JSON value except `null`, optional. Extra information about this part. Unconstrained, as on the other media parts.

Closed object: the schema rejects members not listed here.

### `VideoPart`

A video part.

**Fields:**

* `type` — `"video"`, **required**. Discriminator.
* `id` — `string`, optional. Identifies this part within its message. Optional, and nothing reads it yet: reserved as on the text part.
* `source` — [`PartSource`](#partsource), **required**. Where the video comes from.
* `metadata` — any JSON value except `null`, optional. Extra information about this part. Unconstrained, as on the other media parts.

Closed object: the schema rejects members not listed here.

### `DocumentPart`

A document part.

**Fields:**

* `type` — `"document"`, **required**. Discriminator.
* `id` — `string`, optional. Identifies this part within its message. Optional, and nothing reads it yet: reserved as on the text part.
* `source` — [`PartSource`](#partsource), **required**. Where the document comes from.
* `metadata` — any JSON value except `null`, optional. Extra information about this part. Unconstrained, as on the other media parts.

Closed object: the schema rejects members not listed here.

### `ContentPart`

One part of a message body: what a person sends in a user message, or what a tool returns in a tool message. Discriminated by type. Named by what the part is rather than by direction, because the same part travels into the model inside a user message and back out of the stream inside a tool result.

**Members:**

* [`TextPart`](#textpart)
* [`ImagePart`](#imagepart)
* [`AudioPart`](#audiopart)
* [`VideoPart`](#videopart)
* [`DocumentPart`](#documentpart)

Discriminated by `type`.

### `Tool`

A tool the agent may call.

**Fields:**

* `name` — `string`, **required**. The tool's name, as the agent will call it.
* `description` — `string`, **required**. What the tool does, for the agent to decide when to use it.
* `parameters` — any JSON value except `null`, optional. A JSON Schema describing the tool's arguments. Carried opaquely: the protocol does not constrain or validate it. Optional, because all three SDKs already treat it that way and a tool that takes no arguments has nothing to declare; an absent schema and an empty one mean the same thing to an agent.
* `metadata` — [`Metadata`](#metadata), optional. Extra information about the tool, for consumers that attach their own rendering or routing information to it.

Closed object: the schema rejects members not listed here.

### `Context`

A named piece of ambient information given to the agent for the run, distinct from the conversation.

**Fields:**

* `description` — `string`, **required**. What this context is, for the agent to interpret.
* `value` — `string`, **required**. The context itself.

Closed object: the schema rejects members not listed here.

### `ResumeEntry`

An answer to one interrupt, sent on the run that continues from it.

**Fields:**

* `interruptId` — `string`, **required**. The interrupt being answered.
* `status` — `"resolved"` | `"cancelled"`, **required**. Whether the interrupt was answered or abandoned.
* `payload` — any JSON value except `null`, optional. The answer the agent asked for and will act on. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Envelope information about the response, such as signatures or routing keys, as opposed to payload, which is the answer itself.

Closed object: the schema rejects members not listed here.

### `RunAgentInput`

A request to run an agent. Also echoed back as RUN\_STARTED.input. Only threadId, runId and messages are required: those are the three the SDKs already agree on, and for tools and context an absent key and an empty array mean the same thing, so requiring them would catch nothing a producer could get wrong.

**Fields:**

* `threadId` — `string`, **required**. The conversation this run belongs to.
* `runId` — `string`, **required**. Identifies this run.
* `protocolVersion` — `string`, optional. The protocol version this consumer speaks, such as "1.0". Absent means the input was produced before the protocol carried a version — the versioning rules in the prose govern what each side does with that. Sent in-band rather than by the transport, so a recorded exchange stays self-describing.
* `parentRunId` — `string`, optional. The run that spawned this one.
* `state` — [`State`](#state) except `null`, optional. The state the run starts from.
* `messages` — array of [`Message`](#message), **required**. The conversation so far, in order.
* `tools` — array of [`Tool`](#tool), optional. The tools the agent may call. Absent means none.
* `context` — array of [`Context`](#context), optional. Ambient information for the run. Absent means none.
* `forwardedProps` — any JSON value except `null`, optional. Application-specific values passed through to the agent untouched. Any JSON value.
* `resume` — array of [`ResumeEntry`](#resumeentry), optional. Answers to the interrupts that ended a previous run, when this run continues from one.

Closed object: the schema rejects members not listed here.

## Outcomes and Interrupts

How runs and subagents report ending, and what an interrupted run is waiting for. Behaviour: [Interrupts and Resume](/spec/1.0/basic/patterns/interrupt-resume).

### `RunFinishedSuccessOutcome`

The run completed. Equivalent to an absent outcome. Closed like every other object, which is also what keeps it from carrying the suspended sibling's interrupts — a success with an interrupt still pending would be a contradiction, not an extension. A completed run may still have left frontend tool calls for the application to answer; pendingToolCallIds names them.

**Fields:**

* `type` — `"success"`, **required**. Discriminator.
* `pendingToolCallIds` — array of `string`, optional. The tool calls this run started and left unanswered — no TOOL\_CALL\_RESULT in the run — for the application to answer in the next input's messages, in the order they were made. Absent or empty means the producer named none, and a consumer derives the list from the stream; otherwise it is the list, and it agrees with the stream. On the success outcome rather than the event because a run that stopped on a frontend tool call is a completed run: whether the application continues the thread is its own decision, so the producer reports what it knows and no more. Each entry: A tool call id, as carried by TOOL\_CALL\_START.

Closed object: the schema rejects members not listed here.

### `Interrupt`

Something a run needs from outside before it can continue, such as an approval or a missing value.

**Fields:**

* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `id` — `string`, **required**. Identifies the interrupt. A resume entry answers it by this id.
* `reason` — `string`, **required**. Why the run stopped. An open string rather than an enumeration: the protocol does not attempt to classify every reason an agent might need input.
* `message` — `string`, optional. A human-readable prompt for whoever answers.
* `toolCallId` — `string`, optional. The tool call this interrupt concerns, when it is a tool approval.
* `responseSchema` — `object`, open by key, optional. A JSON Schema describing the answer this interrupt expects, so a consumer can build a form for it. Carried opaquely: the protocol does not constrain or validate it. Restricted to an object because TypeScript and Python both declare it that way; .NET holds it as any JSON, and the ticket that commissioned this schema lists it among the arbitrary-JSON fields. Following the two that constrain it keeps the schema from accepting documents the reference client rejects, at the cost of rejecting the boolean schemas JSON Schema also permits — a bare true for "any answer". Recorded as a known divergence rather than settled.
* `expiresAt` — `string`, optional. When the interrupt stops being answerable. Deliberately unconstrained rather than a date-time format, because producers already disagree about the representation and tightening it here would reject streams that work today. The documented convention is ISO 8601, and a consumer comparing this value will parse it as a date, so a value that is not one leaves the interrupt looking permanently unexpired.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this interrupt.

Closed object: the schema rejects members not listed here.

Composes [`Attributable`](#attributable); the composed fields are listed above.

### `RunFinishedInterruptOutcome`

The run is paused, waiting for something outside it. Resuming means starting a new run whose resume entries answer these interrupts.

**Fields:**

* `type` — `"interrupt"`, **required**. Discriminator.
* `interrupts` — array of [`Interrupt`](#interrupt) (min 1), **required**. What the run is waiting for. At least one: an interrupt outcome with nothing to answer would leave a consumer with nothing to do.

Closed object: the schema rejects members not listed here.

### `RunFinishedCancelledOutcome`

The run was stopped before it completed, by whoever was running it, and did not fail. Neither success nor interrupt: nothing was produced as a result, and nothing is waited for, so the next run on the thread is an ordinary new run rather than a resume. Closed like its siblings: a cancelled run has no interrupts to carry. Named in the schema before 1.0 because an outcome a consumer does not recognise is stripped and read as success — a cancellation added later would reach every 1.0 consumer as a completed run.

**Fields:**

* `type` — `"cancelled"`, **required**. Discriminator.

Closed object: the schema rejects members not listed here.

### `RunFinishedOutcome`

Why a run ended.

**Members:**

* [`RunFinishedSuccessOutcome`](#runfinishedsuccessoutcome)
* [`RunFinishedInterruptOutcome`](#runfinishedinterruptoutcome)
* [`RunFinishedCancelledOutcome`](#runfinishedcancelledoutcome)

Discriminated by `type`.

### `SubagentFinishedSuccessOutcome`

The subagent completed its work. Equivalent to an absent outcome.

**Fields:**

* `type` — `"success"`, **required**. Discriminator.

Closed object: the schema rejects members not listed here.

### `SubagentFinishedSuspendedOutcome`

The subagent is paused awaiting outside input. Terminal for this stream, not for the subagent: a later run may continue the same invocation once the interrupts are answered.

**Fields:**

* `type` — `"suspended"`, **required**. Discriminator.
* `interruptIds` — array of `string`, optional. The run-level interrupts this subagent raised itself. May be empty or absent: a subagent suspended because a descendant interrupted owns no interrupt of its own. Each entry: An Interrupt.id.

Closed object: the schema rejects members not listed here.

### `SubagentFinishedOutcome`

Why a subagent's segment of a run ended. Mirrors RunFinishedOutcome one level down.

**Members:**

* [`SubagentFinishedSuccessOutcome`](#subagentfinishedsuccessoutcome)
* [`SubagentFinishedSuspendedOutcome`](#subagentfinishedsuspendedoutcome)

Discriminated by `type`.

## Common Types

Everything the sections above share.

### `Metadata`

Extra information attached to an event, a message, a tool call, a tool, an interrupt or a resume entry. Open by key: any JSON value is allowed under a key, including null, because a null there is meaningful data. The object itself may be absent but is never null when present. The key ag-ui is reserved for the protocol's own use; reservation is by convention, since validating the shape of a key's value would contradict being open by key.

**Type:** `object`, open by key

### `SubagentRunId`

An opaque handle for one subagent invocation, not a reusable name for a subagent definition: two invocations of the same subagent carry two different values. Named to mirror runId one level down, the way the subagent's name mirrors agentId.

**Type:** `string`

### `State`

Agent state. Any JSON value: the protocol carries state without interpreting it, so an object, an array, a string and a number are all valid.

**Type:** any JSON value

### `JsonPointer`

A JSON Pointer as defined by RFC 6901. Either the empty string, meaning the whole document, or a sequence of slash-prefixed reference tokens in which a tilde is escaped as \~0 and a slash as \~1. A value with no leading slash, or a tilde followed by anything other than 0 or 1, is not a JSON Pointer.

**Type:** `string` matching `^(/([^/~]|~[01])*)*$`

### `AddOperation`

Inserts value at path. RFC 6902 section 4.1.

**Fields:**

* `op` — `"add"`, **required**. Discriminator for the add operation.
* `path` — [`JsonPointer`](#jsonpointer), **required**. Where to insert the value.
* `value` — any JSON value, **required**. The value to insert. Any JSON value, including null, which is a legitimate thing to add.

Open object: members beyond these are protocol-legal and are never stripped.

### `RemoveOperation`

Removes the value at path. RFC 6902 section 4.2.

**Fields:**

* `op` — `"remove"`, **required**. Discriminator for the remove operation.
* `path` — [`JsonPointer`](#jsonpointer), **required**. What to remove.

Open object: members beyond these are protocol-legal and are never stripped.

### `ReplaceOperation`

Replaces the value at path. RFC 6902 section 4.3.

**Fields:**

* `op` — `"replace"`, **required**. Discriminator for the replace operation.
* `path` — [`JsonPointer`](#jsonpointer), **required**. What to replace.
* `value` — any JSON value, **required**. The replacement. Any JSON value, including null.

Open object: members beyond these are protocol-legal and are never stripped.

### `MoveOperation`

Moves the value at from to path. RFC 6902 section 4.4.

**Fields:**

* `op` — `"move"`, **required**. Discriminator for the move operation.
* `from` — [`JsonPointer`](#jsonpointer), **required**. Where the value is moved from.
* `path` — [`JsonPointer`](#jsonpointer), **required**. Where the value is moved to.

Open object: members beyond these are protocol-legal and are never stripped.

### `CopyOperation`

Copies the value at from to path. RFC 6902 section 4.5.

**Fields:**

* `op` — `"copy"`, **required**. Discriminator for the copy operation.
* `from` — [`JsonPointer`](#jsonpointer), **required**. Where the value is copied from.
* `path` — [`JsonPointer`](#jsonpointer), **required**. Where the value is copied to.

Open object: members beyond these are protocol-legal and are never stripped.

### `TestOperation`

Asserts that the value at path equals value. RFC 6902 section 4.6.

**Fields:**

* `op` — `"test"`, **required**. Discriminator for the test operation.
* `path` — [`JsonPointer`](#jsonpointer), **required**. What to compare.
* `value` — any JSON value, **required**. The value the target must equal. Any JSON value, including null.

Open object: members beyond these are protocol-legal and are never stripped.

### `JsonPatchOperation`

A single RFC 6902 operation. Exactly one of the operation shapes must match, discriminated by op. Unlike the protocol's own objects, the operations are open: RFC 6902 section 4 requires members an operation does not define to be ignored rather than rejected, so a remove carrying a leftover value is a valid patch. Two of the RFC's rules are relations between values rather than shapes, so no static schema can express them and neither is checked here: a move whose from is a proper prefix of its path (section 4.4), and any operation whose pointer does not resolve in the target document. Both are the applier's to reject.

**Members:**

* [`AddOperation`](#addoperation)
* [`RemoveOperation`](#removeoperation)
* [`ReplaceOperation`](#replaceoperation)
* [`MoveOperation`](#moveoperation)
* [`CopyOperation`](#copyoperation)
* [`TestOperation`](#testoperation)

Discriminated by `op`.

### `JsonPatch`

A JSON Patch document as defined by RFC 6902, referenced by STATE\_DELTA.delta and ACTIVITY\_DELTA.patch: an ordered sequence of operations applied to a target document. An empty array is a valid no-op patch. Whether the operations actually apply to the document they target is a runtime question RFC 6902 leaves to the applier; structural validity here says nothing about it.

**Type:** array of [`JsonPatchOperation`](#jsonpatchoperation)

### `FunctionCall`

The name and arguments of a tool call.

**Fields:**

* `name` — `string`, **required**. Which tool is being called.
* `arguments` — `string`, **required**. The arguments as a JSON string, not as parsed JSON. Kept as written because a model can emit arguments that are not valid JSON, and losing them at the protocol boundary would hide the fault from the consumer that has to handle it.

Closed object: the schema rejects members not listed here.

### `ToolCall`

A call an assistant message made. Carries no subagent attribution of its own and inherits its containing message's, since several calls can share one parent.

**Fields:**

* `id` — `string`, **required**. Identifies the call. The answering tool message carries this as its toolCallId.
* `type` — `"function"`, **required**. The only kind of call the protocol models.
* `function` — [`FunctionCall`](#functioncall), **required**. What is being called, and with what.
* `encryptedValue` — `string`, optional. A provider's opaque artefact belonging to this call.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this call. Carried here rather than folded into the containing message, because several calls can share one parent and merging them would make the result depend on their order.

Closed object: the schema rejects members not listed here.

### `TokenUsage`

Token counts for one provider and model, in the protocol's own accounting: every count is either a total or a named part of one, so entries from different providers add up without double-counting. inputTokens and outputTokens are the totals; reasoningTokens, cachedInputTokens and cacheWriteInputTokens are parts of them, never additions to them; totalTokens is the two totals summed. Every field is a label or a number — nothing content-bearing or identifying, no prompts, completions, messages, or thread, run and user identifiers.

**Fields:**

* `provider` — `string`, optional. Which provider served the request.
* `model` — `string`, optional. Which model served the request.
* `inputTokens` — `integer` (min 0, max 9007199254740991), optional. Every prompt token the call was charged for: tokens read from a provider cache, tokens written to one, and audio or other non-text input all count here. cachedInputTokens and cacheWriteInputTokens break this number down and are never added to it — a provider that reports its cache counts beside a smaller input count has them added in by the producer before the entry leaves. Bounded like timestamp and for the same reason: a count above the JSON safe-integer range does not survive a round trip, so a consumer would silently read a different number than the producer wrote.
* `outputTokens` — `integer` (min 0, max 9007199254740991), optional. Every generated token, reasoning included where the provider distinguishes it. reasoningTokens breaks this number down and is never added to it — a provider that reports reasoning tokens beside a smaller completion count has them added in by the producer.
* `totalTokens` — `integer` (min 0, max 9007199254740991), optional. inputTokens plus outputTokens, under the accounting above. A producer MAY compute it rather than copy a provider's total, and copies a provider's total only when that total counts the same way, so a consumer can read this field as the sum of the other two.
* `reasoningTokens` — `integer` (min 0, max 9007199254740991), optional. Output tokens spent on reasoning, where the provider distinguishes them. Part of outputTokens, not in addition to it.
* `cachedInputTokens` — `integer` (min 0, max 9007199254740991), optional. Input tokens read from a provider cache. Part of inputTokens, not in addition to it, and disjoint from cacheWriteInputTokens.
* `cacheWriteInputTokens` — `integer` (min 0, max 9007199254740991), optional. Input tokens written to a provider cache on this call, where the provider distinguishes them. Part of inputTokens, not in addition to it, and disjoint from cachedInputTokens. Its own field because providers price a cache write differently from a cache read, so a consumer computing cost cannot do without it.

Closed object: the schema rejects members not listed here.

### `ReasoningEncryptedValueSubtype`

Whether a REASONING\_ENCRYPTED\_VALUE belongs to a message or to a tool call.

**Values:**

`tool-call` · `message`

### `SubagentInfo`

Describes a subagent that can be invoked by a parent agent.

**Fields:**

* `name` — `string`, **required**. Unique name or identifier of the subagent.
* `description` — `string`, optional. What this subagent specializes in. Helps clients build agent selection UIs.

Closed object: the schema rejects members not listed here.

### `IdentityCapabilities`

Basic metadata about the agent. Useful for discovery UIs, agent marketplaces, and debugging. Set these when you want clients to display agent information or when multiple agents are available and users need to pick one.

**Fields:**

* `name` — `string`, optional. Human-readable name shown in UIs and agent selectors.
* `type` — `string`, optional. The framework or platform powering this agent (e.g., "langgraph", "mastra", "crewai").
* `description` — `string`, optional. What this agent does — helps users and routing logic decide when to use it.
* `version` — `string`, optional. Semantic version of the agent (e.g., "1.2.0"). Useful for compatibility checks.
* `provider` — `string`, optional. Organization or team that maintains this agent.
* `documentationUrl` — `string`, optional. URL to the agent's documentation or homepage.
* `metadata` — [`Metadata`](#metadata), optional. Arbitrary key-value pairs for integration-specific identity info.

Closed object: the schema rejects members not listed here.

### `TransportCapabilities`

Declares which transport mechanisms the agent supports. Clients use this to pick the best connection strategy. Only set flags to true for transports your agent actually handles — omit or set false for unsupported ones.

**Fields:**

* `streaming` — `boolean`, optional. Set true if the agent streams responses via SSE. Most agents enable this.
* `websocket` — `boolean`, optional. Set true if the agent accepts persistent WebSocket connections.
* `httpBinary` — `boolean`, optional. Set true if the agent supports the AG-UI binary protocol (protobuf over HTTP).
* `pushNotifications` — `boolean`, optional. Set true if the agent can send async updates via webhooks after a run finishes.
* `resumable` — `boolean`, optional. Set true if the agent supports resuming interrupted streams via sequence numbers.

Closed object: the schema rejects members not listed here.

### `ToolsCapabilities`

Tool calling capabilities. Distinguishes between tools the agent itself provides (listed in items) and tools the client passes at runtime via RunAgentInput.tools. Enable this when your agent can call functions, search the web, execute code, etc.

**Fields:**

* `supported` — `boolean`, optional. Set true if the agent can make tool calls at all. Set false to explicitly signal tool calling is disabled even if items are present.
* `items` — array of [`Tool`](#tool), optional. The tools this agent provides on its own (full JSON Schema definitions). These are distinct from client-provided tools passed in RunAgentInput.tools.
* `parallelCalls` — `boolean`, optional. Set true if the agent can invoke multiple tools concurrently within a single step.
* `clientProvided` — `boolean`, optional. Set true if the agent accepts and uses tools provided by the client at runtime.

Closed object: the schema rejects members not listed here.

### `OutputCapabilities`

Output format support. Enable structuredOutput when your agent can return responses conforming to a JSON schema, which is useful for programmatic consumption.

**Fields:**

* `structuredOutput` — `boolean`, optional. Set true if the agent can produce structured JSON output matching a provided schema.
* `supportedMimeTypes` — array of `string`, optional. MIME types the agent can produce (e.g., \["text/plain", "application/json"]). Omit if the agent only produces plain text.

Closed object: the schema rejects members not listed here.

### `StateCapabilities`

State and memory management capabilities. These tell the client how the agent handles shared state and whether conversation context persists across runs.

**Fields:**

* `snapshots` — `boolean`, optional. Set true if the agent emits STATE\_SNAPSHOT events (full state replacement).
* `deltas` — `boolean`, optional. Set true if the agent emits STATE\_DELTA events (JSON Patch incremental updates).
* `memory` — `boolean`, optional. Set true if the agent has long-term memory beyond the current thread (e.g., vector store, knowledge base, or cross-session recall).
* `persistentState` — `boolean`, optional. Set true if state is preserved across multiple runs within the same thread. When false, state resets on each run.

Closed object: the schema rejects members not listed here.

### `MultiAgentCapabilities`

Multi-agent coordination capabilities. Enable these when your agent can orchestrate or hand off work to other agents.

**Fields:**

* `supported` — `boolean`, optional. Set true if the agent participates in any form of multi-agent coordination.
* `delegation` — `boolean`, optional. Set true if the agent can delegate subtasks to other agents while retaining control.
* `handoffs` — `boolean`, optional. Set true if the agent can transfer the conversation entirely to another agent.
* `subagents` — array of [`SubagentInfo`](#subagentinfo), optional. List of subagents this agent can invoke. Helps clients build agent selection UIs.

Closed object: the schema rejects members not listed here.

### `ReasoningCapabilities`

Reasoning and thinking capabilities. Enable these when your agent exposes its internal thought process (e.g., chain-of-thought, extended thinking).

**Fields:**

* `supported` — `boolean`, optional. Set true if the agent produces reasoning/thinking tokens visible to the client.
* `streaming` — `boolean`, optional. Set true if reasoning tokens are streamed incrementally (vs. returned all at once).
* `encrypted` — `boolean`, optional. Set true if reasoning content is encrypted (zero-data-retention mode). Clients should expect opaque encryptedValue fields instead of readable content.

Closed object: the schema rejects members not listed here.

### `MultimodalInputCapabilities`

Modalities the agent can accept as input. Clients use this to show or hide file upload buttons, audio recorders, image pickers, etc.

**Fields:**

* `image` — `boolean`, optional. Set true if the agent can process image inputs (e.g., screenshots, photos).
* `audio` — `boolean`, optional. Set true if the agent can process audio inputs (speech, recordings).
* `video` — `boolean`, optional. Set true if the agent can process video inputs.
* `pdf` — `boolean`, optional. Set true if the agent can process PDF documents.
* `file` — `boolean`, optional. Set true if the agent can process arbitrary file uploads: files of a kind the image, audio, video and document parts do not cover. Says nothing about how a file arrives; a part's source (inline, URL or provider handle) is a separate question.

Closed object: the schema rejects members not listed here.

### `MultimodalOutputCapabilities`

Modalities the agent can produce as output. Clients use this to anticipate rich content in the agent's response.

**Fields:**

* `image` — `boolean`, optional. Set true if the agent can generate images as part of its response.
* `audio` — `boolean`, optional. Set true if the agent can produce audio output (text-to-speech, audio files).

Closed object: the schema rejects members not listed here.

### `MultimodalCapabilities`

Multimodal input and output support. Organized into input and output sub-objects so clients can independently query what the agent accepts versus what it produces.

**Fields:**

* `input` — [`MultimodalInputCapabilities`](#multimodalinputcapabilities), optional. Modalities the agent can accept as input (images, audio, video, PDFs, files).
* `output` — [`MultimodalOutputCapabilities`](#multimodaloutputcapabilities), optional. Modalities the agent can produce as output (images, audio).

Closed object: the schema rejects members not listed here.

### `ExecutionCapabilities`

Execution control and limits. Declare these so clients can set expectations about how long or how many steps an agent run might take.

**Fields:**

* `codeExecution` — `boolean`, optional. Set true if the agent can execute code (e.g., Python, JavaScript) during a run.
* `sandboxed` — `boolean`, optional. Set true if code execution happens in a sandboxed or isolated environment. Only meaningful when codeExecution is true.
* `maxIterations` — `integer` (min 0, max 9007199254740991), optional. Maximum number of tool-call/reasoning iterations the agent will perform per run. Helps clients display progress or set timeout expectations.
* `maxExecutionTime` — `integer` (min 0, max 9007199254740991), optional. Maximum wall-clock time (in milliseconds) the agent will run before timing out.

Closed object: the schema rejects members not listed here.

### `HumanInTheLoopCapabilities`

Human-in-the-loop interaction support. Enable these when your agent can pause execution to request human input, approval, or feedback before continuing.

**Fields:**

* `supported` — `boolean`, optional. Set true if the agent supports any form of human-in-the-loop interaction.
* `approvals` — `boolean`, optional. Set true if the agent can pause and request explicit approval before performing sensitive actions (e.g., sending emails, deleting data).
* `interventions` — `boolean`, optional. Set true if the agent allows humans to intervene and modify its plan mid-execution.
* `feedback` — `boolean`, optional. Set true if the agent can incorporate user feedback (thumbs up/down, corrections) to improve its behavior within the current session.
* `interrupts` — `boolean`, optional. Set true if the agent participates in the AG-UI interrupt protocol: it ends a run with RUN\_FINISHED carrying an interrupt outcome, and accepts the answers back in RunAgentInput.resume.
* `approveWithEdits` — `boolean`, optional. Set true if tool-call interrupts accept editedArgs in the resume payload. Only meaningful when interrupts is true.

Closed object: the schema rejects members not listed here.

### `AgentCapabilities`

A typed, categorized snapshot of an agent's current capabilities. All fields are optional — agents only declare what they support. An omitted field means the capability is not declared (unknown), not that it is unsupported. The custom field is an escape hatch for integration-specific capabilities that do not fit into the standard categories.

**Fields:**

* `identity` — [`IdentityCapabilities`](#identitycapabilities), optional. Agent identity and metadata.
* `transport` — [`TransportCapabilities`](#transportcapabilities), optional. Supported transport mechanisms (SSE, WebSocket, binary, etc.).
* `tools` — [`ToolsCapabilities`](#toolscapabilities), optional. Tools the agent provides and tool calling configuration.
* `output` — [`OutputCapabilities`](#outputcapabilities), optional. Output format support (structured output, MIME types).
* `state` — [`StateCapabilities`](#statecapabilities), optional. State and memory management (snapshots, deltas, persistence).
* `multiAgent` — [`MultiAgentCapabilities`](#multiagentcapabilities), optional. Multi-agent coordination (delegation, handoffs, subagents).
* `reasoning` — [`ReasoningCapabilities`](#reasoningcapabilities), optional. Reasoning and thinking support (chain-of-thought, encrypted thinking).
* `multimodal` — [`MultimodalCapabilities`](#multimodalcapabilities), optional. Multimodal input/output support (images, audio, video, files).
* `execution` — [`ExecutionCapabilities`](#executioncapabilities), optional. Execution control and limits (code execution, timeouts, iteration caps).
* `humanInTheLoop` — [`HumanInTheLoopCapabilities`](#humanintheloopcapabilities), optional. Human-in-the-loop support (approvals, interventions, feedback).
* `custom` — `object`, open by key, optional. Integration-specific capabilities not covered by the standard categories. Open by key: any JSON value is allowed under a key, because the categories above cannot anticipate what an integration declares.

Closed object: the schema rejects members not listed here.

## Mixins

Shared field sets, flattened into every definition that composes them. They
exist in the schema as named definitions so their documentation lives once;
no wire object is ever just a mixin.

### `Attributable`

Composed into everything that can belong to a subagent's work: the events that describe content or progress, the message types, and each interrupt. Run-scoped events omit it — RUN\_STARTED, RUN\_FINISHED and RUN\_ERROR describe the run itself and MESSAGES\_SNAPSHOT is conversation-wide, so none of them can belong to one subagent. A tool call omits it too and inherits its containing message's attribution.

**Fields:**

* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.

### `BaseEvent`

The fields every event carries, whatever its type. Composed into each event definition rather than repeated, so a change here reaches every event at once.

**Fields:**

* `type` — [`EventType`](#eventtype), **required**. Which event this is. Each event definition narrows this to a single value.
* `timestamp` — `integer` (min -9007199254740991, max 9007199254740991), optional. When the event was created. Bounded to the range JSON numbers survive a round trip in, so the value a consumer reads is the value the producer wrote. Deliberately not a float. The unit is not constrained here, because it never has been stated normatively; every SDK that sets it in practice uses milliseconds since the Unix epoch, and a producer choosing another unit will be misread by consumers even though it validates. Nothing in the protocol computes with this value.
* `rawEvent` — any JSON value except `null`, optional. The provider-native event this one was translated from, carried verbatim for debugging and for consumers that need detail the protocol does not model. Any JSON value.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this event.

### `BaseMessage`

The fields shared by the developer, system, assistant and user messages. Deliberately excludes content, because a user message's content may be an array while the others are strings, and composition here intersects rather than overrides: a base that constrained content to a string would make an array content invalid. The tool, activity and reasoning messages do not compose this, because they carry no name.

**Fields:**

* `subagentRunId` — [`SubagentRunId`](#subagentrunid), optional. The subagent invocation this belongs to. Absent means the parent agent produced it directly.
* `id` — `string`, **required**. Identifies the message within the conversation.
* `role` — `string`, **required**. Who the message is from. Each message definition narrows this to a single value.
* `name` — `string`, optional. An optional display name for the author.
* `encryptedValue` — `string`, optional. A provider's opaque artefact belonging to this message, stored by a consumer and returned on a later turn.
* `metadata` — [`Metadata`](#metadata), optional. Extra information attached to this message.


# Schema files
Source: https://docs.ag-ui.com/spec/1.0/schema-files

The machine-readable schema, its address, and how to use it — 1.0

The schema is authoritative for structure: which fields exist, which are
required, what type each carries, and which values a discriminator may take.
This page is where to fetch it.

## The file

> [card] [schema.json](/spec/1.0/schema.json)
>
> The complete 1.0 schema — every event, message, and the run input.

```
https://ag-ui.com/spec/1.0/schema.json
```

The file states that address in its own `$id`, so a validator that follows
references resolves them against it without configuration. The address serves
the file directly: no redirect stands between a tool and the schema, and the
response carries a cross-origin header so a browser-based tool can read it.

It is [JSON Schema draft 2020-12](https://json-schema.org/draft/2020-12/release-notes).
Every definition is reachable by anchor — `#TextMessageStartEvent`,
`#RunAgentInput` — so a tool can address one shape without slicing the file.

## Using it

```bash theme={null}
curl -sS https://ag-ui.com/spec/1.0/schema.json -o ag-ui-1.0.json
```

Validate an event against the whole schema and let the discriminator select the
member, or validate against a single anchor when you already know the shape.

The schema is strict where the protocol is strict: it closes the objects whose
shape it fixes, so a validator run against it rejects material the protocol does
not describe. Objects that are open by design stay open — `metadata` and the
JSON Patch operations among them — because the protocol carries whatever a
consumer puts there. That strictness is for authoring and for tests. A *runtime* consumer
does the opposite — it accepts unrecognised material and strips it, as
[Processing model](/spec/1.0/basic/processing) requires. Do not
wire the strict schema into a receive path and call the result conformance.

## What the schema does not say

Ordering, lifecycle, attribution, error handling and compatibility are
behavioural, and no JSON Schema can express them. They are specified in the
other pages of this document, starting at the [overview](/spec/1.0).


# Support for AG-UI
Source: https://docs.ag-ui.com/support

Open-source and community support for people building with AG-UI

AG-UI is free and open source. Use the project’s public support channels to
report problems, propose improvements, contribute, or get help from the
community.

> [card] [Bugs, feature requests, and contributions](https://github.com/ag-ui-protocol/ag-ui/issues)
>
> Report a problem, propose an improvement, or contribute to AG-UI on GitHub.

> [card] [Community questions and discussion](https://discord.gg/Jd3FzfdJa8)
>
> Ask questions and learn from other people building with AG-UI in Discord.


# Production support
Source: https://docs.ag-ui.com/talk-to-us

Optional commercial architecture and implementation support for teams deploying AG-UI

AG-UI is free and open source. For bugs, feature requests, contributions, and
community questions, visit [Support for AG-UI](/support).

If your team wants hands-on architecture or implementation help with a
production deployment, CopilotKit offers optional commercial engineering
support. This is separate from using or contributing to the AG-UI open-source
project.

[Talk to a CopilotKit engineer](https://www.copilotkit.ai/talk-to-an-engineer?ref=ag_ui_docs_production_support\&utm_source=docs\&utm_medium=referral\&utm_campaign=production_support\&utm_content=ag_ui_production_support)


# Developing with Cursor
Source: https://docs.ag-ui.com/tutorials/cursor

Use Cursor to build AG-UI implementations faster

This guide will help you set up Cursor to help you build custom Agent User
Interaction Protocol (AG-UI) servers and clients faster. The same principles
apply to other IDE's like Windsurf, VSCode, etc.

## Adding the documentation to Cursor

1. Open up the Cursor settings
2. Go to Features > Docs and click "+ Add new Doc"
3. Paste in the following URL: [https://docs.ag-ui.com/llms-full.txt](https://docs.ag-ui.com/llms-full.txt)
4. Click "Add"

## Using the documentation

Now you can use the documentation to help you build your AG-UI project. Load the
docs into the current prompt by typing the `@` symbol, selecting "Docs" and then
selecting "Agent User Interaction Protocol" from the list. Happy coding!

## Best practices

When building AG-UI servers with Cursor:

* Break down complex problems into smaller steps
* Have a look at what the agent was doing by checking which files it edited
  (above the chat input)
* Let the agent write unit tests to verify your implementation
* Follow AG-UI protocol specifications carefully


# Debugging
Source: https://docs.ag-ui.com/tutorials/debugging

A comprehensive guide to debugging Agent User Interaction Protocol (AG-UI) integrations

# Debugging AG-UI Integrations

Debugging agent-based applications can be challenging, especially when working
with real-time, event-driven protocols like AG-UI. This guide introduces you to
the AG-UI Dojo, a powerful tool for learning, testing, and debugging your AG-UI
implementations.

## The AG-UI Dojo

The AG-UI Dojo is the best way to bring AG-UI to a new surface, and is also an
excellent resource for learning about the protocol's basic capabilities. It
provides a structured environment where you can test and validate each component
of the AG-UI protocol.

### What is the Dojo?

The Dojo consists of a series of "hello world"-sized demonstrations for the
different building blocks available via AG-UI. Each demonstration:

1. Shows a specific AG-UI capability in action
2. Presents both the user-visible interaction and the underlying code side by
   side
3. Allows you to test and verify your implementation

### Using the Dojo as an Implementation Checklist

When working on bringing AG-UI to a new surface or platform, you can use the
Dojo as a comprehensive "todo list":

1. Work through each demonstration one by one
2. Implement and test each AG-UI building block in your environment
3. When all demonstrations work correctly in your implementation, you can be
   confident that full-featured copilots and agent-native applications can be
   built on your new surface

This methodical approach ensures you've covered all the necessary functionality
required for a complete AG-UI implementation.

### Using the Dojo as a Learning Resource

For developers new to AG-UI, the Dojo serves as an interactive learning
resource:

* Each item demonstrates a specific AG-UI capability
* You can see both what the interaction looks like from a user perspective
* The underlying code is shown alongside, helping you understand how it works
* The incremental complexity helps build understanding from basics to advanced
  features

### Common Debugging Patterns

When using the Dojo for debugging your AG-UI implementation, keep these patterns
in mind:

1. **Event Sequence Issues**: Verify that events are being emitted in the
   correct order and with proper nesting (e.g., `TEXT_MESSAGE_START` before
   `TEXT_MESSAGE_CONTENT`)

2. **Data Format Problems**: Ensure your event payloads match the expected
   structure for each event type

3. **Transport Layer Debugging**: Check that your chosen transport mechanism
   (SSE, WebSockets, etc.) is correctly delivering events

4. **State Synchronization**: Confirm that state updates are correctly applied
   using snapshots and deltas

5. **Tool Execution**: Verify that tool calls and responses are properly
   formatted and processed

## Getting Started with the Dojo

To start using the AG-UI Dojo:

1. Clone the repository from
   [github.com/ag-ui-protocol/ag-ui](https://github.com/ag-ui-protocol/ag-ui)
2. Follow the setup instructions in the README
3. Start working through the demonstrations in order
4. Use the provided test cases to validate your implementation

The Dojo's structured approach makes it an invaluable resource for both learning
AG-UI and ensuring your implementation meets all requirements.


# Events
Source: https://docs.ag-ui.com/sdk/dotnet/abstractions/events

Documentation for the streaming event types in AGUI.Abstractions

# Events

AG-UI uses a streaming event-based architecture. Events are the units of
communication from an agent backend to a frontend UI. In .NET, every protocol
event derives from `BaseEvent` and has a `type` discriminator.

## Event Type Constants

`AGUIEventTypes` defines the SCREAMING\_SNAKE\_CASE wire discriminators:

```csharp theme={null}
AGUIEventTypes.RunStarted; // "RUN_STARTED"
AGUIEventTypes.RunFinished; // "RUN_FINISHED"
AGUIEventTypes.RunError; // "RUN_ERROR"
AGUIEventTypes.StepStarted; // "STEP_STARTED"
AGUIEventTypes.StepFinished; // "STEP_FINISHED"
AGUIEventTypes.TextMessageStart; // "TEXT_MESSAGE_START"
AGUIEventTypes.TextMessageContent; // "TEXT_MESSAGE_CONTENT"
AGUIEventTypes.TextMessageEnd; // "TEXT_MESSAGE_END"
AGUIEventTypes.ToolCallStart; // "TOOL_CALL_START"
AGUIEventTypes.ToolCallArgs; // "TOOL_CALL_ARGS"
AGUIEventTypes.ToolCallEnd; // "TOOL_CALL_END"
AGUIEventTypes.ToolCallResult; // "TOOL_CALL_RESULT"
AGUIEventTypes.StateSnapshot; // "STATE_SNAPSHOT"
AGUIEventTypes.StateDelta; // "STATE_DELTA"
AGUIEventTypes.MessagesSnapshot; // "MESSAGES_SNAPSHOT"
AGUIEventTypes.ActivitySnapshot; // "ACTIVITY_SNAPSHOT"
AGUIEventTypes.ActivityDelta; // "ACTIVITY_DELTA"
AGUIEventTypes.ReasoningStart; // "REASONING_START"
AGUIEventTypes.ReasoningMessageStart; // "REASONING_MESSAGE_START"
AGUIEventTypes.ReasoningMessageContent; // "REASONING_MESSAGE_CONTENT"
AGUIEventTypes.ReasoningMessageEnd; // "REASONING_MESSAGE_END"
AGUIEventTypes.ReasoningMessageChunk; // "REASONING_MESSAGE_CHUNK"
AGUIEventTypes.ReasoningEnd; // "REASONING_END"
AGUIEventTypes.ReasoningEncryptedValue; // "REASONING_ENCRYPTED_VALUE"
AGUIEventTypes.Raw; // "RAW"
AGUIEventTypes.Custom; // "CUSTOM"
```

## BaseEvent

All events inherit from `BaseEvent`.

```csharp theme={null}
public abstract class BaseEvent
{
    public abstract string Type { get; } // "type"
    public long? Timestamp { get; set; } // "timestamp"
    public JsonElement? RawEvent { get; set; } // "rawEvent"
    public JsonElement? Metadata { get; set; } // "metadata"
}
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `string` | Event discriminator |
| `Timestamp` | `timestamp` | `long?` | Optional event timestamp |
| `RawEvent` | `rawEvent` | `JsonElement?` | Optional original event data |
| `Metadata` | `metadata` | `JsonElement?` | Optional extra information, open by key |

`Metadata` is open by key: any JSON value is allowed under a key, including
`null`. The object may be absent, but a present one is never `null` — an
explicit `null` is read back as absent, and an absent object is omitted from the
wire rather than serialized as `null`. `AGUIMetadata.ReservedKey` (`"ag-ui"`) is
reserved for AG-UI's own use.

## Lifecycle Events

Lifecycle events represent the run and step lifecycle.

### RunStartedEvent

Signals the start of an agent run.

```csharp theme={null}
var evt = new RunStartedEvent
{
    ThreadId = "thread-1",
    RunId = "run-1",
    ParentRunId = "run-0",
    Input = input,
    ProtocolVersion = AGUIProtocol.Version
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"RUN_STARTED"` | Event discriminator |
| `ThreadId` | `threadId` | `string` | Conversation thread ID |
| `RunId` | `runId` | `string` | Agent run ID |
| `ParentRunId` | `parentRunId` | `string?` | Optional parent run ID |
| `Input` | `input` | `RunAgentInput?` | Optional input payload for the run |
| `ProtocolVersion` | `protocolVersion` | `string?` | AG-UI protocol version the producer speaks. Set it to `AGUIProtocol.Version` (`"1.0"`) on every hand-built event; a stream without it reads as pre-1.0 |

### RunFinishedEvent

Signals the completion of an agent run.

```csharp theme={null}
var evt = new RunFinishedEvent
{
    ThreadId = "thread-1",
    RunId = "run-1",
    Outcome = new RunFinishedSuccessOutcome()
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"RUN_FINISHED"` | Event discriminator |
| `ThreadId` | `threadId` | `string` | Conversation thread ID |
| `RunId` | `runId` | `string` | Agent run ID |
| `Result` | `result` | `JsonElement?` | Optional run result |
| `Outcome` | `outcome` | `RunFinishedOutcome?` | Optional typed outcome |
| `Usage` | `usage` | `IList<TokenUsage>?` | Optional token usage for the run |

`RunFinishedOutcome` is a polymorphic value with `type: "success"` or
`type: "interrupt"`. `RunFinishedInterruptOutcome` carries `interrupts`, an
`IList<AGUIInterrupt>`.

`Usage` is described under [TokenUsage](#tokenusage).

### RunErrorEvent

Signals an error during an agent run.

```csharp theme={null}
var evt = new RunErrorEvent
{
    Message = "The model request failed.",
    Code = "model_error"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"RUN_ERROR"` | Event discriminator |
| `Message` | `message` | `string` | Error message |
| `Code` | `code` | `string?` | Optional error code |
| `Usage` | `usage` | `IList<TokenUsage>?` | Optional partial usage accrued before the failure |

### TokenUsage

Provider-reported token usage, carried by both terminal run events. One entry per
`(provider, model)` pair, so a run that invokes several models keeps them separate;
consumers that only need totals can sum across the entries.

```csharp theme={null}
var evt = new RunFinishedEvent
{
    ThreadId = "thread-1",
    RunId = "run-1",
    Outcome = new RunFinishedSuccessOutcome(),
    Usage =
    [
        new TokenUsage
        {
            Provider = "openai",
            Model = "gpt-4o",
            InputTokens = 658,
            OutputTokens = 188,
            TotalTokens = 846
        }
    ]
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Provider` | `provider` | `string?` | Provider that served the request |
| `Model` | `model` | `string?` | Model that served the request |
| `InputTokens` | `inputTokens` | `long?` | All input tokens, cache reads and writes included |
| `OutputTokens` | `outputTokens` | `long?` | All output tokens, reasoning included |
| `TotalTokens` | `totalTokens` | `long?` | `inputTokens` plus `outputTokens` |
| `ReasoningTokens` | `reasoningTokens` | `long?` | Output tokens spent on reasoning; part of `outputTokens` |
| `CachedInputTokens` | `cachedInputTokens` | `long?` | Input tokens read from a prompt cache; part of `inputTokens` |
| `CacheWriteInputTokens` | `cacheWriteInputTokens` | `long?` | Input tokens written to a prompt cache; part of `inputTokens`. `Microsoft.Extensions.AI` has no first-class property for it, so `AGUI.Server` reads it from `UsageDetails.AdditionalCounts["CacheWriteInputTokens"]` and `AGUI.Client` writes it there |

Every field is optional. A null count means the provider did not report it, which is
distinct from a reported zero — so `usage` never fabricates a count the provider
withheld. The type is numeric-only by design: it carries no prompts, completions,
messages, tool arguments, or thread/run/user identifiers.

When hosting with `AGUI.Server`, usage reported by Microsoft.Extensions.AI as
`UsageContent` is accumulated automatically and attached to the terminal event.
`ModelId` supplies the model label; set the provider label with
`AGUIStreamOptions.WithUsageProvider("openai")`.

### StepStartedEvent

Signals the start of a named step.

```csharp theme={null}
var evt = new StepStartedEvent { StepName = "plan" };
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"STEP_STARTED"` | Event discriminator |
| `StepName` | `stepName` | `string` | Step name |

### StepFinishedEvent

Signals the completion of a named step.

```csharp theme={null}
var evt = new StepFinishedEvent { StepName = "plan" };
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"STEP_FINISHED"` | Event discriminator |
| `StepName` | `stepName` | `string` | Step name |

## Text Message Events

Text message events stream assistant text as a start/content/end sequence.

### TextMessageStartEvent

```csharp theme={null}
var evt = new TextMessageStartEvent
{
    MessageId = "msg-1",
    Role = AGUIRoles.Assistant,
    Name = "assistant"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"TEXT_MESSAGE_START"` | Event discriminator |
| `MessageId` | `messageId` | `string` | Message ID |
| `Role` | `role` | `string` | Message role, typically `"assistant"` |
| `Name` | `name` | `string?` | Optional sender name |

### TextMessageContentEvent

```csharp theme={null}
var evt = new TextMessageContentEvent
{
    MessageId = "msg-1",
    Delta = "Hello"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"TEXT_MESSAGE_CONTENT"` | Event discriminator |
| `MessageId` | `messageId` | `string` | Message ID from the start event |
| `Delta` | `delta` | `string` | Text delta |

### TextMessageEndEvent

```csharp theme={null}
var evt = new TextMessageEndEvent { MessageId = "msg-1" };
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"TEXT_MESSAGE_END"` | Event discriminator |
| `MessageId` | `messageId` | `string` | Message ID from the start event |

## Tool Call Events

Tool call events stream tool invocation arguments and optional server-side
results.

### ToolCallStartEvent

```csharp theme={null}
var evt = new ToolCallStartEvent
{
    ParentMessageId = "msg-1",
    ToolCallId = "call-1",
    ToolCallName = "get_weather"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"TOOL_CALL_START"` | Event discriminator |
| `ParentMessageId` | `parentMessageId` | `string?` | Optional parent assistant message ID |
| `ToolCallId` | `toolCallId` | `string` | Tool call ID |
| `ToolCallName` | `toolCallName` | `string` | Tool name |

### ToolCallArgsEvent

```csharp theme={null}
var evt = new ToolCallArgsEvent
{
    ToolCallId = "call-1",
    Delta = """{"city":"Seattle"}"""
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"TOOL_CALL_ARGS"` | Event discriminator |
| `ToolCallId` | `toolCallId` | `string` | Tool call ID |
| `Delta` | `delta` | `string` | Argument JSON chunk |

### ToolCallEndEvent

```csharp theme={null}
var evt = new ToolCallEndEvent { ToolCallId = "call-1" };
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"TOOL_CALL_END"` | Event discriminator |
| `ToolCallId` | `toolCallId` | `string` | Tool call ID |

### ToolCallResultEvent

```csharp theme={null}
var evt = new ToolCallResultEvent
{
    MessageId = "tool-msg-1",
    ToolCallId = "call-1",
    Content = """{"temperature":72}""",
    Role = AGUIRoles.Tool
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"TOOL_CALL_RESULT"` | Event discriminator |
| `MessageId` | `messageId` | `string` | Tool result message ID |
| `ToolCallId` | `toolCallId` | `string` | Tool call ID |
| `Content` | `content` | `string` | Tool result content |
| `Role` | `role` | `string?` | Optional role, typically `"tool"` |

## State Management Events

State events synchronize frontend state and message history.

### StateSnapshotEvent

Provides a complete state snapshot.

```csharp theme={null}
var evt = new StateSnapshotEvent
{
    Snapshot = JsonDocument.Parse("""{"draft":"hello"}""").RootElement.Clone()
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"STATE_SNAPSHOT"` | Event discriminator |
| `Snapshot` | `snapshot` | `JsonElement` | Complete state value |

### StateDeltaEvent

Provides incremental state changes, commonly as JSON Patch operations.

```csharp theme={null}
var evt = new StateDeltaEvent
{
    Delta = JsonDocument.Parse("""
        [{ "op": "replace", "path": "/draft", "value": "hello world" }]
        """).RootElement.Clone()
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"STATE_DELTA"` | Event discriminator |
| `Delta` | `delta` | `JsonElement` | State delta payload |

### MessagesSnapshotEvent

Replaces the frontend conversation history with the server's view.

```csharp theme={null}
var evt = new MessagesSnapshotEvent
{
    Messages =
    [
        new AGUIUserMessage { Id = "user-1", Content = "Hello" }
    ]
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"MESSAGES_SNAPSHOT"` | Event discriminator |
| `Messages` | `messages` | `IList<AGUIMessage>` | Complete message list |

## Reasoning Events

Reasoning events expose a model or agent reasoning stream. They can create and
update `AGUIReasoningMessage` entries in message history.

### ReasoningStartEvent

```csharp theme={null}
var evt = new ReasoningStartEvent { MessageId = "reasoning-1" };
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"REASONING_START"` | Event discriminator |
| `MessageId` | `messageId` | `string` | Reasoning phase ID |

### ReasoningMessageStartEvent

```csharp theme={null}
var evt = new ReasoningMessageStartEvent
{
    MessageId = "reasoning-1",
    Role = AGUIRoles.Reasoning
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"REASONING_MESSAGE_START"` | Event discriminator |
| `MessageId` | `messageId` | `string` | Reasoning message ID |
| `Role` | `role` | `string` | Defaults to `"reasoning"` |

### ReasoningMessageContentEvent

```csharp theme={null}
var evt = new ReasoningMessageContentEvent
{
    MessageId = "reasoning-1",
    Delta = "Checking constraints..."
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"REASONING_MESSAGE_CONTENT"` | Event discriminator |
| `MessageId` | `messageId` | `string` | Reasoning message ID |
| `Delta` | `delta` | `string` | Reasoning content delta |

### ReasoningMessageEndEvent

```csharp theme={null}
var evt = new ReasoningMessageEndEvent { MessageId = "reasoning-1" };
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"REASONING_MESSAGE_END"` | Event discriminator |
| `MessageId` | `messageId` | `string` | Reasoning message ID |

### ReasoningMessageChunkEvent

Compact reasoning message chunk event with optional fields.

```csharp theme={null}
var evt = new ReasoningMessageChunkEvent
{
    MessageId = "reasoning-1",
    Delta = "Partial reasoning..."
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"REASONING_MESSAGE_CHUNK"` | Event discriminator |
| `MessageId` | `messageId` | `string?` | Optional reasoning message ID |
| `Delta` | `delta` | `string?` | Optional reasoning content delta |

### ReasoningEndEvent

```csharp theme={null}
var evt = new ReasoningEndEvent { MessageId = "reasoning-1" };
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"REASONING_END"` | Event discriminator |
| `MessageId` | `messageId` | `string` | Reasoning phase ID |

### ReasoningEncryptedValueEvent

Attaches an encrypted value to a message or tool call.

```csharp theme={null}
var evt = new ReasoningEncryptedValueEvent
{
    Subtype = "message",
    EntityId = "reasoning-1",
    EncryptedValue = "opaque-token"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"REASONING_ENCRYPTED_VALUE"` | Event discriminator |
| `Subtype` | `subtype` | `string` | Entity subtype, such as `"message"` or `"tool-call"` |
| `EntityId` | `entityId` | `string` | Message or tool call ID |
| `EncryptedValue` | `encryptedValue` | `string` | Opaque encrypted value |

## Activity Events

Activity events carry structured progress state for UI renderers.

### ActivitySnapshotEvent

```csharp theme={null}
var evt = new ActivitySnapshotEvent
{
    MessageId = "activity-1",
    ActivityType = "PLAN",
    Content = JsonDocument.Parse("""{"status":"running"}""").RootElement.Clone(),
    Replace = true
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"ACTIVITY_SNAPSHOT"` | Event discriminator |
| `MessageId` | `messageId` | `string` | Activity message ID |
| `ActivityType` | `activityType` | `string` | Activity discriminator |
| `Content` | `content` | `JsonElement` | Structured activity content |
| `Replace` | `replace` | `bool?` | Optional replace/merge hint |

### ActivityDeltaEvent

```csharp theme={null}
var evt = new ActivityDeltaEvent
{
    MessageId = "activity-1",
    ActivityType = "PLAN",
    Patch = JsonDocument.Parse("""
        [{ "op": "replace", "path": "/status", "value": "done" }]
        """).RootElement.Clone()
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"ACTIVITY_DELTA"` | Event discriminator |
| `MessageId` | `messageId` | `string` | Activity message ID |
| `ActivityType` | `activityType` | `string` | Activity discriminator |
| `Patch` | `patch` | `JsonElement` | Activity JSON Patch payload |

## Subagent Events

These events report that the agent delegated work to a child agent, so a frontend
can attribute output to the subagent that produced it. Attribution itself travels
as an optional `SubagentRunId` on most other event types.

`SubagentRunId` identifies **one invocation**, not a reusable subagent
definition — the same subagent run twice yields two different values. See
[Subagents](/concepts/subagents) for the full model.

### SubagentStartedEvent

Announces a new subagent invocation and names it for display.

```csharp theme={null}
var evt = new SubagentStartedEvent
{
    SubagentRunId = "sub-1",
    Name = "researcher",
    Description = "Searches for supporting sources"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"SUBAGENT_STARTED"` | Event discriminator |
| `SubagentRunId` | `subagentRunId` | `string` | Opaque id for this invocation |
| `Name` | `name` | `string` | Declared subagent name, for display |
| `Description` | `description` | `string?` | Optional description |
| `ParentSubagentRunId` | `parentSubagentRunId` | `string?` | Enclosing subagent, when nesting |
| `ParentToolCallId` | `parentToolCallId` | `string?` | Tool call that spawned this subagent |
| `ParentMessageId` | `parentMessageId` | `string?` | Message holding that tool call |

### SubagentFinishedEvent

Marks a subagent invocation as complete.

```csharp theme={null}
var evt = new SubagentFinishedEvent { SubagentRunId = "sub-1" };
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"SUBAGENT_FINISHED"` | Event discriminator |
| `SubagentRunId` | `subagentRunId` | `string` | Matches the id from `SubagentStartedEvent` |
| `Result` | `result` | `object?` | Optional payload, mirroring `RunFinishedEvent.Result` |
| `Outcome` | `outcome` | `SubagentFinishedOutcome?` | `SubagentFinishedSuccessOutcome` or `SubagentFinishedSuspendedOutcome` (with optional `InterruptIds`); `null` means success (the legacy reading). Suspended says the subagent is checkpointed awaiting outside input; `InterruptIds` names the run-level interrupts whose answers resume it. |

### SubagentErrorEvent

Marks a subagent invocation as failed.

```csharp theme={null}
var evt = new SubagentErrorEvent
{
    SubagentRunId = "sub-1",
    Message = "Search backend unavailable"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"SUBAGENT_ERROR"` | Event discriminator |
| `SubagentRunId` | `subagentRunId` | `string` | Matches the id from `SubagentStartedEvent` |
| `Message` | `message` | `string` | Human-readable error message |
| `Code` | `code` | `string?` | Optional error code |

### Attribution on other events

Most event types expose an optional `SubagentRunId`. An event without it belongs
to the parent agent, so a stream that never sets it behaves exactly as it did
before subagents existed.

`RunStartedEvent`, `RunFinishedEvent` and `RunErrorEvent` are not attributable —
they describe the run as a whole. `MessagesSnapshotEvent` carries attribution
per-message instead.

`StateSnapshotEvent` and `StateDeltaEvent` are attributable, but attribution on
them is provenance rather than ownership — it records which subagent produced the
update. State stays run-scoped, so an attributed snapshot or delta is applied to
the run's one state document just as an unattributed one is.

When events are converted to `Microsoft.Extensions.AI` types, attribution is
preserved on `ChatMessage.AdditionalProperties` under the key
`agui.subagentRunId`, since those types have no dedicated field for it.

## Special Events

### RawEvent

Passes through unprocessed external data.

```csharp theme={null}
var evt = new RawEvent
{
    Event = JsonDocument.Parse("""{"provider":"example","event":"token"}""").RootElement.Clone(),
    Source = "provider"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"RAW"` | Event discriminator |
| `Event` | `event` | `JsonElement` | Raw payload |
| `Source` | `source` | `string?` | Optional source identifier |

### CustomEvent

Carries application-specific data.

```csharp theme={null}
var evt = new CustomEvent
{
    Name = "progress",
    Value = JsonDocument.Parse("""{"percent":50}""").RootElement.Clone()
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"CUSTOM"` | Event discriminator |
| `Name` | `name` | `string` | Custom event name |
| `Value` | `value` | `JsonElement?` | Optional custom payload |

## Serialization

`BaseEvent` uses a discriminator-based JSON converter keyed on the `type` field.
All concrete event types are registered in `AGUIJsonSerializerContext`.

```csharp theme={null}
BaseEvent evt = new TextMessageContentEvent
{
    MessageId = "msg-1",
    Delta = "Hello"
};

var json = JsonSerializer.Serialize(
    evt,
    AGUIJsonSerializerContext.Default.BaseEvent);
```


# Multimodal Inputs
Source: https://docs.ag-ui.com/sdk/dotnet/abstractions/multimodal-inputs

Use modality-specific user input parts with typed data and URL sources in AGUI.Abstractions

# Multimodal Inputs

`AGUIUserMessage.Content` accepts either plain text or an ordered array of
multimodal content parts through the `AGUIContent` union.

```csharp theme={null}
using System.Text.Json;
using AGUI.Abstractions;

var message = new AGUIUserMessage
{
    Id = "user-1",
    Content =
    [
        new AGUITextInputContent
        {
            Text = "Summarize this PDF and screenshot"
        },
        new AGUIImageInputContent
        {
            Source = new AGUIInputContentUrlSource
            {
                Value = "https://example.com/screen.png",
                MimeType = "image/png"
            }
        },
        new AGUIDocumentInputContent
        {
            Source = new AGUIInputContentUrlSource
            {
                Value = "https://example.com/report.pdf",
                MimeType = "application/pdf"
            }
        }
    ]
};
```

## User Message Content

The AG-UI wire model for user messages is `content: string | InputContent[]`.
In .NET, that is represented by `AGUIContent`.

```csharp theme={null}
var plainText = new AGUIUserMessage
{
    Id = "user-1",
    Content = "Hello"
};

var parts = new AGUIUserMessage
{
    Id = "user-2",
    Content =
    [
        new AGUITextInputContent { Text = "Describe this image." },
        new AGUIImageInputContent
        {
            Source = new AGUIInputContentUrlSource
            {
                Value = "https://example.com/image.png",
                MimeType = "image/png"
            }
        }
    ]
};
```

`AGUIContent` has implicit conversions from `string`,
`List<AGUIInputContent>`, and `AGUIInputContent[]`, supports collection
expressions, and implements `IReadOnlyList<AGUIInputContent>` for normalized
reads. When the stored value is a string, the read-only list facade exposes it
as a single `AGUITextInputContent`.

## Input Content Types

All content parts derive from `AGUIInputContent` and use the JSON `type`
discriminator.

| C# type | JSON `type` | Properties |
| - | - | - |
| `AGUITextInputContent` | `text` | `text` |
| `AGUIImageInputContent` | `image` | `source`, optional `metadata` |
| `AGUIAudioInputContent` | `audio` | `source`, optional `metadata` |
| `AGUIVideoInputContent` | `video` | `source`, optional `metadata` |
| `AGUIDocumentInputContent` | `document` | `source`, optional `metadata` |
| `AGUIBinaryInputContent` | `binary` | `mimeType`, optional `id`, `url`, `data`, `filename` |

### Text

```csharp theme={null}
var text = new AGUITextInputContent
{
    Text = "What issue do you see in this UI?"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"text"` | Content discriminator |
| `Id` | `id` | `string?` | Optional part identifier |
| `Text` | `text` | `string` | Text content |
| `Metadata` | `metadata` | `JsonElement?` | Optional metadata, such as a search hit's source and title |

### Media Parts

Images, audio, video, and documents all derive from `AGUIMediaInputContent`.

```csharp theme={null}
var image = new AGUIImageInputContent
{
    Source = new AGUIInputContentUrlSource
    {
        Value = "https://example.com/ui.png",
        MimeType = "image/png"
    },
    Metadata = JsonDocument.Parse("""{"detail":"high"}""").RootElement.Clone()
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"image"`, `"audio"`, `"video"`, or `"document"` | Content discriminator |
| `Id` | `id` | `string?` | Optional part identifier |
| `Source` | `source` | `AGUIInputContentSource` | Data, URL or provider file source |
| `Metadata` | `metadata` | `JsonElement?` | Optional modality-specific metadata |

When a server adapts an AG-UI request to Microsoft.Extensions.AI,
`AGUIChatMessageExtensions.AsChatMessages()` maps data sources to `DataContent`,
URL sources to `UriContent` and file sources to `HostedFileContent` (the handle
becomes `FileId`; `Provider` has no counterpart there and is dropped on that
hop, though it round-trips through JSON and protobuf). The source MIME type is
preserved; when a URL source omits `mimeType`, `UriContent` infers it from the
URL. If the URL does
not have a recognized extension, the canonical discriminator supplies
`image/*`, `audio/*`, or `video/*` so the modality is not lost.

The complete `metadata` value is preserved under the MEAI content's
`AdditionalProperties["metadata"]` key, including object-shaped values. For
inline data, a string `metadata.filename` property is also assigned to
`DataContent.Name` so file-capable providers receive the filename.

In the client direction, `AsAGUIMessages(jsonSerializerOptions)` maps
`DataContent` and `UriContent`
to canonical media parts based on their MIME type and serializes their
`AdditionalProperties` as the part's `metadata`. `DataContent.Name` is included
as `metadata.filename` when that property is not already present.

### Binary

`AGUIBinaryInputContent` represents an arbitrary binary input part.

```csharp theme={null}
var binary = new AGUIBinaryInputContent
{
    MimeType = "application/octet-stream",
    Data = "AAECAwQ=",
    Filename = "payload.bin"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"binary"` | Content discriminator |
| `MimeType` | `mimeType` | `string` | MIME type |
| `Id` | `id` | `string?` | Optional binary identifier |
| `Url` | `url` | `string?` | Optional URL for the binary |
| `Data` | `data` | `string?` | Optional inline base64 data |
| `Filename` | `filename` | `string?` | Optional file name |

## Source Types

Media input parts use `AGUIInputContentSource`, a discriminator-based hierarchy
with JSON field `type`.

### Data Source

Use `AGUIInputContentDataSource` for inline base64 payloads. `mimeType` is
required.

```csharp theme={null}
var source = new AGUIInputContentDataSource
{
    Value = "iVBORw0KGgo...",
    MimeType = "image/png"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"data"` | Source discriminator |
| `Value` | `value` | `string` | Inline base64 payload |
| `MimeType` | `mimeType` | `string` | Payload MIME type |

### URL Source

Use `AGUIInputContentUrlSource` for HTTP(S) URLs or data URLs. `mimeType` is
optional.

```csharp theme={null}
var source = new AGUIInputContentUrlSource
{
    Value = "https://example.com/meeting.wav",
    MimeType = "audio/wav"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"url"` | Source discriminator |
| `Value` | `value` | `string` | URL or data URL |
| `MimeType` | `mimeType` | `string?` | Optional MIME type |

### File Source

Use `AGUIInputContentFileSource` for bytes that already live at the model
provider — an OpenAI or Anthropic file id, a Gemini file URI. Nothing is
fetched and `Value` is opaque: hand it to the provider that issued it, or drop
the part. `provider` and `mimeType` are optional.

```csharp theme={null}
var source = new AGUIInputContentFileSource
{
    Value = "file-abc123",
    Provider = "openai",
    MimeType = "application/pdf"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Type` | `type` | `"file"` | Source discriminator |
| `Value` | `value` | `string` | The provider's handle, exactly as issued |
| `Provider` | `provider` | `string?` | Who issued it, e.g. `"openai"`, `"anthropic"`, `"google"` |
| `MimeType` | `mimeType` | `string?` | Optional MIME type |

## Common Use Cases

### Visual QA

```csharp theme={null}
var message = new AGUIUserMessage
{
    Id = "q1",
    Content =
    [
        new AGUITextInputContent
        {
            Text = "What issue do you see in this UI?"
        },
        new AGUIImageInputContent
        {
            Source = new AGUIInputContentUrlSource
            {
                Value = "https://example.com/ui.png",
                MimeType = "image/png"
            },
            Metadata = JsonDocument.Parse("""{"detail":"high"}""").RootElement.Clone()
        }
    ]
};
```

### Audio Transcription

```csharp theme={null}
var message = new AGUIUserMessage
{
    Id = "q2",
    Content =
    [
        new AGUITextInputContent
        {
            Text = "Transcribe this recording."
        },
        new AGUIAudioInputContent
        {
            Source = new AGUIInputContentUrlSource
            {
                Value = "https://example.com/meeting.wav",
                MimeType = "audio/wav"
            }
        }
    ]
};
```

### Mixed Media Comparison

```csharp theme={null}
var message = new AGUIUserMessage
{
    Id = "q3",
    Content =
    [
        new AGUITextInputContent
        {
            Text = "Compare the screenshot with the spec."
        },
        new AGUIImageInputContent
        {
            Source = new AGUIInputContentDataSource
            {
                Value = "iVBORw0KGgo...",
                MimeType = "image/png"
            }
        },
        new AGUIDocumentInputContent
        {
            Source = new AGUIInputContentUrlSource
            {
                Value = "https://example.com/spec.pdf",
                MimeType = "application/pdf"
            }
        }
    ]
};
```

> [!TIP]
>
> Use plain string `Content` for simple text-only turns. Use multimodal parts
> when order matters or when the user message includes media alongside text.


# Overview
Source: https://docs.ag-ui.com/sdk/dotnet/abstractions/overview

Protocol types in the AG-UI .NET SDK

# AGUI.Abstractions

`AGUI.Abstractions` is the protocol-types package for the AG-UI .NET SDK. It
defines the shared event, message, tool, context, capability, interrupt, and
serialization types used by AG-UI clients and servers.

```bash theme={null}
dotnet add package AGUI.Abstractions
```

The package has no opinion about HTTP, ASP.NET Core, or a specific agent
runtime. It is the .NET sibling of `@ag-ui/core`: stable wire types for the
event stream and request payload.

> [!NOTE]
>
> `AGUI.Abstractions` targets `net10.0`, `net9.0`, `net8.0`,
> `netstandard2.0`, and `net472`. It is AOT-compatible: serializable protocol
> types are registered in the source-generated `AGUIJsonSerializerContext`.

## SDK packages

The .NET SDK is split into small packages so protocol types, wire formats,
client code, and server code can be adopted independently.

| Package | Use it for |
| - | - |
| `AGUI.Abstractions` | Protocol events, messages, tools, capabilities, interrupts, and JSON serialization. |
| `AGUI.Formatting` | Event-stream formatter abstractions and Server-Sent Events support. |
| `AGUI.Protobuf` | Protobuf event-stream formatting and binary protocol support. |
| `AGUI.Client` | HTTP client and `IChatClient` implementation for consuming AG-UI endpoints. |
| `AGUI.Server` | Framework-agnostic adapter from `ChatResponseUpdate` streams to AG-UI events. |

## Wire formats and parity

JSON over Server-Sent Events is the full-fidelity event stream.
`AGUI.Formatting` defines the event-stream formatter contract and SSE support.
`AGUI.Protobuf` adds binary event-stream formatting for the protocol subset
supported by the shared proto schema.

Protocol parity starts in `AGUI.Abstractions`. When the TypeScript reference SDK
adds or changes a wire type, the matching .NET event, message, tool, or
capability type should update alongside `AGUIJsonSerializerContext` and the
compatibility fixtures. Public API tracking files should update whenever a
protocol change adds or changes .NET types.

```bash theme={null}
cd sdks/dotnet
dotnet test tests/AGUI.Abstractions.UnitTests/
dotnet test tests/AGUI.Formatting.UnitTests/
dotnet test tests/AGUI.Protobuf.UnitTests/
```

## Types

Core data structures that represent the building blocks of the protocol:

* [RunAgentInput](/sdk/dotnet/abstractions/types#runagentinput) - Input payload
  for running agents
* [Message types](/sdk/dotnet/abstractions/types#message-types) - Conversation,
  tool, activity, and reasoning messages
* [AGUIContext](/sdk/dotnet/abstractions/types#context) - Contextual information
  provided to agents
* [AGUITool](/sdk/dotnet/abstractions/types#tool) - Tool definitions with JSON
  Schema parameters
* [AgentCapabilities](/sdk/dotnet/abstractions/types#agentcapabilities) -
  Structured capability declarations

> [card] [Types Reference](/sdk/dotnet/abstractions/types)
>
> Complete documentation of the protocol types in `AGUI.Abstractions`

> [card] [Multimodal Inputs](/sdk/dotnet/abstractions/multimodal-inputs)
>
> User message content parts for text, image, audio, video, document, and binary input

## Events

Events power communication between agents and frontends:

* [Lifecycle events](/sdk/dotnet/abstractions/events#lifecycle-events) - Run and
  step tracking
* [Text message events](/sdk/dotnet/abstractions/events#text-message-events) -
  Assistant message streaming
* [Tool call events](/sdk/dotnet/abstractions/events#tool-call-events) -
  Function call lifecycle
* [State management events](/sdk/dotnet/abstractions/events#state-management-events) -
  Agent state and message snapshots
* [Reasoning events](/sdk/dotnet/abstractions/events#reasoning-events) -
  Reasoning stream support
* [Activity events](/sdk/dotnet/abstractions/events#activity-events) -
  Structured progress and transient UI state
* [Special events](/sdk/dotnet/abstractions/events#special-events) - Raw and
  custom events

> [card] [Events Reference](/sdk/dotnet/abstractions/events)
>
> Complete documentation of all event types in `AGUI.Abstractions`


# Types
Source: https://docs.ag-ui.com/sdk/dotnet/abstractions/types

Documentation for the protocol types in AGUI.Abstractions

# AGUI.Abstractions Types

`AGUI.Abstractions` contains the protocol model shared by AG-UI .NET clients
and servers. The JSON wire names are camel-case and match the AG-UI protocol.

## RunAgentInput

`RunAgentInput` is the request payload for running an agent. In the HTTP API, it
is the body of the `POST` request.

```csharp theme={null}
using System.Text.Json;
using AGUI.Abstractions;

var input = new RunAgentInput
{
    ThreadId = "thread-1",
    RunId = "run-1",
    Messages =
    [
        new AGUIUserMessage
        {
            Id = "msg-1",
            Content = "Hello!"
        }
    ],
    Tools =
    [
        new AGUITool
        {
            Name = "get_weather",
            Description = "Get the weather for a city",
            Parameters = JsonDocument.Parse("""
                {
                  "type": "object",
                  "properties": {
                    "city": { "type": "string" }
                  },
                  "required": ["city"]
                }
                """).RootElement.Clone()
        }
    ]
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `ThreadId` | `threadId` | `string` | ID of the conversation thread |
| `RunId` | `runId` | `string` | ID of the current run |
| `ParentRunId` | `parentRunId` | `string?` | Optional lineage pointer for branching or time travel |
| `Messages` | `messages` | `IList<AGUIMessage>` | Conversation messages |
| `Tools` | `tools` | `IList<AGUITool>?` | Tools available to the agent |
| `State` | `state` | `JsonElement?` | Current frontend or agent state |
| `Resume` | `resume` | `IList<AGUIResume>?` | Resume payloads for interrupted runs |
| `Context` | `context` | `IList<AGUIContext>?` | Context objects provided to the agent |
| `ForwardedProperties` | `forwardedProps` | `JsonElement` | Additional properties forwarded by the client |

## AGUIResume

One per-interrupt response inside `RunAgentInput.Resume`, addressing an
interrupt from the previous run. See
[Interrupts](/concepts/interrupts#resuming-a-run) for the full resume contract.

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `InterruptId` | `interruptId` | `string` | ID of the interrupt this entry addresses |
| `Status` | `status` | `string` | `ResumeStatus.Resolved` if the user responded, `ResumeStatus.Cancelled` if they abandoned |
| `Payload` | `payload` | `JsonElement?` | The response itself, validated against the interrupt's `responseSchema` |
| `Metadata` | `metadata` | `JsonElement?` | Envelope data about the response — signatures, routing keys — never the answer itself |

`Metadata` follows the same conventions as metadata everywhere else in the
protocol: open by key, any JSON value allowed under a key including `null`, the
object itself absent or an object but never `null` on the wire, and the
`ag-ui` key (`AGUIMetadata.ReservedKey`) reserved. A resume entry is a request
field, so nothing merges into it; see
[Metadata](/concepts/metadata#resume-entries). For non-tool interrupts, the
hosting layer carries it onto `InterruptResponseContent.Metadata`, and
`AGUIChatClient` copies it from `InterruptResponseContent` onto the entry it
sends. Tool-approval entries are translated through MEAI's own approval
content types, which have no metadata surface — read it from the raw entry via
`RunAgentInput.Resume` if you need it there.

## Message Types

Messages form a closed hierarchy rooted at `AGUIMessage`. The base type carries
only the fields shared by every role: `Id`, `Role` and `Metadata`. Role-specific
properties such as `content`, `name`, `encryptedValue`, `toolCalls`, and
`toolCallId` are declared on the sealed role classes.

> [!NOTE]
>
> `Metadata` (`JsonElement?`, JSON field `metadata`) is carried by every message
> role and by `AGUIToolCall`, and is omitted from the tables below for brevity.
> It is open by key — any JSON value is allowed under a key, including `null` —
> and the object itself may be absent but is never `null`.
> `AGUIMetadata.ReservedKey` (`"ag-ui"`) is reserved for AG-UI's own use.
> Metadata accumulates as a message is built from its events, and tool call
> events accumulate onto the tool call itself; see
> [Metadata](/concepts/metadata) for the merge rules.

```csharp theme={null}
public abstract class AGUIMessage
{
    public string? Id { get; set; } // "id"
    public abstract string Role { get; } // "role"
    public JsonElement? Metadata { get; set; } // "metadata"
}
```

### Roles

The `Role` property returns one of the lowercase constants in `AGUIRoles`:

| Constant | JSON value |
| - | - |
| `AGUIRoles.Developer` | `developer` |
| `AGUIRoles.System` | `system` |
| `AGUIRoles.Assistant` | `assistant` |
| `AGUIRoles.User` | `user` |
| `AGUIRoles.Tool` | `tool` |
| `AGUIRoles.Activity` | `activity` |
| `AGUIRoles.Reasoning` | `reasoning` |

### AGUIDeveloperMessage

```csharp theme={null}
var message = new AGUIDeveloperMessage
{
    Id = "dev-1",
    Content = "Prefer concise answers.",
    Name = "policy"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Id` | `id` | `string?` | Message ID |
| `Role` | `role` | `"developer"` | Fixed role discriminator |
| `Content` | `content` | `string` | Developer instruction content |
| `Name` | `name` | `string?` | Optional sender name |
| `EncryptedValue` | `encryptedValue` | `string?` | Optional opaque encrypted value |

### AGUISystemMessage

```csharp theme={null}
var message = new AGUISystemMessage
{
    Id = "sys-1",
    Content = "You are a helpful assistant.",
    Name = "system"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Id` | `id` | `string?` | Message ID |
| `Role` | `role` | `"system"` | Fixed role discriminator |
| `Content` | `content` | `string` | System instruction content |
| `Name` | `name` | `string?` | Optional sender name |
| `EncryptedValue` | `encryptedValue` | `string?` | Optional opaque encrypted value |

### AGUIAssistantMessage

```csharp theme={null}
var message = new AGUIAssistantMessage
{
    Id = "asst-1",
    Content = "I can help with that.",
    ToolCalls =
    [
        new AGUIToolCall
        {
            Id = "call-1",
            Function = new AGUIToolCallFunction
            {
                Name = "get_weather",
                Arguments = """{"city":"Seattle"}"""
            }
        }
    ]
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Id` | `id` | `string?` | Message ID |
| `Role` | `role` | `"assistant"` | Fixed role discriminator |
| `Content` | `content` | `string?` | Optional assistant text |
| `Name` | `name` | `string?` | Optional assistant name |
| `EncryptedValue` | `encryptedValue` | `string?` | Optional opaque encrypted value |
| `ToolCalls` | `toolCalls` | `IList<AGUIToolCall>?` | Tool calls made in the message |

### AGUIUserMessage

`AGUIUserMessage.Content` is an `AGUIContent` value. It models the AG-UI
wire union `string | InputContent[]`.

```csharp theme={null}
var textOnly = new AGUIUserMessage
{
    Id = "user-1",
    Content = "Summarize this image."
};

AGUIInputContent textPart = new AGUITextInputContent
{
    Text = "What is shown here?"
};

AGUIInputContent imagePart = new AGUIImageInputContent
{
    Source = new AGUIInputContentUrlSource
    {
        Value = "https://example.com/screen.png",
        MimeType = "image/png"
    }
};

var multimodal = new AGUIUserMessage
{
    Id = "user-2",
    Content = [textPart, imagePart]
};
```

`AGUIContent` supports implicit conversions from `string`,
`List<AGUIInputContent>`, and `AGUIInputContent[]`. It also has a collection
builder, so C# collection expressions work. For reading, it implements
`IReadOnlyList<AGUIInputContent>`; a plain string is exposed as one
`AGUITextInputContent` part.

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Id` | `id` | `string?` | Message ID |
| `Role` | `role` | `"user"` | Fixed role discriminator |
| `Content` | `content` | `AGUIContent` | Plain text or ordered multimodal parts |
| `Name` | `name` | `string?` | Optional user name |
| `EncryptedValue` | `encryptedValue` | `string?` | Optional opaque encrypted value |

See [Multimodal Inputs](/sdk/dotnet/abstractions/multimodal-inputs) for the
`AGUIInputContent` hierarchy.

### AGUIToolMessage

```csharp theme={null}
var message = new AGUIToolMessage
{
    Id = "tool-msg-1",
    ToolCallId = "call-1",
    Content = """{"temperature":72}"""
};

// A result may also carry content parts — a document the tool returned, say.
var attachment = new AGUIToolMessage
{
    Id = "tool-msg-2",
    ToolCallId = "call-2",
    Content =
    [
        new AGUITextInputContent { Text = "Invoice attached." },
        new AGUIDocumentInputContent
        {
            Source = new AGUIInputContentUrlSource { Value = "https://example.com/INV-2291.pdf", MimeType = "application/pdf" },
        },
    ],
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Id` | `id` | `string?` | Message ID |
| `Role` | `role` | `"tool"` | Fixed role discriminator |
| `Content` | `content` | `AGUIContent` | Tool result: plain text or ordered content parts, as on the user message |
| `ToolCallId` | `toolCallId` | `string` | ID of the tool call this message answers |
| `Error` | `error` | `string?` | Optional error message |
| `EncryptedValue` | `encryptedValue` | `string?` | Optional opaque encrypted value |

### AGUIActivityMessage

```csharp theme={null}
var message = new AGUIActivityMessage
{
    Id = "activity-1",
    ActivityType = "PLAN",
    Content = JsonDocument.Parse("""{"status":"running"}""").RootElement.Clone()
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Id` | `id` | `string?` | Message ID |
| `Role` | `role` | `"activity"` | Fixed role discriminator |
| `ActivityType` | `activityType` | `string` | Activity discriminator for renderer selection |
| `Content` | `content` | `JsonElement` | Structured activity payload |

### AGUIReasoningMessage

```csharp theme={null}
var message = new AGUIReasoningMessage
{
    Id = "reasoning-1",
    Content = "Thinking through the problem..."
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Id` | `id` | `string?` | Message ID |
| `Role` | `role` | `"reasoning"` | Fixed role discriminator |
| `Content` | `content` | `string` | Reasoning text |
| `EncryptedValue` | `encryptedValue` | `string?` | Optional opaque encrypted value |

### AGUIToolCall

```csharp theme={null}
var call = new AGUIToolCall
{
    Id = "call-1",
    Type = "function",
    Function = new AGUIToolCallFunction
    {
        Name = "get_weather",
        Arguments = """{"city":"Seattle"}"""
    }
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Id` | `id` | `string` | Tool call ID |
| `Type` | `type` | `string` | Tool call type; defaults to `"function"` |
| `Function` | `function` | `AGUIToolCallFunction` | Function name and JSON-encoded arguments |
| `EncryptedValue` | `encryptedValue` | `string?` | Optional opaque encrypted value |

`AGUIToolCallFunction` has `Name` (`name`) and `Arguments` (`arguments`).

## Context

`AGUIContext` represents a piece of contextual information provided to an agent.

```csharp theme={null}
var context = new AGUIContext
{
    Description = "Current customer tier",
    Value = "enterprise"
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Description` | `description` | `string` | Description of what the context represents |
| `Value` | `value` | `string` | Context value |

## Tool

`AGUITool` defines a tool that an agent can call.

```csharp theme={null}
var tool = new AGUITool
{
    Name = "get_weather",
    Description = "Get the weather for a city",
    Parameters = JsonDocument.Parse("""
        {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
        """).RootElement.Clone(),
    Metadata = JsonDocument.Parse("""{"ui":"compact"}""").RootElement.Clone()
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Name` | `name` | `string` | Tool name |
| `Description` | `description` | `string?` | Optional tool description |
| `Parameters` | `parameters` | `JsonElement` | JSON Schema for the tool parameters |
| `Metadata` | `metadata` | `JsonElement?` | Optional arbitrary tool metadata |

## State

State is represented as `JsonElement?` on `RunAgentInput.State` and as
`JsonElement` payloads in `StateSnapshotEvent` and `StateDeltaEvent`.

```csharp theme={null}
input.State = JsonDocument.Parse("""{"draft":"hello"}""").RootElement.Clone();
```

The schema of the state is defined by the agent. The protocol only carries it.

## AgentCapabilities

`AgentCapabilities` is a structured declaration that an agent can expose so
clients can discover what it supports. All fields are optional.

```csharp theme={null}
var capabilities = new AgentCapabilities
{
    Identity = new IdentityCapabilities
    {
        Name = "Support Agent",
        Version = "1.0.0"
    },
    Transport = new TransportCapabilities
    {
        Streaming = true,
        Resumable = true
    },
    Tools = new ToolsCapabilities
    {
        Supported = true,
        ClientProvided = true
    },
    Multimodal = new MultimodalCapabilities
    {
        Input = new MultimodalInputCapabilities
        {
            Image = true,
            Audio = true,
            Pdf = true
        }
    }
};
```

| C# property | JSON field | Type | Description |
| - | - | - | - |
| `Identity` | `identity` | `IdentityCapabilities?` | Agent identity and metadata |
| `Transport` | `transport` | `TransportCapabilities?` | Streaming, websocket, binary, push, and resumability support |
| `Tools` | `tools` | `ToolsCapabilities?` | Tool support and tool-calling configuration |
| `Output` | `output` | `OutputCapabilities?` | Structured output and supported MIME types |
| `State` | `state` | `StateCapabilities?` | Snapshot, delta, memory, and persistence support |
| `MultiAgent` | `multiAgent` | `MultiAgentCapabilities?` | Delegation, handoffs, and sub-agent information |
| `Reasoning` | `reasoning` | `ReasoningCapabilities?` | Reasoning, streaming, and encrypted reasoning support |
| `Multimodal` | `multimodal` | `MultimodalCapabilities?` | Multimodal input and output support |
| `Execution` | `execution` | `ExecutionCapabilities?` | Code execution and iteration/time limits |
| `HumanInTheLoop` | `humanInTheLoop` | `HumanInTheLoopCapabilities?` | Approvals, interventions, feedback, interrupts, and approve-with-edits |
| `Custom` | `custom` | `JsonElement?` | Integration-specific capabilities, open by key; build it with `JsonSerializer.SerializeToElement(...)` |

See [Capabilities](/concepts/capabilities) for protocol-level concepts and
usage patterns.

## Serialization

All protocol types are registered in `AGUIJsonSerializerContext`, a
source-generated `JsonSerializerContext`. Use it when serializing protocol
types in AOT-sensitive code.

```csharp theme={null}
var json = JsonSerializer.Serialize(
    input,
    AGUIJsonSerializerContext.Default.RunAgentInput);
```


# AGUIChatClient
Source: https://docs.ag-ui.com/sdk/dotnet/client/chat-client

IChatClient implementation for consuming AG-UI endpoints

# AGUIChatClient

`AGUIChatClient` is an `IChatClient` implementation for AG-UI. It converts
`ChatMessage` values and `ChatOptions` into a `RunAgentInput`, sends that input
to an AG-UI endpoint, and converts the returned event stream into
`ChatResponseUpdate` values.

```csharp theme={null}
using AGUI.Client;
using Microsoft.Extensions.AI;
```

> [!NOTE]
>
> The .NET client does not define an `AbstractAgent` equivalent. The integration
> point is `Microsoft.Extensions.AI.IChatClient`.

## Construction

Create a client from an `AGUIChatClientOptions`. The simplest form builds the
built-in HTTP transport from an `HttpClient` and the AG-UI endpoint URL:

```csharp theme={null}
using AGUI.Client;
using Microsoft.Extensions.AI;

HttpClient httpClient = new();
IChatClient client = new AGUIChatClient(new(httpClient, "https://api.example.com/agent"));
```

`AGUIChatClient` has a single constructor that takes `AGUIChatClientOptions`:

```csharp theme={null}
new AGUIChatClient(AGUIChatClientOptions options);
```

`AGUIChatClientOptions` carries the transport and optional serializer settings:

```csharp theme={null}
public sealed class AGUIChatClientOptions
{
    public AGUIChatClientOptions();
    public AGUIChatClientOptions(HttpClient httpClient, string endpoint); // builds the HTTP transport
    public required IAGUITransport Transport { get; init; }
    public JsonSerializerOptions? JsonSerializerOptions { get; init; }
}
```

Set `Transport` directly when you need a custom transport for tests or an
alternative wire protocol. See [Transport](/sdk/dotnet/client/transport).
Configured `JsonSerializerOptions` are also used when converting MEAI message
content, including custom CLR values in `AIContent.AdditionalProperties`.

## Streaming responses

`GetStreamingResponseAsync` streams AG-UI output as MEAI
`ChatResponseUpdate` objects:

```csharp theme={null}
using AGUI.Client;
using Microsoft.Extensions.AI;

using HttpClient httpClient = new();
IChatClient client = new AGUIChatClient(new(httpClient, "https://api.example.com/agent"));

List<ChatMessage> messages =
[
    new(ChatRole.User, "Explain AG-UI in one paragraph"),
];

await foreach (ChatResponseUpdate update in client.GetStreamingResponseAsync(
    messages,
    options: null,
    cancellationToken: CancellationToken.None))
{
    if (!string.IsNullOrEmpty(update.Text))
    {
        Console.Write(update.Text);
    }
}
```

Internally, the client converts the AG-UI event stream back into
`ChatResponseUpdate` objects. Text events become text deltas, tool call events
become MEAI tool call content, and lifecycle events remain available through
`RawRepresentation`.

## Non-streaming responses

`GetResponseAsync` is also implemented. It consumes the streaming response and
returns a final `ChatResponse`:

```csharp theme={null}
ChatResponse response = await client.GetResponseAsync(
    messages,
    cancellationToken: CancellationToken.None);

Console.WriteLine(response.Text);
```

## Statelessness and ConversationId

`AGUIChatClient` is stateless. It sends the full message history on every turn
and never surfaces a `ConversationId` on returned updates.

This is intentional. In `Microsoft.Extensions.AI`, a non-null `ConversationId`
signals a service-managed conversation. Agent wrappers may then send only the
new message deltas on the next turn. That would truncate history when talking to
a stateless AG-UI server.

Use these identifiers instead:

* `ChatResponseUpdate.ResponseId` is the AG-UI run id.
* `update.RawRepresentation as RunStartedEvent` exposes the AG-UI `ThreadId`
  and `RunId` from the `RUN_STARTED` event.
* `update.AdditionalProperties["agui_thread_id"]` also contains the resolved
  AG-UI thread id on the `RUN_STARTED` update.

```csharp theme={null}
using AGUI.Abstractions;
using Microsoft.Extensions.AI;

static (string? ThreadId, string? RunId) GetAGUIIds(
    IEnumerable<ChatResponseUpdate> updates)
{
    RunStartedEvent? started = updates
        .Select(update => update.RawRepresentation)
        .OfType<RunStartedEvent>()
        .FirstOrDefault();

    return (started?.ThreadId, started?.RunId);
}
```

> [!WARNING]
>
> Do not use `ConversationId` as AG-UI conversation state. Pass full message
> history each turn and use AG-UI thread/run ids for wire-level correlation.

## Thread continuity

To keep a stable AG-UI thread, reuse the same `ChatOptions` instance across
turns. The client pins the resolved thread id onto that options instance without
setting `ConversationId`.

For explicit continuation or branching, set `RunAgentInput.ThreadId` and
`RunAgentInput.ParentRunId` through `ChatOptions.RawRepresentationFactory`.
This is the AG-UI-native way to control wire-level fields:

```csharp theme={null}
using AGUI.Abstractions;
using Microsoft.Extensions.AI;

List<ChatResponseUpdate> firstTurn = [];
await foreach (ChatResponseUpdate update in client.GetStreamingResponseAsync(
    [new ChatMessage(ChatRole.User, "Hello, tell me about serialization")],
    cancellationToken: CancellationToken.None))
{
    firstTurn.Add(update);
    Console.Write(update.Text);
}

RunStartedEvent? runStarted = firstTurn
    .Select(update => update.RawRepresentation)
    .OfType<RunStartedEvent>()
    .FirstOrDefault();

ChatOptions followUpOptions = new()
{
    RawRepresentationFactory = _ => new RunAgentInput
    {
        ThreadId = runStarted?.ThreadId ?? string.Empty,
        ParentRunId = runStarted?.RunId,
    },
};

await foreach (ChatResponseUpdate update in client.GetStreamingResponseAsync(
    [new ChatMessage(ChatRole.User, "Tell me more about event compaction")],
    followUpOptions,
    CancellationToken.None))
{
    Console.Write(update.Text);
}
```

> [!TIP]
>
> Use `ParentRunId` when you want the next request to branch from a previous
> run. Omit it when you only need to continue on the same thread.

## Interrupts and approvals

When an AG-UI server finishes a run with an interrupt outcome, the client
surfaces the pause as MEAI content:

* Tool-call approvals become `ToolApprovalRequestContent`.
* Other interrupts become `InterruptRequestContent`.

The caller appends a response message and sends the next request. The client
extracts `ToolApprovalResponseContent` and `InterruptResponseContent` from the
latest message and sends them as `RunAgentInput.Resume`.

```csharp theme={null}
using AGUI.Abstractions;
using Microsoft.Extensions.AI;

List<ChatMessage> messages =
[
    new(ChatRole.User, "Delete the generated files"),
];

ChatResponse firstResponse = await client.GetResponseAsync(
    messages,
    cancellationToken: CancellationToken.None);

ToolApprovalRequestContent? approval = firstResponse.Messages
    .SelectMany(message => message.Contents)
    .OfType<ToolApprovalRequestContent>()
    .FirstOrDefault();

if (approval?.ToolCall is FunctionCallContent toolCall)
{
    messages.AddRange(firstResponse.Messages);
    messages.Add(new ChatMessage(ChatRole.User,
    [
        new ToolApprovalResponseContent(approval.RequestId, approved: true, toolCall),
    ]));

    ChatResponse resumed = await client.GetResponseAsync(
        messages,
        cancellationToken: CancellationToken.None);

    Console.WriteLine(resumed.Text);
}
```

For non-tool interrupts, respond with `InterruptResponseContent`:

```csharp theme={null}
using System.Text.Json;
using AGUI.Abstractions;
using Microsoft.Extensions.AI;

static ChatMessage CreateInterruptResponse(InterruptRequestContent request)
{
    using JsonDocument payload = JsonDocument.Parse("""{"approved":true}""");

    return new ChatMessage(ChatRole.User,
    [
        new InterruptResponseContent(request.RequestId)
        {
            Payload = payload.RootElement.Clone(),
        },
    ]);
}
```

`InterruptResponseContent.Metadata` optionally carries envelope data about the
response — a signature proving the decision was not tampered with, routing keys
— as opposed to `Payload`, which is the answer the agent asked for. The client
copies it onto the resume entry's `metadata`, and the hosting layer hands it
back to the server pipeline on `InterruptResponseContent`; see
[Metadata](/concepts/metadata#resume-entries).

```csharp theme={null}
new InterruptResponseContent(request.RequestId)
{
    Payload = payload.RootElement.Clone(),
    Metadata = JsonDocument.Parse(
        """{"definitionId":"review-plan","key":"afterModel-review"}""")
        .RootElement.Clone(),
}
```

## Related references

* [Transport](/sdk/dotnet/client/transport)
* [Events](/sdk/dotnet/abstractions/events)
* [Core protocol types](/sdk/dotnet/abstractions/types)


# Overview
Source: https://docs.ag-ui.com/sdk/dotnet/client/overview

Client package overview

# AGUI.Client

The AG-UI .NET Client SDK adapts an AG-UI endpoint to the standard
`Microsoft.Extensions.AI.IChatClient` abstraction. Instead of introducing a new
agent base class, `AGUI.Client` lets .NET applications consume an AG-UI server
the same way they consume any other chat model.

```bash theme={null}
dotnet add package AGUI.Client
```

> [!NOTE]
>
> If you already use `Microsoft.Extensions.AI`, an AG-UI server is just another
> `IChatClient`.

## AGUIChatClient

`AGUIChatClient` is the primary type in this package. It wraps an AG-UI
HTTP+SSE endpoint and exposes both `GetStreamingResponseAsync` and
`GetResponseAsync` from `IChatClient`.

* [Construction](/sdk/dotnet/client/chat-client#construction) - Create a client
  from `HttpClient` and an endpoint, or from a custom transport
* [Streaming](/sdk/dotnet/client/chat-client#streaming-responses) - Consume
  AG-UI events as `ChatResponseUpdate` values
* [Stateless behavior](/sdk/dotnet/client/chat-client#statelessness-and-conversationid) -
  Send full message history on every turn
* [Thread continuity](/sdk/dotnet/client/chat-client#thread-continuity) - Keep a
  stable thread or branch from a previous run
* [Interrupts and approvals](/sdk/dotnet/client/chat-client#interrupts-and-approvals) -
  Handle server pauses with standard MEAI content types

> [card] [AGUIChatClient Reference](/sdk/dotnet/client/chat-client)
>
> Consume an AG-UI endpoint through the Microsoft.Extensions.AI IChatClient API

## Transport

The client package includes a small transport abstraction for sending
`RunAgentInput` requests and receiving AG-UI event streams. The default path
uses HTTP POST and Server-Sent Events; custom transports are useful for tests or
non-HTTP environments.

* [IAGUITransport](/sdk/dotnet/client/transport#iaguitransport) - The transport
  interface used by `AGUIChatClient`
* [HTTP transport](/sdk/dotnet/client/transport#http-transport) - Built-in
  HTTP+SSE behavior
* [Custom transports](/sdk/dotnet/client/transport#custom-transports) - Plug in
  an in-memory or alternative wire protocol

> [card] [Transport Reference](/sdk/dotnet/client/transport)
>
> Understand the AG-UI client transport contract and HTTP event stream

## Stateless by design

AG-UI endpoints are stateless from the .NET client's perspective. Each request
sends the full message history, and returned `ChatResponseUpdate` objects do not
surface a `ConversationId`. Updates are correlated by `ResponseId`, which maps
to the AG-UI run id. The AG-UI thread id is available from the `RUN_STARTED`
event and as `AdditionalProperties["agui_thread_id"]`.

For the protocol types carried over the wire, see the
[.NET event reference](/sdk/dotnet/abstractions/events).

## Client verification

Client tests protect the conversion between `Microsoft.Extensions.AI` and
AG-UI. They verify that `ChatMessage` history becomes AG-UI messages,
`ChatOptions.Tools` becomes AG-UI tools, caller-supplied AG-UI context,
forwarded properties, and resume payloads are preserved, and `RUN_ERROR`
events become MEAI `ErrorContent` updates.

They also protect the stateless conversation contract: thread and run
identifiers are preserved through AG-UI fields, returned updates clear
`ConversationId`, and server-side tool calls are marked informational so the
.NET client does not execute them locally.

```bash theme={null}
cd sdks/dotnet
dotnet test tests/AGUI.Client.UnitTests/
dotnet test tests/AGUI.CrossLanguage.IntegrationTests/
```


# Transport
Source: https://docs.ag-ui.com/sdk/dotnet/client/transport

AG-UI client transport abstraction and HTTP event stream

# Transport

`AGUI.Client` separates the chat client from the wire protocol with
`IAGUITransport`. `AGUIChatClient` builds a `RunAgentInput`, passes it to the
transport, and consumes the resulting AG-UI `BaseEvent` stream.

```csharp theme={null}
using AGUI.Abstractions;
using AGUI.Client;
```

## IAGUITransport

`IAGUITransport` has a single method:

```csharp theme={null}
public interface IAGUITransport
{
    IAsyncEnumerable<BaseEvent> SendAsync(
        RunAgentInput input,
        CancellationToken cancellationToken);
}
```

The input contains the AG-UI thread id, run id, message history, tools, state,
context, forwarded properties, and any resume entries for interrupted runs. The
output is the ordered AG-UI event stream described in the
[event reference](/sdk/dotnet/abstractions/events).

## HTTP transport

The `AGUIChatClientOptions(HttpClient, endpoint)` constructor creates the
built-in HTTP transport internally:

```csharp theme={null}
using AGUI.Client;
using Microsoft.Extensions.AI;

using HttpClient httpClient = new();
IChatClient client = new AGUIChatClient(new(httpClient, "https://api.example.com/agent"));
```

The built-in transport sends the request as an HTTP `POST` whose body is the
serialized `RunAgentInput`. The response is read as Server-Sent Events, and each
SSE item is deserialized as a `BaseEvent`.

> [!NOTE]
>
> `AGUIHttpTransport` is the built-in HTTP+SSE implementation used by the
> `AGUIChatClientOptions(HttpClient, endpoint)` constructor. Most applications do
> not need to instantiate a transport directly.

## Custom transports

Implement `IAGUITransport` when you want to test without a server or use a
different transport. Then pass the implementation to `AGUIChatClient`.

```csharp theme={null}
using System.Runtime.CompilerServices;
using AGUI.Abstractions;
using AGUI.Client;
using Microsoft.Extensions.AI;

public sealed class InMemoryAGUITransport : IAGUITransport
{
    public List<RunAgentInput> Requests { get; } = [];

    public async IAsyncEnumerable<BaseEvent> SendAsync(
        RunAgentInput input,
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        Requests.Add(input);
        await Task.Yield();

        string threadId = string.IsNullOrEmpty(input.ThreadId) ? "thread_1" : input.ThreadId;
        string runId = string.IsNullOrEmpty(input.RunId) ? "run_1" : input.RunId;

        yield return new RunStartedEvent { ThreadId = threadId, RunId = runId, ProtocolVersion = AGUIProtocol.Version };
        yield return new TextMessageStartEvent { MessageId = "msg_1", Role = AGUIRoles.Assistant };
        yield return new TextMessageContentEvent { MessageId = "msg_1", Delta = "Hello from AG-UI" };
        yield return new TextMessageEndEvent { MessageId = "msg_1" };
        yield return new RunFinishedEvent { ThreadId = threadId, RunId = runId };
    }
}

IAGUITransport transport = new InMemoryAGUITransport();
IChatClient client = new AGUIChatClient(new() { Transport = transport });
```

## Event conversion

The transport returns AG-UI protocol events. `AGUIChatClient` then converts them
to `ChatResponseUpdate` values:

* `RUN_STARTED` establishes the AG-UI thread id and run id.
* Text message events become streamed text updates.
* Tool call events become MEAI function call content.
* Interrupt outcomes become `ToolApprovalRequestContent` or
  `InterruptRequestContent`.
* `RUN_ERROR` becomes an `ErrorContent` update. Its `message` maps to
  `ErrorContent.Message`, and its optional `code` maps to
  `ErrorContent.ErrorCode`. When the event carries partial `usage`, the client
  also emits `UsageContent` updates so `ChatResponse.Usage` includes the tokens
  consumed before the failure.

`ResponseId` on each update corresponds to the AG-UI run id. The client clears
`ConversationId` before yielding updates so callers continue sending full
message history to stateless AG-UI servers.

## Cancellation

`SendAsync` receives the caller's `CancellationToken`. Custom transports should
observe it while sending the request and while producing events:

```csharp theme={null}
public async IAsyncEnumerable<BaseEvent> SendAsync(
    RunAgentInput input,
    [EnumeratorCancellation] CancellationToken cancellationToken)
{
    cancellationToken.ThrowIfCancellationRequested();

    await Task.Delay(TimeSpan.FromMilliseconds(10), cancellationToken);
    yield return new RunStartedEvent
    {
        ThreadId = input.ThreadId,
        RunId = input.RunId,
        ProtocolVersion = AGUIProtocol.Version,
    };

    cancellationToken.ThrowIfCancellationRequested();
    yield return new RunFinishedEvent { ThreadId = input.ThreadId, RunId = input.RunId };
}
```

## Related references

* [AGUIChatClient](/sdk/dotnet/client/chat-client)
* [Events](/sdk/dotnet/abstractions/events)
* [Core protocol types](/sdk/dotnet/abstractions/types)


# Endpoints
Source: https://docs.ag-ui.com/sdk/dotnet/hosting/endpoints

Host an IChatClient as an AG-UI endpoint

# Endpoints

An AG-UI endpoint is a normal ASP.NET Core POST endpoint. It receives a
`RunAgentInput`, calls an `IChatClient`, converts the streamed response to AG-UI
events, and returns Server-Sent Events.

## Register AG-UI services

Call `AddAGUI()` during startup. It configures ASP.NET Core JSON options with
the AG-UI source-generated serializer context and registers interrupt content
types used by the `IChatClient` pipeline.

```csharp theme={null}
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAGUI();
// Register your Microsoft.Extensions.AI IChatClient here.

var app = builder.Build();

app.MapAGUI("/");

app.Run();
```

## Endpoint pattern

Every AG-UI endpoint follows the same five steps.

**1. Receive RunAgentInput**

Map a POST endpoint that receives `[FromBody] RunAgentInput`.

**2. Create ChatRequestContext**

Call `input.ToChatRequestContext(jsonSerializerOptions, streamOptions?)`.
The returned context exposes `ctx.Messages` and `ctx.ChatOptions`.

**3. Call the IChatClient**

Pass `ctx.Messages` and `ctx.ChatOptions` to
`chatClient.GetStreamingResponseAsync(...)`.

**4. Convert to AG-UI events**

Pipe the `ChatResponseUpdate` stream through
`.AsAGUIEventStreamAsync(ctx, cancellationToken)`.

**5. Return Server-Sent Events**

Return `TypedResults.ServerSentEvents(WrapAsSseItems(events, ct))`.

## Minimal endpoint

This is the canonical endpoint shape used by the .NET samples.

```csharp theme={null}
using System.Net.ServerSentEvents;
using System.Runtime.CompilerServices;
using AGUI.Abstractions;
using AGUI.Server;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Routing;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Options;

using JsonOptions = Microsoft.AspNetCore.Http.Json.JsonOptions;

namespace MyAgent.Server;

internal static class AGUIEndpoint
{
    internal static IEndpointConventionBuilder MapAGUI(
        this IEndpointRouteBuilder endpoints,
        string pattern)
    {
        return endpoints.MapPost(pattern, (
            [FromBody] RunAgentInput input,
            [FromServices] IChatClient chatClient,
            [FromServices] IOptions<JsonOptions> jsonOptions,
            CancellationToken cancellationToken) =>
        {
            var jsonSerializerOptions = jsonOptions.Value.SerializerOptions;

            var ctx = input.ToChatRequestContext(jsonSerializerOptions);

            var updates = chatClient.GetStreamingResponseAsync(
                ctx.Messages,
                ctx.ChatOptions,
                cancellationToken);

            var events = updates.AsAGUIEventStreamAsync(ctx, cancellationToken);

            return TypedResults.ServerSentEvents(
                WrapAsSseItems(events, cancellationToken));
        });
    }

    private static async IAsyncEnumerable<SseItem<BaseEvent>> WrapAsSseItems(
        IAsyncEnumerable<BaseEvent> events,
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        await foreach (var evt in events
            .WithCancellation(cancellationToken)
            .ConfigureAwait(false))
        {
            yield return new SseItem<BaseEvent>(evt);
        }
    }
}
```

## Key APIs

### ToChatRequestContext

`ToChatRequestContext` adapts the AG-UI request to the
`Microsoft.Extensions.AI` request shape.

```csharp theme={null}
var ctx = input.ToChatRequestContext(jsonSerializerOptions);
```

`ChatRequestContext` contains:

* `ctx.Input` - the original `RunAgentInput`
* `ctx.Messages` - converted `List<ChatMessage>`
* `ctx.ChatOptions` - configured `ChatOptions`

The original input is also available to downstream chat clients and tools at
`ctx.ChatOptions.AdditionalProperties[AGUIConstants.RunAgentInputKey]`.

> [!TIP]
>
> Client-tool and approval-flow routing happens automatically. Client-declared
> tools from `RunAgentInput.Tools` are installed on `ctx.ChatOptions.Tools` and
> routed through the approval pipeline.

### AsAGUIEventStreamAsync

`AsAGUIEventStreamAsync` converts streamed `ChatResponseUpdate` values into
AG-UI `BaseEvent` values.

```csharp theme={null}
var events = updates.AsAGUIEventStreamAsync(ctx, cancellationToken);
```

It emits run lifecycle events, maps text content to `TEXT_MESSAGE_*` events,
maps `FunctionCallContent` and `FunctionResultContent` to tool events, maps
`TextReasoningContent` to reasoning events, and passes through any `BaseEvent`
stored in `ChatResponseUpdate.RawRepresentation`.

### WrapAsSseItems

ASP.NET Core's `TypedResults.ServerSentEvents` writes `SseItem<T>` values. The
small helper wraps each AG-UI event in `SseItem<BaseEvent>`.

```csharp theme={null}
return TypedResults.ServerSentEvents(
    WrapAsSseItems(events, cancellationToken));
```

## Adding stream options

Pass `AGUIStreamOptions` when the endpoint needs custom stream conversion.

```csharp theme={null}
var streamOptions = new AGUIStreamOptions()
    .MapResultAsStateSnapshot("write_document");

var ctx = input.ToChatRequestContext(jsonSerializerOptions, streamOptions);
```

See [Extensibility](/sdk/dotnet/hosting/extensibility) for the available
mapping hooks.


# Extensibility
Source: https://docs.ag-ui.com/sdk/dotnet/hosting/extensibility

Customize AG-UI stream conversion with AGUIStreamOptions

# Extensibility

`AGUIStreamOptions` customizes how `ChatResponseUpdate` streams are converted
to AG-UI events. It is fluent and method-only: create an instance, register
`Map*` hooks, and pass it to `ToChatRequestContext`.

```csharp theme={null}
var streamOptions = new AGUIStreamOptions()
    .MapResultAsStateSnapshot("create_plan");

var ctx = input.ToChatRequestContext(jsonSerializerOptions, streamOptions);
```

Use stream options when your server needs to surface framework-specific content
types, custom interrupts, state updates, or streaming tool-argument previews.

## Built-in conversion

You do not need stream options for the common path. The hosting layer already
maps:

* `TextContent` to `TEXT_MESSAGE_*`
* `TextReasoningContent` to `REASONING_*`
* `FunctionCallContent` to `TOOL_CALL_*`
* `FunctionResultContent` to `TOOL_CALL_RESULT`
* `ToolApprovalRequestContent` and `InterruptRequestContent` to interrupt
  outcomes
* `ChatResponseUpdate.RawRepresentation` containing a `BaseEvent` directly to
  that event

> [!NOTE]
>
> If a `ChatResponseUpdate.RawRepresentation` is a `BaseEvent`, the hosting
> layer emits it verbatim. This is often the simplest way for a custom
> `IChatClient` wrapper to inject `StateSnapshotEvent`, `CustomEvent`, or
> `RawEvent` values.

## MapContent

`MapContent(Func<AIContent, IEnumerable<BaseEvent>?> mapper)` receives an
otherwise-unmapped `AIContent` and returns AG-UI events to emit. Return `null`
to let the next mapper try the content.

```csharp theme={null}
using AGUI.Abstractions;
using AGUI.Server;
using Microsoft.Extensions.AI;

public sealed class WorkflowStepContent : AIContent
{
    public string StepName { get; set; } = string.Empty;
}

var streamOptions = new AGUIStreamOptions()
    .MapContent(content =>
        content is WorkflowStepContent step
            ? [new StepStartedEvent { StepName = step.StepName }]
            : null);
```

Use this for framework-specific content types such as workflow markers,
progress notifications, or domain events.

> [!TIP]
>
> `TextReasoningContent` is already handled natively. The Step 07 sample emits
> `TextReasoningContent`, and the hosting layer converts it to reasoning events
> without custom `MapContent` configuration.

## MapInterrupt

`MapInterrupt(Func<AIContent, AGUIInterrupt?> mapper)` receives an
otherwise-unmapped `AIContent` and returns an `AGUIInterrupt` when the run needs
user input. The hosting layer emits `RunFinishedEvent` with an interrupt
outcome and stops the run. Return `null` to continue to the next mapper or to
`MapContent`.

```csharp theme={null}
using AGUI.Abstractions;
using AGUI.Server;
using Microsoft.Extensions.AI;

public sealed class ConfirmationRequiredContent : AIContent
{
    public string RequestId { get; set; } = string.Empty;

    public string Message { get; set; } = string.Empty;
}

var streamOptions = new AGUIStreamOptions()
    .MapInterrupt(content =>
        content is ConfirmationRequiredContent confirmation
            ? new AGUIInterrupt
            {
                Id = confirmation.RequestId,
                Reason = InterruptReasons.Confirmation,
                Message = confirmation.Message,
            }
            : null);
```

Use this for custom human-in-the-loop content that is not represented by the
built-in `InterruptRequestContent` or tool approval content.

## MapCall

`MapCall(string toolName, Func<FunctionCallContent, IEnumerable<BaseEvent>>
mapper)` receives a matching `FunctionCallContent` and emits extra events after
the normal tool call start, args, and end events.

```csharp theme={null}
using System.Text.Json;
using AGUI.Abstractions;
using AGUI.Server;

string? lastDocument = null;

var streamOptions = new AGUIStreamOptions()
    .MapCall("write_document", call =>
    {
        var document = call.Arguments?.TryGetValue("document", out var value) == true
            ? value?.ToString()
            : null;

        if (string.IsNullOrEmpty(document) || document == lastDocument)
        {
            return [];
        }

        lastDocument = document;

        var snapshot = JsonSerializer.SerializeToElement(new
        {
            document
        });

        return [new StateSnapshotEvent { Snapshot = snapshot }];
    });
```

Use this for streaming tool-argument previews. For example, while a model is
building arguments for `write_document`, the UI can update a live document
preview before the server-side tool finishes.

## MapResult

`MapResult(string toolName, Func<FunctionResultContent,
IEnumerable<BaseEvent>> mapper)` receives a matching tool result and emits
extra events after the normal `ToolCallResultEvent`.

```csharp theme={null}
using System.Text.Json;
using AGUI.Abstractions;
using AGUI.Server;

var streamOptions = new AGUIStreamOptions()
    .MapResult("save_recipe", result =>
    {
        var snapshot = JsonSerializer.SerializeToElement(new
        {
            saved = true,
            recipe = result.Result,
        });

        return
        [
            new StateSnapshotEvent { Snapshot = snapshot },
            new CustomEvent
            {
                Name = "recipe.saved",
                Value = snapshot,
            },
        ];
    });
```

Use this when a server-side tool result should also update state, activity, or
application-specific UI.

## State mapping helpers

Two convenience methods cover the common state-management cases:

```csharp theme={null}
var streamOptions = new AGUIStreamOptions()
    .MapResultAsStateSnapshot("create_plan")
    .MapResultAsStateDelta("update_plan_step");
```

* `MapResultAsStateSnapshot(toolName)` emits a `StateSnapshotEvent`
* `MapResultAsStateDelta(toolName)` emits a `StateDeltaEvent`

Both helpers expect `FunctionResultContent.Result` to be a `JsonElement`. If
your tool returns another type, use `MapResult` and serialize the value
yourself.

## RawRepresentation pass-through

For custom `IChatClient` wrappers, setting `RawRepresentation` to an AG-UI
event is often simpler than defining a new `AIContent` type.

```csharp theme={null}
using System.Text.Json;
using AGUI.Abstractions;
using Microsoft.Extensions.AI;

var state = JsonSerializer.SerializeToElement(new
{
    status = "ready"
});

yield return new ChatResponseUpdate
{
    RawRepresentation = new StateSnapshotEvent
    {
        Snapshot = state,
    },
};
```

The converter emits the `StateSnapshotEvent` directly. If the raw event appears
before a run has started, the hosting layer emits `RUN_STARTED` first.

## Chaining

You can register multiple `MapContent` or `MapInterrupt` callbacks. They are
tried in registration order, and the first non-null result wins.

```csharp theme={null}
var streamOptions = new AGUIStreamOptions()
    .MapInterrupt(TryMapConfirmation)
    .MapInterrupt(TryMapInputRequest)
    .MapContent(TryMapWorkflowStep)
    .MapContent(TryMapProgress);
```

Keep mappings small and focused. Use the built-in conversion for standard text,
reasoning, tools, and interrupts, then add stream options only for the events
that are specific to your server.


# Overview
Source: https://docs.ag-ui.com/sdk/dotnet/hosting/overview

Server adapter package overview

# AGUI.Server

`AGUI.Server` is the .NET server-side adapter for AG-UI. It converts a
`Microsoft.Extensions.AI.IChatClient` stream into AG-UI protocol events, so you
can expose any chat client as an AG-UI endpoint that accepts `RunAgentInput` and
streams AG-UI events to a frontend UI.

```bash theme={null}
dotnet add package AGUI.Server
```

## The core idea

You do not learn a new agent programming model. You host an `IChatClient`.

The package adapts AG-UI request bodies into `Microsoft.Extensions.AI`
messages and options, calls your chat client, then converts the streamed
`ChatResponseUpdate` values back into AG-UI protocol events.

## What it depends on

`AGUI.Server` is intentionally small:

* [AG-UI protocol types](/sdk/dotnet/abstractions/events) from
  `AGUI.Abstractions`
* `Microsoft.Extensions.AI.Abstractions`

It is framework-agnostic: it does not depend on ASP.NET Core or any web
framework. You host the adapter inside the web framework of your choice (the
samples and docs use ASP.NET Core). It also does not depend on the .NET AG-UI
client package. The server and client packages share protocol types, but remain
independent.

> [!NOTE]
>
> The server package targets `net10.0`, `net9.0`, and `net8.0`.

## What the hosting layer handles

The hosting layer handles the protocol details for you:

* Converts `RunAgentInput.Messages` into `ChatMessage` values
* Translates `RunAgentInput.Resume` into MEAI approval and interrupt response
  content, carrying payload — and, for non-tool interrupts, metadata — onto
  `InterruptResponseContent`
* Installs client-declared tools on `ChatOptions`
* Stores the original input under
  `ChatOptions.AdditionalProperties[AGUIConstants.RunAgentInputKey]`
* Emits `RUN_STARTED` and terminal `RUN_FINISHED` outcomes
* Maps text, reasoning, tool calls, tool results, state, raw events, and
  interrupts to AG-UI events
* Streams the result as Server-Sent Events

## Verification and framework ownership

Server tests verify that `RunAgentInput` becomes `ChatMessage` and
`ChatOptions`, resume payloads become standard MEAI response content, lifecycle
events are emitted, and streamed `ChatResponseUpdate` values become the
expected text, reasoning, tool, state, raw, custom, and interrupt events. Raw
AG-UI events, including `RUN_ERROR`, pass through when supplied on
`ChatResponseUpdate.RawRepresentation`.

```bash theme={null}
cd sdks/dotnet
dotnet test tests/AGUI.Server.UnitTests/
dotnet test tests/AGUI.Hosting.AspNetCore.IntegrationTests/
```

The SDK owns the shared AG-UI and `Microsoft.Extensions.AI` bridge.
Framework-specific mappings belong to the consuming framework. For example,
Microsoft Agent Framework can use `AGUI.Server` for the common bridge, then map
its own workflow, step, and agent events with `AGUIStreamOptions` or raw AG-UI
events.

## Server and client together

Use `AGUI.Server` when you are building an AG-UI server. Use
[AGUI.Client](/sdk/dotnet/client/overview) when .NET code needs to consume an
AG-UI endpoint as an `IChatClient`.

> [card] [Endpoints](/sdk/dotnet/hosting/endpoints)
>
> Build the canonical ASP.NET Core AG-UI endpoint

> [card] [Extensibility](/sdk/dotnet/hosting/extensibility)
>
> Customize stream conversion with AGUIStreamOptions


# Events
Source: https://docs.ag-ui.com/sdk/python/core/events

Documentation for the events used in the Agent User Interaction Protocol Python SDK

# Events

The Agent User Interaction Protocol Python SDK uses a streaming event-based
architecture. Events are the fundamental units of communication between agents
and the frontend. This section documents the event types and their properties.

## EventType Enum

`from ag_ui.core import EventType`

The `EventType` enum defines all possible event types in the system:

```python theme={null}
class EventType(str, Enum):
    TEXT_MESSAGE_START = "TEXT_MESSAGE_START"
    TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT"
    TEXT_MESSAGE_END = "TEXT_MESSAGE_END"
    TOOL_CALL_START = "TOOL_CALL_START"
    TOOL_CALL_ARGS = "TOOL_CALL_ARGS"
    TOOL_CALL_END = "TOOL_CALL_END"
    TOOL_CALL_RESULT = "TOOL_CALL_RESULT"
    STATE_SNAPSHOT = "STATE_SNAPSHOT"
    STATE_DELTA = "STATE_DELTA"
    MESSAGES_SNAPSHOT = "MESSAGES_SNAPSHOT"
    ACTIVITY_SNAPSHOT = "ACTIVITY_SNAPSHOT"
    ACTIVITY_DELTA = "ACTIVITY_DELTA"
    RAW = "RAW"
    CUSTOM = "CUSTOM"
    RUN_STARTED = "RUN_STARTED"
    RUN_FINISHED = "RUN_FINISHED"
    RUN_ERROR = "RUN_ERROR"
    STEP_STARTED = "STEP_STARTED"
    STEP_FINISHED = "STEP_FINISHED"
    REASONING_START = "REASONING_START"
    REASONING_MESSAGE_START = "REASONING_MESSAGE_START"
    REASONING_MESSAGE_CONTENT = "REASONING_MESSAGE_CONTENT"
    REASONING_MESSAGE_END = "REASONING_MESSAGE_END"
    REASONING_MESSAGE_CHUNK = "REASONING_MESSAGE_CHUNK"
    REASONING_END = "REASONING_END"
    REASONING_ENCRYPTED_VALUE = "REASONING_ENCRYPTED_VALUE"
    SUBAGENT_STARTED = "SUBAGENT_STARTED"
    SUBAGENT_FINISHED = "SUBAGENT_FINISHED"
    SUBAGENT_ERROR = "SUBAGENT_ERROR"
```

## BaseEvent

`from ag_ui.core import BaseEvent`

All events inherit from the `BaseEvent` class, which provides common properties
shared across all event types.

```python theme={null}
class BaseEvent(ConfiguredBaseModel):
    type: EventType
    timestamp: Optional[int] = None
    raw_event: Optional[Any] = None
    metadata: Optional[Dict[str, Any]] = None
```

| Property | Type | Description |
| - | - | - |
| `type` | `EventType` | The type of event (discriminator field for the union) |
| `timestamp` | `Optional[int]` | Timestamp when the event was created |
| `raw_event` | `Optional[Any]` | Original event data if this event was transformed |
| `metadata` | `Optional[Dict[str, Any]]` | Extra information attached to the event |

`metadata` is open by key: any JSON value is allowed under a key, including
`None`. The object may be absent, but a present one is never `None` — an
explicit `null` is read back as absent, so a plain `model_dump_json()`
round-trips. `EventEncoder` uses `exclude_none=True`, so an absent object is
omitted from the wire rather than emitted as `null`. The `ag-ui` key is reserved
for AG-UI's own use.

## Lifecycle Events

These events represent the lifecycle of an agent run.

### RunStartedEvent

`from ag_ui.core import RunStartedEvent`

Signals the start of an agent run.

```python theme={null}
class RunStartedEvent(BaseEvent):
    type: Literal[EventType.RUN_STARTED]
    thread_id: str
    run_id: str
    parent_run_id: Optional[str] = None
    input: Optional[RunAgentInput] = None
```

| Property | Type | Description |
| - | - | - |
| `thread_id` | `str` | ID of the conversation thread |
| `run_id` | `str` | ID of the agent run |
| `parent_run_id` | `Optional[str]` | (Optional) Lineage pointer for branching/time travel. If present, refers to a prior run within the same thread |
| `input` | `Optional[RunAgentInput]` | (Optional) The exact agent input payload sent to the agent for this run. May omit messages already in history |

### TokenUsage

`from ag_ui.core import TokenUsage`

A reusable, numeric-only token usage summary carried on terminal run events.
It intentionally contains **only** provider/model labels and token counts — no
prompts, completions, messages, or identifiers. The counts follow the
protocol's [accounting](/spec/1.0/events/lifecycle#token-usage): the input
and output counts are totals, and the cache and reasoning counts are parts of
them, never additions.

```python theme={null}
class TokenUsage(ConfiguredBaseModel):
    provider: Optional[str] = None
    model: Optional[str] = None
    input_tokens: Optional[int] = None
    output_tokens: Optional[int] = None
    total_tokens: Optional[int] = None
    reasoning_tokens: Optional[int] = None
    cached_input_tokens: Optional[int] = None
    cache_write_input_tokens: Optional[int] = None
```

| Property | Type | Description |
| - | - | - |
| `provider` | `Optional[str]` | Provider that reported the usage (e.g. `openai`) |
| `model` | `Optional[str]` | Model that produced the usage |
| `input_tokens` | `Optional[int]` | All input tokens, cache reads and writes included |
| `output_tokens` | `Optional[int]` | All output tokens, reasoning included |
| `total_tokens` | `Optional[int]` | `input_tokens` plus `output_tokens` |
| `reasoning_tokens` | `Optional[int]` | Output tokens spent on reasoning; part of `output_tokens` |
| `cached_input_tokens` | `Optional[int]` | Input tokens read from a prompt cache; part of `input_tokens` |
| `cache_write_input_tokens` | `Optional[int]` | Input tokens written to a prompt cache; part of `input_tokens` |

### RunFinishedEvent

`from ag_ui.core import RunFinishedEvent`

Signals the successful completion of an agent run.

```python theme={null}
class RunFinishedEvent(BaseEvent):
    type: Literal[EventType.RUN_FINISHED]
    thread_id: str
    run_id: str
    result: Optional[Any] = None
    usage: Optional[List[TokenUsage]] = None
```

| Property | Type | Description |
| - | - | - |
| `thread_id` | `str` | ID of the conversation thread |
| `run_id` | `str` | ID of the agent run |
| `result` | `Optional[Any]` | Result data from the agent run |
| `usage` | `Optional[List[TokenUsage]]` | Per-(provider, model) token usage for the run, when reported |

### RunErrorEvent

`from ag_ui.core import RunErrorEvent`

Signals an error during an agent run.

```python theme={null}
class RunErrorEvent(BaseEvent):
    type: Literal[EventType.RUN_ERROR]
    message: str
    code: Optional[str] = None
    usage: Optional[List[TokenUsage]] = None
```

| Property | Type | Description |
| - | - | - |
| `message` | `str` | Error message |
| `code` | `Optional[str]` | Error code |
| `usage` | `Optional[List[TokenUsage]]` | Partial token usage from model calls that completed |

### StepStartedEvent

`from ag_ui.core import StepStartedEvent`

Signals the start of a step within an agent run.

```python theme={null}
class StepStartedEvent(BaseEvent):
    type: Literal[EventType.STEP_STARTED]
    step_name: str
```

| Property | Type | Description |
| - | - | - |
| `step_name` | `str` | Name of the step |

### StepFinishedEvent

`from ag_ui.core import StepFinishedEvent`

Signals the completion of a step within an agent run.

```python theme={null}
class StepFinishedEvent(BaseEvent):
    type: Literal[EventType.STEP_FINISHED]
    step_name: str
```

| Property | Type | Description |
| - | - | - |
| `step_name` | `str` | Name of the step |

## Text Message Events

These events represent the lifecycle of text messages in a conversation.

### TextMessageStartEvent

`from ag_ui.core import TextMessageStartEvent`

Signals the start of a text message.

```python theme={null}
class TextMessageStartEvent(BaseEvent):
    type: Literal[EventType.TEXT_MESSAGE_START]
    message_id: str
    role: Literal["assistant"]
```

| Property | Type | Description |
| - | - | - |
| `message_id` | `str` | Unique identifier for the message |
| `role` | `Literal["assistant"]` | Role is always "assistant" |

### TextMessageContentEvent

`from ag_ui.core import TextMessageContentEvent`

Represents a chunk of content in a streaming text message.

```python theme={null}
class TextMessageContentEvent(BaseEvent):
    type: Literal[EventType.TEXT_MESSAGE_CONTENT]
    message_id: str
    delta: str  # Non-empty string

    def model_post_init(self, __context):
        if len(self.delta) == 0:
            raise ValueError("Delta must not be an empty string")
```

| Property | Type | Description |
| - | - | - |
| `message_id` | `str` | Matches the ID from TextMessageStartEvent |
| `delta` | `str` | Text content chunk (non-empty) |

### TextMessageEndEvent

`from ag_ui.core import TextMessageEndEvent`

Signals the end of a text message.

```python theme={null}
class TextMessageEndEvent(BaseEvent):
    type: Literal[EventType.TEXT_MESSAGE_END]
    message_id: str
```

| Property | Type | Description |
| - | - | - |
| `message_id` | `str` | Matches the ID from TextMessageStartEvent |

## Tool Call Events

These events represent the lifecycle of tool calls made by agents.

### ToolCallStartEvent

`from ag_ui.core import ToolCallStartEvent`

Signals the start of a tool call.

```python theme={null}
class ToolCallStartEvent(BaseEvent):
    type: Literal[EventType.TOOL_CALL_START]
    tool_call_id: str
    tool_call_name: str
    parent_message_id: Optional[str] = None
```

| Property | Type | Description |
| - | - | - |
| `tool_call_id` | `str` | Unique identifier for the tool call |
| `tool_call_name` | `str` | Name of the tool being called |
| `parent_message_id` | `Optional[str]` | ID of the parent message |

### ToolCallArgsEvent

`from ag_ui.core import ToolCallArgsEvent`

Represents a chunk of argument data for a tool call.

```python theme={null}
class ToolCallArgsEvent(BaseEvent):
    type: Literal[EventType.TOOL_CALL_ARGS]
    tool_call_id: str
    delta: str
```

| Property | Type | Description |
| - | - | - |
| `tool_call_id` | `str` | Matches the ID from ToolCallStartEvent |
| `delta` | `str` | Argument data chunk |

### ToolCallEndEvent

`from ag_ui.core import ToolCallEndEvent`

Signals the end of a tool call.

```python theme={null}
class ToolCallEndEvent(BaseEvent):
    type: Literal[EventType.TOOL_CALL_END]
    tool_call_id: str
```

| Property | Type | Description |
| - | - | - |
| `tool_call_id` | `str` | Matches the ID from ToolCallStartEvent |

### ToolCallResultEvent

`from ag_ui.core import ToolCallResultEvent`

Provides the result of a tool call execution.

```python theme={null}
class ToolCallResultEvent(BaseEvent):
    message_id: str
    type: Literal[EventType.TOOL_CALL_RESULT]
    tool_call_id: str
    content: str
    role: Optional[Literal["tool"]] = None
```

| Property | Type | Description |
| - | - | - |
| `message_id` | `str` | ID of the conversation message this result belongs to |
| `tool_call_id` | `str` | Matches the ID from the corresponding ToolCallStartEvent |
| `content` | `str` | The actual result/output content from the tool execution |
| `role` | `Optional[Literal["tool"]]` | Optional role identifier, typically "tool" for tool results |

## State Management Events

These events are used to manage agent state.

### StateSnapshotEvent

`from ag_ui.core import StateSnapshotEvent`

Provides a complete snapshot of an agent's state.

```python theme={null}
class StateSnapshotEvent(BaseEvent):
    type: Literal[EventType.STATE_SNAPSHOT]
    snapshot: State
```

| Property | Type | Description |
| - | - | - |
| `snapshot` | `State` | Complete state snapshot |

### StateDeltaEvent

`from ag_ui.core import StateDeltaEvent`

Provides a partial update to an agent's state using JSON Patch.

```python theme={null}
class StateDeltaEvent(BaseEvent):
    type: Literal[EventType.STATE_DELTA]
    delta: List[Any]  # JSON Patch (RFC 6902)
```

| Property | Type | Description |
| - | - | - |
| `delta` | `List[Any]` | Array of JSON Patch operations |

### MessagesSnapshotEvent

`from ag_ui.core import MessagesSnapshotEvent`

Provides a snapshot of all messages in a conversation.

```python theme={null}
class MessagesSnapshotEvent(BaseEvent):
    type: Literal[EventType.MESSAGES_SNAPSHOT]
    messages: List[Message]
```

| Property | Type | Description |
| - | - | - |
| `messages` | `List[Message]` | Array of message objects |

### ActivitySnapshotEvent

`from ag_ui.core import ActivitySnapshotEvent`

Delivers a complete snapshot of an activity message.

```python theme={null}
class ActivitySnapshotEvent(BaseEvent):
    type: Literal[EventType.ACTIVITY_SNAPSHOT]
    message_id: str
    activity_type: str
    content: Any
    replace: bool = True
```

| Property | Type | Description |
| - | - | - |
| `message_id` | `str` | Identifier for the target `ActivityMessage` |
| `activity_type` | `str` | Activity discriminator such as `"PLAN"` or `"SEARCH"` |
| `content` | `Any` | Structured payload describing the full activity state |
| `replace` | `bool` (default `True`) | When `False`, the snapshot is ignored if a message with the same ID already exists |

### ActivityDeltaEvent

`from ag_ui.core import ActivityDeltaEvent`

Provides incremental updates to an activity snapshot using JSON Patch.

```python theme={null}
class ActivityDeltaEvent(BaseEvent):
    type: Literal[EventType.ACTIVITY_DELTA]
    message_id: str
    activity_type: str
    patch: List[Any]
```

| Property | Type | Description |
| - | - | - |
| `message_id` | `str` | Identifier for the target `ActivityMessage` |
| `activity_type` | `str` | Activity discriminator mirroring the most recent snapshot |
| `patch` | `List[Any]` | JSON Patch operations applied to the structured activity content |

## Special Events

### RawEvent

`from ag_ui.core import RawEvent`

Used to pass through events from external systems.

```python theme={null}
class RawEvent(BaseEvent):
    type: Literal[EventType.RAW]
    event: Any
    source: Optional[str] = None
```

| Property | Type | Description |
| - | - | - |
| `event` | `Any` | Original event data |
| `source` | `Optional[str]` | Source of the event |

### CustomEvent

`from ag_ui.core import CustomEvent`

Used for application-specific custom events.

```python theme={null}
class CustomEvent(BaseEvent):
    type: Literal[EventType.CUSTOM]
    name: str
    value: Any
```

| Property | Type | Description |
| - | - | - |
| `name` | `str` | Name of the custom event |
| `value` | `Any` | Value associated with the event |

## Reasoning Events

These events represent the lifecycle of reasoning/thinking processes within an
agent. Reasoning events allow agents to expose their internal thought process to
the frontend, creating `ReasoningMessage` objects that persist in the message
history with the role `"reasoning"`.

### ReasoningStartEvent

`from ag_ui.core import ReasoningStartEvent`

Signals the start of a reasoning phase. This is a pass-through event that
notifies subscribers but does not create messages.

```python theme={null}
class ReasoningStartEvent(BaseEvent):
    type: Literal[EventType.REASONING_START]
    message_id: str
```

| Property | Type | Description |
| - | - | - |
| `message_id` | `str` | Identifier for the reasoning phase |

### ReasoningMessageStartEvent

`from ag_ui.core import ReasoningMessageStartEvent`

Signals the start of a reasoning message. Creates a new `ReasoningMessage` in
the message history.

```python theme={null}
class ReasoningMessageStartEvent(BaseEvent):
    type: Literal[EventType.REASONING_MESSAGE_START]
    message_id: str
    role: Literal["reasoning"]
```

| Property | Type | Description |
| - | - | - |
| `message_id` | `str` | Unique identifier for the message |
| `role` | `Literal["reasoning"]` | Role is always "reasoning" |

### ReasoningMessageContentEvent

`from ag_ui.core import ReasoningMessageContentEvent`

Represents a chunk of content in a streaming reasoning message.

```python theme={null}
class ReasoningMessageContentEvent(BaseEvent):
    type: Literal[EventType.REASONING_MESSAGE_CONTENT]
    message_id: str
    delta: str
```

| Property | Type | Description |
| - | - | - |
| `message_id` | `str` | Matches the ID from ReasoningMessageStartEvent |
| `delta` | `str` | Reasoning content chunk |

### ReasoningMessageEndEvent

`from ag_ui.core import ReasoningMessageEndEvent`

Signals the end of a reasoning message.

```python theme={null}
class ReasoningMessageEndEvent(BaseEvent):
    type: Literal[EventType.REASONING_MESSAGE_END]
    message_id: str
```

| Property | Type | Description |
| - | - | - |
| `message_id` | `str` | Matches the ID from ReasoningMessageStartEvent |

### ReasoningMessageChunkEvent

`from ag_ui.core import ReasoningMessageChunkEvent`

Convenience event for complete reasoning messages without manually emitting
`ReasoningMessageStart`/`ReasoningMessageEnd`.

```python theme={null}
class ReasoningMessageChunkEvent(BaseEvent):
    type: Literal[EventType.REASONING_MESSAGE_CHUNK]
    message_id: Optional[str] = None  # required on first chunk for a message
    delta: Optional[str] = None
```

Behavior

* Convenience: Some consumers (e.g., the JS/TS client) expand chunk events into
  the standard start/content/end sequence automatically.
* First chunk requirements: The first chunk for a given message must include
  `message_id`.
* Streaming: Subsequent chunks with the same `message_id` correspond to content
  pieces; completion triggers an implied end in clients that perform expansion.

### ReasoningEndEvent

`from ag_ui.core import ReasoningEndEvent`

Signals the end of a reasoning phase. This is a pass-through event that notifies
subscribers but does not modify messages.

```python theme={null}
class ReasoningEndEvent(BaseEvent):
    type: Literal[EventType.REASONING_END]
    message_id: str
```

| Property | Type | Description |
| - | - | - |
| `message_id` | `str` | Identifier for the reasoning phase |

### ReasoningEncryptedValueEvent

`from ag_ui.core import ReasoningEncryptedValueEvent`

Attaches an encrypted value to a message or tool call. When this event is
emitted, it finds the referenced entity by `entity_id` and sets its
`encrypted_value` field.

```python theme={null}
ReasoningEncryptedValueSubtype = Literal["tool-call", "message"]

class ReasoningEncryptedValueEvent(BaseEvent):
    type: Literal[EventType.REASONING_ENCRYPTED_VALUE]
    subtype: ReasoningEncryptedValueSubtype
    entity_id: str
    encrypted_value: str
```

| Property | Type | Description |
| - | - | - |
| `subtype` | `ReasoningEncryptedValueSubtype` | The type of entity this value belongs to |
| `entity_id` | `str` | ID of the tool call or message to attach the value |
| `encrypted_value` | `str` | The encrypted value to attach to the entity |

## Subagent Events

These events report that the agent delegated work to a child agent, so a frontend
can attribute output to the subagent that produced it. Attribution itself travels
as an optional `subagent_run_id` on most other event types.

`subagent_run_id` identifies **one invocation**, not a reusable subagent
definition — the same subagent run twice yields two different values. See
[Subagents](/concepts/subagents) for the full model.

Field names are snake\_case in Python and serialize to camelCase on the wire, so
`subagent_run_id` appears as `subagentRunId` in JSON.

### SubagentStartedEvent

`from ag_ui.core import SubagentStartedEvent`

Announces a new subagent invocation and names it for display.

```python theme={null}
class SubagentStartedEvent(BaseEvent):
    type: Literal[EventType.SUBAGENT_STARTED]
    subagent_run_id: str
    name: str
    description: Optional[str] = None
    parent_subagent_run_id: Optional[str] = None
    parent_tool_call_id: Optional[str] = None
    parent_message_id: Optional[str] = None
```

| Property | Type | Description |
| - | - | - |
| `subagent_run_id` | `str` | Opaque identifier for this invocation |
| `name` | `str` | Declared subagent name or type, for display |
| `description` | `str` | Optional description |
| `parent_subagent_run_id` | `str` | Optional enclosing subagent, when nesting |
| `parent_tool_call_id` | `str` | Optional tool call that spawned this subagent |
| `parent_message_id` | `str` | Optional message holding that tool call |

### SubagentFinishedEvent

`from ag_ui.core import SubagentFinishedEvent`

Marks a subagent invocation as complete.

```python theme={null}
class SubagentFinishedEvent(BaseEvent):
    type: Literal[EventType.SUBAGENT_FINISHED]
    subagent_run_id: str
    result: Optional[Any] = None
    outcome: Optional[SubagentFinishedOutcome] = None
```

| Property | Type | Description |
| - | - | - |
| `subagent_run_id` | `str` | Matches the id from `SubagentStartedEvent` |
| `result` | `Any` | Optional payload, mirroring `RunFinishedEvent.result` |
| `outcome` | `Optional[SubagentFinishedOutcome]` | Discriminated union of `SubagentFinishedSuccessOutcome` and `SubagentFinishedSuspendedOutcome` (with optional `interrupt_ids`); `None` means success (the legacy reading). Suspended says the subagent is checkpointed awaiting outside input; `interrupt_ids` names the run-level interrupts whose answers resume it. |

### SubagentErrorEvent

`from ag_ui.core import SubagentErrorEvent`

Marks a subagent invocation as failed.

```python theme={null}
class SubagentErrorEvent(BaseEvent):
    type: Literal[EventType.SUBAGENT_ERROR]
    subagent_run_id: str
    message: str
    code: Optional[str] = None
```

| Property | Type | Description |
| - | - | - |
| `subagent_run_id` | `str` | Matches the id from `SubagentStartedEvent` |
| `message` | `str` | Human-readable error message |
| `code` | `str` | Optional error code |

### Attribution on other events

Most event types accept an optional `subagent_run_id`. An event without it
belongs to the parent agent, so a stream that never sets the field behaves
exactly as it did before subagents existed.

`RunStartedEvent`, `RunFinishedEvent` and `RunErrorEvent` are not attributable —
they describe the run as a whole. `MessagesSnapshotEvent` carries attribution
per-message instead.

`StateSnapshotEvent` and `StateDeltaEvent` are attributable, but attribution on
them is provenance rather than ownership — it records which subagent produced the
update. State stays run-scoped, so an attributed snapshot or delta is applied to
the run's one state document just as an unattributed one is.

## Deprecated Events

> [!WARNING]
>
> The `THINKING_*` events are deprecated and will be removed in version 1.0.0.
> New implementations should use `REASONING_*` events instead.

### Thinking Events (Deprecated)

The following event types are deprecated:

| Deprecated Event | 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` |

See [Reasoning Migration](/concepts/reasoning#migration-from-thinking-events)
for detailed migration guidance.

## Event Discrimination

`from ag_ui.core import Event`

The SDK uses Pydantic's discriminated unions for event validation:

```python theme={null}
Event = Annotated[
    Union[
        TextMessageStartEvent,
        TextMessageContentEvent,
        TextMessageEndEvent,
        ToolCallStartEvent,
        ToolCallArgsEvent,
        ToolCallEndEvent,
        ToolCallResultEvent,
        StateSnapshotEvent,
        StateDeltaEvent,
        MessagesSnapshotEvent,
        ActivitySnapshotEvent,
        ActivityDeltaEvent,
        RawEvent,
        CustomEvent,
        RunStartedEvent,
        RunFinishedEvent,
        RunErrorEvent,
        StepStartedEvent,
        StepFinishedEvent,
        ReasoningStartEvent,
        ReasoningMessageStartEvent,
        ReasoningMessageContentEvent,
        ReasoningMessageEndEvent,
        ReasoningMessageChunkEvent,
        ReasoningEndEvent,
        ReasoningEncryptedValueEvent,
    ],
    Field(discriminator="type")
]
```

This allows for runtime validation of events and type checking at development
time.

### TextMessageChunkEvent

Convenience event for complete text messages without manually emitting
`TextMessageStart`/`TextMessageEnd`.

```python theme={null}
from ag_ui.core import TextMessageChunkEvent

class TextMessageChunkEvent(BaseEvent):
    type: Literal[EventType.TEXT_MESSAGE_CHUNK]
    message_id: Optional[str] = None  # required on first chunk for a message
    role: Optional[TextMessageRole] = None  # defaults to "assistant" in JS client
    delta: Optional[str] = None
```

Behavior

* Convenience: Some consumers (e.g., the JS/TS client) expand chunk events into
  the standard start/content/end sequence automatically, allowing producers to
  omit explicit start/end events when using chunks.
* First chunk requirements: The first chunk for a given message must include
  `message_id`.
* Streaming: Subsequent chunks with the same `message_id` correspond to content
  pieces; completion triggers an implied end in clients that perform expansion.

### ToolCallChunkEvent

Convenience event for tool calls without manually emitting
`ToolCallStart`/`ToolCallEnd`.

```python theme={null}
from ag_ui.core import ToolCallChunkEvent

class ToolCallChunkEvent(BaseEvent):
    type: Literal[EventType.TOOL_CALL_CHUNK]
    tool_call_id: Optional[str] = None      # required on first chunk
    tool_call_name: Optional[str] = None    # required on first chunk
    parent_message_id: Optional[str] = None
    delta: Optional[str] = None
```

Behavior

* Convenience: Consumers may expand chunk sequences into the standard
  start/args/end triad (the JS/TS client does this automatically).
* First chunk requirements: Include both `tool_call_id` and `tool_call_name` on
  the first chunk.
* Streaming: Subsequent chunks with the same `tool_call_id` correspond to args
  pieces; completion triggers an implied end in clients that perform expansion.


# Multimodal Inputs
Source: https://docs.ag-ui.com/sdk/python/core/multimodal-inputs

Use modality-specific user input parts with typed data/url sources in ag_ui.core

# Multimodal Inputs

`UserMessage.content` accepts either plain text or an ordered list of multimodal
parts.

```python theme={null}
from ag_ui.core import (
    UserMessage,
    TextPart,
    ImagePart,
    DocumentPart,
    UrlSource,
)

message = UserMessage(
    id="user-1",
    content=[
        TextPart(text="Summarize this PDF and screenshot"),
        ImagePart(
            source=UrlSource(
                value="https://example.com/screen.png",
                mime_type="image/png",
            )
        ),
        DocumentPart(
            source=UrlSource(
                value="https://example.com/report.pdf",
                mime_type="application/pdf",
            )
        ),
    ],
)
```

## Source Types

Use `source.type` to describe payload delivery:

* `data`: Inline base64 payload with required `mime_type`
* `url`: HTTP(S) or data URL, optional `mime_type`

## Common Use Cases

### Visual QA

```python theme={null}
from ag_ui.core import UserMessage, TextPart, ImagePart, UrlSource

message = UserMessage(
    id="q1",
    content=[
        TextPart(text="What issue do you see in this UI?"),
        ImagePart(
            source=UrlSource(
                value="https://example.com/ui.png",
                mime_type="image/png",
            ),
            metadata={"detail": "high"},
        ),
    ],
)
```

### Audio transcription

```python theme={null}
from ag_ui.core import UserMessage, TextPart, AudioPart, UrlSource

message = UserMessage(
    id="q2",
    content=[
        TextPart(text="Transcribe this recording."),
        AudioPart(
            source=UrlSource(
                value="https://example.com/meeting.wav",
                mime_type="audio/wav",
            )
        ),
    ],
)
```

### Deprecated binary model

`BinaryInputContent` is deprecated and emits a `DeprecationWarning`. It is kept
as a temporary compatibility path while migrating to modality-specific parts.


# Overview
Source: https://docs.ag-ui.com/sdk/python/core/overview

Core concepts in the Agent User Interaction Protocol SDK

```bash theme={null}
pip install ag-ui-protocol
```

# ag\_ui.core

The Agent User Interaction Protocol SDK uses a streaming event-based
architecture with strongly typed data structures. This package provides the
foundation for connecting to agent systems.

```python theme={null}
from ag_ui.core import ...
```

## Types

Core data structures that represent the building blocks of the system:

* [RunAgentInput](/sdk/python/core/types#runagentinput) - Input parameters for
  running agents
* [Message](/sdk/python/core/types#message-types) - User assistant communication
  and tool usage
* [Context](/sdk/python/core/types#context) - Contextual information provided to
  agents
* [Tool](/sdk/python/core/types#tool) - Defines functions that agents can call
* [State](/sdk/python/core/types#state) - Agent state management

> [card] [Types Reference](/sdk/python/core/types)
>
> Complete documentation of all types in the ag\_ui.core package

## Events

Events that power communication between agents and frontends:

* [Lifecycle Events](/sdk/python/core/events#lifecycle-events) - Run and step
  tracking
* [Text Message Events](/sdk/python/core/events#text-message-events) - Assistant
  message streaming
* [Tool Call Events](/sdk/python/core/events#tool-call-events) - Function call
  lifecycle
* [State Management Events](/sdk/python/core/events#state-management-events) -
  Agent state updates
* [Special Events](/sdk/python/core/events#special-events) - Raw and custom
  events

> [card] [Events Reference](/sdk/python/core/events)
>
> Complete documentation of all events in the ag\_ui.core package


# Types
Source: https://docs.ag-ui.com/sdk/python/core/types

Documentation for the core types used in the Agent User Interaction Protocol Python SDK

# Core Types

The Agent User Interaction Protocol Python SDK is built on a set of core types
that represent the fundamental structures used throughout the system. This page
documents these types and their properties.

## RunAgentInput

`from ag_ui.core import RunAgentInput`

Input parameters for running an agent. In the HTTP API, this is the body of the
`POST` request.

`tools` contains tools provided by the client for this run. Backend-defined
tools should remain in the backend agent or framework configuration, and may be
advertised separately through agent capabilities.

```python theme={null}
class RunAgentInput(ConfiguredBaseModel):
    thread_id: str
    run_id: str
    parent_run_id: Optional[str] = None
    state: Any = None  # optional: absent means "no state"; a bare null reads as absent
    messages: List[Message]
    tools: List[Tool]
    context: List[Context]
    forwarded_props: Any
    resume: Optional[List[ResumeEntry]] = None
```

| Property | Type | Description |
| - | - | - |
| `thread_id` | `str` | ID of the conversation thread |
| `run_id` | `str` | ID of the current run |
| `parent_run_id` | `Optional[str]` | (Optional) ID of the run that spawned this run |
| `state` | `Any` | (Optional) Current state of the agent; absent means "no state", and a bare `null` is read as absent |
| `messages` | `List[Message]` | List of messages in the conversation |
| `tools` | `List[Tool]` | Client-provided tools available for this run |
| `context` | `List[Context]` | List of context objects provided to the agent |
| `forwarded_props` | `Any` | Additional properties forwarded to the agent |
| `resume` | `Optional[List[ResumeEntry]]` | Per-interrupt responses resuming a run that finished with an interrupt outcome |

## ResumeEntry

`from ag_ui.core import ResumeEntry`

One per-interrupt response inside `RunAgentInput.resume`, addressing an
interrupt from the previous run. See
[Interrupts](/concepts/interrupts#resuming-a-run) for the full resume contract.

```python theme={null}
class ResumeEntry(GeneratedBaseModel):
    interrupt_id: str
    status: ResumeStatus  # "resolved" | "cancelled"
    payload: Optional[Any] = None
    metadata: Optional[Metadata] = None
```

| Property | Type | Description |
| - | - | - |
| `interrupt_id` | `str` | ID of the interrupt this entry addresses |
| `status` | `ResumeStatus` | `"resolved"` if the user responded, `"cancelled"` if they abandoned |
| `payload` | `Optional[Any]` | The response itself, validated against the interrupt's `response_schema` |
| `metadata` | `Optional[Dict[str, Any]]` | Envelope data about the response — signatures, routing keys — never the answer itself |

`metadata` follows the same conventions as metadata everywhere else in the
protocol: open by key, any JSON value allowed under a key including `None`, the
object itself absent or a mapping but never `null` on the wire, and the `ag-ui`
key reserved. A resume entry is a request field, so nothing merges into it; see
[Metadata](/concepts/metadata#resume-entries).

## Message Types

The SDK includes several message types that represent different kinds of
messages in the system.

> [!NOTE]
>
> Every message type carries an optional `metadata` object (`Optional[Dict[str,
>     Any]]`), and so does `ToolCall`. Both are omitted from the per-type tables
> below for brevity. It is open by key — any JSON value is allowed under a key,
> including `None` — and the object itself may be absent but is never `None`.
> The `ag-ui` key is reserved for AG-UI's own use. Metadata accumulates as a
> message is built from its events, and tool call events accumulate onto the
> tool call itself; see [Metadata](/concepts/metadata) for the merge rules.

### Role

`from ag_ui.core import Role`

Represents the possible roles a message sender can have.

```python theme={null}
Role = Literal["developer", "system", "assistant", "user", "tool", "activity", "reasoning"]
```

### DeveloperMessage

`from ag_ui.core import DeveloperMessage`

Represents a message from a developer.

```python theme={null}
class DeveloperMessage(BaseMessage):
    role: Literal["developer"]
    content: str
```

| Property | Type | Description |
| - | - | - |
| `id` | `str` | Unique identifier for the message |
| `role` | `Literal["developer"]` | Role of the message sender, fixed as "developer" |
| `content` | `str` | Text content of the message (required) |
| `name` | `Optional[str]` | Optional name of the sender |

### SystemMessage

`from ag_ui.core import SystemMessage`

Represents a system message.

```python theme={null}
class SystemMessage(BaseMessage):
    role: Literal["system"]
    content: str
```

| Property | Type | Description |
| - | - | - |
| `id` | `str` | Unique identifier for the message |
| `role` | `Literal["system"]` | Role of the message sender, fixed as "system" |
| `content` | `str` | Text content of the message (required) |
| `name` | `Optional[str]` | Optional name of the sender |

### AssistantMessage

`from ag_ui.core import AssistantMessage`

Represents a message from an assistant.

```python theme={null}
class AssistantMessage(BaseMessage):
    role: Literal["assistant"]
    content: Optional[str] = None
    tool_calls: Optional[List[ToolCall]] = None
```

| Property | Type | Description |
| - | - | - |
| `id` | `str` | Unique identifier for the message |
| `role` | `Literal["assistant"]` | Role of the message sender, fixed as "assistant" |
| `content` | `Optional[str]` | Text content of the message |
| `name` | `Optional[str]` | Name of the sender |
| `tool_calls` | `Optional[List[ToolCall]]` | Tool calls made in this message |

### UserMessage

`from ag_ui.core import UserMessage`

Represents a message from a user.

```python theme={null}
class UserMessage(BaseMessage):
    role: Literal["user"]
    content: Union[str, List["ContentPart"]]
```

| Property | Type | Description |
| - | - | - |
| `id` | `str` | Unique identifier for the message |
| `role` | `Literal["user"]` | Role of the message sender, fixed as "user" |
| `content` | `Union[str, List["ContentPart"]]` | Either a plain text string or an ordered list of multimodal fragments |
| `name` | `Optional[str]` | Optional name of the sender |

### PartSource

Represents how a non-text part is supplied.

```python theme={null}
PartSource = Annotated[
    Union[DataSource, UrlSource, FileSource],
    Field(discriminator="type"),
]

class DataSource(ConfiguredBaseModel):
    type: Literal["data"]
    value: str
    mime_type: str

class UrlSource(ConfiguredBaseModel):
    type: Literal["url"]
    value: str
    mime_type: Optional[str] = None

class FileSource(ConfiguredBaseModel):
    type: Literal["file"]
    value: str  # the handle, exactly as the provider issued it
    provider: Optional[str] = None  # who issued it, e.g. "openai", "anthropic", "google"
    mime_type: Optional[str] = None
```

A `FileSource` names bytes that already live at the model provider — an
OpenAI or Anthropic file id, a Gemini file URI. Nothing is fetched and `value`
is opaque: an agent hands it to its provider or drops the part, and never
treats it as a URL.

### TextPart

Represents a text part inside a user message or a tool result.

```python theme={null}
class TextPart(ConfiguredBaseModel):
    type: Literal["text"]
    id: Optional[str] = None
    text: str
    metadata: Optional[Any] = None
```

| Property | Type | Description |
| - | - | - |
| `type` | `Literal["text"]` | Identifies the part type |
| `id` | `Optional[str]` | Identifies the part within its message |
| `text` | `str` | Text content |
| `metadata` | `Optional[Any]` | Extra information about the part, such as a search hit's source and title |

### BinaryInputContent

Represents binary data such as images, audio, or files.

```python theme={null}
class BinaryInputContent(ConfiguredBaseModel):
    type: Literal["binary"]
    mime_type: str
    id: Optional[str] = None
    url: Optional[str] = None
    data: Optional[str] = None
    filename: Optional[str] = None
```

| Property | Type | Description |
| - | - | - |
| `type` | `Literal["binary"]` | Identifies the fragment type |
| `mime_type` | `str` | MIME type, for example `"image/png"` |
| `id` | `Optional[str]` | Reference to previously uploaded content |
| `url` | `Optional[str]` | Remote URL where the content can be retrieved |
| `data` | `Optional[str]` | Base64 encoded content |
| `filename` | `Optional[str]` | Optional filename hint |

> **Validation:** At least one of `id`, `url`, or `data` must be provided.
>
> **Deprecated:** `BinaryInputContent` remains available as a temporary
> compatibility model. Prefer modality-specific parts below.

### ImagePart / AudioPart / VideoPart / DocumentPart

```python theme={null}
class ImagePart(ConfiguredBaseModel):
    type: Literal["image"]
    id: Optional[str] = None
    source: PartSource
    metadata: Optional[Any] = None

class AudioPart(ConfiguredBaseModel):
    type: Literal["audio"]
    id: Optional[str] = None
    source: PartSource
    metadata: Optional[Any] = None

class VideoPart(ConfiguredBaseModel):
    type: Literal["video"]
    id: Optional[str] = None
    source: PartSource
    metadata: Optional[Any] = None

class DocumentPart(ConfiguredBaseModel):
    type: Literal["document"]
    id: Optional[str] = None
    source: PartSource
    metadata: Optional[Any] = None
```

### ToolMessage

`from ag_ui.core import ToolMessage`

Represents a message from a tool.

```python theme={null}
class ToolMessage(ConfiguredBaseModel):
    id: str
    role: Literal["tool"]
    content: Union[str, List[ContentPart]]
    tool_call_id: str
    error: Optional[str] = None
    encrypted_value: Optional[str] = None
```

| Property | Type | Description |
| - | - | - |
| `id` | `str` | Unique identifier for the message |
| `content` | `str` | Text content of the message |
| `role` | `Literal["tool"]` | Role of the message sender, fixed as "tool" |
| `tool_call_id` | `str` | ID of the tool call this message responds to |
| `error` | `Optional[str]` | Error message if the tool call failed |
| `encrypted_value` | `Optional[str]` | Optional encrypted value attached via signature |

### ActivityMessage

`from ag_ui.core import ActivityMessage`

Represents structured activity progress emitted between chat messages.

```python theme={null}
class ActivityMessage(ConfiguredBaseModel):
    id: str
    role: Literal["activity"]
    activity_type: str
    content: Dict[str, Any]
```

| Property | Type | Description |
| - | - | - |
| `id` | `str` | Unique identifier for the activity message |
| `role` | `Literal["activity"]` | Fixed discriminator identifying the message as activity |
| `activity_type` | `str` | Activity discriminator used for renderer selection |
| `content` | `Dict[str, Any]` | Structured payload representing the activity state |

### ReasoningMessage

`from ag_ui.core import ReasoningMessage`

Represents a reasoning/thinking message from an agent's internal thought
process.

```python theme={null}
class ReasoningMessage(ConfiguredBaseModel):
    id: str
    role: Literal["reasoning"]
    content: str
    encrypted_value: Optional[str] = None
```

| Property | Type | Description |
| - | - | - |
| `id` | `str` | Unique identifier for the reasoning message |
| `role` | `Literal["reasoning"]` | Fixed discriminator identifying the reasoning role |
| `content` | `str` | The reasoning/thinking content |
| `encrypted_value` | `Optional[str]` | Optional encrypted value attached via signature |

### Message

`from ag_ui.core import Message`

A union type representing any type of message in the system.

```python theme={null}
Message = Annotated[
    Union[
        DeveloperMessage,
        SystemMessage,
        AssistantMessage,
        UserMessage,
        ToolMessage,
        ActivityMessage,
        ReasoningMessage,
    ],
    Field(discriminator="role")
]
```

### ToolCall

`from ag_ui.core import ToolCall`

Represents a tool call made by an agent.

```python theme={null}
class ToolCall(ConfiguredBaseModel):
    id: str
    type: Literal["function"]
    function: FunctionCall
    encrypted_value: Optional[str] = None
```

| Property | Type | Description |
| - | - | - |
| `id` | `str` | Unique identifier for the tool call |
| `type` | `Literal["function"]` | Type of the tool call, always "function" |
| `function` | `FunctionCall` | Details about the function being called |
| `encrypted_value` | `Optional[str]` | Optional encrypted value attached via signature |

#### FunctionCall

`from ag_ui.core import FunctionCall`

Represents function name and arguments in a tool call.

```python theme={null}
class FunctionCall(ConfiguredBaseModel):
    name: str
    arguments: str
```

| Property | Type | Description |
| - | - | - |
| `name` | `str` | Name of the function to call |
| `arguments` | `str` | JSON-encoded string of arguments to the function |

## Context

`from ag_ui.core import Context`

Represents a piece of contextual information provided to an agent.

```python theme={null}
class Context(ConfiguredBaseModel):
    description: str
    value: str
```

| Property | Type | Description |
| - | - | - |
| `description` | `str` | Description of what this context represents |
| `value` | `str` | The actual context value |

## Tool

`from ag_ui.core import Tool`

Defines a tool that can be called by an agent.

```python theme={null}
class Tool(ConfiguredBaseModel):
    name: str
    description: str
    parameters: Any  # JSON Schema
```

| Property | Type | Description |
| - | - | - |
| `name` | `str` | Name of the tool |
| `description` | `str` | Description of what the tool does |
| `parameters` | `Any` | JSON Schema defining the parameters for the tool |

## State

`from ag_ui.core import State`

Represents the state of an agent during execution.

```python theme={null}
State = Any
```

The state type is flexible and can hold any data structure needed by the agent
implementation.


# Overview
Source: https://docs.ag-ui.com/sdk/python/encoder/overview

Documentation for encoding Agent User Interaction Protocol events

```bash theme={null}
pip install ag-ui-protocol
```

# Event Encoder

The Agent User Interaction Protocol uses a streaming approach to send events
from agents to clients. The `EventEncoder` class provides the functionality to
encode events into a format that can be sent over HTTP.

## EventEncoder

`from ag_ui.encoder import EventEncoder`

The `EventEncoder` class is responsible for encoding `BaseEvent` objects into
string representations that can be transmitted to clients.

```python theme={null}
from ag_ui.core import BaseEvent
from ag_ui.encoder import EventEncoder

# Initialize the encoder
encoder = EventEncoder()

# Encode an event
encoded_event = encoder.encode(event)
```

### Usage

The `EventEncoder` is typically used in HTTP handlers to convert event objects
into a stream of data. The current implementation encodes events as Server-Sent
Events (SSE), which can be consumed by clients using the EventSource API.

### Methods

#### `__init__(accept: str = None)`

Creates a new encoder instance.

| Parameter | Type | Description |
| - | - | - |
| `accept` | `str` (optional) | Content type accepted by the client |

#### `encode(event: BaseEvent) -> str`

Encodes an event into a string representation.

| Parameter | Type | Description |
| - | - | - |
| `event` | `BaseEvent` | The event to encode |

**Returns**: A string representation of the event in SSE format.

### Example

```python theme={null}
from ag_ui.core import TextMessageContentEvent, EventType
from ag_ui.encoder import EventEncoder

# Create an event
event = TextMessageContentEvent(
    type=EventType.TEXT_MESSAGE_CONTENT,
    message_id="msg_123",
    delta="Hello, world!"
)

# Initialize the encoder
encoder = EventEncoder()

# Encode the event
encoded_event = encoder.encode(event)
print(encoded_event)
# Output: data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_123","delta":"Hello, world!"}\n\n
```

### Implementation Details

Internally, the encoder converts events to JSON and formats them as Server-Sent
Events with the following structure:

```
data: {json-serialized event}\n\n
```

This format allows clients to receive a continuous stream of events and process
them as they arrive.