工具执行:模型提议,谁真正动手?
第 5 站说“执行工具并回填结果”,这不是一个黑箱。模型给出的工具名称和参数,要经过运行时、路由与注册表,才会到达真正执行代码。
第一轮扩展站:深入主链中的工具支路,精读核心数据和分派边界;不在本课穷举所有内置工具、MCP 或 Code Mode 的实现。 讲义已备好 ≠ 已掌握;本页不会改动你的通关状态。
本站必背 · 走路复习
第 7 站:模型提出调用,工具实现动作
先理解,再背这一个完整段落。日常复述约 1–2 分钟;点标题可遮住正文,按下面的顺序提示试着复述。
核心背诵段 · 点击展开或遮住
第七站位于 Core 的工具执行链。工具定义告诉模型有什么能力、参数怎样填写,但定义本身不会执行动作。模型产生具体工具调用后,运行时安排执行与取消,ToolRouter 补齐会话和步骤上下文,ToolRegistry 查找已注册实现,再由具体工具及下游完成相应检查和动作。call_id 用来关联这一次调用及其结果,不是 Turn 编号;找不到工具应明确报错,不能假装执行成功。结果或可反馈的错误会回到后续模型处理,是否终止整轮取决于错误类型和控制流程。记住:模型是调用的提出者,工具实现才连接真实能力;参数能解析,不代表权限和业务条件已经满足。
复述顺序:工具定义 → 具体调用 → 运行时安排 → 路由与注册表 → 实际动作与结果。
背诵用于抓牢主线。理解自测:为什么给模型一份“删除对象”的工具说明,还不等于已经实现了删除功能? 仍需通过源码阅读和练习验证掌握,不会因背诵自动标记通关。
先听一遍,再对照源码
普通话讲解,保留关键代码语义、实际操作情境和 GEODYNA 对照。用“说明书、调用单、执行者、回执”辅助记忆,再回到真实类型。
点击开始;页面不会自动播放,也不会自动标记课程通关。
点击任一章,从对应位置开始。
展开音频文字稿 · 听不清时对照看
声音中的术语,对应代码里的哪个词?
AI 合成语音;收听位置仅保存在当前浏览器,不跨设备同步。代码以固定快照为准。可下载后用手机播放器离线收听。
先定位:这一站到底在讲哪一层?
这条分支位于 Core。模型服务产出工具调用项目,流事件处理将它转换为内部 ToolCall;ToolCallRuntime 负责执行时机与取消协调;ToolRouter 组织调用上下文;ToolRegistry 查找实际运行实现。
工具的说明和真正执行它的代码是两份东西。模型看见工具名称、用途和参数约束,并不表示模型自己直接修改了文件或运行了求解器。真正的副作用发生在工具执行实现及其下游。
- 1模型看到可用工具说明
- 2模型响应包含工具调用
- 3运行时安排执行与取消
- 4Router 组装 ToolInvocation
- 5Registry 找到工具实现
- 6结果回填历史并供下一次模型使用
| 粒度 | 负责什么 | 不要误认为 |
|---|---|---|
| ToolSpec | 向模型说明可以调用什么、怎样填参数 | 不是实际执行命令的函数体 |
| ToolCall | 一次具体调用的工具身份、调用 ID 和载荷 | 不是工具注册定义 |
| ToolInvocation | 工具调用加上 Session、步骤上下文和取消等运行信息 | 不是把所有字段直接发给模型 |
| 具体工具实现 | 解析业务参数,执行或调用下游服务,形成输出 | 不允许仅因为模型提出就绕过权限边界 |
先拆一份调用单
工具定义回答“系统能提供什么能力”。工具调用回答“这次请调用哪个能力、传什么参数”。工具结果回答“实际上发生了什么”。三个阶段的数据不能混成同一个“工具”。
call_id 用来把这一次调用与结果关联起来。同一个工具在同一 Turn 里调用两次,需要区分这两次;不能只用工具名称作为结果匹配键。payload 则是承载具体调用输入的枚举,普通 function 工具与其他调用形式可能不同。
1. ToolCall:每个字段都属于这一张调用单
真实源码 · codex-rs/core/src/tools/router.rs:36–42
代码较长时可左右滑动;下方按语句和术语拆解。
#[derive(Clone, Debug, PartialEq)]
pub struct ToolCall {
pub tool_name: ToolName,
pub call_id: String,
pub payload: ToolPayload,
pub encrypted_function_args: Option<Vec<String>>,
}| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| #[derive(Clone, Debug, PartialEq)] | 让类型具备克隆、调试格式和相等比较等派生能力;并不是执行工具。 |
| tool_name: ToolName | 工具身份;ToolName 可以表达名称与命名空间,不只是显示用标题。 |
| call_id: String | 本次调用的关联标识;不是 Thread ID,也不是整个 Turn ID。 |
| payload: ToolPayload | 真正承载参数的内部枚举。具体工具还需要校验和解释其中的数据。 |
| encrypted_function_args: Option<Vec<String>> | 此快照还支持可选的加密参数相关材料;普通明文例子不展开该支路,也不能把它理解成一定有密钥。 |
具体输入,逐层拆开
假想 GEODYNA 工具的内部示意,不是现有公开接口或可执行请求。
工具定义:read_project_summary(只读,假想名称)
第一次调用:
tool_name = read_project_summary
call_id = C1
payload = Function { arguments: "{\"projectId\":\"P1\"}" }
工具结果:
call_id = C1
output = 当前项目摘要/结构化错误arguments 在这个示意的 Function 载荷里是一段 JSON 字符串;字符串中写了合法 JSON,不等于 projectId 存在,也不等于业务操作合法。语法校验与领域校验需要分开。
Router 负责组装,不是直接修改工程
2. 从 ToolCall 组装 ToolInvocation
真实源码 · codex-rs/core/src/tools/router.rs:358–381
代码较长时可左右滑动;下方按语句和术语拆解。
let ToolCall {
tool_name,
call_id,
payload,
..
} = call;
// Keep the legacy ToolInvocation.turn field tied to the same request state until handlers migrate.
let turn = Arc::clone(&step_context.turn);
let invocation = ToolInvocation {
session,
turn,
step_context,
cancellation_token,
tracker,
call_id,
tool_name,
source,
payload,
};
self.registry
.dispatch_any_with_terminal_outcome(invocation, terminal_outcome_reached)
.await| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| let ToolCall { tool_name, call_id, payload, .. } | 解构取出当前需要的字段;两个点忽略没有在这里单独绑定的剩余字段,不是把原始调用随意删坏。 |
| Arc::clone(&step_context.turn) | 共享这一模型步骤所对应的 Turn 上下文,避免工具执行时换成另一个请求视图。 |
| ToolInvocation { session, turn, step_context, ... } | 在模型调用数据外,补上 Core 内部执行需要的上下文、取消信号、差异追踪与调用来源。 |
| self.registry.dispatch_any_with_terminal_outcome(...).await | 向注册表委托分派,并等待输出。实际工具逻辑不写在这个 Router 组装片段中。 |
3. 找不到工具,返回明确错误
真实源码 · codex-rs/core/src/tools/registry.rs:515–537
代码较长时可左右滑动;下方按语句和术语拆解。
let dispatch_trace = ToolDispatchTrace::start(&invocation);
let tool = match self.tool(&tool_name) {
Some(tool) => tool,
None => {
let message = unsupported_tool_call_message(&invocation.payload, &tool_name);
let log_payload = tool_log_payload(&invocation.payload, &invocation.source);
let mut tool_result_tags = Vec::with_capacity(2);
sandbox_tags.append_metric_tags(&mut tool_result_tags);
otel.tool_result_with_tags(
&tool_name,
&call_id_owned,
log_payload.as_ref(),
Duration::ZERO,
/*success*/ false,
&message,
&tool_result_tags,
/*extra_trace_fields*/ &[],
);
let err = FunctionCallError::RespondToModel(message);
dispatch_trace.record_failed(&err);
return Err(err);
}
};| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| match self.tool(&tool_name) | 用工具身份查找当前可用实现,不按模型口头描述临时发明函数。 |
| Some(tool) | 找到实现,继续后续检查和执行。 |
| None | 没有匹配实现。该分支记录失败信息,然后返回错误,不继续假装执行成功。 |
| FunctionCallError::RespondToModel(message) | 这类错误可以作为反馈交回模型,让它知道调用不可用;它不同于整轮致命错误。 |
| Duration::ZERO / success false | 此处没进入工具执行,所以用零执行时长及失败标识记录这次分派结果。 |
边界提醒:后面还会检查载荷种类、运行 hooks 等。仅在注册表找到名称,不等于业务参数已经全部合法。
并行不是模型说一句“同时做”就无条件成立
这个快照的 ToolCallRuntime 会查询工具的 supports_parallel 标记。允许并行的调用通过共享读锁进入,不允许并行的调用取独占写锁。注意:这里的读写锁是执行协调门,不等同于判断该工具在业务上是读操作还是写操作。
run_turn 中的 Prompt 允许并行工具调用,也不代表所有调用都能安全并发。模型提议、工具元数据、运行时控制与业务事务是不同层。两个修改同一工程对象的动作,还需要正式业务边界保证一致性。
| 执行结果 | 下一步应该怎样理解 |
|---|---|
| 成功结果 | 关联 call_id 后回填,模型据此继续解释或规划。 |
| 可反馈的工具失败 | 作为工具反馈告诉模型实际错误;不伪造成功,也不必一律立即终止整个 Turn。 |
| 致命错误或取消 | 走相应终止/取消路径;不能把所有错误都包装成“可以继续重试”。 |
| 工具输出很大 | 结果还要受历史与上下文处理约束;第 9 站再讨论如何避免把所有数据塞进模型。 |
4. 工具是否支持并行,由注册信息查询
真实源码 · codex-rs/core/src/tools/router.rs:235–243
代码较长时可左右滑动;下方按语句和术语拆解。
pub fn tool_supports_parallel(&self, call: &ToolCall) -> bool {
self.registry
.supports_parallel_tool_calls(&call.tool_name)
.unwrap_or(false)
}
pub(crate) fn tool_runtime(&self, tool_name: &ToolName) -> Option<Arc<dyn CoreToolRuntime>> {
self.registry.tool(tool_name)
}| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| tool_supports_parallel(&self, call: &ToolCall) | 根据这次调用的工具身份查询并行能力,而不是把调用参数当并行许可证。 |
| supports_parallel_tool_calls(&call.tool_name) | 向 Registry 查询工具元数据。 |
| unwrap_or(false) | 如果查询没有结果,默认不并行;这是 Option 的缺省值处理。 |
| tool_runtime(...) -> Option<Arc<dyn CoreToolRuntime>> | 可能找到共享运行实现,也可能没有;dyn 表示通过接口使用不同的具体实现。 |
把同一个场景换一种条件
假设模型已经提出一次工具调用,接下来是否真的进入了业务实现?
仅为本地教学演示,不调用模型或 GEODYNA,不执行任何真实操作。
先预测会走哪条分支,再点击按钮查看。
正常工具路径
- 解析为内部调用,保留 call_id。
- 组装 invocation,查询实现并经过相应检查。
- 执行产生实际结果,将结果交回模型历史。
模型负责提议与解释;真实执行者必须给出事实结果。
在分派阶段失败
- Registry 查不到相应实现。
- 构造 RespondToModel 类错误。
- 上游可将错误作为模型反馈,而不是创建一个同名假工具。
“模型很想调用”不能创造已经不存在的能力。
还需要领域校验
- 参数可能顺利解析为 JSON。
- 实际业务检查发现目标对象不存在或版本已变化。
- 返回结构化失败,不修改另一个对象来凑成功。
语法合法与业务合法是两个检查层次。
运行时继续检查并行能力
- 模型侧的并行许可并非最终执行顺序。
- 运行时查询工具 supports_parallel 元数据。
- 允许者共享进入,不允许者独占;业务事务仍由业务执行层负责。
执行读锁的“读”,不是对业务操作只读性的万能证明。
最容易说错的边界
| 常见说法 | 准确表述 |
|---|---|
| 给模型写一个工具说明就实现了工具 | 还需要注册可调用实现,并接到真实执行边界。 |
| call_id 就是 Turn ID | 它标识一次调用,用于关联该调用及其结果。 |
| JSON 能解析就可以执行 | 还需要目标、范围、权限、版本和业务不变量校验。 |
| 任何工具报错都必定结束整个 Turn | 错误类型与当前控制流程决定是否反馈、继续或终止,不能一概而论。 |
迁移到你的 GEODYNA 智能体
以下是设计练习,不代表并行产品线已经实现或通过验收;本次只制作课程,不修改 GEODAMNEW。
GEODYNA 的写操作应由适配器调用正式 Command API,并复用现有确认、Undo/Redo 和审计边界。课程没有新增这类工具,也没有修改软件源码。
候选工具先从小而清晰的能力开始:读当前算例摘要、查询校验问题、获取某个结果指标。真正需要写入时,再设计明确目标和参数,而不是向模型开放一个可以随意改全局状态的大洞。
| 你要设计的点 | 可验证的证据 |
|---|---|
| 工具契约 | 写清名称、用途、输入、输出、可恢复错误和是否有副作用。 |
| 调用关联 | 同一工具两次调用也能分别找到参数与结果,不把 C1 的结果贴到 C2。 |
| 写入边界 | 正式命令接口负责业务校验和事务;工具适配器不直接篡改 UI 状态。 |
| 评测用例 | 不存在对象、过期版本、权限不足、重复调用和正常路径都要有结果。 |
产品经理练习:设计一个只读工具的输入/输出,再列出 3 种失败;工具名可以自拟,但必须标注为设计草案。
先答小测,再看解析
每题即时反馈,可反复尝试;答对这些题也不会替代你的源码复述。
1. 工具说明 ToolSpec 和工具执行实现是什么关系?
2. 同一工具调用两次,靠哪个字段关联各自结果?
3. Router 的组装片段有没有直接执行 GEODYNA 写入?
4. 并行能力查询没有值时,unwrap_or(false) 返回什么?
5. 工具参数是合法 JSON,但目标对象不存在,如何处理?
最后一句话交作业
请用“定义 → 调用 → 运行时 → 路由/注册表 → 实现 → 结果”的顺序,解释模型为什么不是实际执行者;再说出 call_id 的用途。
展开参考答案(先自己说一遍)
模型看到工具定义并产生具体调用,Core 运行时安排它,Router 组装执行上下文,Registry 找到实现,实际实现完成检查和动作并返回事实。call_id 关联这一次调用与结果,同一个工具名称可以对应多次不同调用。
下一轮再回来时:第二轮追 ToolPayload 与 FunctionCallOutput 的数据转换;第四轮再深入不同工具、并发、取消与重试。