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.

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]`	List of tools available to the agent
`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"]

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

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.

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

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

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

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,
    ],
    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

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

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

​Core Types

​RunAgentInput

​Message Types

​Role

​DeveloperMessage

​SystemMessage

​AssistantMessage

​UserMessage

​TextInputContent

​BinaryInputContent

​ToolMessage

​ActivityMessage

​Message

​ToolCall

​FunctionCall

​Context

​Tool

​State