核心类型
Agent User Interaction Protocol SDK 建立在一组核心类型之上,它们构成系统中使用的基础结构。本页记录这些类型及其属性。
RunAgentInput
运行智能体的输入参数。在 HTTP API 中,它就是 POST 请求体。
tools 包含客户端为本次运行提供的工具。后端自带的工具应留在后端智能体或框架配置中,并可通过智能体能力单独公告。
type RunAgentInput = {
threadId: string
runId: string
parentRunId?: string
state?: any // 缺省即“无状态”;裸 null 也按缺省处理
messages: Message[]
tools: Tool[]
context: Context[]
forwardedProps: any
resume?: ResumeEntry[]
}| 属性 | 类型 | 说明 |
|---|---|---|
threadId |
string |
会话线程 ID |
runId |
string |
当前运行 ID |
parentRunId |
string(可选) |
派生出本次运行的运行 ID |
state |
any(可选) |
智能体当前状态;缺省表示“无状态”,裸 null 也读作缺省 |
messages |
Message[] |
会话中的消息数组 |
tools |
Tool[] |
本次运行可用的客户端工具 |
context |
Context[] |
提供给智能体的上下文对象数组 |
forwardedProps |
any |
转发给智能体的附加属性 |
resume |
ResumeEntry[](可选) |
针对上个运行中断结果的逐中断响应 |
ResumeEntry
RunAgentInput.resume 中每个中断对应一条,用于回应上一个运行留下的中断。
type ResumeEntry = {
interruptId: string
status: "resolved" | "cancelled"
payload?: any
metadata?: Record<string, any>
}| 属性 | 类型 | 说明 |
|---|---|---|
interruptId |
string |
本条响应对应的中断 ID |
status |
"resolved" | "cancelled" |
用户已作答,或放弃了该中断 |
payload |
any(可选) |
响应本身,按中断的 responseSchema 校验 |
metadata |
Record<string, any>(可选) |
关于响应的信封数据——签名、路由键——绝不是答案本身 |
metadata 遵循协议各处的约定:按 key 开放,任意 JSON 值(含 null),对象本身可缺省但永不为 null,ag-ui 键保留给协议。resume 条目是请求字段,因此不参与合并。
消息类型
说明: 每种消息类型都携带可选的
metadata(Record<string, any>),ToolCall亦然;下表为简洁起见省略。它按 key 开放——任意 JSON 值(含null)——对象可缺省但永不为null。ag-ui键保留给 AG-UI 自用。消息由事件构建时 metadata 会累积,合并规则见 Metadata。
Role
type Role =
| "developer"
| "system"
| "assistant"
| "user"
| "tool"
| "activity"
| "reasoning"DeveloperMessage
type DeveloperMessage = {
id: string
role: "developer"
content: string
name?: string
}| 属性 | 类型 | 说明 |
|---|---|---|
id |
string |
消息唯一标识 |
role |
"developer" |
固定为 "developer" |
content |
string |
文本内容(必填) |
name |
string |
可选发送者名称 |
SystemMessage
type SystemMessage = {
id: string
role: "system"
content: string
name?: string
}AssistantMessage
type AssistantMessage = {
id: string
role: "assistant"
content?: string
name?: string
toolCalls?: ToolCall[]
}| 属性 | 类型 | 说明 |
|---|---|---|
id |
string |
消息唯一标识 |
role |
"assistant" |
固定为 "assistant" |
content |
string(可选) |
文本内容 |
name |
string(可选) |
发送者名称 |
toolCalls |
ToolCall[](可选) |
本消息发起的工具调用 |
UserMessage
type UserMessage = {
id: string
role: "user"
content: string | ContentPart[]
name?: string
}content 既可以是纯文本,也可以是按序排列的多模态内容片段数组。
ContentPart
支持的内容片段联合。同样的片段也可出现在 ToolMessage 上:工具结果是一个字符串或它们组成的列表。每个片段可带可选 id;metadata 不受约束,文本搜索命中可借此保存来源与标题。
type ContentPart = TextPart | ImagePart | AudioPart | VideoPart | DocumentPartPartSource
type PartSource = DataSource | UrlSource | FileSource
type DataSource = {
type: "data"
value: string
mimeType: string
}
type UrlSource = {
type: "url"
value: string
mimeType?: string
}
type FileSource = {
type: "file"
value: string // 句柄,与提供方签发的完全一致
provider?: string // 签发者,例如 "openai"、"anthropic"、"google"
mimeType?: string
}FileSource 指向已经位于模型提供方一侧的字节——OpenAI 或 Anthropic 的文件 id、Gemini 的文件 URI。不会拉取任何内容,value 是不透明的:智能体把它交给自己的提供方,或丢弃该片段,绝不将其当作 URL。
TextPart / ImagePart / AudioPart / VideoPart / DocumentPart
type TextPart = {
type: "text"
id?: string
text: string
metadata?: unknown
}
type ImagePart = {
type: "image"
id?: string
source: PartSource
metadata?: unknown
}AudioPart、VideoPart、DocumentPart 与 ImagePart 结构一致,仅 type 不同。
ToolMessage
type ToolMessage = {
id: string
content: string | ContentPart[]
role: "tool"
toolCallId: string
error?: string
encryptedValue?: string
}| 属性 | 类型 | 说明 |
|---|---|---|
content |
string | ContentPart[] |
文本内容或内容片段 |
toolCallId |
string |
本条消息回应的工具调用 ID |
error |
string(可选) |
工具调用失败时的错误信息 |
encryptedValue |
string(可选) |
通过签名附加的加密值 |
ActivityMessage
type ActivityMessage = {
id: string
role: "activity"
activityType: string
content: Record<string, any>
}| 属性 | 类型 | 说明 |
|---|---|---|
activityType |
string |
用于选择渲染器的活动判别字段 |
content |
Record<string, any> |
表示活动状态的结构化载荷 |
ReasoningMessage
type ReasoningMessage = {
id: string
role: "reasoning"
content: string
encryptedValue?: string
}Message
type Message =
| DeveloperMessage
| SystemMessage
| AssistantMessage
| UserMessage
| ToolMessage
| ActivityMessage
| ReasoningMessageToolCall
type ToolCall = {
id: string
type: "function"
function: FunctionCall
encryptedValue?: string
}FunctionCall
type FunctionCall = {
name: string
arguments: string // JSON 编码的参数字符串
}Context
type Context = {
description: string
value: string
}Tool
type Tool = {
name: string
description: string
parameters: any // JSON Schema
}State
type State = any状态类型是灵活的,可承载智能体实现所需的任意数据结构。
AgentCapabilities
getCapabilities() 返回的类型化能力声明。所有字段都是可选的——智能体只声明自己支持的部分。
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>
}各类别的完整类型定义与用法见能力。