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.
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.
Input parameters for running an agent. In the HTTP API, this is the body of the
POST request.
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[] | Array of tools available to the agent |
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.
type Role =
| "developer"
| "system"
| "assistant"
| "user"
| "tool"
| "activity"
| "reasoning"
DeveloperMessage
Represents a message from a developer.
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.
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.
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.
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.
type InputContent =
| TextInputContent
| ImageInputContent
| AudioInputContent
| VideoInputContent
| DocumentInputContent
InputContentSource
type InputContentSource = InputContentDataSource | InputContentUrlSource
type InputContentDataSource = {
type: "data"
value: string
mimeType: string
}
type InputContentUrlSource = {
type: "url"
value: string
mimeType?: string
}
TextInputContent
type TextInputContent = {
type: "text"
text: string
}
ImageInputContent
type ImageInputContent = {
type: "image"
source: InputContentSource
metadata?: unknown
}
AudioInputContent
type AudioInputContent = {
type: "audio"
source: InputContentSource
metadata?: unknown
}
VideoInputContent
type VideoInputContent = {
type: "video"
source: InputContentSource
metadata?: unknown
}
DocumentInputContent
type DocumentInputContent = {
type: "document"
source: InputContentSource
metadata?: unknown
}
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.
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.
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.
type Message =
| DeveloperMessage
| SystemMessage
| AssistantMessage
| UserMessage
| ToolMessage
| ActivityMessage
| ReasoningMessage
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.
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.
type Context = {
description: string
value: string
}
| Property | Type | Description |
|---|
description | string | Description of what this context represents |
value | string | The actual context value |
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.
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.
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 |
