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.

type RunAgentInput = {
  threadId: string;
  runId: string;
  parentRunId?: string;
  state: any;
  messages: Message[];
  tools: Tool[];
  context: Context[];
  forwardedProps: any;
};

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	Current state of the agent
messages	Message[]	Array of messages in the conversation
tools	Tool[]	Array of tools available to the agent
context	Context[]	Array of context objects provided to the agent
forwardedProps	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

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.