# 人工智能代理开发 > **目的**：使用 Microsoft Foundry 和 Agent Framework 构建可用于生产的 AI 代理。 **范围**：代理架构、模型选择、编排、可观察性、评估。 ** ** ## 何时使用此技能 * 使用 Microsoft Foundry 或 Agent Framework 构建 AI 代理 * 针对代理场景选择LLM模型 * 实施多代理编排工作流程 * 为人工智能代理添加追踪和可观察性 * 评估座席质量和响应准确性 ## 决策树需要人工智能代理吗？ +-- 简单的请求-响应？ -> 带工具的单一代理 +-- 多步推理？ -> 具有规划器的思想链代理 +-- 多个专业领域？ -> 多代理编排 +-- 需要人工批准吗？ -> 人机交互工作流程 +-- 需要高可靠性？ -> 反思+自我修正循环 +-- 实时流媒体？ -> 异步事件驱动代理架构 ## 先决条件 * Python 3.11+ 或 .NET 8+ * 代理框架-azure-ai 包 * 具有已部署模型的 Microsoft Foundry 工作区 ## 快速入门 ### 安装 **Python**（推荐）： pip install agent-framework-azure-ai --pre # --pre 预览期间需要 **.NET**： dotnet 添加包 Microsoft.Agents.AI.AzureAI --prerelease dotnet 添加包 Microsoft.Agents.AI.Workflows --prerelease ### 型号选择 **顶级生产型号**（Microsoft Foundry）：型号|最适合 |背景 |成本/1M ---|---|---|--- **gpt-5.2** |企业代理，结构化输出| 20万/10万|待定 **gpt-5.1-codex-max** |代理编码工作流程 | 272K/128K | 3.44 美元 **克劳德-opus-4-5** |复杂代理、编码、计算机使用| 200K/64K | 10 美元 **gpt-5.1** |多步推理 | 20万/10万| 3.44 美元 **o3** |高级推理| 20万/10万| 3.5 美元 **部署模型** : `Ctrl+Shift+P` -> `AI Toolkit: 部署模型` ** ** ## 代理模式 ### 单一代理从 pathlib 导入路径从 agent_framework.openai 导入 OpenAIChatClient # 从文件加载提示 - 切勿将提示嵌入为内联字符串提示 = Path("提示/assistant.md").read_text(encoding="utf-8") 客户端 = OpenAIChatClient( 型号=“gpt-5.1”， api_key=os.getenv("FOUNDRY_API_KEY"), 端点=os.getenv("FOUNDRY_ENDPOINT") ）代理={ "name": "助理", "instructions":prompt,#从prompts/assistant.md加载 "tools": [] # 根据需要添加工具 } 响应=等待客户端.聊天（ messages=[{"角色": "用户", "内容": "你好"}], 代理人=代理人） ### 多代理编排从 pathlib 导入路径从 agent_framework.workflows 导入 SequentialWorkflow # 每个代理从专用文件加载其提示研究员={ "name": "研究员", "说明": Path("prompts/researcher.md").read_text(encoding="utf-8") } 作者={ “姓名”：“作家”， "说明": Path("prompts/writer.md").read_text(encoding="utf-8") } 工作流程 = 顺序工作流程（代理人=[研究员、作家], handoff_strategy =“on_completion” ） result =等待workflow.run(query="写关于AI代理的文章") **高级模式**：搜索 [github.com/microsoft/agent-framework]()： * 群聊、并发、条件、循环 * 人在环、反射、扇出/扇入 * MCP、多式联运、自定义执行程序 ** ** ## 核心规则 ### 提示和模板文件管理 > **规则**：切勿将提示或输出模板作为内联字符串嵌入代码中。始终将它们存储为单独的文件。 **为什么**：提示是内容，而不是代码。将它们分开可以： * 版本控制差异准确显示提示中发生的更改 * 非开发人员编辑（PM、提示工程师），无需接触代码 * A/B 测试不同的提示，无需更改代码 * 跨代理、语言和测试工具重用 * 清晰的关注点分离（逻辑与内容） **目录约定**：项目/ 提示/#所有系统/代理提示 Assistant.md # 每个代理角色一个文件研究员.md 作家.md 审稿人.md templates/ # 代理使用的输出模板 report-template.md # 结构化输出模板电子邮件模板.md 摘要模板.md 配置/ models.yaml # 模型配置 **加载模式**：从 pathlib 导入路径 # 加载提示提示 = Path("提示/assistant.md").read_text(encoding="utf-8") # 加载输出模板并注入到提示符中模板 = Path("templates/report-template.md").read_text(encoding="utf-8") Prompt_with_template = f"{提示}\n\n## 输出格式\n{模板}" **规则**： * 必须将所有系统提示存储在 `prompts/` 目录中作为 `.md` 或 `.txt` 文件 * 必须将输出格式模板存储在 `templates/` 目录中 * 不得直接在代码中嵌入超过一句话的提示文本 * 应使用 Markdown 格式进行提示（可读，支持结构） * 应在代理角色之后命名文件：`prompts/{agent-name}.md` * 应在每个提示文件中包含简短的注释标题（用途、版本、模型目标） * 可以使用模板变量（`{variable}`）来在运行时注入动态内容 ### 发展 [通过] **做**： * 在编码之前规划代理架构（研究 -> 设计 -> 实施） * 使用Microsoft Foundry模型进行生产 * 从第一天起就实施跟踪 * 部署前使用评估数据集进行测试 * 使用结构化输出来实现可靠的代理响应 * 实现错误处理和重试逻辑 * 对您的代理进行版本控制并跟踪更改 * **将所有提示作为单独的文件存储在`prompts/`目录中** * **将输出模板存储为`templates/`目录中的单独文件** [失败] **不要**： * 硬编码 API 密钥或端点 * 在代码中嵌入提示或输出模板作为多行字符串 * 跳过跟踪设置（对于调试至关重要） * 无需评估即可部署 * 在生产中使用 GitHub 模型（免费套餐有限制） * 忽略令牌限制和上下文窗口 * 将代理逻辑与业务逻辑混合 ### 安全 * 将凭据存储在环境变量或Azure Key Vault中 * 验证所有工具输入和输出 * 对代理API实施速率限制 * 记录代理操作以进行审计跟踪 * 对 Foundry 资源使用基于角色的访问控制 (RBAC) * 查看 OWASP 人工智能 10 强：[owasp.org/AI-Security-and-Privacy-Guide]() ### 性能 * 适当时缓存模型响应 * 对多个请求使用批处理 * 监控代币使用和成本 * 实现超时处理 * 使用async/await进行I/O操作 * 考虑模型大小与延迟的权衡 ### 监控 * 跟踪关键指标：延迟、成功率、代币使用、成本 * 设置故障和异常警报 * 使用带有上下文的结构化日志记录 * 与 Azure Monitor/Application Insights 集成 * 定期审查跟踪以获得优化机会 ** ** ## 生产清单 **发展** * 代理架构记录 * 选择并部署模型 * 工具/插件的实施和测试 * 错误处理重试 * 配置结构化输出 * 没有硬编码的秘密 * 所有提示都作为单独的文件存储在“prompts/”中（不在代码中内联） * 所有输出模板存储在 `templates/` 中（不是内联在代码中） **模型变更管理（强制）** * 明确固定的模型版本（例如“gpt-5.1-2026-01-15”） * 通过环境变量配置模型版本 * 为当前模型保存评估基线 * 在任何模型切换之前运行 A/B 评估 * 模型更改后验证结构化输出模式 * 模型更改后验证工具/函数调用的准确性 * 模型变更记录在变更日志中，并附有评估结果 * 为漂移检测配置的每周评估监控 * 为分数从基线下降 > 10% 设置警报阈值 **模型变更测试自动化（强制）** * 代理设计为与模型无关（模型通过配置注入） * `config/models.yaml` 定义带有阈值的模型测试矩阵 * 针对 2 个模型进行了测试（主要 + 来自不同提供商的后备模型） * CI/CD 中的多模型比较管道（每周+模型配置更改） * 部署受阈值检查限制（CI 在回归时失败） *指定并记录经过验证的后备模型 * 每次运行生成的比较报告（JSON + 人类可读） * 成本和延迟评估器与质量指标一起包含在内 **可观察性** * 启用 OpenTelemetry 跟踪 * 已测试跟踪查看器 * 实现结构化日志记录 * 配置指标收集 **评估** * 创建评估数据集 * 定义评估器（内置+自定义） * 评估运行通过 * 结果符合质量阈值 * 多型号比较运行（测试了2+型号） * 后备模型经过验证并记录 * 保存模型比较基线 **安全与合规性** * Key Vault/env vars 中的凭证 * 实现输入验证 * RBAC配置 * 启用审核日志记录 * OWASP AI Top 10 回顾 **运营** * 实施健康检查 * 配置速率限制 * 监控警报设置 * 定义部署策略 * 记录回滚计划 *启用成本监控 ** ** ## 反模式 * **内联提示字符串** ：将提示作为多行字符串嵌入代码中 -> 作为单独的文件存储在 `prompts/` 目录中 * **未固定的模型版本** ：使用不带日期后缀的 `gpt-4o` -> 显式固定（例如 `gpt-5.1-2026-01-15`） * **部署前不进行评估**：运输代理无需运行评估数据集 -> 根据质量阈值进行部署 * **整体代理**：一个代理处理所有域和任务 -> 分成具有明确交接的专门代理 * **忽略令牌成本**：不监控每个请求的令牌使用情况 -> 跟踪每个组件的令牌并设置预算 * **缺少错误恢复**：LLM 失败时不重试或回退 -> 使用退避和回退模型实施重试 * **跳过跟踪设置**：在没有可观察性的情况下进行部署 -> 从第一天开始启用 OpenTelemetry 跟踪 ** ** ## 资源 **官方文档**： * 代理框架：[github.com/microsoft/agent-framework]() * Microsoft Foundry：[ai.azure.com]() * Azure AI 项目 SDK：[learn.microsoft.com/python/api/overview/azure/ai-projects]() * OpenTelemetry：[opentelemetry.io]() **人工智能工具包**： * 模型目录：`Ctrl+Shift+P` -> `AI 工具包：模型目录` * 跟踪查看器：`Ctrl+Shift+P` -> `AI Toolkit：打开跟踪查看器` * Playground：`Ctrl+Shift+P` -> `AI 工具包：模型 Playground` **安全**： * OWASP 人工智能安全：[owasp.org/AI-Security-and-Privacy-Guide]() * Azure 安全最佳实践：[learn.microsoft.com/azure/security]() ** ** **相关**：[AGENTS.md]() 用于代理行为指南 - [Skills.md]() 用于一般生产实践 **最后更新**：2026 年 1 月 17 日 ## 脚本脚本 |目的|用途 ---|---|--- [`scaffold-agent.py`]() |具有跟踪和评估功能的 Scaffold AI 代理项目 (Python/.NET) | `python 脚本/scaffold-agent.py --name my-agent [--pattern multi-agent] [--with-eval]` [`validate-agent-checklist.ps1`]() |根据生产清单验证代理项目 | `./scripts/validate-agent-checklist.ps1 [-Path ./my-agent] [-Strict]` [`check-model-drift.ps1`]() |验证模型固定、数据漂移信号并判断 LLM 准备情况 | `./scripts/check-model-drift.ps1 [-Path ./my-agent] [-Strict]` [`run-model-comparison.py`]() |针对多个模型运行评估套件并生成比较报告 | `python 脚本/run-model-comparison.py --config config/models.yaml --数据集评估/core.jsonl` ## 故障排除问题 |解决方案 ---|--- 找不到型号 |在 Foundry 门户中验证模型部署并检查端点 URL 追踪未出现 |确保在创建代理之前调用 AIInferenceInstrumentor().instrument() 代理无限循环 |设置 max_turns 限制并添加终止条件 ## 参考文献 * [追踪与评估]() * [多模型模式]() * [模型漂移和判断模式]() * [模型变更测试自动化]()

人工智能代理开发

包含技能