> ## 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
  messages: Message[]
  tools: Tool[]
  context: Context[]
  forwardedProps: any
}
```

| 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`               | Current state of the agent                     |
| `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   |

## Message Types

The SDK includes several message types that represent different kinds of
messages in the system.

### 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 | InputContent[]
  name?: string
}
```

| Property  | Type                       | Description                                                           |
| --------- | -------------------------- | --------------------------------------------------------------------- |
| `id`      | `string`                   | Unique identifier for the message                                     |
| `role`    | `"user"`                   | Role of the message sender, fixed as "user"                           |
| `content` | `string \| InputContent[]` | Either plain text or an ordered array of multimodal content fragments |
| `name`    | `string`                   | Optional name of the sender                                           |

### InputContent

Union of supported multimodal fragments.

```typescript theme={null}
type InputContent =
  | TextInputContent
  | ImageInputContent
  | AudioInputContent
  | VideoInputContent
  | DocumentInputContent
```

### InputContentSource

```typescript theme={null}
type InputContentSource = InputContentDataSource | InputContentUrlSource

type InputContentDataSource = {
  type: "data"
  value: string
  mimeType: string
}

type InputContentUrlSource = {
  type: "url"
  value: string
  mimeType?: string
}
```

### TextInputContent

```typescript theme={null}
type TextInputContent = {
  type: "text"
  text: string
}
```

### ImageInputContent

```typescript theme={null}
type ImageInputContent = {
  type: "image"
  source: InputContentSource
  metadata?: unknown
}
```

### AudioInputContent

```typescript theme={null}
type AudioInputContent = {
  type: "audio"
  source: InputContentSource
  metadata?: unknown
}
```

### VideoInputContent

```typescript theme={null}
type VideoInputContent = {
  type: "video"
  source: InputContentSource
  metadata?: unknown
}
```

### DocumentInputContent

```typescript theme={null}
type DocumentInputContent = {
  type: "document"
  source: InputContentSource
  metadata?: unknown
}
```

### ToolMessage

Represents a message from a tool.

```typescript theme={null}
type ToolMessage = {
  id: string
  content: string
  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.