{
"canonical_name": "VRSEN/agency-swarm",
"compilation_id": "pack_237b4b976b674c0d88bf992a12efad6e",
"created_at": "2026-05-14T00:43:32.083439+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 -U agency-swarm` 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 -U agency-swarm",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_f472a806e44d4a9ca3d7daccc966ad6f"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_6909dd9cd59892dfe53e8d09534014e3",
"canonical_name": "VRSEN/agency-swarm",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/VRSEN/agency-swarm",
"slug": "agency-swarm",
"source_packet_id": "phit_e33ac4bb7cd849bca81ae54a7a69e97b",
"source_validation_id": "dval_ecac37eea46647769698f762ddca2053"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 1045,
"github_stars": 4366,
"one_liner_en": "Reliable Multi-Agent Orchestration Framework",
"one_liner_zh": "Reliable Multi-Agent Orchestration Framework",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "agency-swarm",
"title_zh": "agency-swarm 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"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": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_e33ac4bb7cd849bca81ae54a7a69e97b",
"page_model": {
"artifacts": {
"artifact_slug": "agency-swarm",
"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 -U agency-swarm",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/VRSEN/agency-swarm#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"断点恢复流程",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Reliable Multi-Agent Orchestration Framework"
},
{
"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 社区证据显示该项目存在一个安装相关的待验证问题：Chart Library tool for financial pattern analysis in agent swarms",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_736c9d770ee34419ad2476f2a973e433 | https://github.com/VRSEN/agency-swarm/issues/596 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Chart Library tool for financial pattern analysis in agent swarms",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: native advisor/executor consult flow for stronger-model escalation",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_1b01977e66ac46caa8a8b860da5bdafe | https://github.com/VRSEN/agency-swarm/issues/598 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Feature request: native advisor/executor consult flow for stronger-model escalation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: ClawMem adapter for thread persistence across sessions",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_3bb24559ba48467ab0c8d43d3069d7f1 | https://github.com/VRSEN/agency-swarm/issues/594 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Proposal: ClawMem adapter for thread persistence across sessions",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：CI-level governance checks for swarm agent code",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_b995c0dfb8a5460caa7cfde16ac1c7a4 | https://github.com/VRSEN/agency-swarm/issues/593 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：CI-level governance checks for swarm agent code",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature: Runtime governance and compliance audit trails",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_4bd751455da0479bb37a014ef50934dd | https://github.com/VRSEN/agency-swarm/issues/592 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Feature: Runtime governance and compliance audit trails",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.9.0 - Agent Swarm TUI and OpenClaw",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_445071ada1ba4d558d4ebea6ec395364 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.9.0 - Agent Swarm TUI and OpenClaw",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.0 — Present and Accounted For",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_d270ab8e87c945878e308b78a2c8e7e6 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.8.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.8.0 — Present and Accounted For",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.9.2",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_2e69c962dcc44fd5a160047df0f18192 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.9.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.9.5",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_ec6832c5bd7b4083b4dd1a68c50f666f | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.5 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.9.5",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Research finding: Error detection failure rate in multi-agent chains — empirical data",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_8ef6210eff50485ba327057aa93e59d8 | https://github.com/VRSEN/agency-swarm/issues/609 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Research finding: Error detection failure rate in multi-agent chains — empirical data",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.9.4",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_333f10fed5354907b99a35bb5cba22a4 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.4 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.9.4",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | 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:719367294 | https://github.com/VRSEN/agency-swarm | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 23 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Chart Library tool for financial pattern analysis in agent swarms。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 24,
"forks": 1045,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 4366
},
"source_url": "https://github.com/VRSEN/agency-swarm",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Reliable Multi-Agent Orchestration Framework",
"title": "agency-swarm 能力包",
"trial_prompt": "# agency-swarm - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agency-swarm 的“安装前体验版”。\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. p-intro：Agency Swarm 简介。围绕“Agency Swarm 简介”模拟一次用户任务，不展示安装或运行结果。\n2. p-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. p-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. p-agents：智能体 (Agent)。围绕“智能体 (Agent)”模拟一次用户任务，不展示安装或运行结果。\n5. p-agencies：代理组织 (Agency)。围绕“代理组织 (Agency)”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. p-intro\n输入：用户提供的“Agency Swarm 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. p-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. p-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. p-agents\n输入：用户提供的“智能体 (Agent)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. p-agencies\n输入：用户提供的“代理组织 (Agency)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / p-intro：Step 1 必须围绕“Agency Swarm 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / p-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / p-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / p-agents：Step 4 必须围绕“智能体 (Agent)”形成一个小中间产物，并等待用户确认。\n- Step 5 / p-agencies：Step 5 必须围绕“代理组织 (Agency)”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/VRSEN/agency-swarm\n- https://github.com/VRSEN/agency-swarm#readme\n- .codex/skills/claude-cli-review/SKILL.md\n- .codex/skills/codex-cli-review/SKILL.md\n- .codex/skills/delegation-management/SKILL.md\n- .codex/skills/policy-maintenance/SKILL.md\n- .codex/skills/requirement-ledger/SKILL.md\n- README.md\n- src/agency_swarm/__init__.py\n- pyproject.toml\n- Makefile\n- CONTRIBUTING.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agency-swarm 的核心服务。\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: Feature request: native advisor/executor consult flow for stronger-model（https://github.com/VRSEN/agency-swarm/issues/598）；github/github_issue: Chart Library tool for financial pattern analysis in agent swarms（https://github.com/VRSEN/agency-swarm/issues/596）；github/github_issue: CI-level governance checks for swarm agent code（https://github.com/VRSEN/agency-swarm/issues/593）；github/github_issue: Feature: Runtime governance and compliance audit trails（https://github.com/VRSEN/agency-swarm/issues/592）；github/github_issue: Enforceable agency chart — cryptographic delegation per agent role in th（https://github.com/VRSEN/agency-swarm/issues/595）；github/github_issue: Feature: Agent trust and discovery via MoltBridge integration（https://github.com/VRSEN/agency-swarm/issues/528）；github/github_issue: Proposal: ClawMem adapter for thread persistence across sessions（https://github.com/VRSEN/agency-swarm/issues/594）；github/github_issue: Research finding: Error detection failure rate in multi-agent chains — e（https://github.com/VRSEN/agency-swarm/issues/609）；github/github_release: v1.9.8（https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.8）；github/github_release: v1.9.7（https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.7）；github/github_release: v1.9.6（https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.6）；github/github_release: v1.9.5（https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.5）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Feature request: native advisor/executor consult flow for stronger-model",
"url": "https://github.com/VRSEN/agency-swarm/issues/598"
},
{
"kind": "github_issue",
"source": "github",
"title": "Chart Library tool for financial pattern analysis in agent swarms",
"url": "https://github.com/VRSEN/agency-swarm/issues/596"
},
{
"kind": "github_issue",
"source": "github",
"title": "CI-level governance checks for swarm agent code",
"url": "https://github.com/VRSEN/agency-swarm/issues/593"
},
{
"kind": "github_issue",
"source": "github",
"title": "Feature: Runtime governance and compliance audit trails",
"url": "https://github.com/VRSEN/agency-swarm/issues/592"
},
{
"kind": "github_issue",
"source": "github",
"title": "Enforceable agency chart — cryptographic delegation per agent role in th",
"url": "https://github.com/VRSEN/agency-swarm/issues/595"
},
{
"kind": "github_issue",
"source": "github",
"title": "Feature: Agent trust and discovery via MoltBridge integration",
"url": "https://github.com/VRSEN/agency-swarm/issues/528"
},
{
"kind": "github_issue",
"source": "github",
"title": "Proposal: ClawMem adapter for thread persistence across sessions",
"url": "https://github.com/VRSEN/agency-swarm/issues/594"
},
{
"kind": "github_issue",
"source": "github",
"title": "Research finding: Error detection failure rate in multi-agent chains — e",
"url": "https://github.com/VRSEN/agency-swarm/issues/609"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.9.8",
"url": "https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.8"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.9.7",
"url": "https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.7"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.9.6",
"url": "https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.6"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.9.5",
"url": "https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.5"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Reliable Multi-Agent Orchestration Framework",
"effort": "安装已验证",
"forks": 1045,
"icon": "code",
"name": "agency-swarm 能力包",
"risk": "可发布",
"slug": "agency-swarm",
"stars": 4366,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"断点恢复流程",
"本地优先"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/VRSEN/agency-swarm 项目说明书\n\n生成时间：2026-05-14 00:40:55 UTC\n\n## 目录\n\n- [Agency Swarm 简介](#p-intro)\n- [安装与配置](#p-installation)\n- [系统架构](#p-architecture)\n- [项目目录结构](#p-folder-structure)\n- [智能体 (Agent)](#p-agents)\n- [代理组织 (Agency)](#p-agencies)\n- [通信流程](#p-communication-flows)\n- [自定义工具开发](#p-tools)\n- [内置工具](#p-builtin-tools)\n- [OpenAPI 工具集成](#p-openapi)\n\n\n\n## Agency Swarm 简介\n\n### 相关页面\n\n相关主题：[安装与配置](#p-installation), [系统架构](#p-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n- [examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n- [src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n- [src/agency_swarm/ui/templates/html/visualization.html](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/ui/templates/html/visualization.html)\n- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n- [examples/multimodal_outputs.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/multimodal_outputs.py)\n- [src/agency_swarm/utils/create_agent_template.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)\n- [examples/fastapi_integration/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/fastapi_integration/README.md)\n- [src/agency_swarm/integrations/fastapi_utils/endpoint_handlers.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/integrations/fastapi_utils/endpoint_handlers.py)\n \n\n# Agency Swarm 简介\n\nAgency Swarm 是一个开源的多智能体协作框架，基于 OpenAI 的 Responses API 构建。它旨在帮助开发者创建由多个 AI Agent 组成的自动化工作流，实现复杂的任务处理与协作。\n\n## 核心概念\n\n### Agent（智能体）\n\nAgent 是 Agency Swarm 的基本构建单元。每个 Agent 具有以下属性：\n\n| 属性 | 说明 |\n|------|------|\n| `name` | Agent 的唯一标识名称 |\n| `description` | Agent 的功能描述，供其他 Agent 或 LLM 理解其职责 |\n| `instructions` | Agent 的行为指令文档（支持 Markdown 文件） |\n| `tools` | Agent 可使用的工具列表 |\n| `model` | 底层使用的语言模型（默认为 `gpt-5.4`） |\n| `model_settings` | 模型参数配置（temperature、top_p、reasoning 等） |\n\nAgent 支持的功能包括：\n\n- **文件管理**：通过 `file_manager` 上传和管理文件\n- **向量存储**：支持 `FileSearch` 工具进行文件搜索\n- **工具加载**：支持从 `tools_folder` 动态加载工具\n- **OpenAPI Schema**：可从 `schemas` 文件夹解析 OpenAPI Schema 并生成工具\n- **Web 搜索**：集成 Web 搜索功能并可自定义来源过滤\n\n资料来源：[src/agency_swarm/agent/core.py:1-50]()\n\n### Agency（机构/多智能体系统）\n\nAgency 是多个 Agent 的集合体，负责管理 Agent 之间的通信与协作。Agent 之间可以通过以下方式进行通信：\n\n- **SendMessage**：直接消息传递\n- **Handoff**：任务交接（一个 Agent 将控制权转交给另一个 Agent）\n\n```python\nfrom agency_swarm import Agency, Agent, Handoff\n\nsupport = Agent(...)\nmath = Agent(...)\n\nagency = Agency(\n support,\n math,\n communication_flows=[(support, math, Handoff)],\n shared_instructions=\"共享的系统指令\"\n)\n```\n\n资料来源：[examples/interactive/tui.py:30-50]()\n\n## 工具系统\n\nAgency Swarm 提供三种工具定义方式：\n\n### 1. @function_tool 装饰器\n\n使用 Python 函数快速定义工具：\n\n```python\nfrom agency_swarm import function_tool\n\n@function_tool\ndef calculate(a: int, b: int) -> str:\n \"\"\"执行数学计算\"\"\"\n return str(a + b)\n```\n\n### 2. BaseTool 基类\n\n继承 `BaseTool` 使用 Pydantic 模型定义复杂工具：\n\n```python\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\n\nclass MyCustomTool(BaseTool):\n example_field: str = Field(\n ..., description=\"字段用途说明\"\n )\n\n def run(self):\n return f\"Result: {self.example_field}\"\n```\n\n资料来源：[README.md:50-80]()\n\n### 3. ToolFactory（OpenAPI Schema 转换）\n\n从 OpenAPI Schema 自动生成工具：\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\nwith open(\"schemas/your_schema.json\") as f:\n tools = ToolFactory.from_openapi_schema(f.read())\n```\n\n### 多模态工具输出\n\nAgency Swarm 支持工具返回多种格式的内容，包括图片和文件：\n\n```python\nfrom agency_swarm.tools.utils import tool_output_image_from_path, tool_output_file_from_url\nfrom agency_swarm import ToolOutputImage, ToolOutputFileContent\n\nclass LoadShowcaseImage(BaseTool):\n path: Path\n detail: str = \"auto\"\n\n def run(self) -> ToolOutputImage:\n return tool_output_image_from_path(self.path, detail=self.detail)\n```\n\n资料来源：[examples/multimodal_outputs.py:1-60]()\n\n## 通信与交互\n\n### 交互模式\n\n```mermaid\ngraph TD\n A[用户] -->|消息| B[Agency]\n B --> C[入口 Agent]\n C -->|SendMessage| D[目标 Agent]\n C -->|Handoff| E[交接 Agent]\n D -->|响应| C\n E -->|接管| F[新任务流程]\n F -->|结果| C\n```\n\n### 通信配置\n\n| 配置项 | 说明 |\n|--------|------|\n| `communication_flows` | 定义 Agent 之间的通信路径 |\n| `shared_instructions` | 所有 Agent 共享的指令 |\n| `name` | Agency 的显示名称 |\n\n资料来源：[examples/README.md:1-30]()\n\n## 用户界面\n\nAgency Swarm 提供多种用户界面选项：\n\n### 可视化界面\n\n提供交互式 HTML 可视化，展示 Agent 通信流程和工具关系：\n\n- **节点显示**：Agent（紫色渐变）、工具（橙色渐变）、入口点（绿色渐变）\n- **边连接**：带箭头指示通信方向\n- **缩放控制**：支持放大、缩小、适应视图\n- **统计信息**：实时显示 Agent 数量、工具数量、通信流程数\n\n```python\nagency.visualize() # 在浏览器中打开可视化界面\n```\n\n资料来源：[src/agency_swarm/ui/templates/html/visualization.html:1-80]()\n\n### 终端界面（TUI）\n\n基于 Rich 库的终端用户界面：\n\n```python\nagency.tui(show_reasoning=True) # 显示推理过程\n```\n\n特点：\n\n- 实时流式响应\n- 推理过程可视化\n- 终端内交互\n\n资料来源：[examples/interactive/tui.py:50-60]()\n\n### Copilot 界面\n\n基于 Next.js 和 CopilotKit 的 Web 界面：\n\n- 实时主题切换\n- 动态内容渲染\n- 可扩展的组件系统\n\n## 模型配置\n\n### ModelSettings 参数\n\n| 参数 | 说明 | 适用模型 |\n|------|------|----------|\n| `temperature` | 采样温度（0-2） | 非推理模型 |\n| `top_p` | Top-p 采样 | 非推理模型 |\n| `reasoning` | 推理努力级别 | 推理模型 |\n| `response_include` | 响应包含内容 | 所有模型 |\n\n### 推理模型配置\n\n```python\nfrom agency_swarm import ModelSettings, Reasoning\n\nmodel_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n)\n```\n\n注意：推理模型（如 o3、o4-mini）不支持 `temperature` 参数；非推理模型不支持 `reasoning` 参数。\n\n资料来源：[src/agency_swarm/utils/create_agent_template.py:1-50]()\n\n## FastAPI 集成\n\nAgency Swarm 提供 FastAPI 集成支持，可将 Agency 部署为 REST API 服务：\n\n### 核心端点\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/my-agency/get_response` | POST | 同步响应 |\n| `/my-agency/get_response_stream` | POST | SSE 流式响应 |\n| `/my-agency/get_metadata` | GET | Agency 结构元数据 |\n| `/openapi.json` | GET | OpenAPI 3.1.0 Schema |\n| `/docs` | GET | Swagger UI 文档 |\n\n### 服务工具\n\n```python\nfrom agency_swarm.integrations.fastapi import run_fastapi\n\napp = run_fastapi(\n agencies={\"my-agency\": create_agency},\n app_token_env=\"APP_TOKEN\",\n return_app=True,\n)\n```\n\n工具端点自动暴露：\n\n- `POST /tool/` - 执行工具并验证\n- `GET /openapi.json` - 完整的 OpenAPI Schema\n\n资料来源：[examples/fastapi_integration/README.md:1-40]()\n\n### OpenClaw 集成\n\n支持作为 OpenClaw 工作器模式运行：\n\n```python\nfrom agency_swarm.integrations.openclaw import attach_openclaw_to_fastapi\n\nattach_openclaw_to_fastapi(app)\n```\n\n## 项目结构\n\n```\nagency_swarm/\n├── agents/ # Agent 定义目录\n│ └── AgentName/\n│ ├── AgentName.py # Agent 主类\n│ ├── instructions.md # 指令文档\n│ ├── tools/ # 专用工具\n│ └── schemas/ # OpenAPI Schema\n├── tools/ # 通用工具目录\n│ └── {category}/\n├── ui/ # 用户界面组件\n│ ├── templates/\n│ └── demos/\n├── integrations/ # 第三方集成\n│ ├── fastapi/\n│ └── openclaw/\n└── utils/ # 工具函数\n```\n\n资料来源：[CONTRIBUTING.md:1-50]()\n\n## 示例与演示\n\n### 核心功能示例\n\n| 示例文件 | 演示内容 |\n|----------|----------|\n| `multi_agent_workflow.py` | 多 Agent 协作与验证模式 |\n| `agency_context.py` | Agent 间数据共享 |\n| `streaming.py` | 实时流式响应 |\n| `guardrails.py` | 输入输出防护栏 |\n| `custom_persistence.py` | 聊天历史持久化 |\n| `tools.py` | 工具模式：BaseTool 和 @function_tool |\n\n### 文件处理示例\n\n| 示例文件 | 演示内容 |\n|----------|----------|\n| `agent_file_storage.py` | 向量存储与文件搜索 |\n| `message_attachments.py` | 文件处理与附件 |\n| `web_search.py` | 领域过滤的 Web 搜索 |\n\n### 集成示例\n\n| 路径 | 演示内容 |\n|------|----------|\n| `fastapi_integration/` | FastAPI 服务与客户端 |\n| `interactive/` | TUI 和 Copilot 界面 |\n\n## 快速开始\n\n```python\nfrom agency_swarm import Agency, Agent\n\n# 定义 Agent\nsupport = Agent(\n name=\"SupportAgent\",\n description=\"处理用户请求的入口 Agent\",\n instructions=\"instructions.md\",\n tools=[WebSearchTool()],\n model=\"gpt-5.4-mini\",\n)\n\n# 创建 Agency\nagency = Agency(\n support,\n shared_instructions=\"全局共享指令\"\n)\n\n# 运行\nif __name__ == \"__main__\":\n print(agency.get_response_sync(\"你好！\"))\n```\n\n## 总结\n\nAgency Swarm 是一个功能完整的 AI Agent 协作框架，其核心优势包括：\n\n1. **简洁的 API 设计**：基于 OpenAI Responses API，入门门槛低\n2. **灵活的工具系统**：支持多种工具定义方式和 OpenAPI Schema 转换\n3. **多层次的通信**：支持消息传递和任务交接两种模式\n4. **丰富的界面选项**：可视化、TUI、Web 界面全覆盖\n5. **完善的部署支持**：FastAPI 集成、OpenAPI Schema 生成\n\n该框架适用于构建复杂的多 Agent 工作流、智能客服系统、自动化代理等应用场景。\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[Agency Swarm 简介](#p-intro), [项目目录结构](#p-folder-structure)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/VRSEN/agency-swarm/blob/main/pyproject.toml)\n- [Makefile](https://github.com/VRSEN/agency-swarm/blob/main/Makefile)\n- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n- [src/agency_swarm/utils/create_agent_template.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)\n- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n \n\n# 安装与配置\n\n## 概述\n\n本页面详细说明 Agency Swarm 项目的安装流程、依赖管理、项目初始化以及 CLI 工具的配置方法。Agency Swarm 是一个多智能体协作框架，通过定义 Agent、Tool 和通信流来实现复杂的自动化工作流程。正确的安装与配置是确保框架正常运行的前提条件。\n\n---\n\n## 环境准备\n\n### 系统要求\n\n| 要求项 | 说明 |\n|--------|------|\n| Python 版本 | 3.10+ |\n| 包管理器 | pip 或 poetry |\n| 操作系统 | macOS、Linux、Windows |\n\n### 创建虚拟环境\n\n建议使用虚拟环境隔离项目依赖，避免与其他项目产生冲突：\n\n```bash\n# 使用 venv 创建虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Linux/macOS\nsource venv/bin/activate\n\n# Windows\nvenv\\Scripts\\activate\n```\n\n---\n\n## 安装方式\n\n### 方式一：从源码安装（开发模式）\n\n克隆仓库后，使用 Makefile 安装开发依赖：\n\n```bash\ngit clone https://github.com/VRSEN/agency-swarm.git\ncd agency-swarm\n\n# 安装所有依赖（包括开发依赖）\nmake sync\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 方式二：通过 pip 安装\n\n```bash\npip install agency-swarm\n```\n\n### 方式三：使用 poetry 安装\n\n```bash\npoetry install\npoetry install --with dev # 包含开发依赖\n```\n\n---\n\n## 项目结构\n\n### 核心目录结构\n\n```\nagency_swarm/\n├── agents/ # Agent 定义目录\n│ └── AgentName/\n│ ├── AgentName.py # Agent 主类文件\n│ ├── __init__.py # 包初始化文件\n│ ├── instructions.md # Agent 指令文档\n│ ├── files/ # 上传文件目录\n│ ├── tools/ # 工具目录\n│ └── schemas/ # OpenAPI schemas 目录\n├── tools/ # 工具目录\n│ └── {category}/\n│ └── YourNewTool.py\n└── ...\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### Agent 目录规范\n\n每个 Agent 必须放置在 `agency_swarm/agents/` 目录下，使用 **CamelCase** 命名规范：\n\n```\nagency_swarm/agents/AgentName/\n├── files/ # 上传到 OpenAI 的文件目录\n├── tools/ # Agent 使用的工具目录\n├── schemas/ # OpenAPI schemas 目录\n├── AgentName.py # Agent 主类文件\n├── __init__.py # 包初始化文件\n└── instructions.md # Agent 指令文档\n```\n\n---\n\n## Agent 创建与配置\n\n### 创建 Agent 类\n\n使用以下模板创建新的 Agent：\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools.example import ExampleTool\n\nclass AgentName(Agent):\n def __init__(self):\n super().__init__(\n name=\"AgentName\",\n description=\"Description of the agent\",\n instructions=\"instructions.md\",\n tools=[ExampleTool],\n )\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### CLI 工具创建 Agent\n\n通过命令行工具快速创建 Agent 模板，支持以下参数：\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--name` | str | Agent 名称 | 用户输入 |\n| `--description` | str | Agent 描述 | - |\n| `--model` | str | 模型名称 | `gpt-5.4` |\n| `--reasoning` | str | 推理强度 (`low`/`medium`/`high`) | - |\n| `--temperature` | float | 温度参数 | 0.3 |\n| `--path` | str | 输出路径 | `./` |\n| `--use-txt` | bool | 使用 .txt 格式指令文件 | False |\n\n资料来源：[src/agency_swarm/utils/create_agent_template.py:1]()\n\n### 模型配置\n\n#### 非推理模型配置\n\n```python\nfrom agency_swarm import Agent, ModelSettings\nfrom agency_swarm.util import Reasoning\n\nsupport = Agent(\n name=\"SupportAgent\",\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n temperature=0.3,\n reasoning=Reasoning(effort=\"low\", summary=\"auto\")\n ),\n)\n```\n\n#### 推理模型配置\n\n对于推理模型（如 o1 系列），不支持 `temperature` 参数：\n\n```python\n# 推理模型配置示例\nmodel_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n)\n```\n\n> ⚠️ 注意：推理模型不支持 `temperature` 参数，框架会自动忽略该参数。\n\n资料来源：[src/agency_swarm/utils/create_agent_template.py:1]()\n\n---\n\n## Agency 初始化配置\n\n### 基本初始化\n\n```python\nfrom agency_swarm import Agency, Agent\n\nceo = Agent(name=\"CEO\", ...)\ndeveloper = Agent(name=\"Developer\", ...)\n\nagency = Agency(ceo, developer)\n```\n\n### 带通信流的初始化\n\n```python\nfrom agency_swarm import Agency, Agent\nfrom agency_swarm.agents import Handoff\n\nceo = Agent(name=\"CEO\", ...)\ndeveloper = Agent(name=\"Developer\", ...)\n\nagency = Agency(\n ceo,\n developer,\n communication_flows=[(ceo, developer, Handoff)]\n)\n```\n\n### 完整配置示例\n\n```python\nfrom agency_swarm import Agency, Agent\nfrom agency_swarm.agents import Handoff\nfrom agency_swarm.util import ModelSettings, Reasoning\n\ndef create_demo_agency():\n support = Agent(\n name=\"Support\",\n description=\"Handles user support requests with web search capabilities\",\n instructions=\"You are a helpful support agent.\",\n include_search_results=True,\n tools=[WebSearchTool()],\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n reasoning=Reasoning(effort=\"low\", summary=\"auto\")\n ),\n )\n\n math = Agent(\n name=\"MathAgent\",\n description=\"Handles arithmetic and calculation-heavy requests\",\n instructions=\"You are MathAgent. Use the calculate tool for arithmetic questions.\",\n tools=[calculate],\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n ),\n )\n\n return Agency(\n support,\n math,\n communication_flows=[(support, math, Handoff)],\n shared_instructions=\"Demonstrate reasoning, web search, file search, and handoffs.\",\n )\n```\n\n资料来源：[examples/interactive/tui.py:1]()\n\n---\n\n## 测试与验证\n\n### 运行测试\n\n```bash\n# 运行测试并生成覆盖率报告\nmake coverage\n```\n\n### 检查覆盖率\n\n`make coverage` 命令会输出测试覆盖率信息，请审查以确保有足够的测试覆盖。\n\n资料来源：[CONTRIBUTING.md:1]()\n\n---\n\n## 工具创建与配置\n\n### 工具目录结构\n\n```\nagency_swarm/tools/{category}/\n├── YourNewTool.py # 工具主类文件\n└── __init__.py # 包初始化文件\n```\n\n工具应放置在特定类别目录下，如 `coding`、`browsing`、`investing` 等。\n\n### 工具测试\n\n在 `agency_swarm/tests/test_tools.py` 中添加测试用例：\n\n```python\ndef test_my_tool_example():\n tool = MyCustomTool(example_field=\"test value\")\n result = tool.run()\n assert \"expected output\" in result\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n---\n\n## 快速开始流程\n\n```mermaid\ngraph TD\n A[安装依赖
make sync] --> B[创建 Agent 类]\n B --> C[定义工具和指令]\n C --> D[初始化 Agency]\n D --> E[配置通信流]\n E --> F[运行测试
make coverage]\n F --> G[启动应用]\n```\n\n---\n\n## 常见配置问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 推理模型报错 | 确保不使用 `temperature` 参数 |\n| 工具加载失败 | 检查工具文件路径是否正确 |\n| 通信流不工作 | 确认 Agent 实例和 Handoff 配置正确 |\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[智能体 (Agent)](#p-agents), [代理组织 (Agency)](#p-agencies), [自定义工具开发](#p-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n- [src/agency_swarm/agency/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agency/core.py) （基于 README.md 和 examples 中的引用）\n- [src/agency_swarm/tools/base_tool.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/base_tool.py) （基于 examples 和 README.md 中的引用）\n- [src/agency_swarm/messages/message_formatter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/message_formatter.py) （基于 examples 中的引用）\n- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n- [examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n \n\n# 系统架构\n\n## 概述\n\nAgency Swarm 是一个多智能体（Multi-Agent）协作框架，旨在构建能够协同工作的智能体（Agent）系统。该框架的核心设计理念是通过定义清晰的智能体角色、通信流程和工具集，使多个 AI 智能体能够像真实团队一样协作完成任务。\n\n该系统采用分层架构，主要包含以下核心组件：Agent（智能体）、Agency（代理机构）、Tools（工具）、Messages（消息处理）以及各类通信机制。\n\n## 核心架构组件\n\n### 1. Agent（智能体）\n\nAgent 是框架的基本构建单元，每个 Agent 代表一个具有特定角色和职责的 AI 智能体。\n\n```mermaid\ngraph LR\n A[Agent] --> B[名称与描述]\n A --> C[指令集]\n A --> D[工具集]\n A --> E[模型配置]\n A --> F[文件管理]\n A --> G[通信能力]\n```\n\n#### Agent 核心属性\n\n| 属性 | 说明 | 必填 |\n|------|------|------|\n| `name` | 智能体名称，采用 CamelCase 格式 | 是 |\n| `description` | 智能体职责描述，供其他 Agent 理解其功能 | 是 |\n| `instructions` | 指令文档路径（.md 或 .txt）或直接传入字符串 | 是 |\n| `tools` | 智能体可使用的工具列表 | 否 |\n| `model` | 使用的模型标识符（如 \"gpt-5.4-mini\"） | 否 |\n| `model_settings` | 模型配置对象 | 否 |\n| `files_folder` | 上传至 OpenAI 的文件目录 | 否 |\n| `schemas_folder` | OpenAPI schemas 目录，用于自动生成工具 | 否 |\n\n#### Agent 核心方法\n\n```python\n# Agent 初始化示例 - 资料来源：examples/interactive/tui.py\nceo = Agent(\n name=\"CeoAssistant\",\n description=\"Main support agent that assists users\",\n instructions=\"You are CeoAssistant, a helpful AI assistant.\",\n files_folder=_files(),\n include_search_results=True,\n tools=[WebSearchTool()],\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(reasoning=Reasoning(effort=\"low\", summary=\"auto\")),\n)\n```\n\n`get_response()` 方法是 Agent 的核心执行入口，处理用户与 Agent 之间以及 Agent 相互之间的交互：\n\n```python\n# 资料来源：src/agency_swarm/agent/core.py\nasync def get_response(\n self,\n message: str | list[TResponseInputItem],\n sender_name: str | None = None,\n context_override: dict[str, Any] | None = None,\n hooks_override: RunHooks | None = None,\n run_config_override: RunConfig | None = None,\n file_ids: list[str] | None = None,\n additional_instructions: str | None = None,\n agency_context: AgencyContext | None = None,\n **kwargs: Any,\n) -> RunResult:\n```\n\n### 2. Agency（代理机构）\n\nAgency 是多智能体系统的容器，负责管理智能体之间的通信流程和协作关系。\n\n```mermaid\ngraph TD\n U[用户请求] --> A[Agency]\n A --> A1[Agent 1]\n A --> A2[Agent 2]\n A --> A3[Agent N]\n A1 <-->|通信流程| A2\n A2 <-->|通信流程| A3\n A1 <-->|通信流程| A3\n```\n\n#### Agency 创建模式\n\nAgency 支持两种创建模式：简洁模式（隐式入口点）和显式模式（指定通信流程）：\n\n```python\n# 简洁模式 - 资料来源：examples/agency_visualization.py\nagency = Agency(ceo) # ceo 作为入口点\n\n# 显式模式 - 资料来源：examples/custom_send_message.py\nagency = Agency(\n coordinator,\n specialist,\n communication_flows=[\n (coordinator > specialist, SendMessageWithContext),\n (specialist > coordinator, Handoff),\n ],\n shared_instructions=\"Use key decisions to guide analysis tool selection.\",\n)\n```\n\n#### 通信流程配置\n\n| 符号 | 含义 | 用法 |\n|------|------|------|\n| `>` | 单向通信 | `(A > B)` 表示 A 可以向 B 发送消息 |\n| `< >` | 双向通信 | `(A < > B)` 表示 A 和 B 可以相互通信 |\n| `, Handoff` | 交接工具 | 指定使用 Handoff 进行消息传递 |\n\n### 3. Tools（工具系统）\n\n工具系统允许 Agent 执行特定操作，是扩展 Agent 能力的关键机制。\n\n```mermaid\ngraph TB\n T[工具系统] --> T1[BaseTool]\n T --> T2[FunctionTool]\n T --> T3[ToolFactory]\n T1 --> S1[结构化工具类]\n T2 --> D1[@function_tool 装饰器]\n T3 --> O1[OpenAPI 转换]\n```\n\n#### 工具类型\n\n**使用 @function_tool 装饰器：**\n\n```python\n# 资料来源：examples/README.md\nfrom agency_swarm.tools import function_tool\n\n@function_tool\ndef calculate(query: str) -> str:\n \"\"\"A calculator tool for arithmetic questions.\"\"\"\n return f\"Result: {query}\"\n```\n\n**使用 BaseTool 基类：**\n\n```python\n# 资料来源：README.md\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\n\nclass MyCustomTool(BaseTool):\n \"\"\"自定义工具描述，用于帮助 Agent 理解何时使用此工具。\"\"\"\n \n example_field: str = Field(\n ..., description=\"字段描述，说明其用途\"\n )\n \n def run(self):\n return \"工具操作结果\"\n```\n\n**从 OpenAPI Schema 生成工具：**\n\n```python\n# 资料来源：README.md\nfrom agency_swarm.tools import ToolFactory\n\ntools = ToolFactory.from_openapi_schema(\n openapi_schema_dict\n)\n```\n\n#### 内置工具\n\n| 工具名称 | 功能 | 资料来源 |\n|----------|------|----------|\n| `WebSearchTool` | 网页搜索功能 | examples/interactive/tui.py |\n| `FileSearchTool` | 向量存储文件搜索 | examples/README.md |\n| `IPythonInterpreter` | 代码解释执行 | CLI import-tool 命令 |\n| `Handoff` | Agent 交接通信 | examples/custom_send_message.py |\n| `SendMessage` | 发送消息通信 | examples/custom_send_message.py |\n\n### 4. Messages（消息处理）\n\n消息系统处理 Agent 之间的通信格式化与传递。\n\n```mermaid\ngraph LR\n M1[输入消息] --> MF[MessageFormatter]\n MF --> F[格式化处理]\n F --> M2[结构化消息]\n M2 --> A1[Agent]\n M2 --> A2[Agent]\n```\n\nMessageFormatter 负责消息的解析、格式化和传递，确保不同 Agent 之间能够正确理解彼此的意图。\n\n### 5. ModelSettings（模型配置）\n\n模型配置提供了细粒度的模型控制能力：\n\n```python\n# 资料来源：examples/interactive/tui.py\nfrom agency_swarm import ModelSettings, Reasoning\n\nModelSettings(\n reasoning=Reasoning(effort=\"low\", summary=\"auto\"),\n temperature=0.3,\n max_tokens=25000,\n top_p=0.9,\n)\n```\n\n#### ModelSettings 参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `temperature` | 生成随机性控制 | 0.3（非推理模型） |\n| `max_tokens` | 最大输出 token 数 | 模型默认值 |\n| `top_p` | 核采样概率 | - |\n| `reasoning` | 推理配置 | - |\n\n## 目录结构\n\n```\nagency_swarm/\n├── agency/ # Agency 核心实现\n│ └── core.py\n├── agent/ # Agent 核心实现\n│ └── core.py\n├── tools/ # 工具系统\n│ ├── base_tool.py\n│ ├── function_tool.py\n│ └── ...\n├── messages/ # 消息处理\n│ └── message_formatter.py\n├── cli/ # 命令行工具\n│ └── main.py\n├── ui/ # 用户界面\n│ ├── templates/\n│ └── demos/\n└── integrations/ # 集成功能\n └── fastapi_utils/\n```\n\n### Agent 目录结构规范\n\n```bash\nAgentName/ # 目录名采用 CamelCase\n├── files/ # 上传至 OpenAI 的文件\n├── schemas/ # OpenAPI schemas（自动转工具）\n├── tools/ # Agent 专用工具\n├── AgentName.py # 主类文件\n├── __init__.py\n└── instructions.md # 指令文档\n```\n\n## 通信机制\n\n### Agent 间通信流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as Agency\n participant Ag1 as Agent 1\n participant Ag2 as Agent 2\n \n U->>A: 请求\n A->>Ag1: 路由到入口 Agent\n Ag1->>Ag1: 执行任务\n Ag1->>Ag2: 发送消息/交接\n Ag2->>Ag2: 执行任务\n Ag2-->>Ag1: 返回结果\n Ag1-->>A: 汇总结果\n A-->>U: 最终响应\n```\n\n### 通信工具类型\n\n| 通信工具 | 用途 | 特点 |\n|----------|------|------|\n| `Handoff` | Agent 交接 | 完整上下文传递 |\n| `SendMessage` | 发送消息 | 自定义消息格式 |\n| `SendMessageWithContext` | 带上下文消息 | 附加额外上下文信息 |\n\n## 执行模式\n\n### 异步执行（推荐）\n\n```python\n# 资料来源：README.md\nimport asyncio\n\nasync def main():\n resp = await agency.get_response(\"Create a project skeleton.\")\n print(resp.final_output)\n\nasyncio.run(main())\n```\n\n### 同步执行\n\n```python\n# 资料来源：examples/README.md\nresult = agency.get_response_sync(\"What's your name?\")\n```\n\n## 模型支持\n\n框架支持多种 OpenAI 模型：\n\n| 模型类型 | 示例 | 特性 |\n|----------|------|------|\n| 标准模型 | `gpt-5.4-mini` | 支持 temperature 参数 |\n| 推理模型 | `o3`, `o4` 系列 | 不支持 temperature，支持 reasoning 配置 |\n\n```python\n# 推理模型配置示例 - 资料来源：examples/interactive/tui.py\nmodel_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n)\n```\n\n## 扩展机制\n\n### 1. 自定义工具开发\n\n工具应放置在 `agency_swarm/tools/{category}/` 目录下：\n\n```bash\nagency_swarm/tools/your-tool-category/\n├── YourNewTool.py\n└── __init__.py\n```\n\n### 2. CLI 工具导入\n\n```bash\n# 导入内置工具到项目\nagency-swarm import-tool IPythonInterpreter --destination ./tools\n```\n\n### 3. 从 Assistants API 迁移\n\n```bash\n# 从 settings.json 生成 Agent\nagency-swarm migrate-agent path_to_settings.json --output-dir ./agents\n```\n\n## 可视化功能\n\nAgency 提供可视化功能用于展示智能体通信结构：\n\n```python\n# 资料来源：examples/agency_visualization.py\nhtml_file = agency.visualize(\n output_file=\"agency.html\",\n include_tools=True,\n open_browser=True,\n)\n```\n\n生成的 HTML 页面包含：\n- 智能体节点展示\n- 通信流程箭头\n- 工具关联显示\n- 交互式缩放和拖拽\n\n## 快速开始\n\n```python\n# 1. 定义工具\nfrom agency_swarm.tools import function_tool\n\n@function_tool\ndef calculate(query: str) -> str:\n return f\"Result: {query}\"\n\n# 2. 创建 Agent\nfrom agency_swarm import Agent\n\nsupport = Agent(\n name=\"Support\",\n description=\"帮助用户解决问题\",\n instructions=\"你是客服助手。\",\n tools=[calculate],\n)\n\n# 3. 创建 Agency\nfrom agency_swarm import Agency\n\nagency = Agency(support)\n\n# 4. 执行任务\nresult = agency.get_response_sync(\"计算 345 * 18\")\n```\n\n## 总结\n\nAgency Swarm 的系统架构围绕四个核心概念构建：**Agent**（执行单元）、**Agency**（协作容器）、**Tools**（能力扩展）和 **Messages**（通信机制）。这种设计使得开发者可以灵活地构建复杂的多智能体系统，通过配置通信流程实现不同角色之间的协作，同时保持代码结构的清晰和可维护性。\n\n---\n\n\n\n## 项目目录结构\n\n### 相关页面\n\n相关主题：[系统架构](#p-architecture), [安装与配置](#p-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm)\n- [examples](https://github.com/VRSEN/agency-swarm/blob/main/examples)\n- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n- [examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n \n\n# 项目目录结构\n\n## 概述\n\nAgency Swarm 是一个多代理协作框架，其项目目录结构经过精心设计，以支持模块化、可扩展的代理系统开发。框架采用清晰的职责分离，将核心功能、工具、代理、用户界面和集成模块分别放置在独立目录中，便于开发者理解和扩展。\n\n## 顶层目录结构\n\n```\nagency-swarm/\n├── src/agency_swarm/ # 核心源代码\n├── examples/ # 可运行示例\n├── docs/ # 文档\n├── Makefile # 构建和测试任务\n├── CONTRIBUTING.md # 贡献指南\n└── README.md # 项目说明\n```\n\n## 核心模块结构\n\n`src/agency_swarm/` 是框架的核心代码库，包含以下主要模块：\n\n```\nsrc/agency_swarm/\n├── agent/ # Agent 核心类\n├── tools/ # 内置工具集\n├── util/ # 工具函数\n├── cli/ # 命令行工具\n├── ui/ # 用户界面\n├── integrations/ # 第三方集成\n└── __init__.py # 包入口\n```\n\n### Agent 核心模块\n\n`agent/` 目录包含框架的核心代理实现：\n\n| 文件 | 用途 |\n|------|------|\n| `core.py` | Agent 基类实现，包含工具加载、模式解析、文件处理等核心方法 |\n\nAgent 类提供了 `get_response()` 异步方法用于处理对话循环，支持用户与代理之间的交互以及代理到代理的通信。资料来源：[core.py:30-50]()\n\n### 工具模块\n\n`tools/` 目录采用分类组织结构，每个工具类别放置在独立子目录中：\n\n```\nagency_swarm/tools/{category}/\n├── YourNewTool.py # 工具类文件\n└── __init__.py # 模块入口\n```\n\n可用的工具类别包括但不限于：`coding`、`browsing`、`investing` 等。开发者可通过继承 `BaseTool` 或使用 `@function_tool` 装饰器创建自定义工具。资料来源：[CONTRIBUTING.md]()\n\n### 用户界面模块\n\n`ui/` 目录包含交互式界面组件：\n\n```\nsrc/agency_swarm/ui/\n├── templates/ # HTML 模板\n│ └── html/\n│ └── visualization.html # 代理可视化模板\n└── demos/ # 演示应用\n └── copilot/ # Copilot UI 演示\n```\n\n可视化功能允许用户生成交互式 HTML 页面，展示代理之间的通信流程和工具关系图。资料来源：[visualization.html]()\n\n### 命令行工具\n\n`cli/` 目录包含 TypeScript 编写的 CLI 工具，用于从配置文件生成代理代码：\n\n```\nsrc/agency_swarm/cli/\n└── utils/\n └── generate-agent-from-settings.ts # 代理生成器\n```\n\n### 集成模块\n\n`integrations/` 目录提供与外部服务的集成能力：\n\n| 集成 | 说明 |\n|------|------|\n| FastAPI | 支持流式响应的 API 服务器和客户端示例 |\n| OpenClaw | 与 OpenClaw 系统的集成，支持工作区挂载和消息传递 |\n\n## 代理项目结构\n\n当开发者使用 Agency Swarm 创建实际项目时，推荐采用以下目录结构：\n\n```\n/your-specified-path/\n│\n├── agency_manifesto.md # 代理宣言（代理系统的指导原则）\n└── AgentName/ # 代理专属目录（驼峰命名）\n ├── files/ # 上传至 OpenAI 的文件\n ├── schemas/ # OpenAPI schemas（自动转换为工具）\n ├── tools/ # 代理使用的工具\n ├── AgentName.py # 主代理类文件\n ├── __init__.py # Python 包初始化\n ├── instructions.md # 代理指令文档\n └── tools.py # 自定义工具定义\n```\n\n资料来源：[README.md]()\n\n### AgentName.py 结构示例\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools.example import ExampleTool\n\nclass AgentName(Agent):\n def __init__(self):\n super().__init__(\n name=\"AgentName\",\n description=\"Description of the agent\",\n instructions=\"./instructions.md\",\n tools=[ExampleTool],\n )\n```\n\n### 文件夹职责说明\n\n| 文件夹/文件 | 用途 |\n|------------|------|\n| `files/` | 存放需要上传至 OpenAI 的文件，可用于向量存储和文件搜索工具 |\n| `schemas/` | 存放 OpenAPI 规范文件，框架自动将其转换为可调用工具 |\n| `tools/` | 存放代理专属工具定义 |\n| `instructions.md` | 定义代理的行为准则和任务说明 |\n| `agency_manifesto.md` | 定义整个代理系统的工作原则和价值观 |\n\n## 代理通信结构\n\n代理之间的通信通过 `communication_flows` 定义，支持多种通信模式：\n\n```python\nfrom agency_swarm import Agency, Agent, Handoff, SendMessage\n\nagency = Agency(\n ceo, # 入口点代理\n specialist,\n communication_flows=[\n (ceo > specialist), # CEO 向专家发送消息\n (specialist > ceo, Handoff), # 使用 Handoff 进行交接\n ],\n)\n```\n\n### 通信流程图\n\n```mermaid\ngraph TD\n A[用户] --> B[CEO Agent]\n B --> C{任务类型}\n C -->|需要专业知识| D[Specialist Agent]\n C -->|简单任务| E[直接响应]\n D -->|Handoff| B\n D -->|SendMessage| B\n B --> A\n```\n\n## 示例目录结构\n\n`examples/` 目录包含可运行的演示代码，展示框架的核心功能：\n\n| 示例文件 | 功能说明 |\n|---------|---------|\n| `multi_agent_workflow.py` | 多代理协作与验证模式 |\n| `agency_context.py` | 代理间数据共享 |\n| `streaming.py` | 实时流式响应 |\n| `guardrails.py` | 输入输出防护 |\n| `custom_persistence.py` | 聊天历史持久化 |\n| `tools.py` | BaseTool 和 @function_tool 使用 |\n| `agent_file_storage.py` | 向量存储和文件搜索 |\n| `message_attachments.py` | 文件处理和消息附件 |\n| `web_search.py` | WebSearchTool 使用 |\n| `custom_send_message.py` | SendMessage 配置 |\n| `agency_visualization.py` | 交互式可视化 |\n\n资料来源：[examples/README.md]()\n\n### 交互式示例\n\n```\nexamples/\n├── interactive/\n│ ├── tui.py # 终端 UI 界面\n│ ├── copilot_demo.py # Copilot UI 演示\n│ └── hybrid_communication_flows.py # 混合通信流程\n└── fastapi_integration/\n ├── server.py # FastAPI 服务器\n └── client.py # 客户端示例\n```\n\n## 开发环境配置\n\n### 虚拟环境创建\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate # Windows: venv\\Scripts\\activate\n```\n\n### 依赖安装\n\n```bash\nmake sync\n```\n\n### 测试运行\n\n```bash\nmake coverage\n```\n\n## 贡献者指南中的结构要求\n\n框架对贡献的代码有明确的目录结构要求：\n\n### 工具贡献结构\n\n```\nagency_swarm/tools/your-tool-category/\n├── YourNewTool.py # 主工具类\n└── __init__.py # 导入语句\n```\n\n### 代理贡献结构\n\n```\nagency_swarm/agents/AgentName/\n├── AgentName.py # 主代理类\n├── __init__.py # 初始化文件\n├── instructions.md # 指令文档\n├── files/ # 文件目录\n├── tools/ # 工具目录\n└── schemas/ # schemas 目录\n```\n\n## 架构概览图\n\n```mermaid\ngraph TB\n subgraph \"用户层\"\n U[用户]\n end\n \n subgraph \"API 层\"\n F[FastAPI 集成]\n CLI[CLI 工具]\n end\n \n subgraph \"核心框架\"\n A[Agent 类]\n AG[Agency 类]\n C[通信流]\n end\n \n subgraph \"工具层\"\n BT[BaseTool]\n FT[FunctionTool]\n SF[Schema Factory]\n end\n \n subgraph \"基础设施\"\n FM[文件管理]\n VS[向量存储]\n end\n \n U --> F\n U --> CLI\n F --> A\n A --> AG\n AG --> C\n C --> A\n A --> BT\n A --> FT\n A --> SF\n A --> FM\n FM --> VS\n```\n\n## 总结\n\nAgency Swarm 的目录结构体现了以下设计原则：\n\n1. **模块化设计**：核心功能、工具、界面、集成各自独立\n2. **约定优于配置**：代理目录遵循固定命名和结构约定\n3. **可扩展性**：工具和代理可轻松添加至对应目录\n4. **分离关注点**：文件处理、API 通信、工具定义清晰分离\n5. **开发者友好**：示例代码和文档覆盖常见使用场景\n\n开发者应遵循上述目录结构创建新的代理和工具，以便与框架的其他部分无缝集成。\n\n---\n\n\n\n## 智能体 (Agent)\n\n### 相关页面\n\n相关主题：[代理组织 (Agency)](#p-agencies), [自定义工具开发](#p-tools), [通信流程](#p-communication-flows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n- [src/agency_swarm/agent/execution_helpers.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/execution_helpers.py)\n- [src/agency_swarm/agent/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/tools.py)\n- [src/agency_swarm/agent/file_manager.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/file_manager.py)\n- [examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n \n\n# 智能体 (Agent)\n\n## 概述\n\n智能体（Agent）是 Agency Swarm 框架的核心构建单元，代表一个具有特定角色、能力边界和行为规范的语言模型实例。每个智能体通过定义其名称、描述、指令集、可用工具及模型配置来确立其在多智能体协作系统中的职责定位。\n\nAgent 类封装了与 OpenAI API 交互的完整逻辑，支持异步消息处理、文件管理、工具调用、通信流控制等核心功能。在 Agency 架构中，智能体之间通过预定义的通信流（Communication Flows）进行消息传递和任务交接，形成协作网络来解决复杂问题。\n\n资料来源：[src/agency_swarm/agent/core.py:1-100]()\n\n## 核心架构\n\n### 类定义与继承结构\n\nAgent 类是所有自定义智能体的基类，开发者通过继承 Agent 并配置其参数来创建特定角色的智能体。框架采用组合模式管理智能体的各个功能模块，包括工具管理器、文件管理器、消息处理器等。\n\n```python\nfrom agency_swarm import Agent\n\nclass AgentName(Agent):\n def __init__(self):\n super().__init__(\n name=\"AgentName\",\n description=\"Description of the agent\",\n instructions=\"instructions.md\",\n tools=[ExampleTool],\n )\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n### 智能体目录结构\n\n遵循规范的目录结构是确保智能体正确加载和运行的前提条件。框架约定每个智能体应放置在 `agency_swarm/agents/` 目录下，并采用 CamelCase 命名规范。\n\n```\nagency_swarm/agents/AgentName/\n│\n├── AgentName/ # 智能体专属目录\n│ ├── files/ # 上传至 OpenAI 的文件目录\n│ ├── tools/ # 智能体使用的工具目录\n│ ├── schemas/ # OpenAPI 架构文件目录\n│ ├── AgentName.py # 核心智能体类文件\n│ ├── __init__.py # Python 包初始化文件\n│ └── instructions.md # 智能体指令文档\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n## 构造函数参数\n\n### 必需参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `name` | str | 智能体的唯一标识名称 |\n| `description` | str | 智能体的职责描述，用于上下文理解和任务分配 |\n| `instructions` | str | 指令文件路径或内联指令文本，定义智能体行为规范 |\n\n### 可选参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `files_folder` | str | None | 本地文件目录路径，这些文件会上传至 OpenAI |\n| `schemas_folder` | str | None | OpenAPI 架构文件夹路径，用于自动生成工具 |\n| `tools` | list | [] | 智能体可调用的工具列表 |\n| `model` | str | \"gpt-5.4\" | 使用的语言模型标识 |\n| `model_settings` | ModelSettings | None | 模型行为配置对象 |\n| `output_type` | ResponseFormat | None | 输出格式约束 |\n| `output_guardrails` | list | [] | 输出内容校验拦截器 |\n| `input_guardrails` | list | [] | 输入内容校验拦截器 |\n| `validation_attempts` | int | 1 | 输出验证失败后的重试次数 |\n\n资料来源：[src/agency_swarm/agent/core.py:1-100]()\n\n## 模型配置 (ModelSettings)\n\nModelSettings 类用于精细控制模型的行为参数，支持的配置项如下：\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `temperature` | float | 采样温度，控制输出的随机性（0.0-2.0） |\n| `top_p` | float | Nucleus 采样参数 |\n| `max_tokens` | int | 最大输出 token 数量 |\n| `reasoning` | Reasoning | 推理能力配置对象 |\n\n### 推理模型配置\n\n对于支持推理能力的模型（如 o1 系列），需使用 `Reasoning` 对象进行配置：\n\n```python\nfrom agency_swarm import Agent, ModelSettings\nfrom openai.types.responses import Reasoning\n\nagent = Agent(\n name=\"ReasoningAgent\",\n description=\"具有推理能力的智能体\",\n instructions=\"你是一个逻辑分析助手\",\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n ),\n)\n```\n\n**重要约束**：\n- 推理模型（如 o1 系列）**不支持** `temperature` 参数\n- 非推理模型**不支持** `reasoning` 参数\n\n资料来源：[src/agency_swarm/utils/create_agent_template.py:1-50]()\n\n## 核心方法\n\n### 异步响应获取\n\n`get_response()` 是智能体的核心执行方法，用于处理用户消息并获取模型响应：\n\n```python\nasync def get_response(\n self,\n message: str | list[TResponseInputItem],\n sender_name: str | None = None,\n context_override: dict[str, Any] | None = None,\n hooks_override: RunHooks | None = None,\n run_config_override: RunConfig | None = None,\n file_ids: list[str] | None = None,\n additional_instructions: str | None = None,\n agency_context: AgencyContext | None = None,\n **kwargs: Any,\n) -> RunResult:\n```\n\n该方法支持异步调用，返回 `RunResult` 对象包含完整的执行结果。同步调用可使用 `get_response_sync()` 方法。\n\n资料来源：[src/agency_swarm/agent/core.py:100-150]()\n\n### 文件上传管理\n\n`upload_file()` 方法用于将本地文件上传至 OpenAI 文件存储系统：\n\n```python\ndef upload_file(self, file_path: str, include_in_vector_store: bool = True) -> str:\n \"\"\"Upload a file using the agent's file manager.\"\"\"\n if self.file_manager:\n return self.file_manager.upload_file(file_path, include_in_vector_store)\n raise RuntimeError(f\"Agent {self.name} has no file manager configured\")\n```\n\n上传后的文件可被智能体用于上下文检索、代码解释等场景。\n\n资料来源：[src/agency_swarm/agent/core.py:150-170]()\n\n### 工具自动加载\n\n框架支持从指定文件夹自动加载工具实现：\n\n```python\ndef _load_tools_from_folder(self) -> None:\n \"\"\"Load tools defined in ``tools_folder`` and add them to the agent.\n\n Supports both ``BaseTool`` subclasses and ``FunctionTool``\n instances created via the ``@function_tool`` decorator.\n \"\"\"\n load_tools_from_folder(self)\n```\n\n支持两种工具定义方式：\n- 继承 `BaseTool` 抽象类\n- 使用 `@function_tool` 装饰器创建 FunctionTool 实例\n\n资料来源：[src/agency_swarm/agent/core.py:80-90]()\n\n### 架构文件解析\n\n`_parse_schemas()` 方法从 `schemas_folder` 目录读取 OpenAPI 架构文件并自动转换为可用工具：\n\n```python\ndef _parse_schemas(self):\n \"\"\"Parse OpenAPI schemas from the schemas folder and create tools.\"\"\"\n parse_schemas(self)\n```\n\n这一功能使智能体能够通过自然语言调用外部 API 服务。\n\n资料来源：[src/agency_swarm/agent/core.py:92-96]()\n\n## 执行上下文与钩子\n\n### 运行钩子 (RunHooks)\n\nRunHooks 允许开发者在智能体执行生命周期的关键节点注入自定义逻辑：\n\n```mermaid\ngraph TD\n A[开始执行] --> B[pre_run 钩子]\n B --> C[模型推理]\n C --> D{是否调用工具}\n D -->|是| E[工具执行]\n D -->|否| F[返回结果]\n E --> G[post_tool 钩子]\n G --> C\n F --> H[post_run 钩子]\n H --> I[返回 RunResult]\n```\n\n资料来源：[src/agency_swarm/agent/execution_helpers.py:1-50]()\n\n### 运行上下文包装器\n\n`RunContextWrapper` 提供执行上下文的统一访问接口，用于在钩子函数中访问和管理运行时状态：\n\n```python\nfrom agents import RunContextWrapper\n\n# 在钩子中使用\ndef my_hook(wrapper: RunContextWrapper, **kwargs):\n context = wrapper.context\n # 访问和修改上下文\n```\n\n资料来源：[src/agency_swarm/agent/execution_helpers.py:30-60]()\n\n## 执行结果模型\n\n`RunResult` 是智能体执行的核心返回对象，包含丰富的执行元信息：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `final_output` | Any | 最终输出内容 |\n| `new_items` | list[RunItem] | 执行过程中产生的新项目 |\n| `raw_responses` | list | 原始 API 响应 |\n| `input_guardrail_results` | list | 输入校验结果 |\n| `output_guardrail_results` | list | 输出校验结果 |\n| `tool_input_guardrail_results` | list | 工具输入校验结果 |\n| `tool_output_guardrail_results` | list | 工具输出校验结果 |\n| `context_wrapper` | RunContextWrapper | 执行上下文包装器 |\n\n资料来源：[src/agency_swarm/agent/execution_helpers.py:20-45]()\n\n## 使用示例\n\n### 基础智能体创建\n\n```python\nfrom agency_swarm import Agent, ModelSettings\n\nceo = Agent(\n name=\"CEO\",\n description=\"负责客户沟通、任务规划与管理\",\n instructions=\"你必须与其他智能体对话以确保任务完整执行\",\n files_folder=\"./files\",\n schemas_folder=\"./schemas\",\n tools=[my_custom_tool],\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n max_tokens=25000,\n ),\n)\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n### 带输出格式的智能体\n\n```python\nfrom agency_swarm import Agent\nfrom pydantic import BaseModel\n\nclass ResponseFormat(BaseModel):\n chat_name: str\n message: str\n\nagent = Agent(\n name=\"Analyzer\",\n description=\"数据分析智能体\",\n instructions=\"分析用户输入并返回结构化结果\",\n output_type=ResponseFormat,\n validation_attempts=3,\n)\n```\n\n### 协作智能体配置\n\n```python\nfrom agency_swarm import Agency, Agent, SendMessage, Handoff\n\n# 创建协调者\ncoordinator = Agent(\n name=\"Coordinator\",\n description=\"任务协调者\",\n instructions=\"你负责任务分配和结果汇总\",\n)\n\n# 创建专家\nspecialist = Agent(\n name=\"Specialist\",\n description=\"专业分析智能体\",\n tools=[analyze_costs, analyze_performance],\n)\n\n# 定义通信流\nagency = Agency(\n coordinator,\n specialist,\n communication_flows=[\n (coordinator > specialist, SendMessage),\n (specialist > coordinator, Handoff),\n ],\n)\n```\n\n资料来源：[examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n\n## 可视化\n\nAgency Swarm 提供内置的可视化功能，可生成交互式 HTML 页面展示智能体间的通信拓扑：\n\n```python\nagency = Agency(ceo, dev, qa, communication_flows=[...])\n\nhtml_file = agency.visualize(\n output_file=\"agency_interactive_demo.html\",\n include_tools=True,\n open_browser=True,\n)\n```\n\n生成的可视化页面支持：\n- 拖拽交互\n- 缩放控制\n- 工具显示/隐藏切换\n- 通信流量统计\n\n资料来源：[examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n\n## 最佳实践\n\n### 指令编写规范\n\n1. **明确角色边界**：清晰定义智能体的职责范围和决策权限\n2. **通信协议**：规定与其他智能体交互的标准格式\n3. **错误处理**：定义异常场景下的降级策略\n4. **关键约束**：使用 `CRITICAL` 标记必须遵守的行为规则\n\n```python\ninstructions=\"\"\"\n你的名称是 Coordinator agent。\n你协调分析工作。分配任务时，明确决策关注点和所需方法。\nCRITICAL: 当你收到专家回复时，必须原样包含其完整回复文本。\n不要总结、转述或遗漏任何细节。\n\"\"\"\n```\n\n### 工具设计原则\n\n- 单一职责：每个工具只完成一个明确的任务\n- 清晰的输入输出：定义明确的数据结构和返回格式\n- 错误处理：工具应捕获并妥善处理异常情况\n\n### 模型选择建议\n\n| 场景 | 推荐模型 | 配置 |\n|------|----------|------|\n| 简单任务 | gpt-5.4-mini | temperature=0.3 |\n| 复杂推理 | gpt-5.4 | temperature=0.7, max_tokens=high |\n| 精确输出 | gpt-5.4-mini | temperature=0.0, output_type=json_schema |\n\n资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n---\n\n\n\n## 代理组织 (Agency)\n\n### 相关页面\n\n相关主题：[智能体 (Agent)](#p-agents), [通信流程](#p-communication-flows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/agency/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agency/core.py)\n- [src/agency_swarm/agency/setup.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agency/setup.py)\n- [src/agency_swarm/agency/helpers.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agency/helpers.py)\n- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n- [examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n \n\n# 代理组织 (Agency)\n\n## 概述\n\nAgency 是 Agency Swarm 框架中的核心组件，负责管理和协调多个 Agent 之间的协作交互。作为多代理系统的容器，Agency 封装了代理初始化、通信流配置、消息路由和响应处理等关键功能，使开发者能够构建复杂的多代理工作流。\n\nAgency 的主要职责包括：\n\n- 管理多个 Agent 实例的生命周期\n- 定义和维护 Agent 之间的通信流程（Communication Flows）\n- 处理代理间的消息传递和上下文共享\n- 提供统一的响应接口，支持同步和异步模式\n- 支持可视化展示代理组织结构\n\n## 核心架构\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[用户/应用] --> B[Agency]\n B --> C[Entry Point Agent]\n B --> D[Secondary Agents]\n C --> E[Communication Flows]\n D --> E\n E --> F[Handoff]\n E --> G[SendMessage]\n E --> H[SendMessageWithContext]\n B --> I[Shared Instructions]\n I --> C\n I --> D\n```\n\n### 关键组件\n\n| 组件 | 说明 |\n|------|------|\n| **Agent** | 独立的代理单元，拥有自己的工具、指令和模型配置 |\n| **Communication Flows** | 定义代理之间的通信模式和所使用的通信工具 |\n| **Shared Instructions** | 所有代理共享的全局指令集 |\n| **Entry Point Agent** | 作为入口点的代理，接收初始用户请求 |\n\n## 创建代理组织\n\n### 基本语法\n\nAgency 的构造函数接受可变数量的 Agent 作为位置参数，第一个 Agent 自动成为入口点代理：\n\n```python\nfrom agency_swarm import Agency, Agent\n\n# 创建代理\nceo = Agent(name=\"CEO\", ...)\ndeveloper = Agent(name=\"Developer\", ...)\nqa = Agent(name=\"QA\", ...)\n\n# 创建代理组织\nagency = Agency(ceo, developer, qa)\n```\n\n### 完整参数配置\n\n```python\nagency = Agency(\n ceo, # 入口点代理（必需）\n developer,\n qa,\n communication_flows=[\n (ceo > developer, Handoff), # CEO 可以将任务交接给 Developer\n (developer > qa, Handoff), # Developer 可以将任务交接给 QA\n ],\n shared_instructions=\"这是代理组织的全局共享指令\",\n name=\"MyAgency\",\n)\n```\n\n## 通信流程配置\n\n### 通信流语法\n\n通信流程使用流式语法定义代理之间的交互模式：\n\n```python\n# 基本语法\n(agent_a > agent_b, ToolClass)\n\n# 多代理通信\n(agent_a < agent_b > agent_c, ToolClass)\n```\n\n### 通信工具类型\n\n| 工具类型 | 说明 | 使用场景 |\n|----------|------|----------|\n| `Handoff` | 代理交接工具，用于完全转移对话控制权 | 任务委派、职责转换 |\n| `SendMessage` | 发送消息工具，直接向目标代理发送消息 | 信息传递、请求响应 |\n| `SendMessageWithContext` | 带上下文的发送消息工具，传递额外上下文信息 | 需要传递额外数据的消息 |\n\n### 通信流示例\n\n```python\nfrom agency_swarm import Agency, Agent, Handoff, SendMessage, SendMessageWithContext\n\n# 定义代理\ncoordinator = Agent(name=\"Coordinator\", ...)\nspecialist = Agent(name=\"Specialist\", ...)\n\n# 创建代理组织并配置通信流\nagency = Agency(\n coordinator,\n specialist,\n communication_flows=[\n # Coordinator 可以向 Specialist 发送带上下文的消息\n (coordinator > specialist, SendMessageWithContext),\n # Specialist 可以将任务交接回 Coordinator\n (specialist > coordinator, Handoff),\n ],\n)\n```\n\n资料来源：[examples/custom_send_message.py:1-50]()\n\n## 共享指令\n\n`shared_instructions` 参数用于定义所有代理共享的全局指令。这些指令会在每个代理初始化时注入，确保所有代理都能访问相同的上下文信息和行为规范。\n\n```python\nagency = Agency(\n ceo,\n developer,\n shared_instructions=\"这是一个软件开发代理组织。所有代理应该遵循代码规范和最佳实践。\",\n)\n```\n\n## 响应处理\n\n### 异步获取响应\n\n```python\nimport asyncio\n\nasync def main():\n resp = await agency.get_response(\"创建一个小项目骨架\")\n print(resp.final_output)\n\nasyncio.run(main())\n```\n\n### 同步获取响应\n\n```python\n# 同步模式\nresp = agency.get_response_sync(\"创建一个小项目骨架\")\nprint(resp.final_output)\n```\n\n### 终端用户界面\n\nAgency 提供了内置的 TUI（终端用户界面）功能：\n\n```python\nagency.tui(show_reasoning=True)\n```\n\n资料来源：[examples/interactive/tui.py:1-80]()\n\n## 可视化功能\n\nAgency 支持生成交互式的可视化图表，展示代理组织的结构和通信流程：\n\n```python\nhtml_file = agency.visualize(\n output_file=\"agency_visualization.html\",\n include_tools=True,\n open_browser=True,\n)\n```\n\n可视化功能可以：\n\n- 展示所有代理及其角色\n- 显示代理之间的通信流向\n- 展示每个代理拥有的工具\n- 支持交互式拖拽和缩放\n\n资料来源：[examples/agency_visualization.py:1-60]()\n\n## 工作流程示意\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agency as Agency\n participant Entry as 入口代理\n participant Agent1 as 代理1\n participant Agent2 as 代理2\n\n User->>Agency: get_response(message)\n Agency->>Entry: 处理消息\n Entry->>Agent1: Handoff/SendMessage\n Agent1->>Agent2: Handoff/SendMessage\n Agent2-->>Agent1: 返回结果\n Agent1-->>Entry: 返回结果\n Entry-->>Agency: 最终输出\n Agency-->>User: 响应结果\n```\n\n## 完整使用示例\n\n```python\nfrom agency_swarm import Agency, Agent, Handoff, ModelSettings\n\n# 创建支持代理\nsupport = Agent(\n name=\"Support\",\n description=\"处理客户咨询和技术支持请求\",\n instructions=\"你是技术支持代理。使用搜索工具回答用户问题。\",\n tools=[WebSearchTool()],\n model=\"gpt-4o\",\n)\n\n# 数学代理\nmath = Agent(\n name=\"MathAgent\",\n description=\"处理算术和计算密集型请求\",\n instructions=\"你是数学代理。使用计算工具处理算术问题。\",\n tools=[calculate],\n model=\"gpt-4o\",\n model_settings=ModelSettings(temperature=0.7),\n)\n\n# 创建代理组织\nagency = Agency(\n support,\n math,\n communication_flows=[\n (support < math > support, Handoff),\n ],\n shared_instructions=\"演示推理、网络搜索和代理交接功能。\",\n name=\"SupportAgency\",\n)\n\n# 运行\nif __name__ == \"__main__\":\n response = agency.get_response_sync(\"帮我计算 345 * 18\")\n print(response.final_output)\n```\n\n## 最佳实践\n\n### 1. 明确的职责划分\n\n每个代理应有清晰的职责定义，通过 `description` 和 `instructions` 参数明确其角色和功能。\n\n### 2. 合理的通信流设计\n\n- 使用 Handoff 进行任务委派和职责转换\n- 使用 SendMessage 进行信息查询和响应获取\n- 避免过度复杂的通信流，保持流程清晰\n\n### 3. 共享指令的使用\n\n将所有代理需要遵守的通用规则和约束放在 `shared_instructions` 中，避免重复定义。\n\n### 4. 模型配置\n\n根据代理的具体任务类型调整模型参数，如推理强度、token 限制等：\n\n```python\nfrom agency_swarm import ModelSettings, Reasoning\n\nagent = Agent(\n name=\"Analyst\",\n model_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\"),\n ),\n)\n```\n\n## 总结\n\nAgency 作为 Agency Swarm 框架的核心组件，提供了一套完整的多代理协作解决方案。通过其灵活的通信流机制、共享指令系统和统一的响应接口，开发者可以轻松构建复杂的代理工作流，实现从简单的任务委托到复杂的多代理协作场景。\n\n---\n\n\n\n## 通信流程\n\n### 相关页面\n\n相关主题：[代理组织 (Agency)](#p-agencies), [智能体 (Agent)](#p-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/agent/agent_flow.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/agent_flow.py)\n- [src/agency_swarm/tools/send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py)\n- [examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n- [examples/handoffs.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/handoffs.py)\n- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n- [src/agency_swarm/ui/templates/html/visualization.html](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/ui/templates/html/visualization.html)\n \n\n# 通信流程\n\n## 概述\n\n通信流程（Communication Flows）是 Agency Swarm 框架中定义多代理之间如何传递消息和任务的核心理念。在 Agency Swarm 中，代理不再孤立工作，而是通过预定义的通信模式实现协作。通信流程允许开发者精确控制代理之间的消息流向、触发条件以及交接逻辑。\n\nAgency Swarm 支持两种主要的通信机制：\n\n1. **直接消息传递（SendMessage）**：代理之间点对点的消息传递\n2. **代理交接（Handoff）**：将对话控制权完全转移给另一个代理\n\n资料来源：[examples/agency_visualization.py:32-39]()\n\n## 核心概念\n\n### 代理通信架构\n\nAgency Swarm 采用星型与网状混合的通信架构。Agency 作为顶层容器管理所有代理，通过 `communication_flows` 参数定义代理间的合法通信路径。默认情况下，如果没有定义通信流程，代理只能与用户直接交互。\n\n```mermaid\ngraph TB\n subgraph Agency\n CEO[\"CEO 代理
(入口点)\"]\n Dev[\"Developer 代理\"]\n PM[\"PM 代理\"]\n QA[\"QA 代理\"]\n end\n \n CEO <-->|\"dev < CEO > PM > dev\"| Dev\n CEO <-->|\"dev < CEO > PM > dev\"| PM\n Dev <-->|\"dev > qa, Handoff\"| QA\n \n User((用户)) --> CEO\n```\n\n### 入口点代理\n\n入口点代理是用户首次交互的代理，也是消息流的起点。在 Agency 初始化时，第一个参数即为入口点代理。\n\n```python\nagency = Agency(\n ceo, # 入口点代理（位置参数）\n communication_flows=[\n (dev < ceo > pm > dev),\n (dev > qa, Handoff),\n ],\n)\n```\n\n资料来源：[examples/agency_visualization.py:30-39]()\n\n## 通信流程定义语法\n\n### 符号约定\n\nAgency Swarm 使用简洁的符号语法定义通信流程：\n\n| 符号 | 含义 | 示例 |\n|------|------|------|\n| `>` | 消息流向右侧代理 | `ceo > dev` 表示 CEO 向 Developer 发送消息 |\n| `<` | 消息流向左侧代理 | `dev < ceo` 表示 Developer 接收来自 CEO 的消息 |\n| `>>` | Handoff（完全交接） | `dev >> qa` Developer 完全交接给 QA |\n| `, Handoff` | 添加 Handoff 机制 | `(dev > qa, Handoff)` |\n\n### 流程模式\n\n#### 直接通信模式\n\n使用 `<` 和 `>` 符号定义双向消息传递：\n\n```python\n(dev < ceo > pm > dev)\n```\n\n此模式表示：\n- Developer 可以接收来自 CEO 的消息\n- PM 可以接收来自 CEO 的消息\n- Developer 可以向 PM 发送消息\n\n```mermaid\ngraph LR\n CEO -->|消息| Dev\n CEO -->|消息| PM\n Dev -->|消息| PM\n```\n\n资料来源：[examples/agency_visualization.py:35]()\n\n#### Handoff 模式\n\nHandoff 允许一个代理将对话控制权完全转移给另一个代理：\n\n```python\n(dev > qa, Handoff)\n```\n\n当 Developer 执行 Handoff 时：\n1. Developer 的对话上下文会传递给 QA\n2. QA 成为当前活跃代理\n3. 用户后续消息由 QA 处理\n\n```mermaid\ngraph TB\n Dev -->|\"Handoff\"| QA\n QA -->|\"处理后续对话\"| End[对话结束/返回]\n```\n\n资料来源：[examples/handoffs.py:1-50]()\n\n## SendMessage 工具\n\nSendMessage 是 Agency Swarm 中实现代理间通信的核心工具。每个代理都自动配备此工具，允许向其他代理发送消息。\n\n### 工具定义\n\n```python\nclass SendMessage(BaseTool):\n \"\"\"用于向其他代理发送消息的工具\"\"\"\n \n recipient_name: str = Field(\n ..., \n description=\"消息接收者的名称\"\n )\n message: str = Field(\n ..., \n description=\"要发送的消息内容\"\n )\n```\n\n### 使用示例\n\n```python\n# 在代理的指令中调用\n\"\"\"\n当需要与 Developer 协作时，请使用 SendMessage 工具。\nrecipient_name: \"Developer\"\nmessage: \"请帮我实现用户认证功能\"\n\"\"\"\n```\n\n资料来源：[src/agency_swarm/tools/send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py)\n\n## 自定义通信配置\n\n### SendMessage 配置选项\n\n通过在 Agency 初始化时传递参数，可以自定义 SendMessage 的行为：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `shared_context` | dict | None | 所有代理共享的上下文数据 |\n| `message_history` | int | 10 | 消息历史保留条数 |\n| `timeout` | int | 300 | 消息响应超时（秒） |\n\n### 自定义消息格式\n\n可以自定义发送给其他代理的消息格式：\n\n```python\nfrom agency_swarm import Agency, Agent\n\nceo = Agent(\n name=\"CEO\",\n instructions=\"你的指令\",\n)\n\ndev = Agent(\n name=\"Developer\",\n instructions=\"你的指令\",\n)\n\nagency = Agency(\n ceo,\n communication_flows=[\n (ceo > dev),\n ],\n shared_instructions=\"这是所有代理共享的指令\",\n)\n```\n\n资料来源：[examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n\n## Agent Flow 执行流程\n\n### 消息处理生命周期\n\n```mermaid\ngraph TD\n Start[用户消息] --> Receive[Agent 接收消息]\n Receive --> Check{检查通信流程}\n Check -->|允许通信| Route[路由到目标代理]\n Check -->|禁止通信| Reject[拒绝/返回错误]\n Route --> Process[目标代理处理]\n Process --> Send[发送响应]\n Send --> CheckHandoff{是否 Handoff?}\n CheckHandoff -->|是| Transfer[转移到新代理]\n CheckHandoff -->|否| Return[返回给发起者]\n Transfer --> NewAgent[新代理接管]\n NewAgent --> Continue[继续对话]\n```\n\n### 异步通信支持\n\nAgency Swarm 支持异步消息处理：\n\n```python\nimport asyncio\n\nasync def main():\n agency = create_agency()\n response = await agency.get_response(\"创建项目骨架\")\n print(response.final_output)\n\nasyncio.run(main())\n```\n\n资料来源：[README.md:150-158]()\n\n## 可视化工具\n\nAgency Swarm 提供了内置的可视化功能来展示通信流程：\n\n### 生成可视化\n\n```python\nhtml_file = agency.visualize(\n output_file=\"agency_interactive_demo.html\",\n include_tools=True,\n open_browser=True,\n)\n```\n\n### 可视化统计\n\n可视化界面显示以下统计信息：\n\n- **代理数量**：Agency 中的代理总数\n- **工具数量**：所有代理使用的工具总数\n- **通信流数量**：定义的通信流程数量\n- **入口点数量**：可作为入口的代理数量\n\n```html\n\n
Agency Statistics
\n
Agents: 0
\n
Tools: 0
\n
Communication Flows: 0
\n
Entry Points: 0
\n
\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n- [examples/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/tools.py)\n- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n- [src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n- [src/agency_swarm/integrations/README.md](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/integrations/README.md)\n \n\n# 自定义工具开发\n\n## 概述\n\nAgency Swarm 框架提供了灵活的自定义工具开发机制，允许开发者创建可被 AI Agent 调用的工具。通过自定义工具，Agent 可以执行特定的业务逻辑、访问外部 API、操作文件系统或执行计算任务。工具是 Agent 与外部世界交互的核心桥梁，使得多智能体系统能够完成复杂的工作流程。\n\n## 工具开发方式\n\nAgency Swarm 支持两种主要的工具创建方式：使用 `@function_tool` 装饰器和继承 `BaseTool` 基类。\n\n### 使用 @function_tool 装饰器\n\n`@function_tool` 装饰器是最简单的工具创建方式，适用于轻量级的工具开发。通过装饰一个普通 Python 函数，可以快速将其转换为可被 Agent 调用的工具。\n\n```python\nfrom agency_swarm.tools import function_tool\n\n@function_tool\ndef calculate(a: float, b: float) -> str:\n \"\"\"Performs arithmetic calculation on two numbers.\n \n Args:\n a: First number\n b: Second number\n \"\"\"\n return str(a + b)\n```\n\n这种方法的优势在于代码简洁、学习曲线平缓，适合实现简单的计算或数据转换逻辑。装饰器会自动处理参数解析和返回值格式化。\n\n### 使用 BaseTool 基类\n\n`BaseTool` 提供了更强大的工具开发能力，适合需要复杂验证、状态管理或多步骤执行的工具。通过继承 `BaseTool` 并实现 `run` 方法，开发者可以构建功能完整的工具。\n\n```python\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\n\nclass MyCustomTool(BaseTool):\n \"\"\"\n A brief description of what the custom tool does.\n The docstring should clearly explain the tool's purpose and functionality.\n It will be used by the agent to determine when to use this tool.\n \"\"\"\n\n example_field: str = Field(\n ..., description=\"Description of the example field, explaining its purpose and usage for the Agent.\"\n )\n\n def run(self):\n \"\"\"\n The implementation of the run method, where the tool's main functionality is executed.\n \"\"\"\n # Your custom tool logic goes here\n return f\"Result: {self.example_field}\"\n```\n\n## 工具架构\n\n### 类层次结构\n\nAgency Swarm 的工具系统采用分层架构设计：\n\n```mermaid\ngraph TD\n A[Python Function] --> B[@function_tool Decorator]\n A --> C[BaseTool Class]\n C --> D[Tool Validation]\n C --> E[Parameter Parsing]\n C --> F[run Method]\n B --> G[FunctionToolCompat]\n G --> F\n D --> H[Error Handling]\n E --> H\n```\n\n### 工具加载流程\n\n工具通过 Agent 的 `tools` 参数进行绑定，并在初始化时完成加载和验证：\n\n```mermaid\ngraph TD\n A[Agent Initialization] --> B[tools Parameter]\n B --> C[Load Tools from Folder]\n B --> D[Parse OpenAPI Schemas]\n C --> E[Tool Validation]\n D --> E\n E --> F[Register with Agent]\n F --> G[Ready for Execution]\n```\n\n## 工具目录结构\n\n按照项目贡献规范，自定义工具应放置在 `agency_swarm/tools/{category}/` 目录下：\n\n```\nagency_swarm/tools/your-tool-category/\n│\n├── YourNewTool.py # 工具主类文件\n└── __init__.py # 工具包初始化文件\n```\n\n工具类别可以包括 `coding`、`browsing`、`investing` 等，每个类别对应特定领域的工具集合。\n\n## 工具使用示例\n\n### 在 Agent 中使用工具\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools.example import ExampleTool\n\nclass AgentName(Agent):\n def __init__(self):\n super().__init__(\n name=\"AgentName\",\n description=\"Description of the agent\",\n instructions=\"./instructions.md\",\n tools=[ExampleTool],\n )\n```\n\n### 完整示例：多工具 Agent\n\n```python\nfrom agency_swarm import Agent, Agency\nfrom agency_swarm.tools import BaseTool, function_tool\nfrom pydantic import Field\n\n# 使用 BaseTool 创建自定义工具\nclass WebSearchTool(BaseTool):\n \"\"\"执行网络搜索并返回结果\"\"\"\n query: str = Field(..., description=\"搜索查询关键词\")\n \n def run(self):\n # 实现搜索逻辑\n return f\"搜索结果: {self.query}\"\n\n# 使用 function_tool 创建计算工具\n@function_tool\ndef calculate(a: float, b: float) -> str:\n \"\"\"执行算术运算\"\"\"\n return str(a + b)\n\n# 创建使用工具的 Agent\nsupport = Agent(\n name=\"SupportAgent\",\n description=\"处理用户请求并提供信息\",\n instructions=\"你是支持代理，可以搜索网络和执行计算\",\n tools=[WebSearchTool, calculate],\n model=\"gpt-5.4-mini\",\n)\n```\n\n## OpenAPI 架构转换\n\nAgency Swarm 提供了 `ToolFactory` 用于从 OpenAPI 规范自动生成工具。这一功能使得集成第三方 API 变得简单高效：\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# 从本地文件加载\nwith open(\"schemas/your_schema.json\") as f:\n tools = ToolFactory.from_openapi_schema(f.read())\n\n# 从远程 API 获取\nimport requests\ntools = ToolFactory.from_openapi_schema(\n requests.get(\"https://api.example.com/openapi.json\").json(),\n)\n```\n\n## 工具测试\n\n### 测试框架\n\n每个工具应在 `agency_swarm/tests/test_tools.py` 中添加对应的测试用例：\n\n```python\ndef test_my_tool_example():\n tool = MyCustomTool(example_field=\"test value\")\n result = tool.run()\n assert \"expected output\" in result\n```\n\n### 测试执行\n\n使用 Makefile 运行测试覆盖率：\n\n```bash\nmake coverage\n```\n\n## 配置参数\n\n### BaseTool 字段定义\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `Field(...)` | Any | 是 | 使用 Pydantic Field 定义工具参数 |\n| `description` | str | 是 | 参数描述，供 Agent 理解何时使用 |\n| `default` | Any | 否 | 参数默认值 |\n\n### Agent 工具配置\n\n| 参数 | 说明 |\n|------|------|\n| `tools` | 工具类列表或 BaseTool 实例列表 |\n| `tools_folder` | 从指定文件夹自动加载工具 |\n\n## 工具与 Agent 通信\n\nAgent 可以通过以下方式使用工具：\n\n1. **直接调用**：Agent 根据任务需求选择合适的工具\n2. **工具链**：多个工具按顺序执行完成复杂任务\n3. **条件调用**：基于上下文条件决定是否调用特定工具\n\n```mermaid\ngraph LR\n A[User Request] --> B[Agent]\n B --> C{选择工具}\n C -->|搜索| D[WebSearchTool]\n C -->|计算| E[Calculate]\n D --> F[结果]\n E --> F\n F --> G[Agent Response]\n```\n\n## 最佳实践\n\n1. **清晰的描述**：为每个工具编写清晰的文档字符串，说明其用途和使用场景\n2. **精确的参数描述**：使用 Pydantic Field 的 description 参数详细说明每个参数\n3. **错误处理**：在 `run` 方法中实现适当的错误处理和边界情况处理\n4. **返回格式**：返回易于 Agent 理解和处理的结果格式\n5. **测试覆盖**：为每个工具编写完整的测试用例\n\n## 相关资源\n\n- [工具基础类源码](../src/agency_swarm/tools/base_tool.py)\n- [工具工厂源码](../src/agency_swarm/tools/tool_factory.py)\n- [函数工具兼容性](../src/agency_swarm/tools/function_tool_compat.py)\n- [工具使用示例](../examples/tools.py)\n- [交互式示例](../examples/interactive/tui.py)\n\n---\n\n\n\n## 内置工具\n\n### 相关页面\n\n相关主题：[自定义工具开发](#p-tools), [OpenAPI 工具集成](#p-openapi)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/tools/built_in/IPythonInterpreter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/IPythonInterpreter.py)\n- [src/agency_swarm/tools/built_in/LoadFileAttachment.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/LoadFileAttachment.py)\n- [src/agency_swarm/tools/built_in/PersistentShellTool.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/PersistentShellTool.py)\n- [src/agency_swarm/tools/built_in/PresentFiles.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/PresentFiles.py)\n \n\n# 内置工具\n\n## 概述\n\nAgency Swarm 框架提供了一组内置工具（Built-in Tools），位于 `src/agency_swarm/tools/built_in/` 目录下。这些工具是预实现的、可复用的功能模块，旨在为智能体（Agent）提供常用的系统级能力，包括代码执行、文件处理和Shell命令操作。\n\n内置工具的主要特点包括：\n\n- **开箱即用**：无需额外配置即可在智能体中使用\n- **统一接口**：所有工具继承自 `BaseTool` 基类，保持接口一致性\n- **可扩展性**：开发者可以基于现有工具模式创建自定义工具\n- **工具生态**：按类别组织在 `tools/` 目录下的不同子目录中\n\n```资料来源：[examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)```\n\n## 工具架构\n\n### 工具基类\n\nAgency Swarm 中的工具主要基于两个核心组件：\n\n1. **BaseTool**：Pydantic 模型形式的工具基类，需要定义输入字段并实现 `run()` 方法\n2. **@function_tool 装饰器**：函数式工具定义方式，更轻量级\n\n所有内置工具均继承自 `BaseTool` 类，通过 Pydantic 的 `Field` 定义工具参数，并实现 `run()` 方法执行具体逻辑。\n\n```python\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\n\nclass MyCustomTool(BaseTool):\n \"\"\"工具描述文档字符串\"\"\"\n \n example_field: str = Field(\n ..., \n description=\"字段用途说明\"\n )\n \n def run(self):\n return f\"Result: {self.example_field}\"\n```\n\n```资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)```\n\n### 工具加载机制\n\n工具可以从以下来源加载到智能体：\n\n- **tools 参数**：直接在智能体初始化时传入工具类或实例列表\n- **tools_folder**：指定文件夹路径，自动加载该目录下的所有工具\n- **schemas_folder**：解析 OpenAPI schema 并自动生成工具\n\n```python\nclass AgentName(Agent):\n def __init__(self):\n super().__init__(\n name=\"AgentName\",\n description=\"Description of the agent\",\n instructions=\"instructions.md\",\n tools=[ExampleTool], # 直接传入工具\n )\n```\n\n```资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)```\n\n## 内置工具详解\n\n### PersistentShellTool\n\n**功能概述**：持久化Shell命令执行工具，允许智能体在连续会话中执行操作系统命令。\n\n**核心特性**：\n\n- **持久化状态**：维护命令执行的工作目录上下文\n- **超时保护**：默认超时时间为 5 分钟\n- **目录变更检测**：自动检测并警告目录变更情况\n- **格式化输出**：清晰展示标准输出、标准错误和返回码\n\n**输出格式**：\n\n```python\n# 成功执行示例\n**Output:**\n```\n<命令输出内容>\n```\n\n# Stderr:\n```\n<错误输出内容>\n```\n\n**Exit Code:** 0\n\n**Working Directory:** `/current/path`\n\n# 错误执行示例\n❌ Error: Command timed out after 5 minutes\n\n**Working Directory:** `/current/path`\n```\n\n**关键实现细节**：\n\n- 使用 `subprocess.Popen` 执行命令\n- 通过 `communicate()` 方法获取输出\n- 捕获 `TimeoutExpired` 异常处理超时情况\n- 跟踪 `cwd`（当前工作目录）状态\n\n```资料来源：[src/agency_swarm/tools/built_in/PersistentShellTool.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/PersistentShellTool.py)```\n\n### IPythonInterpreter\n\n**功能概述**：交互式 Python 代码解释器，用于在智能体中执行 Python 代码。\n\n**典型应用场景**：\n\n- 数据分析和计算任务\n- 原型开发和测试\n- 科学计算和可视化\n\n**使用方式**：\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools.built_in import IPythonInterpreter\n\nagent = Agent(\n name=\"CodeAgent\",\n description=\"Executes Python code\",\n tools=[IPythonInterpreter],\n)\n```\n\n### LoadFileAttachment\n\n**功能概述**：文件附件加载工具，用于读取和加载用户上传的文件内容。\n\n**主要职责**：\n\n- 从向量存储中检索相关文件\n- 解析不同格式的文件内容\n- 返回文件内容供智能体处理\n\n### PresentFiles\n\n**功能概述**：文件展示工具，用于向用户或调用方呈现文件内容。\n\n**使用场景**：\n\n- 生成报告文件\n- 导出分析结果\n- 创建可视化内容\n\n### WebSearchTool\n\n**功能概述**：网络搜索工具，支持域过滤的网页搜索并提取源URL。\n\n```python\nfrom agency_swarm.tools import WebSearchTool\n\nagent = Agent(\n name=\"SearchAgent\",\n tools=[WebSearchTool],\n # 可以在此指定搜索域过滤器\n)\n```\n\n```资料来源：[examples/web_search.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/web_search.py)```\n\n## 工具使用流程\n\n```mermaid\ngraph TD\n A[创建智能体] --> B[配置工具]\n B --> C{工具来源选择}\n C -->|直接导入| D[tools 参数传入]\n C -->|工具文件夹| E[tools_folder 配置]\n C -->|OpenAPI Schema| F[schemas_folder 配置]\n D --> G[初始化智能体]\n E --> G\n F --> G\n G --> H[运行时调用工具]\n H --> I[执行工具逻辑]\n I --> J[返回工具输出]\n J --> K[智能体处理结果]\n```\n\n## 内置工具列表\n\n| 工具名称 | 类型 | 功能描述 | 主要依赖 |\n|---------|------|---------|---------|\n| PersistentShellTool | BaseTool | 持久化Shell命令执行 | subprocess |\n| IPythonInterpreter | BaseTool | Python代码解释器 | IPython, Jedi |\n| LoadFileAttachment | BaseTool | 文件附件加载 | - |\n| PresentFiles | BaseTool | 文件内容展示 | - |\n| WebSearchTool | BaseTool | 网络搜索 | requests |\n\n## 工具导入方式\n\n### 方式一：直接导入\n\n```python\nfrom agency_swarm.tools.built_in import PersistentShellTool\nfrom agency_swarm.tools.built_in import IPythonInterpreter\n```\n\n### 方式二：导入全部内置工具\n\n```python\nfrom agency_swarm.tools.built_in import *\n```\n\n### 方式三：通过 CLI 导入到项目\n\n```bash\nagency-swarm import-tool PersistentShellTool --destination ./my_tools\n```\n\n```资料来源：[src/agency_swarm/cli/main.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/main.py)```\n\n## 工具目录结构\n\n```\nagency_swarm/tools/\n├── __init__.py\n├── built_in/\n│ ├── __init__.py\n│ ├── PersistentShellTool.py\n│ ├── IPythonInterpreter.py\n│ ├── LoadFileAttachment.py\n│ └── PresentFiles.py\n├── coding/\n│ ├── __init__.py\n│ └── ...\n├── browsing/\n│ ├── __init__.py\n│ └── ...\n└── investing/\n ├── __init__.py\n └── ...\n```\n\n每个工具目录下必须包含 `__init__.py` 文件以确保工具可被正确导入。\n\n```资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)```\n\n## 自定义工具开发\n\n开发者可以参考内置工具的实现模式创建自定义工具：\n\n### BaseTool 模式\n\n```python\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\nfrom typing import Type\n\nclass MyTool(BaseTool):\n \"\"\"自定义工具描述\"\"\"\n \n input_param: str = Field(\n ..., \n description=\"参数描述\"\n )\n \n def run(self):\n # 工具实现逻辑\n return f\"Processed: {self.input_param}\"\n \n @classmethod\n def get_schema(cls) -> dict:\n # 返回工具的JSON Schema\n return cls.model_json_schema()\n```\n\n### @function_tool 装饰器模式\n\n```python\nfrom agency_swarm.tools import function_tool\n\n@function_tool\ndef my_simple_tool(param: str) -> str:\n \"\"\"工具描述\"\"\"\n return f\"Result: {param}\"\n```\n\n```资料来源：[examples/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/tools.py)```\n\n## 工具测试\n\n为确保内置工具的稳定性，建议添加单元测试：\n\n```python\ndef test_my_tool_example():\n from agency_swarm.tools.built_in import MyCustomTool\n \n tool = MyCustomTool(example_field=\"test value\")\n result = tool.run()\n assert \"expected output\" in result\n```\n\n测试文件应位于 `agency_swarm/tests/test_tools.py`。\n\n```资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)```\n\n## 多模态工具输出\n\n内置工具还支持多模态输出，包括图片和文件：\n\n```python\nfrom agency_swarm.tools.utils import (\n tool_output_image_from_path,\n tool_output_file_from_url\n)\nfrom agency_swarm import ToolOutputImage, ToolOutputFileContent\n\nclass LoadShowcaseImage(BaseTool):\n \"\"\"返回图片作为多模态输出\"\"\"\n \n path: Path = Field(default=DATA_DIR / \"image.png\")\n \n def run(self) -> ToolOutputImage:\n return tool_output_image_from_path(self.path)\n```\n\n```资料来源：[examples/multimodal_outputs.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/multimodal_outputs.py)```\n\n## 配置与调优\n\n### 模型设置与工具配合\n\n工具执行可以与模型推理策略配合使用：\n\n```python\nfrom agency_swarm import Agent, ModelSettings, Reasoning\n\nagent = Agent(\n name=\"MathAgent\",\n tools=[calculate],\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n ),\n)\n```\n\n```资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)```\n\n## 最佳实践\n\n1. **工具选择**：根据任务类型选择合适的内置工具，避免工具滥用\n2. **参数验证**：使用 Pydantic Field 的 description 为模型提供清晰的参数说明\n3. **错误处理**：实现健壮的异常捕获和错误消息返回\n4. **超时控制**：对于可能长时间运行的操作设置合理的超时时间\n5. **输出格式化**：返回结构化的输出，便于后续处理和展示\n\n## 相关资源\n\n- [工具开发指南](../development/tools.md)\n- [智能体配置](../guides/agents.md)\n- [OpenAPI Schema 转工具](./openapi-tools.md)\n- [工具测试](../testing/tools-testing.md)\n\n---\n\n\n\n## OpenAPI 工具集成\n\n### 相关页面\n\n相关主题：[自定义工具开发](#p-tools), [内置工具](#p-builtin-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/tools/tool_factory_utils/factory.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/factory.py)\n- [examples/fastapi_integration/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/fastapi_integration/README.md)\n- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n- [src/agency_swarm/tools/tool_factory_utils/openapi_exporter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/openapi_exporter.py)\n- [examples/multimodal_outputs.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/multimodal_outputs.py)\n \n\n# OpenAPI 工具集成\n\n## 概述\n\nOpenAPI 工具集成是 Agency Swarm 框架中用于将 OpenAPI 规范自动转换为可用工具的核心功能模块。该模块允许开发者通过 `ToolFactory` 类从 OpenAPI Schema 动态生成 `FunctionTool` 实例，使 AI Agent 能够调用外部 API 端点。\n\n主要功能包括：\n\n- **导入**：从 OpenAPI 3.0/3.1 规范生成工具\n- **导出**：将工具定义导出为 OpenAPI Schema\n- **适配**：支持 BaseTool 到 OpenAPI Schema 的双向转换\n\n资料来源：[factory.py:1-28](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/factory.py)\n\n## 架构设计\n\n### 核心组件\n\n```\nToolFactory\n├── openapi_importer (导入 OpenAPI Schema)\n├── openapi_exporter (导出为 OpenAPI Schema)\n├── base_tool_adapter (BaseTool 适配器)\n├── langchain (LangChain 工具转换)\n├── mcp (MCP 协议支持)\n└── file_loader (文件加载)\n```\n\nToolFactory 采用门面（Facade）模式设计，将复杂逻辑委托给专门模块处理，保持公共 API 稳定性。资料来源：[factory.py:13-27](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/factory.py)\n\n### 数据流图\n\n```mermaid\ngraph TD\n A[OpenAPI JSON/YAML] --> B[openapi_importer]\n B --> C[BaseTool / FunctionTool]\n C --> D[Agent.tools]\n D --> E[API 调用执行]\n \n F[BaseTool 实例] --> G[base_tool_adapter]\n G --> H[OpenAPI Schema]\n H --> I[openapi_exporter]\n I --> J[导出 JSON]\n```\n\n## ToolFactory API\n\n### 导入方法\n\n| 方法名 | 说明 | 参数 | 返回值 |\n|--------|------|------|--------|\n| `from_openapi_schema` | 从 OpenAPI Schema 导入工具 | `schema: dict` | `list[FunctionTool]` |\n| `from_openai_schema` | 从 OpenAI 格式 Schema 导入 | `schema: dict` | `list[FunctionTool]` |\n| `from_langchain_tools` | 批量转换 LangChain 工具 | `tools: list` | `list[FunctionTool]` |\n| `from_langchain_tool` | 转换单个 LangChain 工具 | `tool: Any` | `FunctionTool` |\n\n资料来源：[factory.py:16-23](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/factory.py)\n\n### 导出方法\n\n| 方法名 | 说明 | 参数 | 返回值 |\n|--------|------|------|--------|\n| `get_openapi_schema` | 导出为 OpenAPI 3.1.0 Schema | 无 | `dict` |\n\n资料来源：[factory.py:24](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/factory.py)\n\n### 适配方法\n\n| 方法名 | 说明 | 参数 | 返回值 |\n|--------|------|------|--------|\n| `adapt_base_tool` | 将 BaseTool 适配为 FunctionTool | `tool: BaseTool` | `FunctionTool` |\n| `from_mcp` | 从 MCP 服务器导入工具 | `server_config` | `list[FunctionTool]` |\n\n资料来源：[factory.py:25-26](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/factory.py)\n\n## 使用方法\n\n### 基础导入流程\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# 从本地文件加载\ntools = ToolFactory.from_openapi_schema(\n open(\"./openapi.json\").read(),\n)\n\n# 从 URL 加载\nimport requests\ntools = ToolFactory.from_openapi_schema(\n requests.get(\"https://api.example.com/openapi.json\").json(),\n)\n```\n\n资料来源：[README.md:1-15](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n### 在 Agent 中使用\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools import ToolFactory\n\ntools = ToolFactory.from_openapi_schema(open(\"./my-api.json\").read())\n\nceo = Agent(\n name=\"CEO\",\n description=\"API 管理代理\",\n instructions=\"使用可用工具与外部 API 交互\",\n tools=tools, # 将生成的工具注入 Agent\n)\n```\n\n### 导出 OpenAPI Schema\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# 获取当前工具的 OpenAPI Schema\nschema = ToolFactory.get_openapi_schema()\n\n# 打印或保存\nimport json\nprint(json.dumps(schema, indent=2))\n```\n\n资料来源：[examples/fastapi_integration/README.md:1-15](https://github.com/VRSEN/agency-swarm/blob/main/examples/fastapi_integration/README.md)\n\n### 验证 Schema 一致性\n\n```bash\npython print_openapi_schema.py\n```\n\n该脚本打印 FastAPI `/openapi.json` 响应和 ToolFactory Schema，便于直接对比差异。\n\n资料来源：[examples/fastapi_integration/README.md:28-35](https://github.com/VRSEN/agency-swarm/blob/main/examples/fastapi_integration/README.md)\n\n## 工具定义结构\n\n### BaseTool 示例\n\n```python\nfrom agency_swarm import BaseTool, ToolOutputImage, ToolOutputFileContent\nfrom pydantic import Field\nfrom pathlib import Path\n\nclass LoadShowcaseImage(BaseTool):\n \"\"\"返回图片作为多模态输出\"\"\"\n \n path: Path = Field(\n default=Path(\"data/image.png\"),\n description=\"要发布的图片路径\"\n )\n detail: str = Field(\n default=\"auto\",\n description=\"视觉模型详细程度\"\n )\n\n def run(self) -> ToolOutputImage:\n return tool_output_image_from_path(self.path, detail=self.detail)\n```\n\n资料来源：[examples/multimodal_outputs.py:1-50](https://github.com/VRSEN/agency-swarm/blob/main/examples/multimodal_outputs.py)\n\n### ToolOutput 类型\n\n| 类型 | 用途 | 导入来源 |\n|------|------|----------|\n| `ToolOutputImage` | 图片输出 | `agency_swarm` |\n| `ToolOutputFileContent` | 文件输出 | `agency_swarm` |\n\n## FastAPI 集成\n\n### 工具服务\n\n通过 `run_fastapi(tools=[MyTool])` 可以自动暴露工具端点：\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/tool/` | POST | 执行工具并验证 |\n| `/openapi.json` | GET | OpenAPI 3.1.0 Schema |\n| `/docs` | GET | Swagger UI |\n| `/redoc` | GET | ReDoc 文档 |\n\n所有 Schema 包含嵌套的 Pydantic 模型，可直接连接到 Agencii.ai 等平台。\n\n资料来源：[examples/fastapi_integration/README.md:10-20](https://github.com/VRSEN/agency-swarm/blob/main/examples/fastapi_integration/README.md)\n\n### 完整示例\n\n```python\nfrom agency_swarm import Agency, Agent\nfrom agency_swarm.integrations.fastapi import run_fastapi\nfrom agency_swarm.tools import ToolFactory\n\n# 定义 Agent\nceo = Agent(\n name=\"CEO\",\n tools=ToolFactory.from_openapi_schema(open(\"./api.json\").read()),\n)\n\nagency = Agency(ceo)\n\n# 启动 FastAPI 服务\napp = run_fastapi(\n agencies={\"my-agency\": agency},\n tools=[CustomTool], # 额外暴露的工具\n host=\"0.0.0.0\",\n port=8000,\n return_app=True,\n)\n```\n\n## 工具加载机制\n\n### 从文件夹加载\n\nAgent 可以通过 `tools_folder` 加载自定义工具：\n\n```python\nceo = Agent(\n name=\"CEO\",\n tools_folder=\"./tools\", # 加载该目录下的所有工具\n schemas_folder=\"./schemas\", # OpenAPI Schema 目录\n)\n```\n\n支持的工具类型：\n\n- `BaseTool` 子类\n- 使用 `@function_tool` 装饰器创建的 `FunctionTool`\n\n### Schema 解析\n\n```mermaid\ngraph LR\n A[schemas_folder] --> B[parse_schemas]\n B --> C[OpenAPI Tools]\n C --> D[Agent.tools]\n```\n\n## 最佳实践\n\n### 1. Schema 文件组织\n\n```\nproject/\n├── agents/\n│ └── ceo.py\n├── schemas/\n│ ├── github.yaml\n│ └── slack.json\n├── tools/\n│ └── custom_tool.py\n└── agency.py\n```\n\n### 2. 工具验证\n\n运行测试确保工具正确生成：\n\n```bash\nmake coverage\n```\n\n### 3. OpenAPI Schema 质量\n\n- 确保 Schema 包含完整的参数描述\n- 使用 `x-` 扩展字段添加额外元数据\n- 验证 Schema 可以被 ToolFactory 正确解析\n\n## 模块依赖关系\n\n```mermaid\ngraph TD\n ToolFactory --> openapi_importer\n ToolFactory --> openapi_exporter\n ToolFactory --> base_tool_adapter\n ToolFactory --> langchain\n ToolFactory --> mcp\n ToolFactory --> file_loader\n \n openapi_importer --> schema_inspector\n base_tool_adapter --> BaseTool\n BaseTool --> FunctionTool\n```\n\n## 导出 API\n\n`get_openapi_schema()` 返回符合 OpenAPI 3.1.0 规范的完整 Schema，包含：\n\n- 所有已注册工具的路径定义\n- Pydantic 模型嵌套结构\n- 完整的参数和响应定义\n\n这使得 Agency Swarm 工具可以被其他支持 OpenAPI 的系统消费。\n\n资料来源：[examples/fastapi_integration/README.md:15-20](https://github.com/VRSEN/agency-swarm/blob/main/examples/fastapi_integration/README.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：VRSEN/agency-swarm\n\n摘要：发现 23 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Chart Library tool for financial pattern analysis in agent swarms。\n\n## 1. 安装坑 · 来源证据：Chart Library tool for financial pattern analysis in agent swarms\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Chart Library tool for financial pattern analysis in agent swarms\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_736c9d770ee34419ad2476f2a973e433 | https://github.com/VRSEN/agency-swarm/issues/596 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Feature request: native advisor/executor consult flow for stronger-model escalation\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: native advisor/executor consult flow for stronger-model escalation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1b01977e66ac46caa8a8b860da5bdafe | https://github.com/VRSEN/agency-swarm/issues/598 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Proposal: ClawMem adapter for thread persistence across sessions\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: ClawMem adapter for thread persistence across sessions\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3bb24559ba48467ab0c8d43d3069d7f1 | https://github.com/VRSEN/agency-swarm/issues/594 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：CI-level governance checks for swarm agent code\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：CI-level governance checks for swarm agent code\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b995c0dfb8a5460caa7cfde16ac1c7a4 | https://github.com/VRSEN/agency-swarm/issues/593 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：Feature: Runtime governance and compliance audit trails\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature: Runtime governance and compliance audit trails\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bd751455da0479bb37a014ef50934dd | https://github.com/VRSEN/agency-swarm/issues/592 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.9.0 - Agent Swarm TUI and OpenClaw\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.9.0 - Agent Swarm TUI and OpenClaw\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_445071ada1ba4d558d4ebea6ec395364 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 来源证据：v1.8.0 — Present and Accounted For\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.0 — Present and Accounted For\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d270ab8e87c945878e308b78a2c8e7e6 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.8.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 配置坑 · 来源证据：v1.9.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.9.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e69c962dcc44fd5a160047df0f18192 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：v1.9.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.9.5\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ec6832c5bd7b4083b4dd1a68c50f666f | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.5 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 能力坑 · 能力判断依赖假设\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:719367294 | https://github.com/VRSEN/agency-swarm | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 来源证据：Research finding: Error detection failure rate in multi-agent chains — empirical data\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Research finding: Error detection failure rate in multi-agent chains — empirical data\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8ef6210eff50485ba327057aa93e59d8 | https://github.com/VRSEN/agency-swarm/issues/609 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 维护坑 · 来源证据：v1.9.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.9.4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_333f10fed5354907b99a35bb5cba22a4 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在安全注意事项\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:719367294 | https://github.com/VRSEN/agency-swarm | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 来源证据：Enforceable agency chart — cryptographic delegation per agent role in the hierarchy\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Enforceable agency chart — cryptographic delegation per agent role in the hierarchy\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ca5d1cf8ec54c2083ed88c2adc8554f | https://github.com/VRSEN/agency-swarm/issues/595 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Feature: Agent trust and discovery via MoltBridge integration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: Agent trust and discovery via MoltBridge integration\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66c9e8a0b624449c8c4292c01efc6d0c | https://github.com/VRSEN/agency-swarm/issues/528 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.9.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_952f33aba33c45debdfbfe4422b8789c | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v1.9.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.3\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9290fb1e7b174e4a9fe0704355613635 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 21. 安全/权限坑 · 来源证据：v1.9.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.7\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8e9071bb39904407bc7514f299c9374d | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.7 | 来源类型 github_release 暴露的待验证使用条件。\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:719367294 | https://github.com/VRSEN/agency-swarm | 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:719367294 | https://github.com/VRSEN/agency-swarm | release_recency=unknown\n\n\n",
"markdown_key": "agency-swarm",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:719367294",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/VRSEN/agency-swarm"
},
{
"evidence_id": "art_82ba78e7fbe246c4a31383d0fd696d7b",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/VRSEN/agency-swarm#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "agency-swarm 说明书",
"toc": [
"https://github.com/VRSEN/agency-swarm 项目说明书",
"目录",
"Agency Swarm 简介",
"核心概念",
"工具系统",
"通信与交互",
"用户界面",
"模型配置",
"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": "32bca5e4d69c8781d6d3dbd697d4231863c9564b",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"package.json",
"README.md",
"uv.lock",
"docs/openapi.json",
"docs/docs.json",
"docs/analise_docs.py",
"docs/faq.mdx",
"docs/migration/guide.mdx",
"docs/platform/additional-instructions.mdx",
"docs/platform/pricing.mdx",
"docs/platform/how-credits-work.mdx",
"docs/platform/overview.mdx",
"docs/contributing/contributing.mdx",
"docs/additional-features/azure-openai.mdx",
"docs/additional-features/agency-context.mdx",
"docs/additional-features/few-shot-examples.mdx",
"docs/additional-features/mcp-tools-server.mdx",
"docs/additional-features/deployment-to-production.mdx",
"docs/additional-features/third-party-models.mdx",
"docs/additional-features/observability.mdx",
"docs/additional-features/fastapi-integration.mdx",
"docs/additional-features/streaming.mdx",
"docs/extras/extras.mdx",
"docs/tutorials/tutorials.mdx",
"docs/welcome/ai-agency-vs-other-frameworks.mdx",
"docs/welcome/installation.mdx",
"docs/welcome/overview.mdx",
"docs/references/api.mdx",
"docs/platform/marketplace/openclaw.mdx",
"docs/platform/marketplace/onboarding.mdx",
"docs/platform/integrations/openclaw-integration.mdx",
"docs/platform/integrations/zapier-integration.mdx",
"docs/platform/integrations/widget.mdx",
"docs/platform/integrations/whatsapp-integration.mdx",
"docs/platform/integrations/web-api.mdx",
"docs/platform/integrations/n8n-integration.mdx",
"docs/platform/integrations/slack-integration.mdx",
"docs/core-framework/tools/built-in-tools.mdx",
"docs/core-framework/tools/openapi-schemas.mdx"
],
"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": "# agency-swarm-agent-generator - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 agency-swarm-agent-generator 编译的 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- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.codex/skills/claude-cli-review/SKILL.md`, `.codex/skills/codex-cli-review/SKILL.md`, `.codex/skills/delegation-management/SKILL.md`, `.codex/skills/policy-maintenance/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.codex/skills/claude-cli-review/SKILL.md`, `.codex/skills/codex-cli-review/SKILL.md`, `.codex/skills/delegation-management/SKILL.md`, `.codex/skills/policy-maintenance/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install -U agency-swarm` 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.codex/skills/claude-cli-review/SKILL.md`, `.codex/skills/codex-cli-review/SKILL.md`, `.codex/skills/delegation-management/SKILL.md`, `.codex/skills/policy-maintenance/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.codex/skills/claude-cli-review/SKILL.md`, `.codex/skills/codex-cli-review/SKILL.md`, `.codex/skills/delegation-management/SKILL.md`, `.codex/skills/policy-maintenance/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_0005` 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 的默认行为。 证据：`.codex/skills/claude-cli-review/SKILL.md`, `.codex/skills/codex-cli-review/SKILL.md`, `.codex/skills/delegation-management/SKILL.md`, `.codex/skills/policy-maintenance/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 后续工作方式，可能和用户已有规则冲突。 证据：`.codex/skills/claude-cli-review/SKILL.md`, `.codex/skills/codex-cli-review/SKILL.md`, `.codex/skills/delegation-management/SKILL.md`, `.codex/skills/policy-maintenance/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`.claude/agents/agent-creator.md`, `.claude/agents/api-researcher.md`, `.claude/agents/prd-creator.md`, `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- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\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_0006` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0007` 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 体验。 证据：`.codex/skills/claude-cli-review/SKILL.md`, `.codex/skills/codex-cli-review/SKILL.md`, `.codex/skills/delegation-management/SKILL.md`, `.codex/skills/policy-maintenance/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：447\n- 重要文件覆盖：40/447\n- 证据索引条目：73\n- 角色 / Skill 条目：5\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请基于 agency-swarm-agent-generator 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 agency-swarm-agent-generator 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 agency-swarm-agent-generator 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 5 个角色 / Skill / 项目文档条目。\n\n- **claude-cli-review**（skill）：Use when Claude CLI is the chosen local review worker for a bounded diff review or extraction pass and a saved /tmp artifact is required. 激活提示：当用户任务与“claude-cli-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.codex/skills/claude-cli-review/SKILL.md`\n- **codex-cli-review**（skill）：Use when a local Codex CLI review, pull-request opening or update compliance check, pull-request comment review loop, or saved Codex review artifact is required for this repo. 激活提示：当用户任务与“codex-cli-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.codex/skills/codex-cli-review/SKILL.md`\n- **delegation-management**（skill）：Use when a manager delegates to subagents, scopes staged worker tasks, decides whether to reuse or rotate workers, or reviews delegated output before relying on it. 激活提示：当用户任务与“delegation-management”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.codex/skills/delegation-management/SKILL.md`\n- **policy-maintenance**（skill）：Use when editing AGENTS.md, CLAUDE.md, or .codex/skills/ policy, workflow, and manager-skill files. Keeps durable operating rules concise, separates general policy from manager-only policy, and requires review for distorted meaning or regressions. 激活提示：当用户任务与“policy-maintenance”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.codex/skills/policy-maintenance/SKILL.md`\n- **requirement-ledger**（skill）：Use when a task needs a durable active requirement queue and archive workflow. Captures only real user requests or requirements with proofread, sanitized requirement text, source pointers, category, intent, status, next action, and linked artifacts; avoids noisy transcript dumps without erasing user intent. 激活提示：当用户任务与“requirement-ledger”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.codex/skills/requirement-ledger/SKILL.md`\n\n## 证据索引\n\n- 共索引 73 条证据。\n\n- **Agency Swarm Claude Code Sub-Agents**（documentation）：Agency Swarm Claude Code Sub-Agents 证据：`.claude/README.md`\n- **Instruction File Contract**（documentation）：1. Definitions 1.1 Instruction File : the policy text in AGENTS.md and its Mirror Link. 1.2 Mirror Link : the symlink at CLAUDE.md that points to AGENTS.md . 1.3 User Request : any explicit user direction, issue, failure, contradiction, odd behavior, or useful clue that changes the work. 1.4 Manager : an agent with a real Native Subagent capability. 1.5 Subagent : an agent without that capability, or one acting under delegation. 1.6 Native Subagent : the built-in delegation capability. 1.7 Default Native Subagent Policy : model gpt-5.4 with high reasoning. 1.8 Mandate : the authorized action, repository, branch, artifact, and visibility boundary for the task. 1.9 Requirement Ledger : the du… 证据：`AGENTS.md`\n- **🐝 Agency Swarm**（documentation）：! Framework https://firebasestorage.googleapis.com/v0/b/vrsen-ai/o/public%2Fgithub%2FLOGO BG large bold shadow%20 1 .jpg?alt=media&token=8c681331-2a7a-4a69-b21b-3ab1f9bf1a23 证据：`README.md`\n- **Examples**（documentation）：This directory contains runnable examples demonstrating key features of Agency Swarm v1.x. 证据：`examples/README.md`\n- **Tests**（documentation）：Before running any tests, make sure you have uv installed and ideally run make sync after . 证据：`tests/README.md`\n- **FastAPI Integration Example**（documentation）：Full Guide: The canonical FastAPI documentation lives in docs/additional-features/fastapi-integration.mdx . This README only summarizes the runnable sample. 证据：`examples/fastapi_integration/README.md`\n- **Integrations Technical Reference**（documentation）：This file documents technical details for framework integrations that are too low-level for end-user deployment docs. 证据：`src/agency_swarm/integrations/README.md`\n- **Getting Started**（documentation）：This is a Next.js https://nextjs.org project bootstrapped with create-next-app https://nextjs.org/docs/app/api-reference/cli/create-next-app . 证据：`src/agency_swarm/ui/demos/copilot/README.md`\n- **Package**（package_manifest）：{ \"name\": \"agency-swarm-agent-generator\", \"version\": \"1.8.0\", \"description\": \"Generate Agency Swarm v1.x agents from settings.json files\", \"private\": true, \"devDependencies\": { \"@types/node\": \"^20.0.0\", \"typescript\": \"^5.0.0\", \"ts-node\": \"^10.9.0\" }, \"engines\": { \"node\": \" =16.0.0\" } } 证据：`package.json`\n- **Contributing to Agency Swarm**（documentation）：Contributing to Agency Swarm Each agent or tool you add to Agency Swarm will automatically be available for import by the Genesis Swarm, which will help us create an exponentially larger and smarter system. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"ag-ui-app\", \"version\": \"0.1.0\", \"private\": true, \"scripts\": { \"dev\": \"next dev --turbopack\", \"build\": \"next build\", \"start\": \"next start\", \"lint\": \"next lint\" }, \"dependencies\": { \"@ag-ui/client\": \"^0.0.41\", \"@ag-ui/langgraph\": \"^0.0.19\", \"@copilotkit/react-core\": \"^1.9.1\", \"@copilotkit/react-ui\": \"^1.9.1\", \"@copilotkit/runtime\": \"^1.9.1\", \"class-variance-authority\": \"^0.7.1\", \"clsx\": \"^2.1.1\", \"lucide-react\": \"^0.522.0\", \"next\": \"^15.4.7\", \"react\": \"^19.0.0\", \"react-dom\": \"^19.0.0\", \"tailwind-merge\": \"^3.3.1\" }, \"devDependencies\": { \"@tailwindcss/postcss\": \"^4\", \"@types/node\": \"^20\", \"@types/react\": \"^19\", \"@types/react-dom\": \"^19\", \"tailwindcss\": \"^4\", \"tw-animate-css\": \"^1.3.4… 证据：`src/agency_swarm/ui/demos/copilot/package.json`\n- **Claude CLI Review**（skill_instruction）：Use Claude CLI only when AGENTS.md and Tool And Model Policy allow it. Treat it as weaker evidence than GPT-5.5; managers must verify its output before final decisions. 证据：`.codex/skills/claude-cli-review/SKILL.md`\n- **Codex CLI Review**（skill_instruction）：Use this skill for local Codex review artifacts and pull-request review loops. 证据：`.codex/skills/codex-cli-review/SKILL.md`\n- **Delegation Management**（skill_instruction）：Use this skill when delegation affects correctness, queue control, review quality, or context management. 证据：`.codex/skills/delegation-management/SKILL.md`\n- **Policy Maintenance**（skill_instruction）：Use this skill for policy, workflow-rule, and repo-skill changes. Repo skills are checked-in manager instructions under .codex/skills/ ; read the relevant SKILL.md when AGENTS.md routes work to one unless the environment exposes the skill directly. 证据：`.codex/skills/policy-maintenance/SKILL.md`\n- **Requirement Ledger**（skill_instruction）：Use this skill when task state must survive beyond the current chat or when a request has several requirements that can drift. The ledger records work state; durable operating rules live in AGENTS.md or the relevant repo skill. 证据：`.codex/skills/requirement-ledger/SKILL.md`\n- **License**（source_file）：Copyright c 2023–2025 Nick Bobrowski, Arsenii Shatokhin, Artemii Shatokhin 证据：`LICENSE`\n- **Background**（documentation）：Create complete agent modules including folders, agent classes, and initial configurations for Agency Swarm v1.0.0 agencies. 证据：`.claude/agents/agent-creator.md`\n- **Background**（documentation）：Research MCP servers and APIs for Agency Swarm v1.0.0 tool implementation, strongly prioritizing MCP servers. 证据：`.claude/agents/api-researcher.md`\n- **Background**（documentation）：Write and refine Agency Swarm v1.0.0 agent instructions using prompt engineering best practices for maximum clarity and performance. 证据：`.claude/agents/instructions-writer.md`\n- **Background**（documentation）：Create Product Requirements Documents for Agency Swarm v1.0.0 agencies, optimized for parallel agent creation. 证据：`.claude/agents/prd-creator.md`\n- **Background**（documentation）：Wire agency components and test with 5 realistic queries, then provide specific improvement suggestions. 证据：`.claude/agents/qa-tester.md`\n- **Background**（documentation）：Implement production-ready Agency Swarm v1.0.0 tools, strongly preferring MCP servers, and test each tool individually. 证据：`.claude/agents/tools-creator.md`\n- **Please read this first**（documentation）：- Have you read the docs? Agency Swarm docs https://agency-swarm.ai/ - Have you searched for related issues? Others may have faced similar issues. 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Please read this first**（documentation）：- Have you read the docs? Agency Swarm docs https://agency-swarm.ai/ - Have you searched for related issues? Others may have had similar requests 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **Please read this first**（documentation）：- Have you read the docs? Agency Swarm docs https://agency-swarm.ai/ - Have you searched for related issues? Others may have had similar requests 证据：`.github/ISSUE_TEMPLATE/question.md`\n- **Summary**（documentation）：- I've added new tests if relevant - I've added/updated the relevant documentation - I've run make lint and make format - I've made sure tests pass 证据：`.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`\n- **Instructions**（documentation）：Test instructions 证据：`tests/data/files/instructions.md`\n- **Role**（documentation）：Do not do any task if you did not say to the user \"Hello, I'm John Doe, your Portfolio Manager.\" 证据：`tests/integration/fin_agency/financial_research_agency/PortfolioManager/instructions.md`\n- **Role**（documentation）：You are a professional Report Generator specialist in creating executive-ready investment reports and financial documentation. 证据：`tests/integration/fin_agency/financial_research_agency/ReportGenerator/instructions.md`\n- **Role**（documentation）：You are a specialized Risk Analyst expert in investment risk assessment and portfolio risk management. 证据：`tests/integration/fin_agency/financial_research_agency/RiskAnalyst/instructions.md`\n- **Docs**（structured_config）：{ \"$schema\": \"https://mintlify.com/docs.json\", \"theme\": \"maple\", \"name\": \"Agency Swarm\", \"colors\": { \"primary\": \" fcd53b\", \"light\": \" fcd53b\", \"dark\": \" B76E00\" }, \"favicon\": \"/images/favicon.svg\", \"navigation\": { \"tabs\": { \"tab\": \"Framework\", \"global\": { \"anchors\": { \"anchor\": \"Discord Community\", \"href\": \"https://discord.gg/cw2xBaWfFM\", \"icon\": \"discourse\" }, { \"anchor\": \"Changelog\", \"href\": \"https://github.com/VRSEN/agency-swarm/releases\", \"icon\": \"timeline\" } }, \"groups\": { \"group\": \"Welcome\", \"pages\": \"welcome/overview\", \"welcome/ai-agency-vs-other-frameworks\", { \"group\": \"Get Started\", \"icon\": \"rocket\", \"pages\": \"welcome/installation\", \"welcome/getting-started/starter-template\", \"welc… 证据：`docs/docs.json`\n- **Openapi**（structured_config）：{ \"openapi\": \"3.0.3\", \"info\": { \"title\": \"Agencii Platform API\", \"version\": \"1.0.0\", \"description\": \"Reference documentation for the Agencii Platform API. Provides endpoints allowing you to run your agents on custom backends or on other unsupported channels. ⚡ Live Postman Example: https://www.postman.com/vrsen-ai/agencii-api/overview\" }, \"servers\": { \"url\": \"https://agency-swarm-app-japboyzddq-uc.a.run.app\", \"description\": \"Production server\" } , \"components\": { \"securitySchemes\": { \"BearerAuth\": { \"type\": \"http\", \"scheme\": \"bearer\", \"bearerFormat\": \"JWT\", \"description\": \"Platform token required for authentication. Find or create one inside Profile Icon API Keys. Example: Bearer sk-agencii… 证据：`docs/openapi.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2020\", \"module\": \"commonjs\", \"lib\": \"ES2020\" , \"types\": \"node\" , \"outDir\": \"./dist\", \"rootDir\": \"./\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"resolveJsonModule\": true, \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true }, \"include\": \"src/agency swarm/cli/utils/generate-agent-from-settings.ts\" , \"exclude\": \"node modules\", \"dist\" } 证据：`tsconfig.json`\n- **Model Prices And Context Window**（structured_config）：{ \"sample spec\": { \"code interpreter cost per session\": 0.0, \"computer use input cost per 1k tokens\": 0.0, \"computer use output cost per 1k tokens\": 0.0, \"deprecation date\": \"date when the model becomes deprecated in the format YYYY-MM-DD\", \"file search cost per 1k calls\": 0.0, \"file search cost per gb per day\": 0.0, \"input cost per audio token\": 0.0, \"input cost per token\": 0.0, \"litellm provider\": \"one of https://docs.litellm.ai/docs/providers\", \"max input tokens\": \"max input tokens, if the provider specifies it. if not default to max tokens\", \"max output tokens\": \"max output tokens, if the provider specifies it. if not default to max tokens\", \"max tokens\": \"LEGACY parameter. set to max o… 证据：`src/agency_swarm/data/model_prices_and_context_window.json`\n- **Components**（structured_config）：{ \"$schema\": \"https://ui.shadcn.com/schema.json\", \"style\": \"new-york\", \"rsc\": true, \"tsx\": true, \"tailwind\": { \"config\": \"\", \"css\": \"app/globals.css\", \"baseColor\": \"neutral\", \"cssVariables\": true, \"prefix\": \"\" }, \"aliases\": { \"components\": \"@/components\", \"utils\": \"@/lib/utils\", \"ui\": \"@/components/ui\", \"lib\": \"@/lib\", \"hooks\": \"@/hooks\" }, \"iconLibrary\": \"lucide\" } 证据：`src/agency_swarm/ui/demos/copilot/components.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2017\", \"lib\": \"dom\", \"dom.iterable\", \"esnext\" , \"allowJs\": true, \"skipLibCheck\": true, \"strict\": true, \"noEmit\": true, \"esModuleInterop\": true, \"module\": \"esnext\", \"moduleResolution\": \"bundler\", \"resolveJsonModule\": true, \"isolatedModules\": true, \"jsx\": \"preserve\", \"incremental\": true, \"plugins\": { \"name\": \"next\" } , \"paths\": { \"@/ \": \"./ \" } }, \"include\": \"next-env.d.ts\", \" / .ts\", \" / .tsx\", \".next/types/ / .ts\" , \"exclude\": \"node modules\" } 证据：`src/agency_swarm/ui/demos/copilot/tsconfig.json`\n- **Generated Data**（structured_config）：{\"C72aUUla9W\": \"GFp2jqKZlBCJpwANZlHZBK4KxtAUQSL22PlnKil17U4DY1OzAP\", \"fIZ5sGdtDr\": \"G9rfk7kn7Np7ZzObJr2SWidOE1seJH0KanyGsZSt7x934gnfb0\", \"CCp7UfWbxS\": \"dtkYHMLwwyxyVvayZanPM0wOE9GopivwF76XTwA1OHpDbgxNQX\", \"rFNe0bCaGk\": \"lUMKCptIzFVdxyPTLYYPEZnnGSE6ZAXxOykKYRV5N6QJejjzpQ\", \"BYx7YYou1O\": \"B20YUQemcd6KDxJ8Ro40hvcHT2KXHEjrtE33kv1W66ZtVrco3C\", \"C3bgGJNfjR\": \"jkTQ5gBwjVWExA1jJ6LE8BDLcK6TzMJLjYhhT21lS1S6wxrQ5T\", \"lQD4SCdbah\": \"e2in1CsSWSU5OMZTVQdzSQdO23t7R8Ryr8FRYOkwsF5EdOijeq\", \"6OgrE4BG3U\": \"tFtK2jgIyAkHWoEcL7rIJwN0VYCczXxffOZo3GZ4oCuO8xkOE0\", \"nXUBzCFTiI\": \"3RNTzGe1pMghXowbMA4JAstYmWFv1x9brH6INXETkEQytbGZTs\", \"bJWlwCyjpX\": \"tAlXIOztQtP98jK10t4oPhHws66rbSHTAng7itXOYcuImeoCRp\", \"osOVD3sm8D\": \"44p… 证据：`tests/data/files/generated_data.json`\n- **Pastebin**（structured_config）：{ \"openapi\": \"3.1.0\", \"info\": { \"title\": \"Pastebin API\", \"description\": \"Create pastes programmatically.\", \"version\": \"v1.0.0\" }, \"servers\": { \"url\": \"https://pastebin.example.com\" } , \"paths\": { \"/pastes\": { \"post\": { \"operationId\": \"createPaste\", \"summary\": \"Create a new paste entry\", \"requestBody\": { \"required\": true, \"content\": { \"application/json\": { \"schema\": { \"type\": \"object\", \"properties\": { \"title\": { \"type\": \"string\" }, \"content\": { \"type\": \"string\" }, \"visibility\": { \"type\": \"string\", \"enum\": \"public\", \"unlisted\", \"private\" } }, \"required\": \"title\", \"content\", \"visibility\" } } } }, \"description\": \"Create a new paste entry\" } } } } 证据：`tests/data/schemas/pastebin.json`\n- **macOS Files**（source_file）：Byte-compiled / optimized / DLL files pycache / / pycache / .py cod $py.class 证据：`.gitignore`\n- **.Pre Commit Config**（source_file）：repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v6.0.0 hooks: - id: trailing-whitespace exclude: ^docs/ - id: end-of-file-fixer exclude: ^docs/ - id: check-yaml - id: check-toml - id: debug-statements language version: python3 证据：`.pre-commit-config.yaml`\n- **.prettierignore**（source_file）：.mdx .md 证据：`.prettierignore`\n- **.prettierrc**（source_file）：{ \"tabWidth\": 4, \"overrides\": { \"files\": \" .yml\", \"options\": { \"tabWidth\": 2 } } } 证据：`.prettierrc`\n- **Makefile**（source_file）：.PHONY: sync sync: uv sync --all-extras --dev 证据：`Makefile`\n- **docs/.prettierrc**（source_file）：{ \"semi\": true, \"singleQuote\": false, \"tabWidth\": 2, \"printWidth\": 120, \"bracketSpacing\": true, \"arrowParens\": \"always\", \"trailingComma\": \"none\" } 证据：`docs/.prettierrc`\n- **Replace dot access with whitespace if detected**（source_file）：import pandas as pd import textstat 证据：`docs/analise_docs.py`\n- **Then, pass these callbacks during your agency initialization to resume conversations:**（source_file）：Set your API key in your code: Or use a .env file: Then load it with: 证据：`docs/faq.mdx`\n- **Make the examples directory into a package to avoid top-level module name collisions.**（source_file）：Make the examples directory into a package to avoid top-level module name collisions. This is needed so that mypy treats files like examples/customer service/main.py and examples/researcher app/main.py as distinct modules rather than both named \"main\". 证据：`examples/__init__.py`\n- **Path setup for standalone examples**（source_file）：Simple demonstration of sharing data between agents using agency context. Shows how one agent can store data and another can retrieve it. \"\"\" 证据：`examples/agency_context.py`\n- **!/usr/bin/env python3**（source_file）：!/usr/bin/env python3 \"\"\" Agency Swarm Visualization Demo 证据：`examples/agency_visualization.py`\n- **Path setup for standalone examples**（source_file）：This example demonstrates how to enable file search capabilities for an agent by attaching a file storage with automatic vector store processing. 证据：`examples/agent_file_storage.py`\n- **How to get Google OAuth token:**（source_file）：\"\"\" This example demonstrates how to use openai's connector feature with the agency swarm framework. 证据：`examples/connectors.py`\n- **In this demo, we use a simple file for simplicity, but in production**（source_file）：This example demonstrates how to persist thread data between different sessions using callback functions. \"\"\" 证据：`examples/custom_persistence.py`\n- **Path setup so the example can be run standalone**（source_file）：\"\"\" Custom SendMessage Tool with Context Example 证据：`examples/custom_send_message.py`\n- **in case Agency.get response gets a list of input items, join them into a single string**（source_file）：\"\"\"Input guardrails demo that delegates relevance decisions to a judge agent.\"\"\" 证据：`examples/guardrails_input.py`\n- **Guardrails Output**（source_file）：\"\"\"Minimal output guardrail example.\"\"\" 证据：`examples/guardrails_output.py`\n- **Path setup so the example can be run standalone**（source_file）：This example demonstrates a realistic handoff workflow using Handoff. 证据：`examples/handoffs.py`\n- **Launch the SSE MCP server**（source_file）：\"\"\" An example of running an agency with a local and a public MCP server. 证据：`examples/mcp_servers.py`\n- **examples/message attachments.py**（source_file）：examples/message attachments.py \"\"\" Message Attachments Example 证据：`examples/message_attachments.py`\n- **examples/multi agent workflow.py**（source_file）：examples/multi agent workflow.py \"\"\" Multi-Agent Collaboration Example with Validation 证据：`examples/multi_agent_workflow.py`\n- 其余 13 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`.claude/README.md`, `AGENTS.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`.claude/README.md`, `AGENTS.md`, `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- **Agency Swarm 简介**：importance `high`\n - source_paths: README.md, src/agency_swarm/__init__.py, pyproject.toml\n- **安装与配置**：importance `high`\n - source_paths: pyproject.toml, Makefile, CONTRIBUTING.md\n- **系统架构**：importance `high`\n - source_paths: src/agency_swarm/agency/core.py, src/agency_swarm/agent/core.py, src/agency_swarm/tools/base_tool.py, src/agency_swarm/messages/message_formatter.py\n- **项目目录结构**：importance `medium`\n - source_paths: src/agency_swarm, examples, docs\n- **智能体 (Agent)**：importance `high`\n - source_paths: src/agency_swarm/agent/core.py, src/agency_swarm/agent/tools.py, src/agency_swarm/agent/execution.py, src/agency_swarm/agent/file_manager.py\n- **代理组织 (Agency)**：importance `high`\n - source_paths: src/agency_swarm/agency/core.py, src/agency_swarm/agency/setup.py, src/agency_swarm/agency/helpers.py\n- **通信流程**：importance `high`\n - source_paths: src/agency_swarm/agent/agent_flow.py, src/agency_swarm/tools/send_message.py, examples/custom_send_message.py, examples/handoffs.py\n- **自定义工具开发**：importance `high`\n - source_paths: src/agency_swarm/tools/base_tool.py, src/agency_swarm/tools/tool_factory.py, src/agency_swarm/tools/function_tool_compat.py, examples/tools.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `32bca5e4d69c8781d6d3dbd697d4231863c9564b`\n- inspected_files: `pyproject.toml`, `package.json`, `README.md`, `uv.lock`, `docs/openapi.json`, `docs/docs.json`, `docs/analise_docs.py`, `docs/faq.mdx`, `docs/migration/guide.mdx`, `docs/platform/additional-instructions.mdx`, `docs/platform/pricing.mdx`, `docs/platform/how-credits-work.mdx`, `docs/platform/overview.mdx`, `docs/contributing/contributing.mdx`, `docs/additional-features/azure-openai.mdx`, `docs/additional-features/agency-context.mdx`, `docs/additional-features/few-shot-examples.mdx`, `docs/additional-features/mcp-tools-server.mdx`, `docs/additional-features/deployment-to-production.mdx`, `docs/additional-features/third-party-models.mdx`\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: 来源证据：Chart Library tool for financial pattern analysis in agent swarms\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Chart Library tool for financial pattern analysis in agent swarms\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_736c9d770ee34419ad2476f2a973e433 | https://github.com/VRSEN/agency-swarm/issues/596 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Feature request: native advisor/executor consult flow for stronger-model escalation\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: native advisor/executor consult flow for stronger-model escalation\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1b01977e66ac46caa8a8b860da5bdafe | https://github.com/VRSEN/agency-swarm/issues/598 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Proposal: ClawMem adapter for thread persistence across sessions\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: ClawMem adapter for thread persistence across sessions\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3bb24559ba48467ab0c8d43d3069d7f1 | https://github.com/VRSEN/agency-swarm/issues/594 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：CI-level governance checks for swarm agent code\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：CI-level governance checks for swarm agent code\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b995c0dfb8a5460caa7cfde16ac1c7a4 | https://github.com/VRSEN/agency-swarm/issues/593 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Feature: Runtime governance and compliance audit trails\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature: Runtime governance and compliance audit trails\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_4bd751455da0479bb37a014ef50934dd | https://github.com/VRSEN/agency-swarm/issues/592 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v1.9.0 - Agent Swarm TUI and OpenClaw\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.9.0 - Agent Swarm TUI and OpenClaw\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_445071ada1ba4d558d4ebea6ec395364 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v1.8.0 — Present and Accounted For\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.0 — Present and Accounted For\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_d270ab8e87c945878e308b78a2c8e7e6 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.8.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v1.9.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.9.2\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2e69c962dcc44fd5a160047df0f18192 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.2 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v1.9.5\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.9.5\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ec6832c5bd7b4083b4dd1a68c50f666f | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.5 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | README/documentation is current enough for a first validation pass.\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项目：VRSEN/agency-swarm\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- 来源证据：Chart Library tool for financial pattern analysis in agent swarms（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Feature request: native advisor/executor consult flow for stronger-model escalation（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Proposal: ClawMem adapter for thread persistence across sessions（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：CI-level governance checks for swarm agent code（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Feature: Runtime governance and compliance audit trails（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\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/VRSEN/agency-swarm 项目说明书\n\n生成时间：2026-05-14 00:40:55 UTC\n\n## 目录\n\n- [Agency Swarm 简介](#p-intro)\n- [安装与配置](#p-installation)\n- [系统架构](#p-architecture)\n- [项目目录结构](#p-folder-structure)\n- [智能体 (Agent)](#p-agents)\n- [代理组织 (Agency)](#p-agencies)\n- [通信流程](#p-communication-flows)\n- [自定义工具开发](#p-tools)\n- [内置工具](#p-builtin-tools)\n- [OpenAPI 工具集成](#p-openapi)\n\n\n\n## Agency Swarm 简介\n\n### 相关页面\n\n相关主题：[安装与配置](#p-installation), [系统架构](#p-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n- [examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n- [src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n- [src/agency_swarm/ui/templates/html/visualization.html](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/ui/templates/html/visualization.html)\n- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n- [examples/multimodal_outputs.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/multimodal_outputs.py)\n- [src/agency_swarm/utils/create_agent_template.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)\n- [examples/fastapi_integration/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/fastapi_integration/README.md)\n- [src/agency_swarm/integrations/fastapi_utils/endpoint_handlers.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/integrations/fastapi_utils/endpoint_handlers.py)\n \n\n# Agency Swarm 简介\n\nAgency Swarm 是一个开源的多智能体协作框架，基于 OpenAI 的 Responses API 构建。它旨在帮助开发者创建由多个 AI Agent 组成的自动化工作流，实现复杂的任务处理与协作。\n\n## 核心概念\n\n### Agent（智能体）\n\nAgent 是 Agency Swarm 的基本构建单元。每个 Agent 具有以下属性：\n\n| 属性 | 说明 |\n|------|------|\n| `name` | Agent 的唯一标识名称 |\n| `description` | Agent 的功能描述，供其他 Agent 或 LLM 理解其职责 |\n| `instructions` | Agent 的行为指令文档（支持 Markdown 文件） |\n| `tools` | Agent 可使用的工具列表 |\n| `model` | 底层使用的语言模型（默认为 `gpt-5.4`） |\n| `model_settings` | 模型参数配置（temperature、top_p、reasoning 等） |\n\nAgent 支持的功能包括：\n\n- **文件管理**：通过 `file_manager` 上传和管理文件\n- **向量存储**：支持 `FileSearch` 工具进行文件搜索\n- **工具加载**：支持从 `tools_folder` 动态加载工具\n- **OpenAPI Schema**：可从 `schemas` 文件夹解析 OpenAPI Schema 并生成工具\n- **Web 搜索**：集成 Web 搜索功能并可自定义来源过滤\n\n资料来源：[src/agency_swarm/agent/core.py:1-50]()\n\n### Agency（机构/多智能体系统）\n\nAgency 是多个 Agent 的集合体，负责管理 Agent 之间的通信与协作。Agent 之间可以通过以下方式进行通信：\n\n- **SendMessage**：直接消息传递\n- **Handoff**：任务交接（一个 Agent 将控制权转交给另一个 Agent）\n\n```python\nfrom agency_swarm import Agency, Agent, Handoff\n\nsupport = Agent(...)\nmath = Agent(...)\n\nagency = Agency(\n support,\n math,\n communication_flows=[(support, math, Handoff)],\n shared_instructions=\"共享的系统指令\"\n)\n```\n\n资料来源：[examples/interactive/tui.py:30-50]()\n\n## 工具系统\n\nAgency Swarm 提供三种工具定义方式：\n\n### 1. @function_tool 装饰器\n\n使用 Python 函数快速定义工具：\n\n```python\nfrom agency_swarm import function_tool\n\n@function_tool\ndef calculate(a: int, b: int) -> str:\n \"\"\"执行数学计算\"\"\"\n return str(a + b)\n```\n\n### 2. BaseTool 基类\n\n继承 `BaseTool` 使用 Pydantic 模型定义复杂工具：\n\n```python\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\n\nclass MyCustomTool(BaseTool):\n example_field: str = Field(\n ..., description=\"字段用途说明\"\n )\n\n def run(self):\n return f\"Result: {self.example_field}\"\n```\n\n资料来源：[README.md:50-80]()\n\n### 3. ToolFactory（OpenAPI Schema 转换）\n\n从 OpenAPI Schema 自动生成工具：\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\nwith open(\"schemas/your_schema.json\") as f:\n tools = ToolFactory.from_openapi_schema(f.read())\n```\n\n### 多模态工具输出\n\nAgency Swarm 支持工具返回多种格式的内容，包括图片和文件：\n\n```python\nfrom agency_swarm.tools.utils import tool_output_image_from_path, tool_output_file_from_url\nfrom agency_swarm import ToolOutputImage, ToolOutputFileContent\n\nclass LoadShowcaseImage(BaseTool):\n path: Path\n detail: str = \"auto\"\n\n def run(self) -> ToolOutputImage:\n return tool_output_image_from_path(self.path, detail=self.detail)\n```\n\n资料来源：[examples/multimodal_outputs.py:1-60]()\n\n## 通信与交互\n\n### 交互模式\n\n```mermaid\ngraph TD\n A[用户] -->|消息| B[Agency]\n B --> C[入口 Agent]\n C -->|SendMessage| D[目标 Agent]\n C -->|Handoff| E[交接 Agent]\n D -->|响应| C\n E -->|接管| F[新任务流程]\n F -->|结果| C\n```\n\n### 通信配置\n\n| 配置项 | 说明 |\n|--------|------|\n| `communication_flows` | 定义 Agent 之间的通信路径 |\n| `shared_instructions` | 所有 Agent 共享的指令 |\n| `name` | Agency 的显示名称 |\n\n资料来源：[examples/README.md:1-30]()\n\n## 用户界面\n\nAgency Swarm 提供多种用户界面选项：\n\n### 可视化界面\n\n提供交互式 HTML 可视化，展示 Agent 通信流程和工具关系：\n\n- **节点显示**：Agent（紫色渐变）、工具（橙色渐变）、入口点（绿色渐变）\n- **边连接**：带箭头指示通信方向\n- **缩放控制**：支持放大、缩小、适应视图\n- **统计信息**：实时显示 Agent 数量、工具数量、通信流程数\n\n```python\nagency.visualize() # 在浏览器中打开可视化界面\n```\n\n资料来源：[src/agency_swarm/ui/templates/html/visualization.html:1-80]()\n\n### 终端界面（TUI）\n\n基于 Rich 库的终端用户界面：\n\n```python\nagency.tui(show_reasoning=True) # 显示推理过程\n```\n\n特点：\n\n- 实时流式响应\n- 推理过程可视化\n- 终端内交互\n\n资料来源：[examples/interactive/tui.py:50-60]()\n\n### Copilot 界面\n\n基于 Next.js 和 CopilotKit 的 Web 界面：\n\n- 实时主题切换\n- 动态内容渲染\n- 可扩展的组件系统\n\n## 模型配置\n\n### ModelSettings 参数\n\n| 参数 | 说明 | 适用模型 |\n|------|------|----------|\n| `temperature` | 采样温度（0-2） | 非推理模型 |\n| `top_p` | Top-p 采样 | 非推理模型 |\n| `reasoning` | 推理努力级别 | 推理模型 |\n| `response_include` | 响应包含内容 | 所有模型 |\n\n### 推理模型配置\n\n```python\nfrom agency_swarm import ModelSettings, Reasoning\n\nmodel_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n)\n```\n\n注意：推理模型（如 o3、o4-mini）不支持 `temperature` 参数；非推理模型不支持 `reasoning` 参数。\n\n资料来源：[src/agency_swarm/utils/create_agent_template.py:1-50]()\n\n## FastAPI 集成\n\nAgency Swarm 提供 FastAPI 集成支持，可将 Agency 部署为 REST API 服务：\n\n### 核心端点\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/my-agency/get_response` | POST | 同步响应 |\n| `/my-agency/get_response_stream` | POST | SSE 流式响应 |\n| `/my-agency/get_metadata` | GET | Agency 结构元数据 |\n| `/openapi.json` | GET | OpenAPI 3.1.0 Schema |\n| `/docs` | GET | Swagger UI 文档 |\n\n### 服务工具\n\n```python\nfrom agency_swarm.integrations.fastapi import run_fastapi\n\napp = run_fastapi(\n agencies={\"my-agency\": create_agency},\n app_token_env=\"APP_TOKEN\",\n return_app=True,\n)\n```\n\n工具端点自动暴露：\n\n- `POST /tool/` - 执行工具并验证\n- `GET /openapi.json` - 完整的 OpenAPI Schema\n\n资料来源：[examples/fastapi_integration/README.md:1-40]()\n\n### OpenClaw 集成\n\n支持作为 OpenClaw 工作器模式运行：\n\n```python\nfrom agency_swarm.integrations.openclaw import attach_openclaw_to_fastapi\n\nattach_openclaw_to_fastapi(app)\n```\n\n## 项目结构\n\n```\nagency_swarm/\n├── agents/ # Agent 定义目录\n│ └── AgentName/\n│ ├── AgentName.py # Agent 主类\n│ ├── instructions.md # 指令文档\n│ ├── tools/ # 专用工具\n│ └── schemas/ # OpenAPI Schema\n├── tools/ # 通用工具目录\n│ └── {category}/\n├── ui/ # 用户界面组件\n│ ├── templates/\n│ └── demos/\n├── integrations/ # 第三方集成\n│ ├── fastapi/\n│ └── openclaw/\n└── utils/ # 工具函数\n```\n\n资料来源：[CONTRIBUTING.md:1-50]()\n\n## 示例与演示\n\n### 核心功能示例\n\n| 示例文件 | 演示内容 |\n|----------|----------|\n| `multi_agent_workflow.py` | 多 Agent 协作与验证模式 |\n| `agency_context.py` | Agent 间数据共享 |\n| `streaming.py` | 实时流式响应 |\n| `guardrails.py` | 输入输出防护栏 |\n| `custom_persistence.py` | 聊天历史持久化 |\n| `tools.py` | 工具模式：BaseTool 和 @function_tool |\n\n### 文件处理示例\n\n| 示例文件 | 演示内容 |\n|----------|----------|\n| `agent_file_storage.py` | 向量存储与文件搜索 |\n| `message_attachments.py` | 文件处理与附件 |\n| `web_search.py` | 领域过滤的 Web 搜索 |\n\n### 集成示例\n\n| 路径 | 演示内容 |\n|------|----------|\n| `fastapi_integration/` | FastAPI 服务与客户端 |\n| `interactive/` | TUI 和 Copilot 界面 |\n\n## 快速开始\n\n```python\nfrom agency_swarm import Agency, Agent\n\n# 定义 Agent\nsupport = Agent(\n name=\"SupportAgent\",\n description=\"处理用户请求的入口 Agent\",\n instructions=\"instructions.md\",\n tools=[WebSearchTool()],\n model=\"gpt-5.4-mini\",\n)\n\n# 创建 Agency\nagency = Agency(\n support,\n shared_instructions=\"全局共享指令\"\n)\n\n# 运行\nif __name__ == \"__main__\":\n print(agency.get_response_sync(\"你好！\"))\n```\n\n## 总结\n\nAgency Swarm 是一个功能完整的 AI Agent 协作框架，其核心优势包括：\n\n1. **简洁的 API 设计**：基于 OpenAI Responses API，入门门槛低\n2. **灵活的工具系统**：支持多种工具定义方式和 OpenAPI Schema 转换\n3. **多层次的通信**：支持消息传递和任务交接两种模式\n4. **丰富的界面选项**：可视化、TUI、Web 界面全覆盖\n5. **完善的部署支持**：FastAPI 集成、OpenAPI Schema 生成\n\n该框架适用于构建复杂的多 Agent 工作流、智能客服系统、自动化代理等应用场景。\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[Agency Swarm 简介](#p-intro), [项目目录结构](#p-folder-structure)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/VRSEN/agency-swarm/blob/main/pyproject.toml)\n- [Makefile](https://github.com/VRSEN/agency-swarm/blob/main/Makefile)\n- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n- [src/agency_swarm/utils/create_agent_template.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)\n- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n \n\n# 安装与配置\n\n## 概述\n\n本页面详细说明 Agency Swarm 项目的安装流程、依赖管理、项目初始化以及 CLI 工具的配置方法。Agency Swarm 是一个多智能体协作框架，通过定义 Agent、Tool 和通信流来实现复杂的自动化工作流程。正确的安装与配置是确保框架正常运行的前提条件。\n\n---\n\n## 环境准备\n\n### 系统要求\n\n| 要求项 | 说明 |\n|--------|------|\n| Python 版本 | 3.10+ |\n| 包管理器 | pip 或 poetry |\n| 操作系统 | macOS、Linux、Windows |\n\n### 创建虚拟环境\n\n建议使用虚拟环境隔离项目依赖，避免与其他项目产生冲突：\n\n```bash\n# 使用 venv 创建虚拟环境\npython -m venv venv\n\n# 激活虚拟环境\n# Linux/macOS\nsource venv/bin/activate\n\n# Windows\nvenv\\Scripts\\activate\n```\n\n---\n\n## 安装方式\n\n### 方式一：从源码安装（开发模式）\n\n克隆仓库后，使用 Makefile 安装开发依赖：\n\n```bash\ngit clone https://github.com/VRSEN/agency-swarm.git\ncd agency-swarm\n\n# 安装所有依赖（包括开发依赖）\nmake sync\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 方式二：通过 pip 安装\n\n```bash\npip install agency-swarm\n```\n\n### 方式三：使用 poetry 安装\n\n```bash\npoetry install\npoetry install --with dev # 包含开发依赖\n```\n\n---\n\n## 项目结构\n\n### 核心目录结构\n\n```\nagency_swarm/\n├── agents/ # Agent 定义目录\n│ └── AgentName/\n│ ├── AgentName.py # Agent 主类文件\n│ ├── __init__.py # 包初始化文件\n│ ├── instructions.md # Agent 指令文档\n│ ├── files/ # 上传文件目录\n│ ├── tools/ # 工具目录\n│ └── schemas/ # OpenAPI schemas 目录\n├── tools/ # 工具目录\n│ └── {category}/\n│ └── YourNewTool.py\n└── ...\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### Agent 目录规范\n\n每个 Agent 必须放置在 `agency_swarm/agents/` 目录下，使用 **CamelCase** 命名规范：\n\n```\nagency_swarm/agents/AgentName/\n├── files/ # 上传到 OpenAI 的文件目录\n├── tools/ # Agent 使用的工具目录\n├── schemas/ # OpenAPI schemas 目录\n├── AgentName.py # Agent 主类文件\n├── __init__.py # 包初始化文件\n└── instructions.md # Agent 指令文档\n```\n\n---\n\n## Agent 创建与配置\n\n### 创建 Agent 类\n\n使用以下模板创建新的 Agent：\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools.example import ExampleTool\n\nclass AgentName(Agent):\n def __init__(self):\n super().__init__(\n name=\"AgentName\",\n description=\"Description of the agent\",\n instructions=\"instructions.md\",\n tools=[ExampleTool],\n )\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### CLI 工具创建 Agent\n\n通过命令行工具快速创建 Agent 模板，支持以下参数：\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--name` | str | Agent 名称 | 用户输入 |\n| `--description` | str | Agent 描述 | - |\n| `--model` | str | 模型名称 | `gpt-5.4` |\n| `--reasoning` | str | 推理强度 (`low`/`medium`/`high`) | - |\n| `--temperature` | float | 温度参数 | 0.3 |\n| `--path` | str | 输出路径 | `./` |\n| `--use-txt` | bool | 使用 .txt 格式指令文件 | False |\n\n资料来源：[src/agency_swarm/utils/create_agent_template.py:1]()\n\n### 模型配置\n\n#### 非推理模型配置\n\n```python\nfrom agency_swarm import Agent, ModelSettings\nfrom agency_swarm.util import Reasoning\n\nsupport = Agent(\n name=\"SupportAgent\",\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n temperature=0.3,\n reasoning=Reasoning(effort=\"low\", summary=\"auto\")\n ),\n)\n```\n\n#### 推理模型配置\n\n对于推理模型（如 o1 系列），不支持 `temperature` 参数：\n\n```python\n# 推理模型配置示例\nmodel_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n)\n```\n\n> ⚠️ 注意：推理模型不支持 `temperature` 参数，框架会自动忽略该参数。\n\n资料来源：[src/agency_swarm/utils/create_agent_template.py:1]()\n\n---\n\n## Agency 初始化配置\n\n### 基本初始化\n\n```python\nfrom agency_swarm import Agency, Agent\n\nceo = Agent(name=\"CEO\", ...)\ndeveloper = Agent(name=\"Developer\", ...)\n\nagency = Agency(ceo, developer)\n```\n\n### 带通信流的初始化\n\n```python\nfrom agency_swarm import Agency, Agent\nfrom agency_swarm.agents import Handoff\n\nceo = Agent(name=\"CEO\", ...)\ndeveloper = Agent(name=\"Developer\", ...)\n\nagency = Agency(\n ceo,\n developer,\n communication_flows=[(ceo, developer, Handoff)]\n)\n```\n\n### 完整配置示例\n\n```python\nfrom agency_swarm import Agency, Agent\nfrom agency_swarm.agents import Handoff\nfrom agency_swarm.util import ModelSettings, Reasoning\n\ndef create_demo_agency():\n support = Agent(\n name=\"Support\",\n description=\"Handles user support requests with web search capabilities\",\n instructions=\"You are a helpful support agent.\",\n include_search_results=True,\n tools=[WebSearchTool()],\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n reasoning=Reasoning(effort=\"low\", summary=\"auto\")\n ),\n )\n\n math = Agent(\n name=\"MathAgent\",\n description=\"Handles arithmetic and calculation-heavy requests\",\n instructions=\"You are MathAgent. Use the calculate tool for arithmetic questions.\",\n tools=[calculate],\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n ),\n )\n\n return Agency(\n support,\n math,\n communication_flows=[(support, math, Handoff)],\n shared_instructions=\"Demonstrate reasoning, web search, file search, and handoffs.\",\n )\n```\n\n资料来源：[examples/interactive/tui.py:1]()\n\n---\n\n## 测试与验证\n\n### 运行测试\n\n```bash\n# 运行测试并生成覆盖率报告\nmake coverage\n```\n\n### 检查覆盖率\n\n`make coverage` 命令会输出测试覆盖率信息，请审查以确保有足够的测试覆盖。\n\n资料来源：[CONTRIBUTING.md:1]()\n\n---\n\n## 工具创建与配置\n\n### 工具目录结构\n\n```\nagency_swarm/tools/{category}/\n├── YourNewTool.py # 工具主类文件\n└── __init__.py # 包初始化文件\n```\n\n工具应放置在特定类别目录下，如 `coding`、`browsing`、`investing` 等。\n\n### 工具测试\n\n在 `agency_swarm/tests/test_tools.py` 中添加测试用例：\n\n```python\ndef test_my_tool_example():\n tool = MyCustomTool(example_field=\"test value\")\n result = tool.run()\n assert \"expected output\" in result\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n---\n\n## 快速开始流程\n\n```mermaid\ngraph TD\n A[安装依赖
make sync] --> B[创建 Agent 类]\n B --> C[定义工具和指令]\n C --> D[初始化 Agency]\n D --> E[配置通信流]\n E --> F[运行测试
make coverage]\n F --> G[启动应用]\n```\n\n---\n\n## 常见配置问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 推理模型报错 | 确保不使用 `temperature` 参数 |\n| 工具加载失败 | 检查工具文件路径是否正确 |\n| 通信流不工作 | 确认 Agent 实例和 Handoff 配置正确 |\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[智能体 (Agent)](#p-agents), [代理组织 (Agency)](#p-agencies), [自定义工具开发](#p-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n- [src/agency_swarm/agency/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agency/core.py) （基于 README.md 和 examples 中的引用）\n- [src/agency_swarm/tools/base_tool.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/base_tool.py) （基于 examples 和 README.md 中的引用）\n- [src/agency_swarm/messages/message_formatter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/message_formatter.py) （基于 examples 中的引用）\n- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n- [examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n \n\n# 系统架构\n\n## 概述\n\nAgency Swarm 是一个多智能体（Multi-Agent）协作框架，旨在构建能够协同工作的智能体（Agent）系统。该框架的核心设计理念是通过定义清晰的智能体角色、通信流程和工具集，使多个 AI 智能体能够像真实团队一样协作完成任务。\n\n该系统采用分层架构，主要包含以下核心组件：Agent（智能体）、Agency（代理机构）、Tools（工具）、Messages（消息处理）以及各类通信机制。\n\n## 核心架构组件\n\n### 1. Agent（智能体）\n\nAgent 是框架的基本构建单元，每个 Agent 代表一个具有特定角色和职责的 AI 智能体。\n\n```mermaid\ngraph LR\n A[Agent] --> B[名称与描述]\n A --> C[指令集]\n A --> D[工具集]\n A --> E[模型配置]\n A --> F[文件管理]\n A --> G[通信能力]\n```\n\n#### Agent 核心属性\n\n| 属性 | 说明 | 必填 |\n|------|------|------|\n| `name` | 智能体名称，采用 CamelCase 格式 | 是 |\n| `description` | 智能体职责描述，供其他 Agent 理解其功能 | 是 |\n| `instructions` | 指令文档路径（.md 或 .txt）或直接传入字符串 | 是 |\n| `tools` | 智能体可使用的工具列表 | 否 |\n| `model` | 使用的模型标识符（如 \"gpt-5.4-mini\"） | 否 |\n| `model_settings` | 模型配置对象 | 否 |\n| `files_folder` | 上传至 OpenAI 的文件目录 | 否 |\n| `schemas_folder` | OpenAPI schemas 目录，用于自动生成工具 | 否 |\n\n#### Agent 核心方法\n\n```python\n# Agent 初始化示例 - 资料来源：examples/interactive/tui.py\nceo = Agent(\n name=\"CeoAssistant\",\n description=\"Main support agent that assists users\",\n instructions=\"You are CeoAssistant, a helpful AI assistant.\",\n files_folder=_files(),\n include_search_results=True,\n tools=[WebSearchTool()],\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(reasoning=Reasoning(effort=\"low\", summary=\"auto\")),\n)\n```\n\n`get_response()` 方法是 Agent 的核心执行入口，处理用户与 Agent 之间以及 Agent 相互之间的交互：\n\n```python\n# 资料来源：src/agency_swarm/agent/core.py\nasync def get_response(\n self,\n message: str | list[TResponseInputItem],\n sender_name: str | None = None,\n context_override: dict[str, Any] | None = None,\n hooks_override: RunHooks | None = None,\n run_config_override: RunConfig | None = None,\n file_ids: list[str] | None = None,\n additional_instructions: str | None = None,\n agency_context: AgencyContext | None = None,\n **kwargs: Any,\n) -> RunResult:\n```\n\n### 2. Agency（代理机构）\n\nAgency 是多智能体系统的容器，负责管理智能体之间的通信流程和协作关系。\n\n```mermaid\ngraph TD\n U[用户请求] --> A[Agency]\n A --> A1[Agent 1]\n A --> A2[Agent 2]\n A --> A3[Agent N]\n A1 <-->|通信流程| A2\n A2 <-->|通信流程| A3\n A1 <-->|通信流程| A3\n```\n\n#### Agency 创建模式\n\nAgency 支持两种创建模式：简洁模式（隐式入口点）和显式模式（指定通信流程）：\n\n```python\n# 简洁模式 - 资料来源：examples/agency_visualization.py\nagency = Agency(ceo) # ceo 作为入口点\n\n# 显式模式 - 资料来源：examples/custom_send_message.py\nagency = Agency(\n coordinator,\n specialist,\n communication_flows=[\n (coordinator > specialist, SendMessageWithContext),\n (specialist > coordinator, Handoff),\n ],\n shared_instructions=\"Use key decisions to guide analysis tool selection.\",\n)\n```\n\n#### 通信流程配置\n\n| 符号 | 含义 | 用法 |\n|------|------|------|\n| `>` | 单向通信 | `(A > B)` 表示 A 可以向 B 发送消息 |\n| `< >` | 双向通信 | `(A < > B)` 表示 A 和 B 可以相互通信 |\n| `, Handoff` | 交接工具 | 指定使用 Handoff 进行消息传递 |\n\n### 3. Tools（工具系统）\n\n工具系统允许 Agent 执行特定操作，是扩展 Agent 能力的关键机制。\n\n```mermaid\ngraph TB\n T[工具系统] --> T1[BaseTool]\n T --> T2[FunctionTool]\n T --> T3[ToolFactory]\n T1 --> S1[结构化工具类]\n T2 --> D1[@function_tool 装饰器]\n T3 --> O1[OpenAPI 转换]\n```\n\n#### 工具类型\n\n**使用 @function_tool 装饰器：**\n\n```python\n# 资料来源：examples/README.md\nfrom agency_swarm.tools import function_tool\n\n@function_tool\ndef calculate(query: str) -> str:\n \"\"\"A calculator tool for arithmetic questions.\"\"\"\n return f\"Result: {query}\"\n```\n\n**使用 BaseTool 基类：**\n\n```python\n# 资料来源：README.md\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\n\nclass MyCustomTool(BaseTool):\n \"\"\"自定义工具描述，用于帮助 Agent 理解何时使用此工具。\"\"\"\n \n example_field: str = Field(\n ..., description=\"字段描述，说明其用途\"\n )\n \n def run(self):\n return \"工具操作结果\"\n```\n\n**从 OpenAPI Schema 生成工具：**\n\n```python\n# 资料来源：README.md\nfrom agency_swarm.tools import ToolFactory\n\ntools = ToolFactory.from_openapi_schema(\n openapi_schema_dict\n)\n```\n\n#### 内置工具\n\n| 工具名称 | 功能 | 资料来源 |\n|----------|------|----------|\n| `WebSearchTool` | 网页搜索功能 | examples/interactive/tui.py |\n| `FileSearchTool` | 向量存储文件搜索 | examples/README.md |\n| `IPythonInterpreter` | 代码解释执行 | CLI import-tool 命令 |\n| `Handoff` | Agent 交接通信 | examples/custom_send_message.py |\n| `SendMessage` | 发送消息通信 | examples/custom_send_message.py |\n\n### 4. Messages（消息处理）\n\n消息系统处理 Agent 之间的通信格式化与传递。\n\n```mermaid\ngraph LR\n M1[输入消息] --> MF[MessageFormatter]\n MF --> F[格式化处理]\n F --> M2[结构化消息]\n M2 --> A1[Agent]\n M2 --> A2[Agent]\n```\n\nMessageFormatter 负责消息的解析、格式化和传递，确保不同 Agent 之间能够正确理解彼此的意图。\n\n### 5. ModelSettings（模型配置）\n\n模型配置提供了细粒度的模型控制能力：\n\n```python\n# 资料来源：examples/interactive/tui.py\nfrom agency_swarm import ModelSettings, Reasoning\n\nModelSettings(\n reasoning=Reasoning(effort=\"low\", summary=\"auto\"),\n temperature=0.3,\n max_tokens=25000,\n top_p=0.9,\n)\n```\n\n#### ModelSettings 参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `temperature` | 生成随机性控制 | 0.3（非推理模型） |\n| `max_tokens` | 最大输出 token 数 | 模型默认值 |\n| `top_p` | 核采样概率 | - |\n| `reasoning` | 推理配置 | - |\n\n## 目录结构\n\n```\nagency_swarm/\n├── agency/ # Agency 核心实现\n│ └── core.py\n├── agent/ # Agent 核心实现\n│ └── core.py\n├── tools/ # 工具系统\n│ ├── base_tool.py\n│ ├── function_tool.py\n│ └── ...\n├── messages/ # 消息处理\n│ └── message_formatter.py\n├── cli/ # 命令行工具\n│ └── main.py\n├── ui/ # 用户界面\n│ ├── templates/\n│ └── demos/\n└── integrations/ # 集成功能\n └── fastapi_utils/\n```\n\n### Agent 目录结构规范\n\n```bash\nAgentName/ # 目录名采用 CamelCase\n├── files/ # 上传至 OpenAI 的文件\n├── schemas/ # OpenAPI schemas（自动转工具）\n├── tools/ # Agent 专用工具\n├── AgentName.py # 主类文件\n├── __init__.py\n└── instructions.md # 指令文档\n```\n\n## 通信机制\n\n### Agent 间通信流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as Agency\n participant Ag1 as Agent 1\n participant Ag2 as Agent 2\n \n U->>A: 请求\n A->>Ag1: 路由到入口 Agent\n Ag1->>Ag1: 执行任务\n Ag1->>Ag2: 发送消息/交接\n Ag2->>Ag2: 执行任务\n Ag2-->>Ag1: 返回结果\n Ag1-->>A: 汇总结果\n A-->>U: 最终响应\n```\n\n### 通信工具类型\n\n| 通信工具 | 用途 | 特点 |\n|----------|------|------|\n| `Handoff` | Agent 交接 | 完整上下文传递 |\n| `SendMessage` | 发送消息 | 自定义消息格式 |\n| `SendMessageWithContext` | 带上下文消息 | 附加额外上下文信息 |\n\n## 执行模式\n\n### 异步执行（推荐）\n\n```python\n# 资料来源：README.md\nimport asyncio\n\nasync def main():\n resp = await agency.get_response(\"Create a project skeleton.\")\n print(resp.final_output)\n\nasyncio.run(main())\n```\n\n### 同步执行\n\n```python\n# 资料来源：examples/README.md\nresult = agency.get_response_sync(\"What's your name?\")\n```\n\n## 模型支持\n\n框架支持多种 OpenAI 模型：\n\n| 模型类型 | 示例 | 特性 |\n|----------|------|------|\n| 标准模型 | `gpt-5.4-mini` | 支持 temperature 参数 |\n| 推理模型 | `o3`, `o4` 系列 | 不支持 temperature，支持 reasoning 配置 |\n\n```python\n# 推理模型配置示例 - 资料来源：examples/interactive/tui.py\nmodel_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n)\n```\n\n## 扩展机制\n\n### 1. 自定义工具开发\n\n工具应放置在 `agency_swarm/tools/{category}/` 目录下：\n\n```bash\nagency_swarm/tools/your-tool-category/\n├── YourNewTool.py\n└── __init__.py\n```\n\n### 2. CLI 工具导入\n\n```bash\n# 导入内置工具到项目\nagency-swarm import-tool IPythonInterpreter --destination ./tools\n```\n\n### 3. 从 Assistants API 迁移\n\n```bash\n# 从 settings.json 生成 Agent\nagency-swarm migrate-agent path_to_settings.json --output-dir ./agents\n```\n\n## 可视化功能\n\nAgency 提供可视化功能用于展示智能体通信结构：\n\n```python\n# 资料来源：examples/agency_visualization.py\nhtml_file = agency.visualize(\n output_file=\"agency.html\",\n include_tools=True,\n open_browser=True,\n)\n```\n\n生成的 HTML 页面包含：\n- 智能体节点展示\n- 通信流程箭头\n- 工具关联显示\n- 交互式缩放和拖拽\n\n## 快速开始\n\n```python\n# 1. 定义工具\nfrom agency_swarm.tools import function_tool\n\n@function_tool\ndef calculate(query: str) -> str:\n return f\"Result: {query}\"\n\n# 2. 创建 Agent\nfrom agency_swarm import Agent\n\nsupport = Agent(\n name=\"Support\",\n description=\"帮助用户解决问题\",\n instructions=\"你是客服助手。\",\n tools=[calculate],\n)\n\n# 3. 创建 Agency\nfrom agency_swarm import Agency\n\nagency = Agency(support)\n\n# 4. 执行任务\nresult = agency.get_response_sync(\"计算 345 * 18\")\n```\n\n## 总结\n\nAgency Swarm 的系统架构围绕四个核心概念构建：**Agent**（执行单元）、**Agency**（协作容器）、**Tools**（能力扩展）和 **Messages**（通信机制）。这种设计使得开发者可以灵活地构建复杂的多智能体系统，通过配置通信流程实现不同角色之间的协作，同时保持代码结构的清晰和可维护性。\n\n---\n\n\n\n## 项目目录结构\n\n### 相关页面\n\n相关主题：[系统架构](#p-architecture), [安装与配置](#p-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm)\n- [examples](https://github.com/VRSEN/agency-swarm/blob/main/examples)\n- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n- [examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n \n\n# 项目目录结构\n\n## 概述\n\nAgency Swarm 是一个多代理协作框架，其项目目录结构经过精心设计，以支持模块化、可扩展的代理系统开发。框架采用清晰的职责分离，将核心功能、工具、代理、用户界面和集成模块分别放置在独立目录中，便于开发者理解和扩展。\n\n## 顶层目录结构\n\n```\nagency-swarm/\n├── src/agency_swarm/ # 核心源代码\n├── examples/ # 可运行示例\n├── docs/ # 文档\n├── Makefile # 构建和测试任务\n├── CONTRIBUTING.md # 贡献指南\n└── README.md # 项目说明\n```\n\n## 核心模块结构\n\n`src/agency_swarm/` 是框架的核心代码库，包含以下主要模块：\n\n```\nsrc/agency_swarm/\n├── agent/ # Agent 核心类\n├── tools/ # 内置工具集\n├── util/ # 工具函数\n├── cli/ # 命令行工具\n├── ui/ # 用户界面\n├── integrations/ # 第三方集成\n└── __init__.py # 包入口\n```\n\n### Agent 核心模块\n\n`agent/` 目录包含框架的核心代理实现：\n\n| 文件 | 用途 |\n|------|------|\n| `core.py` | Agent 基类实现，包含工具加载、模式解析、文件处理等核心方法 |\n\nAgent 类提供了 `get_response()` 异步方法用于处理对话循环，支持用户与代理之间的交互以及代理到代理的通信。资料来源：[core.py:30-50]()\n\n### 工具模块\n\n`tools/` 目录采用分类组织结构，每个工具类别放置在独立子目录中：\n\n```\nagency_swarm/tools/{category}/\n├── YourNewTool.py # 工具类文件\n└── __init__.py # 模块入口\n```\n\n可用的工具类别包括但不限于：`coding`、`browsing`、`investing` 等。开发者可通过继承 `BaseTool` 或使用 `@function_tool` 装饰器创建自定义工具。资料来源：[CONTRIBUTING.md]()\n\n### 用户界面模块\n\n`ui/` 目录包含交互式界面组件：\n\n```\nsrc/agency_swarm/ui/\n├── templates/ # HTML 模板\n│ └── html/\n│ └── visualization.html # 代理可视化模板\n└── demos/ # 演示应用\n └── copilot/ # Copilot UI 演示\n```\n\n可视化功能允许用户生成交互式 HTML 页面，展示代理之间的通信流程和工具关系图。资料来源：[visualization.html]()\n\n### 命令行工具\n\n`cli/` 目录包含 TypeScript 编写的 CLI 工具，用于从配置文件生成代理代码：\n\n```\nsrc/agency_swarm/cli/\n└── utils/\n └── generate-agent-from-settings.ts # 代理生成器\n```\n\n### 集成模块\n\n`integrations/` 目录提供与外部服务的集成能力：\n\n| 集成 | 说明 |\n|------|------|\n| FastAPI | 支持流式响应的 API 服务器和客户端示例 |\n| OpenClaw | 与 OpenClaw 系统的集成，支持工作区挂载和消息传递 |\n\n## 代理项目结构\n\n当开发者使用 Agency Swarm 创建实际项目时，推荐采用以下目录结构：\n\n```\n/your-specified-path/\n│\n├── agency_manifesto.md # 代理宣言（代理系统的指导原则）\n└── AgentName/ # 代理专属目录（驼峰命名）\n ├── files/ # 上传至 OpenAI 的文件\n ├── schemas/ # OpenAPI schemas（自动转换为工具）\n ├── tools/ # 代理使用的工具\n ├── AgentName.py # 主代理类文件\n ├── __init__.py # Python 包初始化\n ├── instructions.md # 代理指令文档\n └── tools.py # 自定义工具定义\n```\n\n资料来源：[README.md]()\n\n### AgentName.py 结构示例\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools.example import ExampleTool\n\nclass AgentName(Agent):\n def __init__(self):\n super().__init__(\n name=\"AgentName\",\n description=\"Description of the agent\",\n instructions=\"./instructions.md\",\n tools=[ExampleTool],\n )\n```\n\n### 文件夹职责说明\n\n| 文件夹/文件 | 用途 |\n|------------|------|\n| `files/` | 存放需要上传至 OpenAI 的文件，可用于向量存储和文件搜索工具 |\n| `schemas/` | 存放 OpenAPI 规范文件，框架自动将其转换为可调用工具 |\n| `tools/` | 存放代理专属工具定义 |\n| `instructions.md` | 定义代理的行为准则和任务说明 |\n| `agency_manifesto.md` | 定义整个代理系统的工作原则和价值观 |\n\n## 代理通信结构\n\n代理之间的通信通过 `communication_flows` 定义，支持多种通信模式：\n\n```python\nfrom agency_swarm import Agency, Agent, Handoff, SendMessage\n\nagency = Agency(\n ceo, # 入口点代理\n specialist,\n communication_flows=[\n (ceo > specialist), # CEO 向专家发送消息\n (specialist > ceo, Handoff), # 使用 Handoff 进行交接\n ],\n)\n```\n\n### 通信流程图\n\n```mermaid\ngraph TD\n A[用户] --> B[CEO Agent]\n B --> C{任务类型}\n C -->|需要专业知识| D[Specialist Agent]\n C -->|简单任务| E[直接响应]\n D -->|Handoff| B\n D -->|SendMessage| B\n B --> A\n```\n\n## 示例目录结构\n\n`examples/` 目录包含可运行的演示代码，展示框架的核心功能：\n\n| 示例文件 | 功能说明 |\n|---------|---------|\n| `multi_agent_workflow.py` | 多代理协作与验证模式 |\n| `agency_context.py` | 代理间数据共享 |\n| `streaming.py` | 实时流式响应 |\n| `guardrails.py` | 输入输出防护 |\n| `custom_persistence.py` | 聊天历史持久化 |\n| `tools.py` | BaseTool 和 @function_tool 使用 |\n| `agent_file_storage.py` | 向量存储和文件搜索 |\n| `message_attachments.py` | 文件处理和消息附件 |\n| `web_search.py` | WebSearchTool 使用 |\n| `custom_send_message.py` | SendMessage 配置 |\n| `agency_visualization.py` | 交互式可视化 |\n\n资料来源：[examples/README.md]()\n\n### 交互式示例\n\n```\nexamples/\n├── interactive/\n│ ├── tui.py # 终端 UI 界面\n│ ├── copilot_demo.py # Copilot UI 演示\n│ └── hybrid_communication_flows.py # 混合通信流程\n└── fastapi_integration/\n ├── server.py # FastAPI 服务器\n └── client.py # 客户端示例\n```\n\n## 开发环境配置\n\n### 虚拟环境创建\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate # Windows: venv\\Scripts\\activate\n```\n\n### 依赖安装\n\n```bash\nmake sync\n```\n\n### 测试运行\n\n```bash\nmake coverage\n```\n\n## 贡献者指南中的结构要求\n\n框架对贡献的代码有明确的目录结构要求：\n\n### 工具贡献结构\n\n```\nagency_swarm/tools/your-tool-category/\n├── YourNewTool.py # 主工具类\n└── __init__.py # 导入语句\n```\n\n### 代理贡献结构\n\n```\nagency_swarm/agents/AgentName/\n├── AgentName.py # 主代理类\n├── __init__.py # 初始化文件\n├── instructions.md # 指令文档\n├── files/ # 文件目录\n├── tools/ # 工具目录\n└── schemas/ # schemas 目录\n```\n\n## 架构概览图\n\n```mermaid\ngraph TB\n subgraph \"用户层\"\n U[用户]\n end\n \n subgraph \"API 层\"\n F[FastAPI 集成]\n CLI[CLI 工具]\n end\n \n subgraph \"核心框架\"\n A[Agent 类]\n AG[Agency 类]\n C[通信流]\n end\n \n subgraph \"工具层\"\n BT[BaseTool]\n FT[FunctionTool]\n SF[Schema Factory]\n end\n \n subgraph \"基础设施\"\n FM[文件管理]\n VS[向量存储]\n end\n \n U --> F\n U --> CLI\n F --> A\n A --> AG\n AG --> C\n C --> A\n A --> BT\n A --> FT\n A --> SF\n A --> FM\n FM --> VS\n```\n\n## 总结\n\nAgency Swarm 的目录结构体现了以下设计原则：\n\n1. **模块化设计**：核心功能、工具、界面、集成各自独立\n2. **约定优于配置**：代理目录遵循固定命名和结构约定\n3. **可扩展性**：工具和代理可轻松添加至对应目录\n4. **分离关注点**：文件处理、API 通信、工具定义清晰分离\n5. **开发者友好**：示例代码和文档覆盖常见使用场景\n\n开发者应遵循上述目录结构创建新的代理和工具，以便与框架的其他部分无缝集成。\n\n---\n\n\n\n## 智能体 (Agent)\n\n### 相关页面\n\n相关主题：[代理组织 (Agency)](#p-agencies), [自定义工具开发](#p-tools), [通信流程](#p-communication-flows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n- [src/agency_swarm/agent/execution_helpers.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/execution_helpers.py)\n- [src/agency_swarm/agent/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/tools.py)\n- [src/agency_swarm/agent/file_manager.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/file_manager.py)\n- [examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n \n\n# 智能体 (Agent)\n\n## 概述\n\n智能体（Agent）是 Agency Swarm 框架的核心构建单元，代表一个具有特定角色、能力边界和行为规范的语言模型实例。每个智能体通过定义其名称、描述、指令集、可用工具及模型配置来确立其在多智能体协作系统中的职责定位。\n\nAgent 类封装了与 OpenAI API 交互的完整逻辑，支持异步消息处理、文件管理、工具调用、通信流控制等核心功能。在 Agency 架构中，智能体之间通过预定义的通信流（Communication Flows）进行消息传递和任务交接，形成协作网络来解决复杂问题。\n\n资料来源：[src/agency_swarm/agent/core.py:1-100]()\n\n## 核心架构\n\n### 类定义与继承结构\n\nAgent 类是所有自定义智能体的基类，开发者通过继承 Agent 并配置其参数来创建特定角色的智能体。框架采用组合模式管理智能体的各个功能模块，包括工具管理器、文件管理器、消息处理器等。\n\n```python\nfrom agency_swarm import Agent\n\nclass AgentName(Agent):\n def __init__(self):\n super().__init__(\n name=\"AgentName\",\n description=\"Description of the agent\",\n instructions=\"instructions.md\",\n tools=[ExampleTool],\n )\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n### 智能体目录结构\n\n遵循规范的目录结构是确保智能体正确加载和运行的前提条件。框架约定每个智能体应放置在 `agency_swarm/agents/` 目录下，并采用 CamelCase 命名规范。\n\n```\nagency_swarm/agents/AgentName/\n│\n├── AgentName/ # 智能体专属目录\n│ ├── files/ # 上传至 OpenAI 的文件目录\n│ ├── tools/ # 智能体使用的工具目录\n│ ├── schemas/ # OpenAPI 架构文件目录\n│ ├── AgentName.py # 核心智能体类文件\n│ ├── __init__.py # Python 包初始化文件\n│ └── instructions.md # 智能体指令文档\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n## 构造函数参数\n\n### 必需参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `name` | str | 智能体的唯一标识名称 |\n| `description` | str | 智能体的职责描述，用于上下文理解和任务分配 |\n| `instructions` | str | 指令文件路径或内联指令文本，定义智能体行为规范 |\n\n### 可选参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `files_folder` | str | None | 本地文件目录路径，这些文件会上传至 OpenAI |\n| `schemas_folder` | str | None | OpenAPI 架构文件夹路径，用于自动生成工具 |\n| `tools` | list | [] | 智能体可调用的工具列表 |\n| `model` | str | \"gpt-5.4\" | 使用的语言模型标识 |\n| `model_settings` | ModelSettings | None | 模型行为配置对象 |\n| `output_type` | ResponseFormat | None | 输出格式约束 |\n| `output_guardrails` | list | [] | 输出内容校验拦截器 |\n| `input_guardrails` | list | [] | 输入内容校验拦截器 |\n| `validation_attempts` | int | 1 | 输出验证失败后的重试次数 |\n\n资料来源：[src/agency_swarm/agent/core.py:1-100]()\n\n## 模型配置 (ModelSettings)\n\nModelSettings 类用于精细控制模型的行为参数，支持的配置项如下：\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `temperature` | float | 采样温度，控制输出的随机性（0.0-2.0） |\n| `top_p` | float | Nucleus 采样参数 |\n| `max_tokens` | int | 最大输出 token 数量 |\n| `reasoning` | Reasoning | 推理能力配置对象 |\n\n### 推理模型配置\n\n对于支持推理能力的模型（如 o1 系列），需使用 `Reasoning` 对象进行配置：\n\n```python\nfrom agency_swarm import Agent, ModelSettings\nfrom openai.types.responses import Reasoning\n\nagent = Agent(\n name=\"ReasoningAgent\",\n description=\"具有推理能力的智能体\",\n instructions=\"你是一个逻辑分析助手\",\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n ),\n)\n```\n\n**重要约束**：\n- 推理模型（如 o1 系列）**不支持** `temperature` 参数\n- 非推理模型**不支持** `reasoning` 参数\n\n资料来源：[src/agency_swarm/utils/create_agent_template.py:1-50]()\n\n## 核心方法\n\n### 异步响应获取\n\n`get_response()` 是智能体的核心执行方法，用于处理用户消息并获取模型响应：\n\n```python\nasync def get_response(\n self,\n message: str | list[TResponseInputItem],\n sender_name: str | None = None,\n context_override: dict[str, Any] | None = None,\n hooks_override: RunHooks | None = None,\n run_config_override: RunConfig | None = None,\n file_ids: list[str] | None = None,\n additional_instructions: str | None = None,\n agency_context: AgencyContext | None = None,\n **kwargs: Any,\n) -> RunResult:\n```\n\n该方法支持异步调用，返回 `RunResult` 对象包含完整的执行结果。同步调用可使用 `get_response_sync()` 方法。\n\n资料来源：[src/agency_swarm/agent/core.py:100-150]()\n\n### 文件上传管理\n\n`upload_file()` 方法用于将本地文件上传至 OpenAI 文件存储系统：\n\n```python\ndef upload_file(self, file_path: str, include_in_vector_store: bool = True) -> str:\n \"\"\"Upload a file using the agent's file manager.\"\"\"\n if self.file_manager:\n return self.file_manager.upload_file(file_path, include_in_vector_store)\n raise RuntimeError(f\"Agent {self.name} has no file manager configured\")\n```\n\n上传后的文件可被智能体用于上下文检索、代码解释等场景。\n\n资料来源：[src/agency_swarm/agent/core.py:150-170]()\n\n### 工具自动加载\n\n框架支持从指定文件夹自动加载工具实现：\n\n```python\ndef _load_tools_from_folder(self) -> None:\n \"\"\"Load tools defined in ``tools_folder`` and add them to the agent.\n\n Supports both ``BaseTool`` subclasses and ``FunctionTool``\n instances created via the ``@function_tool`` decorator.\n \"\"\"\n load_tools_from_folder(self)\n```\n\n支持两种工具定义方式：\n- 继承 `BaseTool` 抽象类\n- 使用 `@function_tool` 装饰器创建 FunctionTool 实例\n\n资料来源：[src/agency_swarm/agent/core.py:80-90]()\n\n### 架构文件解析\n\n`_parse_schemas()` 方法从 `schemas_folder` 目录读取 OpenAPI 架构文件并自动转换为可用工具：\n\n```python\ndef _parse_schemas(self):\n \"\"\"Parse OpenAPI schemas from the schemas folder and create tools.\"\"\"\n parse_schemas(self)\n```\n\n这一功能使智能体能够通过自然语言调用外部 API 服务。\n\n资料来源：[src/agency_swarm/agent/core.py:92-96]()\n\n## 执行上下文与钩子\n\n### 运行钩子 (RunHooks)\n\nRunHooks 允许开发者在智能体执行生命周期的关键节点注入自定义逻辑：\n\n```mermaid\ngraph TD\n A[开始执行] --> B[pre_run 钩子]\n B --> C[模型推理]\n C --> D{是否调用工具}\n D -->|是| E[工具执行]\n D -->|否| F[返回结果]\n E --> G[post_tool 钩子]\n G --> C\n F --> H[post_run 钩子]\n H --> I[返回 RunResult]\n```\n\n资料来源：[src/agency_swarm/agent/execution_helpers.py:1-50]()\n\n### 运行上下文包装器\n\n`RunContextWrapper` 提供执行上下文的统一访问接口，用于在钩子函数中访问和管理运行时状态：\n\n```python\nfrom agents import RunContextWrapper\n\n# 在钩子中使用\ndef my_hook(wrapper: RunContextWrapper, **kwargs):\n context = wrapper.context\n # 访问和修改上下文\n```\n\n资料来源：[src/agency_swarm/agent/execution_helpers.py:30-60]()\n\n## 执行结果模型\n\n`RunResult` 是智能体执行的核心返回对象，包含丰富的执行元信息：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `final_output` | Any | 最终输出内容 |\n| `new_items` | list[RunItem] | 执行过程中产生的新项目 |\n| `raw_responses` | list | 原始 API 响应 |\n| `input_guardrail_results` | list | 输入校验结果 |\n| `output_guardrail_results` | list | 输出校验结果 |\n| `tool_input_guardrail_results` | list | 工具输入校验结果 |\n| `tool_output_guardrail_results` | list | 工具输出校验结果 |\n| `context_wrapper` | RunContextWrapper | 执行上下文包装器 |\n\n资料来源：[src/agency_swarm/agent/execution_helpers.py:20-45]()\n\n## 使用示例\n\n### 基础智能体创建\n\n```python\nfrom agency_swarm import Agent, ModelSettings\n\nceo = Agent(\n name=\"CEO\",\n description=\"负责客户沟通、任务规划与管理\",\n instructions=\"你必须与其他智能体对话以确保任务完整执行\",\n files_folder=\"./files\",\n schemas_folder=\"./schemas\",\n tools=[my_custom_tool],\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n max_tokens=25000,\n ),\n)\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n### 带输出格式的智能体\n\n```python\nfrom agency_swarm import Agent\nfrom pydantic import BaseModel\n\nclass ResponseFormat(BaseModel):\n chat_name: str\n message: str\n\nagent = Agent(\n name=\"Analyzer\",\n description=\"数据分析智能体\",\n instructions=\"分析用户输入并返回结构化结果\",\n output_type=ResponseFormat,\n validation_attempts=3,\n)\n```\n\n### 协作智能体配置\n\n```python\nfrom agency_swarm import Agency, Agent, SendMessage, Handoff\n\n# 创建协调者\ncoordinator = Agent(\n name=\"Coordinator\",\n description=\"任务协调者\",\n instructions=\"你负责任务分配和结果汇总\",\n)\n\n# 创建专家\nspecialist = Agent(\n name=\"Specialist\",\n description=\"专业分析智能体\",\n tools=[analyze_costs, analyze_performance],\n)\n\n# 定义通信流\nagency = Agency(\n coordinator,\n specialist,\n communication_flows=[\n (coordinator > specialist, SendMessage),\n (specialist > coordinator, Handoff),\n ],\n)\n```\n\n资料来源：[examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n\n## 可视化\n\nAgency Swarm 提供内置的可视化功能，可生成交互式 HTML 页面展示智能体间的通信拓扑：\n\n```python\nagency = Agency(ceo, dev, qa, communication_flows=[...])\n\nhtml_file = agency.visualize(\n output_file=\"agency_interactive_demo.html\",\n include_tools=True,\n open_browser=True,\n)\n```\n\n生成的可视化页面支持：\n- 拖拽交互\n- 缩放控制\n- 工具显示/隐藏切换\n- 通信流量统计\n\n资料来源：[examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n\n## 最佳实践\n\n### 指令编写规范\n\n1. **明确角色边界**：清晰定义智能体的职责范围和决策权限\n2. **通信协议**：规定与其他智能体交互的标准格式\n3. **错误处理**：定义异常场景下的降级策略\n4. **关键约束**：使用 `CRITICAL` 标记必须遵守的行为规则\n\n```python\ninstructions=\"\"\"\n你的名称是 Coordinator agent。\n你协调分析工作。分配任务时，明确决策关注点和所需方法。\nCRITICAL: 当你收到专家回复时，必须原样包含其完整回复文本。\n不要总结、转述或遗漏任何细节。\n\"\"\"\n```\n\n### 工具设计原则\n\n- 单一职责：每个工具只完成一个明确的任务\n- 清晰的输入输出：定义明确的数据结构和返回格式\n- 错误处理：工具应捕获并妥善处理异常情况\n\n### 模型选择建议\n\n| 场景 | 推荐模型 | 配置 |\n|------|----------|------|\n| 简单任务 | gpt-5.4-mini | temperature=0.3 |\n| 复杂推理 | gpt-5.4 | temperature=0.7, max_tokens=high |\n| 精确输出 | gpt-5.4-mini | temperature=0.0, output_type=json_schema |\n\n资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n---\n\n\n\n## 代理组织 (Agency)\n\n### 相关页面\n\n相关主题：[智能体 (Agent)](#p-agents), [通信流程](#p-communication-flows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/agency/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agency/core.py)\n- [src/agency_swarm/agency/setup.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agency/setup.py)\n- [src/agency_swarm/agency/helpers.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agency/helpers.py)\n- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n- [examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n \n\n# 代理组织 (Agency)\n\n## 概述\n\nAgency 是 Agency Swarm 框架中的核心组件，负责管理和协调多个 Agent 之间的协作交互。作为多代理系统的容器，Agency 封装了代理初始化、通信流配置、消息路由和响应处理等关键功能，使开发者能够构建复杂的多代理工作流。\n\nAgency 的主要职责包括：\n\n- 管理多个 Agent 实例的生命周期\n- 定义和维护 Agent 之间的通信流程（Communication Flows）\n- 处理代理间的消息传递和上下文共享\n- 提供统一的响应接口，支持同步和异步模式\n- 支持可视化展示代理组织结构\n\n## 核心架构\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[用户/应用] --> B[Agency]\n B --> C[Entry Point Agent]\n B --> D[Secondary Agents]\n C --> E[Communication Flows]\n D --> E\n E --> F[Handoff]\n E --> G[SendMessage]\n E --> H[SendMessageWithContext]\n B --> I[Shared Instructions]\n I --> C\n I --> D\n```\n\n### 关键组件\n\n| 组件 | 说明 |\n|------|------|\n| **Agent** | 独立的代理单元，拥有自己的工具、指令和模型配置 |\n| **Communication Flows** | 定义代理之间的通信模式和所使用的通信工具 |\n| **Shared Instructions** | 所有代理共享的全局指令集 |\n| **Entry Point Agent** | 作为入口点的代理，接收初始用户请求 |\n\n## 创建代理组织\n\n### 基本语法\n\nAgency 的构造函数接受可变数量的 Agent 作为位置参数，第一个 Agent 自动成为入口点代理：\n\n```python\nfrom agency_swarm import Agency, Agent\n\n# 创建代理\nceo = Agent(name=\"CEO\", ...)\ndeveloper = Agent(name=\"Developer\", ...)\nqa = Agent(name=\"QA\", ...)\n\n# 创建代理组织\nagency = Agency(ceo, developer, qa)\n```\n\n### 完整参数配置\n\n```python\nagency = Agency(\n ceo, # 入口点代理（必需）\n developer,\n qa,\n communication_flows=[\n (ceo > developer, Handoff), # CEO 可以将任务交接给 Developer\n (developer > qa, Handoff), # Developer 可以将任务交接给 QA\n ],\n shared_instructions=\"这是代理组织的全局共享指令\",\n name=\"MyAgency\",\n)\n```\n\n## 通信流程配置\n\n### 通信流语法\n\n通信流程使用流式语法定义代理之间的交互模式：\n\n```python\n# 基本语法\n(agent_a > agent_b, ToolClass)\n\n# 多代理通信\n(agent_a < agent_b > agent_c, ToolClass)\n```\n\n### 通信工具类型\n\n| 工具类型 | 说明 | 使用场景 |\n|----------|------|----------|\n| `Handoff` | 代理交接工具，用于完全转移对话控制权 | 任务委派、职责转换 |\n| `SendMessage` | 发送消息工具，直接向目标代理发送消息 | 信息传递、请求响应 |\n| `SendMessageWithContext` | 带上下文的发送消息工具，传递额外上下文信息 | 需要传递额外数据的消息 |\n\n### 通信流示例\n\n```python\nfrom agency_swarm import Agency, Agent, Handoff, SendMessage, SendMessageWithContext\n\n# 定义代理\ncoordinator = Agent(name=\"Coordinator\", ...)\nspecialist = Agent(name=\"Specialist\", ...)\n\n# 创建代理组织并配置通信流\nagency = Agency(\n coordinator,\n specialist,\n communication_flows=[\n # Coordinator 可以向 Specialist 发送带上下文的消息\n (coordinator > specialist, SendMessageWithContext),\n # Specialist 可以将任务交接回 Coordinator\n (specialist > coordinator, Handoff),\n ],\n)\n```\n\n资料来源：[examples/custom_send_message.py:1-50]()\n\n## 共享指令\n\n`shared_instructions` 参数用于定义所有代理共享的全局指令。这些指令会在每个代理初始化时注入，确保所有代理都能访问相同的上下文信息和行为规范。\n\n```python\nagency = Agency(\n ceo,\n developer,\n shared_instructions=\"这是一个软件开发代理组织。所有代理应该遵循代码规范和最佳实践。\",\n)\n```\n\n## 响应处理\n\n### 异步获取响应\n\n```python\nimport asyncio\n\nasync def main():\n resp = await agency.get_response(\"创建一个小项目骨架\")\n print(resp.final_output)\n\nasyncio.run(main())\n```\n\n### 同步获取响应\n\n```python\n# 同步模式\nresp = agency.get_response_sync(\"创建一个小项目骨架\")\nprint(resp.final_output)\n```\n\n### 终端用户界面\n\nAgency 提供了内置的 TUI（终端用户界面）功能：\n\n```python\nagency.tui(show_reasoning=True)\n```\n\n资料来源：[examples/interactive/tui.py:1-80]()\n\n## 可视化功能\n\nAgency 支持生成交互式的可视化图表，展示代理组织的结构和通信流程：\n\n```python\nhtml_file = agency.visualize(\n output_file=\"agency_visualization.html\",\n include_tools=True,\n open_browser=True,\n)\n```\n\n可视化功能可以：\n\n- 展示所有代理及其角色\n- 显示代理之间的通信流向\n- 展示每个代理拥有的工具\n- 支持交互式拖拽和缩放\n\n资料来源：[examples/agency_visualization.py:1-60]()\n\n## 工作流程示意\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agency as Agency\n participant Entry as 入口代理\n participant Agent1 as 代理1\n participant Agent2 as 代理2\n\n User->>Agency: get_response(message)\n Agency->>Entry: 处理消息\n Entry->>Agent1: Handoff/SendMessage\n Agent1->>Agent2: Handoff/SendMessage\n Agent2-->>Agent1: 返回结果\n Agent1-->>Entry: 返回结果\n Entry-->>Agency: 最终输出\n Agency-->>User: 响应结果\n```\n\n## 完整使用示例\n\n```python\nfrom agency_swarm import Agency, Agent, Handoff, ModelSettings\n\n# 创建支持代理\nsupport = Agent(\n name=\"Support\",\n description=\"处理客户咨询和技术支持请求\",\n instructions=\"你是技术支持代理。使用搜索工具回答用户问题。\",\n tools=[WebSearchTool()],\n model=\"gpt-4o\",\n)\n\n# 数学代理\nmath = Agent(\n name=\"MathAgent\",\n description=\"处理算术和计算密集型请求\",\n instructions=\"你是数学代理。使用计算工具处理算术问题。\",\n tools=[calculate],\n model=\"gpt-4o\",\n model_settings=ModelSettings(temperature=0.7),\n)\n\n# 创建代理组织\nagency = Agency(\n support,\n math,\n communication_flows=[\n (support < math > support, Handoff),\n ],\n shared_instructions=\"演示推理、网络搜索和代理交接功能。\",\n name=\"SupportAgency\",\n)\n\n# 运行\nif __name__ == \"__main__\":\n response = agency.get_response_sync(\"帮我计算 345 * 18\")\n print(response.final_output)\n```\n\n## 最佳实践\n\n### 1. 明确的职责划分\n\n每个代理应有清晰的职责定义，通过 `description` 和 `instructions` 参数明确其角色和功能。\n\n### 2. 合理的通信流设计\n\n- 使用 Handoff 进行任务委派和职责转换\n- 使用 SendMessage 进行信息查询和响应获取\n- 避免过度复杂的通信流，保持流程清晰\n\n### 3. 共享指令的使用\n\n将所有代理需要遵守的通用规则和约束放在 `shared_instructions` 中，避免重复定义。\n\n### 4. 模型配置\n\n根据代理的具体任务类型调整模型参数，如推理强度、token 限制等：\n\n```python\nfrom agency_swarm import ModelSettings, Reasoning\n\nagent = Agent(\n name=\"Analyst\",\n model_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\"),\n ),\n)\n```\n\n## 总结\n\nAgency 作为 Agency Swarm 框架的核心组件，提供了一套完整的多代理协作解决方案。通过其灵活的通信流机制、共享指令系统和统一的响应接口，开发者可以轻松构建复杂的代理工作流，实现从简单的任务委托到复杂的多代理协作场景。\n\n---\n\n\n\n## 通信流程\n\n### 相关页面\n\n相关主题：[代理组织 (Agency)](#p-agencies), [智能体 (Agent)](#p-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/agent/agent_flow.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/agent_flow.py)\n- [src/agency_swarm/tools/send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py)\n- [examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n- [examples/handoffs.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/handoffs.py)\n- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n- [src/agency_swarm/ui/templates/html/visualization.html](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/ui/templates/html/visualization.html)\n \n\n# 通信流程\n\n## 概述\n\n通信流程（Communication Flows）是 Agency Swarm 框架中定义多代理之间如何传递消息和任务的核心理念。在 Agency Swarm 中，代理不再孤立工作，而是通过预定义的通信模式实现协作。通信流程允许开发者精确控制代理之间的消息流向、触发条件以及交接逻辑。\n\nAgency Swarm 支持两种主要的通信机制：\n\n1. **直接消息传递（SendMessage）**：代理之间点对点的消息传递\n2. **代理交接（Handoff）**：将对话控制权完全转移给另一个代理\n\n资料来源：[examples/agency_visualization.py:32-39]()\n\n## 核心概念\n\n### 代理通信架构\n\nAgency Swarm 采用星型与网状混合的通信架构。Agency 作为顶层容器管理所有代理，通过 `communication_flows` 参数定义代理间的合法通信路径。默认情况下，如果没有定义通信流程，代理只能与用户直接交互。\n\n```mermaid\ngraph TB\n subgraph Agency\n CEO[\"CEO 代理
(入口点)\"]\n Dev[\"Developer 代理\"]\n PM[\"PM 代理\"]\n QA[\"QA 代理\"]\n end\n \n CEO <-->|\"dev < CEO > PM > dev\"| Dev\n CEO <-->|\"dev < CEO > PM > dev\"| PM\n Dev <-->|\"dev > qa, Handoff\"| QA\n \n User((用户)) --> CEO\n```\n\n### 入口点代理\n\n入口点代理是用户首次交互的代理，也是消息流的起点。在 Agency 初始化时，第一个参数即为入口点代理。\n\n```python\nagency = Agency(\n ceo, # 入口点代理（位置参数）\n communication_flows=[\n (dev < ceo > pm > dev),\n (dev > qa, Handoff),\n ],\n)\n```\n\n资料来源：[examples/agency_visualization.py:30-39]()\n\n## 通信流程定义语法\n\n### 符号约定\n\nAgency Swarm 使用简洁的符号语法定义通信流程：\n\n| 符号 | 含义 | 示例 |\n|------|------|------|\n| `>` | 消息流向右侧代理 | `ceo > dev` 表示 CEO 向 Developer 发送消息 |\n| `<` | 消息流向左侧代理 | `dev < ceo` 表示 Developer 接收来自 CEO 的消息 |\n| `>>` | Handoff（完全交接） | `dev >> qa` Developer 完全交接给 QA |\n| `, Handoff` | 添加 Handoff 机制 | `(dev > qa, Handoff)` |\n\n### 流程模式\n\n#### 直接通信模式\n\n使用 `<` 和 `>` 符号定义双向消息传递：\n\n```python\n(dev < ceo > pm > dev)\n```\n\n此模式表示：\n- Developer 可以接收来自 CEO 的消息\n- PM 可以接收来自 CEO 的消息\n- Developer 可以向 PM 发送消息\n\n```mermaid\ngraph LR\n CEO -->|消息| Dev\n CEO -->|消息| PM\n Dev -->|消息| PM\n```\n\n资料来源：[examples/agency_visualization.py:35]()\n\n#### Handoff 模式\n\nHandoff 允许一个代理将对话控制权完全转移给另一个代理：\n\n```python\n(dev > qa, Handoff)\n```\n\n当 Developer 执行 Handoff 时：\n1. Developer 的对话上下文会传递给 QA\n2. QA 成为当前活跃代理\n3. 用户后续消息由 QA 处理\n\n```mermaid\ngraph TB\n Dev -->|\"Handoff\"| QA\n QA -->|\"处理后续对话\"| End[对话结束/返回]\n```\n\n资料来源：[examples/handoffs.py:1-50]()\n\n## SendMessage 工具\n\nSendMessage 是 Agency Swarm 中实现代理间通信的核心工具。每个代理都自动配备此工具，允许向其他代理发送消息。\n\n### 工具定义\n\n```python\nclass SendMessage(BaseTool):\n \"\"\"用于向其他代理发送消息的工具\"\"\"\n \n recipient_name: str = Field(\n ..., \n description=\"消息接收者的名称\"\n )\n message: str = Field(\n ..., \n description=\"要发送的消息内容\"\n )\n```\n\n### 使用示例\n\n```python\n# 在代理的指令中调用\n\"\"\"\n当需要与 Developer 协作时，请使用 SendMessage 工具。\nrecipient_name: \"Developer\"\nmessage: \"请帮我实现用户认证功能\"\n\"\"\"\n```\n\n资料来源：[src/agency_swarm/tools/send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py)\n\n## 自定义通信配置\n\n### SendMessage 配置选项\n\n通过在 Agency 初始化时传递参数，可以自定义 SendMessage 的行为：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `shared_context` | dict | None | 所有代理共享的上下文数据 |\n| `message_history` | int | 10 | 消息历史保留条数 |\n| `timeout` | int | 300 | 消息响应超时（秒） |\n\n### 自定义消息格式\n\n可以自定义发送给其他代理的消息格式：\n\n```python\nfrom agency_swarm import Agency, Agent\n\nceo = Agent(\n name=\"CEO\",\n instructions=\"你的指令\",\n)\n\ndev = Agent(\n name=\"Developer\",\n instructions=\"你的指令\",\n)\n\nagency = Agency(\n ceo,\n communication_flows=[\n (ceo > dev),\n ],\n shared_instructions=\"这是所有代理共享的指令\",\n)\n```\n\n资料来源：[examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n\n## Agent Flow 执行流程\n\n### 消息处理生命周期\n\n```mermaid\ngraph TD\n Start[用户消息] --> Receive[Agent 接收消息]\n Receive --> Check{检查通信流程}\n Check -->|允许通信| Route[路由到目标代理]\n Check -->|禁止通信| Reject[拒绝/返回错误]\n Route --> Process[目标代理处理]\n Process --> Send[发送响应]\n Send --> CheckHandoff{是否 Handoff?}\n CheckHandoff -->|是| Transfer[转移到新代理]\n CheckHandoff -->|否| Return[返回给发起者]\n Transfer --> NewAgent[新代理接管]\n NewAgent --> Continue[继续对话]\n```\n\n### 异步通信支持\n\nAgency Swarm 支持异步消息处理：\n\n```python\nimport asyncio\n\nasync def main():\n agency = create_agency()\n response = await agency.get_response(\"创建项目骨架\")\n print(response.final_output)\n\nasyncio.run(main())\n```\n\n资料来源：[README.md:150-158]()\n\n## 可视化工具\n\nAgency Swarm 提供了内置的可视化功能来展示通信流程：\n\n### 生成可视化\n\n```python\nhtml_file = agency.visualize(\n output_file=\"agency_interactive_demo.html\",\n include_tools=True,\n open_browser=True,\n)\n```\n\n### 可视化统计\n\n可视化界面显示以下统计信息：\n\n- **代理数量**：Agency 中的代理总数\n- **工具数量**：所有代理使用的工具总数\n- **通信流数量**：定义的通信流程数量\n- **入口点数量**：可作为入口的代理数量\n\n```html\n\n
Agency Statistics
\n
Agents: 0
\n
Tools: 0
\n
Communication Flows: 0
\n
Entry Points: 0
\n
\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n- [examples/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/tools.py)\n- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n- [src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n- [src/agency_swarm/integrations/README.md](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/integrations/README.md)\n \n\n# 自定义工具开发\n\n## 概述\n\nAgency Swarm 框架提供了灵活的自定义工具开发机制，允许开发者创建可被 AI Agent 调用的工具。通过自定义工具，Agent 可以执行特定的业务逻辑、访问外部 API、操作文件系统或执行计算任务。工具是 Agent 与外部世界交互的核心桥梁，使得多智能体系统能够完成复杂的工作流程。\n\n## 工具开发方式\n\nAgency Swarm 支持两种主要的工具创建方式：使用 `@function_tool` 装饰器和继承 `BaseTool` 基类。\n\n### 使用 @function_tool 装饰器\n\n`@function_tool` 装饰器是最简单的工具创建方式，适用于轻量级的工具开发。通过装饰一个普通 Python 函数，可以快速将其转换为可被 Agent 调用的工具。\n\n```python\nfrom agency_swarm.tools import function_tool\n\n@function_tool\ndef calculate(a: float, b: float) -> str:\n \"\"\"Performs arithmetic calculation on two numbers.\n \n Args:\n a: First number\n b: Second number\n \"\"\"\n return str(a + b)\n```\n\n这种方法的优势在于代码简洁、学习曲线平缓，适合实现简单的计算或数据转换逻辑。装饰器会自动处理参数解析和返回值格式化。\n\n### 使用 BaseTool 基类\n\n`BaseTool` 提供了更强大的工具开发能力，适合需要复杂验证、状态管理或多步骤执行的工具。通过继承 `BaseTool` 并实现 `run` 方法，开发者可以构建功能完整的工具。\n\n```python\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\n\nclass MyCustomTool(BaseTool):\n \"\"\"\n A brief description of what the custom tool does.\n The docstring should clearly explain the tool's purpose and functionality.\n It will be used by the agent to determine when to use this tool.\n \"\"\"\n\n example_field: str = Field(\n ..., description=\"Description of the example field, explaining its purpose and usage for the Agent.\"\n )\n\n def run(self):\n \"\"\"\n The implementation of the run method, where the tool's main functionality is executed.\n \"\"\"\n # Your custom tool logic goes here\n return f\"Result: {self.example_field}\"\n```\n\n## 工具架构\n\n### 类层次结构\n\nAgency Swarm 的工具系统采用分层架构设计：\n\n```mermaid\ngraph TD\n A[Python Function] --> B[@function_tool Decorator]\n A --> C[BaseTool Class]\n C --> D[Tool Validation]\n C --> E[Parameter Parsing]\n C --> F[run Method]\n B --> G[FunctionToolCompat]\n G --> F\n D --> H[Error Handling]\n E --> H\n```\n\n### 工具加载流程\n\n工具通过 Agent 的 `tools` 参数进行绑定，并在初始化时完成加载和验证：\n\n```mermaid\ngraph TD\n A[Agent Initialization] --> B[tools Parameter]\n B --> C[Load Tools from Folder]\n B --> D[Parse OpenAPI Schemas]\n C --> E[Tool Validation]\n D --> E\n E --> F[Register with Agent]\n F --> G[Ready for Execution]\n```\n\n## 工具目录结构\n\n按照项目贡献规范，自定义工具应放置在 `agency_swarm/tools/{category}/` 目录下：\n\n```\nagency_swarm/tools/your-tool-category/\n│\n├── YourNewTool.py # 工具主类文件\n└── __init__.py # 工具包初始化文件\n```\n\n工具类别可以包括 `coding`、`browsing`、`investing` 等，每个类别对应特定领域的工具集合。\n\n## 工具使用示例\n\n### 在 Agent 中使用工具\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools.example import ExampleTool\n\nclass AgentName(Agent):\n def __init__(self):\n super().__init__(\n name=\"AgentName\",\n description=\"Description of the agent\",\n instructions=\"./instructions.md\",\n tools=[ExampleTool],\n )\n```\n\n### 完整示例：多工具 Agent\n\n```python\nfrom agency_swarm import Agent, Agency\nfrom agency_swarm.tools import BaseTool, function_tool\nfrom pydantic import Field\n\n# 使用 BaseTool 创建自定义工具\nclass WebSearchTool(BaseTool):\n \"\"\"执行网络搜索并返回结果\"\"\"\n query: str = Field(..., description=\"搜索查询关键词\")\n \n def run(self):\n # 实现搜索逻辑\n return f\"搜索结果: {self.query}\"\n\n# 使用 function_tool 创建计算工具\n@function_tool\ndef calculate(a: float, b: float) -> str:\n \"\"\"执行算术运算\"\"\"\n return str(a + b)\n\n# 创建使用工具的 Agent\nsupport = Agent(\n name=\"SupportAgent\",\n description=\"处理用户请求并提供信息\",\n instructions=\"你是支持代理，可以搜索网络和执行计算\",\n tools=[WebSearchTool, calculate],\n model=\"gpt-5.4-mini\",\n)\n```\n\n## OpenAPI 架构转换\n\nAgency Swarm 提供了 `ToolFactory` 用于从 OpenAPI 规范自动生成工具。这一功能使得集成第三方 API 变得简单高效：\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# 从本地文件加载\nwith open(\"schemas/your_schema.json\") as f:\n tools = ToolFactory.from_openapi_schema(f.read())\n\n# 从远程 API 获取\nimport requests\ntools = ToolFactory.from_openapi_schema(\n requests.get(\"https://api.example.com/openapi.json\").json(),\n)\n```\n\n## 工具测试\n\n### 测试框架\n\n每个工具应在 `agency_swarm/tests/test_tools.py` 中添加对应的测试用例：\n\n```python\ndef test_my_tool_example():\n tool = MyCustomTool(example_field=\"test value\")\n result = tool.run()\n assert \"expected output\" in result\n```\n\n### 测试执行\n\n使用 Makefile 运行测试覆盖率：\n\n```bash\nmake coverage\n```\n\n## 配置参数\n\n### BaseTool 字段定义\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `Field(...)` | Any | 是 | 使用 Pydantic Field 定义工具参数 |\n| `description` | str | 是 | 参数描述，供 Agent 理解何时使用 |\n| `default` | Any | 否 | 参数默认值 |\n\n### Agent 工具配置\n\n| 参数 | 说明 |\n|------|------|\n| `tools` | 工具类列表或 BaseTool 实例列表 |\n| `tools_folder` | 从指定文件夹自动加载工具 |\n\n## 工具与 Agent 通信\n\nAgent 可以通过以下方式使用工具：\n\n1. **直接调用**：Agent 根据任务需求选择合适的工具\n2. **工具链**：多个工具按顺序执行完成复杂任务\n3. **条件调用**：基于上下文条件决定是否调用特定工具\n\n```mermaid\ngraph LR\n A[User Request] --> B[Agent]\n B --> C{选择工具}\n C -->|搜索| D[WebSearchTool]\n C -->|计算| E[Calculate]\n D --> F[结果]\n E --> F\n F --> G[Agent Response]\n```\n\n## 最佳实践\n\n1. **清晰的描述**：为每个工具编写清晰的文档字符串，说明其用途和使用场景\n2. **精确的参数描述**：使用 Pydantic Field 的 description 参数详细说明每个参数\n3. **错误处理**：在 `run` 方法中实现适当的错误处理和边界情况处理\n4. **返回格式**：返回易于 Agent 理解和处理的结果格式\n5. **测试覆盖**：为每个工具编写完整的测试用例\n\n## 相关资源\n\n- [工具基础类源码](../src/agency_swarm/tools/base_tool.py)\n- [工具工厂源码](../src/agency_swarm/tools/tool_factory.py)\n- [函数工具兼容性](../src/agency_swarm/tools/function_tool_compat.py)\n- [工具使用示例](../examples/tools.py)\n- [交互式示例](../examples/interactive/tui.py)\n\n---\n\n\n\n## 内置工具\n\n### 相关页面\n\n相关主题：[自定义工具开发](#p-tools), [OpenAPI 工具集成](#p-openapi)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/tools/built_in/IPythonInterpreter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/IPythonInterpreter.py)\n- [src/agency_swarm/tools/built_in/LoadFileAttachment.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/LoadFileAttachment.py)\n- [src/agency_swarm/tools/built_in/PersistentShellTool.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/PersistentShellTool.py)\n- [src/agency_swarm/tools/built_in/PresentFiles.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/PresentFiles.py)\n \n\n# 内置工具\n\n## 概述\n\nAgency Swarm 框架提供了一组内置工具（Built-in Tools），位于 `src/agency_swarm/tools/built_in/` 目录下。这些工具是预实现的、可复用的功能模块，旨在为智能体（Agent）提供常用的系统级能力，包括代码执行、文件处理和Shell命令操作。\n\n内置工具的主要特点包括：\n\n- **开箱即用**：无需额外配置即可在智能体中使用\n- **统一接口**：所有工具继承自 `BaseTool` 基类，保持接口一致性\n- **可扩展性**：开发者可以基于现有工具模式创建自定义工具\n- **工具生态**：按类别组织在 `tools/` 目录下的不同子目录中\n\n```资料来源：[examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)```\n\n## 工具架构\n\n### 工具基类\n\nAgency Swarm 中的工具主要基于两个核心组件：\n\n1. **BaseTool**：Pydantic 模型形式的工具基类，需要定义输入字段并实现 `run()` 方法\n2. **@function_tool 装饰器**：函数式工具定义方式，更轻量级\n\n所有内置工具均继承自 `BaseTool` 类，通过 Pydantic 的 `Field` 定义工具参数，并实现 `run()` 方法执行具体逻辑。\n\n```python\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\n\nclass MyCustomTool(BaseTool):\n \"\"\"工具描述文档字符串\"\"\"\n \n example_field: str = Field(\n ..., \n description=\"字段用途说明\"\n )\n \n def run(self):\n return f\"Result: {self.example_field}\"\n```\n\n```资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)```\n\n### 工具加载机制\n\n工具可以从以下来源加载到智能体：\n\n- **tools 参数**：直接在智能体初始化时传入工具类或实例列表\n- **tools_folder**：指定文件夹路径，自动加载该目录下的所有工具\n- **schemas_folder**：解析 OpenAPI schema 并自动生成工具\n\n```python\nclass AgentName(Agent):\n def __init__(self):\n super().__init__(\n name=\"AgentName\",\n description=\"Description of the agent\",\n instructions=\"instructions.md\",\n tools=[ExampleTool], # 直接传入工具\n )\n```\n\n```资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)```\n\n## 内置工具详解\n\n### PersistentShellTool\n\n**功能概述**：持久化Shell命令执行工具，允许智能体在连续会话中执行操作系统命令。\n\n**核心特性**：\n\n- **持久化状态**：维护命令执行的工作目录上下文\n- **超时保护**：默认超时时间为 5 分钟\n- **目录变更检测**：自动检测并警告目录变更情况\n- **格式化输出**：清晰展示标准输出、标准错误和返回码\n\n**输出格式**：\n\n```python\n# 成功执行示例\n**Output:**\n```\n<命令输出内容>\n```\n\n# Stderr:\n```\n<错误输出内容>\n```\n\n**Exit Code:** 0\n\n**Working Directory:** `/current/path`\n\n# 错误执行示例\n❌ Error: Command timed out after 5 minutes\n\n**Working Directory:** `/current/path`\n```\n\n**关键实现细节**：\n\n- 使用 `subprocess.Popen` 执行命令\n- 通过 `communicate()` 方法获取输出\n- 捕获 `TimeoutExpired` 异常处理超时情况\n- 跟踪 `cwd`（当前工作目录）状态\n\n```资料来源：[src/agency_swarm/tools/built_in/PersistentShellTool.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/PersistentShellTool.py)```\n\n### IPythonInterpreter\n\n**功能概述**：交互式 Python 代码解释器，用于在智能体中执行 Python 代码。\n\n**典型应用场景**：\n\n- 数据分析和计算任务\n- 原型开发和测试\n- 科学计算和可视化\n\n**使用方式**：\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools.built_in import IPythonInterpreter\n\nagent = Agent(\n name=\"CodeAgent\",\n description=\"Executes Python code\",\n tools=[IPythonInterpreter],\n)\n```\n\n### LoadFileAttachment\n\n**功能概述**：文件附件加载工具，用于读取和加载用户上传的文件内容。\n\n**主要职责**：\n\n- 从向量存储中检索相关文件\n- 解析不同格式的文件内容\n- 返回文件内容供智能体处理\n\n### PresentFiles\n\n**功能概述**：文件展示工具，用于向用户或调用方呈现文件内容。\n\n**使用场景**：\n\n- 生成报告文件\n- 导出分析结果\n- 创建可视化内容\n\n### WebSearchTool\n\n**功能概述**：网络搜索工具，支持域过滤的网页搜索并提取源URL。\n\n```python\nfrom agency_swarm.tools import WebSearchTool\n\nagent = Agent(\n name=\"SearchAgent\",\n tools=[WebSearchTool],\n # 可以在此指定搜索域过滤器\n)\n```\n\n```资料来源：[examples/web_search.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/web_search.py)```\n\n## 工具使用流程\n\n```mermaid\ngraph TD\n A[创建智能体] --> B[配置工具]\n B --> C{工具来源选择}\n C -->|直接导入| D[tools 参数传入]\n C -->|工具文件夹| E[tools_folder 配置]\n C -->|OpenAPI Schema| F[schemas_folder 配置]\n D --> G[初始化智能体]\n E --> G\n F --> G\n G --> H[运行时调用工具]\n H --> I[执行工具逻辑]\n I --> J[返回工具输出]\n J --> K[智能体处理结果]\n```\n\n## 内置工具列表\n\n| 工具名称 | 类型 | 功能描述 | 主要依赖 |\n|---------|------|---------|---------|\n| PersistentShellTool | BaseTool | 持久化Shell命令执行 | subprocess |\n| IPythonInterpreter | BaseTool | Python代码解释器 | IPython, Jedi |\n| LoadFileAttachment | BaseTool | 文件附件加载 | - |\n| PresentFiles | BaseTool | 文件内容展示 | - |\n| WebSearchTool | BaseTool | 网络搜索 | requests |\n\n## 工具导入方式\n\n### 方式一：直接导入\n\n```python\nfrom agency_swarm.tools.built_in import PersistentShellTool\nfrom agency_swarm.tools.built_in import IPythonInterpreter\n```\n\n### 方式二：导入全部内置工具\n\n```python\nfrom agency_swarm.tools.built_in import *\n```\n\n### 方式三：通过 CLI 导入到项目\n\n```bash\nagency-swarm import-tool PersistentShellTool --destination ./my_tools\n```\n\n```资料来源：[src/agency_swarm/cli/main.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/main.py)```\n\n## 工具目录结构\n\n```\nagency_swarm/tools/\n├── __init__.py\n├── built_in/\n│ ├── __init__.py\n│ ├── PersistentShellTool.py\n│ ├── IPythonInterpreter.py\n│ ├── LoadFileAttachment.py\n│ └── PresentFiles.py\n├── coding/\n│ ├── __init__.py\n│ └── ...\n├── browsing/\n│ ├── __init__.py\n│ └── ...\n└── investing/\n ├── __init__.py\n └── ...\n```\n\n每个工具目录下必须包含 `__init__.py` 文件以确保工具可被正确导入。\n\n```资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)```\n\n## 自定义工具开发\n\n开发者可以参考内置工具的实现模式创建自定义工具：\n\n### BaseTool 模式\n\n```python\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\nfrom typing import Type\n\nclass MyTool(BaseTool):\n \"\"\"自定义工具描述\"\"\"\n \n input_param: str = Field(\n ..., \n description=\"参数描述\"\n )\n \n def run(self):\n # 工具实现逻辑\n return f\"Processed: {self.input_param}\"\n \n @classmethod\n def get_schema(cls) -> dict:\n # 返回工具的JSON Schema\n return cls.model_json_schema()\n```\n\n### @function_tool 装饰器模式\n\n```python\nfrom agency_swarm.tools import function_tool\n\n@function_tool\ndef my_simple_tool(param: str) -> str:\n \"\"\"工具描述\"\"\"\n return f\"Result: {param}\"\n```\n\n```资料来源：[examples/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/tools.py)```\n\n## 工具测试\n\n为确保内置工具的稳定性，建议添加单元测试：\n\n```python\ndef test_my_tool_example():\n from agency_swarm.tools.built_in import MyCustomTool\n \n tool = MyCustomTool(example_field=\"test value\")\n result = tool.run()\n assert \"expected output\" in result\n```\n\n测试文件应位于 `agency_swarm/tests/test_tools.py`。\n\n```资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)```\n\n## 多模态工具输出\n\n内置工具还支持多模态输出，包括图片和文件：\n\n```python\nfrom agency_swarm.tools.utils import (\n tool_output_image_from_path,\n tool_output_file_from_url\n)\nfrom agency_swarm import ToolOutputImage, ToolOutputFileContent\n\nclass LoadShowcaseImage(BaseTool):\n \"\"\"返回图片作为多模态输出\"\"\"\n \n path: Path = Field(default=DATA_DIR / \"image.png\")\n \n def run(self) -> ToolOutputImage:\n return tool_output_image_from_path(self.path)\n```\n\n```资料来源：[examples/multimodal_outputs.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/multimodal_outputs.py)```\n\n## 配置与调优\n\n### 模型设置与工具配合\n\n工具执行可以与模型推理策略配合使用：\n\n```python\nfrom agency_swarm import Agent, ModelSettings, Reasoning\n\nagent = Agent(\n name=\"MathAgent\",\n tools=[calculate],\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n ),\n)\n```\n\n```资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)```\n\n## 最佳实践\n\n1. **工具选择**：根据任务类型选择合适的内置工具，避免工具滥用\n2. **参数验证**：使用 Pydantic Field 的 description 为模型提供清晰的参数说明\n3. **错误处理**：实现健壮的异常捕获和错误消息返回\n4. **超时控制**：对于可能长时间运行的操作设置合理的超时时间\n5. **输出格式化**：返回结构化的输出，便于后续处理和展示\n\n## 相关资源\n\n- [工具开发指南](../development/tools.md)\n- [智能体配置](../guides/agents.md)\n- [OpenAPI Schema 转工具](./openapi-tools.md)\n- [工具测试](../testing/tools-testing.md)\n\n---\n\n\n\n## OpenAPI 工具集成\n\n### 相关页面\n\n相关主题：[自定义工具开发](#p-tools), [内置工具](#p-builtin-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/tools/tool_factory_utils/factory.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/factory.py)\n- [examples/fastapi_integration/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/fastapi_integration/README.md)\n- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n- [src/agency_swarm/tools/tool_factory_utils/openapi_exporter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/openapi_exporter.py)\n- [examples/multimodal_outputs.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/multimodal_outputs.py)\n \n\n# OpenAPI 工具集成\n\n## 概述\n\nOpenAPI 工具集成是 Agency Swarm 框架中用于将 OpenAPI 规范自动转换为可用工具的核心功能模块。该模块允许开发者通过 `ToolFactory` 类从 OpenAPI Schema 动态生成 `FunctionTool` 实例，使 AI Agent 能够调用外部 API 端点。\n\n主要功能包括：\n\n- **导入**：从 OpenAPI 3.0/3.1 规范生成工具\n- **导出**：将工具定义导出为 OpenAPI Schema\n- **适配**：支持 BaseTool 到 OpenAPI Schema 的双向转换\n\n资料来源：[factory.py:1-28](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/factory.py)\n\n## 架构设计\n\n### 核心组件\n\n```\nToolFactory\n├── openapi_importer (导入 OpenAPI Schema)\n├── openapi_exporter (导出为 OpenAPI Schema)\n├── base_tool_adapter (BaseTool 适配器)\n├── langchain (LangChain 工具转换)\n├── mcp (MCP 协议支持)\n└── file_loader (文件加载)\n```\n\nToolFactory 采用门面（Facade）模式设计，将复杂逻辑委托给专门模块处理，保持公共 API 稳定性。资料来源：[factory.py:13-27](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/factory.py)\n\n### 数据流图\n\n```mermaid\ngraph TD\n A[OpenAPI JSON/YAML] --> B[openapi_importer]\n B --> C[BaseTool / FunctionTool]\n C --> D[Agent.tools]\n D --> E[API 调用执行]\n \n F[BaseTool 实例] --> G[base_tool_adapter]\n G --> H[OpenAPI Schema]\n H --> I[openapi_exporter]\n I --> J[导出 JSON]\n```\n\n## ToolFactory API\n\n### 导入方法\n\n| 方法名 | 说明 | 参数 | 返回值 |\n|--------|------|------|--------|\n| `from_openapi_schema` | 从 OpenAPI Schema 导入工具 | `schema: dict` | `list[FunctionTool]` |\n| `from_openai_schema` | 从 OpenAI 格式 Schema 导入 | `schema: dict` | `list[FunctionTool]` |\n| `from_langchain_tools` | 批量转换 LangChain 工具 | `tools: list` | `list[FunctionTool]` |\n| `from_langchain_tool` | 转换单个 LangChain 工具 | `tool: Any` | `FunctionTool` |\n\n资料来源：[factory.py:16-23](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/factory.py)\n\n### 导出方法\n\n| 方法名 | 说明 | 参数 | 返回值 |\n|--------|------|------|--------|\n| `get_openapi_schema` | 导出为 OpenAPI 3.1.0 Schema | 无 | `dict` |\n\n资料来源：[factory.py:24](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/factory.py)\n\n### 适配方法\n\n| 方法名 | 说明 | 参数 | 返回值 |\n|--------|------|------|--------|\n| `adapt_base_tool` | 将 BaseTool 适配为 FunctionTool | `tool: BaseTool` | `FunctionTool` |\n| `from_mcp` | 从 MCP 服务器导入工具 | `server_config` | `list[FunctionTool]` |\n\n资料来源：[factory.py:25-26](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory_utils/factory.py)\n\n## 使用方法\n\n### 基础导入流程\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# 从本地文件加载\ntools = ToolFactory.from_openapi_schema(\n open(\"./openapi.json\").read(),\n)\n\n# 从 URL 加载\nimport requests\ntools = ToolFactory.from_openapi_schema(\n requests.get(\"https://api.example.com/openapi.json\").json(),\n)\n```\n\n资料来源：[README.md:1-15](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n### 在 Agent 中使用\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools import ToolFactory\n\ntools = ToolFactory.from_openapi_schema(open(\"./my-api.json\").read())\n\nceo = Agent(\n name=\"CEO\",\n description=\"API 管理代理\",\n instructions=\"使用可用工具与外部 API 交互\",\n tools=tools, # 将生成的工具注入 Agent\n)\n```\n\n### 导出 OpenAPI Schema\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# 获取当前工具的 OpenAPI Schema\nschema = ToolFactory.get_openapi_schema()\n\n# 打印或保存\nimport json\nprint(json.dumps(schema, indent=2))\n```\n\n资料来源：[examples/fastapi_integration/README.md:1-15](https://github.com/VRSEN/agency-swarm/blob/main/examples/fastapi_integration/README.md)\n\n### 验证 Schema 一致性\n\n```bash\npython print_openapi_schema.py\n```\n\n该脚本打印 FastAPI `/openapi.json` 响应和 ToolFactory Schema，便于直接对比差异。\n\n资料来源：[examples/fastapi_integration/README.md:28-35](https://github.com/VRSEN/agency-swarm/blob/main/examples/fastapi_integration/README.md)\n\n## 工具定义结构\n\n### BaseTool 示例\n\n```python\nfrom agency_swarm import BaseTool, ToolOutputImage, ToolOutputFileContent\nfrom pydantic import Field\nfrom pathlib import Path\n\nclass LoadShowcaseImage(BaseTool):\n \"\"\"返回图片作为多模态输出\"\"\"\n \n path: Path = Field(\n default=Path(\"data/image.png\"),\n description=\"要发布的图片路径\"\n )\n detail: str = Field(\n default=\"auto\",\n description=\"视觉模型详细程度\"\n )\n\n def run(self) -> ToolOutputImage:\n return tool_output_image_from_path(self.path, detail=self.detail)\n```\n\n资料来源：[examples/multimodal_outputs.py:1-50](https://github.com/VRSEN/agency-swarm/blob/main/examples/multimodal_outputs.py)\n\n### ToolOutput 类型\n\n| 类型 | 用途 | 导入来源 |\n|------|------|----------|\n| `ToolOutputImage` | 图片输出 | `agency_swarm` |\n| `ToolOutputFileContent` | 文件输出 | `agency_swarm` |\n\n## FastAPI 集成\n\n### 工具服务\n\n通过 `run_fastapi(tools=[MyTool])` 可以自动暴露工具端点：\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/tool/` | POST | 执行工具并验证 |\n| `/openapi.json` | GET | OpenAPI 3.1.0 Schema |\n| `/docs` | GET | Swagger UI |\n| `/redoc` | GET | ReDoc 文档 |\n\n所有 Schema 包含嵌套的 Pydantic 模型，可直接连接到 Agencii.ai 等平台。\n\n资料来源：[examples/fastapi_integration/README.md:10-20](https://github.com/VRSEN/agency-swarm/blob/main/examples/fastapi_integration/README.md)\n\n### 完整示例\n\n```python\nfrom agency_swarm import Agency, Agent\nfrom agency_swarm.integrations.fastapi import run_fastapi\nfrom agency_swarm.tools import ToolFactory\n\n# 定义 Agent\nceo = Agent(\n name=\"CEO\",\n tools=ToolFactory.from_openapi_schema(open(\"./api.json\").read()),\n)\n\nagency = Agency(ceo)\n\n# 启动 FastAPI 服务\napp = run_fastapi(\n agencies={\"my-agency\": agency},\n tools=[CustomTool], # 额外暴露的工具\n host=\"0.0.0.0\",\n port=8000,\n return_app=True,\n)\n```\n\n## 工具加载机制\n\n### 从文件夹加载\n\nAgent 可以通过 `tools_folder` 加载自定义工具：\n\n```python\nceo = Agent(\n name=\"CEO\",\n tools_folder=\"./tools\", # 加载该目录下的所有工具\n schemas_folder=\"./schemas\", # OpenAPI Schema 目录\n)\n```\n\n支持的工具类型：\n\n- `BaseTool` 子类\n- 使用 `@function_tool` 装饰器创建的 `FunctionTool`\n\n### Schema 解析\n\n```mermaid\ngraph LR\n A[schemas_folder] --> B[parse_schemas]\n B --> C[OpenAPI Tools]\n C --> D[Agent.tools]\n```\n\n## 最佳实践\n\n### 1. Schema 文件组织\n\n```\nproject/\n├── agents/\n│ └── ceo.py\n├── schemas/\n│ ├── github.yaml\n│ └── slack.json\n├── tools/\n│ └── custom_tool.py\n└── agency.py\n```\n\n### 2. 工具验证\n\n运行测试确保工具正确生成：\n\n```bash\nmake coverage\n```\n\n### 3. OpenAPI Schema 质量\n\n- 确保 Schema 包含完整的参数描述\n- 使用 `x-` 扩展字段添加额外元数据\n- 验证 Schema 可以被 ToolFactory 正确解析\n\n## 模块依赖关系\n\n```mermaid\ngraph TD\n ToolFactory --> openapi_importer\n ToolFactory --> openapi_exporter\n ToolFactory --> base_tool_adapter\n ToolFactory --> langchain\n ToolFactory --> mcp\n ToolFactory --> file_loader\n \n openapi_importer --> schema_inspector\n base_tool_adapter --> BaseTool\n BaseTool --> FunctionTool\n```\n\n## 导出 API\n\n`get_openapi_schema()` 返回符合 OpenAPI 3.1.0 规范的完整 Schema，包含：\n\n- 所有已注册工具的路径定义\n- Pydantic 模型嵌套结构\n- 完整的参数和响应定义\n\n这使得 Agency Swarm 工具可以被其他支持 OpenAPI 的系统消费。\n\n资料来源：[examples/fastapi_integration/README.md:15-20](https://github.com/VRSEN/agency-swarm/blob/main/examples/fastapi_integration/README.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：VRSEN/agency-swarm\n\n摘要：发现 23 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Chart Library tool for financial pattern analysis in agent swarms。\n\n## 1. 安装坑 · 来源证据：Chart Library tool for financial pattern analysis in agent swarms\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Chart Library tool for financial pattern analysis in agent swarms\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_736c9d770ee34419ad2476f2a973e433 | https://github.com/VRSEN/agency-swarm/issues/596 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Feature request: native advisor/executor consult flow for stronger-model escalation\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: native advisor/executor consult flow for stronger-model escalation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1b01977e66ac46caa8a8b860da5bdafe | https://github.com/VRSEN/agency-swarm/issues/598 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Proposal: ClawMem adapter for thread persistence across sessions\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: ClawMem adapter for thread persistence across sessions\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3bb24559ba48467ab0c8d43d3069d7f1 | https://github.com/VRSEN/agency-swarm/issues/594 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：CI-level governance checks for swarm agent code\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：CI-level governance checks for swarm agent code\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b995c0dfb8a5460caa7cfde16ac1c7a4 | https://github.com/VRSEN/agency-swarm/issues/593 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：Feature: Runtime governance and compliance audit trails\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature: Runtime governance and compliance audit trails\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bd751455da0479bb37a014ef50934dd | https://github.com/VRSEN/agency-swarm/issues/592 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.9.0 - Agent Swarm TUI and OpenClaw\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.9.0 - Agent Swarm TUI and OpenClaw\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_445071ada1ba4d558d4ebea6ec395364 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 来源证据：v1.8.0 — Present and Accounted For\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.0 — Present and Accounted For\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d270ab8e87c945878e308b78a2c8e7e6 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.8.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 配置坑 · 来源证据：v1.9.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.9.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e69c962dcc44fd5a160047df0f18192 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：v1.9.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.9.5\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ec6832c5bd7b4083b4dd1a68c50f666f | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.5 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 能力坑 · 能力判断依赖假设\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:719367294 | https://github.com/VRSEN/agency-swarm | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 来源证据：Research finding: Error detection failure rate in multi-agent chains — empirical data\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Research finding: Error detection failure rate in multi-agent chains — empirical data\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8ef6210eff50485ba327057aa93e59d8 | https://github.com/VRSEN/agency-swarm/issues/609 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 维护坑 · 来源证据：v1.9.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.9.4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_333f10fed5354907b99a35bb5cba22a4 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在安全注意事项\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:719367294 | https://github.com/VRSEN/agency-swarm | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 来源证据：Enforceable agency chart — cryptographic delegation per agent role in the hierarchy\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Enforceable agency chart — cryptographic delegation per agent role in the hierarchy\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ca5d1cf8ec54c2083ed88c2adc8554f | https://github.com/VRSEN/agency-swarm/issues/595 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Feature: Agent trust and discovery via MoltBridge integration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: Agent trust and discovery via MoltBridge integration\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66c9e8a0b624449c8c4292c01efc6d0c | https://github.com/VRSEN/agency-swarm/issues/528 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.9.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_952f33aba33c45debdfbfe4422b8789c | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v1.9.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.3\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9290fb1e7b174e4a9fe0704355613635 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 21. 安全/权限坑 · 来源证据：v1.9.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.7\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8e9071bb39904407bc7514f299c9374d | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.7 | 来源类型 github_release 暴露的待验证使用条件。\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:719367294 | https://github.com/VRSEN/agency-swarm | 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:719367294 | https://github.com/VRSEN/agency-swarm | 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项目：VRSEN/agency-swarm\n\n摘要：发现 23 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Chart Library tool for financial pattern analysis in agent swarms。\n\n## 1. 安装坑 · 来源证据：Chart Library tool for financial pattern analysis in agent swarms\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Chart Library tool for financial pattern analysis in agent swarms\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_736c9d770ee34419ad2476f2a973e433 | https://github.com/VRSEN/agency-swarm/issues/596 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Feature request: native advisor/executor consult flow for stronger-model escalation\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: native advisor/executor consult flow for stronger-model escalation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1b01977e66ac46caa8a8b860da5bdafe | https://github.com/VRSEN/agency-swarm/issues/598 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Proposal: ClawMem adapter for thread persistence across sessions\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: ClawMem adapter for thread persistence across sessions\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3bb24559ba48467ab0c8d43d3069d7f1 | https://github.com/VRSEN/agency-swarm/issues/594 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：CI-level governance checks for swarm agent code\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：CI-level governance checks for swarm agent code\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b995c0dfb8a5460caa7cfde16ac1c7a4 | https://github.com/VRSEN/agency-swarm/issues/593 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：Feature: Runtime governance and compliance audit trails\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature: Runtime governance and compliance audit trails\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bd751455da0479bb37a014ef50934dd | https://github.com/VRSEN/agency-swarm/issues/592 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.9.0 - Agent Swarm TUI and OpenClaw\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.9.0 - Agent Swarm TUI and OpenClaw\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_445071ada1ba4d558d4ebea6ec395364 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 来源证据：v1.8.0 — Present and Accounted For\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.0 — Present and Accounted For\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d270ab8e87c945878e308b78a2c8e7e6 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.8.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 配置坑 · 来源证据：v1.9.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.9.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e69c962dcc44fd5a160047df0f18192 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：v1.9.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.9.5\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ec6832c5bd7b4083b4dd1a68c50f666f | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.5 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 能力坑 · 能力判断依赖假设\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:719367294 | https://github.com/VRSEN/agency-swarm | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 来源证据：Research finding: Error detection failure rate in multi-agent chains — empirical data\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Research finding: Error detection failure rate in multi-agent chains — empirical data\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8ef6210eff50485ba327057aa93e59d8 | https://github.com/VRSEN/agency-swarm/issues/609 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 维护坑 · 来源证据：v1.9.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.9.4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_333f10fed5354907b99a35bb5cba22a4 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在安全注意事项\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:719367294 | https://github.com/VRSEN/agency-swarm | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 来源证据：Enforceable agency chart — cryptographic delegation per agent role in the hierarchy\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Enforceable agency chart — cryptographic delegation per agent role in the hierarchy\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ca5d1cf8ec54c2083ed88c2adc8554f | https://github.com/VRSEN/agency-swarm/issues/595 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Feature: Agent trust and discovery via MoltBridge integration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: Agent trust and discovery via MoltBridge integration\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66c9e8a0b624449c8c4292c01efc6d0c | https://github.com/VRSEN/agency-swarm/issues/528 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.9.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_952f33aba33c45debdfbfe4422b8789c | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v1.9.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.3\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9290fb1e7b174e4a9fe0704355613635 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 21. 安全/权限坑 · 来源证据：v1.9.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.7\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8e9071bb39904407bc7514f299c9374d | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.7 | 来源类型 github_release 暴露的待验证使用条件。\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:719367294 | https://github.com/VRSEN/agency-swarm | 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:719367294 | https://github.com/VRSEN/agency-swarm | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# agency-swarm - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agency-swarm 的“安装前体验版”。\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. p-intro：Agency Swarm 简介。围绕“Agency Swarm 简介”模拟一次用户任务，不展示安装或运行结果。\n2. p-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. p-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. p-agents：智能体 (Agent)。围绕“智能体 (Agent)”模拟一次用户任务，不展示安装或运行结果。\n5. p-agencies：代理组织 (Agency)。围绕“代理组织 (Agency)”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. p-intro\n输入：用户提供的“Agency Swarm 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. p-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. p-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. p-agents\n输入：用户提供的“智能体 (Agent)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. p-agencies\n输入：用户提供的“代理组织 (Agency)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / p-intro：Step 1 必须围绕“Agency Swarm 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / p-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / p-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / p-agents：Step 4 必须围绕“智能体 (Agent)”形成一个小中间产物，并等待用户确认。\n- Step 5 / p-agencies：Step 5 必须围绕“代理组织 (Agency)”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/VRSEN/agency-swarm\n- https://github.com/VRSEN/agency-swarm#readme\n- .codex/skills/claude-cli-review/SKILL.md\n- .codex/skills/codex-cli-review/SKILL.md\n- .codex/skills/delegation-management/SKILL.md\n- .codex/skills/policy-maintenance/SKILL.md\n- .codex/skills/requirement-ledger/SKILL.md\n- README.md\n- src/agency_swarm/__init__.py\n- pyproject.toml\n- Makefile\n- CONTRIBUTING.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agency-swarm 的核心服务。\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项目：VRSEN/agency-swarm\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install -U agency-swarm\n```\n\n来源：https://github.com/VRSEN/agency-swarm#readme\n\n## 来源\n\n- repo: https://github.com/VRSEN/agency-swarm\n- docs: https://github.com/VRSEN/agency-swarm#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_ecac37eea46647769698f762ddca2053"
}