Skip to main content
运行时负责组织模型调用、工具执行和结果返回。VeADK 默认使用 Google ADK;需要编码类执行后端时,可以选择 codex 或 piagent。切换前应检查工具、模型配置和回调的兼容性 以下示例均需先完成模型配置。火山引擎与 BytePlus 分别使用对应平台的模型端点和 API Key

默认运行时

不设置 runtime 时等同于 runtime="adk",适用于标准模型调用、结构化输出和工具协作
main.py
运行 python main.py 可看到最终文本回复。需要处理事件和流式输出时使用 Runner.run_async

同步工具并行执行

默认 ADK 运行时中的同步函数可能阻塞其他异步任务。设置 tool_thread_pool_config 后,同步工具可在线程池执行;当模型同一轮发出多个调用时,可并行处理
parallel_tools.py
运行 python parallel_tools.py 可获得两个商品的库存。示例展示配置方式,模型是否同一轮发起多个调用由模型决定;线程池不会主动拆分任务。工具若共享可变数据或连接,需保证并发访问安全 RunConfig.tool_thread_pool_config 优先于 Agent 上的配置。该设置只影响 ADK 同步工具,不控制 codex 或 piagent 的执行机制。并行 run_code 的会话隔离及 VEADK_RUN_CODE_ISOLATE_PARALLEL_CALLS 见代码沙箱

切换执行后端

使用 Codex 运行时

安装包含 SDK 与 CLI 二进制的可选依赖组:
模型仍通过 model_name、model_api_base 和 model_api_key 配置。默认采用隔离工作区、workspace_write、关闭网络和拒绝提权;以下示例显式保留这些设置
codex_runtime.py
运行 python codex_runtime.py。函数工具与 MCP 工具可通过 Agent.tools 注册,本地 ADK SkillToolset 中的技能可交给运行时使用;旧 skills_mode 的限制见下方兼容性表

Codex 安全配置

Agent.codex_runtime_config 接受 CodexRuntimeConfig 或同字段字典
auto_review 会自动批准提权和文件修改请求,不是模型审核步骤。full_access 放宽主机访问,reuse_workspace=True 可能在调用间共享文件;仅在明确需要且可信的环境中设置。network_access=False 不能限制 full_access,该组合会在配置时被拒绝。read_only 也不使用这个网络开关
以下环境变量优先于构造配置:

Codex 可观测性

运行时将生命周期通知、函数和 MCP 工具调用转换为 ADK 事件,可供会话、链路和前端消费。运行日志中的 invocation_id、call_id、tool、status 与 duration_ms 用于关联调用;token 用量通过 codex_event_type=token_usage 事件提供 运行时日志不等同于每次模型调用的完整链路。事件、会话或自行配置的导出器可能包含任务与工具内容,接入日志系统时应控制访问和保留范围

配置临时错误重试

使用 PiAgent

PiAgent 在本机工作目录执行任务,内置工具可能读写文件和执行命令。配置目录隔离不等于操作系统沙箱;请使用可信项目及受限运行环境,并按需限制工具
piagent_runtime.py
运行 python piagent_runtime.py。VeADK 依次查找 PIAGENT_BINARY、托管缓存;未找到时从 Pi Release 下载。下载只有在设置 PIAGENT_BINARY_SHA256 时才校验该摘要。离线与生产环境建议预先安装并指定可执行文件

运行时兼容性

以下是切换到 codex 或 piagent 时需要检查的配置:

智能体转移

transfer_to_agent 允许模型将当前任务转交给智能体树中的其他智能体,由目标继续执行并输出结果。ADK、Codex 与 PiAgent 均支持转交
transfer.py
运行 python transfer.py 后可得到公告文本。转交需要由 Runner 驱动,目标仍在同一次调用上下文中运行;它的 output_key 也会生效。需要固定顺序执行时,使用下节的顺序工作流

输出持久化

output_key 将最终回复保存到会话状态,ADK、Codex 和 PiAgent 均支持。它不是独立的磁盘持久化机制;跨进程保存取决于所选会话存储
pipeline.py
运行 python pipeline.py。规划结果写入 plan,写作智能体通过 {plan} 读取,正文写入 draft。示例打印回复和两个状态值,以便检查传递结果

模型回调

回调可以使用同步或异步函数。ADK 按模型调用执行;外部运行时的前后回调围绕整轮执行,插件回调先于智能体回调。返回 None 表示继续默认处理 修改请求不意味着外部运行时支持全部 ADK 配置,仍需遵循兼容性表。例如不能通过回调假定获得 output_schema 支持
model_callback.py
运行 python model_callback.py:模型正常时输出回答,模型调用失败时返回预设文本。该回调不处理所有初始化、工具或业务错误

将 PDF 转为图片

pdf_to_images_before_model_callback 将输入中的 PDF 字节转为图片,适用于支持图片但不能直接读取 PDF 的模型。PDF 渲染依赖已包含在 VeADK 默认安装中 将可发送给模型服务的文件保存为当前目录的 example.pdf,选择支持图片输入的模型,然后运行以下脚本:
pdf_callback.py
默认最多处理每个 PDF 的前 10 页,渲染比例为 2.0。需要调整时,从同一模块导入 make_pdf_to_images_callback,通过 max_pages 和 scale 创建回调。更多页面或更高比例会增加图片数量、内存占用和模型输入用量

按工具选择执行位置

RuntimeProvider 决定单个工具调用如何执行,通常用于保留 ADK 流程而把部分工具交给自有服务。DispatchRuntimeProvider 调用你提供的派发函数;LocalRuntimeProvider 执行原有工具。需要自定义完整策略时,继承 RuntimeProvider 并实现 execute(tool_call)

使用示例

以下示例使用本地演示适配函数模拟服务结果,可验证派发后的库存为 12,原始工具返回的 0 不会再次执行。它不连接实际远端服务
dispatch.py
接入真实服务时,将 dispatch_task 替换为已配置认证与超时的客户端调用,用 tool_call.id 关联请求。派发函数可以同步或异步,并应返回可作为工具结果的数据。服务接口由应用自行约定 也可将 runtime_provider.before_tool_callback 传给 Agent.before_tool_callback;不要同时注册两个入口,否则会重复拦截。MCP 工具仍使用自身连接执行,不受派发范围影响

DispatchRuntimeProvider 参数

ToolCall 字段

请求处理

run_processor 包裹 Runner.run 的整轮事件流,用于鉴权、计时、清理或事件转换。优先级依次为:本次 Runner.run(run_processor=...)、Runner 构造配置、根智能体配置,最后是默认的透传处理器。直接调用 run_async 不会自动使用这一包装 身份认证可使用 veadk.integrations.ve_identity.AuthRequestProcessor,并传给 Agent(run_processor=...);所需身份配置见入站认证

自定义处理器

继承 BaseRunProcessor 并实现 process_run(runner, message, **kwargs)。下面的处理器转发事件,并在正常结束、失败或取消时记录耗时和关闭事件流
run_processor.py
运行 python run_processor.py 可看到回复及执行耗时。处理器若包含重试,应先确认任务是否已产生外部副作用,避免重复执行
最后修改于 2026年9月19日