[!info] related notes

• 上层入口：Agent Engineering MOC、AI Agent Application MOC
• 核心概念：Function Calling、Tool Calling 工程化
• 运行时：Agent Runtime MOC
• 协议：MCP MOC、A2A

Tool Calling Engineering MOC

知识总览

filters:
  and:
    - 'file.ext == "md"'
    - 'file.inFolder("z")'
    - 'this.file.links.contains(file)'
    - 'file.path != this.file.path'
formulas:
  knowledge: 'file.asLink(title)'
properties:
  formula.knowledge:
    displayName: 知识
  note.description:
    displayName: Description
  note.mastery:
    displayName: Mastery
views:
  - type: table
    name: 知识总览
    order:
      - formula.knowledge
      - note.description
      - note.mastery
    columnSize:
      formula.knowledge: 280
      note.description: 760
      note.mastery: 56

[!abstract] 核心认识 模型生成的 tool call 只是一个不可信动作提案。完整 Tool Runtime 必须负责 schema、参数语义、权限、业务状态、审批、幂等、超时、沙箱、结果归一化和审计。

一张图看完整链路

Tool Definition / Schema
→ Model proposes tool call
→ Parse + Schema Validate
→ Resolve Identity / Tenant
→ Authorize + Check Domain Invariants
→ Risk Gate / Human Approval
→ Idempotency + Timeout + Sandbox
→ Execute
→ Normalize Result / Error
→ Append Event / Trace
→ Return Observation to model

推荐阅读顺序

1. Function Calling：模型如何生成结构化调用请求。
2. MCP vs Function Calling：先把“模型如何调用”与“工具如何接入”分层。
3. Tool Calling 工程化：从模型输出到执行系统。
4. Function Schema、Tool Description。
5. Tool Argument Validation、参数修复与重试。
6. Permission Check、Risk Level。
7. Approval Checkpoint、Human-in-the-loop。
8. Tool Idempotency、Tool Timeout。
9. Tool Sandbox、Permission Boundary。
10. Result Normalization、Error Handling、Audit Log。
11. MCP：标准化能力暴露，不替代宿主权限控制。

Schema 通过为什么仍不能执行

例如参数：

{"taskId":"123","action":"delete"}

即使类型完全正确，仍可能：

• task 不属于当前用户；
• task 已进入不可删除状态；
• ID 来自 Prompt Injection；
• 同一动作已执行；
• 需要更高权限或人工审批。

所以验证至少分四层：

Syntax / Schema
→ Referential Integrity
→ Authorization
→ Domain Invariant / Current State

风险分级

风险	示例	常见控制
Read-only	查询天气、读取公开资料	参数校验、超时、数据权限
Reversible Write	创建草稿、更新可回滚设置	幂等、审计、版本检查
Destructive / External	删除、付款、发信、部署	强授权、确认、审批、fencing、补偿

风险级别应由宿主系统定义，不能让模型自报“这是安全操作”。

结果与错误也要结构化

Tool Result 至少区分：

success + data
validation_error
permission_denied
conflict / stale_version
transient_dependency_error
permanent_business_error
cancelled / timeout

这决定 Runtime 是继续推理、修复参数、重试、降级还是升级给人。

Tool Design 原则

• 名称和描述指向清晰、单一的业务能力；
• 参数尽量语义化，避免让模型拼底层 SQL / Shell；
• Read 与 Write 工具分开；
• 高风险动作采用 preview / confirm / execute 两阶段；
• 返回最小必要结果，避免上下文污染；
• 所有副作用带 request / run / idempotency key；
• 记录实际 actor、resolved resource 和执行结果。

掌握标准

• 能解释 Function Calling 与 Tool Runtime 的区别。
• 能设计一个高风险工具的校验、授权、审批和幂等链。
• 能区分可重试错误和业务拒绝。
• 能说明 MCP 为什么不自动解决权限、隔离和审计。
• 能从 trace 还原模型提案与最终实际执行之间的差异。

Related notes

• Agent Runtime MOC
• MCP MOC
• Agent Guardrails