双层 Harness:调用方自己也是智能体时
问题是什么
传统的调用是「应用 → 模型」。OAA 是「应用 → 智能体 → 模型」。而调用方往往自己也是一个智能体(Cursor、Cline、Codex CLI、Claude Code、各种 Agent SDK):它有自己的循环、自己的系统提示、自己的工具,把 OAA 当成一个「模型」来调。于是一次调用里有两层 Harness(工具循环):
外层 Harness(调用方智能体:自己的工具、自己的循环)
│ OpenAI / Claude / Gemini 协议 —— 它以为对面是模型,请求里带着 tools
▼
OAA 内核(准入、身份、持久化、审批、事件)
│
▼
内层 Harness(被发布的智能体:内核循环,或 Codex / Claude Code / ACP 智能体自己的循环)
│
▼
模型两层各有一套工具。如果只是把外层的 tools 悄悄丢掉,外层系统提示里「必须调用 edit_file」之类的话会原样交给内层智能体,而内层并没有这个工具,容易在正文里编造工具调用。所以 OAA 让调用方明确选择外层工具怎么处理。
各种模式
明确执行边界
新发布可声明 access.modes、defaultMode、approval 与 trust。密钥里保存的接入默认值让普通客户端只填标准 /v1 地址即可使用,不需要额外请求头。X-OAA-Tool-Boundary 或 metadata["oaa.tool_boundary"] 可显式选择 managed(服务端工具)、client(仅客户端工具)、hybrid(两端工具)。执行前同时检查发布和密钥授权;不支持的边界明确失败,不静默回退。等待中的调用方工具必须先完成或取消,才能更换模型或执行位置。
目前内核智能体能强制执行仅客户端工具模式;不能保证这一点的外部智能体会被拒绝。混合桥接不代表外部智能体自己的工具被禁用。Antigravity 可通过已验证的 agy acp 入口桥接;即使 ACP 同时提供模型族配置,CLI 的完整模型标识仍可选择。新的 Antigravity 审批策略走 ACP,存量发布保留原 headless 路径。
审批策略为 auto、caller、owner。调用方审批需要 approve scope,不能扩大执行上限;只有 approve scope 的调用方不能解决发布者专属审批。native 表示适配器无法转交审批,遵循其原生规则,界面禁用不支持的审批控件。私有发布不能被开发者平台的外部调用者使用,委派也不能绕过。隔离原生执行需要经过验证的沙箱,任务目录不算沙箱。
所有者管理员通过 POST /v1/local/projects 的 {agent,path} 绑定已存在的本机项目,path:null 解除绑定。该智能体有排队、运行或待审批任务时不能更改绑定。access.workspace:"project" 仅限本人可信使用:本机原生进程以绑定项目为工作目录,上传输入和可下载产物仍放在独立任务目录。同目录的原生执行串行化。调用方目录不暴露项目路径,目录绑定明确不是 OS 沙箱;远程 HTTP/A2A 适配器不能使用本机项目工作目录。
发现、模型选择和多模型执行见 models.md。下文旧工具模式请求头继续兼容现有接入。
| 模式 | 含义 | 谁执行工具 | 适用场景 |
|---|---|---|---|
auto 自动(默认) | 知道是哪个智能体之后由网关决定:智能体能接管调用方的工具就按 bridge,否则做该入口原来做的事(见「auto 怎么判定」) | 取决于它选的模式 | 几乎总是:调用方不用知道名字背后是哪一类智能体 |
managed 托管 | 内层智能体全权完成任务。外层传入的工具不执行,并明确告知:响应头 X-OAA-Client-Tools: ignored;同时在交给智能体的输入末尾加一段固定说明(外部工具在这里不可用,请用自己的工具完成并直接给出结果,不要在正文里写工具调用) | 内层智能体 | 把 OAA 智能体当作「会自己干活的模型」接进现有工具,或保持 auto 之前的行为 |
bridge 桥接 | 外层的工具投射给内层智能体;内层调用时运行停车,以标准 tool_calls 返回给调用方,调用方执行后回传结果,同一个运行接着做 | 调用方(由内层发起) | 工具必须在调用方本机执行(例如编辑调用方工作区里的文件) |
reject 拒绝 | 只要传了工具就报错 client_tools_unsupported,不降级 | — | 需要严格语义、不接受工具被忽略的调用方 |
桥接已对内置内核智能体、Codex 与 Claude Code 原生引擎、Antigravity(ACP 路径)及 ACP 外部智能体提供,支持 Chat Completions、Responses、Claude Messages 与 Gemini
generateContent。 不支持桥接的外部智能体(如 DSH、A2A 或 HTTP 适配器)请求bridge会得到client_tools_bridge_unsupported(400),UAP/1 不接受tools字段;这些情况下任何运行都不会创建。
auto 怎么判定
请求声明了工具、又没有选模式,就得到 auto(网关配置 clientTools.default 可以把这个缺省改成 managed、bridge 或 reject;请求头里显式写的 auto 优先于配置)。规则如下,提交时智能体已经知道:
- 智能体能接管工具(内核智能体,或有在线执行机器为它声明了
client-tools-v1的 Codex、Claude Code、Antigravity ACP 或 ACP 适配器智能体),且工具都是普通函数、名字与智能体自己的不重名:请求按bridge处理(tool_choice: "none"本轮不暴露调用方工具;强制tool_choice对内核智能体原生下推至上游模型驱动,对桥接外部智能体注入必调约束并在未命中时执行最多 1 轮会话续接纠正,仍未调用则报 422tool_choice_unmet)。响应带X-OAA-Client-Tools: bridge;智能体的调用以tool_calls/function_call/tool_use/functionCall交回。 - 其它情况得到该入口原来的行为。若请求强制了
tool_choice(required/any或具名函数)而目标无法桥接(或选了managed),提交直接返回 400client_tools_unsupported。否则 OpenAI 默认端点(不带X-OAA-Compat的/v1/chat/completions、/v1/responses)返回 400unsupported_parameter(error.param是tools):信息说明这个智能体接管不了你的工具、原因是什么(不支持桥接的引擎、没有为调用方工具声明支持的执行机器、名字重名、工具不是函数),并写明三条出路:Base URL 用<origin>/v1/compat、X-OAA-Compat: true、X-OAA-Client-Tools: managed。兼容端点、Claude Messages 与 Gemini 照旧按managed(智能体用自己的工具完成;X-OAA-Client-Tools: ignored)。
旧接入继续保留上述自动选择规则。DSH、A2A 和 HTTP 原生/适配器入口仍仅托管;Codex、Claude Code、ACP 适配器及按能力检查的 Antigravity ACP 路径均支持 bridge。选择 auto 不会增加审批权限,新发布与密钥策略按前文优先约束。
只有请求里的 tools 是非空数组时才会按模式处理。没有 tools、或者 tools: [],行为与以前完全相同,模式请求头也不起作用。
怎么选
- 不确定就保持默认的
auto:能用你的工具的智能体拿到工具,其它智能体照旧工作,响应头(bridge或ignored)说明发生了哪一种。 - 调用方必须知道「工具没被执行」并据此改变行为(例如换一个模型)时,用
reject,按错误码分支。 - 智能体必须调用你本机的工具才能完成任务、而且背后是内核智能体、Codex、Claude Code、Antigravity(ACP)或 ACP 外部智能体时,用
bridge。其它外部智能体可以先把这些工具发布成 OAA 智能体自己的工具(MCP 导入或节点工具),再用managed。
怎么传
两种写法,请求头优先:
- 请求头
X-OAA-Client-Tools: auto | managed | bridge | reject(大小写不敏感)。 - 请求体
metadata["oaa.client_tools"],取值同上。
其它取值报 invalid_request(400),消息里列出三个合法值。
Chat Completions(兼容模式),用请求头:
curl http://127.0.0.1:8787/v1/chat/completions \
-H "Authorization: Bearer $OAA_KEY" \
-H "Content-Type: application/json" \
-H "X-OAA-Compat: true" \
-H "X-OAA-Client-Tools: reject" \
-d '{
"model": "agent/coder",
"messages": [{ "role": "user", "content": "修复登录页的报错" }],
"tools": [{ "type": "function", "function": { "name": "edit_file", "parameters": { "type": "object" } } }]
}'Claude Messages,用 metadata:
{
"model": "agent/coder",
"max_tokens": 1024,
"messages": [{ "role": "user", "content": "修复登录页的报错" }],
"tools": [{ "name": "edit_file", "input_schema": { "type": "object" } }],
"metadata": { "oaa.client_tools": "managed" }
}Responses(/v1/compat/responses)与 Gemini(tools[].functionDeclarations)写法相同:带工具的同时加请求头,或在 metadata 里写 oaa.client_tools。
响应头
| 情况 | 响应头 |
|---|---|
智能体继续用自己的工具、且请求确实带了工具(managed,或 auto 回退) | X-OAA-Client-Tools: ignored(流式与非流式都有) |
工具交给了智能体(bridge,或 auto 选了它) | X-OAA-Client-Tools: bridge |
| 没有带工具 | 不出现,响应头集合与以前一致 |
请求里有被接受但不转发的参数(temperature 等,见 protocol.md「兼容入口的参数、错误与结束原因」) | X-OAA-Ignored-Params: <参数名, …>;没有时不出现 |
运行记录的 metadata 里可见实际采用的模式:oaa.client_tools: "managed" 加 oaa.client_tools_ignored: "<工具个数>",或 oaa.client_tools: "bridge"。
当前支持矩阵
接入方式 × 模式(智能体画像 conversion.client_tools 给出每个智能体的取值:内核、Codex、Claude Code 与 ACP 为 bridge,其余为 managed;auto 取其中那一列):
| 智能体接入方式 | managed | reject | bridge |
|---|---|---|---|
内置内核智能体(engine: kernel) | 支持 | 支持 | 支持 ✓(Chat、Responses、Claude Messages、Gemini) |
Codex / Claude Code 原生入口(codex、claude) | 支持 | 支持 | 支持 ✓(经单次运行隔离的 oaa-caller MCP 中继) |
ACP 外部智能体(adapter/<name>,transport: "acp") | 支持 | 支持 | 支持 ✓(经 MCP 中继,见下文「外部智能体的桥接是怎么工作的」) |
已确认 agy acp 能力的 Antigravity | 支持 | 支持 | 经 ACP 混合桥接调用方工具 |
| DSH 原生入口 | 支持 | 支持 | 仅托管:报 client_tools_bridge_unsupported |
| A2A / oaa-1 HTTP 适配器 | 支持 | 支持 | 仅托管:报 client_tools_bridge_unsupported |
桥接运行只会放到在握手里声明了 client-tools-v1、且对这个引擎声明了支持的执行机器上(内置执行机器声明 kernel 以及已启用的 codex、claude、Antigravity ACP 与 ACP 适配器);没有这样的机器时,提交阶段就报 client_tools_bridge_unsupported(400),不会建运行。0.2.0 的旧版远程执行机器不声明这个特性,因此不会收到桥接任务(以前是到执行时才报 manifest_mismatch)。
外部协议 × 模式:
| 接口 | managed | reject | bridge |
|---|---|---|---|
Chat Completions(X-OAA-Compat: true 或 /v1/compat/chat/completions) | 支持 | 支持 | 支持(内核、Codex、Claude Code 与 ACP 智能体) |
Responses(X-OAA-Compat: true 或 /v1/compat/responses) | 支持 | 支持 | 支持(内核、Codex、Claude Code 与 ACP 智能体;只接受 type: "function" 工具) |
Claude Messages(/v1/messages、/v1/compat/messages) | 支持 | 支持 | 支持(内核、Codex、Claude Code 与 ACP 智能体;带 type 的服务端工具被拒) |
Gemini generateContent / streamGenerateContent(/v1beta 与 /v1) | 支持 | 支持 | 支持(内核、Codex、Claude Code 与 ACP 智能体;只接受 functionDeclarations,googleSearch 等内置工具被拒) |
严格接口(不带 X-OAA-Compat 的 /v1/chat/completions、/v1/responses) | 支持(显式写请求头) | 支持(显式写请求头) | 支持(内核、Codex、Claude Code 与 ACP 智能体);没选模式时,不能桥接的智能体被拒绝(见「auto 怎么判定」) |
UAP/1(/v1/uap) | — | — | — |
严格接口和其它入口一样参与各模式;不同的只是 auto 的回退(拒绝,而不是 managed)。旧式的 functions / function_call 在那里仍被拒绝,空的 tools: [] 按没有工具接受。UAP/1 不参与:带 tools 字段会报 invalid_request。
与人工审批的区别
桥接的「等调用方回传工具结果」和人工审批都会让运行停车,但决定权不同:
- 人工审批由 owner(需要
approve权限)决定是否放行已发布工具的某一步。 - 调用方工具的结果由调用方自己回传(同一数据分区、
invoke权限即可),不经过 owner。
托管与拒绝模式不会产生任何待办。
桥接怎么用(内核智能体)
以 Chat Completions 为例,Responses、Claude Messages 与 Gemini 见下一节。
- 第一次请求带上
tools和X-OAA-Client-Tools: bridge。智能体调用到调用方工具时,运行停车,响应是标准的finish_reason: "tool_calls":message.tool_calls列出这一轮全部待执行的调用(并行的多个调用一次给全),id以call_开头,function.arguments是 JSON 字符串,message.content是这一段新产生的文本(没有则为null)。响应头X-Run-ID是运行 ID。 - 调用方执行这些工具,照 OpenAI 的写法在
messages末尾追加role: "tool"消息(tool_call_id填上一步的id),带着同样的tools与请求头再发一次。 - 网关按
tool_call_id找到停车的运行,写入结果,同一个运行接着做(X-Run-ID不变),不需要把历史压平重放。响应只含上次交付之后的新输出:可能是最终结果,也可能是下一批tool_calls。只回传了一部分结果时,运行再次停车并返回剩下的调用。
要点:
- 只有
messages末尾连续的role: "tool"消息算本次回传的结果;更早的历史照旧压平成文本。 - 续接凭据就是
tool_call_id。网关要求它属于同一 owner、同一数据分区(或 owner 级可见的密钥)、对该智能体有invoke权限,且全部属于同一个运行;任何一条不满足(不认识、过期、属于别人)都当作新请求处理,不影响原运行,也不会透露这个 ID 是否存在。 - 同一批结果重复回传(网络重试)不会改写已写入的结果,会接到同一个运行上。
- 流式(
stream: true):停车时依次发出角色帧(之前没发过时,content: null)、每个调用一帧tool_calls增量(index从 0 起)、finish_reason: "tool_calls"收尾帧、(请求了include_usage时)用量帧与[DONE];续接后的流从上次之后开始,不重放之前的文本。 - 模型给出的参数不符合调用方的 schema 时,这次调用不会交给调用方,而是把
{"error":"invalid_arguments","detail":...}作为工具结果交回模型,让它改了再调。这与已发布工具的参数错误(invalid_tool_arguments,运行直接失败)不同:调用方的 schema 不受发布者控制。 - 名字:须匹配
^[a-zA-Z0-9_-]{1,64}$;内部别名把-换成_,首字符不是字母时加t_,对外一律用原名。与已发布的工具、工作流、委托、execute_graph或另一个调用方工具冲突报client_tool_conflict;已发布工具加调用方工具超过 100 个报client_tools_too_many;schema 无法编译报invalid_client_tool。这些都在任何执行之前检查。调用方工具不能出现在execute_graph与工作流里。 - 等待期限沿用网关的
approvalTimeoutMs,到期未回传时运行以client_tool_timeout(409)结束。停车期间不占运行槽,但仍计入未完成请求数上限;可以照常取消。网关重启后,只等调用方的停车运行保持停车,仍可续接。 - 这类待办在
GET /v1/runs/{id}/actions里可见(kind: "client_tool"),但POST /v1/runs/{id}/actions/{action}会报action_kind_mismatch;概览的「需要处理」计数不包含它们(计入进行中,另有awaiting_caller计数),时间线里显示为client_tool类的等待。 - 同一个运行里同时有人工审批时,先按人工审批的既有方式呈现:非流式 Chat / Claude 返回 422
action_required,带x-should-retry: false与运行 ID。调用方不要重发请求(那会新建一个运行):等 owner 用POST /v1/runs/{id}/actions/{action_id}决定之后,用GET /v1/responses/{id}读结果,或者继续回传调用方工具的结果。 - 响应 ID 不随续接改变:续接是同一个运行,返回的仍是同一个
resp_…(Chat 的chatcmpl_resp_…、Claude 的msg_resp_…);调用方续接时把这个 ID 作为previous_response_id传回。这与 OpenAI「每次responses.create一个新 Response」不同,是「一个任务一个 ID、一次计费」的有意设计:以响应 ID 为键缓存历史的客户端(例如 Agents SDK 的会话存储)会看到同一个 ID 的内容被新的一段覆盖,GET /v1/responses/{id}只给最新状态,不保留上一段的function_call快照。需要逐段历史时请在客户端按请求保存。 - 调用方回传的结果写回对话时:能解析成 JSON 对象或数组就按解析后的值写回,否则按原字符串写回、不加引号。
- 待办与协议无关:用一种协议发起的运行可以用另一种协议回传(例如 Chat 发起、Responses 回传),响应按这次请求的协议渲染。原则上建议同一种协议到底。
Responses、Claude Messages 与 Gemini
Responses(/v1/compat/responses,或带 X-OAA-Compat: true 的 /v1/responses):tools 里扁平的 {"type":"function","name",...,"parameters"} 是调用方工具,其它类型(如内置的 web_search)在 bridge 下报 client_tools_unsupported(managed 下照旧忽略)。input 末尾连续的 function_call_output 条目是回传结果;以 call_id 为准找运行,previous_response_id 给了但不是那个运行时按未命中处理。
{ "model": "agent/coder", "input": "修复登录页的报错",
"tools": [{ "type": "function", "name": "edit_file", "parameters": { "type": "object" } }] }停车响应:status: "completed",metadata["oaa.status"] = "requires_action",output 先是本段新文本的 message 条目,再是每个调用一个条目:
{ "type": "function_call", "id": "fc_8c1…", "call_id": "call_8c1…", "name": "edit_file",
"arguments": "{\"path\":\"login.ts\"}", "status": "completed" }回传:
{ "model": "agent/coder", "previous_response_id": "resp_…", "tools": [ … ],
"input": [{ "type": "function_call_output", "call_id": "call_8c1…", "output": "已修改" }] }流式:停车时为每个调用依次发 response.output_item.added(arguments 为空串)、response.function_call_arguments.delta、response.function_call_arguments.done、response.output_item.done,最后 response.completed(response 同非流式)并关闭。sequence_number(与 SSE id:):0.6.0 起所有 Responses 流都是这条流里帧的序号,从 0 起连续,合成帧同样计数(以前直接用事件 ID,桥接流取事件 ID 与已发出最大值 + 1 中较大的一个)。续接流是新的一段,从停车游标之后的真实事件开始,序号也从 0 起。序号只在一条流内有意义,不要跨流比较。
Claude Messages(/v1/compat/messages 与 /v1/messages,两者用同一个兼容解析器):带 name 与 input_schema 的条目是调用方工具,带 type 的服务端工具(web_search_*、bash_*、computer_* 等)在 bridge 下报 client_tools_unsupported。最后一条 user 消息里的 tool_result 块是回传结果(content 为字符串或 text 块数组;is_error: true 时包成 {"error": …} 交给模型)。
{ "model": "agent/coder", "max_tokens": 1024,
"tools": [{ "name": "edit_file", "input_schema": { "type": "object" } }],
"messages": [{ "role": "user", "content": "修复登录页的报错" }] }停车响应:stop_reason: "tool_use",content 先是本段新文本的 text 块,再是 {"type":"tool_use","id":"call_8c1…","name":"edit_file","input":{"path":"login.ts"}}。tool_use.id 直接用待办 ID(call_ 前缀,不是 Claude 惯例的 toolu_),客户端应把它当作不透明字符串。回传:
{ "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "call_8c1…", "content": "已修改" }] }流式:停车时(还没发过时)先补发 message_start;已打开的 text 块先 content_block_stop;每个调用 content_block_start(tool_use,input: {})、一个 input_json_delta(完整 JSON)、content_block_stop,index 依次递增;最后 message_delta(stop_reason: "tool_use")与 message_stop,然后关闭。
Gemini(/v1beta/models/{agent}:generateContent 与 :streamGenerateContent,/v1/models/... 相同):tools[].functionDeclarations[] 是调用方工具,参数取 parametersJsonSchema(JSON Schema,原样)或 parameters(Gemini 的 OpenAPI 子集:type: "OBJECT" 等大写类型转成小写,nullable: true 并入类型)。googleSearch、codeExecution、urlContext 等内置工具(或与 functionDeclarations 写在同一条里)在 bridge 下报 client_tools_unsupported,managed 下照旧忽略。toolConfig.functionCallingConfig(mode AUTO / NONE / ANY 与 allowedFunctionNames)与 OpenAI、Claude 的 tool_choice 一致解析并生效(NONE 本轮不暴露调用方工具,ANY 或 allowedFunctionNames 要求触发对应函数调用,不再列入 X-OAA-Ignored-Params)。
{ "contents": [{ "role": "user", "parts": [{ "text": "修复登录页的报错" }] }],
"tools": [{ "functionDeclarations": [{ "name": "edit_file", "parameters": { "type": "OBJECT" } }] }] }停车响应:candidates[0].content.parts 先是本段新文本的 text part,再是每个调用一个 {"functionCall":{"id":"call_8c1…","name":"edit_file","args":{"path":"login.ts"}}}(args 是对象,并行调用是多个 part),finishReason: "STOP"(Gemini 的函数调用本来就以 STOP 结束),usageMetadata 照常,responseId 是运行 ID、续接时不变。回传:contents 最后一条(role: "user" 或 "function")里的 functionResponse part:
{ "role": "user", "parts": [{ "functionResponse": { "id": "call_8c1…", "name": "edit_file", "response": { "output": "已修改" } } }] }response 按 JSON 写回对话。带 id 时按 id 配对;不带 id 时(官方 @google/genai 的 chats 会把模型回合的 functionCall(含 id)原样留在历史里,但调用方自己写的 functionResponse 往往不带 id),按上一条 role: "model" 内容里 functionCall 的 name 与出现顺序配对。配不上(不认识的 id、没有可配对的 functionCall、名字对不上)时与其它协议的未知 ID 一样,整体当作新请求处理,原运行保持停车。
流式(?alt=sse 或分块 JSON 数组):停车时一个分片给出全部 functionCall part(Gemini 不对参数分片),同一分片带 finishReason: "STOP" 与 usageMetadata,然后关闭;此前已流式发出的文本不重复。
外部智能体的桥接是怎么工作的
ACP 外部智能体有自己的工具循环,OAA 插不进去。但 ACP 建会话时可以交给智能体一组 MCP 服务(session/new 的 mcpServers,stdio 形式是 ACP 要求所有智能体都支持的基线),OAA 就用这个口子把你的工具交给它:
调用方 ─tools─▶ 网关 ─▶ 内核 ─任务(带调用方工具)─▶ 执行机器
│ session/new { mcpServers: [oaa-caller] }
▼
ACP 智能体 ─MCP tools/call─▶ 中继进程(oaa mcp-relay)
│ 本机 Unix 域套接字
执行机器 ◀─────────────────────┘
▼
内核登记待办,运行进入 requires_action ─▶ 网关以 tool_calls 交给调用方
调用方回传结果 ─▶ 结果原路回到 MCP tools/call,智能体接着做使用者需要知道的几点:
- 中继:每一轮给智能体一个固定名为
oaa-caller的 stdio MCP 服务。它是oaa mcp-relay子命令启动的小进程,只做两件事:tools/list列出你的工具(名字、说明、参数 schema 原样给出),tools/call经本机 Unix 域套接字转给执行机器。套接字放在该运行私有的 0700 目录里(工作区路径过长时改用系统临时目录下的短路径),套接字与一次性令牌文件都是 0600,只接受持有令牌的第一个连接;不监听任何网络端口。这一轮结束(完成、失败、取消、超时)时套接字关闭、文件删除,中继随之退出。 - 对你来说和内核智能体一样:响应里是标准的
tool_calls(或function_call、tool_use),名字是你的原名,回传后同一个运行接着做。同一时刻发出的多个调用一次给全(中继把 5 毫秒内到达的调用合成一次转发,内核在下一个事件循环合并通知);智能体晚一点才发出的调用,在你下一次回传时一并返回。 - 内层智能体看到的工具名是 MCP 的命名,由智能体自己决定(常见的是加服务名前缀,例如
oaa-caller下的edit-file)。外部智能体没有已发布的工具,不做别名,原名里的-在 MCP 里也合法。 - 等待期间内层进程保持存活:这与外部智能体的人工审批一样,占着进程与运行槽,不是可迁移的停车。期限沿用
approvalTimeoutMs,到期以client_tool_timeout结束;可以照常取消。 - 网关重启会中断这类运行(
interrupted,与其它外部智能体运行一致),不会像内核智能体那样保持停车等你续接。 - 参数不符合你的 schema、或智能体调用了清单里没有的名字时,不会交给你,而是直接以 MCP 的错误结果(
isError: true)交回智能体,运行不失败。 - 运行事件:新的调用方待办出现后发出
run.awaiting_caller(载荷是此刻全部待处理的待办 ID),它在外部智能体的桥接运行里代替内核的run.parked。 - 对调用方工具的权限请求自动放行:有的智能体(如 Qoder)在调用 MCP 工具前先发
session/request_permission。这些工具由你自己提供、自己执行,所以只在桥接回合里、且请求针对的确实是中继提供的工具时,OAA 直接选「允许一次」(allow_once),不创建 owner 审批,并记一条进度{ event: "permission_auto_allowed", tool }。判断是保守的,必须同时满足:标题或rawInput的工具标识里出现oaa-caller(大小写不敏感);标题分词后有一个词等于你的某个工具名,或以_<工具名>结尾(覆盖mcp_oaa-caller_<name>写法);标题里的其余词都只是填充词(run、call、calling、use、using、tool、mcp、server、oaa-caller),所以标题里只是提到中继名与工具名的 shell 命令不会被自动放行;并且这个调用不是智能体自己通过 ACP 工具kind标为执行命令或修改文件的类别(execute、edit、delete、move),不管标题怎么写。安全边界:自动放行只发生在桥接回合、只针对中继提供的工具;智能体自带工具(读写文件、执行命令等)的权限请求照旧走 owner 审批。 - 调用前已经输出的文本作为一条输出消息结束,续接后的新文本是新的一条;响应只含上次交付之后的新输出。
限制与未验证项
- 没有对真实 ACP 智能体联调。测试用的是协议级假智能体(
test/fixtures/acp-caller-agent.mjs:读取mcpServers、用 MCP SDK 启动中继、tools/list、tools/call)。mcpServers条目的字段形状({ name, command, args, env: [{ name, value }] })依据 ACP 规范的公开描述,仓库里没有 ACP 的类型定义可以对照。 (2026-11-11 更新:已对本机 Antigravity 命令行(agy1.5.5)的 ACP 入口用 Gemini 3.8 Flash 做过一次真实联调,托管与桥接各一次调用均通过,mcpServers的 stdio 条目形状被接受;并行调用、流式、慢回传与其它 ACP 智能体仍未验证。联调结果见 evidence.md。) - 智能体自己的 MCP 调用超时(例如 MCP SDK 默认 60 秒)可能比
approvalTimeoutMs短:调用方回传太慢时,智能体可能先放弃这次调用。- 保活:等待调用方期间,中继对请求里带了
_meta.progressToken的tools/call每 15 秒发一次notifications/progress(progress递增,message说明在等调用方;间隔可用oaa mcp-relay --progress-interval-ms或环境变量OAA_MCP_RELAY_PROGRESS_MS调整)。没带令牌时不发。这不保证能延长超时:要智能体的 MCP 客户端启用了「收到进度即重置超时」(MCP SDK 的resetTimeoutOnProgress),而且它确实给了 progressToken。建议把网关的approvalTimeoutMs与智能体的 MCP 请求超时对齐(不长于后者),或把智能体的 MCP 超时调大。 - 放弃后的收尾:智能体放弃调用时如果关掉了中继(关闭 MCP 服务,或超时后重启服务),中继到执行机器的套接字会断开;仍在等待的调用随即以
client_tool_abandoned结束:对应步骤失败、待办标为过期,运行不因此失败(智能体还在继续),没有其它待办时状态回到in_progress。之后再回传这个call_id不会续接,按新请求处理。智能体只是让请求超时、却不关闭中继时,这次调用仍会挂到approvalTimeoutMs,以client_tool_timeout结束运行。
- 保活:等待调用方期间,中继对请求里带了
- 桥接通过
oaa-callerMCP 中继统一覆盖 ACP 适配器、Antigravity 已验证的 ACP 路径、Claude Code(options.mcpServers+canUseTool对mcp__oaa-caller__<name>自动放行)与 Codex(单次进程-c mcp_servers.oaa-caller.*覆盖 + MCP 审批 / elicitation 自动放行,绝不修改~/.codex/config.toml)。DSH、A2A 与 oaa-1 HTTP 适配器仍仅托管。
路线
- 已提供:内置内核智能体、Codex 与 Claude Code 原生引擎、Antigravity ACP 及 ACP 外部智能体在 Chat Completions、Responses、Claude Messages、Gemini 上的
bridge(/health的features含harness-bridge-v1、harness-bridge-acp-v1),并支持tool_choice/toolConfig.functionCallingConfig下推与外部智能体续接纠正(未满足时报422 tool_choice_unmet)。UAP/1 不做桥接。 - 后续:无 stdio MCP 挂载点的其它外部适配器继续逐个引擎评估。
/health 的 features 含 client-tools-policy-v1 时,本页描述的托管与拒绝模式可用。错误码见 protocol.md「错误码」一章。