企业官网建设流程全解析

最近后台收到不少同学留言，问题非常一致：“我已经会调大模型 API 了，为什么还是写不出 Agent？”

这个困惑我太理解了。很多人的 Agent 开发之路，是从“把 Prompt 塞进模型”开始的。输入一段话，返回一段结果，好像任务完成了。但做着做着就会发现，这只是在调用接口，距离真正的 Agent 差得很远。

真正把 Agent 开发串起来的，其实是三个词：Agent、Loop、Graph。

如果你去翻各类 Agent 框架的源码，去看面试题里的高频考点，去观察那些“看起来很能打”的智能体项目，你会发现它们兜兜转转都在围绕这三个概念展开。它们不是三个并列的技术点，而是一条递进路径：

• Agent是单次的智能单元，负责“理解任务 + 调用能力”；
• Loop让 Agent 从“回答一次”变成“循环思考、行动、观察”，这是 ReAct 模式的核心；
• Graph则把循环流程变成可控制、可分支、可人工介入的编排图。

理解这条递进关系，相当于拿到一张 Agent 开发的核心地图。这篇文章不打算堆概念，而是把这三段拆开揉碎，配合代码演进示例，帮你把 Agent 开发的学习路线理清楚，同时也讲明白一个很多人没意识到的问题：框架里的 Loop 和 Graph，到底是解决什么问题的。

1. 为什么要把 Agent、Loop、Graph 放在一张地图里看

先说一个现象。很多人学 Agent，学得很散：今天看 LangChain 文档，明天研究 ReAct 论文，后天跑到 LangGraph 里折腾图状态。每个概念单独看好像都懂，但落到自己项目里就不知道怎么组合。

问题出在哪？出在没有先建立“三段递进”的整体框架。

传统软件开发里，我们习惯用函数、模块、流程来控制程序。但 Agent 不一样，它的行为不是“写死的”，而是由模型在运行时动态决策的。这个变化带来一个核心矛盾：既要给模型足够的自主性，又要让流程足够可控。

第一段 Agent：解决“模型如何拥有工具和目标”。 第二段 Loop：解决“模型如何迭代地逼近一个复杂目标”。 第三段 Graph：解决“多步骤、多分支、多 Agent 的流程如何被工程化地管理”。

这三层不是替代关系，而是叠加关系。你在实际项目里做多轮对话 Agent，可能只需要 Loop；做复杂的自动化工作流 Agent，就必须上 Graph。把这张地图装进脑子里，你看框架文档时的视角会完全不同：你不再是在学“某个框架的某个 API”，而是在理解“不同框架是如何实现这三段能力的”。

2. 第一段：Agent 是“有工具、有目标、有约束”的智能单元

2.1 Agent 不等于大模型

这是最容易被混淆的一点。

大模型（LLM）本身只是一个“文本推理引擎”，输入文本、输出文本。你问它“今天天气怎么样”，它只能凭训练数据猜测，无法获取实时的天气信息。而 Agent 的定位是：一个能感知环境、做出决策、调用工具、完成目标的智能体系统。

一个典型的 Agent，至少包含四个部分：

很多初学者把“调大模型”当成“写 Agent”，其实差的就是后面这三块。没有工具，Agent 只能“说”不能“做”；没有记忆，Agent 无法处理多轮上下文；没有约束，Agent 的输出可能完全偏离业务场景。

2.2 最小 Agent 的代码形态

下面是一个非常简化的 Agent 调用示意，重点是让你看到“Agent”和“直接调接口”的区别：

# 文件：simple_agent_demo.py from typing import List, Dict from datetime import datetime # 工具清单：Agent 可以调用的能力 TOOLS = { "get_current_time": datetime.now().strftime, "calculate": lambda expr: eval(expr) # 仅演示，实际项目不要用 eval } def call_llm(messages: List[Dict[str, str]]) -> str: """ 这里只是占位函数。 真实项目中会替换为具体的大模型 API 调用，并传入模型名称、温度等参数。 """ # 简化逻辑：如果消息里出现“几点了”，就返回一个时间工具调用指令 if "几点了" in messages[-1]["content"]: return "ACTION: get_current_time" return "ANSWER: 我无法直接回答，需要工具协助。" def run_simple_agent(user_input: str) -> str: messages = [{"role": "user", "content": user_input}] response = call_llm(messages) if response.startswith("ACTION:"): tool_name = response.split(":", 1)[1].strip() tool_fn = TOOLS[tool_name] result = tool_fn() return f"工具执行结果：{result}" return response if __name__ == "__main__": print(run_simple_agent("现在几点了？"))

这个例子不是完整生产代码，但它展示了 Agent 的基本骨架：模型负责判断需要什么操作，程序负责执行工具并返回结果。

这也就是 Agent 开发的第一层认知：你写的不是一段“模型调用代码”，而是一个“能让模型调用能力”的系统。从这一层开始，你的程序才从“聊天机器人”往“智能体”迈进。

2.3 第一段的局限

单次 Agent 有一个明显问题：它只执行一轮“判断-执行”。

如果任务是“帮我调研一下某领域的近期动态，然后写一份总结报告”，单次 Agent 根本做不完：它需要先搜索资料、再阅读、再总结、再校验。每一步的结果都是下一步的输入，必须多轮迭代才能完成。

这就是第二段 Loop 要解决的问题。

3. 第二段：Agent Loop 让“单次回答”进化为“多步推理”

3.1 从 ReAct 说起

如果你看过 Agent 相关的论文或框架文档，一定遇到过 ReAct 这个词。它的核心思想是：让模型在“推理（Reasoning）”和“行动（Acting）”之间交替进行。

具体来说，就是让模型每轮输出两种内容：

• Thought：当前这一步的思考，比如“我需要查询天气 API 来获取北京今天的天气”。
• Action：要调用的工具和传入参数，比如get_weather(city="北京")。

模型输出 Action 之后，程序执行工具，把结果作为 Observation（观察结果）返回给模型。模型看到结果后继续思考，再决定是继续调用工具，还是输出最终答案。

这个“思考 -> 行动 -> 观察 -> 再思考”的循环，就是 Agent Loop。

3.2 Agent Loop 的三个关键设计

Loop 看起来简单，真正写起来有三个容易出问题的点：

第一，最大步数限制。没有限制的循环是灾难。模型一旦陷入逻辑混乱，可能无限调用工具，既耗费 token 又卡死流程。生产环境里通常设置max_steps=5~10，超过步数就强制结束并告警。

第二，停止条件。循环什么时候结束？要么模型明确输出最终答案，要么达到最大步数，要么触发用户中断（即 human-in-loop 的一种形式）。

第三，工具结果回填。工具执行结果必须转换为模型能理解的消息格式，并放回上下文。否则模型看不到结果，下一步决策就是盲猜。

3.3 一个简化版 Agent Loop

下面代码演示一个最小可用的 Agent Loop。它不依赖某个具体框架，只用一个循环模拟“思考-行动-观察”的流程：

# 文件：agent_loop_demo.py from typing import List, Dict TOOLS = { "search": lambda query: f"关于'{query}'的模拟搜索结果", "calculate": lambda expr: str(eval(expr)), } MAX_STEPS = 5 def call_llm_with_loop(messages: List[Dict[str, str]]) -> str: """ 真实项目里这里会调用大模型 API。 本示例用规则模拟模型输出，只为展示循环结构。 """ last = messages[-1]["content"] # 假设模型收到用户任务后，先思考，再调用搜索工具 if "调研" in last and "ACTION" not in last: return "Thought: 我需要先搜索相关信息。\nACTION: search(Agent开发)" # 收到搜索结果后，模型决定计算一个指标 if "搜索结果" in last: return "Thought: 我看到部分信息，还需要估算文档数量。\nACTION: calculate(128*3)" return "Thought: 信息已经足够。\nANSWER: 已完成调研。" def parse_response(response: str) -> dict: if "ACTION:" in response: action_content = response.split("ACTION:", 1)[1].strip() tool_name = action_content.split("(", 1)[0].strip() tool_arg = action_content.split("(", 1)[1].rstrip(")") return {"type": "action", "tool": tool_name, "arg": tool_arg} if "ANSWER:" in response: return {"type": "answer", "content": response.split("ANSWER:", 1)[1].strip()} return {"type": "unknown"} def run_agent_loop(task: str) -> str: messages = [{"role": "user", "content": task}] for step in range(1, MAX_STEPS + 1): print(f"--- 第 {step} 轮 ---") response = call_llm_with_loop(messages) print(f"模型输出：{response}") parsed = parse_response(response) if parsed["type"] == "answer": return parsed["content"] if parsed["type"] == "action": tool = TOOLS[parsed["tool"]] observation = tool(parsed["arg"]) print(f"工具执行：{parsed['tool']}({parsed['arg']}) -> {observation}") messages.append({"role": "assistant", "content": response}) messages.append({"role": "tool", "content": observation}) else: raise RuntimeError(f"模型输出格式无法解析：{response}") raise TimeoutError(f"超过最大步数 {MAX_STEPS}，循环强制终止。") if __name__ == "__main__": result = run_agent_loop("帮我调研 Agent 开发并估算现状") print(f"\n最终结果：{result}")

这段代码把 Loop 的骨架完整呈现出来了。你在任何 Agent 框架里看到的AgentExecutor、AgentRunner、ReactAgent，底层本质都是这个循环，只是把“模型输出解析”“工具注册”“记忆管理”这些部分做成了更健壮的组件。

3.4 Loop 的局限

Loop 虽然解决了“多步迭代”问题，但它仍然是一条“默认直线”：模型循环执行，直到输出答案。如果流程里需要明确的分支判断，比如“搜索结果质量低就走人工流程，质量高就直接出报告”，Loop 就力不从心了。

再举几个实际场景：

• 某个环节需要人工审批，模型跑完一个分支后必须停下来等人确认；
• 两个子任务之间没有先后关系，可以并行执行；
• 一个主流程里嵌套多个不同的子 Agent，每个子 Agent 有自己的工具集；
• 线上出问题后，开发人员想知道“当时 Agent 为什么走了这一步”，Loop 的线性日志很难回答。

所有这些，都指向第三段：Graph。

4. 第三段：Graph 把“自由循环”变成“可控编排”

4.1 Graph 解决什么问题

Graph 的本质是：把 Agent 的执行流程建模成一张有向图。

图里有节点（Node）、边（Edge）和共享状态（State）。节点是具体的执行单元，比如“调用模型”“执行工具”“人工审批”；边定义了节点之间的流转关系，比如“判断通过后进入下一步”；状态则是整个流程共享的数据，相当于一条流水线上的公共传送带。

为什么要把 Loop 升级成 Graph？因为真实业务的流程从来不是一马平川的直线，它需要：

• 条件分支：根据某一步的结果决定走 A 路还是 B 路。
• 并行执行：多个独立节点同时执行，提高效率。
• 人工介入：在关键节点处暂停，等待人工确认后再继续（即 human-in-loop）。
• 细粒度控制：可以指定从任意节点重跑，而不是只能从头开始。
• 可观测性：每一步的状态变更都能被记录，方便排查问题。

4.2 用图的思想重新理解 Agent 编排

这里要区分一个概念：Graph 不只是“画流程图”，它更是一种状态管理机制。

一个简单的 Agent 流程，用 Loop 写是这样：

用户输入 -> [模型推理] -> [执行工具] -> (结果满意吗?) -> 是: 输出答案 -> 否: 回到模型推理

用 Graph 写，则会拆成更明确的节点和边。比如：

这些节点之间的流转不再靠“模型自由发挥”，而是由代码明确定义。这样做的最大好处是：关键路径可控，异常节点可重试，业务规则可沉淀。

LangGraph 这类框架的设计思路也是围绕这种“状态图”展开的。很多开发者在里面配 human-in-loop 时发现，本质上就是给某个节点配置一个“暂停并等待外部输入”的机制。

4.3 什么时候用 Loop，什么时候用 Graph

有同学会问：那我以后是不是都该用 Graph？

不是。这里的判断依据是流程复杂度。

记住一个原则：能用简单方案解决，就不要一开始上复杂编排。上来就写 Graph 的人，往往会先被自己的“流程设计”绕晕。

5. Agent、Loop、Graph 对比与选型判断

把三段放在一起看，会更加清晰：

这段对比也解释了为什么面试官喜欢问“Agent 和 Agent Loop 有什么区别”“Graph 编排解决了什么问题”。因为这三个概念确实构成了 Agent 开发的一条完整主干。理解这条主干，你再看任何 Agent 框架，都不会有“眼花缭乱”的感觉。

6. 从单次到 Loop 再到 Graph 的代码演进

只看概念不够，我们用一个具体场景演示三段递进：做一个技术文章审校小工具，判断一段技术文档是否存在术语错误，并给出建议。

6.1 第一版：单次 Agent

# 文件：review_agent_single.py def call_llm(prompt: str) -> str: """占位函数，实际项目中替换为具体模型调用。""" return "文档没有明显术语问题，可以发布。" def review_with_single_agent(doc: str) -> str: prompt = f""" 你是一名资深技术编辑。请审校下面的技术文档： {doc} 只返回审校结论。 """ return call_llm(prompt) if __name__ == "__main__": doc = "本文介绍 Agent Loop 与 Graph 的用法。" print(review_with_single_agent(doc))

这一版的问题：只要文档稍微复杂一点，比如术语检查需要调用外部术语库、字数统计需要调用工具，单次 Agent 就做不到了。

6.2 第二版：Agent Loop

# 文件：review_agent_loop.py from typing import List, Dict MAX_STEPS = 4 def call_llm(messages: List[Dict[str, str]]) -> str: """占位函数。真实场景中返回模型的文本输出。""" last_user = messages[-1]["content"] if "术语" in last_user and "ACTION:" not in last_user: return "Thought: 需要调用术语检查工具。\nACTION: check_terms" if "tool_result" in last_user: return "Thought: 检查完毕，没有致命问题。\nANSWER: 审校完成，术语可用。" return "Thought: 当前信息足够。\nANSWER: 审校完成。" def check_terms() -> str: # 模拟外部术语表检查 return "tool_result: 发现 1 个疑似术语问题，建议人工确认。" def execute_tool(action: str) -> str: if action.strip() == "check_terms": return check_terms() return "tool_result: 工具不存在。" def review_agent_loop(task: str) -> str: messages = [{"role": "user", "content": task}] for step in range(MAX_STEPS): response = call_llm(messages) if "ANSWER:" in response: return response.split("ANSWER:", 1)[1].strip() if "ACTION:" in response: action = response.split("ACTION:", 1)[1].strip() observation = execute_tool(action) messages.append({"role": "assistant", "content": response}) messages.append({"role": "tool", "content": observation}) return "达到最大步数，流程终止。" if __name__ == "__main__": task = "请审校文档中是否还有未处理的术语问题。" print(review_agent_loop(task))

这一版已经具备“模型自主判断是否需要调用工具”的能力。但流程里缺少一个关键角色：人工复核。文档上线前，任何术语问题都应该由人工最终确认，不能只靠模型判断。

6.3 第三版：Graph 编排（含人工复核节点）

下面用极简方式模拟一个 Graph 编排器。这里故意不引入任何第三方框架，而是手写一个最小状态图，让你看清节点、边、状态三个要素。

# 文件：review_agent_graph.py from typing import Dict, Callable # 全局状态：相当于 Graph 中的 State state = { "doc": "", "review_result": "", "tool_result": "", "human_approved": False, "final_output": "", } def node_review(context: dict) -> str: """节点1：模型审校""" context["review_result"] = "发现 1 个疑似术语问题。" return "need_tool" # 返回边的名称 def node_tool_check(context: dict) -> str: """节点2：工具检查""" context["tool_result"] = "术语库确认：建议将 'Agent Loop' 改为 'Agent 循环'。" return "need_human" def node_human_check(context: dict) -> str: """节点3：人工复核（human-in-loop）""" print(f"请人工确认以下建议：{context['tool_result']}") # 实际项目中这里会等待审批接口回调 context["human_approved"] = True return "approved" def node_finalize(context: dict) -> str: """节点4：生成最终结果""" if context["human_approved"]: context["final_output"] = "审校通过，已采纳人工确认结果。" return "end" # 节点注册表 NODES: Dict[str, Callable[[dict], str]] = { "review": node_review, "tool_check": node_tool_check, "human_check": node_human_check, "finalize": node_finalize, } # 边的路由表：当前节点 -> 返回值 -> 下一节点 ROUTES = { "review": {"need_tool": "tool_check"}, "tool_check": {"need_human": "human_check"}, "human_check": {"approved": "finalize"}, "finalize": {"end": None}, } def run_graph(start_node: str) -> str: current = start_node while current is not None: print(f"-> 执行节点：{current}") node_fn = NODES[current] next_edge = node_fn(state) next_node = ROUTES[current].get(next_edge) if next_node is None: break current = next_node return state["final_output"] if __name__ == "__main__": state["doc"] = "本文介绍 Agent Loop 与 Graph 的用法。" result = run_graph("review") print(f"\n最终输出：{result}")

这段代码虽然简单，但它把 Graph 编排的三个核心抽象都体现出来了：

• 节点：NODES字典中的每个函数。
• 边与路由：ROUTES定义了“从哪个节点出来，下一站去哪”。
• 共享状态：state字典在所有节点间传递和修改。

对比上一版 Loop，你会发现 Graph 的优点非常直观：

1. 每个人工复核节点可以被单独重跑，不需要重跑整个流程。
2. 如果某个节点失败，可以只看这个节点的输入输出定位问题。
3. 流程的路由规则是显式写在代码里的，不依赖模型自由发挥。

6.4 如何运行验证

三个代码文件都是独立的 Python 脚本，可以用下面的命令依次运行：

python review_agent_single.py python review_agent_loop.py python review_agent_graph.py

只要本机安装了 Python 3.8 以上版本，无需安装第三方库，直接运行即可。输出结果应当依次展示“单次审校结论”、“循环审校过程”和“图编排的执行路径”。

如果运行时出现中文乱码，检查终端编码是否为 UTF-8：

export PYTHONIOENCODING=utf-8

如果是在 Windows 上运行，可以在脚本开头加入：

# -*- coding: utf-8 -*- import sys sys.stdout.reconfigure(encoding='utf-8')

7. 常见误区与问题排查

7.1 常见认知误区

误区一：Agent 就是大模型 API。只看 API 文档永远学不会 Agent，因为 Agent 的关键在工具调用、循环控制、状态管理，这些都在模型之外。

误区二：Loop 越多越好。不是。模型每循环一轮，token 消耗和时间成本都会上升。很多任务的正确做法是先规划好最少需要的轮数。

误区三：Graph 一定比 Loop 高级。从能力上说是，但从工程成本上说不是。Graph 的建模、调试和维护成本更高。一个简单的单工具任务用 Graph，等于杀鸡用牛刀。

误区四：human-in-loop 就是让人在最后看一眼结果。真正的 human-in-loop 是在流程中间设置暂停点。比如“模型生成候选方案 -> 人工选择方向 -> 模型继续执行”，人工参与的是决策，而不是验收。

7.2 代码与运行问题排查

7.3 调试 Agent 流程的实用建议

调试 Agent 不像调试普通函数，不能只靠断点。建议从一开始就做好三件事：

• 打印完整消息链：每一轮发给模型的 messages 都要能输出到日志。
• 给每个节点加 trace_id：线上一次执行会产生很多日志，用统一 ID 把它们串起来。
• 保留工具输入输出快照：模型推理出错的根源往往是工具返回值不符合预期，快照能帮快速定位。

8. Agent 编排的工程化建议

从最小 Demo 走向生产环境，还需要补齐下面这些工程细节。

8.1 安全性

Agent 能调用工具，意味着模型一旦被诱导，可能执行危险操作。生产环境必须做到：

• 工具白名单机制，不在白名单里的工具不可调用。
• 高危操作（删除文件、修改数据库、发送消息）必须设置人工审批。
• 对工具传入参数做校验，不能直接透传模型输出。
• 对 Agent 的运行过程做审计日志，保留每一次工具调用记录。

8.2 可观测性

Agent 系统的调试比传统系统更难，因为模型的行为具有随机性。建议在项目初期就引入：

• 步骤级日志：每次模型推理、工具调用都记录耗时和 token 消耗。
• 状态快照：Graph 每个节点执行前后都保存一次状态。
• 指标监控：步数分布、工具失败率、人工审批通过率这几个指标最能反映流程健康度。

8.3 错误处理与重试

Agent 运行中的错误来源很多：模型 API 超时、工具调用失败、输出格式解析失败。工程上要分层处理：

• 临时性错误：网络抖动、限流，采用指数退避重试。
• 业务性错误：工具返回业务异常，让模型看到错误信息后自行调整方案重试一次。
• 结构性错误：多次重试仍然无法推进，应该走人工兜底流程，而不是无限循环。

8.4 版本管理与回滚

Agent 的流程是“代码 + 模型 + 工具”三者共同决定的。线上出了问题时，可能是代码改坏了，也可能是模型升级导致行为变化。建议：

• 流程定义（Graph 结构）纳入版本管理，每次修改能 diff。
• 模型版本和 Prompt 版本绑定，方便复现问题。
• 工具接口变更要先做兼容性测试，避免 Agent 侧出现运行时错误。

8.5 成本控制

Agent 的 token 成本往往比预想高很多。一个看似简单的任务，在 Loop 模式下可能调 5 次模型、消耗数千 token。成本控制可以从几个方向入手：

• 精简 Prompt，把不必要的历史消息裁剪掉。
• 在工具返回值较长时，先让模型做摘要，再放回上下文。
• 对“是否继续循环”的判定，设置明确的成本阈值，比如超过 3 次工具调用后自动开启人工确认。

9. 学习路线与最终建议

如果你刚接触 Agent 开发，建议按照本文的三段递进路径安排学习计划：

第一周：理解 Agent 基本单元。不用学框架，先自己写一个能调用两个工具的最小 Agent，体会“模型决策 + 工具执行”的感觉。

第二周：吃透 Agent Loop。至少手写一次 ReAct 循环，搞清楚消息链是如何增长的、停止条件如何设计、工具结果如何回填。这一步比刷一万行框架代码都重要。

第三周：接触 Graph 编排。把手写 Loop 改成简单 Graph，加入一个条件分支和一个人工审批节点。你会发现，Graph 带来的不是炫技，而是可控性。

第四周：回到真实项目。带着“三段地图”去选型。简单的工具类应用，用轻量框架就可以；复杂的自动化流程，再考虑 LangGraph 这类图编排框架。

最后给一个很实际的建议：不要一开始就追求“最强大的 Agent 框架”。先用最小代码跑通 Loop，再逐步加入节点、状态、人工介入。每一步都验证稳定后，再往后走。Agent 开发最大的坑，不是某个 API 不会用，而是流程不受控时，你还不知道问题出在哪一层。把 Agent、Loop、Graph 这张地图记在心里，遇到问题就能快速定位到底要调整“模型能力”“循环策略”还是“编排结构”，这才是 Agent 工程化真正的分水岭。