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,把它们组装起来干活,就有两种路数:

先说人话定义:

LangChain 给了三个诊断问题,帮你判断一个系统到底偏 Workflow 还是偏 Agent:

  1. 每一步的输出是谁决定的?
  2. 下一步走哪是谁决定的?
  3. 有哪些步骤可选是谁决定的?

答案越是"代码",越偏 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 可靠的根本原因——它不靠猜,它去查。

循环什么时候停?两种情况:

这个循环我们会在 第 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 的信号:

记住这两句业界共识:

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": "现在几点了?" }
  ]
}

5.3 写代码

新建 code/01-hello-llm/main.go:

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 靠它而不是靠猜

七、小结与下一篇

这一篇我们没写复杂代码,但打下了整个系列最重要的地基:

决策指南(本篇最该带走的):

任务步骤能写死 → 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