{ "canonical_name": "microsoft/agent-framework", "compilation_id": "pack_1bf5edadfbda4198967e1da1ed6d5b32", "created_at": "2026-05-13T17:25:53.989256+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `pip install agent-framework` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "pip install agent-framework", "sandbox_container_image": "python:3.12-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "llm_execute_isolated_install", "sandbox_validation_id": "sbx_7c4f8e2533bc4785884a1d62cd26fc00" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_b607c9afe26f9d1b2c98bd578d5d3eb4", "canonical_name": "microsoft/agent-framework", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/microsoft/agent-framework", "slug": "agent-framework", "source_packet_id": "phit_0f2c356de845420c93118ec85b53fd7c", "source_validation_id": "dval_899444b38f6f433c876c520e7bed344e" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 local_cli的用户", "github_forks": 1697, "github_stars": 10385, "one_liner_en": "A framework for building, orchestrating and deploying AI agents and multi-agent workflows with support for Python and .NET.", "one_liner_zh": "A framework for building, orchestrating and deploying AI agents and multi-agent workflows with support for Python and .NET.", "primary_category": { "category_id": "software-development", "confidence": "high", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:deploy, git, cli" }, "target_user": "使用 local_cli 等宿主 AI 的用户", "title_en": "agent-framework", "title_zh": "agent-framework 能力包", "visible_tags": [ { "label_en": "Knowledge Retrieval", "label_zh": "知识检索", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-knowledge-retrieval", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Multi-agent Collaboration", "label_zh": "多 Agent 协作", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-multi-agent-collaboration", "type": "core_capability" }, { "label_en": "Checkpoint Resume", "label_zh": "断点恢复流程", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-checkpoint-resume", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_0f2c356de845420c93118ec85b53fd7c", "page_model": { "artifacts": { "artifact_slug": "agent-framework", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "pip install agent-framework", "label": "Python / pip · 官方安装入口", "source": "https://github.com/microsoft/agent-framework#readme", "verified": true } ], "display_tags": [ "知识检索", "知识库问答", "多 Agent 协作", "断点恢复流程", "评测体系" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 local_cli的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "A framework for building, orchestrating and deploying AI agents and multi-agent workflows with support for Python and .NET." }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "local_cli", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CONTENT events", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_d329260309954749a2b3b2a9e7135d56 | https://github.com/microsoft/agent-framework/issues/4923 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CON…", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x)", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_8f9f05dcb7564f34bdd5902dcea6be27 | https://github.com/microsoft/agent-framework/issues/5785 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x)", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_49875a7dd60f480a99718cfa30b12723 | https://github.com/microsoft/agent-framework/issues/5708 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression]", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_58594f7966b84d81924da21ad789effd | https://github.com/microsoft/agent-framework/issues/5707 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression]", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_644a3ed07d2d4bfd8188392b4af687c2 | https://github.com/microsoft/agent-framework/issues/5794 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Anthropic function limit fallback can return empty final response", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_b61b91ca16094a448f8c0eab5e2daaa1 | https://github.com/microsoft/agent-framework/issues/5769 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Anthropic function limit fallback can return empty final response", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Python: Add tutorial for building a custom chat client / LLM provider", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_959e1eeb912a469c89f68f7f12275690 | https://github.com/microsoft/agent-framework/issues/5505 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Python: Add tutorial for building a custom chat client / LLM provider", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：python-1.2.1", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_f22ed66ae1f44b28b893aa5cbe439c92 | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：python-1.2.1", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：.NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows CustomStatus 16 KB cap on multi-executor workflows with typed outputs", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_52da26ae3ace4acb9913ac780bfb6cd0 | https://github.com/microsoft/agent-framework/issues/5745 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：.NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows CustomStatus 16 KB cap on multi-executor workflows…", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Python: CosmosHistoryProvider Code interpreter tool calls are saved chunk by chunk", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_48aaa2f1026c4afd9e1a1da3a1a862a6 | https://github.com/microsoft/agent-framework/issues/5793 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Python: CosmosHistoryProvider Code interpreter tool calls are saved chunk by chunk", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：dotnet-1.5.0", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_2b3d3127c36f41798428b164b5444cbb | https://github.com/microsoft/agent-framework/releases/tag/dotnet-1.5.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：dotnet-1.5.0", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：python-1.2.2", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_fb88b6cd86e04e199a03cfcf8a97dde6 | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：python-1.2.2", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:974445592 | https://github.com/microsoft/agent-framework | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：dotnet-1.4.0", "category": "维护坑", "evidence": [ "community_evidence:github | cevd_e25f39a7081848689e086b1f98f92675 | https://github.com/microsoft/agent-framework/releases/tag/dotnet-1.4.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：dotnet-1.4.0", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:974445592 | https://github.com/microsoft/agent-framework | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 23 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CON…。", "title": "踩坑日志" }, "snapshot": { "contributors": 130, "forks": 1697, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 10385 }, "source_url": "https://github.com/microsoft/agent-framework", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "A framework for building, orchestrating and deploying AI agents and multi-agent workflows with support for Python and .NET.", "title": "agent-framework 能力包", "trial_prompt": "# agent-framework - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agent-framework 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：框架介绍。围绕“框架介绍”模拟一次用户任务，不展示安装或运行结果。\n2. architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. core-concepts：核心概念。围绕“核心概念”模拟一次用户任务，不展示安装或运行结果。\n4. agent-basics：Agent 基础。围绕“Agent 基础”模拟一次用户任务，不展示安装或运行结果。\n5. agent-providers：模型提供商集成。围绕“模型提供商集成”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“框架介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. core-concepts\n输入：用户提供的“核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. agent-basics\n输入：用户提供的“Agent 基础”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. agent-providers\n输入：用户提供的“模型提供商集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“框架介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / core-concepts：Step 3 必须围绕“核心概念”形成一个小中间产物，并等待用户确认。\n- Step 4 / agent-basics：Step 4 必须围绕“Agent 基础”形成一个小中间产物，并等待用户确认。\n- Step 5 / agent-providers：Step 5 必须围绕“模型提供商集成”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/microsoft/agent-framework\n- https://github.com/microsoft/agent-framework#readme\n- dotnet/.github/skills/build-and-test/SKILL.md\n- dotnet/.github/skills/project-structure/SKILL.md\n- dotnet/.github/skills/verify-dotnet-samples/SKILL.md\n- dotnet/.github/skills/verify-samples-tool/SKILL.md\n- dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/skills/unit-converter/SKILL.md\n- dotnet/samples/02-agents/AgentSkills/Agent_Step04_MixedSkills/skills/unit-converter/SKILL.md\n- python/.github/skills/python-code-quality/SKILL.md\n- python/.github/skills/python-development/SKILL.md\n- python/.github/skills/python-feature-lifecycle/SKILL.md\n- python/.github/skills/python-package-management/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agent-framework 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: .NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStre（https://github.com/microsoft/agent-framework/issues/4923）；github/github_issue: Python: OpenAI store=True can silently bypass external HistoryProvider p（https://github.com/microsoft/agent-framework/issues/5798）；github/github_issue: Bug: Agent responses lose structured JSON metadata in multi-agent orches（https://github.com/microsoft/agent-framework/issues/5785）；github/github_issue: .NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows Cus（https://github.com/microsoft/agent-framework/issues/5745）；github/github_issue: .NET: [Bug]: Regression - Tool Events not being emitted correctly to the（https://github.com/microsoft/agent-framework/issues/5794）；github/github_issue: Python: CosmosHistoryProvider Code interpreter tool calls are saved chun（https://github.com/microsoft/agent-framework/issues/5793）；github/github_issue: Anthropic function limit fallback can return empty final response（https://github.com/microsoft/agent-framework/issues/5769）；github/github_issue: .NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI（https://github.com/microsoft/agent-framework/issues/5707）；github/github_issue: Python: Add tutorial for building a custom chat client / LLM provider（https://github.com/microsoft/agent-framework/issues/5505）；github/github_issue: .NET: OpenAI-compatible extra body field thinking is not forwarded when （https://github.com/microsoft/agent-framework/issues/5708）；github/github_release: dotnet-1.5.0（https://github.com/microsoft/agent-framework/releases/tag/dotnet-1.5.0）；github/github_release: python-1.3.0（https://github.com/microsoft/agent-framework/releases/tag/python-1.3.0）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": ".NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStre", "url": "https://github.com/microsoft/agent-framework/issues/4923" }, { "kind": "github_issue", "source": "github", "title": "Python: OpenAI store=True can silently bypass external HistoryProvider p", "url": "https://github.com/microsoft/agent-framework/issues/5798" }, { "kind": "github_issue", "source": "github", "title": "Bug: Agent responses lose structured JSON metadata in multi-agent orches", "url": "https://github.com/microsoft/agent-framework/issues/5785" }, { "kind": "github_issue", "source": "github", "title": ".NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows Cus", "url": "https://github.com/microsoft/agent-framework/issues/5745" }, { "kind": "github_issue", "source": "github", "title": ".NET: [Bug]: Regression - Tool Events not being emitted correctly to the", "url": "https://github.com/microsoft/agent-framework/issues/5794" }, { "kind": "github_issue", "source": "github", "title": "Python: CosmosHistoryProvider Code interpreter tool calls are saved chun", "url": "https://github.com/microsoft/agent-framework/issues/5793" }, { "kind": "github_issue", "source": "github", "title": "Anthropic function limit fallback can return empty final response", "url": "https://github.com/microsoft/agent-framework/issues/5769" }, { "kind": "github_issue", "source": "github", "title": ".NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI", "url": "https://github.com/microsoft/agent-framework/issues/5707" }, { "kind": "github_issue", "source": "github", "title": "Python: Add tutorial for building a custom chat client / LLM provider", "url": "https://github.com/microsoft/agent-framework/issues/5505" }, { "kind": "github_issue", "source": "github", "title": ".NET: OpenAI-compatible extra body field thinking is not forwarded when ", "url": "https://github.com/microsoft/agent-framework/issues/5708" }, { "kind": "github_release", "source": "github", "title": "dotnet-1.5.0", "url": "https://github.com/microsoft/agent-framework/releases/tag/dotnet-1.5.0" }, { "kind": "github_release", "source": "github", "title": "python-1.3.0", "url": "https://github.com/microsoft/agent-framework/releases/tag/python-1.3.0" } ], "status": "已收录 12 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "A framework for building, orchestrating and deploying AI agents and multi-agent workflows with support for Python and .NET.", "effort": "安装已验证", "forks": 1697, "icon": "code", "name": "agent-framework 能力包", "risk": "可发布", "slug": "agent-framework", "stars": 10385, "tags": [ "知识检索", "知识库问答", "多 Agent 协作", "断点恢复流程", "评测体系" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/microsoft/agent-framework 项目说明书\n\n生成时间：2026-05-13 17:14:16 UTC\n\n## 目录\n\n- [框架介绍](#introduction)\n- [安装与配置](#installation)\n- [系统架构](#architecture)\n- [核心概念](#core-concepts)\n- [Agent 基础](#agent-basics)\n- [模型提供商集成](#agent-providers)\n- [工具与技能系统](#agent-tools)\n- [工作流系统概述](#workflow-overview)\n- [工作流编排模式](#workflow-patterns)\n- [检查点与恢复机制](#checkpoint-recovery)\n\n\n\n## 框架介绍\n\n### 相关页面\n\n相关主题：[安装与配置](#installation), [系统架构](#architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/microsoft/agent-framework/blob/main/README.md)\n- [python/AGENTS.md](https://github.com/microsoft/agent-framework/blob/main/python/AGENTS.md)\n- [dotnet/AGENTS.md](https://github.com/microsoft/agent-framework/blob/main/dotnet/AGENTS.md)\n- [dotnet/src/Shared/Foundry/Agents/README.md](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Shared/Foundry/Agents/README.md)\n- [python/samples/01-get-started/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md)\n- [python/packages/declarative/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/declarative/README.md)\n
\n\n# 框架介绍\n\nMicrosoft Agent Framework（微软智能体框架）是一个跨平台的智能体（Agent）开发框架，旨在帮助开发者快速构建、部署和管理 AI 智能体应用。该框架提供了丰富的工具、运行时和 SDK，支持多种编程语言和部署场景。\n\n## 框架概述\n\nAgent Framework 由微软开发维护，是一个现代化的 AI 智能体开发平台。框架的核心设计理念是提供一个统一且灵活的架构，使开发者能够轻松创建具有对话能力、工具调用能力、工作流编排能力的高级 AI 应用。\n\n该框架支持两种主要的开发语言生态：\n\n| 编程语言 | SDK 包名 | 定位 |\n|---------|---------|------|\n| Python | `agent-framework` | 主要面向 Python 开发者，提供完整的智能体开发能力 |\n| .NET/C# | Microsoft.Agents.AI | 面向 .NET 生态，提供企业级智能体支持 |\n\n资料来源：[README.md:1]()\n\n## 核心组件架构\n\n### Python SDK 组件\n\nPython SDK 是框架的主要实现之一，提供了从基础智能体创建到复杂工作流编排的完整能力。\n\n```\ngraph TD\n A[用户应用] --> B[agent-framework SDK]\n B --> C[Agent 智能体]\n B --> D[Workflow 工作流]\n B --> E[Tools 工具]\n C --> F[ChatClient 聊天客户端]\n D --> G[Graph Workflow 图工作流]\n D --> H[Functional Workflow 函数式工作流]\n```\n\nPython SDK 的核心包结构：\n\n- `agent-framework` - 核心包，包含智能体、工具和工作流的基础类\n- `agent-framework-declarative` - 声明式包，支持通过 YAML 规范构建智能体\n\n资料来源：[python/AGENTS.md:1]()\n\n### .NET SDK 组件\n\n.NET SDK 提供企业级的智能体开发支持，集成了多种 AI 服务和托管选项。\n\n| 组件命名空间 | 功能说明 |\n|------------|---------|\n| `Microsoft.Agents.AI` | 核心 AI 抽象和接口定义 |\n| `Microsoft.Agents.AI.Hosting.OpenAI` | OpenAI 托管集成 |\n| `Microsoft.Agents.AI.GitHub.Copilot` | GitHub Copilot 客户端集成 |\n| `Microsoft.Agents.AI.AzureAI.Persistent` | Azure AI 持久化智能体客户端 |\n| `Microsoft.Agents.AI.Skills` | 智能体技能（Skills）管理系统 |\n\n资料来源：[dotnet/AGENTS.md:1]()\n\n## 智能体（Agent）体系\n\n智能体是框架的核心抽象单元，代表一个能够理解自然语言、执行工具调用、维护对话状态的 AI 实例。\n\n### ChatClientAgent\n\n`ChatClientAgent` 是框架中最基础的智能体类型，它通过 `IChatClient` 接口与底层聊天服务交互。这种设计实现了智能体逻辑与底层 AI 服务的解耦。\n\n```csharp\n// 创建一个基础智能体的核心参数\npublic class ChatClientAgent\n{\n string? Instructions { get; } // 系统指令\n string? Name { get; } // 智能体名称\n string? Description { get; } // 智能体描述\n IList? Tools { get; } // 可用工具列表\n ILoggerFactory? LoggerFactory { get; } // 日志工厂\n IServiceProvider? Services { get; } // 依赖服务\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs:1]()\n\n### 智能体创建流程\n\n```\ngraph LR\n A[配置模型] --> B[定义工具]\n B --> C[设置指令]\n C --> D[创建 Agent 实例]\n D --> E[建立会话]\n E --> F[发送消息/接收响应]\n```\n\n### AgentId 标识模型\n\n每个智能体都有一个唯一的标识符，用于在分布式系统中追踪和管理智能体实例。\n\n```csharp\npublic sealed class AgentId\n{\n public AgentIdType Type { get; init; } // 标识类型\n public string Name { get; init; } // 智能体名称\n public string Version { get; init; } // 版本号\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs:1]()\n\n## 工具系统（Tools）\n\n工具系统使智能体能够执行外部操作，扩展了纯对话的能力边界。\n\n### 工具定义结构\n\n| 属性 | 类型 | 说明 |\n|-----|------|-----|\n| Name | string | 工具名称，用于标识和调用 |\n| Description | string | 工具功能描述，供 AI 理解用途 |\n| Parameters | Schema | 参数模式定义 |\n| Handler | Delegate | 实际执行逻辑 |\n\n框架支持两种工具定义方式：\n\n1. **代码定义工具** - 通过装饰器或接口直接在代码中实现\n2. **文件定义工具** - 通过 YAML/JSON 配置文件声明\n\n资料来源：[python/samples/01-get-started/README.md:1]()\n\n### 工具资源管理\n\n智能体的工具可以关联资源（Resources），这些资源在运行时被注入到工具执行上下文中。\n\n```csharp\npublic abstract class AgentSkill\n{\n // 技能关联的资源列表\n public virtual IReadOnlyList? Resources => null;\n \n // 技能关联的脚本列表\n public virtual IReadOnlyList? Scripts => null;\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs:1]()\n\n## 技能系统（Skills）\n\n技能系统是框架的高级特性，允许开发者将领域知识、操作流程和资源打包成可复用的模块。\n\n### AgentSkillsProvider\n\n`AgentSkillsProvider` 是技能系统的核心组件，它负责：\n\n- 加载和组织技能定义\n- 将技能转换为 AI 可理解的提示词\n- 管理技能相关的工具和脚本执行\n- 提供上下文感知的技能推荐\n\n```csharp\npublic sealed partial class AgentSkillsProvider : AIContextProvider\n{\n // 技能列表占位符\n private const string SkillsPlaceholder = \"{skills}\";\n \n // 脚本指令占位符\n private const string ScriptInstructionsPlaceholder = \"{script_instructions}\";\n \n // 资源指令占位符\n private const string ResourceInstructionsPlaceholder = \"{resource_instructions}\";\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs:1]()\n\n### 技能指令模板\n\n框架使用预定义的提示词模板来组织技能信息：\n\n```\n你有权访问包含领域特定知识和能力的技能。\n每个技能为特定任务提供专业指导、参考文档和资源。\n\n\n{skills}\n\n\n当任务与某个技能的领域匹配时，按以下步骤操作：\n- 使用 `load_skill` 加载技能指令\n- 遵循提供的指导\n{resource_instructions}\n{script_instructions}\n只加载所需内容，按需加载。\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs:1]()\n\n### 技能类型\n\n| 技能类型 | 说明 | 使用场景 |\n|---------|------|---------|\n| 文件技能（File-Based） | 基于 SKILL.md 文件定义 | 知识型技能、内容管理 |\n| 代码技能（Code-Defined） | 通过代码接口实现 | 动态逻辑、自定义行为 |\n| 混合技能（Mixed） | 结合文件和代码 | 复杂业务逻辑 |\n\n资料来源：[python/packages/declarative/README.md:1]()\n\n### 技能配置选项\n\n```csharp\npublic sealed class AgentSkillsProviderOptions\n{\n // 自定义技能提示模板\n public string? SkillsInstructionPrompt { get; set; }\n \n // 脚本执行是否需要审批\n public bool ScriptApproval { get; set; }\n \n // 是否禁用工具和指令缓存\n public bool DisableCaching { get; set; }\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProviderOptions.cs:1]()\n\n## 工作流系统（Workflows）\n\n框架提供了两种工作流编写范式，满足不同复杂度和可维护性需求。\n\n### 函数式工作流\n\n函数式工作流将工作流定义为普通的异步函数，简洁直观。\n\n```python\n# 简单示例：异步函数即工作流\nasync def my_workflow(input_data):\n result = await agent.run(input_data)\n return process_result(result)\n```\n\n资料来源：[python/samples/01-get-started/README.md:1]()\n\n### 图工作流\n\n图工作流通过有向图组织多个执行节点，支持复杂的条件分支和并行执行。\n\n```\ngraph TD\n A[开始节点] --> B[执行器1]\n A --> C[执行器2]\n B --> D[决策节点]\n C --> D\n D -->|条件A| E[执行器3]\n D -->|条件B| F[执行器4]\n E --> G[结束节点]\n F --> G\n```\n\n图工作流的核心概念：\n\n| 概念 | 说明 |\n|-----|------|\n| 节点（Node） | 工作流中的处理单元 |\n| 边（Edge） | 节点间的数据流向和控制关系 |\n| 输入/输出 | 数据的注入和产出 |\n\n资料来源：[python/samples/01-get-started/README.md:1]()\n\n## 会话管理（Session）\n\n`AgentSession` 管理智能体的对话状态，支持多轮对话和上下文维护。\n\n```python\n# 建立会话\nsession = AgentSession(\n agent=my_agent,\n thread_id=\"unique-thread-id\"\n)\n\n# 多轮对话\nasync with session:\n response1 = await session.run(\"你好\")\n response2 = await session.run(\"帮我查询天气\")\n response3 = await session.run(\"谢谢\") # 上下文保持\n```\n\n会话管理的关键特性：\n\n- **线程隔离** - 每个会话有独立的对话历史\n- **状态持久化** - 支持跨请求的状态恢复\n- **上下文传递** - 自动维护对话上下文\n\n资料来源：[python/samples/01-get-started/README.md:1]()\n\n## 上下文提供者（Context Provider）\n\n`ContextProvider` 允许开发者自定义上下文注入逻辑，为智能体提供动态的补充信息。\n\n```python\nclass MyContextProvider(ContextProvider):\n async def provide_context(self, session, request):\n # 从外部获取相关上下文\n user_profile = await get_user_profile(session.user_id)\n return {\"user\": user_profile}\n```\n\n上下文提供者的工作流程：\n\n```\ngraph LR\n A[请求进入] --> B[ContextProvider.provide_context]\n B --> C[聚合上下文数据]\n C --> D[注入系统提示]\n D --> E[发送给 AI]\n E --> F[处理响应]\n F --> G[返回结果]\n```\n\n资料来源：[python/samples/01-get-started/README.md:1]()\n\n## Azure AI 集成\n\n框架通过 `PersistentAgentsClient` 提供与 Azure AI Foundry Agents 服务的深度集成。\n\n```csharp\n// 已废弃，请使用最新的 Foundry Agents 服务\n[Obsolete(\"Please use the latest Foundry Agents service via the Microsoft.Agents.AI.AzureAI package.\")]\npublic static async Task CreateAIAgentAsync(\n this PersistentAgentsClient persistentAgentsClient,\n string model,\n string? name = null,\n string? description = null,\n string? instructions = null,\n IEnumerable? tools = null,\n ToolResources? toolResources = null,\n float? temperature = null,\n float? topP = null,\n string? responseFormat = null,\n IDictionary? metadata = null,\n IChatClientFactory? clientFactory = null,\n IServiceProvider? services = null,\n CancellationToken cancellationToken = default)\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.AzureAI.Persistent/PersistentAgentsClientExtensions.cs:1]()\n\n## GitHub Copilot 集成\n\n框架支持将 GitHub Copilot 作为 AI 后端：\n\n```csharp\npublic static AIAgent AsAIAgent(\n this CopilotClient client,\n bool ownsClient = false,\n string? id = null,\n string? name = null,\n string? description = null,\n IList? tools = null,\n string? instructions = null)\n{\n Throw.IfNull(client);\n return new GitHubCopilotAgent(client, ownsClient, id, name, description, tools, instructions);\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/CopilotClientExtensions.cs:1]()\n\n## 开发工具（DevUI）\n\nDevUI 是框架提供的示例应用，用于快速入门和探索智能体功能。\n\n```\ngraph TD\n A[DevUI 应用] --> B[连接 Agent Framework 后端]\n B --> C[示例画廊 Sample Gallery]\n B --> D[设置面板 Settings]\n C --> E[浏览示例]\n C --> F[下载示例]\n D --> G[配置端点]\n D --> H[查看能力]\n```\n\nDevUI 特性：\n\n| 功能 | 说明 |\n|-----|------|\n| 示例画廊 | 浏览和下载预置的智能体示例 |\n| 设置管理 | 配置连接参数和能力选项 |\n| 版本信息 | 显示框架和运行时版本 |\n| 能力展示 | 展示后端支持的各项能力 |\n\n资料来源：[python/packages/devui/frontend/src/components/features/gallery/gallery-view.tsx:1]()\n\n## 部署模式\n\n框架支持多种部署场景：\n\n### 客户端托管\n\n智能体作为客户端应用的一部分运行，轻量级部署。\n\n```bash\n# Python 示例\ncd python\nuv run samples/08_host_your_agent.py\n```\n\n### 服务器托管\n\n智能体部署为独立服务，通过 API 暴露功能。\n\n### 云原生部署\n\n结合 Azure Container Apps、Azure Functions 或 Aspire 实现弹性扩缩容。\n\n```\ngraph TD\n A[客户端] -->|HTTP/WebSocket| B[API 网关]\n B --> C[Agent Service]\n C --> D[Foundry Agents API]\n D --> E[AI Model]\n C --> F[Skill Store]\n C --> G[Context Store]\n```\n\n资料来源：[dotnet/src/Aspire.Hosting.AgentFramework.DevUI/AgentEntityInfo.cs:1]()\n\n## 快速开始指南\n\n### Python 环境准备\n\n```bash\n# 安装核心包\npip install agent-framework\n\n# 设置环境变量\nexport FOUNDRY_PROJECT_ENDPOINT=\"https://your-project-endpoint\"\nexport FOUNDRY_MODEL=\"gpt-4o\" # 可选，默认 gpt-4o\n```\n\n### 创建第一个智能体\n\n```python\nfrom agent_framework import Agent\n\n# 创建智能体\nagent = Agent(\n name=\"我的助手\",\n instructions=\"你是一个有帮助的助手。\",\n model=\"gpt-4o\"\n)\n\n# 运行智能体\nresult = await agent.run(\"你好，请介绍一下你自己。\")\nprint(result)\n```\n\n### 添加工具\n\n```python\nfrom agent_framework import Agent, tool\n\n@tool\ndef get_weather(city: str) -> str:\n \"\"\"获取城市天气信息\"\"\"\n # 实现天气查询逻辑\n return f\"{city}今天天气晴朗\"\n\nagent = Agent(\n name=\"天气助手\",\n instructions=\"你是一个天气助手。\",\n tools=[get_weather]\n)\n```\n\n资料来源：[python/samples/01-get-started/README.md:1]()\n\n## 相关资源\n\n- [官方文档](https://github.com/microsoft/agent-framework)\n- [Agent Skills 规范](https://agentskills.io/)\n- [Python SDK 仓库](https://github.com/microsoft/agent-framework/tree/main/python)\n- [.NET SDK 仓库](https://github.com/microsoft/agent-framework/tree/main/dotnet)\n- [示例代码库](https://github.com/microsoft/agent-framework/tree/main/python/samples)\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[框架介绍](#introduction), [Agent 基础](#agent-basics)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/pyproject.toml](https://github.com/microsoft/agent-framework/blob/main/python/pyproject.toml)\n- [python/DEV_SETUP.md](https://github.com/microsoft/agent-framework/blob/main/python/DEV_SETUP.md)\n- [dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj)\n- [python/samples/01-get-started/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md)\n- [dotnet/src/Shared/Foundry/Agents/README.md](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Shared/Foundry/Agents/README.md)\n- [python/packages/devui/frontend/src/components/layout/settings-modal.tsx](https://github.com/microsoft/agent-framework/blob/main/python/packages/devui/frontend/src/components/layout/settings-modal.tsx)\n
\n\n# 安装与配置\n\n## 概述\n\nAgent Framework 是微软开发的一个跨平台智能代理框架，支持 Python 和 .NET 两种运行时环境。框架提供了完整的代理（Agent）开发、部署和管理能力，涵盖从基础代理创建到复杂工作流编排的完整功能链。\n\n本页面详细介绍框架的安装方法、配置选项以及开发环境搭建指南。\n\n---\n\n## 系统要求\n\n### Python 环境要求\n\n| 组件 | 最低版本 | 推荐版本 |\n|------|----------|----------|\n| Python | 3.10 | 3.11+ |\n| pip | 21.0 | 最新版本 |\n\n### .NET 环境要求\n\n| 组件 | 最低版本 | 推荐版本 |\n|------|----------|----------|\n| .NET SDK | .NET 8 | .NET 8 LTS |\n| Visual Studio / VS Code | 最新 | 最新 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj)\n\n---\n\n## Python 安装\n\n### 方式一：pip 安装（生产环境）\n\n使用 pip 直接安装稳定版本的 agent-framework 包：\n\n```bash\npip install agent-framework\n```\n\n资料来源：[python/samples/01-get-started/README.md:14](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md#L14)\n\n### 方式二：源码安装（开发环境）\n\n```bash\ncd python\npip install -e .\n```\n\n-e 参数表示可编辑模式安装，适合需要修改源码或参与框架开发的场景。\n\n### 依赖配置\n\nPython 版本的依赖通过 pyproject.toml 管理，主要依赖包括：\n\n| 依赖包 | 用途 |\n|--------|------|\n| python-dotenv | 环境变量管理 |\n| httpx | HTTP 客户端 |\n| openai | OpenAI API 兼容接口 |\n\n资料来源：[python/pyproject.toml](https://github.com/microsoft/agent-framework/blob/main/python/pyproject.toml)\n\n---\n\n## .NET 安装\n\n### NuGet 包引用\n\n在 .NET 项目中，通过添加包引用来使用 Agent Framework：\n\n```xml\n\n \n \n\n```\n\n### 共享模块注入\n\nAgent Framework 提供了多个可复用的共享模块，通过 .csproj 属性控制是否启用：\n\n```xml\n\n true\n true\n true\n true\n\n```\n\n资料来源：[dotnet/src/Shared/Foundry/Agents/README.md:7-11](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Shared/Foundry/Agents/README.md#L7-L11)\n\n### 共享模块说明\n\n| 模块 | 功能 |\n|------|------|\n| FoundryAgents | Foundry 代理创建和使用的共享模式 |\n| Samples | 高效的示例项目工具类 |\n| Redaction | 日志数据脱敏工具 |\n| Throw | 异常处理工具 |\n\n| 模块 | 功能 |\n|------|------|\n| TrimAttributes | AOT 裁剪优化支持 |\n| ExperimentalAttribute | 实验性功能标记 |\n| DiagnosticAttributes | 诊断属性支持 |\n| CallerAttributes | 调用者信息特性 |\n\n资料来源：[dotnet/src/Shared/Redaction/README.md:15-25](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Shared/Redaction/README.md#L15-L25)\n\n---\n\n## 环境变量配置\n\n### Python 环境变量\n\n创建 `.env` 文件或在终端中设置以下环境变量：\n\n```bash\nexport FOUNDRY_PROJECT_ENDPOINT=\"https://your-project-endpoint\"\nexport FOUNDRY_MODEL=\"gpt-4o\"\n```\n\n| 变量名 | 必填 | 默认值 | 说明 |\n|--------|------|--------|------|\n| FOUNDRY_PROJECT_ENDPOINT | 是 | - | Azure Foundry 项目端点 |\n| FOUNDRY_MODEL | 否 | gpt-4o | 使用的模型标识符 |\n\n资料来源：[python/samples/01-get-started/README.md:18-21](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md#L18-L21)\n\n### .NET 环境变量\n\n在 appsettings.json 中配置：\n\n```json\n{\n \"AzureAI\": {\n \"Endpoint\": \"https://your-resource.azurewebsites.net\",\n \"AuthenticationType\": \"ApiKey\"\n }\n}\n```\n\n---\n\n## 开发环境搭建\n\n### 快速开始流程\n\n```mermaid\ngraph TD\n A[安装依赖] --> B[配置环境变量]\n B --> C[克隆示例代码]\n C --> D[运行第一个代理]\n D --> E[添加自定义工具]\n E --> F[构建工作流]\n```\n\n### Python 开发环境设置\n\n1. **克隆仓库**\n ```bash\n git clone https://github.com/microsoft/agent-framework.git\n cd agent-framework\n ```\n\n2. **创建虚拟环境（推荐）**\n ```bash\n python -m venv venv\n source venv/bin/activate # Linux/macOS\n # 或\n .\\venv\\Scripts\\activate # Windows\n ```\n\n3. **安装开发依赖**\n ```bash\n cd python\n pip install -e \".[dev]\"\n ```\n\n4. **验证安装**\n ```python\n import agent_framework\n print(agent_framework.__version__)\n ```\n\n资料来源：[python/DEV_SETUP.md](https://github.com/microsoft/agent-framework/blob/main/python/DEV_SETUP.md)\n\n### .NET 开发环境设置\n\n1. **克隆仓库**\n ```bash\n git clone https://github.com/microsoft/agent-framework.git\n ```\n\n2. **还原包**\n ```bash\n cd dotnet\n dotnet restore\n ```\n\n3. **构建项目**\n ```bash\n dotnet build\n ```\n\n---\n\n## DevUI 配置\n\nDevUI 是框架提供的示例应用，用于快速上手 Agent Framework 开发。\n\n### 部署模式\n\nDevUI 支持多种运行模式：\n\n| 模式 | 说明 | 使用场景 |\n|------|------|----------|\n| default | 默认本地模式 | 开发调试 |\n| connected | 连接后端服务 | 完整功能测试 |\n| embedded | 内嵌模式 | 集成到现有应用 |\n\n资料来源：[python/packages/devui/frontend/src/components/layout/settings-modal.tsx:35-38](https://github.com/microsoft/agent-framework/blob/main/python/packages/devui/frontend/src/components/layout/settings-modal.tsx#L35-L38)\n\n### DevUI 版本信息\n\nDevUI 界面可显示以下系统信息：\n\n- 版本号 (Version)\n- 运行时类型 (Runtime)\n- UI 模式 (UI Mode)\n- 能力支持 (Capabilities)\n\n```typescript\ninterface ServerCapabilities {\n instrumentation?: boolean;\n // 其他能力字段...\n}\n```\n\n---\n\n## Docker 部署配置\n\n### 快速部署步骤\n\n1. **保存部署文件到项目目录**\n\n2. **构建镜像**\n ```bash\n docker build -t my-agent .\n ```\n\n3. **启动容器**\n ```bash\n docker-compose up\n ```\n\n### 生产环境注意事项\n\n| 注意事项 | 说明 |\n|----------|------|\n| 状态管理 | 内存状态在容器重启后会丢失 |\n| 认证 | 需要添加反向代理（nginx/Caddy）并配置认证 |\n| 密钥管理 | 使用 Azure Key Vault 管理敏感信息 |\n| 扩展性 | 单实例模式，不支持水平扩展 |\n\n资料来源：[python/packages/devui/frontend/src/components/layout/deployment-modal.tsx](https://github.com/microsoft/agent-framework/blob/main/python/packages/devui/frontend/src/components/layout/deployment-modal.tsx)\n\n---\n\n## 代理创建配置\n\n### Python 创建代理\n\n```python\nfrom agent_framework import Agent, tool\n\n@tool\ndef get_weather(city: str) -> str:\n \"\"\"获取城市天气信息\"\"\"\n return f\"{city}今天天气晴朗\"\n\nagent = Agent(\n name=\"weather-assistant\",\n instructions=\"你是一个天气助手\",\n model=\"gpt-4o\",\n tools=[get_weather]\n)\n```\n\n### .NET 创建代理\n\n```csharp\nusing Microsoft.Agents.AI;\n\n// 创建代理配置\nvar agentConfig = new AgentConfiguration\n{\n Name = \"my-agent\",\n Instructions = \"代理指令\",\n Model = \"gpt-4o\"\n};\n\n// 使用 ChatClientAgent\nvar agent = await persistentAgentsClient.CreateAIAgentAsync(\n model: \"gpt-4o\",\n name: \"my-agent\",\n instructions: \"代理指令\",\n tools: agentTools\n);\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.AzureAI.Persistent/PersistentAgentsClientExtensions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.AzureAI.Persistent/PersistentAgentsClientExtensions.cs)\n\n### 代理配置参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | string | 是 | 代理名称（kebab-case） |\n| instructions | string | 是 | 代理指令文本 |\n| description | string | 否 | 代理描述 |\n| model | string | 否 | 模型标识符 |\n| tools | IEnumerable | 否 | 可用工具列表 |\n| temperature | float | 否 | 温度参数（0.0-2.0） |\n| topP | float | 否 | Top-P 参数 |\n| responseFormat | object | 否 | 响应格式配置 |\n| metadata | dictionary | 否 | 自定义元数据 |\n\n资料来源：[python/samples/01-get-started/README.md:20-25](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md#L20-L25)\n\n---\n\n## 技能（Skill）配置\n\n### 技能定义\n\n代理技能支持通过前端资料（frontmatter）定义元数据：\n\n```python\nfrom agent_framework.skills import AgentInlineSkill\n\nskill = AgentInlineSkill(\n name=\"my-skill\",\n description=\"技能描述\",\n instructions=\"技能指令\",\n license=\"MIT\",\n compatibility=\"v1.0+\",\n allowedTools=\"tool1 tool2\",\n metadata={\"author\": \"developer\"}\n)\n```\n\n### 技能资源目录\n\n技能可以包含以下类型的资源目录：\n\n| 目录名 | 用途 |\n|--------|------|\n| references | 参考文档 |\n| assets | 静态资源 |\n| scripts | 脚本文件 |\n\n默认资源目录为 `references` 和 `assets`，可通过 `ResourceDirectories` 自定义配置。\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSourceOptions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSourceOptions.cs)\n\n---\n\n## 工作流配置\n\n### 功能式工作流\n\n```python\nfrom agent_framework import workflow, agent\n\n@workflow\nasync def my_workflow(input_data):\n result = await agent.invoke(input_data)\n return result\n```\n\n### 图工作流\n\n```mermaid\ngraph TD\n A[开始] --> B[代理节点1]\n B --> C{条件判断}\n C -->|成功| D[代理节点2]\n C -->|失败| E[错误处理]\n D --> F[结束]\n E --> F\n```\n\n资料来源：[python/samples/01-get-started/README.md:28-32](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md#L28-L32)\n\n---\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 包安装失败 | 检查 Python 版本是否满足要求（≥3.10） |\n| 环境变量未生效 | 确保重启终端或在新的 shell 会话中运行 |\n| Docker 构建失败 | 检查 Dockerfile 路径和上下文 |\n| 代理响应慢 | 检查网络连接和 API 限流设置 |\n\n### 验证安装\n\n```bash\n# Python 验证\npython -c \"import agent_framework; print('OK')\"\n\n# .NET 验证\ndotnet list package | grep Microsoft.Agents\n```\n\n---\n\n## 下一步\n\n安装配置完成后，建议按以下顺序学习框架：\n\n1. [创建第一个代理](samples/01-get-started/README.md)\n2. [添加自定义工具](samples/02_add_tools.py)\n3. [多轮对话实现](samples/03_multi_turn.py)\n4. [上下文管理](samples/04_memory.py)\n5. [功能式工作流](samples/05_functional_workflow_with_agents.py)\n6. [图工作流](samples/07_first_graph_workflow.py)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心概念](#core-concepts), [Agent 基础](#agent-basics)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/core/agent_framework/_agents.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py)\n- [python/packages/core/agent_framework/_workflows/_workflow.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_workflows/_workflow.py)\n- [dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs)\n- [dotnet/src/Microsoft.Agents.AI.Workflows/Workflow.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/Workflow.cs)\n- [python/samples/01-get-started/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md)\n- [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)\n- [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs)\n
\n\n# 系统架构\n\nMicrosoft Agent Framework 是一个用于构建 AI Agent 的跨平台框架，同时支持 Python 和 .NET 两种语言实现。本页面详细介绍该框架的整体架构设计、核心组件及其交互关系。\n\n## 1. 架构概览\n\nAgent Framework 采用分层架构设计，核心层负责 Agent 的生命周期管理和运行时调度，工作流层提供组合多个 Agent 的能力，外围层则包含工具系统、技能系统、会话管理等功能扩展。\n\n```mermaid\ngraph TB\n subgraph \"外围层\"\n Tools[\"工具系统
@tool 装饰器\"]\n Skills[\"技能系统
AgentSkill\"]\n Memory[\"会话记忆
AgentSession\"]\n end\n \n subgraph \"核心层\"\n Agent[\"Agent / AIAgent\"]\n Runtime[\"运行时调度器\"]\n end\n \n subgraph \"工作流层\"\n Workflow[\"工作流
Workflow\"]\n Functional[\"函数式工作流\"]\n Graph[\"图工作流\"]\n end\n \n subgraph \"通信层\"\n LLM[\"LLM 接口\"]\n Streaming[\"流式输出\"]\n end\n \n Tools --> Agent\n Skills --> Agent\n Memory --> Agent\n Agent --> Runtime\n Runtime --> LLM\n Runtime --> Streaming\n Workflow --> Agent\n Functional --> Agent\n Graph --> Workflow\n```\n\n框架的核心设计理念包括：\n\n- **声明式优先**：支持 YAML 配置文件定义 Agent 行为\n- **工具扩展**：通过 `@tool` 装饰器或 `ToolDefinition` 定义外部能力\n- **状态持久化**：AgentSession 支持多轮对话状态管理\n- **工作流编排**：支持函数式和图结构工作流组合\n\n## 2. 核心组件\n\n### 2.1 Agent 抽象\n\nAgent 是框架的核心抽象，代表一个具备 LLM 交互能力的智能体。在 Python 和 .NET 中均有对应实现。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | string | Agent 名称标识 |\n| description | string | Agent 功能描述 |\n| instructions | string | 系统指令/提示词 |\n| tools | List[Tool] | 可用工具集合 |\n| toolResources | dict | 工具资源映射 |\n\n**Python 实现**：`agent_framework._agents` 模块\n\n```python\n# Python Agent 示例结构 (来源：python/packages/core/agent_framework/_agents.py)\nclass Agent:\n def __init__(\n self,\n name: str,\n description: str | None = None,\n instructions: str | None = None,\n tools: list[Any] | None = None,\n # ... 其他参数\n ):\n self.name = name\n self.description = description\n self.instructions = instructions\n self._tools = tools or []\n```\n\n**NET 实现**：`Microsoft.Agents.AI.Abstractions.AIAgent`\n\n```csharp\n// .NET AIAgent 接口定义 (来源：dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs)\npublic abstract class AIAgent\n{\n public string? Id { get; }\n public string? Name { get; }\n public string? Description { get; }\n public IList? Tools { get; }\n public string? Instructions { get; }\n}\n```\n\n### 2.2 工作流系统\n\n工作流（Workflow）是组合多个 Agent 或任务的编排机制。框架支持三种工作流模式：\n\n| 工作流类型 | 说明 | 适用场景 |\n|------------|------|----------|\n| 函数式工作流 | 异步函数组合 | 简单线性流程 |\n| 图工作流 | 节点-边有向图 | 条件分支流程 |\n| 声明式工作流 | YAML 配置定义 | 可视化编排 |\n\n**Python 工作流基类** (来源：`python/packages/core/agent_framework/_workflows/_workflow.py`)：\n\n```python\nclass Workflow(ABC):\n \"\"\"工作流基类\"\"\"\n \n @property\n @abstractmethod\n def input_schema(self) -> dict | None:\n \"\"\"输入参数模式\"\"\"\n pass\n \n @property\n @abstractmethod\n def output_schema(self) -> dict | None:\n \"\"\"输出参数模式\"\"\"\n pass\n \n @abstractmethod\n async def run(self, input_data: Any) -> Any:\n \"\"\"执行工作流\"\"\"\n pass\n```\n\n**.NET 工作流定义** (来源：`dotnet/src/Microsoft.Agents.AI.Workflows/Workflow.cs`)：\n\n```csharp\npublic abstract class Workflow\n{\n public abstract Task RunAsync(\n WorkflowState input, \n CancellationToken cancellationToken = default);\n}\n```\n\n### 2.3 工具系统\n\n工具是 Agent 调用外部能力的接口，支持函数定义和资源绑定。\n\n```python\n# @tool 装饰器示例 (来源：python/samples/01-get-started/README.md)\nfrom agent_framework import tool\n\n@tool\ndef get_weather(location: str) -> str:\n \"\"\"获取指定位置的天气信息\"\"\"\n # 工具实现\n return f\"{location} 的天气是晴天\"\n```\n\n工具定义包含以下属性：\n\n| 属性 | 说明 | 必需 |\n|------|------|------|\n| name | 工具名称 | 是 |\n| description | 工具功能描述 | 是 |\n| parameters | JSON Schema 参数定义 | 是 |\n| resources | 关联资源映射 | 否 |\n\n## 3. 会话与上下文管理\n\n### 3.1 AgentSession 多轮会话\n\nAgentSession 维护对话历史，支持跨请求的上下文保持。\n\n```mermaid\ngraph LR\n A[用户输入 1] --> B[Agent]\n B --> C[LLM 响应 1]\n C --> D[Session 存储]\n D --> E[用户输入 2]\n E --> B\n B --> F[LLM 响应 2]\n```\n\n关键特性：\n- 自动维护对话历史\n- 支持流式和非流式输出\n- 可扩展的记忆系统接口\n\n### 3.2 ContextProvider 上下文提供者\n\n通过 ContextProvider 接口动态注入额外上下文：\n\n```python\nclass ContextProvider(Protocol):\n \"\"\"上下文提供者协议\"\"\"\n \n async def get_context(self) -> str:\n \"\"\"获取额外上下文\"\"\"\n pass\n```\n\n使用示例 (来源：`python/samples/01-get-started/04_memory.py`)：\n\n```python\nagent = Agent(\n name=\"my_agent\",\n context_providers=[MyCustomContextProvider()]\n)\n```\n\n## 4. 技能系统\n\n技能（Skill）是一种可复用的 Agent 能力封装，支持文件和代码两种定义方式。\n\n### 4.1 技能结构\n\n| 组件 | 说明 |\n|------|------|\n| name | 技能名称（kebab-case） |\n| description | 技能描述 |\n| instructions | 技能指令文本 |\n| resources | 关联资源文件 |\n| scripts | 执行脚本 |\n\n技能抽象定义 (来源：`dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs`)：\n\n```csharp\npublic abstract class AgentSkill\n{\n public abstract string Name { get; }\n public abstract string Description { get; }\n public abstract string Content { get; }\n public virtual IReadOnlyList? Resources => null;\n public virtual IReadOnlyList? Scripts => null;\n}\n```\n\n### 4.2 技能加载流程\n\n```mermaid\ngraph TD\n A[用户请求] --> B[AgentSkillsProvider]\n B --> C{技能源类型}\n C -->|文件| D[SKILL.md 解析]\n C -->|代码| E[AgentInlineSkill 实例化]\n D --> F[生成技能内容]\n E --> F\n F --> G[注入 Agent 上下文]\n G --> H[LLM 调用]\n```\n\n技能提供者配置 (来源：`dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs`)：\n\n```csharp\n// 默认技能指令模板\nprivate const string DefaultSkillsInstructionPrompt =\n \"\"\"\n You have access to skills containing domain-specific knowledge and capabilities.\n \n {skills}\n \n When a task aligns with a skill's domain, follow these steps:\n - Use `load_skill` to retrieve the skill's instructions.\n - Follow the provided guidance.\n \"\"\";\n```\n\n## 5. 部署与托管\n\n框架支持多种部署模式：\n\n| 部署方式 | 说明 | 适用场景 |\n|----------|------|----------|\n| 本地运行 | 开发调试 | 本地开发 |\n| 容器化部署 | Docker 容器 | 生产环境 |\n| Azure Foundry | 云托管服务 | 企业级部署 |\n\n托管示例项目 (来源：`dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/README.md`)：\n\n```bash\ndocker run -e FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT \\\n -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \\\n --env-file .env \\\n hosted-workflow-simple\n```\n\n## 6. 示例学习路径\n\n框架提供渐进式学习示例 (来源：`python/samples/01-get-started/README.md`)：\n\n| 阶段 | 示例文件 | 学习内容 |\n|------|----------|----------|\n| 入门 | 01_hello_agent.py | 创建首个 Agent |\n| 进阶 | 02_add_tools.py | 添加工具 |\n| 多轮 | 03_multi_turn.py | AgentSession |\n| 记忆 | 04_memory.py | ContextProvider |\n| 工作流 | 05-06_functional_workflow | 函数式编排 |\n| 图工作流 | 07_first_graph_workflow | 节点图编排 |\n| 部署 | 08_host_your_agent.py | 服务托管 |\n\n## 7. 集成扩展\n\n### 7.1 LLM 提供商支持\n\n框架通过抽象接口支持多种 LLM 提供商：\n\n| 包 | 提供商 | 安装命令 |\n|----|--------|----------|\n| agent-framework (内置) | OpenAI / Azure OpenAI | pip install agent-framework |\n| agent-framework-claude | Anthropic Claude | pip install agent-framework-claude --pre |\n| agent-framework-declarative | YAML 配置 | pip install agent-framework-declarative --pre |\n\n### 7.2 Azure 服务集成\n\n框架深度集成 Azure AI 服务：\n\n- **Azure AI Foundry**：Agent 部署和托管\n- **Azure Content Understanding**：文档、图像、音视频理解\n- **Azure AI Search**：知识检索增强\n\n集成示例 (来源：`python/packages/azure-contentunderstanding/samples/README.md`)：\n\n```python\n# PDF 文档问答\nfrom agent_framework_azure_contentunderstanding import DocumentProcessor\n\nprocessor = DocumentProcessor(endpoint=AZURE_CU_ENDPOINT)\nresult = await processor.analyze(\"document.pdf\", \"总结本文要点\")\n```\n\n## 8. 总结\n\nMicrosoft Agent Framework 的架构设计遵循以下原则：\n\n1. **跨平台一致性**：Python 和 .NET 实现保持 API 对齐\n2. **可扩展性**：通过抽象接口支持自定义扩展\n3. **声明式优先**：支持 YAML 配置降低使用门槛\n4. **生产就绪**：内置监控、日志、错误处理等企业特性\n\n框架核心位于 `agent_framework._agents` 和 `agent_framework._workflows` 模块，通过清晰的职责划分实现 Agent 创建、工作流编排、工具集成、会话管理的完整功能闭环。\n\n---\n\n\n\n## 核心概念\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [Agent 基础](#agent-basics)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/core/agent_framework/_types.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_types.py)\n- [python/packages/core/agent_framework/_sessions.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_sessions.py)\n- [dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs)\n- [dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs)\n- [dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs)\n- [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)\n- [dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs)\n- [dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs)\n
\n\n# 核心概念\n\nMicrosoft Agent Framework 是一个跨平台的多智能体开发框架，支持 Python 和 .NET 两种语言实现。该框架提供了构建、配置和运行 AI Agent 的完整基础设施，涵盖从基础的会话管理到复杂的多智能体工作流编排。\n\n## 框架架构概览\n\nAgent Framework 采用分层架构设计，核心层负责会话状态管理和响应处理，应用层提供 Agent 的构建和工具集成能力。\n\n```mermaid\ngraph TD\n subgraph \"应用层\"\n A1[ChatClientAgent]\n A2[AgentSkill]\n A3[AgentModeProvider]\n end\n \n subgraph \"核心抽象层\"\n C1[AgentSession]\n C2[AgentResponse]\n C3[AIContext]\n end\n \n subgraph \"客户端层\"\n B1[IChatClient]\n B2[PersistentAgentsClient]\n end\n \n A1 --> C1\n A2 --> C1\n A3 --> C1\n C1 --> C2\n B1 --> A1\n B2 --> A1\n```\n\n## 核心数据类型\n\n### AgentSession（Agent 会话）\n\n`AgentSession` 是框架中管理多轮对话状态的核心抽象，封装了对话历史、用户标识和会话元数据。\n\n```csharp\n// dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs\npublic class AgentSession\n{\n public string? SessionId { get; set; }\n public string? AssistantId { get; set; }\n public string? UserId { get; set; }\n public DateTimeOffset? CreatedAt { get; set; }\n public IDictionary? Metadata { get; set; }\n public IList? Messages { get; set; }\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs]()\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `SessionId` | string? | 会话唯一标识符 |\n| `AssistantId` | string? | Assistant 标识 |\n| `UserId` | string? | 用户标识 |\n| `CreatedAt` | DateTimeOffset? | 会话创建时间 |\n| `Metadata` | IDictionary? | 会话元数据键值对 |\n| `Messages` | IList? | 消息历史列表 |\n\n### AgentResponse（Agent 响应）\n\n`AgentResponse` 封装了 Agent 执行结果的完整信息，包括响应内容、工具调用、Token 使用统计等。\n\n```csharp\n// dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs\npublic class AgentResponse\n{\n public string? Content { get; set; }\n public IList? ToolCalls { get; set; }\n public CompletionUsage? Usage { get; set; }\n public string? FinishReason { get; set; }\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs]()\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `Content` | string? | 响应文本内容 |\n| `ToolCalls` | IList? | 调用的工具列表 |\n| `Usage` | CompletionUsage? | Token 使用统计 |\n| `FinishReason` | string? | 完成原因（如 stop、tool_calls） |\n\n### Python 类型定义\n\nPython SDK 提供了等效的类型定义，通过数据类实现会话和消息的建模。\n\n```python\n# python/packages/core/agent_framework/_types.py\n@dataclass\nclass AgentSession:\n session_id: Optional[str] = None\n user_id: Optional[str] = None\n created_at: Optional[datetime] = None\n metadata: Optional[Dict[str, str]] = None\n\n@dataclass\nclass TurnResponse:\n output: str\n tool_calls: Optional[List[ToolCall]] = None\n usage: Optional[Usage] = None\n session: AgentSession\n```\n\n资料来源：[python/packages/core/agent_framework/_types.py]()\n\n## Agent 类型体系\n\n### ChatClientAgent\n\n`ChatClientAgent` 是基于 `IChatClient` 的标准 Agent 实现，支持流式和非流式两种运行模式。\n\n```csharp\n// dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs\npublic sealed class ChatClientAgent : AIAgent\n{\n public ChatClientAgent(\n IChatClient chatClient,\n string? instructions = null,\n string? name = null,\n string? description = null,\n IEnumerable? tools = null,\n ILoggerFactory? loggerFactory = null,\n IServiceProvider? services = null);\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs]()\n\n| 构造参数 | 类型 | 说明 |\n|----------|------|------|\n| `chatClient` | IChatClient | 底层聊天客户端 |\n| `instructions` | string? | 系统级指令 |\n| `name` | string? | Agent 名称 |\n| `description` | string? | Agent 描述 |\n| `tools` | IEnumerable? | 可用工具集 |\n| `loggerFactory` | ILoggerFactory? | 日志工厂 |\n| `services` | IServiceProvider? | 依赖注入服务容器 |\n\n### AgentSkill（技能）\n\n`AgentSkill` 是框架中的技能抽象基类，支持文件定义和代码定义两种方式。\n\n```mermaid\nclassDiagram\n class AgentSkill {\n <>\n +Name : string\n +Description : string\n +Content : string\n +Resources : IReadOnlyList~AgentSkillResource~?\n +Scripts : IReadOnlyList~AgentSkillScript~?\n }\n \n class AgentInlineSkill {\n +Instructions : string\n +License : string?\n +Compatibility : string?\n +AllowedTools : string?\n +Metadata : AdditionalPropertiesDictionary?\n }\n \n class FileBasedSkill {\n +FilePath : string\n }\n \n AgentSkill <|-- AgentInlineSkill\n AgentSkill <|-- FileBasedSkill\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs]()\n\n**AgentInlineSkill** 支持通过代码直接定义技能：\n\n```csharp\n// dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs\npublic class AgentInlineSkill : AgentSkill\n{\n public AgentInlineSkill(\n string name,\n string description,\n string instructions,\n string? license = null,\n string? compatibility = null,\n string? allowedTools = null,\n AdditionalPropertiesDictionary? metadata = null,\n JsonSerializerOptions? serializerOptions = null);\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs]()\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `name` | string | 技能名称（kebab-case） |\n| `description` | string | 技能描述 |\n| `instructions` | string | 技能指令文本 |\n| `license` | string? | 许可证名称 |\n| `compatibility` | string? | 兼容性信息（最多500字符） |\n| `allowedTools` | string? | 预批准工具空格分隔列表 |\n| `metadata` | AdditionalPropertiesDictionary? | 自定义元数据 |\n| `serializerOptions` | JsonSerializerOptions? | JSON 序列化选项 |\n\n## 会话管理\n\n### AgentSession 的生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建会话: 首次交互\n 创建会话 --> 活跃: 添加用户消息\n 活跃 --> 活跃: 多轮对话\n 活跃 --> 结束: 显式关闭或超时\n 结束 --> [*]: 资源释放\n \n 创建会话 --> 错误: 参数验证失败\n 活跃 --> 错误: 服务不可用\n 错误 --> [*]: 错误处理\n```\n\n### Python 会话管理\n\nPython SDK 提供了 `AgentSession` 类的完整实现：\n\n```python\n# python/packages/core/agent_framework/_sessions.py\nclass AgentSession(ABC):\n @abstractmethod\n async def run(self, prompt: str, *args, **kwargs) -> TurnResponse: ...\n \n @abstractmethod\n async def run_streaming(self, prompt: str, *args, **kwargs) -> AsyncIterator[TurnResponse]: ...\n \n @abstractmethod\n async def reset(self) -> None: ...\n```\n\n资料来源：[python/packages/core/agent_framework/_sessions.py]()\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `run` | TurnResponse | 非流式执行单个轮次 |\n| `run_streaming` | AsyncIterator[TurnResponse] | 流式执行 |\n| `reset` | None | 重置会话状态 |\n\n## Agent 模式（AgentMode）\n\n`AgentMode` 定义了 Agent 的运行模式，支持交互式规划和自主执行两种模式。\n\n```csharp\n// dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs\npublic sealed class AgentMode\n{\n public string Name { get; }\n public string Description { get; }\n \n public AgentMode(string name, string description);\n}\n\npublic class AgentModeProviderOptions\n{\n public IReadOnlyList? Modes { get; set; }\n public string? DefaultMode { get; set; }\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs]()\n\n| 模式名称 | 说明 |\n|----------|------|\n| `plan` | 交互式规划模式 |\n| `execute` | 自主执行模式 |\n\n## 工作流程集成\n\n### 多 Agent 协作\n\n框架支持将多个 Agent 组合成工作流，实现复杂的任务分解和执行：\n\n```mermaid\ngraph LR\n subgraph \"工作流\"\n W1[主 Agent]\n W2[子 Agent 1]\n W3[子 Agent 2]\n W4[聚合器]\n end\n \n W1 --> W2\n W1 --> W3\n W2 --> W4\n W3 --> W4\n```\n\n### 工具系统\n\n框架的工具系统支持两种调用方式：\n\n| 调用方式 | 触发条件 | 用户确认 |\n|----------|----------|----------|\n| 自动调用 | AI 自动选择 | 默认无需确认 |\n| 请求确认 | 高风险操作 | 需要显式批准 |\n\n> [!NOTE]\n> 默认情况下，所有提供的工具都会自动调用。AI 选择调用的函数和参数应被视为不受信任的输入。开发者应为具有副作用、访问敏感数据或执行不可逆操作的工具要求显式批准。\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs]()\n\n## 快速入门示例\n\n### Python 示例\n\n```python\n# 创建基础 Agent\nfrom agent_framework import Agent\n\nagent = Agent(\n model=\"gpt-4o\",\n instructions=\"你是一个有帮助的助手\"\n)\n\n# 非流式运行\nresponse = await agent.run(\"今天天气怎么样？\")\nprint(response.output)\n\n# 流式运行\nasync for chunk in agent.run_streaming(\"讲个故事\"):\n print(chunk.output, end=\"\", flush=True)\n```\n\n### .NET 示例\n\n```csharp\n// 创建 ChatClientAgent\nvar agent = new ChatClientAgent(\n chatClient: chatClient,\n instructions: \"You are a helpful assistant\",\n name: \"Assistant\",\n description: \"A general purpose assistant\",\n tools: myTools);\n\n// 运行 Agent\nvar response = await agent.RunAsync(\"Hello, how are you?\");\n```\n\n## 核心概念总结\n\n| 概念 | 作用 | 关键文件 |\n|------|------|----------|\n| AgentSession | 管理会话状态和消息历史 | _sessions.py, AgentSession.cs |\n| AgentResponse | 封装执行结果 | AgentResponse.cs |\n| ChatClientAgent | 基于 IChatClient 的 Agent 实现 | ChatClientAgent.cs |\n| AgentSkill | 技能抽象，支持文件和代码定义 | AgentSkill.cs |\n| AgentMode | 定义运行模式（plan/execute） | AgentModeProviderOptions.cs |\n| ContextProvider | 提供动态上下文 | AgentSkillsProvider.cs |\n\n---\n\n\n\n## Agent 基础\n\n### 相关页面\n\n相关主题：[工具与技能系统](#agent-tools), [模型提供商集成](#agent-providers)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/core/agent_framework/_agents.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py)\n- [python/samples/01-get-started/01_hello_agent.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/01_hello_agent.py)\n- [dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs)\n- [dotnet/samples/01-get-started/01_hello_agent/Program.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/01-get-started/01_hello_agent/Program.cs)\n- [dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs)\n- [README.md](https://github.com/microsoft/agent-framework/blob/main/README.md)\n- [python/README.md](https://github.com/microsoft/agent-framework/blob/main/python/README.md)\n
\n\n# Agent 基础\n\n## 概述\n\nAgent（智能体）是 Microsoft Agent Framework 的核心抽象单元，代表能够理解自然语言、调用工具并执行复杂任务的 AI 驱动的软件实体。在 Agent Framework 中，Agent 作为一个封装了 AI 客户端、指令、工具和会话状态的可组合单元，为开发者提供了构建 AI 应用的基础构建块。\n\nAgent 的核心职责包括：\n- 接收用户输入并生成响应\n- 管理对话历史和多轮交互\n- 调用工具扩展能力边界\n- 集成多种 AI 服务提供商（如 Azure OpenAI、OpenAI、GitHub Copilot、Claude 等）\n\n资料来源：[python/packages/core/agent_framework/_agents.py:1-50](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py)\n\n## Agent 的核心组件\n\n### Python 实现架构\n\nPython Agent 由以下核心类组成：\n\n| 类名 | 用途 |\n|------|------|\n| `Agent` | 主入口类，封装客户端和指令 |\n| `ChatCompletionMessage` | 聊天消息的数据结构 |\n| `ChatClientProtocol` | 聊天客户端接口协议 |\n| `FunctionSpec` | 函数工具的规范定义 |\n\n资料来源：[python/packages/core/agent_framework/_agents.py:1-100](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py)\n\n### .NET 实现架构\n\n在 .NET 侧，`ChatClientAgent` 类是核心实现：\n\n```csharp\npublic sealed class ChatClientAgent : AIAgent\n```\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `Instructions` | `string?` | 系统指令，指导 Agent 行为 |\n| `Tools` | `IList?` | Agent 可调用的工具集合 |\n| `LoggerFactory` | `ILoggerFactory?` | 日志工厂 |\n| `Services` | `IServiceProvider?` | 依赖注入服务提供器 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs:30-80](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs)\n\n### Agent 标识模型\n\n```mermaid\nclassDiagram\n class AgentId {\n +AgentIdType Type\n +string Name\n +string Version\n }\n \n class AgentIdType {\n +string Value\n }\n \n AgentId --> AgentIdType : contains\n```\n\n`AgentId` 类用于标识特定的 Agent 实例，包含类型、名称和版本信息。\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs:10-40](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs)\n\n## Agent 的创建与初始化\n\n### Python 创建模式\n\n```python\nfrom agent_framework import Agent, FoundryChatClient\nfrom azure.identity import AzureCliCredential\n\nagent = Agent(\n client=FoundryChatClient(\n credential=AzureCliCredential(),\n project_endpoint=os.environ[\"FOUNDRY_PROJECT_ENDPOINT\"],\n ),\n name=\"HaikuAgent\",\n instructions=\"You are an upbeat assistant that writes beautifully.\",\n)\n```\n\nPython Agent 构造函数接受以下核心参数：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `client` | `ChatClientProtocol` | 是 | AI 聊天客户端实例 |\n| `name` | `str` | 否 | Agent 名称，用于标识和日志 |\n| `instructions` | `str` | 否 | 系统提示词 |\n\n资料来源：[python/samples/01-get-started/01_hello_agent.py:1-50](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/01_hello_agent.py)\n\n### .NET 创建模式\n\n```csharp\nusing Azure.AI.Projects;\nusing Azure.Identity;\nusing Microsoft.Agents.AI;\n\nAIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())\n .AsAIAgent(\n model: deploymentName, \n instructions: \"You are an upbeat assistant.\", \n name: \"HaikuAgent\"\n );\n```\n\n.NET 通过扩展方法 `AsAIAgent()` 将 `AIProjectClient` 转换为 `AIAgent` 实例。\n\n资料来源：[dotnet/samples/01-get-started/01_hello_agent/Program.cs:1-30](https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/01-get-started/01_hello_agent/Program.cs)\n\n### 初始化流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant Agent\n participant Client\n participant AI_Service\n \n User->>Agent: 创建 Agent 实例\n Agent->>Client: 初始化 ChatClient\n Client->>AI_Service: 建立连接\n AI_Service-->>Client: 连接成功\n Client-->>Agent: 客户端就绪\n Agent-->>User: Agent 初始化完成\n```\n\n## Agent 的运行机制\n\n### 单轮对话执行\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Agent.run]\n B --> C[构建 ChatOptions]\n C --> D[调用 ChatClient]\n D --> E[AI 模型处理]\n E --> F[返回消息]\n F --> G[解析响应]\n G --> H[返回结果]\n```\n\nAgent 的 `run()` 方法执行单轮对话，输入直接转换为输出，不保留会话历史。\n\n资料来源：[python/packages/core/agent_framework/_agents.py:100-150](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py)\n\n### 消息格式\n\nAgent 使用结构化的消息格式进行通信：\n\n| 消息类型 | 说明 |\n|----------|------|\n| `user` | 用户发送的消息 |\n| `assistant` | AI 生成的回复 |\n| `tool` | 工具调用请求或结果 |\n\n## 工具集成\n\n### 工具定义\n\nAgent 通过工具扩展其能力范围。工具可以是：\n\n- **函数工具**：Python 函数或 .NET 方法，通过装饰器/属性暴露给 AI\n- **外部 API**：通过 HTTP 调用的远程服务\n- **脚本**：可执行的代码片段\n\n### Python 工具定义示例\n\n```python\nfrom agent_framework import tool\n\n@tool\ndef get_weather(city: str) -> str:\n \"\"\"获取指定城市的天气信息\"\"\"\n return f\"{city} 今天的天气是晴天，25°C\"\n```\n\n资料来源：[python/samples/01-get-started/02_add_tools.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/02_add_tools.py)\n\n### .NET 工具定义\n\n在 .NET 中，工具通过 `AITool` 接口实现，并可在创建 Agent 时传入：\n\n```csharp\nAIAgent agent = client.AsAIAgent(\n tools: new List { customTool },\n instructions: \"Instructions here\"\n);\n```\n\n## 多轮对话与会话管理\n\n### Python 会话管理\n\nPython Agent 通过 `AgentSession` 类管理多轮对话：\n\n```python\nfrom agent_framework import AgentSession\n\nasync with AgentSession(agent=agent) as session:\n response1 = await session.run(\"你好\")\n response2 = await session.run(\"请帮我查询天气\")\n```\n\n会话自动维护消息历史，支持跨多次交互的上下文理解。\n\n资料来源：[python/samples/01-get-started/03_multi_turn.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/03_multi_turn.py)\n\n### .NET 会话管理\n\n```csharp\n// 使用 AIProjectClient 的 AsAIAgent 返回 AIAgent\n// AIAgent 内部管理会话状态\nstring response = await agent.RunAsync(\"Hello, how are you?\");\n```\n\n### 会话状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> 初始化: 创建 Agent\n 初始化 --> 就绪: 客户端连接\n 就绪 --> 处理中: 接收用户消息\n 处理中 --> 等待工具: 需要调用工具\n 等待工具 --> 处理中: 工具返回结果\n 处理中 --> 就绪: 生成最终响应\n 就绪 --> [*]: 会话结束\n```\n\n## 流式响应支持\n\nAgent 支持流式输出模式，适合需要实时反馈的场景：\n\n### Python 流式调用\n\n```python\nasync for event in agent.run(\"讲一个故事\", stream=True):\n print(event.delta, end=\"\", flush=True)\n```\n\n### .NET 流式调用\n\n```csharp\nawait foreach (var update in agent.RunAsync(\"Tell me a story\", stream: true))\n{\n Console.Write(update.Content);\n}\n```\n\n## 上下文提供者\n\nAgent 支持通过 `ContextProvider` 接口注入动态上下文：\n\n```python\nfrom agent_framework import ContextProvider\n\nclass CustomContextProvider(ContextProvider):\n async def get_context(self) -> str:\n # 返回动态生成的上下文\n return \"当前时间: 2024-01-01\"\n```\n\n资料来源：[python/samples/01-get-started/04_memory.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/04_memory.py)\n\n## 错误处理与日志\n\n### 异常处理\n\nAgent 运行时可能遇到以下异常类型：\n\n| 异常 | 说明 |\n|------|------|\n| `AgentException` | Agent 执行基础异常 |\n| `ToolExecutionException` | 工具执行失败 |\n| `AuthenticationException` | 认证失败 |\n| `RateLimitException` | 速率限制触发 |\n\n### 日志配置\n\n```csharp\n// .NET 日志配置\nvar loggerFactory = LoggerFactory.Create(builder => \n builder.AddConsole());\n\nAIAgent agent = new ChatClientAgent(client, loggerFactory: loggerFactory);\n```\n\n```python\n# Python 日志配置\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n## 最佳实践\n\n### 设计原则\n\n1. **清晰的指令设计**：编写明确、简洁的系统指令，避免歧义\n2. **合理的工具粒度**：工具应职责单一，便于 AI 理解和调用\n3. **适当的超时设置**：为长时间运行的操作设置超时\n4. **状态管理**：善用会话管理维护对话上下文\n\n### 性能优化\n\n| 策略 | 说明 |\n|------|------|\n| 工具缓存 | 避免重复初始化昂贵的工具资源 |\n| 上下文压缩 | 长对话中适当压缩历史消息 |\n| 并行工具调用 | 支持 AI 并行调用多个独立工具 |\n\n### 安全考虑\n\n- 对具有副作用的工具强制要求用户确认\n- 敏感操作实施访问控制\n- 验证工具返回结果的合法性\n\n## 相关资源\n\n- [Agent Framework 官方文档](https://github.com/microsoft/agent-framework)\n- [Python SDK 快速开始](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md)\n- [示例代码库](../samples/)\n\n---\n\n\n\n## 模型提供商集成\n\n### 相关页面\n\n相关主题：[Agent 基础](#agent-basics)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/openai/agent_framework_openai/_chat_client.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/agent_framework_openai/_chat_client.py)\n- [python/packages/foundry/agent_framework_foundry/_chat_client.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/foundry/agent_framework_foundry/_chat_client.py)\n- [python/packages/anthropic/agent_framework_anthropic/_chat_client.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/anthropic/agent_framework_anthropic/_chat_client.py)\n- [dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs)\n- [dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs)\n
\n\n# 模型提供商集成\n\n## 概述\n\n模型提供商集成（Model Provider Integration）是 Microsoft Agent Framework 的核心架构特性，允许框架通过统一的抽象接口接入多种大语言模型（LLM）提供商。该设计使开发者能够在不修改核心业务逻辑的情况下，灵活切换不同的 AI 后端服务。\n\nAgent Framework 的模型提供商集成具有以下核心目标：\n\n- **统一抽象**：为不同提供商提供一致的 API 接口\n- **多后端支持**：支持 OpenAI、Azure OpenAI、Azure AI Foundry、Anthropic Claude 等主流服务商\n- **配置灵活性**：通过环境变量或代码配置多种参数\n- **流式响应**：支持流式和非流式两种响应模式\n- **工具调用**：统一的函数调用（Function Calling）能力抽象\n\n资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md)\n\n## 架构设计\n\n### 整体架构\n\nAgent Framework 采用分层架构设计，模型提供商作为独立的包存在，通过标准化的接口与核心框架解耦：\n\n```mermaid\ngraph TD\n A[Agent / 业务逻辑层] --> B[核心框架层
agent_framework.core]\n B --> C[聊天客户端抽象层
IChatClient / ChatClientBase]\n C --> D[提供商特定实现层]\n \n D --> E[OpenAI]\n D --> F[Azure OpenAI]\n D --> G[Azure AI Foundry]\n D --> H[Anthropic Claude]\n \n E --> E1[Responses API]\n E --> E2[Chat Completions API]\n```\n\n资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md)\n\n### Python 生态中的聊天客户端\n\nPython 版本的 Agent Framework 为每个提供商提供了独立的聊天客户端类，这些类均继承自统一的基类或实现相同的接口：\n\n| 提供商 | 包名 | 主要类 | API 类型 |\n|--------|------|--------|----------|\n| OpenAI | `agent-framework-openai` | `OpenAIChatClient` | Responses API（推荐） |\n| OpenAI | `agent-framework-openai` | `OpenAIChatCompletionClient` | Chat Completions API |\n| Azure AI Foundry | `agent-framework-foundry` | `FoundryChatClient` | Azure Foundry 原生 |\n| Anthropic | `agent-framework-anthropic` | `AnthropicChatClient` | Claude API |\n\n资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md)\n\n### .NET 生态中的聊天客户端\n\n.NET 版本采用类似的架构，通过扩展方法将聊天客户端转换为代理：\n\n```mermaid\ngraph LR\n A[IChatClient] --> B[ChatClientAgent]\n B --> C[AsAIAgent 扩展方法]\n \n D[OpenAI ChatClient] --> C\n E[Azure OpenAI Client] --> C\n F[FoundryChatClient] --> C\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs)\n\n## OpenAI 集成\n\n### Python 实现\n\nPython 的 `agent-framework-openai` 包提供了两个聊天客户端类，分别对应 OpenAI 的两种 API：\n\n#### OpenAIChatClient（Responses API）\n\n这是推荐使用的客户端，使用 OpenAI 的 Responses API：\n\n```python\nfrom agent_framework.openai import OpenAIChatClient\n\nclient = OpenAIChatClient(\n api_key=\"sk-...\",\n model=\"gpt-4o\"\n)\n```\n\n模型优先级：`OPENAI_CHAT_MODEL` → `OPENAI_MODEL`\n\n资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md)\n\n#### OpenAIChatCompletionClient（Chat Completions API）\n\n此客户端使用传统的 Chat Completions API，主要用于兼容现有集成：\n\n```python\nfrom agent_framework.openai import OpenAIChatCompletionClient\n\nclient = OpenAIChatCompletionClient(\n api_key=\"sk-...\",\n model=\"gpt-4o-mini\"\n)\n```\n\n模型优先级：`OPENAI_CHAT_COMPLETION_MODEL` → `OPENAI_MODEL`\n\n资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md)\n\n### 环境变量配置\n\n| 变量名 | 用途 |\n|--------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 |\n| `OPENAI_ORG_ID` | OpenAI 组织 ID |\n| `OPENAI_BASE_URL` | 自定义 OpenAI 兼容 API 地址 |\n| `OPENAI_MODEL` | 通用默认模型 |\n| `OPENAI_CHAT_MODEL` | `OpenAIChatClient` 首选模型 |\n| `OPENAI_CHAT_COMPLETION_MODEL` | `OpenAIChatCompletionClient` 首选模型 |\n| `OPENAI_EMBEDDING_MODEL` | `OpenAIEmbeddingClient` 首选模型 |\n\n资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md)\n\n### .NET 实现\n\n在 .NET 生态中，通过 `OpenAIChatClientExtensions` 扩展方法将 `ChatClient` 转换为 `Agent`：\n\n```csharp\nusing Microsoft.Agents.AI.OpenAI.Extensions;\n\nChatClientAgent agent = chatClient.AsAIAgent(\n name: \"ChatAssistant\",\n instructions: \"You are a helpful coding assistant specializing in C# and .NET.\");\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs)\n\n## Azure AI Foundry 集成\n\n### Python 实现\n\n`agent-framework-foundry` 包提供了与 Azure AI Foundry 的深度集成：\n\n```python\nfrom agent_framework_foundry import FoundryChatClient\n\nclient = FoundryChatClient(\n project_endpoint=\"https://your-project.services.ai.azure.com\",\n model=\"gpt-4o\"\n)\n```\n\nAzure AI Foundry 集成主要使用环境变量配置：\n\n| 变量名 | 用途 |\n|--------|------|\n| `FOUNDRY_PROJECT_ENDPOINT` | Foundry 项目端点 |\n| `FOUNDRY_MODEL` | 使用的模型名称 |\n\n资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md)\n\n### .NET 实现\n\n```csharp\nusing Microsoft.Agents.AI.Foundry;\n\nFoundryAgent agent = new FoundryAgent(\n projectEndpoint: \"https://your-project.services.ai.azure.com\",\n deploymentName: \"gpt-4o\"\n);\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs)\n\n## Anthropic Claude 集成\n\n### Python 实现\n\n`agent-framework-anthropic` 包提供了 Claude 模型的集成：\n\n```python\nfrom agent_framework_anthropic import AnthropicChatClient\n\nclient = AnthropicChatClient(\n api_key=\"sk-ant-...\",\n model=\"claude-3-5-sonnet-20241022\"\n)\n```\n\nAnthropic 集成允许开发者使用 Claude 系列模型，与 OpenAI 风格的接口保持一致。\n\n资料来源：[python/packages/anthropic/agent_framework_anthropic/_chat_client.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/anthropic/agent_framework_anthropic/_chat_client.py)\n\n## 核心使用模式\n\n### 模式一：直接使用聊天客户端\n\n适用于高级工作流，直接与聊天 API 交互：\n\n```python\nimport asyncio\nfrom agent_framework.openai import OpenAIChatClient\nfrom agent_framework import Message, Role\n\nasync def main():\n client = OpenAIChatClient()\n\n response = await client.get_response([\n Message(\"system\", [\"You are a helpful assistant.\"]),\n Message(\"user\", [\"Write a haiku about Agent Framework.\"])\n ])\n print(response.messages[0].text)\n\nasyncio.run(main())\n```\n\n资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md)\n\n### 模式二：创建代理\n\n使用聊天客户端创建 Agent，让框架处理对话管理：\n\n```python\nfrom agent_framework import Agent\nfrom agent_framework.openai import OpenAIChatClient\n\nagent = Agent(\n client=OpenAIChatClient(),\n instructions=\"你是一个有帮助的编程助手。\"\n)\n\nresult = await agent.run(\"解释什么是函数调用\")\n```\n\n资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md)\n\n### 模式三：带工具的代理\n\n为代理添加工具（函数调用）能力：\n\n```python\nfrom typing import Annotated\nfrom agent_framework import Agent\nfrom agent_framework.openai import OpenAIChatClient\n\ndef get_weather(\n location: Annotated[str, \"要查询天气的城市\"]\n) -> str:\n \"\"\"获取指定城市的天气信息\"\"\"\n return f\"{location} 今天天气晴朗，温度 22°C\"\n\nagent = Agent(\n client=OpenAIChatClient(),\n instructions=\"你是一个天气助手。\",\n tools=[get_weather]\n)\n```\n\n资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md)\n\n## 代理创建参数\n\n### ChatClientAgent 参数说明\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `chatClient` | `IChatClient` | 是 | 用于执行聊天的客户端实例 |\n| `instructions` | `string?` | 否 | 系统指令，指导代理行为 |\n| `name` | `string?` | 否 | 代理名称，用于识别和日志记录 |\n| `description` | `string?` | 否 | 人类可读的代理描述 |\n| `tools` | `IReadOnlyList?` | 否 | 代理可调用的工具集合 |\n| `loggerFactory` | `ILoggerFactory?` | 否 | 日志工厂实例 |\n| `services` | `IServiceProvider?` | 否 | 依赖注入服务提供者 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs)\n\n## 提供商选择指南\n\n### 选择 OpenAI 的场景\n\n- 新项目推荐使用 Responses API（`OpenAIChatClient`）\n- 需要兼容现有 Chat Completions 代码时使用 `OpenAIChatCompletionClient`\n- 需要快速原型开发\n\n### 选择 Azure OpenAI 的场景\n\n- 企业已有 Azure 订阅\n- 需要 Azure 的安全合规特性\n- 与其他 Azure 服务集成\n\n### 选择 Azure AI Foundry 的场景\n\n- 使用 Azure AI Foundry 作为主要推理服务\n- 需要 Foundry 特有的功能（如高级模型路由）\n\n### 选择 Anthropic Claude 的场景\n\n- 需要 Claude 的长上下文能力\n- 偏好 Anthropic 的安全对齐特性\n- 特定场景下 Claude 表现更优\n\n## 流式响应支持\n\n所有聊天客户端均支持流式响应模式：\n\n### Python 流式调用\n\n```python\nasync for chunk in client.stream([Message(\"user\", [\"你好\"])]):\n print(chunk.content, end=\"\", flush=True)\n```\n\n### .NET 流式调用\n\n```csharp\nawait foreach (var update in agent.RunAsyncStreaming(\n new ChatMessage(ChatRole.User, \"Hello\")))\n{\n Console.Write(update.Content);\n}\n```\n\n## 多提供商工作流\n\nAgent Framework 支持在同一应用中混合使用多个提供商：\n\n```python\nfrom agent_framework.openai import OpenAIChatClient\nfrom agent_framework_foundry import FoundryChatClient\nfrom agent_framework import Agent\n\n# 不同任务使用不同提供商\nrouter_agent = Agent(\n client=OpenAIChatClient(),\n instructions=\"你是任务路由器，将问题分类并路由到合适的处理代理。\"\n)\n\n# 编码任务使用 Claude\ncoding_agent = Agent(\n client=AnthropicChatClient(),\n instructions=\"你是一个专业程序员。\"\n)\n\n# 简单问答使用轻量模型\nqa_agent = Agent(\n client=OpenAIChatCompletionClient(model=\"gpt-4o-mini\"),\n instructions=\"你是一个简洁的问答助手。\"\n)\n```\n\n## 配置最佳实践\n\n### 开发环境\n\n```bash\n# .env 文件\nOPENAI_API_KEY=sk-...\nOPENAI_CHAT_MODEL=gpt-4o-mini\n\n# 或使用 Azure\nAZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/\nAZURE_OPENAI_API_KEY=...\nAZURE_OPENAI_MODEL=gpt-4o\n```\n\n### 生产环境\n\n建议使用密钥管理服务：\n\n- Azure: 使用 Azure Key Vault\n- AWS: 使用 AWS Secrets Manager\n- 通用: 环境变量或配置服务\n\n### 客户端配置覆盖\n\n环境变量可以被代码参数覆盖：\n\n```python\nclient = OpenAIChatClient(\n api_key=\"from-secret-manager\",\n model=\"gpt-4o\"\n)\n```\n\n资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md)\n\n## 相关资源\n\n- [Python 快速开始示例](https://github.com/microsoft/agent-framework/tree/main/python/samples/01-get-started)\n- [OpenAI 包文档](https://github.com/microsoft/agent-framework/tree/main/python/packages/openai)\n- [Foundry 包文档](https://github.com/microsoft/agent-framework/tree/main/python/packages/foundry)\n- [Anthropic 包文档](https://github.com/microsoft/agent-framework/tree/main/python/packages/anthropic)\n- [.NET 示例：OpenAI Responses](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/02-agents/AgentProviders/Agent_With_OpenAIResponses)\n- [.NET 示例：OpenAI Chat Completion](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/02-agents/AgentProviders/Agent_With_OpenAIChatCompletion)\n\n---\n\n\n\n## 工具与技能系统\n\n### 相关页面\n\n相关主题：[Agent 基础](#agent-basics)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/core/agent_framework/_tools.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_tools.py)\n- [python/packages/core/agent_framework/_skills.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_skills.py)\n- [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)\n- [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs)\n- [dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs)\n- [dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs)\n
\n\n# 工具与技能系统\n\n## 概述\n\nAgent Framework 的**工具与技能系统**是框架的核心扩展机制，旨在赋予 AI Agent 执行特定任务和访问领域知识的能力。该系统由两个相互关联但功能独立的子系统组成：\n\n- **工具系统 (Tools)**：为 Agent 提供可调用的函数能力，实现与外部系统的交互\n- **技能系统 (Skills)**：为 Agent 提供领域特定的指令、文档和资源，实现知识驱动的任务执行\n\n资料来源：[python/samples/01-get-started/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md)\n\n## 系统架构\n\n```mermaid\ngraph TD\n subgraph \"Agent Framework 工具与技能系统\"\n subgraph \"工具层 (Tools)\"\n A[Function Tool] --> B[ToolDefinition]\n C[FileMemory Tool] --> B\n D[Custom Tools] --> B\n end\n \n subgraph \"技能层 (Skills)\"\n E[AgentSkill 抽象基类] --> F[FileBasedSkill]\n E --> G[AgentInlineSkill]\n G --> H[AgentInlineSkillContentBuilder]\n end\n \n subgraph \"技能提供者\"\n I[AgentSkillsProvider] --> E\n J[AIContext] --> I\n end\n \n subgraph \"Agent 核心\"\n K[ChatClientAgent] --> L[工具调用]\n K --> M[技能加载]\n L --> B\n M --> I\n end\n end\n```\n\n## 工具系统\n\n### 工具定义\n\n工具系统基于函数工具定义，Agent 可以通过调用这些工具执行特定操作。工具定义包含以下核心属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | string | 工具名称，用于标识和调用 |\n| description | string | 工具功能描述，供 LLM 理解何时使用 |\n| parameters | JSON Schema | 工具参数规范 |\n| handler | Function | 工具执行逻辑 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs)\n\n### 内置工具示例\n\n#### FileMemory 工具集\n\nFileMemory 系统提供了一套完整的文件管理工具，Agent 可以使用这些工具进行持久化存储和知识检索：\n\n| 工具名称 | 功能 |\n|----------|------|\n| FileMemory_ReadFile | 读取内存文件内容 |\n| FileMemory_ListFiles | 列出可用的内存文件 |\n| FileMemory_SaveFile | 保存或更新内存文件 |\n| FileMemory_SearchFiles | 搜索内存文件内容 |\n\n```csharp\n[Description(\"Save a memory file with the given name and content. Overwrites the file if it already exists. Include a description for large files to provide a summary that helps with discovery.\")]\nprivate async Task SaveFileAsync(\n string fileName, \n string content, \n string? description = null, \n CancellationToken cancellationToken = default)\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs:54-60](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs)\n\n### 工具注册与调用流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as ChatClientAgent\n participant Tools as 工具系统\n participant LLM as 语言模型\n \n User->>Agent: 发送请求\n Agent->>LLM: 发送包含工具定义的请求\n LLM->>LLM: 分析任务，决定调用工具\n LLM->>Agent: 返回工具调用请求\n Agent->>Tools: 执行工具函数\n Tools->>Tools: 处理业务逻辑\n Tools-->>Agent: 返回执行结果\n Agent->>LLM: 发送工具结果\n LLM-->>Agent: 生成最终响应\n Agent-->>User: 返回结果\n```\n\n## 技能系统\n\n### 技能架构概述\n\n技能系统采用抽象基类设计，支持多种技能定义方式：\n\n```mermaid\nclassDiagram\n class AgentSkill {\n <>\n +Content: string {abstract}\n +Resources: IReadOnlyList~AgentSkillResource~?\n +Scripts: IReadOnlyList~AgentSkillScript~?\n }\n \n class FileBasedSkill {\n +Content: string\n }\n \n class AgentInlineSkill {\n +Name: string\n +Description: string\n +Instructions: string\n +License: string?\n +Compatibility: string?\n +AllowedTools: string?\n +Metadata: AdditionalPropertiesDictionary?\n }\n \n AgentSkill <|-- FileBasedSkill\n AgentSkill <|-- AgentInlineSkill\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)\n\n### AgentSkill 抽象基类\n\n`AgentSkill` 是所有技能类型的基类，定义了技能的通用接口：\n\n```csharp\n/// \n/// For file-based skills this is the raw SKILL.md file content, optionally\n/// augmented with a synthesized scripts block when scripts are present.\n/// For code-defined skills this is a synthesized XML document\n/// containing name, description, and body (instructions, resources, scripts).\n/// \npublic abstract string Content { get; }\n\n/// \n/// Gets the resources associated with this skill, or null if none.\n/// \npublic virtual IReadOnlyList? Resources => null;\n\n/// \n/// Gets the scripts associated with this skill, or null if none.\n/// \npublic virtual IReadOnlyList? Scripts => null;\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs:15-35](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)\n\n### 代码定义技能 (AgentInlineSkill)\n\n`AgentInlineSkill` 允许开发者以编程方式定义技能，无需使用外部文件：\n\n```csharp\npublic AgentInlineSkill(\n string name,\n string description,\n string instructions,\n string? license = null,\n string? compatibility = null,\n string? allowedTools = null,\n AdditionalPropertiesDictionary? metadata = null,\n JsonSerializerOptions? serializerOptions = null)\n```\n\n#### 构造函数参数说明\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| name | string | 是 | 技能名称，使用 kebab-case 格式 |\n| description | string | 是 | 技能描述，用于发现和选择 |\n| instructions | string | 是 | 技能指令文本 |\n| license | string? | 否 | 许可证名称或引用 |\n| compatibility | string? | 否 | 兼容性信息（最多 500 字符） |\n| allowedTools | string? | 否 | 预批准工具的空格分隔列表 |\n| metadata | AdditionalPropertiesDictionary? | 否 | 任意键值元数据 |\n| serializerOptions | JsonSerializerOptions? | 否 | 脚本和资源序列化选项 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs)\n\n### 技能内容构建器\n\n`AgentInlineSkillContentBuilder` 内部类负责将代码定义的技能转换为 XML 格式的内容字符串：\n\n```csharp\npublic static string Build(\n string name,\n string description,\n string instructions,\n IReadOnlyList? resources,\n IReadOnlyList? scripts)\n{\n var sb = new StringBuilder();\n \n sb.Append($\"{EscapeXmlString(name)}\\n\")\n .Append($\"{EscapeXmlString(description)}\\n\\n\")\n .Append(\"\\n\")\n .Append(EscapeXmlString(instructions))\n .Append(\"\\n\");\n // ...\n}\n```\n\n生成的 XML 结构示例：\n\n```xml\ncode-defined-skill\nA code-defined skill example\n\n\nYour skill instructions here...\n\n\n\n\n\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs)\n\n### AgentSkillsProvider 技能提供者\n\n`AgentSkillsProvider` 是 AI 上下文提供者，负责将技能信息注入到 Agent 的执行上下文中：\n\n```mermaid\ngraph LR\n subgraph \"AgentSkillsProvider 内部机制\"\n A[技能源] -->|读取| B[AgentSkillsSource]\n C[提示模板] -->|格式化| D[SkillsPlaceholder]\n B -->|注入| D\n D --> E[AIContext]\n end\n```\n\n#### 默认技能指令模板\n\n```csharp\nprivate const string DefaultSkillsInstructionPrompt =\n \"\"\"\n You have access to skills containing domain-specific knowledge and capabilities.\n Each skill provides specialized instructions, reference documents, and assets for specific tasks.\n\n \n {skills}\n \n\n When a task aligns with a skill's domain, follow these steps in exact order:\n - Use `load_skill` to retrieve the skill's instructions.\n - Follow the provided guidance.\n {resource_instructions}\n {script_instructions}\n Only load what is needed, when it is needed.\n \"\"\";\n```\n\n#### 模板占位符说明\n\n| 占位符 | 说明 |\n|--------|------|\n| `{skills}` | 可用技能列表 |\n| `{resource_instructions}` | 资源相关指令 |\n| `{script_instructions}` | 脚本执行指令 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs)\n\n### 技能与 Agent 的集成流程\n\n```mermaid\nflowchart TD\n A[定义技能] --> B{技能类型选择}\n B -->|文件型| C[创建 SKILL.md]\n B -->|代码型| D[实例化 AgentInlineSkill]\n \n C --> E[注册到 AgentSkillsProvider]\n D --> E\n \n E --> F[Agent 执行时加载技能]\n F --> G{技能是否匹配任务}\n \n G -->|是| H[加载技能指令]\n G -->|否| I[跳过技能]\n \n H --> J[执行技能任务]\n I --> K[继续其他任务]\n J --> L[返回执行结果]\n K --> L\n```\n\n## 工具与技能协同\n\n### 工具调用链\n\n当技能包含脚本时，系统会通过 `run_skill_script` 工具执行脚本：\n\n```mermaid\nsequenceDiagram\n participant Agent as Agent\n participant LLM as Language Model\n participant Provider as AgentSkillsProvider\n participant Script as 技能脚本\n \n Agent->>LLM: 请求执行任务\n LLM->>Agent: 识别需要使用技能\n Agent->>Provider: 加载技能\n Provider-->>Agent: 返回技能内容\n Agent->>LLM: 传递技能指令\n LLM->>Agent: 决定调用工具\n Agent->>Script: 执行 run_skill_script\n Script-->>Agent: 返回执行结果\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)\n\n### 能力说明\n\n| 能力 | 工具支持 | 技能支持 | 说明 |\n|------|----------|----------|------|\n| 函数调用 | ✅ | ❌ | 工具通过函数定义实现调用 |\n| 知识注入 | ❌ | ✅ | 技能通过指令和资源注入知识 |\n| 持久化存储 | ✅ | ❌ | FileMemory 工具提供文件操作 |\n| 脚本执行 | ❌ | ✅ | 技能脚本通过专用工具执行 |\n| 动态发现 | ✅ | ✅ | 两者都支持描述性元数据 |\n\n## 使用示例\n\n### .NET 代码定义技能\n\n```csharp\nvar mySkill = new AgentInlineSkill(\n name: \"code-defined-skill\",\n description: \"A skill defined in code\",\n instructions: \"Follow these steps to complete the task...\",\n license: \"MIT\",\n compatibility: \"Agent Framework v1.0+\",\n allowedTools: \"FileMemory_ReadFile FileMemory_SaveFile\",\n metadata: new AdditionalPropertiesDictionary\n {\n { \"author\", \"developer@example.com\" },\n { \"version\", \"1.0.0\" }\n }\n);\n```\n\n### Python 工具装饰器\n\n```python\nfrom agent_framework import tool\n\n@tool\ndef add_numbers(a: int, b: int) -> int:\n \"\"\"Add two numbers together.\"\"\"\n return a + b\n```\n\n## 最佳实践\n\n### 技能设计原则\n\n1. **单一职责**：每个技能应专注于特定领域\n2. **清晰描述**：使用准确的描述帮助 LLM 选择合适的技能\n3. **版本管理**：通过元数据跟踪技能版本\n4. **权限控制**：使用 `allowedTools` 限制技能可访问的工具\n\n### 工具设计原则\n\n1. **原子性**：每个工具应执行单一操作\n2. **幂等性**：工具应能安全地重复执行\n3. **错误处理**：提供清晰的错误消息\n4. **参数验证**：使用 JSON Schema 严格定义参数\n\n## 相关资源\n\n- [Agent Skills Specification](https://agentskills.io/)\n- [Microsoft Agent Framework 文档](https://github.com/microsoft/agent-framework)\n- [入门示例](../samples/01-get-started/)\n\n---\n\n\n\n## 工作流系统概述\n\n### 相关页面\n\n相关主题：[工作流编排模式](#workflow-patterns), [检查点与恢复机制](#checkpoint-recovery)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/core/agent_framework/_workflows/_workflow.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_workflows/_workflow.py)\n- [python/packages/core/agent_framework/_workflows/_workflow_builder.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_workflows/_workflow_builder.py)\n- [dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilder.cs)\n- [dotnet/src/Microsoft.Agents.AI.Workflows/Executor.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/Executor.cs)\n- [python/samples/03-workflows/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/03-workflows/README.md)\n- [dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs)\n- [python/samples/03-workflows/declarative/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/03-workflows/declarative/README.md)\n
\n\n# 工作流系统概述\n\n## 1. 系统简介\n\nMicrosoft Agent Framework 的工作流系统（Workflow System）是一个用于编排多代理（Multi-Agent）协作的核心模块。该系统提供了两种互补的工作流定义方式：**命令式工作流（Imperative Workflow）** 和 **声明式工作流（Declarative Workflow）**。通过工作流系统，开发者可以将多个代理（Agent）、执行器（Executor）、工具（Tool）以及控制流逻辑组合成复杂的自动化流程。\n\n命令式工作流允许开发者使用 Python 或 C# 等编程语言直接编写工作流逻辑，而声明式工作流则支持通过 YAML 配置文件定义工作流，实现业务逻辑与代码的解耦。资料来源：[python/samples/03-workflows/README.md]()、[python/samples/03-workflows/declarative/README.md]()\n\n## 2. 核心概念\n\n### 2.1 执行器（Executor）\n\n执行器是工作流系统的基本构建单元，负责执行具体的任务或调用代理。每个执行器接收输入、执行逻辑并产生输出，输出可以传递给后续的执行器形成链条。\n\n在 .NET 实现中，`Executor` 类是执行器的基类，提供了异步执行能力。资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/Executor.cs]()\n\n### 2.2 工作流（Workflow）\n\n工作流是执行器的容器，定义了执行器的组织结构和执行顺序。工作流可以包含：\n\n- **起始执行器（Start Executor）**：工作流的入口点\n- **执行器图（Executor Graph）**：执行器之间的连接关系\n- **状态管理（State Management）**：工作流执行过程中的状态存储\n\n```mermaid\ngraph LR\n A[用户输入] --> B[起始执行器]\n B --> C[执行器 1]\n C --> D[执行器 2]\n D --> E[执行器 N]\n E --> F[工作流输出]\n```\n\n资料来源：[python/packages/core/agent_framework/_workflows/_workflow.py]()\n\n### 2.3 状态（State）\n\n工作流状态用于在工作流执行过程中存储和传递数据。状态可以包含：\n\n| 状态字段 | 描述 |\n|---------|------|\n| `turn.*` | 当前轮次相关的变量，如 `turn.greeting` |\n| `user.*` | 用户相关数据 |\n| `agent.*` | 代理生成的数据 |\n| `_executor_state` | 执行器内部状态（系统保留） |\n\n资料来源：[python/samples/03-workflows/declarative/README.md]()\n\n## 3. 工作流类型\n\n### 3.1 命令式工作流（Imperative Workflow）\n\n命令式工作流使用代码直接定义，允许开发者使用完整的编程语言能力。\n\n#### 3.1.1 函数式工作流（Functional Workflow）\n\n函数式工作流将工作流编写为普通的异步函数，使用原生的 `if/else`、循环和 `asyncio.gather` 等控制流语法。\n\n```python\nasync def my_workflow(input_data: dict) -> dict:\n # 原生 Python 异步控制流\n if input_data.get(\"type\") == \"A\":\n result = await agent_a.invoke(input_data)\n else:\n results = await asyncio.gather(\n agent_b.invoke(input_data),\n agent_c.invoke(input_data)\n )\n result = combine_results(results)\n return result\n```\n\n资料来源：[python/samples/03-workflows/README.md]()\n\n#### 3.1.2 图工作流（Graph Workflow）\n\n图工作流通过连接执行器和边（Edge）来构建有向无环图（DAG）结构。\n\n```mermaid\ngraph TD\n Start[起始执行器] --> AgentA[代理 A]\n AgentA -->|条件分支| Condition{条件判断}\n Condition -->|true| AgentB[代理 B]\n Condition -->|false| AgentC[代理 C]\n AgentB --> End[结束]\n AgentC --> End\n```\n\n资料来源：[python/samples/03-workflows/README.md]()\n\n### 3.2 声明式工作流（Declarative Workflow）\n\n声明式工作流通过 YAML 文件定义，适合业务逻辑稳定、频繁变更的场景。\n\n#### 3.2.1 基本结构\n\n```yaml\nname: my-workflow\ndescription: 工作流描述\n\nactions:\n - kind: SetValue\n path: turn.greeting\n value: \"你好\"\n\n - kind: SendActivity\n activity:\n text: \"=turn.greeting\"\n```\n\n资料来源：[python/samples/03-workflows/declarative/README.md]()\n\n#### 3.2.2 支持的动作类型\n\n| 动作类型 | 功能描述 |\n|---------|---------|\n| `SetValue` | 设置变量值 |\n| `SetVariable` | 设置变量（.NET 风格命名） |\n| `AppendValue` | 向列表追加值 |\n| `If` | 条件分支 |\n| `Switch` | 多路分支 |\n| `Foreach` | 遍历集合 |\n| `RepeatUntil` | 循环直到条件满足 |\n| `SendActivity` | 向用户发送消息 |\n| `GotoAction` | 跳转到指定标签动作 |\n\n资料来源：[python/samples/03-workflows/declarative/README.md]()\n\n## 4. 系统架构\n\n### 4.1 架构组件\n\n```mermaid\ngraph TD\n subgraph \"Python SDK\"\n PYWF[Python 工作流]\n PYFB[函数式构建器]\n PYGB[图构建器]\n PYDB[声明式构建器]\n end\n \n subgraph \".NET SDK\"\n DNFWF[.NET 工作流]\n DNFB[WorkflowBuilder]\n DNDTB[DeclarativeWorkflowBuilder]\n end\n \n subgraph \"共享组件\"\n EX[Executor 执行器]\n ST[State 状态管理]\n CK[Checkpoint 检查点]\n end\n \n PYWF --> EX\n PYFB --> EX\n PYGB --> EX\n DNFWF --> EX\n DNFB --> EX\n DNDTB --> EX\n \n EX --> ST\n ST --> CK\n```\n\n### 4.2 工作流构建器\n\n#### 4.2.1 Python WorkflowBuilder\n\nPython 版本的 `WorkflowBuilder` 提供链式 API 构建工作流：\n\n```python\nworkflow = WorkflowBuilder(\n start_executor=my_start_executor\n).add_edge(\n from_executor=my_start_executor,\n to_executor=my_next_executor\n).build()\n```\n\n资料来源：[python/packages/core/agent_framework/_workflows/_workflow_builder.py]()\n\n#### 4.2.2 .NET WorkflowBuilder\n\n.NET 版本的 `WorkflowBuilder` 支持依赖注入和配置驱动：\n\n```csharp\nservices.AddAgentsWorkflows(options =>\n{\n options.WorkflowBuilder = workflowBuilder;\n});\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilder.cs]()\n\n#### 4.2.3 DeclarativeWorkflowBuilder\n\n声明式构建器从 YAML 加载工作流定义：\n\n```csharp\nvar workflow = DeclarativeWorkflowBuilder.Build(\"workflow.yaml\", options);\n```\n\n```python\n# Python 版本\nfrom agent_framework_declarative import load_workflow\nworkflow = load_workflow(\"workflow.yaml\")\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs]()\n\n## 5. 执行模型\n\n### 5.1 同步与异步执行\n\n工作流支持同步和异步两种执行模式：\n\n```python\n# 非流式执行\nresult = await workflow.execute(input_data)\n\n# 流式执行\nasync for event in workflow.stream(input_data):\n print(event)\n```\n\n资料来源：[python/packages/core/agent_framework/_workflows/_workflow.py]()\n\n### 5.2 代理调用链\n\n在多代理工作流中，代理可以按顺序调用，形成处理链：\n\n```mermaid\ngraph LR\n A[用户输入] --> B[翻译代理
French Agent]\n B --> C[翻译代理
Spanish Agent]\n C --> D[翻译代理
English Agent]\n D --> E[最终输出]\n```\n\n每个代理接收前一个代理的输出作为输入，实现管道式处理。资料来源：[dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/README.md]()\n\n### 5.3 人机交互（HITL）\n\n声明式工作流支持人类在环（Human-in-the-Loop）模式，允许工作流暂停等待人工输入：\n\n```yaml\nactions:\n - kind: If\n condition: \"turn.needsApproval == true\"\n then:\n - kind: WaitForHumanInput\n timeout: 300\n```\n\n资料来源：[python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/README.md]()\n\n## 6. 状态持久化与检查点\n\n### 6.1 检查点机制\n\n工作流系统支持检查点（Checkpoint）功能，用于保存和恢复工作流执行状态：\n\n```mermaid\ngraph LR\n A[执行中] -->|保存| B[检查点]\n B -->|恢复| C[继续执行]\n B -->|重启| D[从起始执行]\n```\n\nDevUI 可以显示工作流的检查点信息，包括完整的状态快照。资料来源：[python/packages/devui/frontend/src/components/features/workflow/checkpoint-info-modal.tsx]()\n\n### 6.2 状态查看\n\n工作流状态可以通过 DevUI 的工作流视图组件查看：\n\n| 组件 | 功能 |\n|-----|------|\n| 状态徽章 | 显示当前状态变量 |\n| 原始 JSON | 展开查看完整状态 |\n| 检查点列表 | 历史状态快照 |\n\n资料来源：[python/packages/devui/frontend/src/components/features/workflow/workflow-view.tsx]()\n\n## 7. 工具与技能集成\n\n### 7.1 函数工具\n\n工作流中的代理可以调用函数工具（Function Tool）：\n\n```python\n@tool\ndef get_weather(location: str) -> str:\n \"\"\"获取指定位置的天气信息\"\"\"\n return f\"{location} 今天天气晴朗\"\n```\n\n资料来源：[python/samples/01-get-started/README.md]()\n\n### 7.2 技能（Skills）\n\n技能是一种结构化的工具定义方式，支持代码定义和文件定义两种形式：\n\n| 类型 | 描述 |\n|-----|------|\n| 代码定义技能 | 直接在代码中定义 |\n| 文件定义技能 | 通过 `SKILL.md` 文件定义 |\n\n技能可以包含脚本、参考资料和执行命令。资料来源：[python/samples/02-agents/skills/mixed_skills/README.md]()\n\n## 8. 开发工具\n\n### 8.1 DevUI\n\nDevUI 提供了工作流的图形化开发界面：\n\n| 功能 | 说明 |\n|-----|-----|\n| 可视化编辑器 | 编辑和测试工作流 |\n| 实时执行 | 流式显示执行结果 |\n| 检查点查看 | 查看历史状态快照 |\n| 示例库 | 预置工作流示例 |\n\n资料来源：[python/packages/devui/README.md]()\n\n### 8.2 代码导出（Eject）\n\n声明式工作流支持导出为代码，便于进一步定制：\n\n```csharp\nvar code = DeclarativeWorkflowBuilder.Eject(\n \"workflow.yaml\",\n DeclarativeWorkflowLanguage.CSharp,\n \"MyNamespace\"\n);\n```\n\n支持的目标语言：\n\n| 语言 | 枚举值 |\n|-----|-------|\n| Python | `DeclarativeWorkflowLanguage.Python` |\n| C# | `DeclarativeWorkflowLanguage.CSharp` |\n| JavaScript | `DeclarativeWorkflowLanguage.JavaScript` |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs]()\n\n## 9. 快速开始\n\n### 9.1 Python 入门示例\n\n```bash\npip install agent-framework\n```\n\n| 示例 | 文件 | 学习内容 |\n|-----|------|---------|\n| 1 | `01_hello_agent.py` | 创建第一个代理 |\n| 2 | `02_add_tools.py` | 添加函数工具 |\n| 3 | `03_multi_turn.py` | 多轮对话 |\n| 4 | `04_memory.py` | 自定义上下文 |\n| 5 | `05_functional_workflow_with_agents.py` | 函数式工作流 |\n| 6 | `06_functional_workflow_basics.py` | 工作流基础 |\n| 7 | `07_first_graph_workflow.py` | 图工作流 |\n| 8 | `08_host_your_agent.py` | 部署代理 |\n\n资料来源：[python/samples/01-get-started/README.md]()\n\n### 9.2 .NET 入门示例\n\n```bash\ncd dotnet/samples\ndotnet run --project 01-hello-agent\n```\n\n## 10. 最佳实践\n\n1. **选择合适的工作流类型**：业务逻辑稳定时使用声明式工作流，需要复杂逻辑时使用命令式工作流\n2. **合理设计状态结构**：使用清晰的前缀命名（如 `turn.`、`user.`）区分不同来源的数据\n3. **使用检查点恢复**：对于长时间运行的工作流，定期保存检查点便于故障恢复\n4. **流式输出优化**：对延迟敏感的应用使用流式执行模式\n5. **工具封装**：将常用功能封装为工具，便于在多个工作流中复用\n\n## 11. 相关资源\n\n| 资源类型 | 链接 |\n|---------|------|\n| Python 包 | `pip install agent-framework` |\n| 声明式包 | `pip install agent-framework-declarative` |\n| 可视化支持 | `pip install agent-framework[viz]` |\n| 官方文档 | [Agent Framework 文档](https://github.com/microsoft/agent-framework) |\n\n---\n\n\n\n## 工作流编排模式\n\n### 相关页面\n\n相关主题：[工作流系统概述](#workflow-overview), [检查点与恢复机制](#checkpoint-recovery)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/orchestrations/agent_framework_orchestrations/_sequential.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/orchestrations/agent_framework_orchestrations/_sequential.py)\n- [python/packages/orchestrations/agent_framework_orchestrations/_concurrent.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/orchestrations/agent_framework_orchestrations/_concurrent.py)\n- [python/packages/orchestrations/agent_framework_orchestrations/_handoff.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/orchestrations/agent_framework_orchestrations/_handoff.py)\n- [dotnet/src/Microsoft.Agents.AI.Workflows/GroupChatManager.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/GroupChatManager.cs)\n- [dotnet/src/Microsoft.Agents.AI.Workflows/HandoffWorkflowBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/HandoffWorkflowBuilder.cs)\n
\n\n# 工作流编排模式\n\n## 概述\n\n工作流编排（Workflow Orchestration）是Microsoft Agent Framework中的核心能力，它允许开发者将多个代理（Agent）、工具（Tool）和功能组件组合成复杂的自动化流程。Agent Framework提供了多种编排模式，包括顺序执行、并发执行和交接（Handoff）机制，使开发者能够构建从简单到复杂的各种自动化工作流。\n\n工作流编排系统的主要特点包括：\n\n- **声明式定义**：通过Python装饰器或C#构建器模式声明工作流结构\n- **状态管理**：内置的状态传递和上下文共享机制\n- **异步支持**：完整的异步执行模型，支持流式和非流式响应\n- **错误处理**：统一的异常捕获和恢复机制\n- **可扩展性**：支持自定义执行器和节点类型\n\n## 核心组件\n\n### 执行器（Executor）\n\n执行器是工作流编排的基本构建单元，负责执行具体的任务或调用代理。每个执行器可以包含输入参数、执行逻辑和输出处理。\n\n```mermaid\ngraph LR\n A[输入数据] --> B[执行器 Executor]\n B --> C{执行类型}\n C -->|同步| D[同步执行]\n C -->|异步| E[异步执行]\n C -->|流式| F[流式执行]\n D --> G[输出结果]\n E --> G\n F --> G\n```\n\n### 顺序工作流（Sequential Workflow）\n\n顺序工作流按照定义的顺序依次执行各个执行器，前一个执行器的输出作为下一个执行器的输入。这种模式适用于步骤之间存在依赖关系的场景。\n\n**Python实现**：\n\n```python\nfrom agent_framework_orchestrations import SequentialWorkflow, Step\n\nworkflow = SequentialWorkflow(\n steps=[\n Step(executor=data_loader, name=\"load_data\"),\n Step(executor=processor, name=\"process_data\"),\n Step(executor=formatter, name=\"format_output\")\n ]\n)\n```\n\n**C#实现**：\n\n```csharp\nvar workflow = new SequentialWorkflowBuilder()\n .AddStep(dataLoader)\n .AddStep(processor)\n .AddStep(formatter)\n .Build();\n```\n\n### 并发工作流（Concurrent Workflow）\n\n并发工作流允许同时执行多个执行器，通过并行处理提高整体效率。适用于彼此独立、可同时运行的任务。\n\n```mermaid\ngraph TD\n A[开始] --> B[并发执行]\n B --> C[执行器 A]\n B --> D[执行器 B]\n B --> E[执行器 N]\n C --> F[收集结果]\n D --> F\n E --> F\n F --> G[聚合输出]\n G --> H[结束]\n```\n\n**关键参数**：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `max_concurrency` | int | 最大并发数，限制同时运行的任务数量 |\n| `timeout` | timedelta | 单个任务的最大执行时间 |\n| `fail_fast` | bool | 任何任务失败时是否立即停止 |\n\n### 交接工作流（Handoff Workflow）\n\n交接工作流实现了代理之间的上下文传递，允许一个代理将控制权和会话状态移交给另一个代理。这是构建多代理协作系统的核心机制。\n\n```mermaid\ngraph LR\n A[Agent A] -->|Handoff| B[上下文传递]\n B --> C[Agent B]\n B --> D[消息队列]\n D --> C\n C --> E[继续执行]\n```\n\n## 交接机制（Handoff）\n\n### 工作原理\n\n交接机制是Agent Framework中最核心的编排模式之一，它允许：\n\n1. **上下文转移**：当前代理的状态、记忆和对话历史完整传递给下一个代理\n2. **控制权移交**：执行流程从源代理平滑转移到目标代理\n3. **消息传递**：支持通过消息队列进行异步交接\n\n### HandoffWorkflowBuilder（C#）\n\n`HandoffWorkflowBuilder`提供了声明式的交接工作流构建方式：\n\n```csharp\nvar handoffWorkflow = new HandoffWorkflowBuilder(\"transfer_to_specialist\")\n .WithSourceAgent(\"general_agent\")\n .WithTargetAgent(\"specialist_agent\")\n .WithContextMapping(mappings => {\n mappings.Map(\"user_preferences\", \"preferences\");\n mappings.Map(\"conversation_history\", \"history\");\n })\n .WithHandoffMessage(\"正在将您的请求转交给专家代理...\")\n .Build();\n```\n\n**配置选项**：\n\n| 选项 | 说明 |\n|------|------|\n| `WithSourceAgent` | 指定源代理标识符 |\n| `WithTargetAgent` | 指定目标代理标识符 |\n| `WithContextMapping` | 配置上下文字段映射规则 |\n| `WithHandoffMessage` | 设置交接时的提示消息 |\n| `WithRetryPolicy` | 配置交接失败重试策略 |\n\n## 群组聊天管理器（GroupChatManager）\n\n`GroupChatManager`是.NET实现中的群组聊天协调器，负责管理多个代理之间的对话交互和消息路由。\n\n### 核心职责\n\n```mermaid\ngraph TD\n A[用户消息] --> B[GroupChatManager]\n B --> C{路由决策}\n C -->|选择代理| D[代理 A]\n C -->|选择代理| E[代理 B]\n C -->|选择代理| F[代理 N]\n D --> G[响应]\n E --> G\n F --> G\n G --> H[消息汇总]\n H --> I[返回用户]\n```\n\n### 管理功能\n\n| 功能 | 说明 |\n|------|------|\n| 代理注册 | 允许动态注册和注销参与对话的代理 |\n| 消息路由 | 根据规则或AI判断将消息路由到合适的代理 |\n| 状态同步 | 维护所有参与代理的当前状态 |\n| 发言控制 | 管理多代理场景下的发言顺序和权限 |\n\n## 最佳实践\n\n### 1. 工作流设计原则\n\n- **单一职责**：每个执行器应专注于单一任务\n- **松耦合**：执行器之间通过明确定义的接口通信\n- **错误边界**：为关键步骤添加错误处理和回退逻辑\n\n### 2. 性能优化\n\n- **识别并行机会**：分析工作流中的独立步骤，尽量并行化\n- **设置合理超时**：防止单个任务长时间阻塞整个工作流\n- **资源限制**：使用`max_concurrency`控制并发资源使用\n\n### 3. 调试技巧\n\n- **启用详细日志**：使用日志记录每个步骤的输入输出\n- **状态检查点**：在关键节点保存工作流状态便于恢复\n- **逐步执行**：开发阶段使用单步模式验证逻辑\n\n## 相关示例\n\n| 示例文件 | 模式 | 说明 |\n|----------|------|------|\n| `05_functional_workflow_with_agents.py` | 功能工作流 | 在函数式工作流中调用代理 |\n| `06_functional_workflow_basics.py` | 基础功能工作流 | 纯函数组合的工作流 |\n| `07_first_graph_workflow.py` | 图工作流 | 使用边连接执行器构建图 |\n| `08_host_your_agent.py` | 托管代理 | 将代理部署到生产环境 |\n\n## 总结\n\n工作流编排模式是构建复杂AI应用的基础，Agent Framework提供了从简单顺序处理到复杂多代理协作的完整解决方案。开发者可以根据业务需求选择合适的编排模式，并通过框架提供的丰富API实现高效、可靠的工作流系统。\n\n---\n\n\n\n## 检查点与恢复机制\n\n### 相关页面\n\n相关主题：[工作流系统概述](#workflow-overview), [工作流编排模式](#workflow-patterns)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/core/agent_framework/_workflows/_checkpoint.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_workflows/_checkpoint.py)\n- [python/samples/03-workflows/checkpoint/checkpoint_with_resume.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/03-workflows/checkpoint/checkpoint_with_resume.py)\n- [dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs)\n- [dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs)\n
\n\n# 检查点与恢复机制\n\n## 概述\n\n检查点（Checkpoint）与恢复（Resume）机制是 Agent Framework 工作流系统的核心功能之一，它允许长时间运行的工作流在中断后从上一个保存点继续执行，而无需重新开始整个流程。\n\n### 核心能力\n\n| 能力 | 描述 |\n|------|------|\n| 状态持久化 | 保存工作流的完整执行状态到外部存储 |\n| 断点恢复 | 从任意检查点恢复工作流执行 |\n| 会话管理 | 通过会话ID关联多个检查点 |\n| HIL 支持 | 支持人类在环（Human-in-the-Loop）场景下的暂停与恢复 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/ICheckpointManager.cs:1-15]()\n\n---\n\n## 架构设计\n\n### 系统组件图\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n A[Workflow 执行环境] --> B[Checkpoint Manager]\n end\n \n subgraph \"核心接口\"\n C[ICheckpointManager] \n D[IWorkflowExecutionEnvironment]\n end\n \n subgraph \"存储层\"\n E[(检查点存储)]\n F[(会话状态)]\n end\n \n B --> C\n B --> E\n A --> D\n D -->|ResumeAsync| B\n C -->|CommitCheckpointAsync| E\n C -->|LookupCheckpointAsync| F\n \n G[工作流执行器] -->|创建检查点| B\n B -->|返回 CheckpointInfo| G\n```\n\n### 检查点生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 执行中: 开始工作流\n 执行中 --> 暂停: 遇到 HIL / 中断\n 暂停 --> 保存检查点: CommitCheckpointAsync\n 保存检查点 --> 已保存: 返回 CheckpointInfo\n 已保存 --> 恢复执行: ResumeAsync\n 恢复执行 --> 执行中: 加载检查点状态\n 执行中 --> 完成: 正常结束\n 暂停 --> 取消: 用户取消\n 已保存 --> [*]: 清理\n```\n\n资料来源：[python/packages/core/agent_framework/_workflows/_checkpoint.py:1-50]()\n\n---\n\n## 核心数据模型\n\n### CheckpointInfo\n\n检查点信息模型，用于唯一标识和检索检查点。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `SessionId` | `string` | 会话唯一标识符 |\n| `CheckpointId` | `string` | 检查点唯一标识符（自动生成） |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/CheckpointInfo.cs:10-20]()\n\n```csharp\npublic sealed class CheckpointInfo : IEquatable\n{\n public string SessionId { get; }\n public string CheckpointId { get; }\n \n internal CheckpointInfo(string sessionId) \n : this(sessionId, Guid.NewGuid().ToString(\"N\")) { }\n \n public CheckpointInfo(string sessionId, string checkpointId)\n {\n this.SessionId = Throw.IfNullOrEmpty(sessionId);\n this.CheckpointId = Throw.IfNullOrEmpty(checkpointId);\n }\n}\n```\n\n### Checkpoint 接口模型\n\n```mermaid\nclassDiagram\n class Checkpoint {\n +string SessionId\n +string CheckpointId\n +Dictionary state\n +WorkflowTaskMetadata metadata\n +string serialized_state\n }\n \n class CheckpointInfo {\n +string SessionId\n +string CheckpointId\n }\n \n Checkpoint --> CheckpointInfo : 通过 CommitCheckpointAsync 返回\n```\n\n资料来源：[python/packages/core/agent_framework/_workflows/_checkpoint.py:15-35]()\n\n---\n\n## 接口定义\n\n### ICheckpointManager\n\n检查点管理器接口，定义检查点的提交和检索操作。\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/ICheckpointManager.cs:10-40]()\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `CommitCheckpointAsync` | `ValueTask` | 提交检查点并返回检索信息 |\n| `LookupCheckpointAsync` | `ValueTask` | 根据检查点信息检索完整状态 |\n\n#### CommitCheckpointAsync\n\n```csharp\n/// \n/// 提交指定的检查点并返回可用于后续检索的信息\n/// \n/// 当前会话或执行上下文的标识符\n/// 要提交的检查点\n/// 表示传入检查点的 CheckpointInfo\nValueTask CommitCheckpointAsync(string sessionId, Checkpoint checkpoint);\n```\n\n#### LookupCheckpointAsync\n\n```csharp\n/// \n/// 检索与指定检查点信息关联的检查点\n/// \n/// 当前会话的标识符\n/// 用于标识检查点的信息\n/// 包含关联 Checkpoint 的 ValueTask\n/// 如果未找到检查点\nValueTask LookupCheckpointAsync(string sessionId, CheckpointInfo checkpointInfo);\n```\n\n### IWorkflowExecutionEnvironment\n\n工作流执行环境接口，提供从检查点恢复执行的能力。\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowExecutionEnvironment.cs:1-20]()\n\n```csharp\n/// \n/// 从检查点恢复工作流执行\n/// \n/// 要执行的工作流\n/// 要恢复的检查点对应的 CheckpointInfo\n/// 取消令牌\n/// 包含 Run 实例的 ValueTask\nValueTask ResumeAsync(\n Workflow workflow, \n CheckpointInfo fromCheckpoint, \n CancellationToken cancellationToken = default);\n```\n\n---\n\n## Python 实现\n\n### 检查点类结构\n\n资料来源：[python/packages/core/agent_framework/_workflows/_checkpoint.py:1-80]()\n\n```python\nclass Checkpoint:\n \"\"\"工作流执行检查点\"\"\"\n def __init__(\n self,\n state: dict[str, Any],\n checkpoint_id: str,\n session_id: str,\n metadata: Optional[WorkflowTaskMetadata] = None,\n ):\n self.checkpoint_id = checkpoint_id\n self.session_id = session_id\n self.state = state\n self.metadata = metadata\n\nclass CheckpointInfo:\n \"\"\"检查点元信息，用于恢复\"\"\"\n def __init__(\n self,\n checkpoint_id: str,\n session_id: str,\n created_at: datetime,\n ):\n self.checkpoint_id = checkpoint_id\n self.session_id = session_id\n self.created_at = created_at\n```\n\n### 异步检查点管理器\n\n```python\nclass AsyncCheckpointManager(ABC):\n \"\"\"异步检查点管理器基类\"\"\"\n \n @abstractmethod\n async def commit(self, session_id: str, checkpoint: Checkpoint) -> CheckpointInfo:\n \"\"\"提交检查点\"\"\"\n pass\n \n @abstractmethod\n async def lookup(self, session_id: str, checkpoint_info: CheckpointInfo) -> Checkpoint:\n \"\"\"检索检查点\"\"\"\n pass\n \n @abstractmethod\n async def list_checkpoints(self, session_id: str) -> list[CheckpointInfo]:\n \"\"\"列出所有检查点\"\"\"\n pass\n```\n\n资料来源：[python/packages/core/agent_framework/_workflows/_checkpoint.py:80-100]()\n\n---\n\n## 使用示例\n\n### Python 示例：检查点与恢复\n\n资料来源：[python/samples/03-workflows/checkpoint/checkpoint_with_resume.py:1-120]()\n\n```python\nimport asyncio\nfrom agent_framework import Agent, WorkflowBuilder\nfrom agent_framework.workflows import (\n CheckpointManager,\n Checkpoint,\n CheckpointInfo,\n)\n\n# 创建带检查点支持的工作流\nworkflow = WorkflowBuilder(start_executor=my_executor)\\\n .with_checkpointing()\\\n .build()\n\nasync def run_with_checkpoint():\n # 运行工作流并获取检查点\n run = await workflow.run(input_data)\n \n # 在 HIL 暂停点保存检查点\n checkpoint_info = await run.save_checkpoint()\n \n print(f\"检查点已保存: {checkpoint_info.checkpoint_id}\")\n \n # 模拟中断后恢复\n resumed_run = await workflow.resume(\n from_checkpoint=checkpoint_info\n )\n \n return resumed_run\n\nasyncio.run(run_with_checkpoint())\n```\n\n### .NET 示例：检查点与重新水化\n\n资料来源：[dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs:1-80]()\n\n```csharp\nusing Microsoft.Agents.AI.Workflows;\nusing Microsoft.Agents.AI.Workflows.Checkpointing;\n\n// 创建检查点管理器\nICheckpointManager checkpointManager = new CheckpointManagerImpl(storageProvider);\n\n// 执行工作流并获取检查点\nWorkflow workflow = BuildWorkflow();\nvar run = await workflow.RunAsync(inputData);\n\n// 在适当位置提交检查点\nvar checkpointInfo = await checkpointManager.CommitCheckpointAsync(\n sessionId: run.SessionId,\n checkpoint: new Checkpoint\n {\n SessionId = run.SessionId,\n State = run.GetState(),\n Metadata = run.GetMetadata()\n });\n\nConsole.WriteLine($\"检查点已保存: {checkpointInfo.CheckpointId}\");\n\n// 模拟应用重启后恢复\nvar checkpointToResume = new CheckpointInfo(\n sessionId: \"previous-session-id\",\n checkpointId: checkpointInfo.CheckpointId\n);\n\nvar resumedRun = await workflow.ResumeAsync(checkpointToResume);\n```\n\n---\n\n## 检查点管理器实现\n\n### CheckpointManagerImpl\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs:1-100]()\n\n```csharp\ninternal sealed class CheckpointManagerImpl : ICheckpointManager\n{\n private readonly IWorkflowStorage _storage;\n private readonly IWorkflowStateSerializer _serializer;\n\n public async ValueTask CommitCheckpointAsync(\n string sessionId, \n Checkpoint checkpoint)\n {\n // 生成新的检查点ID\n var checkpointInfo = new CheckpointInfo(sessionId);\n \n // 序列化检查点数据\n var serialized = _serializer.Serialize(checkpoint);\n \n // 存储到持久化层\n await _storage.StoreAsync(\n key: GetStorageKey(sessionId, checkpointInfo.CheckpointId),\n data: serialized);\n \n // 更新会话索引\n await UpdateSessionIndexAsync(sessionId, checkpointInfo);\n \n return checkpointInfo;\n }\n\n public async ValueTask LookupCheckpointAsync(\n string sessionId, \n CheckpointInfo checkpointInfo)\n {\n var key = GetStorageKey(sessionId, checkpointInfo.CheckpointId);\n var data = await _storage.RetrieveAsync(key);\n \n if (data == null)\n {\n throw new KeyNotFoundException(\n $\"Checkpoint not found: {checkpointInfo.CheckpointId}\");\n }\n \n return _serializer.Deserialize(data);\n }\n}\n```\n\n---\n\n## DevUI 集成\n\n### 检查点信息模态框\n\nAgent Framework 的 DevUI 组件提供了检查点可视化功能。\n\n资料来源：[python/packages/devui/frontend/src/components/features/workflow/checkpoint-info-modal.tsx:1-80]()\n\n```tsx\ninterface CheckpointInfoModalProps {\n session: WorkflowSession | null;\n checkpoints: CheckpointInfo[];\n open: boolean;\n onOpenChange: (open: boolean) => void;\n}\n```\n\n### 检查点列表展示\n\nDevUI 中的检查点信息模态框包含以下功能：\n\n| 功能 | 说明 |\n|------|------|\n| 时间线视图 | 按创建顺序展示所有检查点 |\n| 状态预览 | 显示每个检查点的工作流状态摘要 |\n| HIL 标识 | 高亮显示待处理 HIL 请求的检查点 |\n| 原始 JSON | 可展开的检查点完整数据视图 |\n\n```tsx\n// 检查点渲染逻辑\ncheckpoints.map((checkpoint, index) => {\n const isSelected = checkpoint.checkpoint_id === selectedCheckpointId;\n const hasHil = checkpoint.metadata?.has_pending_hil;\n\n return (\n
\n setSelectedCheckpointId(checkpoint.checkpoint_id)}\n className={cn(\n \"w-full text-left p-3 rounded-lg border\",\n isSelected ? \"bg-primary/10 border-primary\" : \"hover:bg-muted/50\"\n )}\n >\n {hasHil && ⚠️ HIL Pending}\n \n
\n );\n})\n```\n\n### 工作流视图中的检查点集成\n\n资料来源：[python/packages/devui/frontend/src/components/features/workflow/workflow-view.tsx:1-100]()\n\n```tsx\ninterface WorkflowViewProps {\n // ... 其他属性\n checkpoints: CheckpointInfo[];\n showCheckpoints?: boolean;\n}\n\n// 检查点状态显示\n 0 \n ? \"completed\" \n : \"ready\"\n }\n checkpoints={sessionCheckpoints}\n showCheckpoints={true}\n/>\n```\n\n---\n\n## 配置选项\n\n### 检查点存储配置\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `storage_type` | `string` | `memory` | 存储类型：memory、file、database |\n| `storage_path` | `string` | `./checkpoints` | 文件系统存储路径 |\n| `max_checkpoints` | `int` | `100` | 单个会话最大检查点数量 |\n| `checkpoint_interval` | `int` | `60` | 自动检查点保存间隔（秒） |\n\n### 序列化配置\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `serializer` | `ISerializer` | 检查点序列化器实现 |\n| `compression` | `bool` | 是否启用压缩 |\n| `encryption` | `bool` | 是否启用加密 |\n\n---\n\n## 最佳实践\n\n### 1. 合理设置检查点频率\n\n```mermaid\ngraph LR\n A[工作流执行] --> B{检查点频率}\n B -->|过密| C[存储开销增加]\n B -->|过疏| D[恢复时数据丢失风险]\n C --> E[建议：HIL 点 + 关键步骤]\n D --> E\n```\n\n### 2. HIL 场景下的检查点\n\n```python\nasync def workflow_with_hil():\n workflow = WorkflowBuilder(start_executor=process_executor)\n \n # 在 HIL 点自动保存检查点\n workflow.on_hil_request(lambda ctx: ctx.save_checkpoint())\n \n run = await workflow.run(user_input)\n \n # 等待人类输入\n user_response = await wait_for_user_input()\n \n # 恢复执行\n resumed = await run.resume(user_response)\n```\n\n### 3. 错误恢复策略\n\n```csharp\ntry\n{\n var resumedRun = await workflow.ResumeAsync(checkpointInfo);\n}\ncatch (KeyNotFoundException)\n{\n // 检查点不存在，尝试从头开始\n var freshRun = await workflow.RunAsync(inputData);\n}\ncatch (CorruptedDataException)\n{\n // 检查点数据损坏，尝试上一个有效检查点\n var previousCheckpoint = await FindValidCheckpoint(sessionId);\n var recoveredRun = await workflow.ResumeAsync(previousCheckpoint);\n}\n```\n\n---\n\n## 相关文件索引\n\n| 类别 | 文件路径 |\n|------|----------|\n| Python 核心 | `python/packages/core/agent_framework/_workflows/_checkpoint.py` |\n| Python 示例 | `python/samples/03-workflows/checkpoint/checkpoint_with_resume.py` |\n| .NET 接口 | `dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/ICheckpointManager.cs` |\n| .NET 实现 | `dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs` |\n| .NET 数据模型 | `dotnet/src/Microsoft.Agents.AI.Workflows/CheckpointInfo.cs` |\n| .NET 执行环境 | `dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowExecutionEnvironment.cs` |\n| .NET 示例 | `dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs` |\n| DevUI 组件 | `python/packages/devui/frontend/src/components/features/workflow/checkpoint-info-modal.tsx` |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：microsoft/agent-framework\n\n摘要：发现 23 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CON…。\n\n## 1. 安装坑 · 来源证据：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CON…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CONTENT events\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d329260309954749a2b3b2a9e7135d56 | https://github.com/microsoft/agent-framework/issues/4923 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8f9f05dcb7564f34bdd5902dcea6be27 | https://github.com/microsoft/agent-framework/issues/5785 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49875a7dd60f480a99718cfa30b12723 | https://github.com/microsoft/agent-framework/issues/5708 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression]\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression]\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_58594f7966b84d81924da21ad789effd | https://github.com/microsoft/agent-framework/issues/5707 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安全/权限坑 · 来源证据：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_644a3ed07d2d4bfd8188392b4af687c2 | https://github.com/microsoft/agent-framework/issues/5794 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安全/权限坑 · 来源证据：Anthropic function limit fallback can return empty final response\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Anthropic function limit fallback can return empty final response\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b61b91ca16094a448f8c0eab5e2daaa1 | https://github.com/microsoft/agent-framework/issues/5769 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安全/权限坑 · 来源证据：Python: Add tutorial for building a custom chat client / LLM provider\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Python: Add tutorial for building a custom chat client / LLM provider\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_959e1eeb912a469c89f68f7f12275690 | https://github.com/microsoft/agent-framework/issues/5505 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：python-1.2.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：python-1.2.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f22ed66ae1f44b28b893aa5cbe439c92 | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 来源证据：.NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows CustomStatus 16 KB cap on multi-executor workflows…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：.NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows CustomStatus 16 KB cap on multi-executor workflows with typed outputs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_52da26ae3ace4acb9913ac780bfb6cd0 | https://github.com/microsoft/agent-framework/issues/5745 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：Python: CosmosHistoryProvider Code interpreter tool calls are saved chunk by chunk\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Python: CosmosHistoryProvider Code interpreter tool calls are saved chunk by chunk\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_48aaa2f1026c4afd9e1a1da3a1a862a6 | https://github.com/microsoft/agent-framework/issues/5793 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 来源证据：dotnet-1.5.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：dotnet-1.5.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2b3d3127c36f41798428b164b5444cbb | https://github.com/microsoft/agent-framework/releases/tag/dotnet-1.5.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 配置坑 · 来源证据：python-1.2.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：python-1.2.2\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb88b6cd86e04e199a03cfcf8a97dde6 | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:974445592 | https://github.com/microsoft/agent-framework | README/documentation is current enough for a first validation pass.\n\n## 14. 维护坑 · 来源证据：dotnet-1.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：dotnet-1.4.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e25f39a7081848689e086b1f98f92675 | https://github.com/microsoft/agent-framework/releases/tag/dotnet-1.4.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:974445592 | https://github.com/microsoft/agent-framework | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:974445592 | https://github.com/microsoft/agent-framework | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 18. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:974445592 | https://github.com/microsoft/agent-framework | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 来源证据：Python: OpenAI store=True can silently bypass external HistoryProvider persistence\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Python: OpenAI store=True can silently bypass external HistoryProvider persistence\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36cbde33c0a64127b95d953c65d49c54 | https://github.com/microsoft/agent-framework/issues/5798 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：python-1.2.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：python-1.2.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_aa3fc8cfbbad40f98ea1da9e68eeaa3f | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：python-1.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：python-1.3.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6df4ed99139d4fb0bc182d80b34e9d45 | https://github.com/microsoft/agent-framework/releases/tag/python-1.3.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | release_recency=unknown\n\n\n", "markdown_key": "agent-framework", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:974445592", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/microsoft/agent-framework" }, { "evidence_id": "art_97f588e7fdde430184d67583bc8bfaf2", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/microsoft/agent-framework#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "agent-framework 说明书", "toc": [ "https://github.com/microsoft/agent-framework 项目说明书", "目录", "框架介绍", "框架概述", "核心组件架构", "智能体（Agent）体系", "工具系统（Tools）", "技能系统（Skills）", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "bd0d6070f1708e17cb0c946a17bbe6ee2c01d7cd", "repo_inspection_error": null, "repo_inspection_files": [ "README.md", "docs/FAQS.md", "docs/specs/001-foundry-sdk-alignment.md", "docs/specs/spec-template.md", "docs/design/python-package-setup.md", "docs/decisions/0001-agent-run-response.md", "docs/decisions/0006-userapproval.md", "docs/decisions/0014-feature-collections.md", "docs/decisions/0021-agent-skills-design.md", "docs/decisions/0025-foundry-toolbox-support.md", "docs/decisions/0008-python-subpackages.md", "docs/decisions/0005-python-naming-conventions.md", "docs/decisions/0017-agent-additional-properties.md", "docs/decisions/0021-provider-leading-clients.md", "docs/decisions/0011-create-get-agent-api.md", "docs/decisions/0013-python-get-response-simplification.md", "docs/decisions/0012-python-typeddict-options.md", "docs/decisions/0018-agentthread-serialization.md", "docs/decisions/0004-foundry-sdk-extensions.md", "docs/decisions/0002-agent-tools.md", "docs/decisions/README.md", "docs/decisions/adr-short-template.md", "docs/decisions/0024-codeact-integration.md", "docs/decisions/0022-chat-history-persistence-consistency.md", "docs/decisions/0007-agent-filtering-middleware.md", "docs/decisions/0003-agent-opentelemetry-instrumentation.md", "docs/decisions/0024-prompt-injection-defense.md", "docs/decisions/adr-template.md", "docs/decisions/0016-python-context-middleware.md", "docs/decisions/0010-ag-ui-support.md", "docs/decisions/0016-structured-output.md", "docs/decisions/0020-foundry-agent-type-naming.md", "docs/decisions/0023-foundry-evals-integration.md", "docs/decisions/0009-support-long-running-operations.md", "docs/decisions/0015-agent-run-context.md", "docs/decisions/0019-python-context-compaction-strategy.md", "docs/features/FIDES_IMPLEMENTATION_SUMMARY.md", "docs/features/durable-agents/AGENTS.md", "docs/features/durable-agents/durable-agents-ttl.md", "docs/features/durable-agents/README.md" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# frontend - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 frontend 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`dotnet/.github/skills/build-and-test/SKILL.md`, `dotnet/.github/skills/project-structure/SKILL.md`, `dotnet/.github/skills/verify-dotnet-samples/SKILL.md`, `dotnet/.github/skills/verify-samples-tool/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`dotnet/.github/skills/build-and-test/SKILL.md`, `dotnet/.github/skills/project-structure/SKILL.md`, `dotnet/.github/skills/verify-dotnet-samples/SKILL.md`, `dotnet/.github/skills/verify-samples-tool/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install agent-framework` 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`dotnet/.github/skills/build-and-test/SKILL.md`, `dotnet/.github/skills/project-structure/SKILL.md`, `dotnet/.github/skills/verify-dotnet-samples/SKILL.md`, `dotnet/.github/skills/verify-samples-tool/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`dotnet/.github/skills/build-and-test/SKILL.md`, `dotnet/.github/skills/project-structure/SKILL.md`, `dotnet/.github/skills/verify-dotnet-samples/SKILL.md`, `dotnet/.github/skills/verify-samples-tool/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`dotnet/.github/skills/build-and-test/SKILL.md`, `dotnet/.github/skills/project-structure/SKILL.md`, `dotnet/.github/skills/verify-dotnet-samples/SKILL.md`, `dotnet/.github/skills/verify-samples-tool/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`dotnet/.github/skills/build-and-test/SKILL.md`, `dotnet/.github/skills/project-structure/SKILL.md`, `dotnet/.github/skills/verify-dotnet-samples/SKILL.md`, `dotnet/.github/skills/verify-samples-tool/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0005` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`dotnet/.github/skills/build-and-test/SKILL.md`, `dotnet/.github/skills/project-structure/SKILL.md`, `dotnet/.github/skills/verify-dotnet-samples/SKILL.md`, `dotnet/.github/skills/verify-samples-tool/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：4555\n- 重要文件覆盖：40/4555\n- 证据索引条目：96\n- 角色 / Skill 条目：16\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 frontend 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 frontend 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 frontend 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 16 个角色 / Skill / 项目文档条目。\n\n- **build-and-test**（skill）：How to build and test .NET projects in the Agent Framework repository. Use this when verifying or testing changes. 激活提示：当用户任务与“build-and-test”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`dotnet/.github/skills/build-and-test/SKILL.md`\n- **project-structure**（skill）：Explains the project structure of the agent-framework .NET solution 激活提示：当用户任务与“project-structure”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`dotnet/.github/skills/project-structure/SKILL.md`\n- **verify-dotnet-samples**（skill）：How to build, run and verify the .NET sample projects in the Agent Framework repository. Use this when a user wants to verify that the samples still function as expected. 激活提示：当用户任务与“verify-dotnet-samples”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`dotnet/.github/skills/verify-dotnet-samples/SKILL.md`\n- **verify-samples-tool**（skill）：How to use the verify-samples tool to run, verify, and manage sample definitions in the Agent Framework repository. Use this when adding, updating, or running sample verification. 激活提示：当用户任务与“verify-samples-tool”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`dotnet/.github/skills/verify-samples-tool/SKILL.md`\n- **unit-converter**（skill）：Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms. 激活提示：当用户任务与“unit-converter”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/skills/unit-converter/SKILL.md`\n- **unit-converter**（skill）：Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms. 激活提示：当用户任务与“unit-converter”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`dotnet/samples/02-agents/AgentSkills/Agent_Step04_MixedSkills/skills/unit-converter/SKILL.md`\n- **python-code-quality**（skill）： 激活提示：当用户任务与“python-code-quality”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`python/.github/skills/python-code-quality/SKILL.md`\n- **python-development**（skill）： 激活提示：当用户任务与“python-development”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`python/.github/skills/python-development/SKILL.md`\n- **python-feature-lifecycle**（skill）： 激活提示：当用户任务与“python-feature-lifecycle”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`python/.github/skills/python-feature-lifecycle/SKILL.md`\n- **python-package-management**（skill）： 激活提示：当用户任务与“python-package-management”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`python/.github/skills/python-package-management/SKILL.md`\n- **python-samples**（skill）： 激活提示：当用户任务与“python-samples”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`python/.github/skills/python-samples/SKILL.md`\n- **python-testing**（skill）： 激活提示：当用户任务与“python-testing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`python/.github/skills/python-testing/SKILL.md`\n- **unit-converter**（skill）：Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms. 激活提示：当用户任务与“unit-converter”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`python/samples/02-agents/skills/file_based_skill/skills/unit-converter/SKILL.md`\n- **unit-converter**（skill）：Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms. 激活提示：当用户任务与“unit-converter”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`python/samples/02-agents/skills/mixed_skills/skills/unit-converter/SKILL.md`\n- **length-converter**（skill）：Convert between common length units miles, km, feet, meters using a multiplication factor. 激活提示：当用户任务与“length-converter”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`python/samples/02-agents/skills/skill_filtering/skills/length-converter/SKILL.md`\n- **volume-converter**（skill）：Convert between gallons and liters using a conversion factor. 激活提示：当用户任务与“volume-converter”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`python/samples/02-agents/skills/skill_filtering/skills/volume-converter/SKILL.md`\n\n## 证据索引\n\n- 共索引 96 条证据。\n\n- **Architectural Decision Records ADRs**（documentation）：Architectural Decision Records ADRs 证据：`docs/decisions/README.md`\n- **AGENTS.md**（documentation）：Instructions for AI coding agents working on durable agents documentation. 证据：`docs/features/durable-agents/AGENTS.md`\n- **Durable agents**（documentation）：Durable agents extend the standard Microsoft Agent Framework with durable state management powered by the Durable Task framework. An ordinary Agent Framework agent runs in-process: its conversation history lives in memory and is lost when the process ends. A durable agent persists conversation history and execution state in external storage so that sessions survive process restarts, failures, and scale-out events. 证据：`docs/features/durable-agents/README.md`\n- **Vector Stores and Embeddings**（documentation）：This feature ports the vector store abstractions, embedding generator abstractions, and their implementations from Semantic Kernel into Agent Framework. The ported code follows AF's coding standards, feels native to AF, and is structured to allow data models/schemas to be reusable across both frameworks. The embedding abstraction combines the best of SK's EmbeddingGeneratorBase and MEAI's IEmbeddingGenerator . 证据：`docs/features/vector-stores-and-embeddings/README.md`\n- **Welcome to Microsoft Agent Framework!**（documentation）：! Microsoft Agent Framework docs/assets/readme-banner.png 证据：`README.md`\n- **AGENTS.md**（documentation）：Instructions for AI coding agents working in the .NET codebase. 证据：`dotnet/AGENTS.md`\n- **Get Started with Microsoft Agent Framework for C Developers**（documentation）：Get Started with Microsoft Agent Framework for C Developers 证据：`dotnet/README.md`\n- **AGENTS.md**（documentation）：Instructions for AI coding agents working in the Python codebase. 证据：`python/AGENTS.md`\n- **Get Started with Microsoft Agent Framework for Python Developers**（documentation）：Get Started with Microsoft Agent Framework for Python Developers 证据：`python/README.md`\n- **Declarative Agents**（documentation）：This folder contains sample agent definitions that can be run using the declarative agent support, for python see the declarative agent python sample folder ../../python/samples/02-agents/declarative/ . 证据：`declarative-agents/agent-samples/README.md`\n- **Declarative Workflows**（documentation）：A Declarative Workflow is defined as a single YAML file and may be executed locally no different from any regular Workflow that is defined by code. 证据：`declarative-agents/workflow-samples/README.md`\n- **A2A Agent as Function Tools**（documentation）：This sample demonstrates how to represent an A2A agent as a set of function tools, where each function tool corresponds to a skill of the A2A agent, and register these function tools with another AI agent so it can leverage the A2A agent's skills. 证据：`dotnet/samples/02-agents/A2A/A2AAgent_AsFunctionTools/README.md`\n- **Polling for A2A Agent Task Completion**（documentation）：Polling for A2A Agent Task Completion 证据：`dotnet/samples/02-agents/A2A/A2AAgent_PollingForTaskCompletion/README.md`\n- **A2A Agent Protocol Selection**（documentation）：This sample demonstrates how to select the A2A protocol binding when creating an AIAgent from an A2A agent card. 证据：`dotnet/samples/02-agents/A2A/A2AAgent_ProtocolSelection/README.md`\n- **A2A Agent Stream Reconnection**（documentation）：This sample demonstrates how to reconnect to an A2A agent's streaming response using continuation tokens, allowing recovery from stream interruptions without losing progress. 证据：`dotnet/samples/02-agents/A2A/A2AAgent_StreamReconnection/README.md`\n- **Agent-to-Agent A2A Samples**（documentation）：These samples demonstrate how to work with Agent-to-Agent A2A specific features in the Agent Framework. 证据：`dotnet/samples/02-agents/A2A/README.md`\n- **AG-UI Getting Started Samples**（documentation）：This directory contains samples that demonstrate how to build AG-UI Agent UI Protocol servers and clients using the Microsoft Agent Framework. 证据：`dotnet/samples/02-agents/AGUI/README.md`\n- **OpenTelemetry Aspire Demo with Azure OpenAI**（documentation）：OpenTelemetry Aspire Demo with Azure OpenAI 证据：`dotnet/samples/02-agents/AgentOpenTelemetry/README.md`\n- **Prerequisites**（documentation）：Before you begin, ensure you have the following prerequisites: 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_A2A/README.md`\n- **Creating an AIAgent with Anthropic**（documentation）：This sample demonstrates how to create an AIAgent using Anthropic Claude models as the underlying inference service. 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_Anthropic/README.md`\n- **Classic Foundry Agents**（documentation）：This sample demonstrates how to create an agent using the classic Foundry Agents experience. 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_AzureAIAgentsPersistent/README.md`\n- **New Foundry Agents**（documentation）：This sample demonstrates how to create an agent using the new Foundry Agents experience. 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_AzureAIProject/README.md`\n- **Overview**（documentation）：This sample shows how to use the OpenAI SDK to create and use a simple AI agent with any model hosted in Microsoft Foundry. 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_AzureFoundryModel/README.md`\n- **Prerequisites**（documentation）：Before you begin, ensure you have the following prerequisites: 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_AzureOpenAIChatCompletion/README.md`\n- **Prerequisites**（documentation）：Before you begin, ensure you have the following prerequisites: 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_AzureOpenAIResponses/README.md`\n- **Agent with Custom Implementation**（documentation）：This sample demonstrates how to create a fully custom agent implementation without relying on external AI services. 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_CustomImplementation/README.md`\n- **Prerequisites**（documentation）：⚠️ WARNING: Container Recommendation GitHub Copilot can execute tools and commands that may interact with your system. For safety, it is strongly recommended to run this sample in a containerized environment e.g., Docker, Dev Container to avoid unintended consequences to your machine. 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/README.md`\n- **Creating an AIAgent with Google Gemini**（documentation）：Creating an AIAgent with Google Gemini 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_GoogleGemini/README.md`\n- **Prerequisites**（documentation）：WARNING: ONNX doesn't support function calling, so any function tools passed to the agent will be ignored. 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_ONNX/README.md`\n- **Prerequisites**（documentation）：Before you begin, ensure you have the following prerequisites: 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_Ollama/README.md`\n- **Prerequisites**（documentation）：Before you begin, ensure you have the following prerequisites: 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_OpenAIChatCompletion/README.md`\n- **Prerequisites**（documentation）：Before you begin, ensure you have the following prerequisites: 证据：`dotnet/samples/02-agents/AgentProviders/Agent_With_OpenAIResponses/README.md`\n- **Creating an AIAgent instance for various providers**（documentation）：Creating an AIAgent instance for various providers 证据：`dotnet/samples/02-agents/AgentProviders/README.md`\n- **File-Based Agent Skills Sample**（documentation）：This sample demonstrates how to use file-based Agent Skills with a ChatClientAgent . 证据：`dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/README.md`\n- **Code-Defined Agent Skills Sample**（documentation）：This sample demonstrates how to define Agent Skills entirely in code using AgentInlineSkill . 证据：`dotnet/samples/02-agents/AgentSkills/Agent_Step02_CodeDefinedSkills/README.md`\n- **Class-Based Agent Skills Sample**（documentation）：This sample demonstrates how to define Agent Skills as C classes using AgentClassSkill with attributes for automatic script and resource discovery. 证据：`dotnet/samples/02-agents/AgentSkills/Agent_Step03_ClassBasedSkills/README.md`\n- **Mixed Agent Skills Sample Advanced**（documentation）：This sample demonstrates an advanced scenario : combining multiple skill types in a single agent using AgentSkillsProviderBuilder . 证据：`dotnet/samples/02-agents/AgentSkills/Agent_Step04_MixedSkills/README.md`\n- **Agent Skills with Dependency Injection**（documentation）：Agent Skills with Dependency Injection 证据：`dotnet/samples/02-agents/AgentSkills/Agent_Step05_SkillsWithDI/README.md`\n- **AgentSkills Samples**（documentation）：Samples demonstrating Agent Skills capabilities. Each sample shows a different way to define and use skills. 证据：`dotnet/samples/02-agents/AgentSkills/README.md`\n- **Running a simple agent with Anthropic**（documentation）：Running a simple agent with Anthropic 证据：`dotnet/samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step01_Running/README.md`\n- **Using reasoning with Anthropic agents**（documentation）：Using reasoning with Anthropic agents 证据：`dotnet/samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step02_Reasoning/README.md`\n- **Using Function Tools with Anthropic agents**（documentation）：Using Function Tools with Anthropic agents 证据：`dotnet/samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools/README.md`\n- **Using Anthropic Skills with agents**（documentation）：This sample demonstrates how to use Anthropic-managed Skills with AI agents. Skills are pre-built capabilities provided by Anthropic that can be used with the Claude API. 证据：`dotnet/samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/README.md`\n- **Getting started with agents using Anthropic**（documentation）：Getting started with agents using Anthropic 证据：`dotnet/samples/02-agents/AgentWithAnthropic/README.md`\n- **AgentWithCodeAct Step01 Interpreter**（documentation）：AgentWithCodeAct Step01 Interpreter 证据：`dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step01_Interpreter/README.md`\n- **AgentWithCodeAct Step02 ToolEnabled**（documentation）：AgentWithCodeAct Step02 ToolEnabled 证据：`dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step02_ToolEnabled/README.md`\n- **AgentWithCodeAct Step03 ManualWiring**（documentation）：AgentWithCodeAct Step03 ManualWiring 证据：`dotnet/samples/02-agents/AgentWithCodeAct/AgentWithCodeAct_Step03_ManualWiring/README.md`\n- **Agent Framework CodeAct Hyperlight Samples**（documentation）：Agent Framework CodeAct Hyperlight Samples 证据：`dotnet/samples/02-agents/AgentWithCodeAct/README.md`\n- **Agent with Memory Using Microsoft Foundry**（documentation）：Agent with Memory Using Microsoft Foundry 证据：`dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/README.md`\n- **Bounded Chat History with Vector Store Overflow**（documentation）：Bounded Chat History with Vector Store Overflow 证据：`dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step05_BoundedChatHistory/README.md`\n- **Agent Framework Retrieval Augmented Generation RAG**（documentation）：Agent Framework Retrieval Augmented Generation RAG 证据：`dotnet/samples/02-agents/AgentWithMemory/README.md`\n- **Creating an Agent from a ChatClient**（documentation）：Creating an Agent from a ChatClient 证据：`dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/README.md`\n- **Creating an Agent from an OpenAIResponseClient**（documentation）：Creating an Agent from an OpenAIResponseClient 证据：`dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/README.md`\n- **Managing Conversation State with OpenAI**（documentation）：Managing Conversation State with OpenAI 证据：`dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/README.md`\n- **Code Interpreter File Download OpenAI**（documentation）：Code Interpreter File Download OpenAI 证据：`dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step06_CodeInterpreterFileDownload/README.md`\n- **Agent Framework with OpenAI**（documentation）：These samples show how to use the Agent Framework with the OpenAI exchange types. 证据：`dotnet/samples/02-agents/AgentWithOpenAI/README.md`\n- **Agent Framework Retrieval Augmented Generation RAG with an external Vector Store with a custom schema**（documentation）：Agent Framework Retrieval Augmented Generation RAG with an external Vector Store with a custom schema 证据：`dotnet/samples/02-agents/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/README.md`\n- **Agent Framework Retrieval Augmented Generation RAG with Neo4j GraphRAG**（documentation）：Agent Framework Retrieval Augmented Generation RAG with Neo4j GraphRAG 证据：`dotnet/samples/02-agents/AgentWithRAG/AgentWithRAG_Step05_Neo4jGraphRAG/README.md`\n- **Agent Framework Retrieval Augmented Generation RAG**（documentation）：Agent Framework Retrieval Augmented Generation RAG 证据：`dotnet/samples/02-agents/AgentWithRAG/README.md`\n- **Structured Output with ChatClientAgent**（documentation）：Structured Output with ChatClientAgent 证据：`dotnet/samples/02-agents/Agents/Agent_Step02_StructuredOutput/README.md`\n- 其余 36 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/decisions/README.md`, `docs/features/durable-agents/AGENTS.md`, `docs/features/durable-agents/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/decisions/README.md`, `docs/features/durable-agents/AGENTS.md`, `docs/features/durable-agents/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **框架介绍**：importance `high`\n - source_paths: README.md, python/AGENTS.md, dotnet/AGENTS.md\n- **安装与配置**：importance `high`\n - source_paths: python/pyproject.toml, python/DEV_SETUP.md, dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj\n- **系统架构**：importance `high`\n - source_paths: python/packages/core/agent_framework/_agents.py, python/packages/core/agent_framework/_workflows/_workflow.py, dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs, dotnet/src/Microsoft.Agents.AI.Workflows/Workflow.cs\n- **核心概念**：importance `high`\n - source_paths: python/packages/core/agent_framework/_types.py, python/packages/core/agent_framework/_sessions.py, dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs, dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs\n- **Agent 基础**：importance `high`\n - source_paths: python/packages/core/agent_framework/_agents.py, python/samples/01-get-started/01_hello_agent.py, dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs, dotnet/samples/01-get-started/01_hello_agent/Program.cs\n- **模型提供商集成**：importance `high`\n - source_paths: python/packages/openai/agent_framework_openai/_chat_client.py, python/packages/foundry/agent_framework_foundry/_chat_client.py, python/packages/anthropic/agent_framework_anthropic/_chat_client.py, dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs, dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs\n- **工具与技能系统**：importance `high`\n - source_paths: python/packages/core/agent_framework/_tools.py, python/packages/core/agent_framework/_skills.py, dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs, dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs\n- **工作流系统概述**：importance `high`\n - source_paths: python/packages/core/agent_framework/_workflows/_workflow.py, python/packages/core/agent_framework/_workflows/_workflow_builder.py, dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilder.cs, dotnet/src/Microsoft.Agents.AI.Workflows/Executor.cs\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `bd0d6070f1708e17cb0c946a17bbe6ee2c01d7cd`\n- inspected_files: `README.md`, `docs/FAQS.md`, `docs/specs/001-foundry-sdk-alignment.md`, `docs/specs/spec-template.md`, `docs/design/python-package-setup.md`, `docs/decisions/0001-agent-run-response.md`, `docs/decisions/0006-userapproval.md`, `docs/decisions/0014-feature-collections.md`, `docs/decisions/0021-agent-skills-design.md`, `docs/decisions/0025-foundry-toolbox-support.md`, `docs/decisions/0008-python-subpackages.md`, `docs/decisions/0005-python-naming-conventions.md`, `docs/decisions/0017-agent-additional-properties.md`, `docs/decisions/0021-provider-leading-clients.md`, `docs/decisions/0011-create-get-agent-api.md`, `docs/decisions/0013-python-get-response-simplification.md`, `docs/decisions/0012-python-typeddict-options.md`, `docs/decisions/0018-agentthread-serialization.md`, `docs/decisions/0004-foundry-sdk-extensions.md`, `docs/decisions/0002-agent-tools.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CON…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CONTENT events\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d329260309954749a2b3b2a9e7135d56 | https://github.com/microsoft/agent-framework/issues/4923 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x)\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8f9f05dcb7564f34bdd5902dcea6be27 | https://github.com/microsoft/agent-framework/issues/5785 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_49875a7dd60f480a99718cfa30b12723 | https://github.com/microsoft/agent-framework/issues/5708 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression]\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression]\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_58594f7966b84d81924da21ad789effd | https://github.com/microsoft/agent-framework/issues/5707 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_644a3ed07d2d4bfd8188392b4af687c2 | https://github.com/microsoft/agent-framework/issues/5794 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：Anthropic function limit fallback can return empty final response\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Anthropic function limit fallback can return empty final response\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_b61b91ca16094a448f8c0eab5e2daaa1 | https://github.com/microsoft/agent-framework/issues/5769 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Python: Add tutorial for building a custom chat client / LLM provider\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Python: Add tutorial for building a custom chat client / LLM provider\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_959e1eeb912a469c89f68f7f12275690 | https://github.com/microsoft/agent-framework/issues/5505 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：python-1.2.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：python-1.2.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_f22ed66ae1f44b28b893aa5cbe439c92 | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：.NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows CustomStatus 16 KB cap on multi-executor workflows…\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：.NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows CustomStatus 16 KB cap on multi-executor workflows with typed outputs\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_52da26ae3ace4acb9913ac780bfb6cd0 | https://github.com/microsoft/agent-framework/issues/5745 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：Python: CosmosHistoryProvider Code interpreter tool calls are saved chunk by chunk\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Python: CosmosHistoryProvider Code interpreter tool calls are saved chunk by chunk\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_48aaa2f1026c4afd9e1a1da3a1a862a6 | https://github.com/microsoft/agent-framework/issues/5793 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：microsoft/agent-framework\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CON…（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x)（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression]（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/microsoft/agent-framework 项目说明书\n\n生成时间：2026-05-13 17:14:16 UTC\n\n## 目录\n\n- [框架介绍](#introduction)\n- [安装与配置](#installation)\n- [系统架构](#architecture)\n- [核心概念](#core-concepts)\n- [Agent 基础](#agent-basics)\n- [模型提供商集成](#agent-providers)\n- [工具与技能系统](#agent-tools)\n- [工作流系统概述](#workflow-overview)\n- [工作流编排模式](#workflow-patterns)\n- [检查点与恢复机制](#checkpoint-recovery)\n\n\n\n## 框架介绍\n\n### 相关页面\n\n相关主题：[安装与配置](#installation), [系统架构](#architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/microsoft/agent-framework/blob/main/README.md)\n- [python/AGENTS.md](https://github.com/microsoft/agent-framework/blob/main/python/AGENTS.md)\n- [dotnet/AGENTS.md](https://github.com/microsoft/agent-framework/blob/main/dotnet/AGENTS.md)\n- [dotnet/src/Shared/Foundry/Agents/README.md](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Shared/Foundry/Agents/README.md)\n- [python/samples/01-get-started/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md)\n- [python/packages/declarative/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/declarative/README.md)\n
\n\n# 框架介绍\n\nMicrosoft Agent Framework（微软智能体框架）是一个跨平台的智能体（Agent）开发框架，旨在帮助开发者快速构建、部署和管理 AI 智能体应用。该框架提供了丰富的工具、运行时和 SDK，支持多种编程语言和部署场景。\n\n## 框架概述\n\nAgent Framework 由微软开发维护，是一个现代化的 AI 智能体开发平台。框架的核心设计理念是提供一个统一且灵活的架构，使开发者能够轻松创建具有对话能力、工具调用能力、工作流编排能力的高级 AI 应用。\n\n该框架支持两种主要的开发语言生态：\n\n| 编程语言 | SDK 包名 | 定位 |\n|---------|---------|------|\n| Python | `agent-framework` | 主要面向 Python 开发者，提供完整的智能体开发能力 |\n| .NET/C# | Microsoft.Agents.AI | 面向 .NET 生态，提供企业级智能体支持 |\n\n资料来源：[README.md:1]()\n\n## 核心组件架构\n\n### Python SDK 组件\n\nPython SDK 是框架的主要实现之一，提供了从基础智能体创建到复杂工作流编排的完整能力。\n\n```\ngraph TD\n A[用户应用] --> B[agent-framework SDK]\n B --> C[Agent 智能体]\n B --> D[Workflow 工作流]\n B --> E[Tools 工具]\n C --> F[ChatClient 聊天客户端]\n D --> G[Graph Workflow 图工作流]\n D --> H[Functional Workflow 函数式工作流]\n```\n\nPython SDK 的核心包结构：\n\n- `agent-framework` - 核心包，包含智能体、工具和工作流的基础类\n- `agent-framework-declarative` - 声明式包，支持通过 YAML 规范构建智能体\n\n资料来源：[python/AGENTS.md:1]()\n\n### .NET SDK 组件\n\n.NET SDK 提供企业级的智能体开发支持，集成了多种 AI 服务和托管选项。\n\n| 组件命名空间 | 功能说明 |\n|------------|---------|\n| `Microsoft.Agents.AI` | 核心 AI 抽象和接口定义 |\n| `Microsoft.Agents.AI.Hosting.OpenAI` | OpenAI 托管集成 |\n| `Microsoft.Agents.AI.GitHub.Copilot` | GitHub Copilot 客户端集成 |\n| `Microsoft.Agents.AI.AzureAI.Persistent` | Azure AI 持久化智能体客户端 |\n| `Microsoft.Agents.AI.Skills` | 智能体技能（Skills）管理系统 |\n\n资料来源：[dotnet/AGENTS.md:1]()\n\n## 智能体（Agent）体系\n\n智能体是框架的核心抽象单元，代表一个能够理解自然语言、执行工具调用、维护对话状态的 AI 实例。\n\n### ChatClientAgent\n\n`ChatClientAgent` 是框架中最基础的智能体类型，它通过 `IChatClient` 接口与底层聊天服务交互。这种设计实现了智能体逻辑与底层 AI 服务的解耦。\n\n```csharp\n// 创建一个基础智能体的核心参数\npublic class ChatClientAgent\n{\n string? Instructions { get; } // 系统指令\n string? Name { get; } // 智能体名称\n string? Description { get; } // 智能体描述\n IList? Tools { get; } // 可用工具列表\n ILoggerFactory? LoggerFactory { get; } // 日志工厂\n IServiceProvider? Services { get; } // 依赖服务\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs:1]()\n\n### 智能体创建流程\n\n```\ngraph LR\n A[配置模型] --> B[定义工具]\n B --> C[设置指令]\n C --> D[创建 Agent 实例]\n D --> E[建立会话]\n E --> F[发送消息/接收响应]\n```\n\n### AgentId 标识模型\n\n每个智能体都有一个唯一的标识符，用于在分布式系统中追踪和管理智能体实例。\n\n```csharp\npublic sealed class AgentId\n{\n public AgentIdType Type { get; init; } // 标识类型\n public string Name { get; init; } // 智能体名称\n public string Version { get; init; } // 版本号\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs:1]()\n\n## 工具系统（Tools）\n\n工具系统使智能体能够执行外部操作，扩展了纯对话的能力边界。\n\n### 工具定义结构\n\n| 属性 | 类型 | 说明 |\n|-----|------|-----|\n| Name | string | 工具名称，用于标识和调用 |\n| Description | string | 工具功能描述，供 AI 理解用途 |\n| Parameters | Schema | 参数模式定义 |\n| Handler | Delegate | 实际执行逻辑 |\n\n框架支持两种工具定义方式：\n\n1. **代码定义工具** - 通过装饰器或接口直接在代码中实现\n2. **文件定义工具** - 通过 YAML/JSON 配置文件声明\n\n资料来源：[python/samples/01-get-started/README.md:1]()\n\n### 工具资源管理\n\n智能体的工具可以关联资源（Resources），这些资源在运行时被注入到工具执行上下文中。\n\n```csharp\npublic abstract class AgentSkill\n{\n // 技能关联的资源列表\n public virtual IReadOnlyList? Resources => null;\n \n // 技能关联的脚本列表\n public virtual IReadOnlyList? Scripts => null;\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs:1]()\n\n## 技能系统（Skills）\n\n技能系统是框架的高级特性，允许开发者将领域知识、操作流程和资源打包成可复用的模块。\n\n### AgentSkillsProvider\n\n`AgentSkillsProvider` 是技能系统的核心组件，它负责：\n\n- 加载和组织技能定义\n- 将技能转换为 AI 可理解的提示词\n- 管理技能相关的工具和脚本执行\n- 提供上下文感知的技能推荐\n\n```csharp\npublic sealed partial class AgentSkillsProvider : AIContextProvider\n{\n // 技能列表占位符\n private const string SkillsPlaceholder = \"{skills}\";\n \n // 脚本指令占位符\n private const string ScriptInstructionsPlaceholder = \"{script_instructions}\";\n \n // 资源指令占位符\n private const string ResourceInstructionsPlaceholder = \"{resource_instructions}\";\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs:1]()\n\n### 技能指令模板\n\n框架使用预定义的提示词模板来组织技能信息：\n\n```\n你有权访问包含领域特定知识和能力的技能。\n每个技能为特定任务提供专业指导、参考文档和资源。\n\n\n{skills}\n\n\n当任务与某个技能的领域匹配时，按以下步骤操作：\n- 使用 `load_skill` 加载技能指令\n- 遵循提供的指导\n{resource_instructions}\n{script_instructions}\n只加载所需内容，按需加载。\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs:1]()\n\n### 技能类型\n\n| 技能类型 | 说明 | 使用场景 |\n|---------|------|---------|\n| 文件技能（File-Based） | 基于 SKILL.md 文件定义 | 知识型技能、内容管理 |\n| 代码技能（Code-Defined） | 通过代码接口实现 | 动态逻辑、自定义行为 |\n| 混合技能（Mixed） | 结合文件和代码 | 复杂业务逻辑 |\n\n资料来源：[python/packages/declarative/README.md:1]()\n\n### 技能配置选项\n\n```csharp\npublic sealed class AgentSkillsProviderOptions\n{\n // 自定义技能提示模板\n public string? SkillsInstructionPrompt { get; set; }\n \n // 脚本执行是否需要审批\n public bool ScriptApproval { get; set; }\n \n // 是否禁用工具和指令缓存\n public bool DisableCaching { get; set; }\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProviderOptions.cs:1]()\n\n## 工作流系统（Workflows）\n\n框架提供了两种工作流编写范式，满足不同复杂度和可维护性需求。\n\n### 函数式工作流\n\n函数式工作流将工作流定义为普通的异步函数，简洁直观。\n\n```python\n# 简单示例：异步函数即工作流\nasync def my_workflow(input_data):\n result = await agent.run(input_data)\n return process_result(result)\n```\n\n资料来源：[python/samples/01-get-started/README.md:1]()\n\n### 图工作流\n\n图工作流通过有向图组织多个执行节点，支持复杂的条件分支和并行执行。\n\n```\ngraph TD\n A[开始节点] --> B[执行器1]\n A --> C[执行器2]\n B --> D[决策节点]\n C --> D\n D -->|条件A| E[执行器3]\n D -->|条件B| F[执行器4]\n E --> G[结束节点]\n F --> G\n```\n\n图工作流的核心概念：\n\n| 概念 | 说明 |\n|-----|------|\n| 节点（Node） | 工作流中的处理单元 |\n| 边（Edge） | 节点间的数据流向和控制关系 |\n| 输入/输出 | 数据的注入和产出 |\n\n资料来源：[python/samples/01-get-started/README.md:1]()\n\n## 会话管理（Session）\n\n`AgentSession` 管理智能体的对话状态，支持多轮对话和上下文维护。\n\n```python\n# 建立会话\nsession = AgentSession(\n agent=my_agent,\n thread_id=\"unique-thread-id\"\n)\n\n# 多轮对话\nasync with session:\n response1 = await session.run(\"你好\")\n response2 = await session.run(\"帮我查询天气\")\n response3 = await session.run(\"谢谢\") # 上下文保持\n```\n\n会话管理的关键特性：\n\n- **线程隔离** - 每个会话有独立的对话历史\n- **状态持久化** - 支持跨请求的状态恢复\n- **上下文传递** - 自动维护对话上下文\n\n资料来源：[python/samples/01-get-started/README.md:1]()\n\n## 上下文提供者（Context Provider）\n\n`ContextProvider` 允许开发者自定义上下文注入逻辑，为智能体提供动态的补充信息。\n\n```python\nclass MyContextProvider(ContextProvider):\n async def provide_context(self, session, request):\n # 从外部获取相关上下文\n user_profile = await get_user_profile(session.user_id)\n return {\"user\": user_profile}\n```\n\n上下文提供者的工作流程：\n\n```\ngraph LR\n A[请求进入] --> B[ContextProvider.provide_context]\n B --> C[聚合上下文数据]\n C --> D[注入系统提示]\n D --> E[发送给 AI]\n E --> F[处理响应]\n F --> G[返回结果]\n```\n\n资料来源：[python/samples/01-get-started/README.md:1]()\n\n## Azure AI 集成\n\n框架通过 `PersistentAgentsClient` 提供与 Azure AI Foundry Agents 服务的深度集成。\n\n```csharp\n// 已废弃，请使用最新的 Foundry Agents 服务\n[Obsolete(\"Please use the latest Foundry Agents service via the Microsoft.Agents.AI.AzureAI package.\")]\npublic static async Task CreateAIAgentAsync(\n this PersistentAgentsClient persistentAgentsClient,\n string model,\n string? name = null,\n string? description = null,\n string? instructions = null,\n IEnumerable? tools = null,\n ToolResources? toolResources = null,\n float? temperature = null,\n float? topP = null,\n string? responseFormat = null,\n IDictionary? metadata = null,\n IChatClientFactory? clientFactory = null,\n IServiceProvider? services = null,\n CancellationToken cancellationToken = default)\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.AzureAI.Persistent/PersistentAgentsClientExtensions.cs:1]()\n\n## GitHub Copilot 集成\n\n框架支持将 GitHub Copilot 作为 AI 后端：\n\n```csharp\npublic static AIAgent AsAIAgent(\n this CopilotClient client,\n bool ownsClient = false,\n string? id = null,\n string? name = null,\n string? description = null,\n IList? tools = null,\n string? instructions = null)\n{\n Throw.IfNull(client);\n return new GitHubCopilotAgent(client, ownsClient, id, name, description, tools, instructions);\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/CopilotClientExtensions.cs:1]()\n\n## 开发工具（DevUI）\n\nDevUI 是框架提供的示例应用，用于快速入门和探索智能体功能。\n\n```\ngraph TD\n A[DevUI 应用] --> B[连接 Agent Framework 后端]\n B --> C[示例画廊 Sample Gallery]\n B --> D[设置面板 Settings]\n C --> E[浏览示例]\n C --> F[下载示例]\n D --> G[配置端点]\n D --> H[查看能力]\n```\n\nDevUI 特性：\n\n| 功能 | 说明 |\n|-----|------|\n| 示例画廊 | 浏览和下载预置的智能体示例 |\n| 设置管理 | 配置连接参数和能力选项 |\n| 版本信息 | 显示框架和运行时版本 |\n| 能力展示 | 展示后端支持的各项能力 |\n\n资料来源：[python/packages/devui/frontend/src/components/features/gallery/gallery-view.tsx:1]()\n\n## 部署模式\n\n框架支持多种部署场景：\n\n### 客户端托管\n\n智能体作为客户端应用的一部分运行，轻量级部署。\n\n```bash\n# Python 示例\ncd python\nuv run samples/08_host_your_agent.py\n```\n\n### 服务器托管\n\n智能体部署为独立服务，通过 API 暴露功能。\n\n### 云原生部署\n\n结合 Azure Container Apps、Azure Functions 或 Aspire 实现弹性扩缩容。\n\n```\ngraph TD\n A[客户端] -->|HTTP/WebSocket| B[API 网关]\n B --> C[Agent Service]\n C --> D[Foundry Agents API]\n D --> E[AI Model]\n C --> F[Skill Store]\n C --> G[Context Store]\n```\n\n资料来源：[dotnet/src/Aspire.Hosting.AgentFramework.DevUI/AgentEntityInfo.cs:1]()\n\n## 快速开始指南\n\n### Python 环境准备\n\n```bash\n# 安装核心包\npip install agent-framework\n\n# 设置环境变量\nexport FOUNDRY_PROJECT_ENDPOINT=\"https://your-project-endpoint\"\nexport FOUNDRY_MODEL=\"gpt-4o\" # 可选，默认 gpt-4o\n```\n\n### 创建第一个智能体\n\n```python\nfrom agent_framework import Agent\n\n# 创建智能体\nagent = Agent(\n name=\"我的助手\",\n instructions=\"你是一个有帮助的助手。\",\n model=\"gpt-4o\"\n)\n\n# 运行智能体\nresult = await agent.run(\"你好，请介绍一下你自己。\")\nprint(result)\n```\n\n### 添加工具\n\n```python\nfrom agent_framework import Agent, tool\n\n@tool\ndef get_weather(city: str) -> str:\n \"\"\"获取城市天气信息\"\"\"\n # 实现天气查询逻辑\n return f\"{city}今天天气晴朗\"\n\nagent = Agent(\n name=\"天气助手\",\n instructions=\"你是一个天气助手。\",\n tools=[get_weather]\n)\n```\n\n资料来源：[python/samples/01-get-started/README.md:1]()\n\n## 相关资源\n\n- [官方文档](https://github.com/microsoft/agent-framework)\n- [Agent Skills 规范](https://agentskills.io/)\n- [Python SDK 仓库](https://github.com/microsoft/agent-framework/tree/main/python)\n- [.NET SDK 仓库](https://github.com/microsoft/agent-framework/tree/main/dotnet)\n- [示例代码库](https://github.com/microsoft/agent-framework/tree/main/python/samples)\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[框架介绍](#introduction), [Agent 基础](#agent-basics)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/pyproject.toml](https://github.com/microsoft/agent-framework/blob/main/python/pyproject.toml)\n- [python/DEV_SETUP.md](https://github.com/microsoft/agent-framework/blob/main/python/DEV_SETUP.md)\n- [dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj)\n- [python/samples/01-get-started/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md)\n- [dotnet/src/Shared/Foundry/Agents/README.md](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Shared/Foundry/Agents/README.md)\n- [python/packages/devui/frontend/src/components/layout/settings-modal.tsx](https://github.com/microsoft/agent-framework/blob/main/python/packages/devui/frontend/src/components/layout/settings-modal.tsx)\n
\n\n# 安装与配置\n\n## 概述\n\nAgent Framework 是微软开发的一个跨平台智能代理框架，支持 Python 和 .NET 两种运行时环境。框架提供了完整的代理（Agent）开发、部署和管理能力，涵盖从基础代理创建到复杂工作流编排的完整功能链。\n\n本页面详细介绍框架的安装方法、配置选项以及开发环境搭建指南。\n\n---\n\n## 系统要求\n\n### Python 环境要求\n\n| 组件 | 最低版本 | 推荐版本 |\n|------|----------|----------|\n| Python | 3.10 | 3.11+ |\n| pip | 21.0 | 最新版本 |\n\n### .NET 环境要求\n\n| 组件 | 最低版本 | 推荐版本 |\n|------|----------|----------|\n| .NET SDK | .NET 8 | .NET 8 LTS |\n| Visual Studio / VS Code | 最新 | 最新 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj)\n\n---\n\n## Python 安装\n\n### 方式一：pip 安装（生产环境）\n\n使用 pip 直接安装稳定版本的 agent-framework 包：\n\n```bash\npip install agent-framework\n```\n\n资料来源：[python/samples/01-get-started/README.md:14](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md#L14)\n\n### 方式二：源码安装（开发环境）\n\n```bash\ncd python\npip install -e .\n```\n\n-e 参数表示可编辑模式安装，适合需要修改源码或参与框架开发的场景。\n\n### 依赖配置\n\nPython 版本的依赖通过 pyproject.toml 管理，主要依赖包括：\n\n| 依赖包 | 用途 |\n|--------|------|\n| python-dotenv | 环境变量管理 |\n| httpx | HTTP 客户端 |\n| openai | OpenAI API 兼容接口 |\n\n资料来源：[python/pyproject.toml](https://github.com/microsoft/agent-framework/blob/main/python/pyproject.toml)\n\n---\n\n## .NET 安装\n\n### NuGet 包引用\n\n在 .NET 项目中，通过添加包引用来使用 Agent Framework：\n\n```xml\n\n \n \n\n```\n\n### 共享模块注入\n\nAgent Framework 提供了多个可复用的共享模块，通过 .csproj 属性控制是否启用：\n\n```xml\n\n true\n true\n true\n true\n\n```\n\n资料来源：[dotnet/src/Shared/Foundry/Agents/README.md:7-11](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Shared/Foundry/Agents/README.md#L7-L11)\n\n### 共享模块说明\n\n| 模块 | 功能 |\n|------|------|\n| FoundryAgents | Foundry 代理创建和使用的共享模式 |\n| Samples | 高效的示例项目工具类 |\n| Redaction | 日志数据脱敏工具 |\n| Throw | 异常处理工具 |\n\n| 模块 | 功能 |\n|------|------|\n| TrimAttributes | AOT 裁剪优化支持 |\n| ExperimentalAttribute | 实验性功能标记 |\n| DiagnosticAttributes | 诊断属性支持 |\n| CallerAttributes | 调用者信息特性 |\n\n资料来源：[dotnet/src/Shared/Redaction/README.md:15-25](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Shared/Redaction/README.md#L15-L25)\n\n---\n\n## 环境变量配置\n\n### Python 环境变量\n\n创建 `.env` 文件或在终端中设置以下环境变量：\n\n```bash\nexport FOUNDRY_PROJECT_ENDPOINT=\"https://your-project-endpoint\"\nexport FOUNDRY_MODEL=\"gpt-4o\"\n```\n\n| 变量名 | 必填 | 默认值 | 说明 |\n|--------|------|--------|------|\n| FOUNDRY_PROJECT_ENDPOINT | 是 | - | Azure Foundry 项目端点 |\n| FOUNDRY_MODEL | 否 | gpt-4o | 使用的模型标识符 |\n\n资料来源：[python/samples/01-get-started/README.md:18-21](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md#L18-L21)\n\n### .NET 环境变量\n\n在 appsettings.json 中配置：\n\n```json\n{\n \"AzureAI\": {\n \"Endpoint\": \"https://your-resource.azurewebsites.net\",\n \"AuthenticationType\": \"ApiKey\"\n }\n}\n```\n\n---\n\n## 开发环境搭建\n\n### 快速开始流程\n\n```mermaid\ngraph TD\n A[安装依赖] --> B[配置环境变量]\n B --> C[克隆示例代码]\n C --> D[运行第一个代理]\n D --> E[添加自定义工具]\n E --> F[构建工作流]\n```\n\n### Python 开发环境设置\n\n1. **克隆仓库**\n ```bash\n git clone https://github.com/microsoft/agent-framework.git\n cd agent-framework\n ```\n\n2. **创建虚拟环境（推荐）**\n ```bash\n python -m venv venv\n source venv/bin/activate # Linux/macOS\n # 或\n .\\venv\\Scripts\\activate # Windows\n ```\n\n3. **安装开发依赖**\n ```bash\n cd python\n pip install -e \".[dev]\"\n ```\n\n4. **验证安装**\n ```python\n import agent_framework\n print(agent_framework.__version__)\n ```\n\n资料来源：[python/DEV_SETUP.md](https://github.com/microsoft/agent-framework/blob/main/python/DEV_SETUP.md)\n\n### .NET 开发环境设置\n\n1. **克隆仓库**\n ```bash\n git clone https://github.com/microsoft/agent-framework.git\n ```\n\n2. **还原包**\n ```bash\n cd dotnet\n dotnet restore\n ```\n\n3. **构建项目**\n ```bash\n dotnet build\n ```\n\n---\n\n## DevUI 配置\n\nDevUI 是框架提供的示例应用，用于快速上手 Agent Framework 开发。\n\n### 部署模式\n\nDevUI 支持多种运行模式：\n\n| 模式 | 说明 | 使用场景 |\n|------|------|----------|\n| default | 默认本地模式 | 开发调试 |\n| connected | 连接后端服务 | 完整功能测试 |\n| embedded | 内嵌模式 | 集成到现有应用 |\n\n资料来源：[python/packages/devui/frontend/src/components/layout/settings-modal.tsx:35-38](https://github.com/microsoft/agent-framework/blob/main/python/packages/devui/frontend/src/components/layout/settings-modal.tsx#L35-L38)\n\n### DevUI 版本信息\n\nDevUI 界面可显示以下系统信息：\n\n- 版本号 (Version)\n- 运行时类型 (Runtime)\n- UI 模式 (UI Mode)\n- 能力支持 (Capabilities)\n\n```typescript\ninterface ServerCapabilities {\n instrumentation?: boolean;\n // 其他能力字段...\n}\n```\n\n---\n\n## Docker 部署配置\n\n### 快速部署步骤\n\n1. **保存部署文件到项目目录**\n\n2. **构建镜像**\n ```bash\n docker build -t my-agent .\n ```\n\n3. **启动容器**\n ```bash\n docker-compose up\n ```\n\n### 生产环境注意事项\n\n| 注意事项 | 说明 |\n|----------|------|\n| 状态管理 | 内存状态在容器重启后会丢失 |\n| 认证 | 需要添加反向代理（nginx/Caddy）并配置认证 |\n| 密钥管理 | 使用 Azure Key Vault 管理敏感信息 |\n| 扩展性 | 单实例模式，不支持水平扩展 |\n\n资料来源：[python/packages/devui/frontend/src/components/layout/deployment-modal.tsx](https://github.com/microsoft/agent-framework/blob/main/python/packages/devui/frontend/src/components/layout/deployment-modal.tsx)\n\n---\n\n## 代理创建配置\n\n### Python 创建代理\n\n```python\nfrom agent_framework import Agent, tool\n\n@tool\ndef get_weather(city: str) -> str:\n \"\"\"获取城市天气信息\"\"\"\n return f\"{city}今天天气晴朗\"\n\nagent = Agent(\n name=\"weather-assistant\",\n instructions=\"你是一个天气助手\",\n model=\"gpt-4o\",\n tools=[get_weather]\n)\n```\n\n### .NET 创建代理\n\n```csharp\nusing Microsoft.Agents.AI;\n\n// 创建代理配置\nvar agentConfig = new AgentConfiguration\n{\n Name = \"my-agent\",\n Instructions = \"代理指令\",\n Model = \"gpt-4o\"\n};\n\n// 使用 ChatClientAgent\nvar agent = await persistentAgentsClient.CreateAIAgentAsync(\n model: \"gpt-4o\",\n name: \"my-agent\",\n instructions: \"代理指令\",\n tools: agentTools\n);\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.AzureAI.Persistent/PersistentAgentsClientExtensions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.AzureAI.Persistent/PersistentAgentsClientExtensions.cs)\n\n### 代理配置参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | string | 是 | 代理名称（kebab-case） |\n| instructions | string | 是 | 代理指令文本 |\n| description | string | 否 | 代理描述 |\n| model | string | 否 | 模型标识符 |\n| tools | IEnumerable | 否 | 可用工具列表 |\n| temperature | float | 否 | 温度参数（0.0-2.0） |\n| topP | float | 否 | Top-P 参数 |\n| responseFormat | object | 否 | 响应格式配置 |\n| metadata | dictionary | 否 | 自定义元数据 |\n\n资料来源：[python/samples/01-get-started/README.md:20-25](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md#L20-L25)\n\n---\n\n## 技能（Skill）配置\n\n### 技能定义\n\n代理技能支持通过前端资料（frontmatter）定义元数据：\n\n```python\nfrom agent_framework.skills import AgentInlineSkill\n\nskill = AgentInlineSkill(\n name=\"my-skill\",\n description=\"技能描述\",\n instructions=\"技能指令\",\n license=\"MIT\",\n compatibility=\"v1.0+\",\n allowedTools=\"tool1 tool2\",\n metadata={\"author\": \"developer\"}\n)\n```\n\n### 技能资源目录\n\n技能可以包含以下类型的资源目录：\n\n| 目录名 | 用途 |\n|--------|------|\n| references | 参考文档 |\n| assets | 静态资源 |\n| scripts | 脚本文件 |\n\n默认资源目录为 `references` 和 `assets`，可通过 `ResourceDirectories` 自定义配置。\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSourceOptions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSourceOptions.cs)\n\n---\n\n## 工作流配置\n\n### 功能式工作流\n\n```python\nfrom agent_framework import workflow, agent\n\n@workflow\nasync def my_workflow(input_data):\n result = await agent.invoke(input_data)\n return result\n```\n\n### 图工作流\n\n```mermaid\ngraph TD\n A[开始] --> B[代理节点1]\n B --> C{条件判断}\n C -->|成功| D[代理节点2]\n C -->|失败| E[错误处理]\n D --> F[结束]\n E --> F\n```\n\n资料来源：[python/samples/01-get-started/README.md:28-32](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md#L28-L32)\n\n---\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 包安装失败 | 检查 Python 版本是否满足要求（≥3.10） |\n| 环境变量未生效 | 确保重启终端或在新的 shell 会话中运行 |\n| Docker 构建失败 | 检查 Dockerfile 路径和上下文 |\n| 代理响应慢 | 检查网络连接和 API 限流设置 |\n\n### 验证安装\n\n```bash\n# Python 验证\npython -c \"import agent_framework; print('OK')\"\n\n# .NET 验证\ndotnet list package | grep Microsoft.Agents\n```\n\n---\n\n## 下一步\n\n安装配置完成后，建议按以下顺序学习框架：\n\n1. [创建第一个代理](samples/01-get-started/README.md)\n2. [添加自定义工具](samples/02_add_tools.py)\n3. [多轮对话实现](samples/03_multi_turn.py)\n4. [上下文管理](samples/04_memory.py)\n5. [功能式工作流](samples/05_functional_workflow_with_agents.py)\n6. [图工作流](samples/07_first_graph_workflow.py)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心概念](#core-concepts), [Agent 基础](#agent-basics)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/core/agent_framework/_agents.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py)\n- [python/packages/core/agent_framework/_workflows/_workflow.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_workflows/_workflow.py)\n- [dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs)\n- [dotnet/src/Microsoft.Agents.AI.Workflows/Workflow.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/Workflow.cs)\n- [python/samples/01-get-started/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md)\n- [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)\n- [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs)\n
\n\n# 系统架构\n\nMicrosoft Agent Framework 是一个用于构建 AI Agent 的跨平台框架，同时支持 Python 和 .NET 两种语言实现。本页面详细介绍该框架的整体架构设计、核心组件及其交互关系。\n\n## 1. 架构概览\n\nAgent Framework 采用分层架构设计，核心层负责 Agent 的生命周期管理和运行时调度，工作流层提供组合多个 Agent 的能力，外围层则包含工具系统、技能系统、会话管理等功能扩展。\n\n```mermaid\ngraph TB\n subgraph \"外围层\"\n Tools[\"工具系统
@tool 装饰器\"]\n Skills[\"技能系统
AgentSkill\"]\n Memory[\"会话记忆
AgentSession\"]\n end\n \n subgraph \"核心层\"\n Agent[\"Agent / AIAgent\"]\n Runtime[\"运行时调度器\"]\n end\n \n subgraph \"工作流层\"\n Workflow[\"工作流
Workflow\"]\n Functional[\"函数式工作流\"]\n Graph[\"图工作流\"]\n end\n \n subgraph \"通信层\"\n LLM[\"LLM 接口\"]\n Streaming[\"流式输出\"]\n end\n \n Tools --> Agent\n Skills --> Agent\n Memory --> Agent\n Agent --> Runtime\n Runtime --> LLM\n Runtime --> Streaming\n Workflow --> Agent\n Functional --> Agent\n Graph --> Workflow\n```\n\n框架的核心设计理念包括：\n\n- **声明式优先**：支持 YAML 配置文件定义 Agent 行为\n- **工具扩展**：通过 `@tool` 装饰器或 `ToolDefinition` 定义外部能力\n- **状态持久化**：AgentSession 支持多轮对话状态管理\n- **工作流编排**：支持函数式和图结构工作流组合\n\n## 2. 核心组件\n\n### 2.1 Agent 抽象\n\nAgent 是框架的核心抽象，代表一个具备 LLM 交互能力的智能体。在 Python 和 .NET 中均有对应实现。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | string | Agent 名称标识 |\n| description | string | Agent 功能描述 |\n| instructions | string | 系统指令/提示词 |\n| tools | List[Tool] | 可用工具集合 |\n| toolResources | dict | 工具资源映射 |\n\n**Python 实现**：`agent_framework._agents` 模块\n\n```python\n# Python Agent 示例结构 (来源：python/packages/core/agent_framework/_agents.py)\nclass Agent:\n def __init__(\n self,\n name: str,\n description: str | None = None,\n instructions: str | None = None,\n tools: list[Any] | None = None,\n # ... 其他参数\n ):\n self.name = name\n self.description = description\n self.instructions = instructions\n self._tools = tools or []\n```\n\n**NET 实现**：`Microsoft.Agents.AI.Abstractions.AIAgent`\n\n```csharp\n// .NET AIAgent 接口定义 (来源：dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs)\npublic abstract class AIAgent\n{\n public string? Id { get; }\n public string? Name { get; }\n public string? Description { get; }\n public IList? Tools { get; }\n public string? Instructions { get; }\n}\n```\n\n### 2.2 工作流系统\n\n工作流（Workflow）是组合多个 Agent 或任务的编排机制。框架支持三种工作流模式：\n\n| 工作流类型 | 说明 | 适用场景 |\n|------------|------|----------|\n| 函数式工作流 | 异步函数组合 | 简单线性流程 |\n| 图工作流 | 节点-边有向图 | 条件分支流程 |\n| 声明式工作流 | YAML 配置定义 | 可视化编排 |\n\n**Python 工作流基类** (来源：`python/packages/core/agent_framework/_workflows/_workflow.py`)：\n\n```python\nclass Workflow(ABC):\n \"\"\"工作流基类\"\"\"\n \n @property\n @abstractmethod\n def input_schema(self) -> dict | None:\n \"\"\"输入参数模式\"\"\"\n pass\n \n @property\n @abstractmethod\n def output_schema(self) -> dict | None:\n \"\"\"输出参数模式\"\"\"\n pass\n \n @abstractmethod\n async def run(self, input_data: Any) -> Any:\n \"\"\"执行工作流\"\"\"\n pass\n```\n\n**.NET 工作流定义** (来源：`dotnet/src/Microsoft.Agents.AI.Workflows/Workflow.cs`)：\n\n```csharp\npublic abstract class Workflow\n{\n public abstract Task RunAsync(\n WorkflowState input, \n CancellationToken cancellationToken = default);\n}\n```\n\n### 2.3 工具系统\n\n工具是 Agent 调用外部能力的接口，支持函数定义和资源绑定。\n\n```python\n# @tool 装饰器示例 (来源：python/samples/01-get-started/README.md)\nfrom agent_framework import tool\n\n@tool\ndef get_weather(location: str) -> str:\n \"\"\"获取指定位置的天气信息\"\"\"\n # 工具实现\n return f\"{location} 的天气是晴天\"\n```\n\n工具定义包含以下属性：\n\n| 属性 | 说明 | 必需 |\n|------|------|------|\n| name | 工具名称 | 是 |\n| description | 工具功能描述 | 是 |\n| parameters | JSON Schema 参数定义 | 是 |\n| resources | 关联资源映射 | 否 |\n\n## 3. 会话与上下文管理\n\n### 3.1 AgentSession 多轮会话\n\nAgentSession 维护对话历史，支持跨请求的上下文保持。\n\n```mermaid\ngraph LR\n A[用户输入 1] --> B[Agent]\n B --> C[LLM 响应 1]\n C --> D[Session 存储]\n D --> E[用户输入 2]\n E --> B\n B --> F[LLM 响应 2]\n```\n\n关键特性：\n- 自动维护对话历史\n- 支持流式和非流式输出\n- 可扩展的记忆系统接口\n\n### 3.2 ContextProvider 上下文提供者\n\n通过 ContextProvider 接口动态注入额外上下文：\n\n```python\nclass ContextProvider(Protocol):\n \"\"\"上下文提供者协议\"\"\"\n \n async def get_context(self) -> str:\n \"\"\"获取额外上下文\"\"\"\n pass\n```\n\n使用示例 (来源：`python/samples/01-get-started/04_memory.py`)：\n\n```python\nagent = Agent(\n name=\"my_agent\",\n context_providers=[MyCustomContextProvider()]\n)\n```\n\n## 4. 技能系统\n\n技能（Skill）是一种可复用的 Agent 能力封装，支持文件和代码两种定义方式。\n\n### 4.1 技能结构\n\n| 组件 | 说明 |\n|------|------|\n| name | 技能名称（kebab-case） |\n| description | 技能描述 |\n| instructions | 技能指令文本 |\n| resources | 关联资源文件 |\n| scripts | 执行脚本 |\n\n技能抽象定义 (来源：`dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs`)：\n\n```csharp\npublic abstract class AgentSkill\n{\n public abstract string Name { get; }\n public abstract string Description { get; }\n public abstract string Content { get; }\n public virtual IReadOnlyList? Resources => null;\n public virtual IReadOnlyList? Scripts => null;\n}\n```\n\n### 4.2 技能加载流程\n\n```mermaid\ngraph TD\n A[用户请求] --> B[AgentSkillsProvider]\n B --> C{技能源类型}\n C -->|文件| D[SKILL.md 解析]\n C -->|代码| E[AgentInlineSkill 实例化]\n D --> F[生成技能内容]\n E --> F\n F --> G[注入 Agent 上下文]\n G --> H[LLM 调用]\n```\n\n技能提供者配置 (来源：`dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs`)：\n\n```csharp\n// 默认技能指令模板\nprivate const string DefaultSkillsInstructionPrompt =\n \"\"\"\n You have access to skills containing domain-specific knowledge and capabilities.\n \n {skills}\n \n When a task aligns with a skill's domain, follow these steps:\n - Use `load_skill` to retrieve the skill's instructions.\n - Follow the provided guidance.\n \"\"\";\n```\n\n## 5. 部署与托管\n\n框架支持多种部署模式：\n\n| 部署方式 | 说明 | 适用场景 |\n|----------|------|----------|\n| 本地运行 | 开发调试 | 本地开发 |\n| 容器化部署 | Docker 容器 | 生产环境 |\n| Azure Foundry | 云托管服务 | 企业级部署 |\n\n托管示例项目 (来源：`dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/README.md`)：\n\n```bash\ndocker run -e FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT \\\n -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \\\n --env-file .env \\\n hosted-workflow-simple\n```\n\n## 6. 示例学习路径\n\n框架提供渐进式学习示例 (来源：`python/samples/01-get-started/README.md`)：\n\n| 阶段 | 示例文件 | 学习内容 |\n|------|----------|----------|\n| 入门 | 01_hello_agent.py | 创建首个 Agent |\n| 进阶 | 02_add_tools.py | 添加工具 |\n| 多轮 | 03_multi_turn.py | AgentSession |\n| 记忆 | 04_memory.py | ContextProvider |\n| 工作流 | 05-06_functional_workflow | 函数式编排 |\n| 图工作流 | 07_first_graph_workflow | 节点图编排 |\n| 部署 | 08_host_your_agent.py | 服务托管 |\n\n## 7. 集成扩展\n\n### 7.1 LLM 提供商支持\n\n框架通过抽象接口支持多种 LLM 提供商：\n\n| 包 | 提供商 | 安装命令 |\n|----|--------|----------|\n| agent-framework (内置) | OpenAI / Azure OpenAI | pip install agent-framework |\n| agent-framework-claude | Anthropic Claude | pip install agent-framework-claude --pre |\n| agent-framework-declarative | YAML 配置 | pip install agent-framework-declarative --pre |\n\n### 7.2 Azure 服务集成\n\n框架深度集成 Azure AI 服务：\n\n- **Azure AI Foundry**：Agent 部署和托管\n- **Azure Content Understanding**：文档、图像、音视频理解\n- **Azure AI Search**：知识检索增强\n\n集成示例 (来源：`python/packages/azure-contentunderstanding/samples/README.md`)：\n\n```python\n# PDF 文档问答\nfrom agent_framework_azure_contentunderstanding import DocumentProcessor\n\nprocessor = DocumentProcessor(endpoint=AZURE_CU_ENDPOINT)\nresult = await processor.analyze(\"document.pdf\", \"总结本文要点\")\n```\n\n## 8. 总结\n\nMicrosoft Agent Framework 的架构设计遵循以下原则：\n\n1. **跨平台一致性**：Python 和 .NET 实现保持 API 对齐\n2. **可扩展性**：通过抽象接口支持自定义扩展\n3. **声明式优先**：支持 YAML 配置降低使用门槛\n4. **生产就绪**：内置监控、日志、错误处理等企业特性\n\n框架核心位于 `agent_framework._agents` 和 `agent_framework._workflows` 模块，通过清晰的职责划分实现 Agent 创建、工作流编排、工具集成、会话管理的完整功能闭环。\n\n---\n\n\n\n## 核心概念\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [Agent 基础](#agent-basics)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/core/agent_framework/_types.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_types.py)\n- [python/packages/core/agent_framework/_sessions.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_sessions.py)\n- [dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs)\n- [dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs)\n- [dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs)\n- [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)\n- [dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs)\n- [dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs)\n
\n\n# 核心概念\n\nMicrosoft Agent Framework 是一个跨平台的多智能体开发框架，支持 Python 和 .NET 两种语言实现。该框架提供了构建、配置和运行 AI Agent 的完整基础设施，涵盖从基础的会话管理到复杂的多智能体工作流编排。\n\n## 框架架构概览\n\nAgent Framework 采用分层架构设计，核心层负责会话状态管理和响应处理，应用层提供 Agent 的构建和工具集成能力。\n\n```mermaid\ngraph TD\n subgraph \"应用层\"\n A1[ChatClientAgent]\n A2[AgentSkill]\n A3[AgentModeProvider]\n end\n \n subgraph \"核心抽象层\"\n C1[AgentSession]\n C2[AgentResponse]\n C3[AIContext]\n end\n \n subgraph \"客户端层\"\n B1[IChatClient]\n B2[PersistentAgentsClient]\n end\n \n A1 --> C1\n A2 --> C1\n A3 --> C1\n C1 --> C2\n B1 --> A1\n B2 --> A1\n```\n\n## 核心数据类型\n\n### AgentSession（Agent 会话）\n\n`AgentSession` 是框架中管理多轮对话状态的核心抽象，封装了对话历史、用户标识和会话元数据。\n\n```csharp\n// dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs\npublic class AgentSession\n{\n public string? SessionId { get; set; }\n public string? AssistantId { get; set; }\n public string? UserId { get; set; }\n public DateTimeOffset? CreatedAt { get; set; }\n public IDictionary? Metadata { get; set; }\n public IList? Messages { get; set; }\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSession.cs]()\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `SessionId` | string? | 会话唯一标识符 |\n| `AssistantId` | string? | Assistant 标识 |\n| `UserId` | string? | 用户标识 |\n| `CreatedAt` | DateTimeOffset? | 会话创建时间 |\n| `Metadata` | IDictionary? | 会话元数据键值对 |\n| `Messages` | IList? | 消息历史列表 |\n\n### AgentResponse（Agent 响应）\n\n`AgentResponse` 封装了 Agent 执行结果的完整信息，包括响应内容、工具调用、Token 使用统计等。\n\n```csharp\n// dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs\npublic class AgentResponse\n{\n public string? Content { get; set; }\n public IList? ToolCalls { get; set; }\n public CompletionUsage? Usage { get; set; }\n public string? FinishReason { get; set; }\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Abstractions/AgentResponse.cs]()\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `Content` | string? | 响应文本内容 |\n| `ToolCalls` | IList? | 调用的工具列表 |\n| `Usage` | CompletionUsage? | Token 使用统计 |\n| `FinishReason` | string? | 完成原因（如 stop、tool_calls） |\n\n### Python 类型定义\n\nPython SDK 提供了等效的类型定义，通过数据类实现会话和消息的建模。\n\n```python\n# python/packages/core/agent_framework/_types.py\n@dataclass\nclass AgentSession:\n session_id: Optional[str] = None\n user_id: Optional[str] = None\n created_at: Optional[datetime] = None\n metadata: Optional[Dict[str, str]] = None\n\n@dataclass\nclass TurnResponse:\n output: str\n tool_calls: Optional[List[ToolCall]] = None\n usage: Optional[Usage] = None\n session: AgentSession\n```\n\n资料来源：[python/packages/core/agent_framework/_types.py]()\n\n## Agent 类型体系\n\n### ChatClientAgent\n\n`ChatClientAgent` 是基于 `IChatClient` 的标准 Agent 实现，支持流式和非流式两种运行模式。\n\n```csharp\n// dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs\npublic sealed class ChatClientAgent : AIAgent\n{\n public ChatClientAgent(\n IChatClient chatClient,\n string? instructions = null,\n string? name = null,\n string? description = null,\n IEnumerable? tools = null,\n ILoggerFactory? loggerFactory = null,\n IServiceProvider? services = null);\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs]()\n\n| 构造参数 | 类型 | 说明 |\n|----------|------|------|\n| `chatClient` | IChatClient | 底层聊天客户端 |\n| `instructions` | string? | 系统级指令 |\n| `name` | string? | Agent 名称 |\n| `description` | string? | Agent 描述 |\n| `tools` | IEnumerable? | 可用工具集 |\n| `loggerFactory` | ILoggerFactory? | 日志工厂 |\n| `services` | IServiceProvider? | 依赖注入服务容器 |\n\n### AgentSkill（技能）\n\n`AgentSkill` 是框架中的技能抽象基类，支持文件定义和代码定义两种方式。\n\n```mermaid\nclassDiagram\n class AgentSkill {\n <>\n +Name : string\n +Description : string\n +Content : string\n +Resources : IReadOnlyList~AgentSkillResource~?\n +Scripts : IReadOnlyList~AgentSkillScript~?\n }\n \n class AgentInlineSkill {\n +Instructions : string\n +License : string?\n +Compatibility : string?\n +AllowedTools : string?\n +Metadata : AdditionalPropertiesDictionary?\n }\n \n class FileBasedSkill {\n +FilePath : string\n }\n \n AgentSkill <|-- AgentInlineSkill\n AgentSkill <|-- FileBasedSkill\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs]()\n\n**AgentInlineSkill** 支持通过代码直接定义技能：\n\n```csharp\n// dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs\npublic class AgentInlineSkill : AgentSkill\n{\n public AgentInlineSkill(\n string name,\n string description,\n string instructions,\n string? license = null,\n string? compatibility = null,\n string? allowedTools = null,\n AdditionalPropertiesDictionary? metadata = null,\n JsonSerializerOptions? serializerOptions = null);\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs]()\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `name` | string | 技能名称（kebab-case） |\n| `description` | string | 技能描述 |\n| `instructions` | string | 技能指令文本 |\n| `license` | string? | 许可证名称 |\n| `compatibility` | string? | 兼容性信息（最多500字符） |\n| `allowedTools` | string? | 预批准工具空格分隔列表 |\n| `metadata` | AdditionalPropertiesDictionary? | 自定义元数据 |\n| `serializerOptions` | JsonSerializerOptions? | JSON 序列化选项 |\n\n## 会话管理\n\n### AgentSession 的生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建会话: 首次交互\n 创建会话 --> 活跃: 添加用户消息\n 活跃 --> 活跃: 多轮对话\n 活跃 --> 结束: 显式关闭或超时\n 结束 --> [*]: 资源释放\n \n 创建会话 --> 错误: 参数验证失败\n 活跃 --> 错误: 服务不可用\n 错误 --> [*]: 错误处理\n```\n\n### Python 会话管理\n\nPython SDK 提供了 `AgentSession` 类的完整实现：\n\n```python\n# python/packages/core/agent_framework/_sessions.py\nclass AgentSession(ABC):\n @abstractmethod\n async def run(self, prompt: str, *args, **kwargs) -> TurnResponse: ...\n \n @abstractmethod\n async def run_streaming(self, prompt: str, *args, **kwargs) -> AsyncIterator[TurnResponse]: ...\n \n @abstractmethod\n async def reset(self) -> None: ...\n```\n\n资料来源：[python/packages/core/agent_framework/_sessions.py]()\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `run` | TurnResponse | 非流式执行单个轮次 |\n| `run_streaming` | AsyncIterator[TurnResponse] | 流式执行 |\n| `reset` | None | 重置会话状态 |\n\n## Agent 模式（AgentMode）\n\n`AgentMode` 定义了 Agent 的运行模式，支持交互式规划和自主执行两种模式。\n\n```csharp\n// dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs\npublic sealed class AgentMode\n{\n public string Name { get; }\n public string Description { get; }\n \n public AgentMode(string name, string description);\n}\n\npublic class AgentModeProviderOptions\n{\n public IReadOnlyList? Modes { get; set; }\n public string? DefaultMode { get; set; }\n}\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs]()\n\n| 模式名称 | 说明 |\n|----------|------|\n| `plan` | 交互式规划模式 |\n| `execute` | 自主执行模式 |\n\n## 工作流程集成\n\n### 多 Agent 协作\n\n框架支持将多个 Agent 组合成工作流，实现复杂的任务分解和执行：\n\n```mermaid\ngraph LR\n subgraph \"工作流\"\n W1[主 Agent]\n W2[子 Agent 1]\n W3[子 Agent 2]\n W4[聚合器]\n end\n \n W1 --> W2\n W1 --> W3\n W2 --> W4\n W3 --> W4\n```\n\n### 工具系统\n\n框架的工具系统支持两种调用方式：\n\n| 调用方式 | 触发条件 | 用户确认 |\n|----------|----------|----------|\n| 自动调用 | AI 自动选择 | 默认无需确认 |\n| 请求确认 | 高风险操作 | 需要显式批准 |\n\n> [!NOTE]\n> 默认情况下，所有提供的工具都会自动调用。AI 选择调用的函数和参数应被视为不受信任的输入。开发者应为具有副作用、访问敏感数据或执行不可逆操作的工具要求显式批准。\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs]()\n\n## 快速入门示例\n\n### Python 示例\n\n```python\n# 创建基础 Agent\nfrom agent_framework import Agent\n\nagent = Agent(\n model=\"gpt-4o\",\n instructions=\"你是一个有帮助的助手\"\n)\n\n# 非流式运行\nresponse = await agent.run(\"今天天气怎么样？\")\nprint(response.output)\n\n# 流式运行\nasync for chunk in agent.run_streaming(\"讲个故事\"):\n print(chunk.output, end=\"\", flush=True)\n```\n\n### .NET 示例\n\n```csharp\n// 创建 ChatClientAgent\nvar agent = new ChatClientAgent(\n chatClient: chatClient,\n instructions: \"You are a helpful assistant\",\n name: \"Assistant\",\n description: \"A general purpose assistant\",\n tools: myTools);\n\n// 运行 Agent\nvar response = await agent.RunAsync(\"Hello, how are you?\");\n```\n\n## 核心概念总结\n\n| 概念 | 作用 | 关键文件 |\n|------|------|----------|\n| AgentSession | 管理会话状态和消息历史 | _sessions.py, AgentSession.cs |\n| AgentResponse | 封装执行结果 | AgentResponse.cs |\n| ChatClientAgent | 基于 IChatClient 的 Agent 实现 | ChatClientAgent.cs |\n| AgentSkill | 技能抽象，支持文件和代码定义 | AgentSkill.cs |\n| AgentMode | 定义运行模式（plan/execute） | AgentModeProviderOptions.cs |\n| ContextProvider | 提供动态上下文 | AgentSkillsProvider.cs |\n\n---\n\n\n\n## Agent 基础\n\n### 相关页面\n\n相关主题：[工具与技能系统](#agent-tools), [模型提供商集成](#agent-providers)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/core/agent_framework/_agents.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py)\n- [python/samples/01-get-started/01_hello_agent.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/01_hello_agent.py)\n- [dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs)\n- [dotnet/samples/01-get-started/01_hello_agent/Program.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/01-get-started/01_hello_agent/Program.cs)\n- [dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs)\n- [README.md](https://github.com/microsoft/agent-framework/blob/main/README.md)\n- [python/README.md](https://github.com/microsoft/agent-framework/blob/main/python/README.md)\n
\n\n# Agent 基础\n\n## 概述\n\nAgent（智能体）是 Microsoft Agent Framework 的核心抽象单元，代表能够理解自然语言、调用工具并执行复杂任务的 AI 驱动的软件实体。在 Agent Framework 中，Agent 作为一个封装了 AI 客户端、指令、工具和会话状态的可组合单元，为开发者提供了构建 AI 应用的基础构建块。\n\nAgent 的核心职责包括：\n- 接收用户输入并生成响应\n- 管理对话历史和多轮交互\n- 调用工具扩展能力边界\n- 集成多种 AI 服务提供商（如 Azure OpenAI、OpenAI、GitHub Copilot、Claude 等）\n\n资料来源：[python/packages/core/agent_framework/_agents.py:1-50](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py)\n\n## Agent 的核心组件\n\n### Python 实现架构\n\nPython Agent 由以下核心类组成：\n\n| 类名 | 用途 |\n|------|------|\n| `Agent` | 主入口类，封装客户端和指令 |\n| `ChatCompletionMessage` | 聊天消息的数据结构 |\n| `ChatClientProtocol` | 聊天客户端接口协议 |\n| `FunctionSpec` | 函数工具的规范定义 |\n\n资料来源：[python/packages/core/agent_framework/_agents.py:1-100](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py)\n\n### .NET 实现架构\n\n在 .NET 侧，`ChatClientAgent` 类是核心实现：\n\n```csharp\npublic sealed class ChatClientAgent : AIAgent\n```\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `Instructions` | `string?` | 系统指令，指导 Agent 行为 |\n| `Tools` | `IList?` | Agent 可调用的工具集合 |\n| `LoggerFactory` | `ILoggerFactory?` | 日志工厂 |\n| `Services` | `IServiceProvider?` | 依赖注入服务提供器 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs:30-80](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs)\n\n### Agent 标识模型\n\n```mermaid\nclassDiagram\n class AgentId {\n +AgentIdType Type\n +string Name\n +string Version\n }\n \n class AgentIdType {\n +string Value\n }\n \n AgentId --> AgentIdType : contains\n```\n\n`AgentId` 类用于标识特定的 Agent 实例，包含类型、名称和版本信息。\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs:10-40](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Models/AgentId.cs)\n\n## Agent 的创建与初始化\n\n### Python 创建模式\n\n```python\nfrom agent_framework import Agent, FoundryChatClient\nfrom azure.identity import AzureCliCredential\n\nagent = Agent(\n client=FoundryChatClient(\n credential=AzureCliCredential(),\n project_endpoint=os.environ[\"FOUNDRY_PROJECT_ENDPOINT\"],\n ),\n name=\"HaikuAgent\",\n instructions=\"You are an upbeat assistant that writes beautifully.\",\n)\n```\n\nPython Agent 构造函数接受以下核心参数：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `client` | `ChatClientProtocol` | 是 | AI 聊天客户端实例 |\n| `name` | `str` | 否 | Agent 名称，用于标识和日志 |\n| `instructions` | `str` | 否 | 系统提示词 |\n\n资料来源：[python/samples/01-get-started/01_hello_agent.py:1-50](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/01_hello_agent.py)\n\n### .NET 创建模式\n\n```csharp\nusing Azure.AI.Projects;\nusing Azure.Identity;\nusing Microsoft.Agents.AI;\n\nAIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())\n .AsAIAgent(\n model: deploymentName, \n instructions: \"You are an upbeat assistant.\", \n name: \"HaikuAgent\"\n );\n```\n\n.NET 通过扩展方法 `AsAIAgent()` 将 `AIProjectClient` 转换为 `AIAgent` 实例。\n\n资料来源：[dotnet/samples/01-get-started/01_hello_agent/Program.cs:1-30](https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/01-get-started/01_hello_agent/Program.cs)\n\n### 初始化流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant Agent\n participant Client\n participant AI_Service\n \n User->>Agent: 创建 Agent 实例\n Agent->>Client: 初始化 ChatClient\n Client->>AI_Service: 建立连接\n AI_Service-->>Client: 连接成功\n Client-->>Agent: 客户端就绪\n Agent-->>User: Agent 初始化完成\n```\n\n## Agent 的运行机制\n\n### 单轮对话执行\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Agent.run]\n B --> C[构建 ChatOptions]\n C --> D[调用 ChatClient]\n D --> E[AI 模型处理]\n E --> F[返回消息]\n F --> G[解析响应]\n G --> H[返回结果]\n```\n\nAgent 的 `run()` 方法执行单轮对话，输入直接转换为输出，不保留会话历史。\n\n资料来源：[python/packages/core/agent_framework/_agents.py:100-150](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_agents.py)\n\n### 消息格式\n\nAgent 使用结构化的消息格式进行通信：\n\n| 消息类型 | 说明 |\n|----------|------|\n| `user` | 用户发送的消息 |\n| `assistant` | AI 生成的回复 |\n| `tool` | 工具调用请求或结果 |\n\n## 工具集成\n\n### 工具定义\n\nAgent 通过工具扩展其能力范围。工具可以是：\n\n- **函数工具**：Python 函数或 .NET 方法，通过装饰器/属性暴露给 AI\n- **外部 API**：通过 HTTP 调用的远程服务\n- **脚本**：可执行的代码片段\n\n### Python 工具定义示例\n\n```python\nfrom agent_framework import tool\n\n@tool\ndef get_weather(city: str) -> str:\n \"\"\"获取指定城市的天气信息\"\"\"\n return f\"{city} 今天的天气是晴天，25°C\"\n```\n\n资料来源：[python/samples/01-get-started/02_add_tools.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/02_add_tools.py)\n\n### .NET 工具定义\n\n在 .NET 中，工具通过 `AITool` 接口实现，并可在创建 Agent 时传入：\n\n```csharp\nAIAgent agent = client.AsAIAgent(\n tools: new List { customTool },\n instructions: \"Instructions here\"\n);\n```\n\n## 多轮对话与会话管理\n\n### Python 会话管理\n\nPython Agent 通过 `AgentSession` 类管理多轮对话：\n\n```python\nfrom agent_framework import AgentSession\n\nasync with AgentSession(agent=agent) as session:\n response1 = await session.run(\"你好\")\n response2 = await session.run(\"请帮我查询天气\")\n```\n\n会话自动维护消息历史，支持跨多次交互的上下文理解。\n\n资料来源：[python/samples/01-get-started/03_multi_turn.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/03_multi_turn.py)\n\n### .NET 会话管理\n\n```csharp\n// 使用 AIProjectClient 的 AsAIAgent 返回 AIAgent\n// AIAgent 内部管理会话状态\nstring response = await agent.RunAsync(\"Hello, how are you?\");\n```\n\n### 会话状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> 初始化: 创建 Agent\n 初始化 --> 就绪: 客户端连接\n 就绪 --> 处理中: 接收用户消息\n 处理中 --> 等待工具: 需要调用工具\n 等待工具 --> 处理中: 工具返回结果\n 处理中 --> 就绪: 生成最终响应\n 就绪 --> [*]: 会话结束\n```\n\n## 流式响应支持\n\nAgent 支持流式输出模式，适合需要实时反馈的场景：\n\n### Python 流式调用\n\n```python\nasync for event in agent.run(\"讲一个故事\", stream=True):\n print(event.delta, end=\"\", flush=True)\n```\n\n### .NET 流式调用\n\n```csharp\nawait foreach (var update in agent.RunAsync(\"Tell me a story\", stream: true))\n{\n Console.Write(update.Content);\n}\n```\n\n## 上下文提供者\n\nAgent 支持通过 `ContextProvider` 接口注入动态上下文：\n\n```python\nfrom agent_framework import ContextProvider\n\nclass CustomContextProvider(ContextProvider):\n async def get_context(self) -> str:\n # 返回动态生成的上下文\n return \"当前时间: 2024-01-01\"\n```\n\n资料来源：[python/samples/01-get-started/04_memory.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/04_memory.py)\n\n## 错误处理与日志\n\n### 异常处理\n\nAgent 运行时可能遇到以下异常类型：\n\n| 异常 | 说明 |\n|------|------|\n| `AgentException` | Agent 执行基础异常 |\n| `ToolExecutionException` | 工具执行失败 |\n| `AuthenticationException` | 认证失败 |\n| `RateLimitException` | 速率限制触发 |\n\n### 日志配置\n\n```csharp\n// .NET 日志配置\nvar loggerFactory = LoggerFactory.Create(builder => \n builder.AddConsole());\n\nAIAgent agent = new ChatClientAgent(client, loggerFactory: loggerFactory);\n```\n\n```python\n# Python 日志配置\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n## 最佳实践\n\n### 设计原则\n\n1. **清晰的指令设计**：编写明确、简洁的系统指令，避免歧义\n2. **合理的工具粒度**：工具应职责单一，便于 AI 理解和调用\n3. **适当的超时设置**：为长时间运行的操作设置超时\n4. **状态管理**：善用会话管理维护对话上下文\n\n### 性能优化\n\n| 策略 | 说明 |\n|------|------|\n| 工具缓存 | 避免重复初始化昂贵的工具资源 |\n| 上下文压缩 | 长对话中适当压缩历史消息 |\n| 并行工具调用 | 支持 AI 并行调用多个独立工具 |\n\n### 安全考虑\n\n- 对具有副作用的工具强制要求用户确认\n- 敏感操作实施访问控制\n- 验证工具返回结果的合法性\n\n## 相关资源\n\n- [Agent Framework 官方文档](https://github.com/microsoft/agent-framework)\n- [Python SDK 快速开始](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md)\n- [示例代码库](../samples/)\n\n---\n\n\n\n## 模型提供商集成\n\n### 相关页面\n\n相关主题：[Agent 基础](#agent-basics)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/openai/agent_framework_openai/_chat_client.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/agent_framework_openai/_chat_client.py)\n- [python/packages/foundry/agent_framework_foundry/_chat_client.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/foundry/agent_framework_foundry/_chat_client.py)\n- [python/packages/anthropic/agent_framework_anthropic/_chat_client.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/anthropic/agent_framework_anthropic/_chat_client.py)\n- [dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs)\n- [dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs)\n
\n\n# 模型提供商集成\n\n## 概述\n\n模型提供商集成（Model Provider Integration）是 Microsoft Agent Framework 的核心架构特性，允许框架通过统一的抽象接口接入多种大语言模型（LLM）提供商。该设计使开发者能够在不修改核心业务逻辑的情况下，灵活切换不同的 AI 后端服务。\n\nAgent Framework 的模型提供商集成具有以下核心目标：\n\n- **统一抽象**：为不同提供商提供一致的 API 接口\n- **多后端支持**：支持 OpenAI、Azure OpenAI、Azure AI Foundry、Anthropic Claude 等主流服务商\n- **配置灵活性**：通过环境变量或代码配置多种参数\n- **流式响应**：支持流式和非流式两种响应模式\n- **工具调用**：统一的函数调用（Function Calling）能力抽象\n\n资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md)\n\n## 架构设计\n\n### 整体架构\n\nAgent Framework 采用分层架构设计，模型提供商作为独立的包存在，通过标准化的接口与核心框架解耦：\n\n```mermaid\ngraph TD\n A[Agent / 业务逻辑层] --> B[核心框架层
agent_framework.core]\n B --> C[聊天客户端抽象层
IChatClient / ChatClientBase]\n C --> D[提供商特定实现层]\n \n D --> E[OpenAI]\n D --> F[Azure OpenAI]\n D --> G[Azure AI Foundry]\n D --> H[Anthropic Claude]\n \n E --> E1[Responses API]\n E --> E2[Chat Completions API]\n```\n\n资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md)\n\n### Python 生态中的聊天客户端\n\nPython 版本的 Agent Framework 为每个提供商提供了独立的聊天客户端类，这些类均继承自统一的基类或实现相同的接口：\n\n| 提供商 | 包名 | 主要类 | API 类型 |\n|--------|------|--------|----------|\n| OpenAI | `agent-framework-openai` | `OpenAIChatClient` | Responses API（推荐） |\n| OpenAI | `agent-framework-openai` | `OpenAIChatCompletionClient` | Chat Completions API |\n| Azure AI Foundry | `agent-framework-foundry` | `FoundryChatClient` | Azure Foundry 原生 |\n| Anthropic | `agent-framework-anthropic` | `AnthropicChatClient` | Claude API |\n\n资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md)\n\n### .NET 生态中的聊天客户端\n\n.NET 版本采用类似的架构，通过扩展方法将聊天客户端转换为代理：\n\n```mermaid\ngraph LR\n A[IChatClient] --> B[ChatClientAgent]\n B --> C[AsAIAgent 扩展方法]\n \n D[OpenAI ChatClient] --> C\n E[Azure OpenAI Client] --> C\n F[FoundryChatClient] --> C\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs)\n\n## OpenAI 集成\n\n### Python 实现\n\nPython 的 `agent-framework-openai` 包提供了两个聊天客户端类，分别对应 OpenAI 的两种 API：\n\n#### OpenAIChatClient（Responses API）\n\n这是推荐使用的客户端，使用 OpenAI 的 Responses API：\n\n```python\nfrom agent_framework.openai import OpenAIChatClient\n\nclient = OpenAIChatClient(\n api_key=\"sk-...\",\n model=\"gpt-4o\"\n)\n```\n\n模型优先级：`OPENAI_CHAT_MODEL` → `OPENAI_MODEL`\n\n资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md)\n\n#### OpenAIChatCompletionClient（Chat Completions API）\n\n此客户端使用传统的 Chat Completions API，主要用于兼容现有集成：\n\n```python\nfrom agent_framework.openai import OpenAIChatCompletionClient\n\nclient = OpenAIChatCompletionClient(\n api_key=\"sk-...\",\n model=\"gpt-4o-mini\"\n)\n```\n\n模型优先级：`OPENAI_CHAT_COMPLETION_MODEL` → `OPENAI_MODEL`\n\n资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md)\n\n### 环境变量配置\n\n| 变量名 | 用途 |\n|--------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 |\n| `OPENAI_ORG_ID` | OpenAI 组织 ID |\n| `OPENAI_BASE_URL` | 自定义 OpenAI 兼容 API 地址 |\n| `OPENAI_MODEL` | 通用默认模型 |\n| `OPENAI_CHAT_MODEL` | `OpenAIChatClient` 首选模型 |\n| `OPENAI_CHAT_COMPLETION_MODEL` | `OpenAIChatCompletionClient` 首选模型 |\n| `OPENAI_EMBEDDING_MODEL` | `OpenAIEmbeddingClient` 首选模型 |\n\n资料来源：[python/packages/openai/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/openai/README.md)\n\n### .NET 实现\n\n在 .NET 生态中，通过 `OpenAIChatClientExtensions` 扩展方法将 `ChatClient` 转换为 `Agent`：\n\n```csharp\nusing Microsoft.Agents.AI.OpenAI.Extensions;\n\nChatClientAgent agent = chatClient.AsAIAgent(\n name: \"ChatAssistant\",\n instructions: \"You are a helpful coding assistant specializing in C# and .NET.\");\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs)\n\n## Azure AI Foundry 集成\n\n### Python 实现\n\n`agent-framework-foundry` 包提供了与 Azure AI Foundry 的深度集成：\n\n```python\nfrom agent_framework_foundry import FoundryChatClient\n\nclient = FoundryChatClient(\n project_endpoint=\"https://your-project.services.ai.azure.com\",\n model=\"gpt-4o\"\n)\n```\n\nAzure AI Foundry 集成主要使用环境变量配置：\n\n| 变量名 | 用途 |\n|--------|------|\n| `FOUNDRY_PROJECT_ENDPOINT` | Foundry 项目端点 |\n| `FOUNDRY_MODEL` | 使用的模型名称 |\n\n资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md)\n\n### .NET 实现\n\n```csharp\nusing Microsoft.Agents.AI.Foundry;\n\nFoundryAgent agent = new FoundryAgent(\n projectEndpoint: \"https://your-project.services.ai.azure.com\",\n deploymentName: \"gpt-4o\"\n);\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs)\n\n## Anthropic Claude 集成\n\n### Python 实现\n\n`agent-framework-anthropic` 包提供了 Claude 模型的集成：\n\n```python\nfrom agent_framework_anthropic import AnthropicChatClient\n\nclient = AnthropicChatClient(\n api_key=\"sk-ant-...\",\n model=\"claude-3-5-sonnet-20241022\"\n)\n```\n\nAnthropic 集成允许开发者使用 Claude 系列模型，与 OpenAI 风格的接口保持一致。\n\n资料来源：[python/packages/anthropic/agent_framework_anthropic/_chat_client.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/anthropic/agent_framework_anthropic/_chat_client.py)\n\n## 核心使用模式\n\n### 模式一：直接使用聊天客户端\n\n适用于高级工作流，直接与聊天 API 交互：\n\n```python\nimport asyncio\nfrom agent_framework.openai import OpenAIChatClient\nfrom agent_framework import Message, Role\n\nasync def main():\n client = OpenAIChatClient()\n\n response = await client.get_response([\n Message(\"system\", [\"You are a helpful assistant.\"]),\n Message(\"user\", [\"Write a haiku about Agent Framework.\"])\n ])\n print(response.messages[0].text)\n\nasyncio.run(main())\n```\n\n资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md)\n\n### 模式二：创建代理\n\n使用聊天客户端创建 Agent，让框架处理对话管理：\n\n```python\nfrom agent_framework import Agent\nfrom agent_framework.openai import OpenAIChatClient\n\nagent = Agent(\n client=OpenAIChatClient(),\n instructions=\"你是一个有帮助的编程助手。\"\n)\n\nresult = await agent.run(\"解释什么是函数调用\")\n```\n\n资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md)\n\n### 模式三：带工具的代理\n\n为代理添加工具（函数调用）能力：\n\n```python\nfrom typing import Annotated\nfrom agent_framework import Agent\nfrom agent_framework.openai import OpenAIChatClient\n\ndef get_weather(\n location: Annotated[str, \"要查询天气的城市\"]\n) -> str:\n \"\"\"获取指定城市的天气信息\"\"\"\n return f\"{location} 今天天气晴朗，温度 22°C\"\n\nagent = Agent(\n client=OpenAIChatClient(),\n instructions=\"你是一个天气助手。\",\n tools=[get_weather]\n)\n```\n\n资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md)\n\n## 代理创建参数\n\n### ChatClientAgent 参数说明\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `chatClient` | `IChatClient` | 是 | 用于执行聊天的客户端实例 |\n| `instructions` | `string?` | 否 | 系统指令，指导代理行为 |\n| `name` | `string?` | 否 | 代理名称，用于识别和日志记录 |\n| `description` | `string?` | 否 | 人类可读的代理描述 |\n| `tools` | `IReadOnlyList?` | 否 | 代理可调用的工具集合 |\n| `loggerFactory` | `ILoggerFactory?` | 否 | 日志工厂实例 |\n| `services` | `IServiceProvider?` | 否 | 依赖注入服务提供者 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs)\n\n## 提供商选择指南\n\n### 选择 OpenAI 的场景\n\n- 新项目推荐使用 Responses API（`OpenAIChatClient`）\n- 需要兼容现有 Chat Completions 代码时使用 `OpenAIChatCompletionClient`\n- 需要快速原型开发\n\n### 选择 Azure OpenAI 的场景\n\n- 企业已有 Azure 订阅\n- 需要 Azure 的安全合规特性\n- 与其他 Azure 服务集成\n\n### 选择 Azure AI Foundry 的场景\n\n- 使用 Azure AI Foundry 作为主要推理服务\n- 需要 Foundry 特有的功能（如高级模型路由）\n\n### 选择 Anthropic Claude 的场景\n\n- 需要 Claude 的长上下文能力\n- 偏好 Anthropic 的安全对齐特性\n- 特定场景下 Claude 表现更优\n\n## 流式响应支持\n\n所有聊天客户端均支持流式响应模式：\n\n### Python 流式调用\n\n```python\nasync for chunk in client.stream([Message(\"user\", [\"你好\"])]):\n print(chunk.content, end=\"\", flush=True)\n```\n\n### .NET 流式调用\n\n```csharp\nawait foreach (var update in agent.RunAsyncStreaming(\n new ChatMessage(ChatRole.User, \"Hello\")))\n{\n Console.Write(update.Content);\n}\n```\n\n## 多提供商工作流\n\nAgent Framework 支持在同一应用中混合使用多个提供商：\n\n```python\nfrom agent_framework.openai import OpenAIChatClient\nfrom agent_framework_foundry import FoundryChatClient\nfrom agent_framework import Agent\n\n# 不同任务使用不同提供商\nrouter_agent = Agent(\n client=OpenAIChatClient(),\n instructions=\"你是任务路由器，将问题分类并路由到合适的处理代理。\"\n)\n\n# 编码任务使用 Claude\ncoding_agent = Agent(\n client=AnthropicChatClient(),\n instructions=\"你是一个专业程序员。\"\n)\n\n# 简单问答使用轻量模型\nqa_agent = Agent(\n client=OpenAIChatCompletionClient(model=\"gpt-4o-mini\"),\n instructions=\"你是一个简洁的问答助手。\"\n)\n```\n\n## 配置最佳实践\n\n### 开发环境\n\n```bash\n# .env 文件\nOPENAI_API_KEY=sk-...\nOPENAI_CHAT_MODEL=gpt-4o-mini\n\n# 或使用 Azure\nAZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/\nAZURE_OPENAI_API_KEY=...\nAZURE_OPENAI_MODEL=gpt-4o\n```\n\n### 生产环境\n\n建议使用密钥管理服务：\n\n- Azure: 使用 Azure Key Vault\n- AWS: 使用 AWS Secrets Manager\n- 通用: 环境变量或配置服务\n\n### 客户端配置覆盖\n\n环境变量可以被代码参数覆盖：\n\n```python\nclient = OpenAIChatClient(\n api_key=\"from-secret-manager\",\n model=\"gpt-4o\"\n)\n```\n\n资料来源：[python/packages/core/README.md](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/README.md)\n\n## 相关资源\n\n- [Python 快速开始示例](https://github.com/microsoft/agent-framework/tree/main/python/samples/01-get-started)\n- [OpenAI 包文档](https://github.com/microsoft/agent-framework/tree/main/python/packages/openai)\n- [Foundry 包文档](https://github.com/microsoft/agent-framework/tree/main/python/packages/foundry)\n- [Anthropic 包文档](https://github.com/microsoft/agent-framework/tree/main/python/packages/anthropic)\n- [.NET 示例：OpenAI Responses](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/02-agents/AgentProviders/Agent_With_OpenAIResponses)\n- [.NET 示例：OpenAI Chat Completion](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/02-agents/AgentProviders/Agent_With_OpenAIChatCompletion)\n\n---\n\n\n\n## 工具与技能系统\n\n### 相关页面\n\n相关主题：[Agent 基础](#agent-basics)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/core/agent_framework/_tools.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_tools.py)\n- [python/packages/core/agent_framework/_skills.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_skills.py)\n- [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)\n- [dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs)\n- [dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs)\n- [dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs)\n
\n\n# 工具与技能系统\n\n## 概述\n\nAgent Framework 的**工具与技能系统**是框架的核心扩展机制，旨在赋予 AI Agent 执行特定任务和访问领域知识的能力。该系统由两个相互关联但功能独立的子系统组成：\n\n- **工具系统 (Tools)**：为 Agent 提供可调用的函数能力，实现与外部系统的交互\n- **技能系统 (Skills)**：为 Agent 提供领域特定的指令、文档和资源，实现知识驱动的任务执行\n\n资料来源：[python/samples/01-get-started/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/01-get-started/README.md)\n\n## 系统架构\n\n```mermaid\ngraph TD\n subgraph \"Agent Framework 工具与技能系统\"\n subgraph \"工具层 (Tools)\"\n A[Function Tool] --> B[ToolDefinition]\n C[FileMemory Tool] --> B\n D[Custom Tools] --> B\n end\n \n subgraph \"技能层 (Skills)\"\n E[AgentSkill 抽象基类] --> F[FileBasedSkill]\n E --> G[AgentInlineSkill]\n G --> H[AgentInlineSkillContentBuilder]\n end\n \n subgraph \"技能提供者\"\n I[AgentSkillsProvider] --> E\n J[AIContext] --> I\n end\n \n subgraph \"Agent 核心\"\n K[ChatClientAgent] --> L[工具调用]\n K --> M[技能加载]\n L --> B\n M --> I\n end\n end\n```\n\n## 工具系统\n\n### 工具定义\n\n工具系统基于函数工具定义，Agent 可以通过调用这些工具执行特定操作。工具定义包含以下核心属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | string | 工具名称，用于标识和调用 |\n| description | string | 工具功能描述，供 LLM 理解何时使用 |\n| parameters | JSON Schema | 工具参数规范 |\n| handler | Function | 工具执行逻辑 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs)\n\n### 内置工具示例\n\n#### FileMemory 工具集\n\nFileMemory 系统提供了一套完整的文件管理工具，Agent 可以使用这些工具进行持久化存储和知识检索：\n\n| 工具名称 | 功能 |\n|----------|------|\n| FileMemory_ReadFile | 读取内存文件内容 |\n| FileMemory_ListFiles | 列出可用的内存文件 |\n| FileMemory_SaveFile | 保存或更新内存文件 |\n| FileMemory_SearchFiles | 搜索内存文件内容 |\n\n```csharp\n[Description(\"Save a memory file with the given name and content. Overwrites the file if it already exists. Include a description for large files to provide a summary that helps with discovery.\")]\nprivate async Task SaveFileAsync(\n string fileName, \n string content, \n string? description = null, \n CancellationToken cancellationToken = default)\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs:54-60](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs)\n\n### 工具注册与调用流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as ChatClientAgent\n participant Tools as 工具系统\n participant LLM as 语言模型\n \n User->>Agent: 发送请求\n Agent->>LLM: 发送包含工具定义的请求\n LLM->>LLM: 分析任务，决定调用工具\n LLM->>Agent: 返回工具调用请求\n Agent->>Tools: 执行工具函数\n Tools->>Tools: 处理业务逻辑\n Tools-->>Agent: 返回执行结果\n Agent->>LLM: 发送工具结果\n LLM-->>Agent: 生成最终响应\n Agent-->>User: 返回结果\n```\n\n## 技能系统\n\n### 技能架构概述\n\n技能系统采用抽象基类设计，支持多种技能定义方式：\n\n```mermaid\nclassDiagram\n class AgentSkill {\n <>\n +Content: string {abstract}\n +Resources: IReadOnlyList~AgentSkillResource~?\n +Scripts: IReadOnlyList~AgentSkillScript~?\n }\n \n class FileBasedSkill {\n +Content: string\n }\n \n class AgentInlineSkill {\n +Name: string\n +Description: string\n +Instructions: string\n +License: string?\n +Compatibility: string?\n +AllowedTools: string?\n +Metadata: AdditionalPropertiesDictionary?\n }\n \n AgentSkill <|-- FileBasedSkill\n AgentSkill <|-- AgentInlineSkill\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)\n\n### AgentSkill 抽象基类\n\n`AgentSkill` 是所有技能类型的基类，定义了技能的通用接口：\n\n```csharp\n/// \n/// For file-based skills this is the raw SKILL.md file content, optionally\n/// augmented with a synthesized scripts block when scripts are present.\n/// For code-defined skills this is a synthesized XML document\n/// containing name, description, and body (instructions, resources, scripts).\n/// \npublic abstract string Content { get; }\n\n/// \n/// Gets the resources associated with this skill, or null if none.\n/// \npublic virtual IReadOnlyList? Resources => null;\n\n/// \n/// Gets the scripts associated with this skill, or null if none.\n/// \npublic virtual IReadOnlyList? Scripts => null;\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs:15-35](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)\n\n### 代码定义技能 (AgentInlineSkill)\n\n`AgentInlineSkill` 允许开发者以编程方式定义技能，无需使用外部文件：\n\n```csharp\npublic AgentInlineSkill(\n string name,\n string description,\n string instructions,\n string? license = null,\n string? compatibility = null,\n string? allowedTools = null,\n AdditionalPropertiesDictionary? metadata = null,\n JsonSerializerOptions? serializerOptions = null)\n```\n\n#### 构造函数参数说明\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| name | string | 是 | 技能名称，使用 kebab-case 格式 |\n| description | string | 是 | 技能描述，用于发现和选择 |\n| instructions | string | 是 | 技能指令文本 |\n| license | string? | 否 | 许可证名称或引用 |\n| compatibility | string? | 否 | 兼容性信息（最多 500 字符） |\n| allowedTools | string? | 否 | 预批准工具的空格分隔列表 |\n| metadata | AdditionalPropertiesDictionary? | 否 | 任意键值元数据 |\n| serializerOptions | JsonSerializerOptions? | 否 | 脚本和资源序列化选项 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkill.cs)\n\n### 技能内容构建器\n\n`AgentInlineSkillContentBuilder` 内部类负责将代码定义的技能转换为 XML 格式的内容字符串：\n\n```csharp\npublic static string Build(\n string name,\n string description,\n string instructions,\n IReadOnlyList? resources,\n IReadOnlyList? scripts)\n{\n var sb = new StringBuilder();\n \n sb.Append($\"{EscapeXmlString(name)}\\n\")\n .Append($\"{EscapeXmlString(description)}\\n\\n\")\n .Append(\"\\n\")\n .Append(EscapeXmlString(instructions))\n .Append(\"\\n\");\n // ...\n}\n```\n\n生成的 XML 结构示例：\n\n```xml\ncode-defined-skill\nA code-defined skill example\n\n\nYour skill instructions here...\n\n\n\n\n\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs)\n\n### AgentSkillsProvider 技能提供者\n\n`AgentSkillsProvider` 是 AI 上下文提供者，负责将技能信息注入到 Agent 的执行上下文中：\n\n```mermaid\ngraph LR\n subgraph \"AgentSkillsProvider 内部机制\"\n A[技能源] -->|读取| B[AgentSkillsSource]\n C[提示模板] -->|格式化| D[SkillsPlaceholder]\n B -->|注入| D\n D --> E[AIContext]\n end\n```\n\n#### 默认技能指令模板\n\n```csharp\nprivate const string DefaultSkillsInstructionPrompt =\n \"\"\"\n You have access to skills containing domain-specific knowledge and capabilities.\n Each skill provides specialized instructions, reference documents, and assets for specific tasks.\n\n \n {skills}\n \n\n When a task aligns with a skill's domain, follow these steps in exact order:\n - Use `load_skill` to retrieve the skill's instructions.\n - Follow the provided guidance.\n {resource_instructions}\n {script_instructions}\n Only load what is needed, when it is needed.\n \"\"\";\n```\n\n#### 模板占位符说明\n\n| 占位符 | 说明 |\n|--------|------|\n| `{skills}` | 可用技能列表 |\n| `{resource_instructions}` | 资源相关指令 |\n| `{script_instructions}` | 脚本执行指令 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs)\n\n### 技能与 Agent 的集成流程\n\n```mermaid\nflowchart TD\n A[定义技能] --> B{技能类型选择}\n B -->|文件型| C[创建 SKILL.md]\n B -->|代码型| D[实例化 AgentInlineSkill]\n \n C --> E[注册到 AgentSkillsProvider]\n D --> E\n \n E --> F[Agent 执行时加载技能]\n F --> G{技能是否匹配任务}\n \n G -->|是| H[加载技能指令]\n G -->|否| I[跳过技能]\n \n H --> J[执行技能任务]\n I --> K[继续其他任务]\n J --> L[返回执行结果]\n K --> L\n```\n\n## 工具与技能协同\n\n### 工具调用链\n\n当技能包含脚本时，系统会通过 `run_skill_script` 工具执行脚本：\n\n```mermaid\nsequenceDiagram\n participant Agent as Agent\n participant LLM as Language Model\n participant Provider as AgentSkillsProvider\n participant Script as 技能脚本\n \n Agent->>LLM: 请求执行任务\n LLM->>Agent: 识别需要使用技能\n Agent->>Provider: 加载技能\n Provider-->>Agent: 返回技能内容\n Agent->>LLM: 传递技能指令\n LLM->>Agent: 决定调用工具\n Agent->>Script: 执行 run_skill_script\n Script-->>Agent: 返回执行结果\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs)\n\n### 能力说明\n\n| 能力 | 工具支持 | 技能支持 | 说明 |\n|------|----------|----------|------|\n| 函数调用 | ✅ | ❌ | 工具通过函数定义实现调用 |\n| 知识注入 | ❌ | ✅ | 技能通过指令和资源注入知识 |\n| 持久化存储 | ✅ | ❌ | FileMemory 工具提供文件操作 |\n| 脚本执行 | ❌ | ✅ | 技能脚本通过专用工具执行 |\n| 动态发现 | ✅ | ✅ | 两者都支持描述性元数据 |\n\n## 使用示例\n\n### .NET 代码定义技能\n\n```csharp\nvar mySkill = new AgentInlineSkill(\n name: \"code-defined-skill\",\n description: \"A skill defined in code\",\n instructions: \"Follow these steps to complete the task...\",\n license: \"MIT\",\n compatibility: \"Agent Framework v1.0+\",\n allowedTools: \"FileMemory_ReadFile FileMemory_SaveFile\",\n metadata: new AdditionalPropertiesDictionary\n {\n { \"author\", \"developer@example.com\" },\n { \"version\", \"1.0.0\" }\n }\n);\n```\n\n### Python 工具装饰器\n\n```python\nfrom agent_framework import tool\n\n@tool\ndef add_numbers(a: int, b: int) -> int:\n \"\"\"Add two numbers together.\"\"\"\n return a + b\n```\n\n## 最佳实践\n\n### 技能设计原则\n\n1. **单一职责**：每个技能应专注于特定领域\n2. **清晰描述**：使用准确的描述帮助 LLM 选择合适的技能\n3. **版本管理**：通过元数据跟踪技能版本\n4. **权限控制**：使用 `allowedTools` 限制技能可访问的工具\n\n### 工具设计原则\n\n1. **原子性**：每个工具应执行单一操作\n2. **幂等性**：工具应能安全地重复执行\n3. **错误处理**：提供清晰的错误消息\n4. **参数验证**：使用 JSON Schema 严格定义参数\n\n## 相关资源\n\n- [Agent Skills Specification](https://agentskills.io/)\n- [Microsoft Agent Framework 文档](https://github.com/microsoft/agent-framework)\n- [入门示例](../samples/01-get-started/)\n\n---\n\n\n\n## 工作流系统概述\n\n### 相关页面\n\n相关主题：[工作流编排模式](#workflow-patterns), [检查点与恢复机制](#checkpoint-recovery)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/core/agent_framework/_workflows/_workflow.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_workflows/_workflow.py)\n- [python/packages/core/agent_framework/_workflows/_workflow_builder.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_workflows/_workflow_builder.py)\n- [dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilder.cs)\n- [dotnet/src/Microsoft.Agents.AI.Workflows/Executor.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/Executor.cs)\n- [python/samples/03-workflows/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/03-workflows/README.md)\n- [dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs)\n- [python/samples/03-workflows/declarative/README.md](https://github.com/microsoft/agent-framework/blob/main/python/samples/03-workflows/declarative/README.md)\n
\n\n# 工作流系统概述\n\n## 1. 系统简介\n\nMicrosoft Agent Framework 的工作流系统（Workflow System）是一个用于编排多代理（Multi-Agent）协作的核心模块。该系统提供了两种互补的工作流定义方式：**命令式工作流（Imperative Workflow）** 和 **声明式工作流（Declarative Workflow）**。通过工作流系统，开发者可以将多个代理（Agent）、执行器（Executor）、工具（Tool）以及控制流逻辑组合成复杂的自动化流程。\n\n命令式工作流允许开发者使用 Python 或 C# 等编程语言直接编写工作流逻辑，而声明式工作流则支持通过 YAML 配置文件定义工作流，实现业务逻辑与代码的解耦。资料来源：[python/samples/03-workflows/README.md]()、[python/samples/03-workflows/declarative/README.md]()\n\n## 2. 核心概念\n\n### 2.1 执行器（Executor）\n\n执行器是工作流系统的基本构建单元，负责执行具体的任务或调用代理。每个执行器接收输入、执行逻辑并产生输出，输出可以传递给后续的执行器形成链条。\n\n在 .NET 实现中，`Executor` 类是执行器的基类，提供了异步执行能力。资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/Executor.cs]()\n\n### 2.2 工作流（Workflow）\n\n工作流是执行器的容器，定义了执行器的组织结构和执行顺序。工作流可以包含：\n\n- **起始执行器（Start Executor）**：工作流的入口点\n- **执行器图（Executor Graph）**：执行器之间的连接关系\n- **状态管理（State Management）**：工作流执行过程中的状态存储\n\n```mermaid\ngraph LR\n A[用户输入] --> B[起始执行器]\n B --> C[执行器 1]\n C --> D[执行器 2]\n D --> E[执行器 N]\n E --> F[工作流输出]\n```\n\n资料来源：[python/packages/core/agent_framework/_workflows/_workflow.py]()\n\n### 2.3 状态（State）\n\n工作流状态用于在工作流执行过程中存储和传递数据。状态可以包含：\n\n| 状态字段 | 描述 |\n|---------|------|\n| `turn.*` | 当前轮次相关的变量，如 `turn.greeting` |\n| `user.*` | 用户相关数据 |\n| `agent.*` | 代理生成的数据 |\n| `_executor_state` | 执行器内部状态（系统保留） |\n\n资料来源：[python/samples/03-workflows/declarative/README.md]()\n\n## 3. 工作流类型\n\n### 3.1 命令式工作流（Imperative Workflow）\n\n命令式工作流使用代码直接定义，允许开发者使用完整的编程语言能力。\n\n#### 3.1.1 函数式工作流（Functional Workflow）\n\n函数式工作流将工作流编写为普通的异步函数，使用原生的 `if/else`、循环和 `asyncio.gather` 等控制流语法。\n\n```python\nasync def my_workflow(input_data: dict) -> dict:\n # 原生 Python 异步控制流\n if input_data.get(\"type\") == \"A\":\n result = await agent_a.invoke(input_data)\n else:\n results = await asyncio.gather(\n agent_b.invoke(input_data),\n agent_c.invoke(input_data)\n )\n result = combine_results(results)\n return result\n```\n\n资料来源：[python/samples/03-workflows/README.md]()\n\n#### 3.1.2 图工作流（Graph Workflow）\n\n图工作流通过连接执行器和边（Edge）来构建有向无环图（DAG）结构。\n\n```mermaid\ngraph TD\n Start[起始执行器] --> AgentA[代理 A]\n AgentA -->|条件分支| Condition{条件判断}\n Condition -->|true| AgentB[代理 B]\n Condition -->|false| AgentC[代理 C]\n AgentB --> End[结束]\n AgentC --> End\n```\n\n资料来源：[python/samples/03-workflows/README.md]()\n\n### 3.2 声明式工作流（Declarative Workflow）\n\n声明式工作流通过 YAML 文件定义，适合业务逻辑稳定、频繁变更的场景。\n\n#### 3.2.1 基本结构\n\n```yaml\nname: my-workflow\ndescription: 工作流描述\n\nactions:\n - kind: SetValue\n path: turn.greeting\n value: \"你好\"\n\n - kind: SendActivity\n activity:\n text: \"=turn.greeting\"\n```\n\n资料来源：[python/samples/03-workflows/declarative/README.md]()\n\n#### 3.2.2 支持的动作类型\n\n| 动作类型 | 功能描述 |\n|---------|---------|\n| `SetValue` | 设置变量值 |\n| `SetVariable` | 设置变量（.NET 风格命名） |\n| `AppendValue` | 向列表追加值 |\n| `If` | 条件分支 |\n| `Switch` | 多路分支 |\n| `Foreach` | 遍历集合 |\n| `RepeatUntil` | 循环直到条件满足 |\n| `SendActivity` | 向用户发送消息 |\n| `GotoAction` | 跳转到指定标签动作 |\n\n资料来源：[python/samples/03-workflows/declarative/README.md]()\n\n## 4. 系统架构\n\n### 4.1 架构组件\n\n```mermaid\ngraph TD\n subgraph \"Python SDK\"\n PYWF[Python 工作流]\n PYFB[函数式构建器]\n PYGB[图构建器]\n PYDB[声明式构建器]\n end\n \n subgraph \".NET SDK\"\n DNFWF[.NET 工作流]\n DNFB[WorkflowBuilder]\n DNDTB[DeclarativeWorkflowBuilder]\n end\n \n subgraph \"共享组件\"\n EX[Executor 执行器]\n ST[State 状态管理]\n CK[Checkpoint 检查点]\n end\n \n PYWF --> EX\n PYFB --> EX\n PYGB --> EX\n DNFWF --> EX\n DNFB --> EX\n DNDTB --> EX\n \n EX --> ST\n ST --> CK\n```\n\n### 4.2 工作流构建器\n\n#### 4.2.1 Python WorkflowBuilder\n\nPython 版本的 `WorkflowBuilder` 提供链式 API 构建工作流：\n\n```python\nworkflow = WorkflowBuilder(\n start_executor=my_start_executor\n).add_edge(\n from_executor=my_start_executor,\n to_executor=my_next_executor\n).build()\n```\n\n资料来源：[python/packages/core/agent_framework/_workflows/_workflow_builder.py]()\n\n#### 4.2.2 .NET WorkflowBuilder\n\n.NET 版本的 `WorkflowBuilder` 支持依赖注入和配置驱动：\n\n```csharp\nservices.AddAgentsWorkflows(options =>\n{\n options.WorkflowBuilder = workflowBuilder;\n});\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilder.cs]()\n\n#### 4.2.3 DeclarativeWorkflowBuilder\n\n声明式构建器从 YAML 加载工作流定义：\n\n```csharp\nvar workflow = DeclarativeWorkflowBuilder.Build(\"workflow.yaml\", options);\n```\n\n```python\n# Python 版本\nfrom agent_framework_declarative import load_workflow\nworkflow = load_workflow(\"workflow.yaml\")\n```\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs]()\n\n## 5. 执行模型\n\n### 5.1 同步与异步执行\n\n工作流支持同步和异步两种执行模式：\n\n```python\n# 非流式执行\nresult = await workflow.execute(input_data)\n\n# 流式执行\nasync for event in workflow.stream(input_data):\n print(event)\n```\n\n资料来源：[python/packages/core/agent_framework/_workflows/_workflow.py]()\n\n### 5.2 代理调用链\n\n在多代理工作流中，代理可以按顺序调用，形成处理链：\n\n```mermaid\ngraph LR\n A[用户输入] --> B[翻译代理
French Agent]\n B --> C[翻译代理
Spanish Agent]\n C --> D[翻译代理
English Agent]\n D --> E[最终输出]\n```\n\n每个代理接收前一个代理的输出作为输入，实现管道式处理。资料来源：[dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/README.md]()\n\n### 5.3 人机交互（HITL）\n\n声明式工作流支持人类在环（Human-in-the-Loop）模式，允许工作流暂停等待人工输入：\n\n```yaml\nactions:\n - kind: If\n condition: \"turn.needsApproval == true\"\n then:\n - kind: WaitForHumanInput\n timeout: 300\n```\n\n资料来源：[python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/README.md]()\n\n## 6. 状态持久化与检查点\n\n### 6.1 检查点机制\n\n工作流系统支持检查点（Checkpoint）功能，用于保存和恢复工作流执行状态：\n\n```mermaid\ngraph LR\n A[执行中] -->|保存| B[检查点]\n B -->|恢复| C[继续执行]\n B -->|重启| D[从起始执行]\n```\n\nDevUI 可以显示工作流的检查点信息，包括完整的状态快照。资料来源：[python/packages/devui/frontend/src/components/features/workflow/checkpoint-info-modal.tsx]()\n\n### 6.2 状态查看\n\n工作流状态可以通过 DevUI 的工作流视图组件查看：\n\n| 组件 | 功能 |\n|-----|------|\n| 状态徽章 | 显示当前状态变量 |\n| 原始 JSON | 展开查看完整状态 |\n| 检查点列表 | 历史状态快照 |\n\n资料来源：[python/packages/devui/frontend/src/components/features/workflow/workflow-view.tsx]()\n\n## 7. 工具与技能集成\n\n### 7.1 函数工具\n\n工作流中的代理可以调用函数工具（Function Tool）：\n\n```python\n@tool\ndef get_weather(location: str) -> str:\n \"\"\"获取指定位置的天气信息\"\"\"\n return f\"{location} 今天天气晴朗\"\n```\n\n资料来源：[python/samples/01-get-started/README.md]()\n\n### 7.2 技能（Skills）\n\n技能是一种结构化的工具定义方式，支持代码定义和文件定义两种形式：\n\n| 类型 | 描述 |\n|-----|------|\n| 代码定义技能 | 直接在代码中定义 |\n| 文件定义技能 | 通过 `SKILL.md` 文件定义 |\n\n技能可以包含脚本、参考资料和执行命令。资料来源：[python/samples/02-agents/skills/mixed_skills/README.md]()\n\n## 8. 开发工具\n\n### 8.1 DevUI\n\nDevUI 提供了工作流的图形化开发界面：\n\n| 功能 | 说明 |\n|-----|-----|\n| 可视化编辑器 | 编辑和测试工作流 |\n| 实时执行 | 流式显示执行结果 |\n| 检查点查看 | 查看历史状态快照 |\n| 示例库 | 预置工作流示例 |\n\n资料来源：[python/packages/devui/README.md]()\n\n### 8.2 代码导出（Eject）\n\n声明式工作流支持导出为代码，便于进一步定制：\n\n```csharp\nvar code = DeclarativeWorkflowBuilder.Eject(\n \"workflow.yaml\",\n DeclarativeWorkflowLanguage.CSharp,\n \"MyNamespace\"\n);\n```\n\n支持的目标语言：\n\n| 语言 | 枚举值 |\n|-----|-------|\n| Python | `DeclarativeWorkflowLanguage.Python` |\n| C# | `DeclarativeWorkflowLanguage.CSharp` |\n| JavaScript | `DeclarativeWorkflowLanguage.JavaScript` |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowBuilder.cs]()\n\n## 9. 快速开始\n\n### 9.1 Python 入门示例\n\n```bash\npip install agent-framework\n```\n\n| 示例 | 文件 | 学习内容 |\n|-----|------|---------|\n| 1 | `01_hello_agent.py` | 创建第一个代理 |\n| 2 | `02_add_tools.py` | 添加函数工具 |\n| 3 | `03_multi_turn.py` | 多轮对话 |\n| 4 | `04_memory.py` | 自定义上下文 |\n| 5 | `05_functional_workflow_with_agents.py` | 函数式工作流 |\n| 6 | `06_functional_workflow_basics.py` | 工作流基础 |\n| 7 | `07_first_graph_workflow.py` | 图工作流 |\n| 8 | `08_host_your_agent.py` | 部署代理 |\n\n资料来源：[python/samples/01-get-started/README.md]()\n\n### 9.2 .NET 入门示例\n\n```bash\ncd dotnet/samples\ndotnet run --project 01-hello-agent\n```\n\n## 10. 最佳实践\n\n1. **选择合适的工作流类型**：业务逻辑稳定时使用声明式工作流，需要复杂逻辑时使用命令式工作流\n2. **合理设计状态结构**：使用清晰的前缀命名（如 `turn.`、`user.`）区分不同来源的数据\n3. **使用检查点恢复**：对于长时间运行的工作流，定期保存检查点便于故障恢复\n4. **流式输出优化**：对延迟敏感的应用使用流式执行模式\n5. **工具封装**：将常用功能封装为工具，便于在多个工作流中复用\n\n## 11. 相关资源\n\n| 资源类型 | 链接 |\n|---------|------|\n| Python 包 | `pip install agent-framework` |\n| 声明式包 | `pip install agent-framework-declarative` |\n| 可视化支持 | `pip install agent-framework[viz]` |\n| 官方文档 | [Agent Framework 文档](https://github.com/microsoft/agent-framework) |\n\n---\n\n\n\n## 工作流编排模式\n\n### 相关页面\n\n相关主题：[工作流系统概述](#workflow-overview), [检查点与恢复机制](#checkpoint-recovery)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/orchestrations/agent_framework_orchestrations/_sequential.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/orchestrations/agent_framework_orchestrations/_sequential.py)\n- [python/packages/orchestrations/agent_framework_orchestrations/_concurrent.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/orchestrations/agent_framework_orchestrations/_concurrent.py)\n- [python/packages/orchestrations/agent_framework_orchestrations/_handoff.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/orchestrations/agent_framework_orchestrations/_handoff.py)\n- [dotnet/src/Microsoft.Agents.AI.Workflows/GroupChatManager.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/GroupChatManager.cs)\n- [dotnet/src/Microsoft.Agents.AI.Workflows/HandoffWorkflowBuilder.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/HandoffWorkflowBuilder.cs)\n
\n\n# 工作流编排模式\n\n## 概述\n\n工作流编排（Workflow Orchestration）是Microsoft Agent Framework中的核心能力，它允许开发者将多个代理（Agent）、工具（Tool）和功能组件组合成复杂的自动化流程。Agent Framework提供了多种编排模式，包括顺序执行、并发执行和交接（Handoff）机制，使开发者能够构建从简单到复杂的各种自动化工作流。\n\n工作流编排系统的主要特点包括：\n\n- **声明式定义**：通过Python装饰器或C#构建器模式声明工作流结构\n- **状态管理**：内置的状态传递和上下文共享机制\n- **异步支持**：完整的异步执行模型，支持流式和非流式响应\n- **错误处理**：统一的异常捕获和恢复机制\n- **可扩展性**：支持自定义执行器和节点类型\n\n## 核心组件\n\n### 执行器（Executor）\n\n执行器是工作流编排的基本构建单元，负责执行具体的任务或调用代理。每个执行器可以包含输入参数、执行逻辑和输出处理。\n\n```mermaid\ngraph LR\n A[输入数据] --> B[执行器 Executor]\n B --> C{执行类型}\n C -->|同步| D[同步执行]\n C -->|异步| E[异步执行]\n C -->|流式| F[流式执行]\n D --> G[输出结果]\n E --> G\n F --> G\n```\n\n### 顺序工作流（Sequential Workflow）\n\n顺序工作流按照定义的顺序依次执行各个执行器，前一个执行器的输出作为下一个执行器的输入。这种模式适用于步骤之间存在依赖关系的场景。\n\n**Python实现**：\n\n```python\nfrom agent_framework_orchestrations import SequentialWorkflow, Step\n\nworkflow = SequentialWorkflow(\n steps=[\n Step(executor=data_loader, name=\"load_data\"),\n Step(executor=processor, name=\"process_data\"),\n Step(executor=formatter, name=\"format_output\")\n ]\n)\n```\n\n**C#实现**：\n\n```csharp\nvar workflow = new SequentialWorkflowBuilder()\n .AddStep(dataLoader)\n .AddStep(processor)\n .AddStep(formatter)\n .Build();\n```\n\n### 并发工作流（Concurrent Workflow）\n\n并发工作流允许同时执行多个执行器，通过并行处理提高整体效率。适用于彼此独立、可同时运行的任务。\n\n```mermaid\ngraph TD\n A[开始] --> B[并发执行]\n B --> C[执行器 A]\n B --> D[执行器 B]\n B --> E[执行器 N]\n C --> F[收集结果]\n D --> F\n E --> F\n F --> G[聚合输出]\n G --> H[结束]\n```\n\n**关键参数**：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `max_concurrency` | int | 最大并发数，限制同时运行的任务数量 |\n| `timeout` | timedelta | 单个任务的最大执行时间 |\n| `fail_fast` | bool | 任何任务失败时是否立即停止 |\n\n### 交接工作流（Handoff Workflow）\n\n交接工作流实现了代理之间的上下文传递，允许一个代理将控制权和会话状态移交给另一个代理。这是构建多代理协作系统的核心机制。\n\n```mermaid\ngraph LR\n A[Agent A] -->|Handoff| B[上下文传递]\n B --> C[Agent B]\n B --> D[消息队列]\n D --> C\n C --> E[继续执行]\n```\n\n## 交接机制（Handoff）\n\n### 工作原理\n\n交接机制是Agent Framework中最核心的编排模式之一，它允许：\n\n1. **上下文转移**：当前代理的状态、记忆和对话历史完整传递给下一个代理\n2. **控制权移交**：执行流程从源代理平滑转移到目标代理\n3. **消息传递**：支持通过消息队列进行异步交接\n\n### HandoffWorkflowBuilder（C#）\n\n`HandoffWorkflowBuilder`提供了声明式的交接工作流构建方式：\n\n```csharp\nvar handoffWorkflow = new HandoffWorkflowBuilder(\"transfer_to_specialist\")\n .WithSourceAgent(\"general_agent\")\n .WithTargetAgent(\"specialist_agent\")\n .WithContextMapping(mappings => {\n mappings.Map(\"user_preferences\", \"preferences\");\n mappings.Map(\"conversation_history\", \"history\");\n })\n .WithHandoffMessage(\"正在将您的请求转交给专家代理...\")\n .Build();\n```\n\n**配置选项**：\n\n| 选项 | 说明 |\n|------|------|\n| `WithSourceAgent` | 指定源代理标识符 |\n| `WithTargetAgent` | 指定目标代理标识符 |\n| `WithContextMapping` | 配置上下文字段映射规则 |\n| `WithHandoffMessage` | 设置交接时的提示消息 |\n| `WithRetryPolicy` | 配置交接失败重试策略 |\n\n## 群组聊天管理器（GroupChatManager）\n\n`GroupChatManager`是.NET实现中的群组聊天协调器，负责管理多个代理之间的对话交互和消息路由。\n\n### 核心职责\n\n```mermaid\ngraph TD\n A[用户消息] --> B[GroupChatManager]\n B --> C{路由决策}\n C -->|选择代理| D[代理 A]\n C -->|选择代理| E[代理 B]\n C -->|选择代理| F[代理 N]\n D --> G[响应]\n E --> G\n F --> G\n G --> H[消息汇总]\n H --> I[返回用户]\n```\n\n### 管理功能\n\n| 功能 | 说明 |\n|------|------|\n| 代理注册 | 允许动态注册和注销参与对话的代理 |\n| 消息路由 | 根据规则或AI判断将消息路由到合适的代理 |\n| 状态同步 | 维护所有参与代理的当前状态 |\n| 发言控制 | 管理多代理场景下的发言顺序和权限 |\n\n## 最佳实践\n\n### 1. 工作流设计原则\n\n- **单一职责**：每个执行器应专注于单一任务\n- **松耦合**：执行器之间通过明确定义的接口通信\n- **错误边界**：为关键步骤添加错误处理和回退逻辑\n\n### 2. 性能优化\n\n- **识别并行机会**：分析工作流中的独立步骤，尽量并行化\n- **设置合理超时**：防止单个任务长时间阻塞整个工作流\n- **资源限制**：使用`max_concurrency`控制并发资源使用\n\n### 3. 调试技巧\n\n- **启用详细日志**：使用日志记录每个步骤的输入输出\n- **状态检查点**：在关键节点保存工作流状态便于恢复\n- **逐步执行**：开发阶段使用单步模式验证逻辑\n\n## 相关示例\n\n| 示例文件 | 模式 | 说明 |\n|----------|------|------|\n| `05_functional_workflow_with_agents.py` | 功能工作流 | 在函数式工作流中调用代理 |\n| `06_functional_workflow_basics.py` | 基础功能工作流 | 纯函数组合的工作流 |\n| `07_first_graph_workflow.py` | 图工作流 | 使用边连接执行器构建图 |\n| `08_host_your_agent.py` | 托管代理 | 将代理部署到生产环境 |\n\n## 总结\n\n工作流编排模式是构建复杂AI应用的基础，Agent Framework提供了从简单顺序处理到复杂多代理协作的完整解决方案。开发者可以根据业务需求选择合适的编排模式，并通过框架提供的丰富API实现高效、可靠的工作流系统。\n\n---\n\n\n\n## 检查点与恢复机制\n\n### 相关页面\n\n相关主题：[工作流系统概述](#workflow-overview), [工作流编排模式](#workflow-patterns)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [python/packages/core/agent_framework/_workflows/_checkpoint.py](https://github.com/microsoft/agent-framework/blob/main/python/packages/core/agent_framework/_workflows/_checkpoint.py)\n- [python/samples/03-workflows/checkpoint/checkpoint_with_resume.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/03-workflows/checkpoint/checkpoint_with_resume.py)\n- [dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs)\n- [dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs](https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs)\n
\n\n# 检查点与恢复机制\n\n## 概述\n\n检查点（Checkpoint）与恢复（Resume）机制是 Agent Framework 工作流系统的核心功能之一，它允许长时间运行的工作流在中断后从上一个保存点继续执行，而无需重新开始整个流程。\n\n### 核心能力\n\n| 能力 | 描述 |\n|------|------|\n| 状态持久化 | 保存工作流的完整执行状态到外部存储 |\n| 断点恢复 | 从任意检查点恢复工作流执行 |\n| 会话管理 | 通过会话ID关联多个检查点 |\n| HIL 支持 | 支持人类在环（Human-in-the-Loop）场景下的暂停与恢复 |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/ICheckpointManager.cs:1-15]()\n\n---\n\n## 架构设计\n\n### 系统组件图\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n A[Workflow 执行环境] --> B[Checkpoint Manager]\n end\n \n subgraph \"核心接口\"\n C[ICheckpointManager] \n D[IWorkflowExecutionEnvironment]\n end\n \n subgraph \"存储层\"\n E[(检查点存储)]\n F[(会话状态)]\n end\n \n B --> C\n B --> E\n A --> D\n D -->|ResumeAsync| B\n C -->|CommitCheckpointAsync| E\n C -->|LookupCheckpointAsync| F\n \n G[工作流执行器] -->|创建检查点| B\n B -->|返回 CheckpointInfo| G\n```\n\n### 检查点生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 执行中: 开始工作流\n 执行中 --> 暂停: 遇到 HIL / 中断\n 暂停 --> 保存检查点: CommitCheckpointAsync\n 保存检查点 --> 已保存: 返回 CheckpointInfo\n 已保存 --> 恢复执行: ResumeAsync\n 恢复执行 --> 执行中: 加载检查点状态\n 执行中 --> 完成: 正常结束\n 暂停 --> 取消: 用户取消\n 已保存 --> [*]: 清理\n```\n\n资料来源：[python/packages/core/agent_framework/_workflows/_checkpoint.py:1-50]()\n\n---\n\n## 核心数据模型\n\n### CheckpointInfo\n\n检查点信息模型，用于唯一标识和检索检查点。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `SessionId` | `string` | 会话唯一标识符 |\n| `CheckpointId` | `string` | 检查点唯一标识符（自动生成） |\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/CheckpointInfo.cs:10-20]()\n\n```csharp\npublic sealed class CheckpointInfo : IEquatable\n{\n public string SessionId { get; }\n public string CheckpointId { get; }\n \n internal CheckpointInfo(string sessionId) \n : this(sessionId, Guid.NewGuid().ToString(\"N\")) { }\n \n public CheckpointInfo(string sessionId, string checkpointId)\n {\n this.SessionId = Throw.IfNullOrEmpty(sessionId);\n this.CheckpointId = Throw.IfNullOrEmpty(checkpointId);\n }\n}\n```\n\n### Checkpoint 接口模型\n\n```mermaid\nclassDiagram\n class Checkpoint {\n +string SessionId\n +string CheckpointId\n +Dictionary state\n +WorkflowTaskMetadata metadata\n +string serialized_state\n }\n \n class CheckpointInfo {\n +string SessionId\n +string CheckpointId\n }\n \n Checkpoint --> CheckpointInfo : 通过 CommitCheckpointAsync 返回\n```\n\n资料来源：[python/packages/core/agent_framework/_workflows/_checkpoint.py:15-35]()\n\n---\n\n## 接口定义\n\n### ICheckpointManager\n\n检查点管理器接口，定义检查点的提交和检索操作。\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/ICheckpointManager.cs:10-40]()\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `CommitCheckpointAsync` | `ValueTask` | 提交检查点并返回检索信息 |\n| `LookupCheckpointAsync` | `ValueTask` | 根据检查点信息检索完整状态 |\n\n#### CommitCheckpointAsync\n\n```csharp\n/// \n/// 提交指定的检查点并返回可用于后续检索的信息\n/// \n/// 当前会话或执行上下文的标识符\n/// 要提交的检查点\n/// 表示传入检查点的 CheckpointInfo\nValueTask CommitCheckpointAsync(string sessionId, Checkpoint checkpoint);\n```\n\n#### LookupCheckpointAsync\n\n```csharp\n/// \n/// 检索与指定检查点信息关联的检查点\n/// \n/// 当前会话的标识符\n/// 用于标识检查点的信息\n/// 包含关联 Checkpoint 的 ValueTask\n/// 如果未找到检查点\nValueTask LookupCheckpointAsync(string sessionId, CheckpointInfo checkpointInfo);\n```\n\n### IWorkflowExecutionEnvironment\n\n工作流执行环境接口，提供从检查点恢复执行的能力。\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowExecutionEnvironment.cs:1-20]()\n\n```csharp\n/// \n/// 从检查点恢复工作流执行\n/// \n/// 要执行的工作流\n/// 要恢复的检查点对应的 CheckpointInfo\n/// 取消令牌\n/// 包含 Run 实例的 ValueTask\nValueTask ResumeAsync(\n Workflow workflow, \n CheckpointInfo fromCheckpoint, \n CancellationToken cancellationToken = default);\n```\n\n---\n\n## Python 实现\n\n### 检查点类结构\n\n资料来源：[python/packages/core/agent_framework/_workflows/_checkpoint.py:1-80]()\n\n```python\nclass Checkpoint:\n \"\"\"工作流执行检查点\"\"\"\n def __init__(\n self,\n state: dict[str, Any],\n checkpoint_id: str,\n session_id: str,\n metadata: Optional[WorkflowTaskMetadata] = None,\n ):\n self.checkpoint_id = checkpoint_id\n self.session_id = session_id\n self.state = state\n self.metadata = metadata\n\nclass CheckpointInfo:\n \"\"\"检查点元信息，用于恢复\"\"\"\n def __init__(\n self,\n checkpoint_id: str,\n session_id: str,\n created_at: datetime,\n ):\n self.checkpoint_id = checkpoint_id\n self.session_id = session_id\n self.created_at = created_at\n```\n\n### 异步检查点管理器\n\n```python\nclass AsyncCheckpointManager(ABC):\n \"\"\"异步检查点管理器基类\"\"\"\n \n @abstractmethod\n async def commit(self, session_id: str, checkpoint: Checkpoint) -> CheckpointInfo:\n \"\"\"提交检查点\"\"\"\n pass\n \n @abstractmethod\n async def lookup(self, session_id: str, checkpoint_info: CheckpointInfo) -> Checkpoint:\n \"\"\"检索检查点\"\"\"\n pass\n \n @abstractmethod\n async def list_checkpoints(self, session_id: str) -> list[CheckpointInfo]:\n \"\"\"列出所有检查点\"\"\"\n pass\n```\n\n资料来源：[python/packages/core/agent_framework/_workflows/_checkpoint.py:80-100]()\n\n---\n\n## 使用示例\n\n### Python 示例：检查点与恢复\n\n资料来源：[python/samples/03-workflows/checkpoint/checkpoint_with_resume.py:1-120]()\n\n```python\nimport asyncio\nfrom agent_framework import Agent, WorkflowBuilder\nfrom agent_framework.workflows import (\n CheckpointManager,\n Checkpoint,\n CheckpointInfo,\n)\n\n# 创建带检查点支持的工作流\nworkflow = WorkflowBuilder(start_executor=my_executor)\\\n .with_checkpointing()\\\n .build()\n\nasync def run_with_checkpoint():\n # 运行工作流并获取检查点\n run = await workflow.run(input_data)\n \n # 在 HIL 暂停点保存检查点\n checkpoint_info = await run.save_checkpoint()\n \n print(f\"检查点已保存: {checkpoint_info.checkpoint_id}\")\n \n # 模拟中断后恢复\n resumed_run = await workflow.resume(\n from_checkpoint=checkpoint_info\n )\n \n return resumed_run\n\nasyncio.run(run_with_checkpoint())\n```\n\n### .NET 示例：检查点与重新水化\n\n资料来源：[dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs:1-80]()\n\n```csharp\nusing Microsoft.Agents.AI.Workflows;\nusing Microsoft.Agents.AI.Workflows.Checkpointing;\n\n// 创建检查点管理器\nICheckpointManager checkpointManager = new CheckpointManagerImpl(storageProvider);\n\n// 执行工作流并获取检查点\nWorkflow workflow = BuildWorkflow();\nvar run = await workflow.RunAsync(inputData);\n\n// 在适当位置提交检查点\nvar checkpointInfo = await checkpointManager.CommitCheckpointAsync(\n sessionId: run.SessionId,\n checkpoint: new Checkpoint\n {\n SessionId = run.SessionId,\n State = run.GetState(),\n Metadata = run.GetMetadata()\n });\n\nConsole.WriteLine($\"检查点已保存: {checkpointInfo.CheckpointId}\");\n\n// 模拟应用重启后恢复\nvar checkpointToResume = new CheckpointInfo(\n sessionId: \"previous-session-id\",\n checkpointId: checkpointInfo.CheckpointId\n);\n\nvar resumedRun = await workflow.ResumeAsync(checkpointToResume);\n```\n\n---\n\n## 检查点管理器实现\n\n### CheckpointManagerImpl\n\n资料来源：[dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs:1-100]()\n\n```csharp\ninternal sealed class CheckpointManagerImpl : ICheckpointManager\n{\n private readonly IWorkflowStorage _storage;\n private readonly IWorkflowStateSerializer _serializer;\n\n public async ValueTask CommitCheckpointAsync(\n string sessionId, \n Checkpoint checkpoint)\n {\n // 生成新的检查点ID\n var checkpointInfo = new CheckpointInfo(sessionId);\n \n // 序列化检查点数据\n var serialized = _serializer.Serialize(checkpoint);\n \n // 存储到持久化层\n await _storage.StoreAsync(\n key: GetStorageKey(sessionId, checkpointInfo.CheckpointId),\n data: serialized);\n \n // 更新会话索引\n await UpdateSessionIndexAsync(sessionId, checkpointInfo);\n \n return checkpointInfo;\n }\n\n public async ValueTask LookupCheckpointAsync(\n string sessionId, \n CheckpointInfo checkpointInfo)\n {\n var key = GetStorageKey(sessionId, checkpointInfo.CheckpointId);\n var data = await _storage.RetrieveAsync(key);\n \n if (data == null)\n {\n throw new KeyNotFoundException(\n $\"Checkpoint not found: {checkpointInfo.CheckpointId}\");\n }\n \n return _serializer.Deserialize(data);\n }\n}\n```\n\n---\n\n## DevUI 集成\n\n### 检查点信息模态框\n\nAgent Framework 的 DevUI 组件提供了检查点可视化功能。\n\n资料来源：[python/packages/devui/frontend/src/components/features/workflow/checkpoint-info-modal.tsx:1-80]()\n\n```tsx\ninterface CheckpointInfoModalProps {\n session: WorkflowSession | null;\n checkpoints: CheckpointInfo[];\n open: boolean;\n onOpenChange: (open: boolean) => void;\n}\n```\n\n### 检查点列表展示\n\nDevUI 中的检查点信息模态框包含以下功能：\n\n| 功能 | 说明 |\n|------|------|\n| 时间线视图 | 按创建顺序展示所有检查点 |\n| 状态预览 | 显示每个检查点的工作流状态摘要 |\n| HIL 标识 | 高亮显示待处理 HIL 请求的检查点 |\n| 原始 JSON | 可展开的检查点完整数据视图 |\n\n```tsx\n// 检查点渲染逻辑\ncheckpoints.map((checkpoint, index) => {\n const isSelected = checkpoint.checkpoint_id === selectedCheckpointId;\n const hasHil = checkpoint.metadata?.has_pending_hil;\n\n return (\n
\n setSelectedCheckpointId(checkpoint.checkpoint_id)}\n className={cn(\n \"w-full text-left p-3 rounded-lg border\",\n isSelected ? \"bg-primary/10 border-primary\" : \"hover:bg-muted/50\"\n )}\n >\n {hasHil && ⚠️ HIL Pending}\n \n
\n );\n})\n```\n\n### 工作流视图中的检查点集成\n\n资料来源：[python/packages/devui/frontend/src/components/features/workflow/workflow-view.tsx:1-100]()\n\n```tsx\ninterface WorkflowViewProps {\n // ... 其他属性\n checkpoints: CheckpointInfo[];\n showCheckpoints?: boolean;\n}\n\n// 检查点状态显示\n 0 \n ? \"completed\" \n : \"ready\"\n }\n checkpoints={sessionCheckpoints}\n showCheckpoints={true}\n/>\n```\n\n---\n\n## 配置选项\n\n### 检查点存储配置\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `storage_type` | `string` | `memory` | 存储类型：memory、file、database |\n| `storage_path` | `string` | `./checkpoints` | 文件系统存储路径 |\n| `max_checkpoints` | `int` | `100` | 单个会话最大检查点数量 |\n| `checkpoint_interval` | `int` | `60` | 自动检查点保存间隔（秒） |\n\n### 序列化配置\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `serializer` | `ISerializer` | 检查点序列化器实现 |\n| `compression` | `bool` | 是否启用压缩 |\n| `encryption` | `bool` | 是否启用加密 |\n\n---\n\n## 最佳实践\n\n### 1. 合理设置检查点频率\n\n```mermaid\ngraph LR\n A[工作流执行] --> B{检查点频率}\n B -->|过密| C[存储开销增加]\n B -->|过疏| D[恢复时数据丢失风险]\n C --> E[建议：HIL 点 + 关键步骤]\n D --> E\n```\n\n### 2. HIL 场景下的检查点\n\n```python\nasync def workflow_with_hil():\n workflow = WorkflowBuilder(start_executor=process_executor)\n \n # 在 HIL 点自动保存检查点\n workflow.on_hil_request(lambda ctx: ctx.save_checkpoint())\n \n run = await workflow.run(user_input)\n \n # 等待人类输入\n user_response = await wait_for_user_input()\n \n # 恢复执行\n resumed = await run.resume(user_response)\n```\n\n### 3. 错误恢复策略\n\n```csharp\ntry\n{\n var resumedRun = await workflow.ResumeAsync(checkpointInfo);\n}\ncatch (KeyNotFoundException)\n{\n // 检查点不存在，尝试从头开始\n var freshRun = await workflow.RunAsync(inputData);\n}\ncatch (CorruptedDataException)\n{\n // 检查点数据损坏，尝试上一个有效检查点\n var previousCheckpoint = await FindValidCheckpoint(sessionId);\n var recoveredRun = await workflow.ResumeAsync(previousCheckpoint);\n}\n```\n\n---\n\n## 相关文件索引\n\n| 类别 | 文件路径 |\n|------|----------|\n| Python 核心 | `python/packages/core/agent_framework/_workflows/_checkpoint.py` |\n| Python 示例 | `python/samples/03-workflows/checkpoint/checkpoint_with_resume.py` |\n| .NET 接口 | `dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/ICheckpointManager.cs` |\n| .NET 实现 | `dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs` |\n| .NET 数据模型 | `dotnet/src/Microsoft.Agents.AI.Workflows/CheckpointInfo.cs` |\n| .NET 执行环境 | `dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowExecutionEnvironment.cs` |\n| .NET 示例 | `dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs` |\n| DevUI 组件 | `python/packages/devui/frontend/src/components/features/workflow/checkpoint-info-modal.tsx` |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：microsoft/agent-framework\n\n摘要：发现 23 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CON…。\n\n## 1. 安装坑 · 来源证据：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CON…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CONTENT events\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d329260309954749a2b3b2a9e7135d56 | https://github.com/microsoft/agent-framework/issues/4923 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8f9f05dcb7564f34bdd5902dcea6be27 | https://github.com/microsoft/agent-framework/issues/5785 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49875a7dd60f480a99718cfa30b12723 | https://github.com/microsoft/agent-framework/issues/5708 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression]\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression]\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_58594f7966b84d81924da21ad789effd | https://github.com/microsoft/agent-framework/issues/5707 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安全/权限坑 · 来源证据：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_644a3ed07d2d4bfd8188392b4af687c2 | https://github.com/microsoft/agent-framework/issues/5794 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安全/权限坑 · 来源证据：Anthropic function limit fallback can return empty final response\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Anthropic function limit fallback can return empty final response\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b61b91ca16094a448f8c0eab5e2daaa1 | https://github.com/microsoft/agent-framework/issues/5769 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安全/权限坑 · 来源证据：Python: Add tutorial for building a custom chat client / LLM provider\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Python: Add tutorial for building a custom chat client / LLM provider\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_959e1eeb912a469c89f68f7f12275690 | https://github.com/microsoft/agent-framework/issues/5505 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：python-1.2.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：python-1.2.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f22ed66ae1f44b28b893aa5cbe439c92 | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 来源证据：.NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows CustomStatus 16 KB cap on multi-executor workflows…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：.NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows CustomStatus 16 KB cap on multi-executor workflows with typed outputs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_52da26ae3ace4acb9913ac780bfb6cd0 | https://github.com/microsoft/agent-framework/issues/5745 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：Python: CosmosHistoryProvider Code interpreter tool calls are saved chunk by chunk\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Python: CosmosHistoryProvider Code interpreter tool calls are saved chunk by chunk\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_48aaa2f1026c4afd9e1a1da3a1a862a6 | https://github.com/microsoft/agent-framework/issues/5793 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 来源证据：dotnet-1.5.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：dotnet-1.5.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2b3d3127c36f41798428b164b5444cbb | https://github.com/microsoft/agent-framework/releases/tag/dotnet-1.5.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 配置坑 · 来源证据：python-1.2.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：python-1.2.2\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb88b6cd86e04e199a03cfcf8a97dde6 | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:974445592 | https://github.com/microsoft/agent-framework | README/documentation is current enough for a first validation pass.\n\n## 14. 维护坑 · 来源证据：dotnet-1.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：dotnet-1.4.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e25f39a7081848689e086b1f98f92675 | https://github.com/microsoft/agent-framework/releases/tag/dotnet-1.4.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:974445592 | https://github.com/microsoft/agent-framework | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:974445592 | https://github.com/microsoft/agent-framework | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 18. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:974445592 | https://github.com/microsoft/agent-framework | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 来源证据：Python: OpenAI store=True can silently bypass external HistoryProvider persistence\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Python: OpenAI store=True can silently bypass external HistoryProvider persistence\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36cbde33c0a64127b95d953c65d49c54 | https://github.com/microsoft/agent-framework/issues/5798 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：python-1.2.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：python-1.2.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_aa3fc8cfbbad40f98ea1da9e68eeaa3f | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：python-1.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：python-1.3.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6df4ed99139d4fb0bc182d80b34e9d45 | https://github.com/microsoft/agent-framework/releases/tag/python-1.3.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：microsoft/agent-framework\n\n摘要：发现 23 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CON…。\n\n## 1. 安装坑 · 来源证据：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CON…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：.NET: [Bug]: TextContent.AdditionalProperties dropped by AsAGUIEventStreamAsync for TEXT_MESSAGE_START/TEXT_MESSAGE_CONTENT events\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d329260309954749a2b3b2a9e7135d56 | https://github.com/microsoft/agent-framework/issues/4923 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: Agent responses lose structured JSON metadata in multi-agent orchestration (MAF 1.x.x)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8f9f05dcb7564f34bdd5902dcea6be27 | https://github.com/microsoft/agent-framework/issues/5785 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: OpenAI-compatible extra body field thinking is not forwarded when using Microsoft.Agents.AI.OpenAI\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49875a7dd60f480a99718cfa30b12723 | https://github.com/microsoft/agent-framework/issues/5708 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression]\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: [Bug]: In v. 1.5.0 Microsoft.Agents.AI.Anthropic (and Google.GenAI) do not work [Regression]\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_58594f7966b84d81924da21ad789effd | https://github.com/microsoft/agent-framework/issues/5707 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安全/权限坑 · 来源证据：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：.NET: [Bug]: Regression - Tool Events not being emitted correctly to the front end\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_644a3ed07d2d4bfd8188392b4af687c2 | https://github.com/microsoft/agent-framework/issues/5794 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安全/权限坑 · 来源证据：Anthropic function limit fallback can return empty final response\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Anthropic function limit fallback can return empty final response\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b61b91ca16094a448f8c0eab5e2daaa1 | https://github.com/microsoft/agent-framework/issues/5769 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安全/权限坑 · 来源证据：Python: Add tutorial for building a custom chat client / LLM provider\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Python: Add tutorial for building a custom chat client / LLM provider\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_959e1eeb912a469c89f68f7f12275690 | https://github.com/microsoft/agent-framework/issues/5505 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：python-1.2.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：python-1.2.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f22ed66ae1f44b28b893aa5cbe439c92 | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 来源证据：.NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows CustomStatus 16 KB cap on multi-executor workflows…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：.NET: [Bug]: DurableTask: SuperstepState.AccumulatedEvents overflows CustomStatus 16 KB cap on multi-executor workflows with typed outputs\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_52da26ae3ace4acb9913ac780bfb6cd0 | https://github.com/microsoft/agent-framework/issues/5745 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：Python: CosmosHistoryProvider Code interpreter tool calls are saved chunk by chunk\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Python: CosmosHistoryProvider Code interpreter tool calls are saved chunk by chunk\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_48aaa2f1026c4afd9e1a1da3a1a862a6 | https://github.com/microsoft/agent-framework/issues/5793 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 配置坑 · 来源证据：dotnet-1.5.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：dotnet-1.5.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2b3d3127c36f41798428b164b5444cbb | https://github.com/microsoft/agent-framework/releases/tag/dotnet-1.5.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 配置坑 · 来源证据：python-1.2.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：python-1.2.2\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb88b6cd86e04e199a03cfcf8a97dde6 | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:974445592 | https://github.com/microsoft/agent-framework | README/documentation is current enough for a first validation pass.\n\n## 14. 维护坑 · 来源证据：dotnet-1.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：dotnet-1.4.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e25f39a7081848689e086b1f98f92675 | https://github.com/microsoft/agent-framework/releases/tag/dotnet-1.4.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:974445592 | https://github.com/microsoft/agent-framework | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:974445592 | https://github.com/microsoft/agent-framework | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 18. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:974445592 | https://github.com/microsoft/agent-framework | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 来源证据：Python: OpenAI store=True can silently bypass external HistoryProvider persistence\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Python: OpenAI store=True can silently bypass external HistoryProvider persistence\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36cbde33c0a64127b95d953c65d49c54 | https://github.com/microsoft/agent-framework/issues/5798 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：python-1.2.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：python-1.2.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_aa3fc8cfbbad40f98ea1da9e68eeaa3f | https://github.com/microsoft/agent-framework/releases/tag/python-1.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：python-1.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：python-1.3.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6df4ed99139d4fb0bc182d80b34e9d45 | https://github.com/microsoft/agent-framework/releases/tag/python-1.3.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:974445592 | https://github.com/microsoft/agent-framework | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# agent-framework - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agent-framework 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：框架介绍。围绕“框架介绍”模拟一次用户任务，不展示安装或运行结果。\n2. architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. core-concepts：核心概念。围绕“核心概念”模拟一次用户任务，不展示安装或运行结果。\n4. agent-basics：Agent 基础。围绕“Agent 基础”模拟一次用户任务，不展示安装或运行结果。\n5. agent-providers：模型提供商集成。围绕“模型提供商集成”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“框架介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. core-concepts\n输入：用户提供的“核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. agent-basics\n输入：用户提供的“Agent 基础”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. agent-providers\n输入：用户提供的“模型提供商集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“框架介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / core-concepts：Step 3 必须围绕“核心概念”形成一个小中间产物，并等待用户确认。\n- Step 4 / agent-basics：Step 4 必须围绕“Agent 基础”形成一个小中间产物，并等待用户确认。\n- Step 5 / agent-providers：Step 5 必须围绕“模型提供商集成”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/microsoft/agent-framework\n- https://github.com/microsoft/agent-framework#readme\n- dotnet/.github/skills/build-and-test/SKILL.md\n- dotnet/.github/skills/project-structure/SKILL.md\n- dotnet/.github/skills/verify-dotnet-samples/SKILL.md\n- dotnet/.github/skills/verify-samples-tool/SKILL.md\n- dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/skills/unit-converter/SKILL.md\n- dotnet/samples/02-agents/AgentSkills/Agent_Step04_MixedSkills/skills/unit-converter/SKILL.md\n- python/.github/skills/python-code-quality/SKILL.md\n- python/.github/skills/python-development/SKILL.md\n- python/.github/skills/python-feature-lifecycle/SKILL.md\n- python/.github/skills/python-package-management/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agent-framework 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：microsoft/agent-framework\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install agent-framework\n```\n\n来源：https://github.com/microsoft/agent-framework#readme\n\n## 来源\n\n- repo: https://github.com/microsoft/agent-framework\n- docs: https://github.com/microsoft/agent-framework#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_899444b38f6f433c876c520e7bed344e" }