Support non-ADK agent transfer

[FirstayZheng]

背景

Codex/PiAgent 这类非 ADK 原生 runtime 会进入各自的 reasoning / tool loop，不再继续走 Google ADK AutoFlow。ADK AutoFlow 原生动态注入的 transfer_to_agent(...) 因此不会自动存在，导致配置了 sub_agents 的 Agent 在非 ADK runtime 下无法完成 agent transfer。

这个 PR 的目标是：在不重新依赖 ADK AutoFlow 的前提下，为非 ADK runtime 恢复 ADK 兼容的 agent transfer 语义。

总体方案

• 新增公共 transfer 兼容层 veadk.runtime.agent_transfer：
  • 复用 ADK TransferToAgentTool 暴露标准 transfer_to_agent；
  • 按 ADK agent tree 规则计算可转移目标，包括 child / parent / peer，并排除 single_turn、task 等不可转移 agent；
  • 给 LLM request 追加可用目标 agent 的 transfer instruction；
  • 从 ADK Event 中识别 actions.transfer_to_agent；
  • transfer 发生后调用目标 agent 的 run_async，并保留 output_key 写 state 的行为。

Codex runtime

• 在 Codex runtime 初始化工具时注入 transfer_to_agent，让 Codex 的 Responses/tool loop 能看到和 ADK AutoFlow 等价的 transfer tool。
• 在 before_model_callback 之后重新同步 tool bundle，确保 callback 对工具集合的增删改会反映到 Codex shim 中。
• Codex tool executor 将 actions.transfer_to_agent 映射成结构化 status="transferred"，用于 runtime/proxy 判断 transfer 已发生。
• Codex Responses shim 在检测到 transfer tool output 后，会返回一个最小 completed response，避免继续发起第二次模型调用；真正的目标 agent 执行由 VeADK runtime 接管。
• Codex runtime 在收到 transfer event 后：
  • 对普通运行场景直接执行目标 agent，并把目标 agent event 继续 yield 出去；
  • 对 ADK 2.x 外层 scheduler 场景，延迟交还 transfer event，避免和 ADK 自己的 transfer 调度重复执行；
  • transfer 后清空 root final text buffer，避免 router transfer 后的文本泄漏。

PiAgent runtime

• 先补齐 PiAgent 工具生命周期，使 PiAgent tool bridge 走 ADK tool callback 语义：
  • 支持 before/after tool callback；
  • 支持工具确认、鉴权恢复、callback 改写工具结果；
  • 支持 before_model_callback 修改后的 tools_dict 回写到 PiAgent extension；
  • 正确关闭 MCP/toolset 生命周期。
• 在 PiAgent runtime 中注入 transfer_to_agent，并把 transfer instruction 一起写入 prompt。
• PiAgent tool executor 同样将 actions.transfer_to_agent 映射成 status="transferred"。
• PiAgent runtime 在收到 transfer event 后执行目标子 agent，并停止 root PiAgent 后续输出，避免 router 文本泄漏。

测试覆盖

• 公共 transfer 测试：
  • get_transfer_targets 覆盖 ADK child / parent / peer 规则；
  • append_transfer_instructions 覆盖 transfer instruction 生成；
  • run_transferred_agent 覆盖目标 agent 执行和 output_key 写 state。
• Codex 测试：
  • transfer tool executor 能产出 ADK actions.transfer_to_agent；
  • Responses shim 在 transfer 后完成当前 turn，不触发第二次模型调用；
  • Codex runtime transfer 后继续执行目标 agent；
  • 覆盖 callback/tool bundle 同步、认证/确认工具恢复、MCP toolset 等既有工具链路，避免 transfer 接入破坏原有行为。
• PiAgent 测试：
  • transfer tool executor 能产出 ADK actions.transfer_to_agent；
  • 单 worker transfer 后执行目标 agent；
  • 多子 agent 能按 agent_name 精确路由到 planner / coder / reviewer；
  • 非法 target 会明确报错，不会误进入已有子 agent；
  • transfer instruction 注入 prompt；
  • before_model_callback 可以删除 transfer tool；
  • PiAgent 工具生命周期、MCP toolset、toolset close、callback 改写工具结果等行为保持可用。

验证

• uv run pre-commit run --files veadk/runtime/agent_transfer.py veadk/runtime/codex/proxy.py veadk/runtime/codex/runtime.py veadk/runtime/codex/tools_bridge.py veadk/runtime/piagent/runtime.py veadk/runtime/piagent/tool_runtime.py veadk/runtime/piagent/tools_bridge.py veadk/runtime/piagent/translate.py tests/runtime/test_agent_transfer.py tests/runtime/codex/test_codex_runtime.py tests/runtime/piagent/test_piagent_runtime.py
  • 结果：Passed
• uv run pytest tests/runtime/piagent/test_piagent_runtime.py tests/runtime/test_agent_transfer.py tests/runtime/codex/test_codex_runtime.py
  • 结果：82 passed, 9 warnings
• 使用本地临时真实模型 E2E 脚本验证 PiAgent root 转给真实 LLM worker：
  • root 使用 runtime="piagent"；worker 使用真实 LLM Agent；
  • 模型参数来自仓库 .env，MODEL_AGENT_API_BASE 显式使用 https://ark.cn-beijing.volces.com/api/v3/；
  • 结果：出现 CALL transfer_to_agent {"agent_name": "worker"}、TRANSFER_ACTION worker，最终 worker 输出 PIAGENT_REAL_LLM_WORKER_OK。
• 已做云端 AgentKit PiAgent smoke：
  • runtime r-yeu2jhhkowdvde9li1qa
  • /run_sse 返回 200
  • 日志出现 piagent: generated tool extension for ['transfer_to_agent'] 和 tool=transfer_to_agent status=transferred
  • 最终事件 author 为 worker。