跳到主要内容

类型

@ag-ui/core 的核心类型:RunAgentInput、消息、内容片段、工具与状态。

核心类型

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 | DocumentPart

PartSource

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
  | ReasoningMessage

ToolCall

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>
}

各类别的完整类型定义与用法见能力。

Type to search…

↑↓ navigate↵ selectEsc close