核心类型
AG-UI Python SDK 建立在一组核心类型之上。所有模型都由 Pydantic 定义,序列化到线路时使用 camelCase。
RunAgentInput
from ag_ui.core import RunAgentInput
class RunAgentInput(ConfiguredBaseModel):
thread_id: str
run_id: str
parent_run_id: Optional[str] = None
state: Any = None # 可缺省:缺省表示“无状态”;裸 null 也读作缺省
messages: List[Message]
tools: List[Tool]
context: List[Context]
forwarded_props: Any
resume: Optional[List[ResumeEntry]] = None| 属性 | 类型 | 说明 |
|---|---|---|
thread_id |
str |
会话线程 ID |
run_id |
str |
当前运行 ID |
parent_run_id |
Optional[str] |
派生出本次运行的运行 ID |
state |
Any |
智能体当前状态;缺省表示“无状态” |
messages |
List[Message] |
会话消息 |
tools |
List[Tool] |
本次运行可用的客户端工具 |
context |
List[Context] |
上下文对象 |
forwarded_props |
Any |
转发给智能体的附加属性 |
resume |
Optional[List[ResumeEntry]] |
针对上个运行中断结果的逐中断响应 |
ResumeEntry
from ag_ui.core import ResumeEntry
class ResumeEntry(GeneratedBaseModel):
interrupt_id: str
status: ResumeStatus # "resolved" | "cancelled"
payload: Optional[Any] = None
metadata: Optional[Metadata] = None| 属性 | 类型 | 说明 |
|---|---|---|
interrupt_id |
str |
本条响应对应的中断 ID |
status |
ResumeStatus |
用户已作答为 resolved,放弃为 cancelled |
payload |
Optional[Any] |
响应本身,按中断的 response_schema 校验 |
metadata |
Optional[Dict[str, Any]] |
信封数据:签名、路由键;绝不是答案本身 |
metadata 遵循协议各处的约定:按 key 开放,任意 JSON 值(含 None),对象可缺省但线上永不为 null,ag-ui 键保留。resume 条目是请求字段,不参与合并。
消息类型
说明: 每种消息类型都携带可选
metadata(Optional[Dict[str, Any]]),ToolCall亦然;下表省略。它按 key 开放(含None),对象可缺省但永不为None。ag-ui键保留给 AG-UI 自用。合并规则见 Metadata。
Role
Role = Literal["developer", "system", "assistant", "user", "tool", "activity", "reasoning"]DeveloperMessage / SystemMessage
class DeveloperMessage(BaseMessage):
role: Literal["developer"]
content: str
class SystemMessage(BaseMessage):
role: Literal["system"]
content: str两者都继承 BaseMessage(含 id、可选 name)。
AssistantMessage
class AssistantMessage(BaseMessage):
role: Literal["assistant"]
content: Optional[str] = None
tool_calls: Optional[List[ToolCall]] = NoneUserMessage
class UserMessage(BaseMessage):
role: Literal["user"]
content: Union[str, List["ContentPart"]]content 是纯文本或按序排列的多模态片段列表。
PartSource
PartSource = Annotated[
Union[DataSource, UrlSource, FileSource],
Field(discriminator="type"),
]
class DataSource(ConfiguredBaseModel):
type: Literal["data"]
value: str
mime_type: str
class UrlSource(ConfiguredBaseModel):
type: Literal["url"]
value: str
mime_type: Optional[str] = None
class FileSource(ConfiguredBaseModel):
type: Literal["file"]
value: str # 句柄,与提供方签发的完全一致
provider: Optional[str] = None # "openai"、"anthropic"、"google"
mime_type: Optional[str] = NoneFileSource 指向模型提供方一侧已存在的字节——OpenAI 或 Anthropic 的文件 id、Gemini 文件 URI。不会拉取任何内容,value 对协议不透明。
TextPart
class TextPart(ConfiguredBaseModel):
type: Literal["text"]
id: Optional[str] = None
text: str
metadata: Optional[Any] = NoneImagePart / AudioPart / VideoPart / DocumentPart
class ImagePart(ConfiguredBaseModel):
type: Literal["image"]
id: Optional[str] = None
source: PartSource
metadata: Optional[Any] = NoneAudioPart、VideoPart、DocumentPart 结构相同,仅 type 不同。
BinaryInputContent(已弃用)
class BinaryInputContent(ConfiguredBaseModel):
type: Literal["binary"]
mime_type: str
id: Optional[str] = None
url: Optional[str] = None
data: Optional[str] = None
filename: Optional[str] = Noneid、url、data 至少提供一项。该模型仅为临时兼容保留,请优先使用上面的模态专属片段。
ToolMessage
class ToolMessage(ConfiguredBaseModel):
id: str
role: Literal["tool"]
content: Union[str, List[ContentPart]]
tool_call_id: str
error: Optional[str] = None
encrypted_value: Optional[str] = NoneActivityMessage
class ActivityMessage(ConfiguredBaseModel):
id: str
role: Literal["activity"]
activity_type: str
content: Dict[str, Any]ReasoningMessage
class ReasoningMessage(ConfiguredBaseModel):
id: str
role: Literal["reasoning"]
content: str
encrypted_value: Optional[str] = NoneMessage
Message = Annotated[
Union[
DeveloperMessage, SystemMessage, AssistantMessage,
UserMessage, ToolMessage, ActivityMessage, ReasoningMessage,
],
Field(discriminator="role"),
]ToolCall / FunctionCall
class ToolCall(ConfiguredBaseModel):
id: str
type: Literal["function"]
function: FunctionCall
encrypted_value: Optional[str] = None
class FunctionCall(ConfiguredBaseModel):
name: str
arguments: str # JSON 编码的参数字符串Context
class Context(ConfiguredBaseModel):
description: str
value: strTool
class Tool(ConfiguredBaseModel):
name: str
description: str
parameters: Any # JSON SchemaState
State = Any