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": "{}"
            }
          }
        ]
      }
    }
  ]
}

三个必须记住的细节:

2.3 回传结果:把工具输出喂回去

执行完工具,你要往 messages 里追加两条消息:先追加模型那条 tool_calls 消息(原样),再追加一条 role: "tool" 的结果消息:

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "2026-09-21 14:30:00"
}

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
        # 带着工具结果继续下一轮循环
    返回 错误("超过最大轮数")

三个停止条件缺一不可:


四、动手:完整可运行的 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 可能死循环烧钱 必须加循环上限

八、小结与下一篇

你现在已经有了一个能干活的 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