跳转到主要内容
运行时负责组织模型调用、工具执行和结果返回。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 也不使用这个网络开关
以下环境变量优先于构造配置:

模型传输模式

model_transport 决定 Codex 如何访问模型和执行工具: auto 模式下,火山引擎方舟(*.volces.com)、BytePlus ModelArk(*.bytepluses.com)和 api.openai.com 的端点使用 direct,其他端点使用 shim

线程恢复

thread_mode="resume" 时,每个会话保持一个 Codex 线程。线程的 rollout 随会话一起存储(使用数据库会话存储时保存在数据库中),后续调用恢复该线程,Codex 保留自身完整历史而无需重放对话。ephemeral 模式每次调用创建新的临时线程
线程恢复仅在 direct 传输模式下生效。shim 模式始终使用临时线程,因为适配层执行的工具不会进入 Codex 的历史记录。线程恢复依赖会话存储的持久性;使用内存会话存储时,线程不会在进程重启后保留

运行时转向

Runner.steer(session_id, text) 在当前正在运行的轮次中插入一条附加指令,无需开始新的轮次。智能体在执行过程中调整方向而不丢失已有进展
steer.py
steer 返回 True 表示指令已送达正在运行的轮次,False 表示当前没有正在运行的轮次或运行时不支持转向。仅在 direct 传输模式下支持,且轮次必须在当前进程内运行

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 时才校验该摘要。离线与生产环境建议预先安装并指定可执行文件

使用 DeepSeek Harness 运行时

DeepSeek Harness 运行时将智能体内层循环交给 DeepSeek Harness SDK 执行。安装时通过 Python extra 获取二进制,运行时懒启动子进程,不依赖首次运行下载 安装包含 SDK 与匹配二进制的可选依赖组:
veadk-python[dsh] 依赖 deepseek-harness-sdk,该 SDK 再依赖匹配版本的 deepseek-harness-runtime-bin。dsh 可执行文件随 wheel 安装,VeADK 不在运行时下载二进制。导入 VeADK 或构造 Agent 不会启动 DSH;第一次执行到运行时入口时 SDK 才拉起子进程 同一有效配置复用一个 SDK 对象和 DSH 子进程;同一 VeADK app/user/session/agent 映射到稳定的 DSH 会话标识。VeADK 会话历史作为短期记忆的事实来源,以结构化形式序列化进 prompt;DSH 会话标识保持稳定但不作为唯一记忆来源 ADK 函数工具与 MCP 工具在 DSH 运行前展开,通过生成的工具插件和带鉴权的本地回调服务执行。sub_agents 使用与其他外部运行时相同的注入式转交路径。ADK SkillToolset 与 legacy 技能会被物料化到隔离目录,注册为 DSH 原生技能插件。根会话的 DSH 流式输出映射为 ADK partial 事件,DSH 原生工具事件映射为 ADK 函数调用/响应事件 模型仍通过 model_name、model_api_base 和 model_api_key 配置。以下示例使用火山引擎方舟端点:
dsh_runtime.py
运行 python dsh_runtime.py 可看到最终文本回复 provider 是面向用户的 provider 名称,默认 deepseek-official。openai、volcengine、volcengine-ark、ark、openai-compatible 和 third-party 均映射到当前 DSH 的 deepseek-official adapter;未知 provider 名称原样透传,供未来 DSH 原生 adapter 使用。base_url 和 api_key 未在配置中设置时,分别回退到 Agent.model_api_base 和 Agent.model_api_key 未配置 dsh_home 时,VeADK 生成进程隔离目录并显式传给 SDK,不会隐式使用 ~/.dsh。需要跨进程保留 DSH 会话时,显式配置 dsh_home

DSH 配置

Agent.deepseek_harness_runtime_config 接受 DeepSeekHarnessRuntimeConfig 或同字段字典 以下环境变量优先于构造配置:
enable_skills_checklist 不会在 DSH 原生技能加载器内执行。DSH 子智能体会话的通知尚未投影为一等子会话事件。这两项与 codex、piagent 的差异见下方兼容性表

运行时兼容性

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

智能体转移

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

输出持久化

output_key 将最终回复保存到会话状态,ADK、Codex、PiAgent 和 DSH 均支持。它不是独立的磁盘持久化机制;跨进程保存取决于所选会话存储
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年10月16日