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.

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

class ResumeEntry(MetadataMixin):
    interrupt_id: str
    status: ResumeStatus  # "resolved" | "cancelled"
    payload: Optional[Any] = 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.

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

Role

from ag_ui.core import Role Represents the possible roles a message sender can have.

Role = Literal["developer", "system", "assistant", "user", "tool", "activity", "reasoning"]

DeveloperMessage

from ag_ui.core import DeveloperMessage Represents a message from a developer.

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.

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.

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.

class UserMessage(BaseMessage):
    role: Literal["user"]
    content: Union[str, List["InputContent"]]

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["InputContent"]]`	Either a plain text string or an ordered list of multimodal fragments
`name`	`Optional[str]`	Optional name of the sender

InputContentSource

Represents how a non-text part is supplied.

InputContentSource = Annotated[
    Union[InputContentDataSource, InputContentUrlSource],
    Field(discriminator="type"),
]

class InputContentDataSource(ConfiguredBaseModel):
    type: Literal["data"]
    value: str
    mime_type: str

class InputContentUrlSource(ConfiguredBaseModel):
    type: Literal["url"]
    value: str
    mime_type: Optional[str] = None

TextInputContent

Represents a text fragment inside a multimodal user message.

class TextInputContent(ConfiguredBaseModel):
    type: Literal["text"]
    text: str

Property	Type	Description
`type`	`Literal["text"]`	Identifies the fragment type
`text`	`str`	Text content

BinaryInputContent

Represents binary data such as images, audio, or files.

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.

ImageInputContent / AudioInputContent / VideoInputContent / DocumentInputContent

class ImageInputContent(ConfiguredBaseModel):
    type: Literal["image"]
    source: InputContentSource
    metadata: Optional[Any] = None

class AudioInputContent(ConfiguredBaseModel):
    type: Literal["audio"]
    source: InputContentSource
    metadata: Optional[Any] = None

class VideoInputContent(ConfiguredBaseModel):
    type: Literal["video"]
    source: InputContentSource
    metadata: Optional[Any] = None

class DocumentInputContent(ConfiguredBaseModel):
    type: Literal["document"]
    source: InputContentSource
    metadata: Optional[Any] = None

ToolMessage

from ag_ui.core import ToolMessage Represents a message from a tool.

class ToolMessage(ConfiguredBaseModel):
    id: str
    role: Literal["tool"]
    content: str
    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.

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.

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.

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.

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.

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.

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.

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.

State = Any

The state type is flexible and can hold any data structure needed by the agent implementation.

TypeScript

Python

.NET

Types

Core Types

RunAgentInput

ResumeEntry

Message Types

Role

DeveloperMessage

SystemMessage

AssistantMessage

UserMessage

InputContentSource

TextInputContent

BinaryInputContent

ImageInputContent / AudioInputContent / VideoInputContent / DocumentInputContent

ToolMessage

ActivityMessage

ReasoningMessage

Message

ToolCall

FunctionCall

Context

Tool

State

​Core Types

​RunAgentInput

​ResumeEntry

​Message Types

​Role

​DeveloperMessage

​SystemMessage

​AssistantMessage

​UserMessage

​InputContentSource

​TextInputContent

​BinaryInputContent

​ImageInputContent / AudioInputContent / VideoInputContent / DocumentInputContent

​ToolMessage

​ActivityMessage

​ReasoningMessage

​Message

​ToolCall

​FunctionCall

​Context

​Tool

​State

Core Types

RunAgentInput

ResumeEntry

Message Types

Role

DeveloperMessage

SystemMessage

AssistantMessage

UserMessage

InputContentSource

TextInputContent

BinaryInputContent

ImageInputContent / AudioInputContent / VideoInputContent / DocumentInputContent

ToolMessage

ActivityMessage

ReasoningMessage

Message

ToolCall

FunctionCall

Context

Tool

State