# Agent Tool Calling 底层机制总结

> Tool Call 是大模型生成的一次结构化工具调用请求，告诉外部程序调用哪个工具、传入什么参数。真正执行工具的是 Runtime 或对应的工具执行环境。

## 1. Tool Calling 的本质

一次工具调用涉及三个层次：

| 层次 | 职责 |
| --- | --- |
| 大语言模型（LLM） | 根据上下文生成文本或工具调用请求 |
| 模型 API 服务 | 按接口协议组织或解析模型输出，返回结构化数据 |
| Agent Runtime | 管理模型调用、工具匹配与执行、结果回传和状态流转 |

## 2. 一次工具调用的完整流程

![工具调用的完整流程：从发送消息和工具定义，到执行工具并将结果回传模型](https://herblab.online/qwen-imgs/agent-tool-calling-loop-03-sequence-v2.png)<!-- display-width:600 -->

以下代码使用 Chat Completions 格式。`client`、`MODEL_NAME`、`get_time` 和 `search_knowledge_base` 在应用侧预先准备。

### 2.1 发送消息和工具定义

```python
messages = [{"role": "user", "content": "百炼计费说明"}]

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_time",
            "description": "获取当前时间",
            "parameters": {
                "type": "object", "properties": {},
                "additionalProperties": False,
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "search_knowledge_base",
            "description": "从知识库查询资料",
            "parameters": {
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"],
                "additionalProperties": False,
            },
        },
    },
]

response = client.chat.completions.create(
    model=MODEL_NAME, messages=messages, tools=tools,
)
```

`tools` 是可用工具的清单，可以包含多个工具。每个工具定义包括名称、描述和参数 Schema；**传给模型的是工具说明，不是函数源代码。**

### 2.2 模型返回工具调用请求

模型根据消息和工具描述决定调用哪些工具。返回的 assistant 消息中，`tool_calls` 包含实际请求的工具调用：

```json
{
  "role": "assistant",
  "content": null,
  "tool_calls": [{
    "id": "call_001",
    "type": "function",
    "function": {
      "name": "search_knowledge_base",
      "arguments": "{\"query\": \"百炼计费说明\"}"
    }
  }]
}
```

`name` 是工具名，`arguments` 是 JSON 字符串格式的参数，`id` 是调用编号。模型也可能在一次返回中请求调用多个工具；**此时工具尚未执行。**

支持工具调用的模型经过相关训练，能够生成约定格式的调用内容，模型服务将其解析为 API 返回的结构。在 DeepSeek 的一些开源模型实现中，工具调用、工具名和参数使用特殊标记区分；具体编码方式取决于模型和服务实现。

### 2.3 程序执行工具并回传结果

```python
import json

handlers = {
    "get_time": get_time,
    "search_knowledge_base": search_knowledge_base,
}

message = response.choices[0].message
messages.append(message)

for call in message.tool_calls:
    args = json.loads(call.function.arguments)
    result = handlers[call.function.name](**args)
    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": str(result),
    })

response = client.chat.completions.create(
    model=MODEL_NAME, messages=messages, tools=tools,
)
```

程序根据工具名找到对应函数，执行后把调用消息和工具结果加入 `messages`，再发给模型。每条工具结果通过 `tool_call_id` 与原调用的 `id` 对应。上面的代码省略了校验；实际运行前需要检查工具名和参数。

模型拿到结果后，可以回答，也可以继续请求工具；程序再处理下一轮，直到模型回答或达到停止条件。没有 `tool_calls` 并不自动代表任务成功，还需要结合响应状态和任务结果判断。

## 3. LangGraph 与 OpenAI Agents SDK

两者都可以组织模型调用和工具执行，只是封装方式不同。

| 职责 | LangGraph | OpenAI Agents SDK |
| --- | --- | --- |
| 注册工具 | `bind_tools` 与 `ToolNode` | Agent 配置中的函数工具 |
| 决定下一步 | `tools_condition` 或自定义条件路由 | Runner 检查模型输出 |
| 执行和回传 | `ToolNode` 执行工具并产生 `ToolMessage` | SDK 调度函数工具并处理结果 |
| 管理循环 | Graph 的节点和边 | `Runner.run()` 等运行入口 |

结果的具体字段取决于接口：上面的 Chat Completions 示例使用 `tool_call_id`；Responses API 使用 `function_call_output` 和 `call_id`。

### AIFriends 中的 LangGraph 流程

AIFriends 的 `backend/web/views/friend/message/chat/graph.py` 中，`get_time` 和 `search_knowledge_base` 被注册为工具。下面的代码按项目源码整理，省略了工具定义、模型初始化和状态类型：

```python
tools = [get_time, search_knowledge_base]
llm = llm.bind_tools(tools)

def model_call(state):
    response = llm.invoke(state["messages"])
    return {"messages": [response]}

def should_continue(state):
    if state["messages"][-1].tool_calls:
        return "tools"
    return "end"

graph = StateGraph(AgentState)
graph.add_node("agent", model_call)
graph.add_node("tools", ToolNode(tools))
graph.add_edge(START, "agent")
graph.add_conditional_edges(
    "agent", should_continue, {"tools": "tools", "end": END}
)
graph.add_edge("tools", "agent")
app = graph.compile()
```

- `bind_tools` 把工具定义交给模型；`ToolNode` 持有同一组工具，负责执行模型请求的工具。
- `should_continue` 检查模型消息：有工具调用就转到 `tools`，否则结束。
- `tools` 节点执行后回到 `agent`；图的消息状态会把工具结果加入对话，再交给模型。

LangGraph 把工具分发、结果回传和流程跳转组织在图中；手写运行程序也可以完成同一套机制。🐳

## 4. Skill 的本质

```text
skills/
└── pptx/
    ├── SKILL.md
    └── generate.py
```

Skill 是一套可复用的操作说明及配套资源，`SKILL.md` 描述使用方法；它本身不是一个天然会自动执行的工具。

Agent 的典型加载方式：

![Agent 的典型加载方式：发现 Skill、读取说明并通过工具执行操作](https://herblab.online/qwen-imgs/agent-tool-calling-loop-04-skill-loading-v2.png)<!-- display-width:600 -->

读取 Skill 的具体方式由 Runtime 决定；说明内容可以通过工具结果或其他方式提供给模型。

- **安装**：把 Skill 文件放到运行环境可发现的位置。
- **加载**：读取说明，并将需要的内容提供给模型；具体加载方式由 Runtime 决定。
- **执行**：模型按照说明完成任务，必要时请求文件、命令等工具执行动作。

Skill 可以包含脚本，但使用 Skill 不一定会运行脚本。LangGraph 本身也不会自动扫描任意 Skill 目录；这需要额外的 Skill 管理能力。

## 5. 最终知识框架

| 概念 | 作用 |
| --- | --- |
| LLM | 生成文本或工具调用请求 |
| Tool Call | 描述工具名、参数等信息的调用请求 |
| Runtime | 管理模型、工具和上下文之间的执行流程 |
| Tool | 实际执行操作的函数或外部能力接口 |
| Skill | 提供完成某类任务的说明和资源 |
| Agent | 将模型、Runtime、工具和上下文组织起来的应用 |

本文讨论程序自己提供的函数工具；服务商内置工具可能由服务端执行。`tool_calls` 是常见的 API 字段名，不同接口的表示方式可能不同。

**Tool Calling 让模型能够请求外部系统执行动作；Agent Runtime 将这些动作组织成持续的执行与反馈循环。Skill 则提供完成特定任务的说明和资源。**

## 参考资料

接口和模型模板核对日期：2026 年 10 月 28 日。代码展示调用流程，知识库查询未实际执行；LangGraph 片段根据本地 AIFriends 项目源码整理。

- [DeepSeek：Tool Calls](https://api-docs.deepseek.com/guides/tool_calls/)
- [DeepSeek：Chat Completions](https://api-docs.deepseek.com/api/create-chat-completion/)
- [DeepSeek：模型工具调用模板](https://huggingface.co/deepseek-ai/DeepSeek-V3.2-Exp-Base/blob/main/assets/chat_template.jinja)
- [LangGraph：ToolNode 参考](https://reference.langchain.com/python/langgraph.prebuilt/tool_node/ToolNode)
- [OpenAI：Agent 执行循环](https://developers.openai.com/api/docs/guides/agents/running-agents)
- [OpenAI：Function Calling](https://developers.openai.com/api/docs/guides/function-calling)
- [OpenAI：Skills](https://developers.openai.com/api/docs/guides/tools-skills)

---

完整网页版本、清晰原图、Word 和离线 HTML：
[Agent Tool Calling 底层机制总结｜文潇的技术博客](https://aiarchblog-6hz4s01hv.maozi.io/articles/agent-tool-calling-loop/)
