> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ag-ui.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.
</Note>

### 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.