# Agent 开发学习计划：从入门到独立完成项目

建议采用 **8 周、每周 8～12 小时** 的学习周期。核心路线是：

> **大模型 API → Prompt 与结构化输出 → 工具调用 → Agent 循环 → 记忆与知识库 → 工作流编排 → 评估与安全 → 完整项目**

第一阶段不要同时学习多个框架。建议先使用 **Python + OpenAI Agents SDK** 理解 Agent 的基本机制，再学习 LangGraph 处理复杂、可恢复的工作流。OpenAI Agents SDK 的核心抽象相对少，主要包括 Agent、工具、handoff、guardrails、sessions 和 tracing，比较适合作为入门框架。([OpenAI][1])

---

## 一、你最终要达到的能力

完成学习后，你应该能够独立完成下面这些工作：

1. 调用大模型 API，并正确管理配置、异常和费用。
2. 为模型设计清晰的系统提示词。
3. 让模型输出符合 Pydantic 定义的结构化数据。
4. 把 Python 函数、数据库和第三方 API 封装成工具。
5. 实现“思考—调用工具—观察结果—继续执行”的 Agent 循环。
6. 管理多轮对话、短期记忆和长期记忆。
7. 构建基于文档的 RAG Agent。
8. 使用工作流控制 Agent，而不是完全依赖模型自由决策。
9. 编写测试集，评估 Agent 的正确率、成本和延迟。
10. 将 Agent 封装为 API 或 Web 应用并部署。

---

# 二、8 周学习安排

## 第 1 周：理解大模型应用，而不是急着写 Agent

### 理论目标

理解以下概念：

* LLM 是如何根据上下文生成结果的
* system、user、assistant 消息的区别
* Token、上下文窗口、温度、输出长度
* Prompt、结构化输出和普通文本输出
* 幻觉为什么会发生
* API 调用与网页版聊天的区别
* 同步、异步和流式输出

最重要的是建立一个认识：

> Agent 不是一个全新的模型，而是“大模型 + 指令 + 工具 + 状态 + 控制循环”。

### 实践任务

完成三个小程序：

1. 命令行聊天机器人
2. 文本总结器
3. 信息提取器

信息提取器要求输出固定的数据结构，例如：

```python
from pydantic import BaseModel

class TaskInfo(BaseModel):
    title: str
    priority: str
    deadline: str | None
```

输入：

```text
我需要在周五之前完成 Agent 项目的数据库设计，这件事很重要。
```

输出：

```json
{
  "title": "完成 Agent 项目的数据库设计",
  "priority": "high",
  "deadline": "周五"
}
```

### 本周验收标准

你能够：

* 独立调用一次模型 API
* 从环境变量读取 API Key
* 捕获请求异常
* 获得稳定的 JSON 或 Pydantic 对象
* 解释什么是 Token 和上下文

### 项目结构

```text
week1_llm_basics/
├── app.py
├── config.py
├── schemas.py
├── prompts.py
├── requirements.txt
└── .env.example
```

不要把 API Key 直接写进代码。

---

## 第 2 周：工具调用与最小 Agent

这是 Agent 开发最关键的一周。

### 理论目标

理解：

* 什么是 Tool Calling，也叫 Function Calling
* 工具名称、描述、参数 Schema 的作用
* 模型只是“决定调用哪个工具”，真正执行工具的是你的程序
* 工具调用结果为什么要重新交给模型
* Agent Loop 的基本结构
* 最大循环次数和停止条件
* 工具报错如何反馈给模型

工具调用的基本流程是：

```text
用户提出任务
    ↓
模型判断是否需要工具
    ↓
模型生成工具名称和参数
    ↓
Python 执行工具
    ↓
把工具结果交回模型
    ↓
模型继续调用工具或生成最终答案
```

### 实践任务

先手写三个工具：

```python
def calculate(expression: str) -> str:
    ...

def get_current_time(timezone: str) -> str:
    ...

def search_local_notes(keyword: str) -> list[str]:
    ...
```

然后完成一个“个人效率 Agent”，支持：

* 数学计算
* 查询本地笔记
* 获取时间
* 自动判断是否需要使用工具
* 最多执行 5 轮
* 工具异常时不崩溃

OpenAI Agents SDK 可以将 Python 函数封装为工具，并自动生成参数 Schema、进行 Pydantic 验证，适合用来理解工具调用。([OpenAI][2])

### 建议做两遍

第一遍：自己手写 Agent Loop。

伪代码：

```python
messages = [system_message, user_message]

for step in range(MAX_STEPS):
    response = call_model(messages, tools=tools)

    if response_has_tool_call(response):
        tool_result = execute_tool(response.tool_call)
        messages.append(response.output)
        messages.append(tool_result)
    else:
        return response.final_text

raise RuntimeError("Agent exceeded maximum steps")
```

第二遍：使用 Agents SDK 重写。

```python
from agents import Agent, Runner, function_tool

@function_tool
def calculate(expression: str) -> str:
    """计算一个数学表达式。"""
    return str(eval(expression, {"__builtins__": {}}))

agent = Agent(
    name="Productivity Assistant",
    instructions="帮助用户完成任务，必要时使用可用工具。",
    tools=[calculate],
)

result = Runner.run_sync(agent, "计算 125 * 48")
print(result.final_output)
```

实际项目中不要直接使用未经限制的 `eval`，这里仅用于理解最小示例。

### 本周验收标准

你能够解释：

* 模型是否真的执行了 Python 函数
* 工具描述为什么影响调用准确率
* 为什么需要最大执行轮数
* 工具返回值应该是文本、字典还是对象
* 什么情况下不应该调用工具

---

## 第 3 周：Prompt、上下文和对话记忆

### 理论目标

学习 Prompt 的基本结构：

```text
角色
目标
输入说明
可用工具
执行规则
输出格式
边界条件
失败处理方式
示例
```

理解两种“记忆”：

### 短期记忆

当前对话中的消息历史。

问题：

* 对话越长，Token 成本越高
* 历史内容可能包含无关信息
* 旧指令可能干扰新任务

常用处理：

* 保留最近 N 轮
* 对旧对话进行摘要
* 只保留与当前任务相关的信息

### 长期记忆

保存到数据库中的用户偏好、历史事实和任务记录。

例如：

```json
{
  "user_id": "u001",
  "preferred_language": "Chinese",
  "coding_level": "Python beginner",
  "current_goal": "Build an independent agent project"
}
```

### 实践任务

开发一个“学习教练 Agent”：

* 用户可以设定学习目标
* Agent 能记录用户的学习进度
* 下次对话能够读取之前的进度
* 长对话自动生成摘要
* 用户可以纠正或删除记忆

推荐先使用 SQLite：

```text
users
conversations
messages
memories
learning_tasks
```

### 必须理解的原则

不要把所有聊天内容都写入长期记忆。

只保存：

* 稳定偏好
* 明确目标
* 用户主动要求保存的信息
* 后续任务确实需要的信息

敏感信息、临时内容和未经确认的推断不应直接成为长期记忆。

Agents SDK 支持会话状态管理；`Agent` 与 `Runner` 也可以代替开发者处理轮次、工具、handoff 和 session 等编排工作。([OpenAI][3])

---

## 第 4 周：RAG 与知识库 Agent

### 理论目标

理解 RAG 的完整流程：

```text
文档
 ↓
解析和清洗
 ↓
切分 Chunk
 ↓
生成 Embedding
 ↓
存入向量数据库
 ↓
用户提问
 ↓
检索相关 Chunk
 ↓
将检索结果交给模型
 ↓
生成带来源的回答
```

需要掌握：

* Chunk 大小与重叠
* Embedding
* 相似度检索
* Top-K
* 元数据过滤
* 关键词检索和向量检索
* 混合检索
* 引用来源
* 无答案时拒绝猜测

### 实践任务

开发“Python 学习资料问答 Agent”：

1. 准备若干 Markdown、TXT 或 PDF 学习资料。
2. 对文档进行切分。
3. 建立向量索引。
4. 用户提问时检索相关片段。
5. Agent 必须给出来源。
6. 资料中没有答案时明确说明没有找到。
7. 增加一个普通计算工具。

这样你会得到一个同时具备：

* 知识检索
* 工具调用
* 对话能力

的基础 Agent。

### 验收测试

至少准备 20 个问题：

* 10 个资料中明确有答案的问题
* 5 个需要综合两个片段的问题
* 5 个资料中没有答案的问题

记录：

```text
问题
期望答案
检索到的文档
最终回答
是否正确
是否出现无依据内容
```

---

## 第 5 周：工作流、状态机与 LangGraph

完成前四周之后，再开始学习 LangGraph。

LangGraph 是一个偏底层的 Agent 编排和运行框架，重点在持久化执行、状态管理、人机协作以及复杂工作流控制；其官方文档也建议先熟悉模型和工具，再学习 LangGraph。([Docs by LangChain][4])

### 理论目标

分清两个概念：

### Workflow

执行路径主要由程序决定。

```text
接收需求
→ 分类
→ 检索资料
→ 生成答案
→ 审核答案
→ 返回结果
```

### Agent

由模型动态决定下一步。

```text
接收目标
→ 模型选择工具
→ 根据结果决定下一步
→ 直到完成
```

LangGraph 官方文档也将 workflow 描述为预定义代码路径，而 agent 会动态决定过程和工具使用。([Docs by LangChain][5])

### 实践任务

使用 LangGraph 重构第 4 周的项目：

```text
START
  ↓
问题分类
  ├── 普通知识问题 → 直接回答
  ├── 资料问题 → RAG 检索
  ├── 计算问题 → 计算工具
  └── 高风险问题 → 人工确认
  ↓
答案检查
  ├── 合格 → 输出
  └── 不合格 → 重新生成
  ↓
END
```

建议定义清晰的状态：

```python
from typing import TypedDict

class AgentState(TypedDict):
    user_query: str
    query_type: str
    retrieved_documents: list[str]
    draft_answer: str
    review_result: str
    retry_count: int
    final_answer: str
```

LangGraph 的核心思路是用图表达 Agent 流程，节点通常是 Python 函数，边表示节点之间的流转关系。([Docs by LangChain][6])

### 本周验收标准

你能够判断：

* 哪些节点应该由代码控制
* 哪些决策可以交给模型
* 什么状态需要持久化
* 失败后应该从哪个节点恢复
* 如何防止流程无限循环

---

## 第 6 周：多 Agent 与 MCP

### 多 Agent

不要因为名字听起来高级，就把所有系统都做成多 Agent。

单 Agent 能完成时，优先使用单 Agent。

只有下面这些情况才考虑多 Agent：

* 不同任务需要完全不同的提示词
* 不同角色拥有不同的工具权限
* 上下文过大，需要拆分
* 各任务可以并行处理
* 需要独立审核角色
* 不同任务需要不同模型

Agents SDK 支持两类常见方式：

* **Agents as tools**：主 Agent 把其他 Agent 当作工具调用。
* **Handoff**：当前 Agent 将任务交给另一个 Agent继续处理。([OpenAI][1])

### 实践任务

构建一个“研究报告 Agent”：

```text
Coordinator Agent
├── Research Agent：收集和整理资料
├── Analyst Agent：分析和归纳
└── Reviewer Agent：检查证据和逻辑
```

工作流程：

```text
用户给出研究主题
→ Coordinator 拆分任务
→ Researcher 返回资料
→ Analyst 形成初稿
→ Reviewer 检查
→ 不合格则返回修改
→ Coordinator 输出最终报告
```

### MCP

本周只需要理解并做一个简单练习。

MCP 是连接 AI 应用与外部系统的开放标准，可用于暴露工具、资源和提示模板。([Model Context Protocol][7])

你需要理解：

```text
MCP Host
MCP Client
MCP Server
Tools
Resources
Prompts
Transport
```

实践：

* 写一个本地 MCP Server
* 暴露两个工具：

  * 查询学习任务
  * 新增学习任务
* 让 Agent 通过 MCP 调用它们

不要一开始研究复杂的远程部署、认证和大量 MCP Server 集成。

---

## 第 7 周：测试、评估、安全与可观测性

一个能运行的 Agent，不代表是一个可靠的 Agent。

### 理论目标

建立四类指标。

### 1. 任务效果

* 最终答案是否正确
* 是否完成用户目标
* 是否遗漏步骤
* 是否使用了正确工具

### 2. 工具行为

* 工具选择准确率
* 参数是否正确
* 是否进行了不必要调用
* 工具出错后是否正确恢复

### 3. 系统指标

* 响应时间
* 模型调用次数
* Token 消耗
* 单次任务成本
* 错误率

Agents SDK 可以追踪每次运行的请求数、输入 Token、输出 Token和总 Token，可用于成本监控和限制。([OpenAI][8])

### 4. 安全指标

* Prompt Injection 防护
* 越权工具调用
* 敏感数据泄露
* 危险操作确认
* 输出格式校验
* 无限循环
* 超预算执行

### 实践任务

为前面的项目建立测试集：

```python
TEST_CASES = [
    {
        "input": "计算 38 * 27",
        "expected_tool": "calculate",
        "expected_contains": "1026",
    },
    {
        "input": "根据资料解释 Python 装饰器",
        "expected_tool": "search_documents",
        "must_have_citation": True,
    },
]
```

至少完成：

* 30 个固定测试案例
* 5 个工具异常案例
* 5 个 Prompt Injection 案例
* 5 个长对话案例
* 5 个资料中不存在答案的案例

### 必须加入的保护机制

```text
最大 Agent 步数
单次任务 Token 上限
工具超时
参数验证
工具白名单
危险操作人工确认
外部内容不可信标记
输出 Schema 验证
日志脱敏
```

SDK 内置 tracing，可用于查看和调试 Agent 的运行过程。([OpenAI][1])

---

## 第 8 周：完成一个可展示的完整 Agent

推荐你的第一个完整项目做成：

# 智能学习助理 Agent

它与你现在的实际需求一致，也能覆盖 Agent 开发的大多数核心能力。

### 核心功能

1. 用户设定学习目标。
2. Agent 将目标拆解成学习计划。
3. 查询用户当前的学习进度。
4. 根据学习资料回答问题。
5. 自动生成练习题。
6. 批改用户答案。
7. 保存学习记录。
8. 每周生成学习总结。
9. 必要时调用计算、检索和任务管理工具。
10. 对重要数据修改要求用户确认。

### 推荐技术栈

```text
Python 3.11+
FastAPI
Pydantic
OpenAI Agents SDK
LangGraph
SQLite，后续可替换为 PostgreSQL
向量数据库：先选择一个轻量方案
Streamlit 或简单前端
pytest
Docker
```

### 推荐目录结构

```text
learning_agent/
├── app/
│   ├── main.py
│   ├── api/
│   │   ├── chat.py
│   │   └── tasks.py
│   ├── agents/
│   │   ├── learning_agent.py
│   │   ├── reviewer_agent.py
│   │   └── prompts.py
│   ├── workflows/
│   │   ├── learning_graph.py
│   │   └── state.py
│   ├── tools/
│   │   ├── calculator.py
│   │   ├── knowledge_search.py
│   │   ├── task_manager.py
│   │   └── progress_tracker.py
│   ├── memory/
│   │   ├── short_term.py
│   │   └── long_term.py
│   ├── retrieval/
│   │   ├── ingestion.py
│   │   ├── chunking.py
│   │   └── retriever.py
│   ├── database/
│   │   ├── models.py
│   │   └── repository.py
│   ├── schemas/
│   │   ├── chat.py
│   │   └── tasks.py
│   ├── evaluation/
│   │   ├── datasets.py
│   │   ├── graders.py
│   │   └── runner.py
│   └── core/
│       ├── config.py
│       ├── logging.py
│       └── exceptions.py
├── tests/
├── data/
├── scripts/
├── .env.example
├── requirements.txt
├── Dockerfile
└── README.md
```

### 最终演示流程

```text
用户：我想在一个月内掌握 Agent 开发。

Agent：
1. 读取用户当前水平
2. 生成学习计划
3. 将计划写入任务数据库
4. 推荐今天的学习任务
5. 根据知识库回答问题
6. 生成练习题
7. 批改答案
8. 更新学习进度
9. 输出当日总结
```

---

# 三、每周固定学习节奏

建议每周按照下面的比例安排：

| 环节   |   时间 | 内容              |
| ---- | ---: | --------------- |
| 理论学习 | 2 小时 | 阅读官方文档，整理概念     |
| 示例复现 | 2 小时 | 不修改地运行官方示例      |
| 独立编码 | 4 小时 | 不照抄示例完成任务       |
| 测试调试 | 2 小时 | 构造错误输入和边界情况     |
| 复盘总结 | 1 小时 | 编写 README 和学习笔记 |

每天推荐采用：

```text
20 分钟：阅读概念
60 分钟：写代码
20 分钟：测试和记录问题
```

最重要的是：**每学一个概念，立即写一个可以运行的小程序。**

---

# 四、推荐学习顺序

严格按照这个顺序学习：

```text
模型 API
→ 消息与 Prompt
→ 结构化输出
→ Tool Calling
→ 手写 Agent Loop
→ 使用 Agent SDK
→ 对话状态
→ RAG
→ LangGraph
→ 多 Agent
→ MCP
→ 评估与部署
```

不要采用下面这种顺序：

```text
一开始就学多 Agent
→ 同时学习五个框架
→ 复制一个复杂开源项目
→ 程序能运行但不知道为什么
```

---

# 五、学习过程中必须手写的 6 个项目

按难度依次完成：

1. **结构化信息提取器**
   学习 API、Prompt 和 Pydantic。

2. **工具调用助手**
   学习 Function Calling 和 Agent Loop。

3. **带记忆的聊天助手**
   学习状态、会话和数据库。

4. **本地文档问答 Agent**
   学习 RAG、引用和知识边界。

5. **研究报告多 Agent**
   学习任务拆解、handoff 和审核。

6. **智能学习助理**
   综合 API、工具、记忆、RAG、工作流、评估和部署。

每个项目都必须包含：

```text
README
环境变量示例
类型注解
异常处理
日志
单元测试
测试数据集
运行截图或演示视频
```

---

# 六、你暂时不需要深入学习的内容

入门阶段先不深入：

* 模型微调
* 自己训练大语言模型
* 复杂强化学习
* 大规模分布式 Agent
* Kubernetes
* 十几个 Agent 的群体协作
* 高复杂度知识图谱
* 浏览器自动化和电脑控制
* 自主执行高风险操作
* 同时适配大量模型供应商

先做到：

> 一个 Agent，三个可靠工具，一个清晰工作流，一套测试数据。

这比做十个不能稳定运行的 Agent 更有价值。

---

# 七、判断自己是否真正学会了

遇到一个新 Agent 需求时，你应该能回答：

1. 这个任务真的需要 Agent 吗？
2. 普通工作流是否已经足够？
3. 哪些步骤必须由代码控制？
4. 哪些步骤可以让模型判断？
5. Agent 可以使用哪些工具？
6. 每个工具需要什么权限？
7. 哪些操作必须人工确认？
8. 状态和记忆保存在哪里？
9. 如何判断任务已经完成？
10. 如何测试它比普通聊天机器人更好？

能够独立回答并实现这些问题，就已经具备了独立开发 Agent 的基础能力。

---

## 最重要的学习原则

**先理解循环，再学习框架；先做单 Agent，再做多 Agent；先建立测试，再增加功能。**

你的第一周不要追求做出“万能助手”。只完成一个能够稳定调用模型、返回结构化结果、具备异常处理的小程序。第二周再让它真正使用工具。这样进步最快，也最不容易陷入“会调用框架，但不会设计 Agent”的状态。

[1]: https://openai.github.io/openai-agents-python/?utm_source=chatgpt.com "OpenAI Agents SDK"
[2]: https://openai.github.io/openai-agents-python/zh/tools/?utm_source=chatgpt.com "工具 - OpenAI Agents SDK"
[3]: https://openai.github.io/openai-agents-python/agents/?utm_source=chatgpt.com "Agents - OpenAI Agents SDK"
[4]: https://docs.langchain.com/oss/python/langgraph/overview?utm_source=chatgpt.com "LangGraph overview - Docs by LangChain"
[5]: https://docs.langchain.com/oss/python/langgraph/workflows-agents?utm_source=chatgpt.com "Workflows and agents - Docs by LangChain"
[6]: https://docs.langchain.com/oss/python/langgraph/graph-api?utm_source=chatgpt.com "Graph API overview - Docs by LangChain"
[7]: https://modelcontextprotocol.io/docs/getting-started/intro?utm_source=chatgpt.com "What is the Model Context Protocol (MCP)? - Model Context Protocol"
[8]: https://openai.github.io/openai-agents-python/usage/?utm_source=chatgpt.com "Usage - OpenAI Agents SDK"