Agent开发完全实战指南(一)什么是Agent
你写了一个调用 LLM 的接口,能一问一答,挺好。这时候老板说:"给咱们做个 Agent 吧。"
你打开一堆框架文档,满屏的 ReAct、Orchestrator、Multi-Agent、Memory,越看越懵。到底什么是 Agent?它和你已经写好的那个"聊天接口"差在哪?是不是把接口套个循环就叫 Agent 了?
先记住 Anthropic 那句最朴素的定义,本系列都建立在它之上:
Agent 本质上就是"一个在循环里使用工具的 LLM"(LLMs using tools based on environmental feedback in a loop)。
这一篇不写复杂代码。我们先把"Agent 到底是什么"彻底讲透,再用 Go 调通第一个 LLM 请求,亲眼看到"裸 LLM 为什么不会干活"——这正是我们后面要解决的问题。
一、先说人话:Agent、Workflow、裸 LLM 的区别
很多人把"调用了 LLM 的程序"都叫 Agent,这是最大的误区。三者的差别,核心就一个问题:谁在决定下一步做什么?
裸 LLM:只会预测文字
一个裸 LLM 的能力边界非常清晰:你给它一段文字,它接着往下写一段文字。 仅此而已。
它不能查数据库、不能读文件、不能调接口、记不住上一通对话(除非你把历史再喂给它)。你问它"现在几点",它要么拒绝,要么一本正经地编一个时间给你——因为它没有任何"感知世界"的手段。
Augmented LLM:给 LLM 装上手脚
Anthropic 把 Agent 系统的最小积木叫做 Augmented LLM:
The basic building block of agentic systems is an LLM enhanced with augmentations such as retrieval, tools, and memory.
翻译成人话:给裸 LLM 接上三样东西——工具(能干活)、检索(能查资料)、记忆(能记事)。 装上这三样,LLM 才从"只会聊天"变成"能感知世界、能改变世界"。
这是理解 Agent 的第一块基石。后面所有文章,本质上都在教你怎么把这三样东西做好。
Workflow vs Agent:控制流归谁
有了 Augmented LLM,把它们组装起来干活,就有两种路数:
先说人话定义:
- Workflow(工作流):干活的步骤是你用代码写死的。LLM 只在你规定的某几个格子里发挥,走哪条路、走几步,是代码说了算。
- Agent(智能体):干活的步骤是 LLM 自己临场决定的。它自己判断该调哪个工具、要不要再来一步、什么时候算干完了。
LangChain 给了三个诊断问题,帮你判断一个系统到底偏 Workflow 还是偏 Agent:
- 每一步的输出是谁决定的?
- 下一步走哪是谁决定的?
- 有哪些步骤可选是谁决定的?
答案越是"代码",越偏 Workflow;越是"模型",越偏 Agent。
关键洞察:Workflow 和 Agent 不是非黑即白,而是一条光谱。控制流交给模型的比例越高,系统就越"Agentic"。绝大多数生产系统都落在两者之间。
三者对比:
| 维度 | 裸 LLM | Workflow | Agent |
|---|---|---|---|
| 能否调用工具 | 否 | 能(代码编排) | 能(模型自主调用) |
| 谁决定下一步 | 无"下一步" | 你的代码 | LLM 自己 |
| 步骤数是否固定 | — | 固定 | 不固定,动态决定 |
| 确定性 | 高 | 高 | 低(有不确定性) |
| 适合场景 | 单轮问答、分类 | 步骤清晰、可预先拆解的任务 | 步骤无法预测的开放性任务 |
| 调试难度 | 低 | 中 | 高 |
二、Agent 的核心:那个"循环"
Agent 之所以能"自己干活",靠的就是一个循环。把上面那句定义拆开:
LLM 决定一个动作 → 工具执行 → 把结果(观察)喂回给 LLM → LLM 再决定下一个动作 → …… 直到它认为任务完成。
画成图:
flowchart TD
Start([用户下达任务]) --> LLM[LLM 思考:
下一步该做什么?]
LLM --> Decide{需要调用工具吗?}
Decide -->|需要| Tool[执行工具
查数据/读文件/调接口]
Tool --> Obs[把工具结果
喂回对话历史]
Obs --> LLM
Decide -->|不需要,任务完成| Answer([输出最终答案])这里有一个容易被忽略但至关重要的点,Anthropic 专门强调过:
it's crucial for the agents to gain 'ground truth' from the environment at each step (such as tool call results or code execution).
关键洞察:循环里的每一步,Agent 都必须从真实环境拿到"实锤"(工具返回、代码执行结果),而不是自己脑补。 这就是 Agent 比裸 LLM 可靠的根本原因——它不靠猜,它去查。
循环什么时候停?两种情况:
- 正常结束:LLM 觉得任务干完了,直接输出文字答案(不再要求调工具)。
- 强制结束:达到最大轮数(maxIterations)等停止条件,防止它无限循环下去。
这个循环我们会在 第 02 篇 用 Go 从零手写。这一篇你只要理解它的形状。
三、别急着上 Agent:先认识五种 Workflow 模式
新手最容易犯的错,是给什么都套一个 Agent。Anthropic 反复强调的第一原则是:
find the simplest solution possible, and only increase complexity when needed.
很多需求根本不需要"让模型自己决定流程",一个写死的 Workflow 又快、又便宜、又稳定。下面五种 Workflow 模式,是你在掏出 Agent 之前应该先考虑的武器:
| 模式 | 一句话说清 | 适合场景 | 例子 |
|---|---|---|---|
| Prompt Chaining(提示链) | 把任务拆成固定的几步,前一步输出喂给后一步 | 任务能干净地拆成固定子步骤 | 先写文档大纲 → 校验大纲 → 再写正文 |
| Routing(路由) | 先分类,再分发到对应的专门处理流程 | 输入有明显不同的类别,分开处理更好 | 客服问题分成"退款/技术/咨询"分别处理;简单问题走便宜模型,难题走强模型 |
| Parallelization(并行) | 多个 LLM 调用同时跑,再把结果汇总 | 子任务相互独立,或想多次投票提高置信度 | 一个模型答题、另一个同时审查内容合规;多个模型投票查代码漏洞 |
| Orchestrator-Workers(编排者-执行者) | 一个主 LLM 动态拆任务,派给多个执行者,再汇总 | 子任务无法预先写死,要看输入临场拆 | 跨多个文件改代码;多来源检索后综合 |
| Evaluator-Optimizer(评估-优化) | 一个 LLM 生成,另一个 LLM 评估并反馈,循环改进 | 有明确的评价标准,且反馈能提升质量 | 文学翻译反复打磨;多轮研究直到评估者认为够了 |
关键洞察:后两种(Orchestrator-Workers、Evaluator-Optimizer)已经带了循环和动态性,长得很像 Agent,但只要"整体结构是代码写死的",它就还是 Workflow。真正跨入 Agent,是当步骤的数量和类型完全由 LLM 在运行时决定。
四、决策指南:什么时候该用 Agent
这是本篇最该收藏的一节。综合 Anthropic 和 OpenAI 的建议:
该用 Agent 的信号:
- 步骤数无法预测:开放性问题,你事先根本不知道要走几步、走哪几步。这是 Agent 最核心的适用场景。
- 需要复杂判断:要处理大量例外、要根据上下文灵活决策,写死的规则搞不定。
- 规则多到难以维护:if-else 已经堆成一坨看不懂的意大利面。
- 重度依赖非结构化数据:需要理解自然语言、分析文档、多轮对话。
不该用 Agent 的信号:
- 任务步骤清晰固定 → 用 Workflow,甚至普通代码。
- 对延迟、成本、确定性要求高 → Agent 会更慢、更贵、结果不稳定。
- 一次带检索和示例的 LLM 调用就能解决 → 别加循环。
记住这两句业界共识:
Agentic systems often trade latency and cost for better task performance.(Agent 是用延迟和成本换任务表现。)
A team that reaches for an agent when a workflow will do introduces non-determinism they do not need.(该用 Workflow 却硬上 Agent,等于给自己引入不需要的不确定性。)
一个简单的决策树:
flowchart TD
Q1{任务步骤能
提前写死吗?} -->|能| W[用 Workflow
或普通代码]
Q1 -->|不能,要临场决定| Q2{值得为此
牺牲延迟和成本吗?}
Q2 -->|不值得| W
Q2 -->|值得| Q3{在可信/可沙箱
的环境里运行吗?}
Q3 -->|否,高风险不可逆| HITL[用 Agent
但必须加 human-in-the-loop]
Q3 -->|是| AGENT[放心上 Agent]五、动手:调通你的第一个 LLM 请求
概念讲够了,开始动手。这一篇的目标很小但很关键:用 Go 原生 HTTP 调通一次 LLM 调用,并亲眼看到"裸 LLM 不会干活"。
我们不用任何 SDK,直接手拼 HTTP 请求。因为理解 Agent 的第一步,就是理解你和 LLM 之间到底在传什么。
5.1 准备环境变量
教程全程使用 OpenAI 兼容接口(OpenAI 官方、Ollama、vLLM、公司内部网关都行)。设置两个环境变量:
# 你的 API 密钥
export OPENAI_API_KEY="sk-xxxxxxxx"
# 接口地址,OpenAI 官方是这个;换成你自己的兼容网关也行
export OPENAI_BASE_URL="https://api.openai.com/v1"
5.2 理解请求长什么样
一次最基础的对话请求,body 就三个关键字段:
{
"model": "gpt-4o-mini",
"messages": [
{ "role": "user", "content": "现在几点了?" }
]
}
model:用哪个模型。messages:对话历史,是个数组。role有三种:system(系统指令)、user(用户说的)、assistant(模型说的)。- 这个
messages数组会成为整个 Agent 系列的主角——Agent 的"记忆"和"循环",本质上就是在往这个数组里不断追加内容。 请记住它。
5.3 写代码
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
)
// Message 对应 messages 数组里的一条消息
// role 取值:system / user / assistant
type Message struct {
Role string `json:"role"`
Content string `json:"content"`
}
// ChatRequest 是发给 LLM 的请求体,遵循 OpenAI Chat Completions 格式
type ChatRequest struct {
Model string `json:"model"`
Messages []Message `json:"messages"`
}
// ChatResponse 只解析我们关心的字段
type ChatResponse struct {
Choices []struct {
Message Message `json:"message"`
FinishReason string `json:"finish_reason"` // 结束原因,后面会重点用到
} `json:"choices"`
}
func main() {
apiKey := os.Getenv("OPENAI_API_KEY")
baseURL := os.Getenv("OPENAI_BASE_URL")
if baseURL == "" {
baseURL = "https://api.openai.com/v1" // 默认走 OpenAI 官方
}
// 1. 构造请求体:问一个"裸 LLM 答不了"的问题
reqBody := ChatRequest{
Model: "gpt-4o-mini",
Messages: []Message{
{Role: "user", Content: "现在几点了?请直接告诉我当前的准确时间。"},
},
}
buf, _ := json.Marshal(reqBody)
// 2. 拼 HTTP 请求
req, _ := http.NewRequest("POST", baseURL+"/chat/completions", bytes.NewReader(buf))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey) // 密钥放在 Authorization 头
// 3. 发送
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
// 4. 解析响应
body, _ := io.ReadAll(resp.Body)
var chatResp ChatResponse
if err := json.Unmarshal(body, &chatResp); err != nil {
fmt.Println("原始响应:", string(body)) // 出错时打印原始返回,方便排查
panic(err)
}
// 5. 打印结果
fmt.Println("模型回答:", chatResp.Choices[0].Message.Content)
fmt.Println("结束原因:", chatResp.Choices[0].FinishReason)
}
5.4 跑起来
cd code/01-hello-llm
go mod init hello-llm # 首次运行需要初始化模块
go run main.go
5.5 观察:裸 LLM 是怎么"露馅"的
你会看到类似这样的输出:
模型回答: 抱歉,我无法获取实时信息,无法告诉你当前的准确时间。你可以查看设备上的时钟……
结束原因: stop
或者更糟——它一本正经地编了个时间给你。
这就是裸 LLM 的天花板:它没有任何手段去"感知"真实世界。 问它当前时间、让它查数据库、让它读一个文件,它统统做不到,只能拒绝或者胡编。
注意那个 finish_reason: "stop",意思是"模型正常说完话了"。记住这个字段——在第 02 篇,当我们给它接上工具后,你会看到它变成 tool_calls,那一刻,裸 LLM 就进化成 Agent 了。
六、几个必须认识的术语
后面文章会反复出现,先建立印象即可:
| 术语 | 人话解释 |
|---|---|
| Augmented LLM | 接上了工具、检索、记忆的 LLM,是 Agent 的最小积木 |
| Tool Use / Function Calling | LLM 调用外部函数/接口的机制。它输出"我要调用哪个工具、传什么参数",你的代码去执行。这是 Agent 循环里的原子动作 |
| ReAct | Reasoning + Acting,让模型"边推理边行动"交替进行。现代 Agent 循环的思想源头 |
| Chain-of-Thought (CoT) | 让模型先写出中间推理步骤再给答案,"想清楚再回答" |
| Human-in-the-loop (HITL) | 在关键节点(如高风险、不可逆操作)暂停,让人来审批 |
| Ground Truth | 从真实环境拿到的"实锤"(工具结果、代码执行结果),Agent 靠它而不是靠猜 |
七、小结与下一篇
这一篇我们没写复杂代码,但打下了整个系列最重要的地基:
- Agent = 在循环里使用工具的 LLM,核心区别在于"下一步做什么"是模型自己决定的。
- 裸 LLM → Augmented LLM → Workflow → Agent 是一条能力递进的光谱。
- 五种 Workflow 模式是你掏出 Agent 之前该先考虑的选择,能用简单方案就别上 Agent。
- 你已经用 Go 调通了第一个 LLM 请求,并亲眼看到裸 LLM "不会干活"的天花板。
决策指南(本篇最该带走的):
任务步骤能写死 → Workflow;步骤无法预测、值得用延迟和成本去换 → Agent;高风险不可逆 → Agent + human-in-the-loop。
下一篇预告——《手写第一个 Agent 循环:Tool Calling 原理与实现》:我们会给这个裸 LLM 接上第一个工具,从零手写 Agent 主循环,让它真正能查到"现在几点"。你会看到 finish_reason 从 stop 变成 tool_calls,亲手见证裸 LLM 进化成 Agent 的那一刻。
参考资料
| 资料 | 来源 |
|---|---|
| Building Effective Agents(Agent 设计第一性原理,必读) | anthropic.com/engineering/building-effective-agents |
| What is an AI agent?(Workflow-Agent 光谱、三个诊断问题) | langchain.com/blog/what-is-an-agent |
| A Practical Guide to Building Agents(OpenAI 官方指南) | openai.com/business/guides-and-resources |
| ReAct: Synergizing Reasoning and Acting(Agent 循环思想源头) | arxiv.org/abs/2210.03629 |
| OpenAI Chat Completions / Function Calling 官方文档 | developers.openai.com/api/docs/guides/function-calling |