Types

The Agent User Interaction Protocol Ruby 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.

Context

AgUiProtocol::Core::Types::Context

Represents a piece of contextual information provided to an agent.


ctx = AgUiProtocol::Core::Types::Context.new(description: "User locale",
value: "es-CL")

Property	Type	Description
`description`	`String`	Description of what this context represents.
`value`	`String`	The actual context value.

RunAgentInput

AgUiProtocol::Core::Types::RunAgentInput

Input parameters for running an agent. In the HTTP API, this is the body of the POST request.


input = AgUiProtocol::Core::Types::RunAgentInput.new(
    thread_id: "thread_123",
    run_id: "run_123",
    parent_run_id: nil,
    state: {},
    messages: [],
    tools: [],
    context: [],
    forwarded_props: {}

)

Property	Type	Description
`thread_id`	`String`	ID of the conversation thread
`run_id`	`String`	ID of the current run
`state`	`Object`	Current state of the agent
`messages`	`Array<BaseMessage>`	List of messages in the conversation
`tools`	`Array<Tool>`	List of tools available to the agent
`context`	`Array<Context>`	List of context objects provided to the agent
`forwarded_props`	`Object`	Additional properties forwarded to the agent
`parent_run_id`	`String` (optional)	Lineage pointer for branching/time travel , Default: `nil`.

Tool

AgUiProtocol::Core::Types::Tool

Defines a tool that can be called by an agent.


tool = AgUiProtocol::Core::Types::Tool.new(
    name: "search",
    description: "Search the web",
    parameters: { "type" => "object", "properties" => { "q" => { "type" => "string" } } }

)

Property	Type	Description
`name`	`String`	Name of the tool.
`description`	`String`	Description of what the tool does.
`parameters`	`Object`	JSON Schema for tool parameters.

ToolCall

AgUiProtocol::Core::Types::ToolCall

Tool calls are embedded within assistant messages.


tool_call = AgUiProtocol::Core::Types::ToolCall.new(
    id: "tc_1",
    function: { name: "search", arguments: "{\"q\":\"AG-UI\"}" }

)

Property	Type	Description
`id`	`String`	Unique identifier for the tool call
`function`	`FunctionCall , Hash`	Function name and arguments
`type`	`String` (optional)	Type of the tool call , Default: `'function'`.

FunctionCall

AgUiProtocol::Core::Types::FunctionCall

Function invocation descriptor used inside tool calls.


fn = AgUiProtocol::Core::Types::FunctionCall.new(
    name: "search",
    arguments: "{\"q\":\"AG-UI\"}"

)

@category [] ToolCall

Property	Type	Description
`name`	`String`	Function name.
`arguments`	`String`	JSON-encoded arguments.

Message Types

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

ActivityMessage

AgUiProtocol::Core::Types::ActivityMessage

Represents structured activity progress emitted between chat messages.


msg = AgUiProtocol::Core::Types::ActivityMessage.new(
    id: "activity_1",
    activity_type: "progress",
    content: { "pct" => 10 }

)

@category [] Message Types

Property	Type	Description
`id`	`String`	Unique identifier for the activity message.
`activity_type`	`String`	Activity discriminator used for renderer selection.
`content`	`Hash`	Structured payload representing the activity state.

AssistantMessage

AgUiProtocol::Core::Types::AssistantMessage

Represents a message from an assistant.


msg = AgUiProtocol::Core::Types::AssistantMessage.new(
    id: "asst_1",
    content: "Hello!",
    tool_calls: [
      {
        id: "tc_1",
        function: { name: "search", arguments: "{\"q\":\"AG-UI\"}" }
      }
    ]

)

@category [] Message Types

Property	Type	Description
`id`	`String`	Unique identifier for the message
`content`	`Object` (optional)	Text content of the message , Default: `nil`.
`tool_calls`	`Array<ToolCall , Hash>` (optional)	Tool calls made in this message , Default: `nil`.
`name`	`String` (optional)	Name of the sender , Default: `nil`.

BinaryInputContent

AgUiProtocol::Core::Types::BinaryInputContent

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


content = AgUiProtocol::Core::Types::BinaryInputContent.new(
    mime_type: "image/png",
    url: "https://example.com/cat.png"

)

Validation: At least one of id, url, or data must be provided.

@category [] Message Types

Property	Type	Description
`type`	`String` (optional)	Identifies the fragment type , Default: `"binary"`.
`mime_type`	`String`	MIME type, for example `"image/png"`
`id`	`String` (optional)	Reference to previously uploaded content , Default: `nil`.
`url`	`String` (optional)	Remote URL where the content can be retrieved , Default: `nil`.
`data`	`String` (optional)	Base64 encoded content , Default: `nil`.
`filename`	`String` (optional)	Optional filename hint , Default: `nil`.

DeveloperMessage

AgUiProtocol::Core::Types::DeveloperMessage

Represents a message from a developer.


msg = AgUiProtocol::Core::Types::DeveloperMessage.new(
    id: "dev_1",
    content: "You are a helpful assistant."

)

@category [] Message Types

Property	Type	Description
`id`	`String`	Unique identifier for the message
`content`	`Object`	Text content of the message (required)
`name`	`String` (optional)	Optional name of the sender , Default: `nil`.

Role

AgUiProtocol::Core::Types::Role

Represents the possible roles a message sender can have.


AgUiProtocol::Core::Types::Role # => ["developer", "system", "assistant",
"user", "tool", "activity"]

@category [] Message Types

SystemMessage

AgUiProtocol::Core::Types::SystemMessage

Represents a system message.


msg = AgUiProtocol::Core::Types::SystemMessage.new(
    id: "sys_1",
    content: "Follow the protocol."

)

@category [] Message Types

Property	Type	Description
`id`	`String`	Unique identifier for the message
`content`	`Object`	Text content of the message (required)
`name`	`String` (optional)	Optional name of the sender , Default: `nil`.

TextInputContent

AgUiProtocol::Core::Types::TextInputContent

Represents a text fragment inside a multimodal user message.


content = AgUiProtocol::Core::Types::TextInputContent.new(text: "hello")

@category [] Message Types

Property	Type	Description
`text`	`String`	Text content
`type`	`String` (optional)	Identifies the fragment type , Default: `"text"`.

ToolMessage

AgUiProtocol::Core::Types::ToolMessage

Tool result message.


msg = AgUiProtocol::Core::Types::ToolMessage.new(
    id: "tool_msg_1",
    tool_call_id: "tc_1",
    content: "ok"

)

@category [] Message Types

Property	Type	Description
`id`	`String`	Unique identifier for the message.
`content`	`String`	Tool result content.
`tool_call_id`	`String`	ID of the tool call this message responds to.
`error`	`String` (optional)	Error payload if the tool call failed. , Default: `nil`.

UserMessage

AgUiProtocol::Core::Types::UserMessage

Represents a message from a user.


msg = AgUiProtocol::Core::Types::UserMessage.new(
    id: "user_2",
    content: [
      { type: "text", text: "Please describe this image" },
      { type: "binary", mimeType: "image/png", url: "https://example.com/cat.png" }
    ]

)

@category [] Message Types

Property	Type	Description
`id`	`String`	Unique identifier for the message
`content`	`String , Array<TextInputContent , BinaryInputContent>`	Either a plain text string or an ordered list of multimodal fragments
`name`	`String` (optional)	Optional name of the sender , Default: `nil`.

State

State is represented as Any.

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