自主智能编程：一条通往生产落地的路线图

标题：代理编程：路线图

URL 来源：https://machinelearningmastery.com/agentic-programming-a-roadmap/

发布日期：2026-05-20T14:15:49+00:00

Markdown 内容： 在本文中，您将了解什么是代理编程，如何从零开始构建生产级 AI 代理，以及从零经验到将真实代理部署到生产环境所需的一切。

我们将涵盖以下主题：

• 代理系统背后的基础概念，包括代理循环、内存架构和工具设计。
• 2026 年可用的主要代理框架、它们的权衡以及每个框架最适合的用例。
• 一个具体的月度学习路线图，最终您将构建并部署一个可工作的生产代理。

代理编程：路线图

引言

这里有一个数字定义了当前的状况：79% 的企业表示他们已经采用了 AI 代理，但只有 11% 在生产环境中运行它们。这个 68 个百分点的差距不是需求问题。没有人缺乏雄心壮志。这是一个技能和架构问题。那些卡在这个差距中的组织资助了从未上线的试点项目和在真实条件下崩溃的演示——主要是因为他们把代理系统当作提示挑战来处理，而实际上它是一个软件工程挑战。

LangChain 对超过 1,300 名专业人士的 2026 年调查显示，57.3% 的人已经在生产环境中使用代理。在同一时期，Gartner 预测到 2027 年底，由于成本、价值不明确或治理薄弱，超过 40% 的代理 AI 项目将被取消。这两个数据点处于同一市场中。它们之间的差异主要是工程和架构问题——而这正是本路线图所解决的问题。

这是一条从零到具备生产能力的代理工程师的结构化路径。它涵盖了代理编程究竟是什么，您在编写第一个代理之前需要学习的内容，代理在底层是如何工作的，应该使用哪些框架及其原因，如何将代理部署到生产环境，以及您可以从第一天开始遵循的具体月度学习计划。

代理编程

代理编程是一种设计软件的学科，其中 AI 模型不仅仅是生成文本；它是系统内部的决策引擎，负责规划多步骤任务、使用外部工具、观察其行动的结果，并在没有逐步人工指导的情况下朝着目标前进。

最后一点是它与此前所有技术的区别所在。聊天机器人执行对话。代理执行工作流程。 一个产生响应。另一个产生结果——一份归档报告、一个已解决的支持工单、一个经过测试并提交的代码修复、一个已完成的研究简报。

无论框架或复杂性如何，每个代理系统都是由四个组件构建而成的：

1. 推理引擎 是 LLM——根据上下文、目标和它迄今为止积累的观察结果决定下一步该做什么的大脑。
2. 记忆 是代理维持状态的方式：当前任务中的短期上下文、从外部存储检索的长期知识，以及过去运行中哪些有效、哪些无效的事件记录。
3. 工具接口 是代理在现实世界中采取行动的方式——调用 API、读写文件、查询数据库、运行代码、浏览网页。
4. 目标管理 是将高层次目标分解为子任务的能力，跟踪对这些子任务的进展，并在某一步失败或产生意外结果时进行调整。

构建代理前需要学习的内容

大多数路线图会跳过这一部分或将其视为可选。这不是可选的。在没有这三个基础的前提下尝试构建生产级代理系统，会导致代理在演示中运行良好但在真实数据上却崩溃。

1. Python： 几乎所有代理框架、库和工具都是以 Python 为主构建的。您需要熟悉数据结构、函数、类、错误处理、异步/等待模式以及调用 API。如果您是初学者，请在继续前进之前花四到六周时间掌握基础知识。
2. LLM 基础知识： 您不需要训练模型或理解反向传播。但您需要足够理解 LLM 的工作机制，以便可靠地使用它们并在它们行为异常时进行调试。重要的概念包括：

• 分词（为什么长输入更昂贵且表现不同）
• 上下文窗口（为什么随着任务变长，代理性能会下降）
• 温度和采样（为什么输出会变化以及如何控制它）
• API 使用模式（如何构造调用、处理速率限制和解析响应）

1. 数学： 您不需要博士学位。您需要两个特定的知识点。向量和嵌入——因为它们驱动了您将构建的每一个记忆和检索系统。如果您不了解向量相似性搜索在做什么，就无法为您的代理设计记忆架构。还有基本的概率论，因为您需要对模型的不确定性、置信度以及为何同一个提示会产生不同的输出进行推理。

代理实际是如何工作的

代理循环

每个代理，无论围绕它的系统多么复杂，都运行在一个循环中。它接收一个目标。它推理下一步该做什么。它采取行动——几乎总是工具调用。它观察该行动的结果。它基于学到的内容再次推理。它继续直到目标达成或确定在没有输入的情况下无法继续。

这是 ReAct 模式（推理 + 行动）的最基本形式。以下是它在一个真实任务中的循环过程：

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24 目标：“研究排名前三的项目管理工具的价格和关键功能，并生成一份对比文档。”

第一轮迭代

思考：我需要了解这些顶级工具的最新价格。先做一个广泛的搜索来确认哪三个最相关。

行动：web_search("top project management tools 2026 market share")

观察：多个来源显示 Asana、Monday.com 和 Notion 是排名前三的工具。

第二轮迭代

思考：我已经知道了这些工具。现在分别研究每个工具的价格。

行动：web_search("Asana pricing plans 2026")

观察：Asana：免费版、入门版（$10.99/用户/月）、高级版（$24.99/用户/月）

第三和第四轮迭代

[与 Monday.com 和 Notion 的处理方式相同]

第五轮迭代

思考：我已经收集了所有所需数据，该生成文档了。

行动：write_file("comparison.md", [结构化对比内容])

观察：文件已成功写入。

最终输出：comparison.md 已保存到工作目录。

每次迭代中，代理都会执行特定操作，获得实际结果，并更新其推理逻辑。它不会从目标一步跳到输出。这种基于事实、逐步迭代的行为正是代理与花哨聊天机器人之间的区别所在。

记忆架构

没有记忆的代理是无状态的——它无法从当前任务中学习，无法参考本次会话之前的知识，也无法通过以往运行来改进。生产级代理同时使用三种类型的记忆。

1. 短期记忆 是实时上下文窗口——即代理对当前任务的所有认知：目标、迄今为止累积的工具结果以及推理步骤。它快速且始终可用，但容量有限。随着任务的进行和更多工具结果堆积，上下文会逐渐填满，性能可能会下降。
2. 长期记忆 存在于上下文窗口之外的一个向量数据库中，是代理在任务过程中查询的知识库。当客服代理需要某个具体政策、之前的案例或产品细节时，它会查询其向量存储并只检索相关的片段，而不是一次性加载全部内容。像 Pinecone、Weaviate 和 Chroma 这样的工具负责处理这一层。
3. 情节记忆 是过去运行记录：代理采取了哪些行动、哪些有效、哪些失败，以及下次应该怎样调整。大多数初学者会跳过这一层。大多数生产团队在意识到他们的代理在不同会话中重复犯同样错误后，最终会加入这一层。

工具设计

工具是代理的“双手”。它在现实世界中所做的一切动作——每一次搜索、每一个文件操作、每一次 API 调用——都是一次工具调用。你的工具设计质量直接影响代理的可靠性。根据 Anthropic 工程团队的说法，臃肿或模糊的工具集是生产级代理最常见的失败模式之一。测试很简单：如果你不能迅速而明确地识别出哪个工具适用于特定情况，那么你的代理也无法做到这一点。

以下是实践中的示例：

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35# 弱——过于模糊，没有边界

tools=[

{

"name":"search",

"description":"在线搜索信息"

}

]

强——一个任务、明确的使用场景、包含边界条件

tools=[

{

"name":"web_search",

"description":(

"在公共网络上搜索关于某主题的最新信息。 "

"当你需要近期变化的事实、新闻或数据，或者这些信息不在你的训练知识范围内时使用。 "

"不要用于任务上下文中已经提供的文档。"

),

"input_schema":{

"type":"object",

"properties":{

"query":{

"type":"string",

"description":"具体的搜索查询，3-8个词。要精准。"

},

"max_results":{

"type":"integer",

"description":"返回的结果数量。默认值为5，最大值为10。",

"default":5

}

},

"required":["query"]

}

}

]

边界条件“不要用于任务上下文中已有的文档”防止代理搜索它已经拥有的信息，从而浪费 token 和 API 调用。这种明确的范围界定是区分生产环境中可靠运行的工具和仅在演示中可靠的工具的关键。

实际构建什么？（框架选择）

框架市场已基本集中于少数几个强势玩家，每个都有适合特定用例的独特架构。截至 2026 年初，LangGraph 和 CrewAI 成为了两大主导框架。

LangGraph（LangChain）

LangGraph 是那些需要精确控制代理状态、条件分支和持久运行工作流的团队的生产级选择。它将代理建模为有向图，其中节点代表动作或推理步骤，边代表它们之间的转换，这些转换可以是条件性的。代理可以回环、根据运行时结果走不同路径，或暂停等待人工批准后再继续。

LangGraph 在 2025 年 10 月发布了 v1.0 正式版，在更广泛的 LangChain 生态系统中拥有超过 97,000 颗 GitHub 星标。如果代理在工作流程中途崩溃，LangGraph 可以从最后一个检查点恢复——这对耗时数小时甚至数天的任务至关重要。LangSmith 提供开箱即用的追踪、成本跟踪和评估管道。

最适合： 具有复杂条件逻辑、长时间运行的工作流、合规性要求以及每一步完整审计能力的生产系统。以下是一个简单的实现：

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25 from langgraph.graph import StateGraph

from typing import TypedDict

定义代理在各步骤间传递的状态

class ResearchState(TypedDict):

goal:str# 原始任务

findings:list# 累积的研究结果

final_report:str# 最终输出

构建图：每个节点代表一个动作或推理步骤

workflow=StateGraph(state_schema=ResearchState)

workflow.add_node("plan",plan_research)# 将目标分解为搜索查询

workflow.add_node("search",execute_searches)# 执行搜索

workflow.add_node("write",write_report)# 整合成文档

定义节点之间的显式转换

workflow.set_entry_point("plan")

workflow.add_edge("plan","search")

workflow.add_edge("search","write")

编译并运行

agent=workflow.compile()

result=agent.invoke({"goal":"比较前三大CRM工具的价格"})

print(result["final_report"])

CrewAI

CrewAI 将代理组织成团队——一个由专业人员组成的团队，每位成员都有角色、目标和工具。一个代理负责研究，另一个负责撰写，第三个负责审核。CrewAI 处理交接工作。在过去12个月中，它已经支持了约20亿次代理工作流执行，并被近40%的财富500强公司使用。对于适合“专业团队”模式的工作流，与 LangGraph 相比，您可以少写40–60%的代码，并显著更快地进入生产环境。

最适合： 多代理系统、基于角色的自动化流水线，以及没有专门机器学习工程师但需要快速推进的团队。以下是一个简单的实现：

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40 from crewai import Agent,Task,Crew

每个代理都有角色、目标和背景故事来塑造其行为

researcher=Agent(

role="高级研究员",

goal="查找指定主题的准确、最新的信息",

backstory=(

"你是一个严谨的研究者，总是引用来源并标记过时的信息。你从不猜测。"

),

tools=[web_search_tool],

verbose=True

)

writer=Agent(

role="内容策略师",

goal="根据研究成果生成清晰、结构化的文档",

backstory=(

"你将原始研究转化为精炼的文档。你从不在研究中添加未包含的信息。"

),

verbose=True

)

任务定义每个代理必须交付的内容

research_task=Task(

description="研究Salesforce、HubSpot和Zoho CRM的当前定价及主要功能。",

expected_output="每个CRM的结构化定价和功能，附带来源网址。",

agent=researcher

)

writing_task=Task(

description="基于研究结果，为非技术人员撰写一份对比报告。",

expected_output="400字的对比文档，顶部包含摘要表格。",

agent=writer

)

crew=Crew(agents=[researcher,writer],tasks=[research_task,writing_task],verbose=True)

result=crew.kickoff()

print(result)

Anthropic Claude API（直接调用）

对于专门构建于 Claude 的团队，Anthropic 的直接 API 结合工具使用，提供了最大控制力且抽象开销最小。没有框架偏好、版本冲突或隐藏行为——只有模型和您的架构。API 原生支持工具使用、计算机操作、流式传输和 Model Context Protocol (MCP)，用于跨代理标准化工具发现。使用 Claude Sonnet 进行代理循环和执行步骤，而将 Opus 预留给高风险规划或需要最大推理深度的任务。

最适合： 专门为 Claude 构建的生产代理、希望零框架开销的团队，以及需要计算机操作或 MCP 集成的用例。

Microsoft Agent Framework

微软在2026年初将 AutoGen 和 Semantic Kernel 合并为统一的 Agent Framework。AutoGen 现已进入维护模式——仅修复错误，不再添加新功能。如果您今天开始一个基于 AutoGen 的新项目，您实际上是在构建微软自身正在放弃的框架。新的 Agent Framework 继承了 AutoGen 在多代理对话模式中的优势，并与 Azure、Copilot Studio 和微软生态系统紧密集成。

最适合： 微软栈企业、多代理对话和谈判模式，以及需要原生 Azure 集成的团队。

构建您的第一个代理

这是一个最小但真正有用的调研代理。它接收一个目标，使用 ReAct 循环在网页上搜索，并将结构化报告写入文件。该模式可直接应用于实际工作场景。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

108

109

110

111

112

113# 安装：pip install anthropic

设置环境变量：ANTHROPIC_API_KEY

import anthropic

client=anthropic.Anthropic()

定义代理可以使用的工具

tools=[

{

"name":"web_search",

"description":(

"在互联网上搜索最新信息。 "

"适用于可能最近发生变化的事实或数据。 "

"不要用于对话中已有的信息。"

),

"input_schema":{

"type":"object",

{
  "name": "web_search",
  "description": "Perform a web search using a specified query.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "特定搜索查询，3-8个单词。"
      }
    },
    "required": ["query"]
  }
}

{
  "name": "write_file",
  "description": "将文本写入本地文件。当任务完成且输出就绪时使用。",
  "input_schema": {
    "type": "object",
    "properties": {
      "filename": {
        "type": "string",
        "description": "输出文件名，例如 'report.md'"
      },
      "content": {
        "type": "string",
        "description": "要写入的完整内容。"
      }
    },
    "required": ["filename", "content"]
  }
}

def web_search(query:str)->str:

连接真实的API：Tavily（tavily.com）专为代理设计

替换为：return tavily_client.search(query=query)

return f"[搜索结果 '{query}'：在此插入 Tavily 或 Brave Search API]"

def write_file(filename:str,content:str)->str: with open(filename,"w")as f: f.write(content) return f"文件 '{filename}' 写入成功（{len(content)} 个字符）。"

def execute_tool(name:str,inputs:dict)->str: if name=="web_search": return web_search(inputs["query"]) elif name=="write_file": return write_file(inputs["filename"],inputs["content"]) return f"未知工具：{name}"

def run_agent(goal:str,max_iterations:int=10)->str: system="""你是一个研究代理。给定一个研究目标时：

1. 使用 web_search 查找最新、准确的信息

1. 多次搜索以涵盖主题的不同方面

1. 当你拥有足够信息时，使用 write_file 保存结构化报告

1. 报告需要：执行摘要、关键发现和来源

在行动前仔细思考每一步。当文件写入完成后，你就完成了任务。"""

对话历史随着每次工具调用和结果增长

messages=[{"role":"user","content":goal}]

for i in range(max_iterations): print(f"\n--- 第 {i + 1} 轮 ---") response=client.messages.create( model="claude-sonnet-4-20250514",# Sonnet 适用于循环，速度快且成本效益高 max_tokens=4096, system=system, tools=tools, messages=messages )

print(f"停止原因：{response.stop_reason}")

模型已完成——返回最终消息

if response.stop_reason=="end_turn": return next( (b.text for b in response.content if hasattr(b,"text")), "任务完成。" )

模型想要调用工具——执行并反馈结果

if response.stop_reason=="tool_use": messages.append({"role":"assistant","content":response.content}) tool_results=[]

for block in response.content: if block.type=="tool_use": print(f"调用：{block.name}({block.input})") result=execute_tool(block.name,block.input) print(f"结果：{result[:80]}...")

tool_use_id 将此结果链接到产生它的具体调用

tool_results.append({ "type":"tool_result", "tool_use_id":block.id, "content":result })

添加结果以便模型可以推理它所学到的内容

messages.append({"role":"user","content":tool_results})

return"达到最大迭代次数。"

if __name__ =="__main__": goal="研究2026年AI领域排名前三的向量数据库并撰写比较报告。" print(f"目标：{goal}\n") run_agent(goal)

这段代码的作用： 对话历史是代理的工作记忆；它会随着每次工具调用和结果的增长而扩展，为模型提供关于其在任务过程中已完成和学习的所有内容的完整上下文。tool_use_id 字段由 Anthropic API 所需；它将每个结果链接回产生它的具体工具调用，因此模型知道哪个观察对应于哪个操作。在生产环境中，用 Tavily 替换 web_search 占位符——它专为代理用例设计，并有一个免费层，适合开发使用。

多代理系统

单个运行 ReAct 循环的代理能够很好地处理大多数任务。但有些任务打破了单代理模式：并行工作流如果顺序执行会太慢，质量检查需要真正独立的评审者，或者领域专业化深度到一个通用代理在整个范围内表现平庸。

主流模式是协调者-工作者。一个协调者代理接收目标，将其分解为子任务，将每个任务委派给专门的工作者，并综合结果。每个工作者只知道完成其工作的必要信息——而不是更广泛任务的全部上下文。这是有意为之。最小共享上下文使每个代理的注意力集中，减少跨任务污染，并使故障更容易隔离和调试。

内容生产流水线是一个清晰的例子：研究员负责资料搜集和事实核查，作家负责起草，评审员在发布前根据原始简报评估草稿。协调者负责协调交接并拥有最终输出。

这种架构比大多数教程所承认的更重要。80% 的组织报告称其部署的代理至少有一次越界行为。具有明确交接规范和显式范围约束的多代理设计是控制这种情况最有效的方法之一。当每个代理都有一个任务以及定义好的输入和输出时，超出范围的行为比一个代理负责一切时更容易捕捉。

1. **可观察性是不可妥协的。** [89% 的生产环境中的代理构建者已经实施了可观察性工具](https://blog.mean.ceo/ai-agent-startup-statistics/) — 追踪每一次工具调用、每一步推理、每一个失败以及每一笔成本。值得关注的工具包括：用于基于 LangGraph 的系统的 [LangSmith](https://www.langchain.com/langsmith)，用于无框架追踪的 [AgentOps](https://www.agentops.ai/)，以及用于 API 级监控的 [Helicone](https://www.helicone.ai/)。没有可观察性，调试生产环境中的代理故障就是猜谜游戏。有了它，你可以精确地追踪到哪一步出了问题以及为什么出错。

2. **代理的失败方式与普通软件不同。** 一个标准应用程序会因异常而崩溃。而代理则会出现“漂移”现象 —— 它执行了一些在权限范围内技术上可行但你从未预期的操作，生成了一个看似合理但错误的结果，或者以一种消耗资源却无进展的方式陷入循环。这些故障更难捕捉，因为它们并不总是看起来像失败。提前设计应对策略：设置严格的迭代限制，定义代理可以验证的明确成功标准，并建立约束机制来限制代理的行为。

3. **成本增长迅速。** 多步骤代理在调用工具时消耗的 token 数量远高于单轮推理。一个在撰写报告前运行六次搜索的科研代理，可能仅一个看似简单的任务就轻易达到 **15,000+ token**。如果将这个数字乘以用户数和会话数，你将面临一个令人惊讶的成本结构。在扩展之前，先设定每个任务的基础成本，设置硬性迭代限制，并将每个任务的成本作为与质量同等重要的指标进行跟踪。

4. **人机协作是良好的架构设计，而非备选方案。** 对于高风险决策 —— 涉及客户数据、金融交易或外部通信的任何操作 —— 在代理继续执行前，由人工审查并批准的显式检查点才是该风险等级下的正确设计。[最优秀的生产级代理系统将人类监督视为一种设计特性](https://www.promptingguide.ai/agents/introduction)，而不是等待模型变好之前的临时权宜之计。

## 你的学习路径（按月）

这是一条具体且有时间限制的学习路径。每个阶段都直接建立在前一阶段之上。到第六个月结束时，你将至少构建并部署一个真实的生产级代理。

1. **第 1 和第 2 个月：** 如果你不熟悉 Python，请从基础开始：数据结构、函数、类、错误处理和 HTTP API 调用。然后进入大语言模型（LLM）基础知识：从 [Anthropic](https://console.anthropic.com/) 获取 API 密钥，阅读文档，并构建简单的单轮应用 —— 例如摘要器、分类器或结构化数据提取器。到第二个月末，使用本文中介绍的直接 API 模式构建你的第一个工具调用代理。它不需要很惊艳，但必须能正常工作，并且你需要理解其中的每一行代码。

2. **第 3 和第 4 个月：** 深入研究使代理可靠的系统。学习向量数据库的工作原理，并使用 [Chroma](https://www.trychroma.com/) 或 [Pinecone](https://www.pinecone.io/) 为其中一个代理实现长期记忆功能。构建一个多步骤的研究代理，能够完整运行 ReAct 循环，优雅地处理工具失败，并输出真实文件。然后将其部署到实际运行的地方 —— 一个定时任务、一个简单的 API 端点，而不是仅仅本地脚本。部署让生产环境的约束变得真实，这是本地开发无法提供的体验。选择一个框架深入学习：[LangGraph](https://github.com/langchain-ai/langgraph) 提供最大控制力和可观察性，[CrewAI](https://github.com/crewAIInc/crewAI) 则适合在多代理任务中快速部署。

3. **第 5 和第 6 个月：** 使用编排器-工作者模式构建一个多代理系统。两个或三个由编排器协调的专业代理，共同完成一个你真正关心的任务。加入可观察性：为每个代理步骤添加追踪能力，以便你能追溯失败原因。加入成本追踪：测量每个任务的实际成本。然后将其上线 —— 让它在真实数据上为真实用户运行，哪怕是一个小范围的内部用户群体。来自实际生产环境的反馈比任何教程都更有价值。到第六个月末，你将拥有一个可用的生产级代理，清晰了解代理为何以及如何失败，并具备构建越来越复杂系统的坚实基础。

## 结论

在代理编程中的机遇是真实存在的，时机也已成熟。[只有 17% 的组织已部署 AI 代理，但超过 60% 的组织预计在未来两年内会这样做](https://www.gartner.com/en/articles/hype-cycle-for-agentic-ai) —— 这是 Gartner 在其 2026 年调查中测得的所有新兴技术中最为激进的采用曲线。那些能够可靠地构建这些系统、正确地为生产环境进行仪器化，并设计出防止代理偏离预期边界架构的工程师极为稀缺。这种稀缺性正是一个真正的机遇。

本文中的路线图是一条通往成为这类工程师的直接路径。这些基础可以在几周内掌握，而不是几年。第一个可用的代理离你并不遥远。区分那些构建生产级代理的人与那些困在演示循环中的人的唯一因素几乎总是：他们上线了某个东西。从本文中的代码开始。修改它、破坏它、修复它。让一个代理在真实任务上运行起来。那个第一次会话 —— 观察循环执行、看到工具调用触发、看着完成的文件出现在你的目录中 —— 就是让一切变得清晰的关键时刻。