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 或同字段字典
以下环境变量优先于构造配置:
Codex 可观测性
运行时将生命周期通知、函数和 MCP 工具调用转换为 ADK 事件,可供会话、链路和前端消费。运行日志中的invocation_id、call_id、tool、status 与 duration_ms 用于关联调用;token 用量通过 codex_event_type=token_usage 事件提供
运行时日志不等同于每次模型调用的完整链路。事件、会话或自行配置的导出器可能包含任务与工具内容,接入日志系统时应控制访问和保留范围
配置临时错误重试
使用 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
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 可看到回复及执行耗时。处理器若包含重试,应先确认任务是否已产生外部副作用,避免重复执行