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.

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 for the full resume contract.

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.

Message Types

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

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 for the merge rules.

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
}

ToolMessage

Represents a message from a tool.

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

ToolCall

Represents a tool call made by an agent.

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

Tool

Defines a tool that can be called by an agent.

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.

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.

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 for the full category type definitions and usage patterns.

TypeScript

Python

.NET

Types

Core Types

RunAgentInput

ResumeEntry

Message Types

Role

DeveloperMessage

SystemMessage

AssistantMessage

UserMessage

InputContent

InputContentSource

TextInputContent

ImageInputContent

AudioInputContent

VideoInputContent

DocumentInputContent

ToolMessage

ActivityMessage

ReasoningMessage

Message

ToolCall

FunctionCall

Context

Tool

State

AgentCapabilities

​Core Types

​RunAgentInput

​ResumeEntry

​Message Types

​Role

​DeveloperMessage

​SystemMessage

​AssistantMessage

​UserMessage

​InputContent

​InputContentSource

​TextInputContent

​ImageInputContent

​AudioInputContent

​VideoInputContent

​DocumentInputContent

​ToolMessage

​ActivityMessage

​ReasoningMessage

​Message

​ToolCall

​FunctionCall

​Context

​Tool

​State

​AgentCapabilities

Core Types

RunAgentInput

ResumeEntry

Message Types

Role

DeveloperMessage

SystemMessage

AssistantMessage

UserMessage

InputContent

InputContentSource

TextInputContent

ImageInputContent

AudioInputContent

VideoInputContent

DocumentInputContent

ToolMessage

ActivityMessage

ReasoningMessage

Message

ToolCall

FunctionCall

Context

Tool

State

AgentCapabilities