如何做一个简单的 AI Agent

目录

大模型并不会真的去执行什么,它只是返回一个"我想调用某个函数、参数是这些"的结构化响应。真正干活的是客户端:拿到这个响应,找到对应的函数跑一遍,再把结果塞回对话。把"模型返回工具调用 → 客户端执行 → 结果塞回对话 → 再问模型"这个往返过程循环起来,一个Agent就成型了。

所以Agent并不神秘,它的骨架只有三样东西:一个大模型、一组能真正干活的工具、一个把两者串起来的循环。本文用Go写一个四百来行的版本,具备读写文件、列目录、执行shell命令的能力,能自己完成"创建 hello.go 并运行验证"这种任务。

Agent 的骨架

抛开各种框架的封装,一次完整的Agent执行过程是这样的:

用户任务
   ↓
[系统提示 + 任务] → 调用 LLM(带工具列表)
   ↓
模型返回:纯文本 或 工具调用
   ↓
有工具调用? ── 否 → 把文本作为最终答案返回
   │ 是
   ↓
执行工具,把结果以 role=tool 的消息追加进对话
   ↓
回到"调用 LLM",进入下一轮

这里有两个关键点,决定了 Agent 和普通的"一问一答"有什么不同:

  • 对话是要累积的。每一轮都要把历史消息(包括模型的工具调用和工具的执行结果)完整传回去,模型才知道自己上一轮干了什么、现在处于哪一步。
  • 循环要有出口。要么模型不再请求工具(说明它认为任务完成),要么轮数达到上限。少了这个约束,遇到模型"钻牛角尖"就会一直烧token。

下面的代码就是按这个骨架写的,分成四块:类型定义、工具实现、模型调用(流式解析)、主循环。

环境准备

只需要Go,不用第三方库——net/http加encoding/json就够了。模型接口按OpenAI兼容格式调用,所以DeepSeek、Kimi、vLLM、Ollama这些都能直接用。

准备一个.env放在程序同目录:

LLM_BASE_URL=https://api.deepseek.com/v1
LLM_API_KEY=sk-xxxxxx
LLM_MODEL_ID=deepseek-chat

LLM_BASE_URL要包含版本路径(比如/v1),因为代码里是直接拼/chat/completions的。

第一步:定义数据结构

先看类型定义。Tool是工具在程序里的表示:名字、给模型看的描述、参数的JSON Schema,以及真正执行的函数。

type Tool struct {
	Name        string
	Description string
	Parameters  map[string]any
	Execute     func(args map[string]any) (string, error)
}

Execute的签名值得留意:参数是map[string]any,返回string和error。也就是说工具的输入输出都被限制成"可以序列化的东西",因为返回值最终要作为文本塞回对话里。error不中断流程,而是会被转成文本交给模型看——这一点在主循环里会用到。

消息结构直接用OpenAI的字段名,这样序列化出去就能用:

type Message struct {
	Role       string     `json:"role"`
	Content    any        `json:"content"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

Content用的是any而不是string,因为同一套结构要表达三种消息:

  • 普通的用户/系统消息,Content是字符串;
  • 带工具调用的助手消息,Content是null(有工具调用时文本通常为空),信息在ToolCalls里;
  • 工具结果消息,Content是字符串,同时必须带上ToolCallID,告诉模型这是对哪一次调用的回应。

ToolCall的结构对应接口返回:

type ToolCall struct {
	Index    int    `json:"index"`
	ID       string `json:"id"`
	Type     string `json:"type"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function"`
}

这里有两个容易踩的细节:Arguments是一段字符串,不是对象,需要自己json.Unmarshal;Index在流式返回里用来标记"这是第几个工具调用",聚合分片时要用。

第二步:实现四个工具

工具本身没有任何魔法,就是普通的Go函数。决定它"能被模型用"的,是那几行描述和参数声明。

第一个是列目录:

{
	Name:        "list_dir",
	Description: "列出指定目录下的文件和子目录名",
	Parameters: map[string]any{
		"type": "object",
		"properties": map[string]any{
			"path": map[string]any{"type": "string", "description": "目录路径,默认当前目录"},
		},
	},
	Execute: func(args map[string]any) (string, error) {
		path := str(args, "path", ".")
		...
	},
}

Parameters是标准JSON Schema,会被原样发给模型,模型据此知道有哪些参数、什么类型、是不是必填。path没有放进required,所以在Execute里用str给了个默认值.——参数的可选性既影响模型的理解,也影响你的取值代码,两边要对齐。

read_file和write_file就更直接了,读的时候顺手截断,写的时候自动建父目录:

data, err := os.ReadFile(path)
if err != nil {
	return "", err
}
text := string(data)
if len(text) > 50_000 {
	text = text[:50_000] + "\n\n[文件过长,已截断]"
}

50KB 的截断是必须的。模型不知道这个文件有多大,你不截,它可能一口气把几 MB 的日志读进上下文,后面的请求直接超限。截断时还要留一句说明,否则模型会以为读到的是完整内容,基于残缺信息做出错误判断。

write_file里的os.MkdirAll同理,是为了让模型少犯"目录不存在"的错——这种错误本来可以避免,没必要浪费一轮对话。

真正的重头戏是run_command:

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

cmd := exec.CommandContext(ctx, "sh", "-c", cmdText)
var out bytes.Buffer
cmd.Stdout = &out
cmd.Stderr = &out
err := cmd.Run()

result := out.String()
if err != nil {
	if ctx.Err() == context.DeadlineExceeded {
		result += "\n[命令超时,已终止]"
	} else {
		result += fmt.Sprintf("\n[exit 错误: %v]", err)
	}
}
return truncate(result, 20_000), nil

三个要点:

  • 用CommandContext而不是exec.Command。模型很可能会执行go run、npm install或者一条卡住的命令,没有超时就会永久挂起。CommandContext在超时后会自动kill子进程,ctx.Err()也能区分"超时"和"命令本身失败"。
  • stdout和stderr合并到一个buffer。对模型来说这两者都是"命令的输出",分开反而要多解释一遍;合并之后它看到的就是终端里会看到的东西。
  • 命令失败不返回error。这里err只用来判断,结果照样拼进字符串,函数最终返回nil错误。因为"命令退出码非 0"对模型来说是有效的观察信息,它需要看到失败原因才能自己调整;如果当成工具异常抛出去,模型看到的信息反而更少。

两个小工具函数支撑上面这些逻辑:

func str(args map[string]any, key, def string) string {
	if v, ok := args[key].(string); ok {
		return v
	}
	return def
}

func truncate(s string, n int) string {
	if len(s) > n {
		return s[:n] + "\n[已截断]"
	}
	return s
}

第三步:流式调用大模型

callLLM做两件事:把消息和工具列表发出去,然后把流式响应解析成一个事件流。

先看请求体:

reqBody := map[string]any{
	"model":    os.Getenv("LLM_MODEL_ID"),
	"messages": messages,
	"stream":   true,
	"tools": func() []map[string]any {
		var ts []map[string]any
		for _, t := range tools {
			ts = append(ts, map[string]any{
				"type": "function",
				"function": map[string]any{
					"name":        t.Name,
					"description": t.Description,
					"parameters":  t.Parameters,
				},
			})
		}
		return ts
	}(),
}

tools这一段就是把手里的Tool翻译成接口要求的格式。因为这个结构每轮都一样,其实可以提前算好存起来,这里写成立即执行的闭包只是为了少一个全局变量。这一步是整个 Agent 的关键:没有它,模型只会聊天;有了它,模型才有"手"。

接着是SSE解析。开启stream后,响应体是一行行data: {...},最后以data: [DONE]结束:

scanner := bufio.NewScanner(resp.Body)
scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
for scanner.Err() == nil && scanner.Scan() {
	line := strings.TrimSpace(scanner.Text())
	if !strings.HasPrefix(line, "data:") {
		continue
	}
	payload := strings.TrimSpace(line[5:])
	if payload == "[DONE]" {
		break
	}
	...
}

为什么用Scanner而不是直接Read?因为Scanner是按行切的,网络分块导致的"半行"会被它自己拼回去,不用手写缓冲区管理。scanner.Buffer把单行上限从默认的 64KB 提到 1MB,是防止工具参数特别长(比如整个文件内容)时单行超限。

每一行payload解出来是一个增量chunk,里面可能有三种东西:思考过程(reasoning_content)、正文(content)、工具调用分片(tool_calls)。处理方式各不相同:

if delta.ReasoningContent != "" {
	events <- streamEvent{Type: "reasoning", Delta: delta.ReasoningContent}
}

if delta.Content != "" {
	content.WriteString(delta.Content)
	events <- streamEvent{Type: "text", Delta: delta.Content}
}

reasoning_content只送给界面显示(绿色打印),不存进下一轮消息。推理模型的思考过程不属于对话历史的一部分,塞回去反而可能触发接口报错或者干扰后续生成。

正文则一边累积到content,一边作为text事件发出去,让调用方可以实时打印。

真正麻烦的是tool_calls。流式返回里一个工具调用会被拆成很多片:第一片带id和函数名,后面的片只有arguments的片段,而且多个工具调用还会交错着来。所以要按index归并:

for _, tc := range delta.ToolCalls {
	idx := tc.Index
	if toolCalls[idx] == nil {
		c := tc
		toolCalls[idx] = &c
	} else {
		if tc.ID != "" {
			toolCalls[idx].ID += tc.ID
		}
		if tc.Function.Name != "" {
			toolCalls[idx].Function.Name += tc.Function.Name
		}
		if tc.Function.Arguments != "" {
			toolCalls[idx].Function.Arguments += tc.Function.Arguments
		}
	}
}

流结束后再把聚合结果组装成一条完整的助手消息:

msg := &Message{Role: "assistant", Content: content.String()}
if len(toolCalls) > 0 {
	for _, tc := range toolCalls {
		if tc.Type == "" {
			tc.Type = "function"
		}
		msg.ToolCalls = append(msg.ToolCalls, *tc)
	}
	msg.Content = nil
}
events <- streamEvent{Type: "done", Message: msg}

两个补丁:Type在流式分片里通常不带,回传时必须补成function,否则下一轮请求格式不合法;Content在有工具调用时置为nil,因为此时它的值是空字符串,而严格一点的接口要求这里是null。

另外,整个解析放在一个goroutine里,通过chan往外发事件,defer close(events)保证调用方range能正常结束。这样主循环可以像消费生成器一样,边收边打印。

第四步:主循环

runAgent是前面所有东西的汇合点,逻辑其实很短:

messages := []Message{
	{Role: "system", Content: "你是一个能读写文件、执行命令的编程助手。先观察,再动手,最后验证并汇报。"},
	{Role: "user", Content: task},
}

for turn := 0; turn < 30; turn++ {
	events, err := callLLM(messages)
	...
}

系统提示里那句"先观察,再动手,最后验证"不是装饰。它显著影响行为:没有它,模型经常直接凭想象写文件而不先list_dir;有了它,多数情况下会先看一眼目录、写完再跑一次验证。

每一轮的流程是:收事件流 → 拿到完整的助手消息 → 追加进历史 → 判断有没有工具调用。

var assistantMsg *Message
for ev := range events {
	switch ev.Type {
	case "text":
		fmt.Print(ev.Delta)
	case "reasoning":
		fmt.Print("\033[32m", ev.Delta, "\033[0m")
	default:
		assistantMsg = ev.Message
	}
}

default分支接的就是done事件。range在通道关闭时自然退出,所以不需要额外判断结束条件。

拿到完整消息后,第一件事是把整条助手消息原样追加进历史,而不是只追加工具结果:

messages = append(messages, *assistantMsg)

if len(assistantMsg.ToolCalls) == 0 {
	if s, ok := assistantMsg.Content.(string); ok {
		return s
	}
	return ""
}

这一行是整个循环里最容易被忽略、但少不得的一行。role=tool的结果消息只写了"结果是什么",没有写"这是对哪次调用的回应"——如果历史里缺了带tool_calls的那条助手消息,下一轮请求里就会有一堆ToolCallID指着不存在的调用,接口通常会直接报错(类似tool_call_id找不到对应的tool_calls),再严格一点的实现甚至会拒绝这种不配对的对话。

所以顺序必须是:助手消息(意图 + 参数)→ 工具结果消息(tool_call_id + 输出),两者成对出现。模型下一轮看到的历史长这样:

user      任务
assistant tool_calls: [list_dir]
tool      文件列表…
assistant tool_calls: [write_file]
tool      已写入…
assistant 任务完成了,我做了这些…

顺带说明两个"看起来像丢了内容"的地方,其实是故意的:

  • 带工具调用的这一轮,Content在解析时就被置成了nil(前面第三步讲过)。空字符串和nil在多数接口里语义不同,这里取null是为了格式稳妥;代价是如果模型在调用工具的同时还说了半句话,那段文本不会进历史。真在意的话,可以在有tool_calls时保留content.String()。
  • reasoning_content从头到尾都没进messages。思考过程不属于对话内容,回灌回去既浪费上下文,也可能被接口拒收。

而最后那一轮(没有工具调用)的回复是return出去的,不再append——因为它就代表任务结束,没有下一轮了。如果你想把 Agent 做成多轮可对话的,这里正是要把这条最终回复也存进历史的地方。

有工具调用,就逐个执行,并把结果作为role=tool的消息追加进去:

for _, call := range assistantMsg.ToolCalls {
	fmt.Printf("\n⚙️  [%s] %s\n", call.Function.Name, call.Function.Arguments)
	var result string
	tool := findTool(call.Function.Name)
	var args map[string]any
	json.Unmarshal([]byte(call.Function.Arguments), &args)

	if tool == nil {
		result = "错误:未知工具 " + call.Function.Name
	} else if r, err := tool.Execute(args); err != nil {
		result = "工具执行出错: " + err.Error()
	} else {
		result = r
	}
	fmt.Printf("📤 %s\n\n", truncate(result, 200))
	messages = append(messages, Message{
		Role:       "tool",
		Content:    result,
		ToolCallID: call.ID,
	})
}

注意错误处理的思路:工具不存在、参数缺失、执行报错,这三种情况都不是致命错误,而是转成一句描述性文本交给模型。模型下一轮看到"缺少 path 参数",通常就会自己补上参数重试。这是 Agent 比传统脚本"聪明"的地方——它在一个反馈回路里,而不是一条写死的直线。

json.Unmarshal的返回值这里被忽略了,参数不是合法JSON时会得到一个空map,最后以"缺少参数"的形式反馈给模型——能跑,但正式代码里更稳妥的做法是把解析错误也当成一条观察结果说明清楚。

fmt.Printf那两行只是给人看的:⚙️显示模型想调什么工具、参数是什么,📤显示截断到 200 字符的执行结果。真正发给模型的是完整结果,界面上的短预览只是为了不让终端刷屏。

循环跑满 30 轮还没结束,就直接返回一句话收尾,避免死循环。

findTool是个平凡的线性查找:

func findTool(name string) *Tool {
	for i := range tools {
		if tools[i].Name == name {
			return &tools[i]
		}
	}
	return nil
}

工具只有四个,查找开销可以忽略;真做到几十个工具时,换成map[string]*Tool更合适。

入口与 .env 加载

最后是loadEnv和main。loadEnv只是一个极简的KEY=VALUE解析,跳过空行和#注释:

parts := strings.SplitN(line, "=", 2)
if len(parts) != 2 {
	continue
}
key := strings.TrimSpace(parts[0])
value := strings.TrimSpace(parts[1])
os.Setenv(key, value)

用SplitN(..., 2)是因为value里可能还有=(比如base64的密钥),只切第一个等号才不会把值截坏。

main里检查三个环境变量是否齐全,然后拿命令行参数当任务;不给参数就用默认任务:

task := "在当前目录创建 hello.go 输出 Hello World,然后用 go run 验证"
if len(os.Args) > 1 {
	task = os.Args[1]
}
fmt.Println(runAgent(task))

默认任务选得很小,但它完整体现了Agent的标志性行为:先写文件,再执行,最后根据执行结果决定是否结束。这正是"聊天"和"干活"的分界线。

跑起来

$ go mod init agent
$ go run . "把当前目录下的 go 文件列出来,统计每个文件多少行"

终端里会看到绿色的思考内容、逐字出现的正文,以及每次工具调用的参数和返回摘要。整个过程大概几秒到几十秒,取决于任务要跑多少轮。

如果模型反复在同一个地方打转,先看两类信息:系统提示里的约束够不够明确,以及工具返回的错误信息是否足够具体。“错误:未知工具 xxx"这种回复,模型基本只能换一种猜法;而"缺少 path 参数"它就能立刻改对。

几个值得注意的坑

代码能跑,但离"能用"还有距离,下面几点是实现过程中觉得最该知道的:

  • run_command等于把shell交出去了。模型可能执行rm、可能改配置、可能访问网络。真实场景至少要加白名单、目录隔离或者人工确认;本文为了保持简洁没有做,自己跑的时候最好在临时目录里。
  • 上下文会一直涨。每轮都往里追加消息和工具结果,长任务很容易顶到模型上限。工具输出的截断只是止血,正经做法是做摘要压缩,或者把大结果落到文件里只回传路径。
  • 多个工具调用时顺序不保证。聚合用的是map[int]*ToolCall,遍历map的顺序是随机的。好在回传时靠tool_call_id配对,一般不影响正确性;但如果模型在一轮里调了多个工具、并且有依赖关系,按Index排一下序会更稳。
  • 流式响应没有做取消。用户按Ctrl+C时请求还会继续跑。想做得细一点,可以把context一路传进callLLM,用http.NewRequestWithContext。
  • 接口出错时会把Header打出来,而Authorization就在里面。调试时可以这样看,正式使用前记得删掉。
  • 只有一次任务,没有会话。每次运行都是全新的messages,想做成多轮对话的助手,需要把历史消息跨任务保存下来。

把这些补齐之后,它就更像一个"产品"了;而核心的百来行逻辑,其实已经都在这里。

完整源码

下面的代码就是上面所有片段合起来的样子。

package main

import (
	"bufio"
	"bytes"
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"net/http"
	"os"
	"os/exec"
	"path/filepath"
	"strings"
	"time"
)

type Tool struct {
	Name        string
	Description string
	Parameters  map[string]any
	Execute     func(args map[string]any) (string, error)
}

type Message struct {
	Role       string     `json:"role"`
	Content    any        `json:"content"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

type ToolCall struct {
	Index    int    `json:"index"`
	ID       string `json:"id"`
	Type     string `json:"type"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function"`
}

var tools = []Tool{
	{
		Name:        "list_dir",
		Description: "列出指定目录下的文件和子目录名",
		Parameters: map[string]any{
			"type": "object",
			"properties": map[string]any{
				"path": map[string]any{"type": "string", "description": "目录路径,默认当前目录"},
			},
		},
		Execute: func(args map[string]any) (string, error) {
			path := str(args, "path", ".")
			entries, err := os.ReadDir(path)
			if err != nil {
				return "", err
			}
			var names []string
			for _, e := range entries {
				n := e.Name()
				if e.IsDir() {
					n += "/"
				}
				names = append(names, n)
			}
			return strings.Join(names, "\n"), nil
		},
	},
	{
		Name:        "read_file",
		Description: "读取文件内容(UTF-8 文本),超过 50KB 截断",
		Parameters: map[string]any{
			"type": "object",
			"properties": map[string]any{
				"path": map[string]any{"type": "string", "description": "文件路径"},
			},
			"required": []string{"path"},
		},
		Execute: func(args map[string]any) (string, error) {
			path := str(args, "path", "")
			if path == "" {
				return "", errors.New("缺少 path 参数")
			}
			data, err := os.ReadFile(path)
			if err != nil {
				return "", err
			}
			text := string(data)
			if len(text) > 50_000 {
				text = text[:50_000] + "\n\n[文件过长,已截断]"
			}
			return text, nil
		},
	},
	{
		Name:        "write_file",
		Description: "将文本写入文件,存在则覆盖,不存在则创建(自动创建父目录)",
		Parameters: map[string]any{
			"type": "object",
			"properties": map[string]any{
				"path":    map[string]any{"type": "string"},
				"content": map[string]any{"type": "string"},
			},
			"required": []string{"path", "content"},
		},
		Execute: func(args map[string]any) (string, error) {
			path := str(args, "path", "")
			content := str(args, "content", "")
			if path == "" {
				return "", errors.New("缺少 path 参数")
			}
			if dir := filepath.Dir(path); dir != "." {
				if err := os.MkdirAll(dir, 0o755); err != nil {
					return "", err
				}
			}
			if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
				return "", err
			}
			return fmt.Sprintf("已写入 %s(%d 字符)", path, len(content)), nil
		},
	},
	{
		Name:        "run_command",
		Description: "执行一条 shell 命令,返回 stdout/stderr,超时 30 秒",
		Parameters: map[string]any{
			"type": "object",
			"properties": map[string]any{
				"command": map[string]any{"type": "string", "description": "要执行的命令"},
			},
			"required": []string{"command"},
		},
		Execute: func(args map[string]any) (string, error) {
			cmdText := str(args, "command", "")
			if cmdText == "" {
				return "", errors.New("缺少 command 参数")
			}

			ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
			defer cancel()

			cmd := exec.CommandContext(ctx, "sh", "-c", cmdText)
			var out bytes.Buffer
			cmd.Stdout = &out
			cmd.Stderr = &out
			err := cmd.Run()

			result := out.String()
			if err != nil {
				if ctx.Err() == context.DeadlineExceeded {
					result += "\n[命令超时,已终止]"
				} else {
					result += fmt.Sprintf("\n[exit 错误: %v]", err)
				}
			}
			return truncate(result, 20_000), nil
		},
	},
}

func str(args map[string]any, key, def string) string {
	if v, ok := args[key].(string); ok {
		return v
	}
	return def
}

func truncate(s string, n int) string {
	if len(s) > n {
		return s[:n] + "\n[已截断]"
	}
	return s
}

type streamEvent struct {
	Type    string
	Delta   string
	Message *Message
}

func callLLM(messages []Message) (<-chan streamEvent, error) {
	reqBody := map[string]any{
		"model":    os.Getenv("LLM_MODEL_ID"),
		"messages": messages,
		"stream":   true,
		"tools": func() []map[string]any {
			var ts []map[string]any
			for _, t := range tools {
				ts = append(ts, map[string]any{
					"type": "function",
					"function": map[string]any{
						"name":        t.Name,
						"description": t.Description,
						"parameters":  t.Parameters,
					},
				})
			}
			return ts
		}(),
	}
	body, _ := json.Marshal(reqBody)

	req, _ := http.NewRequest("POST", os.Getenv("LLM_BASE_URL")+"/chat/completions", bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LLM_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	if resp.StatusCode != 200 {
		buf := new(bytes.Buffer)
		buf.ReadFrom(resp.Body)
		resp.Body.Close()
		fmt.Println(req.Header)
		fmt.Println(string(body))
		return nil, fmt.Errorf("API 错误 %d: %s", resp.StatusCode, buf.String())
	}

	events := make(chan streamEvent)
	go func() {
		defer resp.Body.Close()
		defer close(events)

		var content strings.Builder
		toolCalls := map[int]*ToolCall{}

		scanner := bufio.NewScanner(resp.Body)
		scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
		for scanner.Err() == nil && scanner.Scan() {
			line := strings.TrimSpace(scanner.Text())
			if !strings.HasPrefix(line, "data:") {
				continue
			}
			payload := strings.TrimSpace(line[5:])
			if payload == "[DONE]" {
				break
			}

			var chunk struct {
				Choices []struct {
					Delta struct {
						ReasoningContent string     `json:"reasoning_content"`
						Content          string     `json:"content"`
						ToolCalls        []ToolCall `json:"tool_calls"`
					} `json:"delta"`
				} `json:"choices"`
			}
			if err := json.Unmarshal([]byte(payload), &chunk); err != nil {
				continue
			}
			if len(chunk.Choices) == 0 {
				continue
			}
			delta := chunk.Choices[0].Delta

			if delta.ReasoningContent != "" {
				events <- streamEvent{Type: "reasoning", Delta: delta.ReasoningContent}
			}

			if delta.Content != "" {
				content.WriteString(delta.Content)
				events <- streamEvent{Type: "text", Delta: delta.Content}
			}
			for _, tc := range delta.ToolCalls {
				idx := tc.Index
				if toolCalls[idx] == nil {
					c := tc
					toolCalls[idx] = &c
				} else {
					if tc.ID != "" {
						toolCalls[idx].ID += tc.ID
					}
					if tc.Function.Name != "" {
						toolCalls[idx].Function.Name += tc.Function.Name
					}
					if tc.Function.Arguments != "" {
						toolCalls[idx].Function.Arguments += tc.Function.Arguments
					}
				}
			}
		}

		msg := &Message{Role: "assistant", Content: content.String()}
		if len(toolCalls) > 0 {
			for _, tc := range toolCalls {
				if tc.Type == "" {
					tc.Type = "function"
				}
				msg.ToolCalls = append(msg.ToolCalls, *tc)
			}
			msg.Content = nil
		}
		events <- streamEvent{Type: "done", Message: msg}
	}()
	return events, nil
}

func runAgent(task string) string {
	messages := []Message{
		{Role: "system", Content: "你是一个能读写文件、执行命令的编程助手。先观察,再动手,最后验证并汇报。"},
		{Role: "user", Content: task},
	}

	for turn := 0; turn < 30; turn++ {
		events, err := callLLM(messages)
		if err != nil {
			return "调用失败: " + err.Error()
		}

		var assistantMsg *Message
		for ev := range events {
			switch ev.Type {
			case "text":
				fmt.Print(ev.Delta)
			case "reasoning":
				fmt.Print("\033[32m", ev.Delta, "\033[0m")
			default:
				assistantMsg = ev.Message
			}
		}
		fmt.Println()

		messages = append(messages, *assistantMsg)

		if len(assistantMsg.ToolCalls) == 0 {
			if s, ok := assistantMsg.Content.(string); ok {
				return s
			}
			return ""
		}

		for _, call := range assistantMsg.ToolCalls {
			fmt.Printf("\n⚙️  [%s] %s\n", call.Function.Name, call.Function.Arguments)
			var result string
			tool := findTool(call.Function.Name)
			var args map[string]any
			json.Unmarshal([]byte(call.Function.Arguments), &args)

			if tool == nil {
				result = "错误:未知工具 " + call.Function.Name
			} else if r, err := tool.Execute(args); err != nil {
				result = "工具执行出错: " + err.Error()
			} else {
				result = r
			}
			fmt.Printf("📤 %s\n\n", truncate(result, 200))
			messages = append(messages, Message{
				Role:       "tool",
				Content:    result,
				ToolCallID: call.ID,
			})
		}
	}
	return "达到最大轮数,任务未完成"
}

func findTool(name string) *Tool {
	for i := range tools {
		if tools[i].Name == name {
			return &tools[i]
		}
	}
	return nil
}

func loadEnv(filename string) error {
	file, err := os.Open(filename)
	if err != nil {
		return err
	}
	defer file.Close()

	scanner := bufio.NewScanner(file)
	for scanner.Scan() {
		line := scanner.Text()
		if line == "" || strings.HasPrefix(line, "#") {
			continue
		}
		parts := strings.SplitN(line, "=", 2)
		if len(parts) != 2 {
			continue
		}
		key := strings.TrimSpace(parts[0])
		value := strings.TrimSpace(parts[1])
		os.Setenv(key, value)
	}
	return scanner.Err()
}

func main() {
	if err := loadEnv(".env"); err != nil {
		fmt.Println("加载 .env 文件出错:", err)
	}

	if os.Getenv("LLM_BASE_URL") == "" || os.Getenv("LLM_API_KEY") == "" || os.Getenv("LLM_MODEL_ID") == "" {
		fmt.Println(os.Getenv("LLM_BASE_URL"))
		fmt.Println("请先设置环境变量:export LLM_BASE_URL=x LLM_API_KEY=xx LLM_MODEL_ID=xx")
		os.Exit(1)
	}
	task := "在当前目录创建 hello.go 输出 Hello World,然后用 go run 验证"
	if len(os.Args) > 1 {
		task = os.Args[1]
	}
	fmt.Println(runAgent(task))
}

写到这里,一个可用的最小Agent就完整了。它没有记忆、没有多模态、没有复杂规划,但"模型决定调什么工具、程序执行、结果回灌"这个循环是完整的,市面上那些花哨的 Agent 产品往回追一层,核心也无非是这套东西加上更多的工具和更严的约束。