# 初学者的 AI 代理 - 学习指南

在学习课程时，将本指南作为实用伴侣使用。
它并不是要替代课程内容，而是帮助你决定从哪里开始，课程中该关注什么，
以及如何将这些想法连接起来，做成一个小型的可运行代理演示。


如果你是第一次接触，建议简易开始：

1. 阅读[课程设置](./00-course-setup/README.md)。
2. 按顺序完成第01到06课。
3. 学习过程中保持一个小型演示想法在脑海中。
4. 每课结束后，问自己：“我的代理现在能做什么，以前做不到的？”


## 一个简单的演示示例

通过课程跟随一个演示思路学习代理非常有效。

示例演示：<strong>课程助手代理</strong>。

用户会这样问：

> “我想学习代理如何使用工具。帮我找到合适的课程，总结我先要读的内容，
> 并给我一个简短的练习任务。”

普通聊天机器人可以回答它已有知识的信息，但代理能做得更多：

1. <strong>阅读或搜索课程文件</strong>，找到合适的课程。
2. <strong>使用工具</strong>检索课程链接、示例或辅助材料。
3. <strong>规划</strong>一个短的学习路径，而不是给出一个冗长答案。
4. <strong>利用上下文</strong>，基于当前对话聚焦学习者的目标。
5. <strong>记忆有用偏好</strong>，如果应用支持记忆功能。
6. **显示操作痕迹、引用或日志**，让用户理解发生了什么。
7. <strong>应用安全防护措施</strong>，在执行高风险操作或使用敏感数据前进行保护。





## 你要构建的目标

课程结束时，你应该能解释并构建结合这些部分的代理系统：


| 部分 | 通俗含义 | 演示中的表现 |
|------|------------------------|-------------|
| 模型 | 解释用户请求的推理引擎 | 理解学习者想要学习工具使用课程 |
| 工具 | 代理可调用的函数、API、文件、浏览器或服务 | 搜索代码库或检索课程内容 |
| 知识 | 用来支撑回答的文档或数据 | 课程 README 文件和课程资料 |
| 上下文 | 下一次模型调用时包含的信息 | 用户目标和工具结果 |
| 记忆 | 为后续使用保存的信息 | 学习者偏好动手的 Python 示例 |
| 规划 | 把大目标拆分成小步骤 | 找课程，总结，建议练习 |
| 协调 | 在工具、步骤或代理间路由工作 | 计划者调用搜索工具，再调用总结器 |
| 信任 | 安全性、评估和可观测性 | 记录工具调用并在重大操作前询问 |

## 模型和提供者

本课程示例代码使用<strong>Microsoft Agent Framework (MAF)</strong>，针对<strong>Azure OpenAI Responses API</strong> —— 推荐的 API，整合了聊天完成、工具调用、多模态输入和有状态对话于一个接口。你可以通过<strong>Microsoft Foundry</strong>项目（使用`FoundryChatClient`）或直接连接 Azure OpenAI（使用`OpenAIChatClient`）。

在学习过程中，你有几个提供者选项：

- **Microsoft Foundry / Azure OpenAI (Responses API)** — 这是课程中主要使用的路径。使用`az login`命令登陆，实现无密 Entra ID 认证。
- **Foundry 本地版** — 通过兼容 OpenAI 的 API 在设备上完整运行模型（无云，无 API key）。适合离线或免费实验。详情见[课程设置](./00-course-setup/README.md)。
- **MiniMax** — 兼容 OpenAI 的提供者，支持大上下文模型，可作为替代方案直接使用。

> **注意：** GitHub Models 已弃用（2026 年 7 月退役），且不支持 Responses API。示例代码已更新，改为使用 Azure OpenAI / Microsoft Foundry。

## 选择你的学习路线

你可以按顺序完成全课程，或根据想要构建的目标跳转路径。


| 如果你的目标是... | 从这开始 | 接着学习 |
|-----------------------|------------|------------|
| 理解什么是代理 | 01, 02, 03 | 04, 05, 06 |
| 构建使用工具的代理 | 04 | 05, 07, 14 |
| 构建基于 RAG 的代理 | 05 | 04, 06, 12 |
| 设计多步骤工作流 | 07 | 08, 09, 14 |
| 理解多代理系统 | 08 | 07, 09, 11 |
| 准备代理用于生产环境 | 06, 10 | 12, 13, 16, 18 |
| 在 Foundry 上部署和扩展代理 | 10, 16 | 06, 13, 18 |
| 构建本地/优先离线代理 | 17 | 04, 05, 11 |
| 探索协议和浏览器自动化 | 11, 15 | 10, 18 |

提示：如果你是代理新手，不要跳过第01-06课。这些课会给你全课程所需的词汇基础。


## 逐课指南

| 课程 | 学习内容 | 课后练习 |
|--------|----------------|---------------------------|
| [01 - AI 代理简介](./01-intro-to-ai-agents/README.md) | 什么让代理与基础聊天机器人不同。 | 用代理身份讲述你的演示想法，而不仅是聊天应用。 |
| [02 - 代理框架](./02-explore-agentic-frameworks/README.md) | 框架如何帮助模型、工具、状态和工作流。 | 确定框架会管理你演示的哪些部分。 |
| [03 - 代理设计模式](./03-agentic-design-patterns/README.md) | 设计代理行为的常见模式。 | 在写代码前绘制用户旅程草图。 |
| [04 - 工具使用](./04-tool-use/README.md) | 代理如何调用工具获取数据或采取行动。 | 定义你演示代理需要的一个工具。 |
| [05 - 代理检索增强生成（RAG）](./05-agentic-rag/README.md) | 如何通过检索支持代理回答的文件或数据。 | 决定演示应搜索的知识源。 |
| [06 - 可信赖的代理](./06-building-trustworthy-agents/README.md) | 如何添加护栏、监督以及更安全的行为。 | 添加一条规则，说明代理何时应该先询问用户。 |
| [07 - 规划设计](./07-planning-design/README.md) | 代理如何将更大的目标分解为更小的步骤。 | 为你的演示请求写一个三步计划。 |
| [08 - 多代理设计](./08-multi-agent/README.md) | 何时将工作分配给多个专门代理。 | 决定你的演示需要一个代理还是多个代理。 |
| [09 - 元认知](./09-metacognition/README.md) | 代理如何审查并改进自身输出。 | 在代理响应前加入最终的自我检查。 |
| [10 - 生产环境中的AI代理](./10-ai-agents-production/README.md) | 当代理从演示转到生产环境时会发生什么变化。 | 列出你会监控的内容：质量、成本、延迟、失败。 |
| [11 - 代理协议](./11-agentic-protocols/README.md) | 协议如何连接代理与工具及其他代理。 | 确定在哪些地方标准协议可以简化集成。 |
| [12 - 上下文工程](./12-context-engineering/README.md) | 如何选择、修剪、隔离和管理上下文。 | 决定什么内容放入提示中，什么内容应排除。 |
| [13 - 代理记忆](./13-agent-memory/README.md) | 代理如何在交互中保存有用信息。 | 选择一个你的演示可以记住的安全偏好。 |
| [14 - 微软代理框架](./14-microsoft-agent-framework/README.md) | 针对代理和工作流的框架特定构建块，以及在Microsoft Foundry上托管LangChain/LangGraph代理。 | 将你的演示步骤映射到框架概念。 |
| [15 - 计算机使用代理](./15-browser-use/README.md) | 代理如何与浏览器或UI界面交互，包括微软Project Opal等现实案例。 | 选择一个浏览器任务，仍需用户确认。 |
| [16 - 部署可扩展代理](./16-deploying-scalable-agents/README.md) | 如何将代理从原型转为在Microsoft Foundry上可扩展、可观测的生产部署（托管代理、模型路由、缓存、评价门控、冒烟测试）。 | 列出你的演示仍需考虑的生产问题：托管、路由、成本、评价。 |
| [17 - 创建本地AI代理](./17-creating-local-ai-agents/README.md) | 如何构建完全在你的机器上运行的本地优先代理，使用Foundry Local和Qwen（本地工具、本地RAG、本地MCP）。 | 决定你的演示哪些部分应保密并本地运行。 |
| [18 - 保障AI代理安全](./18-securing-ai-agents/README.md) | 如何使代理行为更易审计且防篡改。 | 决定你的演示中哪些行为应被记录或生成凭证。 |

## 使用冒烟测试验证已部署的代理

当你部署代理时（第16课），<strong>冒烟测试</strong>是最便宜的首步
检查，以确认部署实际上有响应。该仓库附带了
可运行的测试目录，位于[tests/](./tests/README.md)，用于第
01、04、05和16课中可部署的代理，

[AI Smoke Test](https://github.com/marketplace/actions/ai-smoke-test) GitHub
操作。 在部署课程代理后，从<strong>操作</strong>标签运行它们。
烟雾测试是第一道门槛——离线和在线评估（第10和第16课）
告诉你代理有多<em>优秀</em>。

## 初学者友好的关键理念

### 工具

工具是代理可以调用以在模型之外完成工作的东西。一个好的工具
拥有清晰的名称、狭窄的任务、类型化的输入、可预测的输出，以及安全的
失败方式。

对于课程助手演示，一个工具可能是：

- `search_lessons(query)`
- `read_lesson(path)`
- `create_practice_task(topic)`

### RAG 和知识

RAG 帮助代理从源材料回答问题而不是凭猜测。在本
课程中，该源材料可以是课程的 README、代码示例或课程中链接的外部
资源。

当答案应以文档、数据或当前
项目文件为基础时，使用 RAG。

### 计划

当请求包含多个步骤时，规划是有用的。保持计划简短且
足够明显，方便开发人员或用户检查。

对于演示，一个计划可能是：

1. 查找与工具使用相关的课程。
2. 总结最相关的课程。
3. 推荐一个练习任务。

### 上下文

上下文是模型当前所见。上下文过少会使代理
错过重要细节。上下文过多会让代理变慢、成本更高，
或更容易混淆。

良好的上下文工程意味着为下一次模型
调用选择合适的信息。

### 记忆

记忆是保存以备后用的信息。不应保存所有内容。仅在信息
有用、安全且容易更新或删除时保存。

例如，记住“学习者偏好 Python 示例”可能有用。
记住敏感个人数据通常没有用。

### 评估与可观察性

评估问：代理是否做了正确的事？

可观察性问：我们能看到它是怎样发生的吗？

对于生产代理，跟踪模型调用、工具调用、检索上下文、
延迟、成本、失败和用户反馈。

### 信任与安全

值得信赖的代理需要的不仅是一个有帮助的提示。使用最少权限工具，
对高影响操作需要人工审批，必要时进行数据脱敏，并对必须审计的操作
保留日志或记录。

## 15分钟复习流程

每节课后使用此流程：

1. **用一句话总结课程。**
2. <strong>命名新的代理能力。</strong>例如：工具使用、检索、
   规划、记忆、可观察性或安全。
3. <strong>将它添加到课程助手演示中。</strong>演示现在发生了什么变化？
4. <strong>找出风险。</strong>如果此能力被滥用，可能出什么问题？
5. <strong>写一个测试问题。</strong>你如何检查代理表现良好？

## 快速自查

继续之前，尝试回答这些问题：

1. 代理能做哪些普通聊天机器人自己做不了的事？
2. 你的代理首先需要哪种工具，为什么？
3. 应该用哪个知识源来支撑代理的回答？
4. 下一次模型调用应包含哪些上下文？

5. 代理应该记住什么，应该避免存储什么？
6. 代理什么时候应该请求人工批准？
7. 什么日志、跟踪或收据能帮助你以后调试或审计代理？


## 建议的毕业设计练习

在课程结束时，构建一个小型代理，帮助学习者浏览此
仓库。

最低版本：

- 接收用户输入的主题。
- 查找最相关的课程。
- 总结先阅读什么内容。
- 建议一个动手实践任务。
- 显示使用了哪些课程文件或链接。

拓展版本：

- 记住学习者偏好的编程语言。
- 在回答前使用简单的计划。
- 在最终回复前添加自检步骤。
- 记录工具调用和检索到的来源。
- 在打开浏览器或执行 UI 自动化任务前请求确认。

这为你提供了一个小而真实的项目来练习工具、RAG、规划、
上下文、记忆、可观察性和信任。

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**免责声明**：
本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻译完成。尽管我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。原始语言版文件应视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用本翻译而产生的任何误解或误释不承担责任。
<!-- CO-OP TRANSLATOR DISCLAIMER END -->