函数调用

Function calling（工具调用） 让 LLM 在对话中输出 结构化的「要调哪个函数、参数是什么」，由你的运行时 真正执行 并把结果塞回上下文。这是 Agent「能行动」的核心机制，不是模型内置的插件魔法。

学习目标

• 理解 function calling 的请求/响应往返
• 会注册工具描述（name、description、parameters schema）
• 设计错误处理：超时、4xx/5xx、参数非法、幂等

一次调用的往返

1. 你：messages + tools[] 定义
2. 模型：tool_calls[{ name, arguments }]
3. 你：执行本地/远程函数 → tool result message
4. 模型：根据 result 继续对话或再调工具

模型 不执行 函数；你的 Agent 运行时 执行。这与 agt-intro 的观察环节直接对应。

工具注册要点

字段	建议
name	稳定 snake_case，如 search_course_docs
description	何时用、何时不用；避免与别的工具重叠
parameters	JSON Schema；枚举优于自由文本

{
  "name": "search_course_docs",
  "description": "检索 CodeRoadMap 课程 markdown 分块；用户问 track/lesson 时必须先用此工具",
  "parameters": {
    "type": "object",
    "required": ["query"],
    "properties": {
      "query": { "type": "string" },
      "top_k": { "type": "integer", "default": 5 }
    }
  }
}

description 质量 直接决定 模型会不会乱调工具——比堆更多 system prompt 更有效。

错误处理

• 参数 JSON 非法：返回 {"error":"invalid_arguments","detail":"..."} 让模型自纠
• 业务失败：带 code 与可读 message，勿只返回 stack trace 给模型
• 超时/限流：明确 retry_after；Agent 层设最大工具调用次数
• 副作用操作（写库、发邮件）：需 agt-safety 的人工批准 gate

并行多 tool call 时，注意 依赖顺序 与 幂等 id；写操作禁止 blind retry。

与 RAG、MCP 的关系

• RAG 检索常封装为一个 tool（内部走向量库或 elasticsearch-essentials）
• MCP 把工具/资源 标准化暴露 给多种客户端（见 agt-mcp）

练习