Agent开发完全实战指南(二)手写Agent循环
上一篇结尾,我们问裸 LLM "现在几点了",它只能两手一摊:"抱歉,我无法获取实时信息。"
这一篇,我们要让它真的能查到时间。做完你会发现,所谓 Agent,去掉所有花哨包装,核心就是一段不到 40 行的循环代码。
先记住这一篇的一句话概括:
Tool Calling 的本质是:LLM 不亲自干活,它只负责"说"要调用哪个工具、传什么参数;真正执行工具的是你的代码,执行完再把结果喂回给它。
理解了这句话,你就理解了 Agent 的发动机。
一、先厘清一个巨大的误解
很多人以为 "LLM 调用工具" = "LLM 自己去执行了代码"。大错特错。
LLM 从头到尾只会做一件事:输出文字。它永远不会、也没能力真的去执行一个函数、读一个文件、发一个 HTTP 请求。
那 Tool Calling 是怎么回事?拆成三个角色你就懂了:
| 角色 | 职责 | 谁扮演 |
|---|---|---|
| 决策者 | 判断"该调哪个工具、传什么参数",输出一个结构化的调用请求 | LLM |
| 执行者 | 拿到调用请求,真正去执行(跑函数、查库、调接口) | 你的代码 |
| 能力 | 被执行的具体函数 | 你写的工具函数 |
关键洞察:LLM 只是那个"发号施令"的大脑,真正的手脚是你的代码。所谓"给 LLM 装上工具",其实是你写好一堆函数,告诉 LLM "你可以指挥我调用它们",然后由你的循环代码来执行并回传结果。
所以一次工具调用的完整流程是:
sequenceDiagram
participant U as 用户
participant C as 你的循环代码
participant L as LLM
participant T as 工具函数
U->>C: 现在几点了?
C->>L: 消息历史 + 可用工具清单
L-->>C: 我要调用 get_current_time(finish_reason=tool_calls)
C->>T: 执行 getCurrentTime()
T-->>C: "2026-09-21 14:30:00"
C->>L: 把工具结果追加进历史,再问一次
L-->>C: 现在是 2026-09-21 14:30(finish_reason=stop)
C-->>U: 现在是 2026-09-21 14:30看懂这张图,剩下的都是把它翻译成代码。
二、协议细节:请求和响应到底传了什么
我们用的还是 OpenAI 兼容的 Chat Completions 接口,只是这次请求里多带一个 tools 字段。
2.1 声明工具:给 LLM 一份"工具说明书"
在请求体里加一个 tools 数组,每个工具用 JSON Schema 描述它的名字、用途、参数:
{
"model": "gpt-4o-mini",
"messages": [{ "role": "user", "content": "现在几点了?" }],
"tools": [
{
"type": "function",
"function": {
"name": "get_current_time",
"description": "获取当前的日期和时间",
"parameters": { "type": "object", "properties": {} }
}
}
]
}
这里的 description 极其重要——它是 LLM 判断"什么时候该用这个工具"的唯一依据。 描述写得含糊,模型就不知道该不该调、怎么调。第 03 篇会专门讲怎么写好它。
2.2 模型的回应:它"想"调用工具
当模型决定调用工具,返回的不是文字答案,而是一个 tool_calls,并且 finish_reason 变成 tool_calls:
{
"choices": [
{
"finish_reason": "tool_calls",
"message": {
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_current_time",
"arguments": "{}"
}
}
]
}
}
]
}
三个必须记住的细节:
finish_reason: "tool_calls"是循环的"信号灯"——看到它就说明模型要调工具,你得去执行;看到"stop"才是模型给了最终答案。content是null——调工具的时候没有文字内容,别去读它。arguments是一个 JSON 字符串,不是 JSON 对象。比如"{\"a\": 1, \"b\": 2}"。你必须先json.Unmarshal把它解析成对象再用。这是新手第一大坑。
2.3 回传结果:把工具输出喂回去
执行完工具,你要往 messages 里追加两条消息:先追加模型那条 tool_calls 消息(原样),再追加一条 role: "tool" 的结果消息:
{
"role": "tool",
"tool_call_id": "call_abc123",
"content": "2026-09-21 14:30:00"
}
tool_call_id必须和上面tool_calls里的id一字不差地对应,这是绑定"这个结果是哪次调用的"的钥匙。content是字符串,工具返回什么都塞这里。
2.4 完整的消息数组演进
这是全篇最该盯住的东西。Agent 的"循环"和"记忆",本质就是这个 messages 数组在不断变长:
第 1 轮请求:
[ user: "现在几点了?" ]
第 1 轮响应:finish_reason = tool_calls,模型要调 get_current_time
第 2 轮请求(追加了 assistant 的调用 + tool 的结果):
[
user: "现在几点了?",
assistant: (tool_calls: get_current_time, id=call_abc123),
tool: (tool_call_id=call_abc123, content="2026-09-21 14:30:00")
]
第 2 轮响应:finish_reason = stop,模型答"现在是 2026-09-21 14:30"
关键洞察:Agent 没有什么神秘的"记忆",它的记忆就是这个只增不减的 messages 数组。每一轮工具调用的请求和结果,都被追加进去,模型下一轮就能"看到"之前发生的一切。 后面第 04、05 篇讲的上下文工程和记忆,本质都是在管理这个数组。
三、Agent 主循环:把流程翻译成代码
有了协议细节,主循环的算法就呼之欲出了:
函数 runAgent(用户输入):
messages = [ user 消息 ]
循环最多 maxIterations 次:
响应 = 调用 LLM(messages, tools)
把 assistant 消息追加进 messages # 无论如何都要先追加
如果 finish_reason 不是 tool_calls:
返回 最终文字答案 # 结束
对每一个 tool_call:
解析 arguments (JSON 字符串 -> 对象)
结果 = 执行对应的工具函数
把 {role:tool, tool_call_id, 结果} 追加进 messages
# 带着工具结果继续下一轮循环
返回 错误("超过最大轮数")
三个停止条件缺一不可:
finish_reason == "stop":模型给了最终答案,正常退出。finish_reason == "tool_calls":执行工具,继续循环。maxIterations到顶:安全阀,防止模型反复调工具陷入死循环,必须有。
四、动手:完整可运行的 Agent
下面是完整代码。相比第 01 篇,多了工具声明、工具执行、和那个循环。建议你先自己敲一遍,再对照 code/02-first-agent/main.go。
4.1 数据结构
// Message 对应 messages 数组里的一条消息
type Message struct {
Role string `json:"role"`
Content string `json:"content"`
ToolCalls []ToolCall `json:"tool_calls,omitempty"` // assistant 想调用的工具
ToolCallID string `json:"tool_call_id,omitempty"` // role=tool 时,回指哪次调用
}
type ToolCall struct {
ID string `json:"id"`
Type string `json:"type"`
Function FunctionCall `json:"function"`
}
type FunctionCall struct {
Name string `json:"name"`
Arguments string `json:"arguments"` // 注意:是 JSON 字符串,不是对象!
}
// Tool 是给模型看的"工具说明书"
type Tool struct {
Type string `json:"type"` // 固定 "function"
Function FunctionDefinition `json:"function"`
}
type FunctionDefinition struct {
Name string `json:"name"`
Description string `json:"description"`
Parameters map[string]any `json:"parameters"` // JSON Schema
}
type ChatRequest struct {
Model string `json:"model"`
Messages []Message `json:"messages"`
Tools []Tool `json:"tools,omitempty"`
}
type ChatResponse struct {
Choices []struct {
Message Message `json:"message"`
FinishReason string `json:"finish_reason"`
} `json:"choices"`
}
4.2 工具:一个函数 + 一份声明
每个工具由两部分组成:实际执行的 Go 函数 + 给模型看的声明。
import "time"
// 工具 1:返回当前时间
func getCurrentTime(args map[string]any) string {
return time.Now().Format("2006-01-02 15:04:05")
}
// 工具 2:把两个数字相加
func calculate(args map[string]any) string {
a, _ := args["a"].(float64) // JSON 数字解析成 Go 里是 float64
b, _ := args["b"].(float64)
return fmt.Sprintf("%v", a+b)
}
// 注册表:工具名 -> 执行函数
var toolRegistry = map[string]func(map[string]any) string{
"get_current_time": getCurrentTime,
"calculate": calculate,
}
// 声明:告诉模型有哪些工具、怎么用
var toolDefs = []Tool{
{
Type: "function",
Function: FunctionDefinition{
Name: "get_current_time",
Description: "获取当前的日期和时间,当用户询问现在几点、今天几号时使用",
Parameters: map[string]any{"type": "object", "properties": map[string]any{}},
},
},
{
Type: "function",
Function: FunctionDefinition{
Name: "calculate",
Description: "计算两个数字 a 与 b 的和",
Parameters: map[string]any{
"type": "object",
"properties": map[string]any{
"a": map[string]any{"type": "number", "description": "第一个加数"},
"b": map[string]any{"type": "number", "description": "第二个加数"},
},
"required": []string{"a", "b"},
},
},
},
}
4.3 调用 LLM
和第 01 篇几乎一样,只是请求里带上了 Tools:
func callLLM(messages []Message) (*ChatResponse, error) {
apiKey := os.Getenv("OPENAI_API_KEY")
baseURL := os.Getenv("OPENAI_BASE_URL")
if baseURL == "" {
baseURL = "https://api.openai.com/v1"
}
reqBody := ChatRequest{
Model: "gpt-4o-mini",
Messages: messages,
Tools: toolDefs, // 每一轮都带上工具声明
}
buf, _ := json.Marshal(reqBody)
req, _ := http.NewRequest("POST", baseURL+"/chat/completions", bytes.NewReader(buf))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)
resp, err := http.DefaultClient.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var chatResp ChatResponse
if err := json.Unmarshal(body, &chatResp); err != nil {
return nil, fmt.Errorf("解析失败: %v, 原始响应: %s", err, string(body))
}
if len(chatResp.Choices) == 0 {
return nil, fmt.Errorf("无返回, 原始响应: %s", string(body))
}
return &chatResp, nil
}
4.4 主循环:Agent 的发动机
这就是整个 Agent 的核心,不到 40 行:
func runAgent(userInput string) (string, error) {
messages := []Message{{Role: "user", Content: userInput}}
const maxIterations = 10 // 安全阀:防止无限循环
for i := 0; i < maxIterations; i++ {
resp, err := callLLM(messages)
if err != nil {
return "", err
}
choice := resp.Choices[0]
// 关键:无论如何都先把 assistant 消息原样追加进历史
messages = append(messages, choice.Message)
// 没有要求调工具 => 这是最终答案,结束
if choice.FinishReason != "tool_calls" || len(choice.Message.ToolCalls) == 0 {
return choice.Message.Content, nil
}
// 逐个执行工具调用(一次可能有多个 = 并行调用)
for _, call := range choice.Message.ToolCalls {
fmt.Printf(" [调用] %s(%s)\n", call.Function.Name, call.Function.Arguments)
var args map[string]any
json.Unmarshal([]byte(call.Function.Arguments), &args) // arguments 是字符串,先解析
result := "错误:未知工具 " + call.Function.Name
if fn, ok := toolRegistry[call.Function.Name]; ok {
result = fn(args)
}
fmt.Printf(" [结果] %s\n", result)
// 把结果喂回去,tool_call_id 必须精确匹配
messages = append(messages, Message{
Role: "tool",
ToolCallID: call.ID,
Content: result,
})
}
// 继续循环:带着工具结果再问一次模型
}
return "", fmt.Errorf("超过最大轮数 %d", maxIterations)
}
func main() {
for _, q := range []string{"现在几点了?", "帮我算一下 1234 加 5678"} {
fmt.Printf("\n用户:%s\n", q)
answer, err := runAgent(q)
if err != nil {
fmt.Println("出错:", err)
continue
}
fmt.Printf("Agent:%s\n", answer)
}
}
4.5 跑起来
cd code/02-first-agent
go run main.go
你会看到类似输出:
用户:现在几点了?
[调用] get_current_time({})
[结果] 2026-09-21 14:30:00
Agent:现在是 2026 年 9 月 21 日 14:30。
用户:帮我算一下 1234 加 5678
[调用] calculate({"a":1234,"b":5678})
[结果] 6912
Agent:1234 加 5678 等于 6912。
成了。 同一个模型,第 01 篇答不出时间,这一篇却能准确报时——区别只在于我们给了它工具、并写了个循环去执行。这就是 Agent。
五、观察:进化时刻
回头看这个循环里 finish_reason 的变化轨迹,你就看到了裸 LLM 进化成 Agent 的全过程:
第 1 轮:finish_reason = tool_calls ← 模型说"我要查时间"
(代码执行工具,把结果喂回)
第 2 轮:finish_reason = stop ← 模型拿到实锤,给出最终答案
对比第 01 篇——那时候只有一个孤零零的 stop,模型没有任何手段获取真实信息,只能硬答。现在它学会了"先查、再答"。
这就是上一篇说的 ground truth:Agent 不靠猜,它调用工具从真实环境拿到实锤,再基于实锤回答。 可靠性的飞跃就来源于此。
六、进阶细节
6.1 并行工具调用
模型一轮可能同时要求调用多个工具,tool_calls 数组会有多个元素,各自有独立的 id。我们上面的循环用 for _, call := range ... 已经天然支持——每个 call 都执行、都回传一条 role:tool 消息即可。少回传任何一个,接口会报错。
6.2 换成 Anthropic 接口有什么不同
如果你用 Claude 的 Messages API,机制一样,但字段名不同:
| 概念 | OpenAI | Anthropic |
|---|---|---|
| "要调工具"信号 | finish_reason: "tool_calls" | stop_reason: "tool_use" |
| 调用载体 | message.tool_calls[] | tool_use 内容块 |
| 参数格式 | JSON 字符串 | JSON 对象(已解析) |
| 回传结果 | role: "tool" 消息 | role: "user" 里放 tool_result 块 |
原理完全一致,理解了 OpenAI 版,换任何接口都是换字段名而已。
七、常见坑速查
| 坑 | 后果 | 正确做法 |
|---|---|---|
直接把 arguments 当对象用 | 崩溃/取不到值 | 它是 JSON 字符串,先 json.Unmarshal |
tool_call_id 没对应上 | 接口 400 报错 | 精确回传响应里的 id |
| 忘了先追加 assistant 消息 | 接口报错 | 先 append assistant(含 tool_calls),再 append tool 结果 |
| 并行调用只回传了一个结果 | 接口报错 | 每个 tool_call 都要回一条 tool 消息 |
用 content 判断是否结束 | 逻辑错误 | 用 finish_reason 判断,content 调工具时是 null |
| 没有 maxIterations | 可能死循环烧钱 | 必须加循环上限 |
八、小结与下一篇
- Tool Calling 的本质:LLM 只"说"要调什么工具,执行是你的代码干的。
- Agent 三角色:LLM(决策)、你的循环代码(执行)、工具函数(能力)。
- Agent 的"记忆"就是那个只增不减的
messages数组。 - 主循环不到 40 行:调模型 → 追加 assistant 消息 → 看 finish_reason → 执行工具并回传 → 循环,用
maxIterations兜底。
你现在已经有了一个能干活的 Agent 骨架。但它只有两个玩具工具。真实世界里,工具的设计质量直接决定 Agent 的能力上限——工具描述怎么写、参数怎么设计、出错了怎么返回、输出太长怎么办?
下一篇预告——《工具设计的艺术》:我们会把玩具工具升级成真实工具(读文件、发 HTTP、执行命令),并讲透工具设计的核心原则:粒度、Schema、错误处理、输出控制,以及让模型少犯错的"防呆设计"(poka-yoke)。这是从"能跑的 Agent"到"好用的 Agent"的关键一跃。
参考资料
| 资料 | 来源 |
|---|---|
| OpenAI Function Calling 官方指南 | developers.openai.com/api/docs/guides/function-calling |
| Function calling 请求/响应格式(含并行调用、流式) | learn.microsoft.com/azure/ai-services/openai/how-to/function-calling |
| Anthropic Tool Use 概览(tool_use / tool_result) | platform.claude.com/docs/en/agents-and-tools/tool-use/overview |
| Building Effective Agents(ground truth、循环设计) | anthropic.com/engineering/building-effective-agents |
| go-openai(Go 社区库,可对照其 tool 示例) | github.com/sashabaranov/go-openai |