Python SDK

Python SDK#

yuanrong.agentruntime.AgentExecutor#

class yuanrong.agentruntime.AgentExecutor#

基类：ABC

Agent 开发者必须继承的抽象基类，定义了 Agent 的生命周期方法。

方法：

init

初始化 Agent，在 SessionContext 绑定时调用一次。

execute

处理一次调用请求，返回 Complete 或 InputRequired。

yuanrong.agentruntime.SessionContext#

class yuanrong.agentruntime.SessionContext(session_context_id: str, event_log: EventLog)#

基类：object

Agent 的会话上下文，在 init() 阶段传入，用于获取会话 ID 和事件日志。

参数：

  • session_context_id – 会话上下文 ID。

  • event_log – EventLog 实例。

属性：

id

获取会话上下文 ID。

event_log

获取 EventLog 实例。get() 可在 init() 和 execute() 阶段使用；append() 仅可在 execute() 的活跃请求期间调用。

yuanrong.agentruntime.RequestContext#

class yuanrong.agentruntime.RequestContext(session_context: SessionContext, turn_id: str, message: Any, output: OutputWriter)#

基类：object

单次调用请求的上下文，在 execute() 阶段传入，包含输入、输出、Turn ID 等信息。

构造函数接收原始 message，框架内部自动将其包装为 RequestInput 对象，通过 input 属性访问。

属性：

session_context

获取当前请求所属的 SessionContext。

turn_id

获取当前 Turn 的 ID。

input

获取请求输入，类型为 RequestInput。

output

获取输出写入器，类型为 OutputWriter。

is_active

检查当前请求是否仍处于活跃状态。

yuanrong.agentruntime.RequestInput#

class yuanrong.agentruntime.RequestInput(message: Any)#

基类：object

请求输入的封装，为 frozen dataclass。

参数：

  • message – 调用方传入的原始消息。

属性：

message

获取调用方传入的原始消息。

yuanrong.agentruntime.OutputWriter#

class yuanrong.agentruntime.OutputWriter#

基类：object

流式输出写入器，用于在 execute() 中向客户端发送中间结果。写入的数据会先持久化再发送到 SSE 流。

方法：

write

向 SSE 流写入一条中间结果。

yuanrong.agentruntime.EventLog#

class yuanrong.agentruntime.EventLog#

基类：object

事件日志的读写接口，用于在 init() 和 execute() 阶段读取历史事件或追加自定义事件。

方法：

get

获取事件日志列表。

append

追加一条自定义事件到日志。

yuanrong.agentruntime.Event#

class yuanrong.agentruntime.Event#

基类：object

事件日志中的单条事件记录，为 frozen dataclass。由框架内部创建（EventLog.get() 返回、EventLog.append() 返回），用户无需自行构造。

属性：

session_context_id

会话上下文 ID。

turn_id

Turn ID。

seq

事件序号。

event_id

事件唯一 ID。

source

事件来源，"PLATFORM" 或 "SDK"。

type

事件类型。

data

事件数据。

schema_version

Schema 版本。

created_at

事件创建时间。

yuanrong.agentruntime.Complete#

class yuanrong.agentruntime.Complete(value: Any)#

基类：object

表示 Agent 执行完成，为 frozen dataclass。作为 execute() 的返回值，表示当前 Turn 已结束。

参数：

  • value – Agent 返回的结果数据。

yuanrong.agentruntime.InputRequired#

class yuanrong.agentruntime.InputRequired(value: Any)#

基类：object

表示 Agent 需要额外输入才能继续，为 frozen dataclass。作为 execute() 的返回值，表示当前 Turn 暂停，等待用户输入。

参数：

  • value – Agent 返回的中间结果数据。

yuanrong.agentruntime.ExecutionResult#

yuanrong.agentruntime.ExecutionResult#

类型别名，等价于 Union[Complete, InputRequired]。execute() 的返回类型标注为此类型。

yuanrong.agentruntime.AgentRuntimeError#

class yuanrong.agentruntime.AgentRuntimeError(code: str, message: str)#

基类：RuntimeError

Agent Runtime 的基础错误类型，包含稳定的机器可读错误码。

参数：

  • code – 错误码。

  • message – 错误信息。

子类：

AgentRuntimeNotConfigured

Agent Runtime 未配置初始化器。

SessionContextBindingMismatch

调用标识与 Agent Runtime 实例绑定的 SessionContext 不匹配。

AgentExecutorLoadFailed

加载 Agent 类失败。

AgentInitFailed

Agent init() 执行失败。

InvalidExecutionResult

execute() 返回值不是 Complete 或 InputRequired。

OutputNotActive

当前请求已不再活跃时调用 OutputWriter.write()。

EventAppendNotActive

当前请求已不再活跃时调用 EventLog.append()。

EventSerializationFailed

事件序列化失败。

DataSystemError

DataSystem 初始化失败。