为什么需要搭建环境

本课程每节课都附带可运行的 Python 代码示例（Jupyter Notebook）。这些示例基于 Microsoft Agent Framework (MAF) 与 Microsoft Foundry Agent Service V2（Responses API），通过 Microsoft Foundry 连接到大模型。在动手写代码前，先把环境准备好。

运行环境要求

获取代码

点击仓库右上角的 Fork 按钮，得到你自己的副本，然后克隆：

bash
git clone --depth 1 https://github.com/<你的用户名>/ai-agents-for-beginners.git
cd ai-agents-for-beginners
pip install -r requirements.txt

配置 Microsoft Foundry

1. 在 ai.azure.com 登录 Azure 账号，创建 Hub 与 Project。
2. 在 Models + Endpoints 部署一个模型（如 gpt-5-mini）。
3. 在项目 Overview 复制 Project Endpoint；在模型页复制 Deployment name。
4. 终端执行 az login 完成无密钥登录（课程 Notebook 使用 AzureCliCredential）。
5. 复制 .env.example 为 .env，填入：AZURE_AI_PROJECT_ENDPOINT 与 AZURE_AI_MODEL_DEPLOYMENT_NAME。

不想用 Azure？试试替代方案

• MiniMax：OpenAI 兼容接口，提供最大 204K tokens 上下文模型。在 .env 配置 MINIMAX_API_KEY / MINIMAX_BASE_URL / MINIMAX_MODEL_ID 即可作为 Azure OpenAI 的平替。
• Foundry Local：在你的机器上本地运行小模型（如 phi-4-mini），完全离线、无需 Azure 订阅和 API Key，适合本地开发与隐私场景。

📝 随堂测验

AI 智能体到底是什么？

一个智能体不只是“一个东西”，而是多个部件协同工作的集合。每个智能体核心由三个部分组成：

没有智能体系统时，LLM 只能生成文本；而在智能体系统内，LLM 能真正执行步骤——搜索数据库、调用 API、发送消息。智能体还能拥有短期记忆（当前对话）与长期记忆（客户数据库、历史交互）。

智能体的不同类型

什么时候该用 AI 智能体？

• 开放式问题：解决问题的步骤无法预先写死，需要 LLM 动态规划路径。
• 多步骤流程：需要跨多轮使用工具，而不只是单次查询或生成。
• 随时间改进：希望系统能基于用户反馈或环境信号变得更聪明。

智能体方案的基础构件

• 智能体开发：先定义它能做什么——工具、动作、行为。本课程用 Microsoft Foundry Agent Service 作为主平台。
• 智能体模式（Agentic Patterns）：可复用的提示与编排策略，让 LLM 在规模化、可靠的方式下行动。
• 智能体框架：提供现成模板、工具与基础设施，方便接线工具、观测调试、多智能体协作。本课程聚焦 Microsoft Agent Framework。

📝 随堂测验

框架解决了什么问题

传统 AI 框架帮你把 AI 集成进应用（个性化、自动化、增强用户体验）。而智能体框架更进一步：它让开发者创建能与用户、其他智能体以及环境交互以达成目标的智能体，具备自主行为、决策与适应能力。

框架带来的关键能力：

• 智能体协作与协调：创建多个智能体共同解决复杂任务。
• 任务自动化与管理：多步骤工作流、任务委派、动态任务管理。
• 上下文理解与适应：理解上下文、适应环境变化、基于实时信息决策。

如何快速原型与迭代

• 使用模块化组件：SDK 提供 AI 连接器、记忆模块、函数调用、提示词模板等现成部件。
• 善用协作工具：为智能体设计明确角色与任务，测试并打磨协作流程。
• 实时学习：通过反馈回路让智能体从交互中学习并动态调整。

用 MAF 定义工具（@tool）

python
@tool(approval_mode="never_require")
def book_flight(date: str, location: str) -> str:
    """Book travel given location and date."""
    return f"Travel was booked to {location} on {date}"

provider = FoundryChatClient(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=AzureCliCredential(),
)
agent = provider.as_agent(
    name="travel_agent",
    instructions="Help the user book travel.",
    tools=[book_flight],
)
response = await agent.run("I'd like to go to New York on Jan 1")

两套微软方案的区别

多智能体协作示例（MAF）

python
agent_retrieve = provider.as_agent(name="dataretrieval", instructions="Retrieve data.", tools=[retrieve_tool])
agent_analyze = provider.as_agent(name="dataanalysis", instructions="Analyze data.", tools=[analyze_tool])

retrieval = await agent_retrieve.run("Retrieve sales data for Q4")
analysis = await agent_analyze.run(f"Analyze this: {retrieval}")
print(analysis)

📝 随堂测验

以人为本的设计原则

在生成式 AI 中，模糊性本身就是特性而非缺陷。为帮助团队着手，微软提出一套以人为本的 UX 设计原则，作为定义与构建智能体体验的起点（而非规定性架构）。智能体应当：

• 扩展并放大人类能力（头脑风暴、问题解决、自动化）
• 填补知识鸿沟（快速上手某个领域、翻译等）
• 促进并支持符合个人偏好的协作
• 帮助我们成为更好的自己（如生活教练、情绪调节）

三大维度

Agent（空间 Space）

• 连接而非折叠：帮助人与人、事件、可行动知识建立连接，而不是取代或贬低人。
• 易得且偶尔隐形：大多在后台运行，只在恰当的时刻轻轻提醒；支持多模态输入输出，可在前台/后台、主动/被动间无缝切换。

Agent（时间 Time）

• 过去：基于更丰富的历史数据与记忆进行反思。
• 现在：更多是“轻推”而非单纯的“通知”，在正确时刻引导注意力。
• 未来：适应设备、平台与用户行为，并随持续交互而演化。

Agent（核心 Core）

落地指南

📝 随堂测验

什么是工具使用设计模式

工具使用设计模式的核心是：赋予 LLM 与外部工具交互以达成目标的能力。工具是能被智能体执行的代码——可以是一个简单函数（如计算器），也可以是调用第三方服务的 API（如查股价、查天气）。在智能体语境下，工具由智能体响应模型生成的函数调用来触发。

适用场景

• 动态信息检索：查询外部 API / 数据库获取最新数据（SQLite 分析、股价、天气）。
• 代码执行与解释：运行代码解题、生成报告、做仿真。
• 工作流自动化：用任务调度、邮件、数据管道串联多步流程。
• 客户支持：对接 CRM、工单、知识库解决用户问题。
• 内容生成与编辑：语法检查、摘要、内容安全评估。

关键构件

• 函数/工具 Schema：工具的名称、用途、参数、返回值的详细定义，让 LLM 知道怎么构造合法请求。
• 函数执行逻辑：基于用户意图与上下文决定何时、如何调用工具（规划器、路由、条件流）。
• 消息处理系统：管理用户、LLM、工具调用与工具返回之间的对话流。
• 工具集成框架：连接各类工具的基础设施。
• 错误处理与校验：处理工具执行失败、校验参数、管理异常响应。
• 状态管理：跨多轮维护上下文与历史工具交互。

函数调用（Function Calling）是怎么工作的

LLM 把用户的请求与函数描述做比对，选出最合适的函数，返回函数名与参数；被选中的函数被执行，结果再回传给 LLM，由它生成最终回答。需要三样东西：支持函数调用的模型、包含函数描述的 Schema、每个函数的实现代码。

示例：查询某城市当前时间

python
tools = [{
    "type": "function",
    "name": "get_current_time",
    "description": "Get the current time in a given location",
    "parameters": {
        "type": "object",
        "properties": {"location": {"type": "string", "description": "City name"}},
        "required": ["location"],
    },
}]

messages = [{"role": "user", "content": "What's the time in San Francisco?"}]
response = client.responses.create(model=deployment, input=messages, tools=tools, tool_choice="auto")
# 模型返回的是工具调用，而非最终答案

构建可信赖智能体的注意事项

LLM 动态生成的 SQL 常让人担心注入或恶意操作（如删库）。有效缓解方式：把数据库配置为只读权限，应用只分配 SELECT 角色；在安全环境中运行；在企业场景中把运营数据 ETL 到只读数据仓库，schema 友好且权限受限。

📝 随堂测验

什么是 Agentic RAG

Agentic RAG 是一种新兴范式：LLM 在从外部数据源拉取信息的同时，自主规划下一步。不同于“先检索后阅读”的静态流程，它是一连串对 LLM 的迭代调用，穿插着工具/函数调用与结构化输出。系统评估结果、改写查询、必要时调用更多工具，循环往复，直到得到满意结果。这种迭代式的“生成者—校验者（maker-checker）”风格提升了正确性，也能处理畸形查询。

拥有推理过程（Owning the Reasoning）

区分一个系统是否“具智能体性”的关键，在于它能否拥有自己的推理过程。传统 RAG 依赖人类预先定义路径；而真正的智能体系统会基于所找到信息的质量，自主决定步骤顺序。例如制定产品发布策略时，它会自主决定：

1. 用 Bing Web Grounding 检索最新市场趋势报告
2. 用 Azure AI Search 识别竞品数据
3. 用 Azure SQL 关联内部历史销售指标
4. 通过 Azure OpenAI 综合成策略
5. 评估策略是否存在缺口，必要时再检索一轮

迭代循环、工具集成与记忆

失败模式与自我纠正

• 迭代与重查：尝试新搜索策略、改写查询、换数据集。
• 诊断工具：调用辅助函数调试推理步骤，Azure AI Tracing 提供可观测性。
• 回退人工监督：高风险或反复失败时，标记不确定并请求人类指导。

价值与治理

它在正确性优先（合规、法务）、复杂数据库交互（NL2SQL 自适应改写）、长流程工作流中表现出色。随着自主性增强，可解释推理（审计轨迹）、偏见控制与人工监督变得至关重要。

📝 随堂测验

安全（Safety）

安全意味着智能体按设计运行。对智能体而言，系统提示词（System Message）比普通 AI 应用更重要——它需要高度具体的指令来约束智能体完成任务。为规模化地写好系统提示词，可采用系统消息框架：

1. 第 1 步 元系统消息（Meta）：让一个 LLM 根据公司名、角色、职责生成智能体的系统提示词模板。
2. 第 2 步 基础提示词：描述智能体角色、任务与其他职责。
3. 第 3 步 交给 LLM 优化：把元提示词与基础提示词一起输入，得到结构清晰、更适合指导智能体的系统消息。
4. 第 4 步 迭代改进：很少有一次写对的提示词，小步调整并对比评估效果。

理解威胁与缓解

人在回路（Human-in-the-Loop）

让用户能在运行中提供反馈、审批或终止，是构建可信系统的有效方式。用户相当于多智能体系统中的一个“智能体”。

python
provider = FoundryChatClient(project_endpoint=..., model=..., credential=AzureCliCredential())
response = provider.create_response(
    input="Write a 4-line poem about the ocean.",
    instructions="You are a helpful assistant. Ask for user approval before finalizing.",
)
print(response.output_text)
user_input = input("Do you approve? (APPROVE/REJECT): ")
if user_input == "APPROVE":
    print("Response approved.")
else:
    print("Response rejected. Revising...")

📝 随堂测验

定义目标并拆解任务

多数真实任务太复杂，无法一步完成。智能体需要一个简洁的目标来引导规划。例如“生成一份 3 天旅行行程”——越清晰，智能体与协作者越能聚焦正确结果。

任务分解（Task Decomposition）

把大任务拆成更小、目标导向的子任务。以旅行行程为例，可拆成：航班预订、酒店预订、租车、个性化。每个子任务交给专门的智能体，再由一个协调智能体汇总成完整行程。模块化还便于后续增量增强（如加“美食推荐”专用智能体）。

结构化输出

LLM 可生成 JSON 等结构化输出，便于下游智能体或服务解析处理——在多智能体协作中尤其有用：规划结果可直接路由给对应智能体执行。

python
class TravelSubTask(BaseModel):
    task_details: str
    assigned_agent: AgentEnum

class TravelPlan(BaseModel):
    main_task: str
    subtasks: List[TravelSubTask]
    is_greeting: bool

# 系统提示词要求模型以 JSON 返回计划，包含主任务与子任务列表
system_prompt = """You are a planner agent.
    Decide which agents to run based on the user's request.
    Provide your response in JSON format..."""

多智能体编排的规划智能体

一个 Semantic Router 智能体接收请求（如“帮我做酒店计划”），规划器基于系统提示词生成结构化行程，再从智能体注册表中找到对应智能体与工具，单任务直接派发、多任务经群聊管理器协调，最后汇总结果。

迭代式规划

有些任务需要来回或重新规划——一个子任务的结果会影响下一步。例如订票时发现数据格式异常，就需要先调整策略再继续酒店预订；用户的反馈（想改早班机）也会触发局部重规划。这种动态迭代确保最终方案贴合真实约束与偏好。

📝 随堂测验

什么是多智能体模式

适用场景

• 大工作量：拆成小任务并行处理（如大型数据处理）。
• 复杂任务：拆给不同专长的智能体（如自动驾驶中导航、障碍检测、车际通信各司其职）。
• 多元专长：不同智能体各有所长，比单一智能体更有效（如医疗中诊断、治疗方案、患者监测分开）。

相比单一智能体的优势

实现构件

• 智能体通信：决定哪些智能体共享什么信息、如何共享（如航班智能体要把日期同步给酒店智能体）。
• 协调机制：协调彼此动作以满足用户偏好与约束。
• 智能体架构：内部决策与从交互中学习的结构。
• 多智能体交互可见性：用日志、可视化、性能指标追踪交互。
• 多智能体模式：集中式、去中心化、混合架构。
• 人在回路：明确何时请求人工介入（如预订前确认）。

常见多智能体模式

📝 随堂测验

让智能体“思考自己的思考”

元认知（Metacognition）指的是智能体对自身思考过程进行监控与反思的能力——不只是给出答案，还能评估“我这个答案靠谱吗？我的推理有没有漏洞？”。它是让智能体更可靠、更值得信任的重要一层。

核心思想

• 自我监控：在执行过程中检查自己的状态与进度。
• 自我反思：对已完成的结果做复盘，识别错误或偏差。
• 自我修正：基于反思调整策略，再次尝试。

何时使用

当任务容错率低、需要可解释性或步骤复杂易出错时，引入元认知能显著提升质量。但也要注意成本：多一轮“反思”意味着多一次模型调用，应在关键节点而非每一步都使用。

📝 随堂测验

从原型走向真实应用

当 AI 智能体从实验原型走向真实应用，理解其行为、监控其性能、系统化评估其产出变得至关重要。生产环境关注的不只是“能不能跑”，而是“跑得稳不稳、对不对、贵不贵”。

可观测性（Observability）

• 追踪（Tracing）：记录每一步 LLM 调用、工具调用与中间结果，形成可审计的轨迹。
• 日志与指标：记录延迟、token 消耗、成功率、错误率等。
• 回溯调试：当结果异常时，能顺着轨迹定位是哪一步出了问题。

评估（Evaluation）

用数据集与 rubric 对智能体输出打分：正确性、相关性、安全性、成本效率等。可结合自动化评估与人工抽检，持续回归测试，防止改一处坏一片。

📝 随堂测验

为什么需要协议

当智能体要连接无数工具、彼此协作、或与网站交互时，需要统一“协议”来标准化这些交互，否则集成成本会爆炸。本章介绍三个关键协议：

MCP（Model Context Protocol）

MCP 为智能体定义了连接数据源与工具的标准方式——就像给智能体装上了统一的“插头”，不同厂商的工具都可按同一规范接入，避免为每个工具写一套定制集成。

A2A（Agent-to-Agent）

A2A 让不同来源、不同框架构建的智能体能够彼此发现、通信与协作，支撑跨系统的多智能体编排。

NLWeb

NLWeb 把自然语言接口带到任意网站，使智能体能够“理解”网页并以对话方式与之交互，拓宽了智能体可操作的外部世界。

📝 随堂测验

上下文工程 ≠ 提示词工程

提示词工程关注“怎么写好一句提示”；上下文工程关注的是：在每一次推理时，把哪些信息、以什么形式、放进模型的上下文窗口。对长流程、多工具的智能体来说，上下文管理直接决定成败。

四大策略

常见上下文失败

• 上下文污染：无关或错误的信息混进来，带偏模型。
• 上下文溢出：超出窗口限制，关键信息被截断。
• 上下文漂移：长对话中目标逐渐模糊。

📝 随堂测验

记忆为何重要

没有记忆，智能体每轮对话都像“失忆”——无法利用历史、无法个性化、无法持续改进。记忆让智能体跨会话保留知识，是个性化与自我改进的基础。

短期记忆 vs 长期记忆

如何让智能体自我改进

• 把交互结果与反馈写入长期记忆，供后续检索。
• 基于过往经验调整决策与推荐。
• 结合第 9 课元认知，对失败做复盘并沉淀为经验。

📝 随堂测验

MAF 是什么

Microsoft Agent Framework (MAF) 是一个开源、生产级的智能体构建 SDK。它通过 FoundryChatClient 让开发者用极少代码定义带工具调用、会话管理与企业级安全（Azure 身份）的智能体。

核心抽象

• Agent：由名称、指令（instructions）与工具组成，能处理消息、自动调用工具、维护会话状态。
• Tools：以 Python 函数形式注册，框架自动序列化并生成 Schema。
• 多智能体协调：创建多个专职智能体并编排其工作。
• Azure 身份集成：用 AzureCliCredential / DefaultAzureCredential 实现无密钥鉴权。

最小示例

python
provider = FoundryChatClient(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=AzureCliCredential(),
)
agent = provider.as_agent(name="my_agent", instructions="You are a helpful assistant.")
response = await agent.run("Hello, World!")
print(response)

📝 随堂测验

什么是计算机使用智能体（CUA）

当目标任务没有现成 API、或界面是动态变化的网页时，计算机使用智能体可以通过“看屏幕 + 操作界面”来完成任务——就像人一样点按、输入、滚动。

何时比 API 自动化更合适

• 目标站点没有公开 API 或 API 能力受限。
• 流程依赖动态渲染、反爬或人工界面操作。
• 需要跨多个异构网站完成同一类任务。

技术组合

📝 随堂测验

原型 vs 部署

把智能体从 Notebook 原型推向生产，难点往往不在模型本身，而在模型周围的一切：鉴权、并发、伸缩、可观测、成本控制、合规。

部署模式

智能体生命周期

• 版本管理与回滚
• 蓝绿 / 灰度发布
• 自动伸缩与限流
• 健康检查与告警
• 与第 10 课可观测性、第 18 课安全 receipts 联动

📝 随堂测验

小语言模型（SLM）

SLM 指的是参数量较小、可在本地/边缘设备运行的模型。它们在延迟低、隐私好、离线可用、成本低的场景中表现出色；但在复杂推理、广博知识上不如大模型。

Microsoft Foundry Local

Foundry Local 是一个轻量运行时，通过 OpenAI 兼容 API 在本机下载、管理并托管模型——无需云、无需 Azure 订阅、无需 API Key。非常适合离线开发、零云成本实验与数据留本机。

快速开始

bash
winget install Microsoft.FoundryLocal   # Windows
foundry model list
foundry model run phi-4-mini

Qwen 函数调用模型

Qwen 等小模型在函数调用上表现可靠，可作为本地智能体的大脑，配合 MAF 的 OpenAIChatClient（OpenAI 兼容端点）即插即用。

📝 随堂测验

为什么需要审计轨迹

智能体会自动调用工具、改数据、发消息。为了合规、调试与建立信任，我们必须能证明“某次工具调用确实发生过、且内容未被篡改”。普通日志行可以被悄悄修改，缺乏可信度。

密码学收据（Cryptographic Receipt）

密码学收据是对智能体某次工具调用（输入、输出、时间戳等）进行数字签名的产物。它与“无签名的日志行”的关键区别：任何篡改都会使签名校验失败，从而可被离线检测。

生成与验证（思路）

python
# 伪代码：用私钥对调用内容签名，产出可验证收据
import hashlib, json
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

def make_receipt(payload: dict, private_key) -> dict:
    data = json.dumps(payload, sort_keys=True).encode()
    signature = private_key.sign(data, padding.PKCS1v15(), hashes.SHA256())
    return {"payload": payload, "signature": signature.hex()}

def verify_receipt(receipt: dict, public_key) -> bool:
    data = json.dumps(receipt["payload"], sort_keys=True).encode()
    try:
        public_key.verify(bytes.fromhex(receipt["signature"]), data,
                          padding.PKCS1v15(), hashes.SHA256())
        return True
    except Exception:
        return False  # 内容被篡改或签名不匹配

📝 随堂测验