Skip to content

fix(responses): 支持 Codex 官方多智能体 v2 协作协议与子任务明文提取 - #44

Closed
ItQianChen wants to merge 1 commit into
maiphucgiang:mainfrom
ItQianChen:main
Closed

ItQianChen wants to merge 1 commit into
maiphucgiang:mainfrom
ItQianChen:main

Conversation

@ItQianChen

@ItQianChen ItQianChen commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

描述 (Description)

1. 背景与问题 (Background)

在 Codex 官方客户端通过 /v1/responses 接口调用多智能体协作(Multi-Agent v2)时,存在两个核心协议层兼容问题:

  1. 协作工具丢失:Codex 客户端将协作工具(spawn_agent, send_message, followup_task, wait_agent 等)打包在 type: "namespace" 类型的 collaboration 命名空间中。原有的 _convert_tools_for_chat 仅处理 type: "function" 的顶层工具,导致所有协作工具被静默丢弃,模型在执行时报“协作工具未暴露”。
  2. 任务 Payload 丢失:Codex 在派发子智能体任务(NEW_TASK)以及回传结果(FINAL_ANSWER)时,会将正文挂载在 agent_message 的 encrypted_content 属性中(内容为明文)。原有内容提取函数 _extract_content 仅支持 input_text/text/output_text,导致任务正文被丢弃,子智能体收到空 Payload 并陷入“我是谁、查什么”的身份迷航。

2. 主要改动 (Key Changes)

  • 递归解包命名空间工具:
    • 在 app/adapters/responses_adapter.py 的 _convert_tools_for_chat 中增加对 type: "namespace" 的递归提取与去重,拍平为标准 Chat Completions function 工具。
    • 新增 _build_tool_namespace_map,在 ResponsesStreamConverter 中建立双向命名空间映射;当模型输出 spawn_agent 等调用时,在 function_call 事件中准确补回 "namespace": "collaboration",满足 Codex 客户端识别需求。
  • 支持 encrypted_content 正文提取:
    • 在 _extract_content 中增加对 type: "encrypted_content" 的提取分支,读取 encrypted_content 属性并将文本无缝拼接回任务正文中。
  • 工具入参 Schema 规范化:
    • 在转换工具定义时,递归剥离 parameters.properties 中的 "encrypted": true 客户端专用标记,输出标准的 JSON Schema,避免严格校验的下游模型网关报错。
  • 请求体纯净化:
    • 在 converter.py 的流式与非流式调用中,发往后端请求体时自动剔除用于内部映射的临时元数据键 _tool_namespaces。

3. 验证与测试 (Verification)

  1. 单元测试:
    • 在 tests/test_responses_adapter.py 中新增 test_encrypted_content_and_namespace_tools 测试用例,覆盖 namespace 工具展开、agent_message 提取及 namespace 事件还原。
    • 适配器核心测试套件 25 项全量通过(pytest tests/test_responses_adapter.py)。
  2. 端到端实测:
    • 模拟 Codex 官方客户端通过 agent_message + encrypted_content 构造请求打向 /v1/responses,后端模型成功读取正文并正常响应(HTTP 200 OK)。

4. 兼容性 (Compatibility)

  • 纯向后兼容改动,不影响单智能体普通文本对话与常规函数调用逻辑。

- 支持递归解包 `namespace` 命名空间工具,解决直连时 `spawn_agent` 等协作工具被静默丢弃的问题
- 支持提取 `agent_message` 中的 `encrypted_content`,解决子智能体任务 Payload 为空及结果回传丢失问题
- 清理工具参数中的 `"encrypted": true` 私有属性,保证转发给上游的 JSON Schema 格式纯净
- 在 `ResponsesStreamConverter` 中建立双向命名空间映射,回传工具调用时补齐 `namespace: "collaboration"`
- 新增多智能体消息提取与工具解包的单元测试用例

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @ItQianChen, your pull request is larger than the review limit of 500,000 diff characters

@ItQianChen ItQianChen changed the title fix(responses): 支持 Codex 官方多智能体 v2 协作协议与子任务明文提取fix(responses): 支持 Codex 官方多智能体 v2 协作协议与子任务明文提取 fix(responses): 支持 Codex 官方多智能体 v2 协作协议与子任务明文提取 Sep 26, 2026
@maiphucgiang

Copy link
Copy Markdown
Owner

感谢补充 Codex 多智能体兼容支持。但是这个 PR 目前存在大量行尾差异及工具身份映射问题,请基于上游最新 main 新建独立功能分支,完成以下调整后重新提交新PR:

  1. 统一行尾为 LF
    三个修改文件混入大量 CRLF,导致实际约 +192 / -13 的修改膨胀为 +5645 / -5466 。请清除无关行尾差异,保持最小改动范围。

  2. 修复工具身份映射
    按 (namespace, name) 区分工具,建立一致、可逆的上游名称映射,并同步处理历史工具调用和 tool_choice。不要按裸名称静默去重,也不要仅凭名称前缀猜测命名空间;未声明命名空间的普通工具应保留原名。

  3. 补充接口级回归测试
    通过 /v1/responses 覆盖非流式、缓冲流式和实时流式,至少验证:

    • 不同命名空间下的同名工具不会丢失或调用错位。
    • 普通工具 collaboration__spawn_agent 不会被擅自改名。
    • 命名空间内名称包含 __ 的工具能够正确还原身份。
    • 内部映射元数据不会发送给上游。

新 PR 请附相关测试结果,并确保说明与实际实现一致。当前 PR 先关闭。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants