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
    messages: List[Message]
    tools: List[Tool]
    context: List[Context]
    forwarded_props: Any

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

Message Types

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

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.

​Core Types

​RunAgentInput

​Message Types

​Role

​DeveloperMessage

​SystemMessage

​AssistantMessage

​UserMessage

​InputContentSource

​TextInputContent

​BinaryInputContent

​ImageInputContent / AudioInputContent / VideoInputContent / DocumentInputContent

​ToolMessage

​ActivityMessage

​ReasoningMessage

​Message

​ToolCall

​FunctionCall

​Context

​Tool

​State