{
"canonical_name": "VRSEN/agency-swarm",
"compilation_id": "pack_089c7333a3874d62a00c25e3d4a973d7",
"created_at": "2026-05-15T11:24:57.584599+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": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_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. page-introduction：Introduction to Agency Swarm。围绕“Introduction to Agency Swarm”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：Installation and Setup。围绕“Installation and Setup”模拟一次用户任务，不展示安装或运行结果。\n3. page-getting-started：Getting Started Guide。围绕“Getting Started Guide”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-architecture：Core Architecture。围绕“Core Architecture”模拟一次用户任务，不展示安装或运行结果。\n5. page-tools-system：Tools System。围绕“Tools System”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Introduction to Agency Swarm”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“Installation and Setup”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-getting-started\n输入：用户提供的“Getting Started Guide”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-architecture\n输入：用户提供的“Core Architecture”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-tools-system\n输入：用户提供的“Tools System”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Introduction to Agency Swarm”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“Installation and Setup”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-getting-started：Step 3 必须围绕“Getting Started Guide”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-architecture：Step 4 必须围绕“Core Architecture”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-tools-system：Step 5 必须围绕“Tools System”形成一个小中间产物，并等待用户确认。\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- docs/welcome/installation.mdx\n- docs/welcome/getting-started/from-scratch.mdx\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-15 11:07:28 UTC\n\n## 目录\n\n- [Introduction to Agency Swarm](#page-introduction)\n- [Installation and Setup](#page-installation)\n- [Getting Started Guide](#page-getting-started)\n- [Core Architecture](#page-core-architecture)\n- [Agent Internals](#page-agent-internal)\n- [Tools System](#page-tools-system)\n- [Communication Flows](#page-communication-flows)\n- [Context Management](#page-context-management)\n- [Messaging System](#page-messaging-system)\n- [File Management](#page-file-management)\n\n\n\n## Introduction to Agency Swarm\n\n### 相关页面\n\n相关主题：[Installation and Setup](#page-installation), [Getting Started Guide](#page-getting-started), [Core Architecture](#page-core-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- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\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/utils/create_agent_template.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)\n- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n- [src/agency_swarm/integrations/README.md](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/integrations/README.md)\n \n\n# Introduction to Agency Swarm\n\nAgency Swarm is a multi-agent orchestration framework designed for building autonomous AI agent systems that can collaborate, communicate, and delegate tasks between specialized agents. The framework enables developers to create complex workflows where multiple AI agents work together to accomplish tasks that require diverse capabilities.\n\n## Overview\n\nAgency Swarm provides a structured approach to building multi-agent systems with the following core capabilities:\n\n- **Agent Definition**: Create specialized agents with specific roles, instructions, and tools\n- **Inter-Agent Communication**: Enable agents to communicate and transfer control via handoffs\n- **Tool Integration**: Support for custom tools, OpenAPI schema conversion, and built-in capabilities\n- **Agency Management**: Orchestrate multiple agents within an agency context\n- **User Interfaces**: Multiple UI options including Terminal UI (TUI), Copilot UI, and visualization\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Architecture Overview\n\nThe framework is built around two primary concepts: **Agents** and **Agencies**. Agents represent individual AI workers with specific responsibilities, while Agencies coordinate multiple agents to accomplish complex tasks.\n\n```mermaid\ngraph TD\n A[User] --> B[Agency]\n B --> C[CEO Agent]\n C --> D[Developer Agent]\n C --> E[Support Agent]\n D --> F[Custom Tools]\n E --> G[WebSearch Tool]\n D --> H[File Management]\n E --> D\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n### Core Components\n\n| Component | Description | Location |\n|-----------|-------------|----------|\n| Agent | Base class for all agents with core execution methods | `src/agency_swarm/agent/core.py` |\n| Agency | Orchestrates multiple agents and their communication | Main orchestration layer |\n| Tool | Base class for custom tools and decorators | Tool infrastructure |\n| ModelSettings | Configuration for model parameters | Configuration layer |\n\n## Creating Agents\n\nAgents are the fundamental building blocks of Agency Swarm. Each agent has a name, description, instructions, tools, and model configuration.\n\n### Agent Folder Structure\n\n```\nAgentName/\n├── files/ # Files to upload to OpenAI\n├── schemas/ # OpenAPI schemas for tool generation\n├── tools/ # Agent-specific tools\n├── AgentName.py # Main agent class\n├── __init__.py # Package initialization\n└── instructions.md # Agent instruction document\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n### Agent Implementation Example\n\n```python\nfrom agency_swarm import Agent, ModelSettings\nfrom agency_swarm.tools.example import ExampleTool\n\nclass SupportAgent(Agent):\n def __init__(self):\n super().__init__(\n name=\"SupportAgent\",\n description=\"Handles customer support requests\",\n instructions=\"./instructions.md\",\n files_folder=\"./files\",\n tools=[ExampleTool],\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n temperature=0.3,\n max_tokens=25000,\n ),\n )\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n### Agent Core Methods\n\nThe `Agent` class provides several core execution methods for handling interactions:\n\n| Method | Description |\n|--------|-------------|\n| `get_response()` | Async method for running agent turns in conversation loop |\n| `get_response_sync()` | Synchronous wrapper for `get_response()` |\n| `upload_file()` | Upload files using the agent's file manager |\n\n资料来源：[src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n## Tools System\n\nAgency Swarm supports multiple tool definition patterns to give agents capabilities beyond plain text generation.\n\n### Tool Definition Patterns\n\n| Pattern | Description | Use Case |\n|---------|-------------|----------|\n| `@function_tool` decorator | Lightweight function-based tool | Quick tool definitions |\n| `BaseTool` subclass | Full Pydantic-based tool | Complex tools with validation |\n| `ToolFactory` | OpenAPI schema conversion | API integration |\n\n### BaseTool Implementation\n\n```python\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\n\nclass MyCustomTool(BaseTool):\n example_field: str = Field(\n ..., description=\"Description of the example field\"\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### OpenAPI Schema Conversion\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资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Agency Structure\n\nThe Agency class orchestrates multiple agents and defines how they communicate with each other.\n\n### Defining an Agency\n\n```python\nfrom agency_swarm import Agency, Agent\n\nceo = Agent(name=\"CEO\", ...)\ndeveloper = Agent(name=\"Developer\", ...)\nsupport = Agent(name=\"Support\", ...)\n\nagency = Agency(\n ceo,\n developer,\n support,\n communication_flows=[\n (ceo, developer), # CEO can delegate to Developer\n (ceo, support), # CEO can delegate to Support\n (support, developer), # Support can handoff to Developer\n ],\n shared_instructions=\"Agency-wide guidelines\",\n)\n```\n\n### Communication Flows\n\nCommunication flows define the allowed message paths between agents. The framework supports two primary communication patterns:\n\n| Pattern | Description |\n|---------|-------------|\n| `SendMessage` | Direct message passing between agents |\n| `Handoff` | Transfer of control to another agent |\n\n资料来源：[examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n\n## User Interfaces\n\nAgency Swarm provides multiple UI options for interacting with agencies.\n\n### Available UIs\n\n| UI Type | Description | Location |\n|---------|-------------|----------|\n| Terminal UI (TUI) | Command-line chat interface | `examples/interactive/tui.py` |\n| Copilot UI | Next.js-based copilot interface | `src/agency_swarm/ui/demos/copilot/` |\n| Visualization | HTML-based agency visualization | `src/agency_swarm/ui/templates/` |\n| FastAPI | REST API integration | `src/agency_swarm/integrations/` |\n\n### Terminal UI Example\n\n```python\nif __name__ == \"__main__\":\n create_demo_agency().tui(show_reasoning=True)\n```\n\n资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n## Running the Agency\n\n### Synchronous Execution\n\n```python\nagency = Agency(ceo, developer, support)\nresponse = agency.get_response_sync(\"Create a project skeleton\")\n```\n\n### Asynchronous Execution\n\n```python\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资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Model Configuration\n\nAgents can be configured with specific model settings for fine-tuned control over generation behavior.\n\n### ModelSettings Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `temperature` | float | 0.3 | Sampling temperature (0-2) |\n| `max_tokens` | int | None | Maximum tokens in response |\n| `top_p` | float | None | Nucleus sampling parameter |\n| `reasoning` | Reasoning | None | Reasoning effort for reasoning models |\n\n### Reasoning Models\n\nFor reasoning models (like o1 series), the framework automatically handles compatibility:\n\n- Temperature parameter is disabled for reasoning models\n- Reasoning effort can be configured via `ModelSettings(reasoning=Reasoning(effort=\"low\"))`\n\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\n## Integration with External Services\n\nAgency Swarm supports integration with external frameworks like FastAPI and OpenClaw.\n\n### FastAPI Integration\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资料来源：[src/agency_swarm/integrations/README.md](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/integrations/README.md)\n\n## Example Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Agency\n participant CEO\n participant Developer\n participant Support\n\n User->>Agency: Initial Request\n Agency->>CEO: Process Request\n CEO->>Support: Route to Support\n Support->>CEO: Needs Development\n CEO->>Developer: Delegate Task\n Developer-->>CEO: Task Complete\n CEO-->>Agency: Final Response\n Agency-->>User: Response\n```\n\n## Key Features Summary\n\n| Feature | Description |\n|---------|-------------|\n| Multi-Agent Orchestration | Coordinate multiple specialized agents |\n| Inter-Agent Communication | Built-in message passing and handoffs |\n| Tool System | Custom tools, OpenAPI conversion, built-in tools |\n| Model Flexibility | Support for various OpenAI models |\n| UI Options | TUI, Copilot, Visualization, FastAPI |\n| File Management | Vector stores and file search capabilities |\n| Streaming | Real-time response streaming |\n| Guardrails | Input and output validation |\n\n资料来源：[examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n\n## Getting Started\n\n1. Install Agency Swarm: `pip install agency-swarm`\n2. Create your first agent with the CLI: `agency-swarm create-agent`\n3. Define tools and instructions\n4. Compose agents into an agency\n5. Run the agency with `get_response_sync()` or async `get_response()`\n\n---\n\n\n\n## Installation and Setup\n\n### 相关页面\n\n相关主题：[Introduction to Agency Swarm](#page-introduction), [Getting Started Guide](#page-getting-started)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n- [src/agency_swarm/cli/main.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/main.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/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n \n\n# Installation and Setup\n\nThis guide covers how to install Agency Swarm, configure your development environment, and set up your first multi-agent project.\n\n## Prerequisites\n\nBefore installing Agency Swarm, ensure you have the following:\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| Python | 3.10+ | Required for async/await support |\n| pip / uv | Latest | Package manager |\n| OpenAI API Key | - | Set as environment variable |\n| Git | - | For cloning and version control |\n\n## Installation Methods\n\n### From PyPI (Recommended)\n\n```bash\npip install agency-swarm\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/VRSEN/agency-swarm.git\ncd agency-swarm\npip install -e .\n```\n\n### Development Installation\n\nFor contributors working on Agency Swarm itself:\n\n```bash\ngit clone https://github.com/VRSEN/agency-swarm.git\ncd agency-swarm\npip install -e \".[dev]\"\n```\n\n资料来源：[CONTRIBUTING.md:1-20]()\n\n## Environment Configuration\n\n### Required Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `OPENAI_API_KEY` | Your OpenAI API key | Yes |\n\n```bash\nexport OPENAI_API_KEY=\"sk-your-key-here\"\n```\n\nFor persistent configuration, add this to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.).\n\n### Optional Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `OPENAI_BASE_URL` | OpenAI default | Custom API endpoint |\n| `AGENCY_SWARM_LOG_LEVEL` | `INFO` | Logging verbosity |\n\n## CLI Installation and Setup\n\nAgency Swarm provides a command-line interface for agent creation and management.\n\n### Verify CLI Installation\n\n```bash\nagency-swarm --version\n```\n\n### CLI Command Reference\n\n资料来源：[src/agency_swarm/cli/main.py:1-50]()\n\n| Command | Description |\n|---------|-------------|\n| `agency-swarm create-agent` | Scaffold a new agent template |\n| `agency-swarm migrate-agent` | Generate agent from Assistants API settings.json |\n| `agency-swarm import-tool` | Import built-in tools into project |\n\n#### Create Agent Command Options\n\n```bash\nagency-swarm create-agent [AGENT_NAME] [options]\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--model` | string | `gpt-5.4` | Model identifier |\n| `--reasoning` | string | - | Reasoning effort level |\n| `--max-tokens` | int | - | Maximum completion tokens |\n| `--temperature` | float | `0.3` | Sampling temperature (non-reasoning models only) |\n| `--instructions` | string | - | Custom instructions for agent |\n| `--use-txt` | flag | False | Use .txt instead of .md for instructions |\n| `--path` | string | `./` | Output directory for agent template |\n\n资料来源：[src/agency_swarm/utils/create_agent_template.py:1-40]()\n\n#### Migrate Agent Command\n\n```bash\nagency-swarm migrate-agent path_to_settings.json [--output-dir DIR]\n```\n\nThis converts an OpenAI Assistant configuration into an Agency Swarm agent definition.\n\n资料来源：[src/agency_swarm/cli/main.py:80-95]()\n\n## Project Structure Setup\n\nWhen creating a new agent using the CLI, the following structure is generated:\n\n```\nagency_swarm/agents/AgentName/\n├── AgentName/\n│ ├── files/ # Files uploaded to OpenAI\n│ ├── tools/ # Agent-specific tools\n│ ├── schemas/ # OpenAPI schemas\n│ ├── AgentName.py # Main agent class\n│ ├── __init__.py # Package initialization\n│ └── instructions.md # Agent instructions\n```\n\n资料来源：[CONTRIBUTING.md:60-75]()\n\n### Agent Template Example\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-15]()\n\n## Tool Installation\n\nAgency Swarm provides pre-built tools that can be imported into your project.\n\n### List Available Tools\n\n```bash\nagency-swarm import-tool --list\n```\n\n### Import a Tool\n\n```bash\nagency-swarm import-tool ToolName [--directory ./tools]\n```\n\nTools are organized by category in the `agency_swarm/tools/` directory:\n\n```\nagency_swarm/tools/{category}/\n├── YourNewTool.py\n└── __init__.py\n```\n\n资料来源：[CONTRIBUTING.md:40-55]()\n\n## Development Dependencies\n\n### Install Dev Dependencies\n\n```bash\nmake sync\n```\n\n### Run Test Suite\n\n```bash\nmake coverage\n```\n\nThe `make coverage` command runs the test suite with coverage reporting.\n\n资料来源：[CONTRIBUTING.md:25-35]()\n\n## Quick Start: Your First Agency\n\n```mermaid\ngraph TD\n A[Install agency-swarm] --> B[Set OPENAI_API_KEY]\n B --> C[Create Agent Templates]\n C --> D[Define Communication Flows]\n D --> E[Initialize Agency]\n E --> F[Run get_response]\n```\n\n### Complete Example\n\n```python\nfrom agency_swarm import Agency, Agent\nfrom agency_swarm.tools import WebSearchTool\n\n# Create agents\nsupport = Agent(\n name=\"SupportAgent\",\n description=\"Handles user inquiries\",\n instructions=\"You are a helpful support agent.\",\n tools=[WebSearchTool()],\n model=\"gpt-5.4-mini\",\n)\n\n# Initialize agency\nagency = Agency(support)\n\n# Run\nresult = agency.get_response_sync(\"Hello!\")\n```\n\n资料来源：[examples/README.md:1-20]()\n\n## Troubleshooting\n\n### Common Installation Issues\n\n| Issue | Solution |\n|-------|----------|\n| `ModuleNotFoundError` | Reinstall: `pip install agency-swarm` |\n| Python version error | Ensure Python 3.10+ with `python --version` |\n| API key not found | Verify `OPENAI_API_KEY` environment variable |\n\n### Verify Installation\n\n```python\nimport agency_swarm\nprint(agency_swarm.__version__)\n```\n\n### Running Examples\n\nExamples are located in the `examples/` directory. Each can be run directly:\n\n```bash\ncd examples\npython multi_agent_workflow.py\n```\n\n资料来源：[examples/README.md:1-30]()\n\n## Next Steps\n\nAfter installation, explore:\n\n- [Getting Started Guide](/docs/getting-started/from-scratch.mdx) - Build your first agency\n- [Agent Communication](/docs/features/communication.mdx) - Configure agent-to-agent messaging\n- [Tool Development](/docs/features/tools.mdx) - Create custom tools\n- [FastAPI Integration](/docs/additional-features/fastapi-integration.mdx) - Deploy as API service\n\n---\n\n\n\n## Getting Started Guide\n\n### 相关页面\n\n相关主题：[Introduction to Agency Swarm](#page-introduction), [Installation and Setup](#page-installation), [Core Architecture](#page-core-architecture), [Tools System](#page-tools-system)\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- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n- [examples/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/tools.py)\n- [examples/multi_agent_workflow.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/multi_agent_workflow.py)\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- [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 \n\n# Getting Started Guide\n\nWelcome to the Agency Swarm Getting Started Guide. This guide provides comprehensive instructions for setting up your development environment, understanding the project structure, and building your first multi-agent application using the Agency Swarm framework.\n\n## Overview\n\nAgency Swarm is a framework for building multi-agent systems that enables multiple AI agents to collaborate through defined communication flows. The framework provides tools for creating agents, defining their capabilities through tools, establishing communication patterns between agents, and visualizing agent hierarchies.\n\nThis guide covers the essential steps from initial environment setup to running your first multi-agent workflow, with practical examples drawn from the repository's example implementations.\n\n## Prerequisites\n\nBefore beginning with Agency Swarm, ensure your development environment meets the following requirements:\n\n| Requirement | Minimum Version | Notes |\n|-------------|-----------------|-------|\n| Python | 3.10+ | Required for type hints and async features |\n| pip | Latest | For dependency management |\n| Git | Any recent version | For cloning the repository |\n| OpenAI API Key | Valid key | Required for agent execution |\n\n## Environment Setup\n\n### Cloning the Repository\n\nBegin by cloning the Agency Swarm repository to your local machine:\n\n```bash\ngit clone https://github.com/VRSEN/agency-swarm.git\ncd agency-swarm\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n### Creating a Virtual Environment\n\nCreating an isolated Python environment is recommended to avoid dependency conflicts:\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate # On Windows use `venv\\Scripts\\activate`\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n### Installing Dependencies\n\nAgency Swarm uses a Makefile for dependency management. Install all required packages with the sync command:\n\n```bash\nmake sync\n```\n\nThis command installs both runtime and development dependencies, including pre-commit hooks for code quality checks. To also install pre-commit hooks manually:\n\n```bash\npip install pre-commit\npre-commit install\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n## Project Structure\n\nUnderstanding the Agency Swarm directory structure is essential for effective development:\n\n```mermaid\ngraph TD\n A[agency-swarm Root] --> B[examples/]\n A --> C[src/agency_swarm/]\n A --> D[agency_swarm/]\n \n B --> B1[Core Examples]\n B --> B2[interactive/]\n B --> B3[fastapi_integration/]\n \n C --> C1[agent/]\n C --> C2[tools/]\n C --> C3[cli/]\n C --> C4[ui/]\n \n D --> D1[agents/]\n D --> D2[tools/]\n```\n\n### Key Directories\n\n| Directory | Purpose |\n|-----------|---------|\n| `examples/` | Runnable example scripts demonstrating various features |\n| `examples/interactive/` | Interactive UI demos including TUI and copilot interfaces |\n| `examples/fastapi_integration/` | FastAPI server and client examples |\n| `src/agency_swarm/` | Core framework source code |\n| `agency_swarm/` | User-defined agents and custom tools |\n\n### Recommended Agent Folder Structure\n\nEach agent should follow a consistent folder structure:\n\n```\nAgentName/\n├── files/ # Files to be uploaded to OpenAI\n├── schemas/ # OpenAPI schemas for tool generation\n├── tools/ # Agent-specific tool definitions\n├── AgentName.py # Main agent class\n├── __init__.py # Package initialization\n└── instructions.md # Agent instruction document\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Creating Your First Agent\n\n### Using the CLI Template Generator\n\nAgency Swarm provides a CLI command to scaffold agent templates automatically:\n\n```bash\nagency-swarm create-agent AgentName --model gpt-5.4-mini\n```\n\nThe CLI supports the following parameters:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `--name` | string | (prompt) | Name of the agent |\n| `--description` | string | (prompt) | Agent description |\n| `--model` | string | gpt-5.4 | Model to use |\n| `--temperature` | float | 0.3 | Sampling temperature (not for reasoning models) |\n| `--reasoning` | string | null | Reasoning effort for reasoning models |\n| `--instructions` | string | null | Custom instructions |\n| `--path` | string | ./ | Output directory |\n\n资料来源：[src/agency_swarm/cli/main.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/main.py)\n\n### Manual Agent Definition\n\nAlternatively, define agents programmatically using the Agent class:\n\n```python\nfrom agency_swarm import Agent, ModelSettings\n\nceo = Agent(\n name=\"CEO\",\n description=\"Responsible for client communication, task planning and management.\",\n instructions=\"You must converse with other agents to ensure complete task execution.\",\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## Defining Tools\n\nAgency Swarm supports multiple tool definition patterns.\n\n### Function Tool with Decorator\n\nThe simplest approach uses the `@function_tool` decorator:\n\n```python\nfrom agency_swarm import function_tool\n\n@function_tool\ndef calculate(a: int, b: int) -> int:\n \"\"\"A brief description of what the custom tool does.\"\"\"\n return a + b\n```\n\n资料来源：[examples/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/tools.py)\n\n### BaseTool Class\n\nFor more complex tools with validation, use the `BaseTool` class:\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.\n \"\"\"\n\n example_field: str = Field(\n ..., description=\"Description of the example field\"\n )\n\n def run(self):\n return \"Result of MyCustomTool operation\"\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n### OpenAPI Schema to Tools\n\nConvert existing OpenAPI schemas into Agency Swarm tools:\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# Using local file\nwith open(\"schemas/your_schema.json\") as f:\n tools = ToolFactory.from_openapi_schema(f.read())\n\n# Using remote URL\nimport requests\ntools = ToolFactory.from_openapi_schema(\n requests.get(\"https://api.example.com/openapi.json\").json()\n)\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Building Multi-Agent Workflows\n\n### Defining Communication Flows\n\nAgents communicate through defined flows using `SendMessage` and `Handoff`:\n\n```python\nfrom agency_swarm import Agency, Agent, SendMessage, Handoff\n\nceo = Agent(name=\"CEO\", ...)\ndeveloper = Agent(name=\"Developer\", ...)\nmanager = Agent(name=\"Manager\", ...)\n\nagency = Agency(\n ceo, # Entry point agent\n communication_flows=[\n (ceo > developer, SendMessage), # CEO sends to Developer\n (developer < manager), # Bidirectional with handoff\n (developer > ceo, Handoff), # Developer hands off to CEO\n ]\n)\n```\n\n资料来源：[examples/multi_agent_workflow.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/multi_agent_workflow.py)\n\n### Communication Flow Syntax\n\n| Syntax | Meaning |\n|--------|---------|\n| `(agent_a > agent_b)` | A sends to B with default SendMessage |\n| `(agent_a > agent_b, SendMessage)` | Explicit SendMessage tool |\n| `(agent_a < agent_b)` | Bidirectional communication |\n| `(agent_a < agent_b, Handoff)` | Bidirectional with handoff |\n| `(a < b > c)` | Multi-agent pattern |\n\n### Running the Agency\n\nExecute the agency asynchronously:\n\n```python\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\nFor synchronous execution:\n\n```python\nresp = agency.get_response_sync(\"Create a project skeleton.\")\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Running Examples\n\nThe repository includes numerous runnable examples demonstrating key features:\n\n### Available Example Scripts\n\n| Example | Purpose |\n|---------|---------|\n| `multi_agent_workflow.py` | Multi-agent collaboration with validation |\n| `agency_context.py` | Data sharing between agents |\n| `streaming.py` | Real-time streaming responses |\n| `guardrails.py` | Input and output validation |\n| `tools.py` | Tool patterns with BaseTool and @function_tool |\n| `agent_file_storage.py` | Vector store and FileSearch tool usage |\n| `message_attachments.py` | File processing in messages |\n| `custom_send_message.py` | Custom SendMessage configurations |\n\n资料来源：[examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n\n### Running an Example\n\nNavigate to the examples directory and run any example script:\n\n```bash\ncd examples\npython multi_agent_workflow.py\n```\n\n## Interactive Interfaces\n\nAgency Swarm provides multiple interactive UI options.\n\n### Terminal UI\n\nThe terminal UI provides a chat interface in the terminal:\n\n```python\nfrom agency_swarm import Agency\n\nagency = create_demo_agency()\nagency.tui(show_reasoning=True)\n```\n\n资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n### Agency Visualization\n\nGenerate interactive HTML visualizations of your agency structure:\n\n```python\nfrom agency_swarm import Agency\n\nagency = create_demo_agency()\nhtml_file = agency.visualize(\n output_file=\"agency.html\",\n include_tools=True,\n open_browser=True,\n)\n```\n\n资料来源：[examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n\n## Testing\n\nRun the test suite to ensure your implementation works correctly:\n\n```bash\nmake coverage\n```\n\nThe coverage command runs pytest with coverage reporting. Review the output to ensure adequate test coverage for your changes.\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n## Additional Resources\n\n### Cursor IDE Integration\n\nFor enhanced development with AI coding assistants, use the `.cursorrules` file at the repository root. See the Cursor IDE guide at https://agency-swarm.ai/welcome/getting-started/cursor-ide for detailed setup instructions.\n\n### FastAPI Integration\n\nAgency Swarm supports FastAPI integration for serving agents as REST endpoints:\n\n```bash\ncd examples/fastapi_integration\npython server.py\n```\n\nThis exposes endpoints for streaming responses and agency metadata. See the `examples/fastapi_integration/README.md` for complete documentation.\n\n### CLI Commands Reference\n\n| Command | Description |\n|---------|-------------|\n| `agency-swarm create-agent` | Create a new agent template |\n| `agency-swarm migrate-agent` | Generate agent from OpenAI settings.json |\n| `agency-swarm import-tool` | Import built-in tools into your project |\n\n资料来源：[src/agency_swarm/cli/main.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/main.py)\n\n## Next Steps\n\nAfter completing this guide, consider exploring:\n\n1. **Advanced Communication Patterns** - Study `examples/interactive/hybrid_communication_flows.py` for complex agent interaction patterns\n2. **Custom Tool Development** - Create domain-specific tools following the patterns in `examples/tools.py`\n3. **Persistence** - Implement chat history persistence using `examples/custom_persistence.py`\n4. **Guardrails** - Add input/output validation as demonstrated in `examples/guardrails.py`\n\nFor comprehensive documentation, visit https://agency-swarm.ai/welcome/getting-started/from-scratch for the full tutorial.\n\n---\n\n\n\n## Core Architecture\n\n### 相关页面\n\n相关主题：[Introduction to Agency Swarm](#page-introduction), [Agent Internals](#page-agent-internal), [Communication Flows](#page-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/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n- [src/agency_swarm/agent/agent_flow.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/agent_flow.py)\n- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.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/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n- [src/agency_swarm/cli/utils/generate-agent-from-settings.ts](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/utils/generate-agent-from-settings.ts)\n \n\n# Core Architecture\n\nAgency Swarm is a multi-agent framework built on OpenAI's Agents SDK that enables the creation of collaborative AI agent systems. The core architecture comprises three fundamental layers: the **Agency Layer**, the **Agent Layer**, and the **Communication Layer**. This document provides an in-depth analysis of how these components interact to form a cohesive multi-agent system.\n\n## Architecture Overview\n\nThe framework follows a hierarchical design where the Agency serves as the top-level orchestrator, managing multiple Agents that collaborate through well-defined communication channels.\n\n```mermaid\ngraph TB\n subgraph Agency[\"Agency Layer\"]\n A[Agency]\n AC[AgencyContext]\n AF[Communication Flows]\n end\n \n subgraph Agent[\"Agent Layer\"]\n AG1[Agent Instance]\n AG2[Agent Instance]\n AGn[Agent Instance]\n end\n \n subgraph Tools[\"Tool Layer\"]\n BT[BaseTool]\n FT[FunctionTool]\n TF[ToolFactory]\n end\n \n subgraph Model[\"Model Layer\"]\n MS[ModelSettings]\n RM[Reasoning Models]\n end\n \n A --> AG1\n A --> AG2\n A --> AGn\n A --> AC\n A --> AF\n \n AG1 --> BT\n AG2 --> FT\n AGn --> TF\n \n AG1 --> MS\n AG2 --> RM\n```\n\n## The Agency Layer\n\n### Purpose and Role\n\nThe Agency acts as the central coordinator for all agents within the system. It manages agent initialization, communication routing, shared context distribution, and the overall execution flow.\n\n**资料来源:** [examples/README.md:1-30](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n\n### Agency Initialization\n\nThe Agency is initialized with a collection of agents and optional communication flows:\n\n```python\nfrom agency_swarm import Agency, Agent\n\nsupport = Agent(name=\"SupportAgent\", ...)\nmath = Agent(name=\"MathAgent\", ...)\n\nagency = Agency(\n support,\n math,\n communication_flows=[(support, math, Handoff)],\n shared_instructions=\"Demonstrate reasoning, web search, file search, and handoffs.\",\n name=\"DemoAgency\"\n)\n```\n\n**资料来源:** [examples/interactive/tui.py:40-68](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n### Key Agency Components\n\n| Component | Description |\n|-----------|-------------|\n| `agents` | Dictionary of initialized Agent instances |\n| `communication_flows` | Defines allowed communication paths between agents |\n| `shared_instructions` | Common instructions for all agents |\n| `agency_context` | Shared data store accessible by all agents |\n\n## The Agent Layer\n\n### Agent Class Structure\n\nThe `Agent` class is the fundamental building block of Agency Swarm. Each agent encapsulates a specific role, set of tools, instructions, and model configuration.\n\n**资料来源:** [src/agency_swarm/agent/core.py:1-100](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n### Agent Initialization Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `name` | `str` | Yes | Unique identifier for the agent |\n| `description` | `str` | Yes | Role description for the agent |\n| `instructions` | `str` | Yes | Instructions or path to instructions file |\n| `tools` | `list[BaseTool]` | No | List of tool instances |\n| `files_folder` | `str` | No | Path to files for vector store |\n| `schemas_folder` | `str` | No | Path to OpenAPI schemas |\n| `model` | `str` | No | Model identifier (default: \"gpt-5.4\") |\n| `model_settings` | `ModelSettings` | No | Model configuration |\n| `output_type` | `type` | No | Output schema for structured responses |\n\n**资料来源:** [src/agency_swarm/agent/core.py:50-150](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n### Tool Loading Mechanism\n\nAgents support three distinct tool loading mechanisms:\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**资料来源:** [src/agency_swarm/agent/core.py:120-130](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n### OpenAPI Schema Parsing\n\nAgents can automatically convert OpenAPI schemas into usable tools:\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**资料来源:** [src/agency_swarm/agent/core.py:135-140](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n## Communication Architecture\n\n### Agent-to-Agent Communication\n\nAgents communicate through two primary mechanisms:\n\n1. **Direct Messaging** (`SendMessage`)\n2. **Handoffs** - Transfer of control between agents\n\n```python\nfrom agency_swarm import Handoff\n\nagency = Agency(\n support,\n math,\n communication_flows=[(support, math, Handoff)],\n)\n```\n\n**资料来源:** [examples/interactive/tui.py:55-57](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n### Communication Flow Definition\n\nCommunication flows are defined as a list of tuples specifying source agent, target agent, and the communication type:\n\n```python\ncommunication_flows=[\n (agent_a, agent_b, Handoff),\n (agent_b, agent_c, SendMessage),\n]\n```\n\n## Execution Flow\n\n### The get_response Method\n\nThe primary method for agent execution is `get_response`, which handles both user and agent-to-agent interactions:\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**资料来源:** [src/agency_swarm/agent/core.py:150-200](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n### Synchronous Execution\n\nFor synchronous use cases, `get_response_sync` provides a blocking interface:\n\n```python\nresp = agency.get_response_sync(\"What's your name?\")\n```\n\n### Streaming Responses\n\nThe framework supports real-time streaming for interactive applications:\n\n```python\n# See streaming.py in examples\n```\n\n**资料来源:** [examples/README.md:8](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n\n## Model Configuration\n\n### ModelSettings\n\nModel configuration is handled through the `ModelSettings` class:\n\n```python\nfrom agency_swarm import ModelSettings, Reasoning\n\nmodel_settings=ModelSettings(\n temperature=0.3,\n top_p=0.9,\n max_tokens=25000,\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n)\n```\n\n**资料来源:** [src/agency_swarm/cli/utils/generate-agent-from-settings.ts:50-80](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/utils/generate-agent-from-settings.ts)\n\n### Reasoning Models\n\nThe framework supports OpenAI's reasoning models with special configuration:\n\n```python\ndef is_reasoning_model(model: str) -> bool:\n \"\"\"Check if the model is a reasoning model.\"\"\"\n # Reasoning models do not support temperature parameter\n```\n\n**资料来源:** [src/agency_swarm/utils/create_agent_template.py:10-25](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)\n\n### ModelSettings Parameters\n\n| Parameter | Type | Description | Reasoning Model Compatible |\n|-----------|------|-------------|---------------------------|\n| `temperature` | `float` | Sampling temperature | No |\n| `top_p` | `float` | Nucleus sampling | No |\n| `max_tokens` | `int` | Maximum tokens in response | Yes |\n| `reasoning` | `Reasoning` | Reasoning effort configuration | Yes |\n\n## File Management\n\n### Vector Store Integration\n\nAgents can upload files to OpenAI's vector stores for semantic search:\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**资料来源:** [src/agency_swarm/agent/core.py:145-152](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n### File Search Tool Configuration\n\nThe `FileSearchTool` can be configured with vector store IDs:\n\n```python\ntoolImports.push(\"FileSearchTool\");\nconfigParts.push(`vector_store_ids=[${vectorStoreIds}]`);\n```\n\n**资料来源:** [src/agency_swarm/cli/utils/generate-agent-from-settings.ts:100-120](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/utils/generate-agent-from-settings.ts)\n\n## Tool System Architecture\n\n### Tool Types\n\n| Tool Type | Description | Base Class |\n|-----------|-------------|------------|\n| `BaseTool` | Pydantic-based tool definition | `BaseTool` |\n| `FunctionTool` | Decorator-based tool creation | `@function_tool` |\n| `ToolFactory` | OpenAPI schema conversion | `ToolFactory.from_openapi_schema()` |\n\n### BaseTool Implementation\n\n```python\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\n\nclass MyCustomTool(BaseTool):\n example_field: str = Field(\n ..., description=\"Description of the example field\"\n )\n\n def run(self):\n return f\"Result: {self.example_field}\"\n```\n\n**资料来源:** [README.md:100-130](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n### ToolFactory for OpenAPI Schemas\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\ntools = ToolFactory.from_openapi_schema(\n openapi_schema_json # Can be dict or loaded from file\n)\n```\n\n## Agent Flow State Machine\n\nThe `agent_flow.py` module manages the state transitions within an agent's execution cycle:\n\n```mermaid\ngraph LR\n A[Init] --> B[Process Input]\n B --> C{Tool Call?}\n C -->|Yes| D[Execute Tool]\n D --> B\n C -->|No| E[Generate Response]\n E --> F[Check Handoff]\n F -->|Yes| G[Transfer Control]\n G --> H[End]\n F -->|No| I[Final Output]\n I --> H\n```\n\n**资料来源:** [src/agency_swarm/agent/agent_flow.py:1-50](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/agent_flow.py)\n\n## CLI and Template Generation\n\n### Agent Template Creation\n\nThe CLI provides utilities for generating agent templates with validation:\n\n```python\ndef create_agent_template(\n agent_name=None,\n agent_description=None,\n model=\"gpt-5.4\",\n reasoning=None,\n max_tokens=None,\n temperature=None,\n path=\"./\",\n instructions=None,\n use_txt=False,\n include_example_tool=True,\n) -> bool:\n```\n\n**资料来源:** [src/agency_swarm/utils/create_agent_template.py:15-40](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)\n\n### Input Validation\n\nThe framework validates agent names and parameters:\n\n```python\ndef _validate_agent_name(agent_name):\n \"\"\"Validate agent name follows CamelCase convention.\"\"\"\n\ndef _validate_temperature(temperature):\n \"\"\"Validate temperature is within valid range (0-2).\"\"\"\n```\n\n**资料来源:** [src/agency_swarm/utils/create_agent_template.py:40-70](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)\n\n## Recommended Folder Structure\n\n```\nagency_project/\n├── agency_manifesto.md # Agency's guiding principles\n└── AgentName/\n ├── files/ # Files for vector store upload\n ├── schemas/ # OpenAPI schemas for tools\n ├── tools/ # Custom tool modules\n ├── AgentName.py # Agent class definition\n ├── __init__.py # Package initialization\n └── instructions.md # Agent instructions\n```\n\n**资料来源:** [README.md:60-80](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Programmatic Usage Patterns\n\n### Async Execution\n\n```python\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### Sync Execution\n\n```python\nresp = agency.get_response_sync(\"What's your name?\")\n```\n\n## Summary\n\nThe Agency Swarm core architecture consists of three interdependent layers:\n\n1. **Agency Layer**: Orchestrates multiple agents, manages communication flows, and maintains shared context\n2. **Agent Layer**: Encapsulates individual agent capabilities including tools, instructions, and model configurations\n3. **Communication Layer**: Enables agent-to-agent messaging and handoff mechanisms\n\nThe architecture follows a modular design pattern where tools, models, and communication mechanisms can be independently configured and composed to create complex multi-agent workflows.\n\n---\n\n\n\n## Agent Internals\n\n### 相关页面\n\n相关主题：[Core Architecture](#page-core-architecture), [Tools System](#page-tools-system)\n\n\nRelevant Source Files
\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/initialization.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/initialization.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/execution.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/execution.py)\n- [src/agency_swarm/agent/execution_guardrails.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/execution_guardrails.py)\n \n\n# Agent Internals\n\n## Overview\n\nThe Agent is the fundamental execution unit in Agency Swarm. It represents an autonomous entity capable of processing messages, executing tools, and communicating with other agents within an agency. Agents are built on OpenAI's Responses API and encapsulate configuration for model selection, tool definitions, file management, and communication protocols.\n\nAgents serve as the building blocks for multi-agent systems, enabling complex workflows where specialized agents collaborate through defined communication flows. Each agent maintains its own state, toolset, and instruction set while participating in the broader agency ecosystem.\n\n资料来源：[src/agency_swarm/agent/core.py:1-50]()\n\n## Architecture Overview\n\nThe Agent module is organized into several interconnected components that handle different aspects of agent behavior:\n\n```mermaid\ngraph TD\n A[Agent] --> B[Initialization]\n A --> C[Core Execution]\n A --> D[Tools Management]\n A --> E[Guardrails]\n \n B --> B1[__init__]\n B --> B2[_init_files]\n B --> B3[_load_tools_from_folder]\n B --> B4[_parse_schemas]\n \n C --> C1[get_response]\n C --> C2[Run Hooks]\n C --> C3[Run Config]\n \n D --> D1[BaseTool]\n D --> D2[FunctionTool]\n D --> D3[ToolFactory]\n \n E --> E1[Input Guardrails]\n E --> E2[Output Guardrails]\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `core.py` | Main Agent class | Primary interface for agent operations |\n| `initialization.py` | Agent setup | Initialization logic and factory methods |\n| `tools.py` | Tool management | Tool loading, parsing, and factory utilities |\n| `execution.py` | Runtime execution | Response processing and hooks |\n| `execution_guardrails.py` | Validation | Input/output validation pipelines |\n\n资料来源：[src/agency_swarm/agent/core.py:1-30]()\n\n## Agent Initialization\n\n### Constructor Parameters\n\nThe Agent class accepts the following core parameters during initialization:\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `name` | `str` | Yes | - | Unique identifier for the agent |\n| `description` | `str` | Yes | - | Human-readable description of agent's role |\n| `instructions` | `str` | Yes | - | Instructions file path or inline text |\n| `files_folder` | `str` | No | `None` | Path to files for vector store upload |\n| `schemas_folder` | `str` | No | `None` | Path to OpenAPI schema files |\n| `tools` | `list[Tool]` | No | `[]` | List of tool instances to attach |\n| `tools_folder` | `str` | No | `None` | Directory to auto-load tools from |\n| `model` | `str` | No | `\"gpt-5.4\"` | OpenAI model identifier |\n| `model_settings` | `ModelSettings` | No | `None` | Configuration for temperature, max_tokens, etc. |\n| `response_format` | `ResponseFormat` | No | `None` | Output format specification |\n\n资料来源：[src/agency_swarm/agent/core.py:50-120]()\n\n### Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Agent\n participant FileManager\n participant ToolLoader\n participant SchemaParser\n \n User->>Agent: __init__(params)\n Agent->>Agent: _validate_params()\n Agent->>FileManager: _init_files()\n Agent->>ToolLoader: _load_tools_from_folder()\n Agent->>SchemaParser: _parse_schemas()\n Agent-->>User: Agent instance\n```\n\nThe initialization process follows these steps:\n\n1. **Parameter Validation**: All required parameters are validated\n2. **File Manager Setup**: Files in `files_folder` are prepared for upload\n3. **Tool Loading**: Tools are loaded from both the `tools` parameter and `tools_folder`\n4. **Schema Parsing**: OpenAPI schemas in `schemas_folder` are converted to tools\n\n资料来源：[src/agency_swarm/agent/initialization.py:1-80]()\n\n### Model Configuration\n\nAgents support various OpenAI models with appropriate default settings:\n\n```python\n# Reasoning models (e.g., o3, o4-mini) - no temperature\nmodel=\"gpt-5.4\"\nmodel_settings=ModelSettings(\n reasoning=Reasoning(effort=\"medium\")\n)\n\n# Non-reasoning models - temperature defaults to 0.3\nmodel=\"gpt-4o\"\nmodel_settings=ModelSettings(\n temperature=0.3,\n max_tokens=25000\n)\n```\n\n资料来源：[src/agency_swarm/utils/create_agent_template.py:40-70]()\n\n## Tools Management\n\n### Tool Types\n\nThe framework supports two primary tool paradigms:\n\n| Type | Base Class | Use Case |\n|------|------------|----------|\n| `BaseTool` | Abstract class | Complex tools with custom state and validation |\n| `FunctionTool` | Decorator-based | Simple functions wrapped as tools |\n\n### BaseTool Implementation\n\n`BaseTool` subclasses must implement the following interface:\n\n```python\nfrom agency_swarm.tools import BaseTool\n\nclass MyTool(BaseTool):\n name: str = \"my_tool\"\n description: str = \"Description of what the tool does\"\n \n def run(self) -> str:\n \"\"\"Execute the tool's primary function.\"\"\"\n return \"result\"\n```\n\n资料来源：[src/agency_swarm/agent/tools.py:1-50]()\n\n### FunctionTool Decorator\n\nFor simpler use cases, the `@function_tool` decorator wraps regular Python functions:\n\n```python\nfrom agency_swarm import function_tool\n\n@function_tool\ndef calculate(expression: str) -> str:\n \"\"\"Evaluate a mathematical expression.\"\"\"\n return str(eval(expression))\n```\n\n### Tool Loading from Folder\n\nThe `_load_tools_from_folder()` method dynamically imports tools from a directory structure:\n\n```\nAgentName/tools/\n├── __init__.py\n├── MyTool.py\n└── AnotherTool.py\n```\n\nThe loader:\n- Scans the folder for Python files\n- Imports classes inheriting from `BaseTool`\n- Includes `FunctionTool` instances defined in `__init__.py`\n- Adds all discovered tools to the agent's toolset\n\n资料来源：[src/agency_swarm/agent/core.py:100-120]()\n\n### OpenAPI Schema Parsing\n\nAgents can automatically convert OpenAPI schemas into callable tools:\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# From file\ntools = ToolFactory.from_openapi_schema(\n openapi_schema=json.load(open(\"schema.json\"))\n)\n\n# From URL\ntools = ToolFactory.from_openapi_schema(\n requests.get(\"https://api.example.com/openapi.json\").json()\n)\n```\n\nThe `_parse_schemas()` method processes schemas from `schemas_folder` and creates corresponding tools.\n\n资料来源：[README.md:50-80]()\n\n## Execution Flow\n\n### Core Execution Method\n\nThe `get_response()` method is the primary interface for agent execution:\n\n```mermaid\ngraph LR\n A[Message Input] --> B[Context Override]\n B --> C[Run Hooks]\n C --> D[OpenAI API Call]\n D --> E[Tool Execution]\n E --> D\n D --> F[Output Processing]\n F --> G[Response Format]\n G --> H[RunResult]\n```\n\n### Method Signature\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### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `message` | `str \\| list[TResponseInputItem]` | Input message or list of message items |\n| `sender_name` | `str \\| None` | Name of the sending agent (for agent-to-agent) |\n| `context_override` | `dict \\| None` | Override agency context values |\n| `hooks_override` | `RunHooks \\| None` | Custom hooks for this execution |\n| `run_config_override` | `RunConfig \\| None` | Custom run configuration |\n| `file_ids` | `list[str] \\| None` | Pre-uploaded file IDs to include |\n| `additional_instructions` | `str \\| None` | Extra instructions appended to agent prompt |\n| `agency_context` | `AgencyContext \\| None` | Context from parent agency |\n\n资料来源：[src/agency_swarm/agent/core.py:150-200]()\n\n### Run Result\n\nThe execution returns a `RunResult` object containing:\n\n- `messages`: Conversation history\n- `final_output`: Text response from the model\n- `tool_calls`: List of tool invocations made\n- `usage`: Token and cost information\n\n## Execution Guardrails\n\nGuardrails provide validation hooks at the input and output boundaries of agent execution.\n\n### Guardrail Interface\n\n```python\nclass BaseExecutionGuardrail(ABC):\n @abstractmethod\n async def validate(\n self,\n agent: Agent,\n messages: list[Message],\n ) -> tuple[bool, str | None]:\n \"\"\"Validate input or output. Returns (passed, error_message).\"\"\"\n pass\n```\n\n### Guardrail Pipeline\n\n```mermaid\ngraph TD\n A[Input Messages] --> B[Input Guardrails]\n B -->|pass| C[Execute Agent]\n B -->|fail| D[Return Error]\n C --> E[Output Processing]\n E --> F[Output Guardrails]\n F -->|pass| G[Return Result]\n F -->|fail| D\n \n style D fill:#ff6b6b\n style G fill:#51cf66\n```\n\n### Configuration\n\nGuardrails are configured per-agent:\n\n```python\nfrom agency_swarm.agent import Agent, InputGuardrail, OutputGuardrail\n\nagent = Agent(\n name=\"SecureAgent\",\n instructions=\"...\",\n input_guardrails=[MyInputGuardrail()],\n output_guardrails=[MyOutputGuardrail()],\n)\n```\n\n资料来源：[src/agency_swarm/agent/execution_guardrails.py:1-60]()\n\n## File Handling\n\n### File Manager Integration\n\nAgents can manage files for upload to OpenAI's vector stores:\n\n```python\nagent = Agent(\n name=\"Researcher\",\n instructions=\"...\",\n files_folder=\"./files\",\n)\n```\n\n### Upload Method\n\n```python\ndef upload_file(\n self,\n file_path: str,\n include_in_vector_store: bool = True\n) -> str:\n \"\"\"Upload a file using the agent's file manager.\n \n Returns:\n str: The uploaded file ID\n \"\"\"\n if self.file_manager:\n return self.file_manager.upload_file(\n file_path,\n include_in_vector_store\n )\n raise RuntimeError(f\"Agent {self.name} has no file manager configured\")\n```\n\n资料来源：[src/agency_swarm/agent/core.py:130-145]()\n\n## Communication Patterns\n\n### Agent-to-Agent Messaging\n\nAgents communicate through defined flows using specialized message tools:\n\n```python\nfrom agency_swarm import Agency, Agent, SendMessage, Handoff\n\nceo = Agent(name=\"CEO\", ...)\ndeveloper = Agent(name=\"Developer\", ...)\n\nagency = Agency(\n ceo,\n developer,\n communication_flows=[\n (ceo > developer, SendMessage), # CEO sends to Developer\n (developer > ceo, Handoff), # Developer returns to CEO\n ]\n)\n```\n\n### Message Types\n\n| Type | Purpose |\n|------|---------|\n| `SendMessage` | Direct message with optional context |\n| `SendMessageWithContext` | Message preserving agency context |\n| `Handoff` | Transfer control back to calling agent |\n\n## Model Settings\n\nThe `ModelSettings` class configures LLM behavior:\n\n```python\nfrom agency_swarm import Agent, ModelSettings, Reasoning\n\nagent = Agent(\n name=\"Analyzer\",\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n temperature=0.3,\n max_tokens=25000,\n reasoning=Reasoning(effort=\"high\", summary=\"auto\"),\n top_p=0.9,\n ),\n)\n```\n\n### Settings Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `temperature` | `float` | `0.3` | Sampling temperature (0-2) |\n| `max_tokens` | `int` | varies | Maximum completion tokens |\n| `top_p` | `float` | `None` | Nucleus sampling threshold |\n| `reasoning` | `Reasoning` | `None` | Reasoning effort configuration |\n| `response_include` | `list` | `None` | Include additional metadata |\n\n资料来源：[src/agency_swarm/cli/utils/generate-agent-from-settings.ts:60-100]()\n\n## State Management\n\n### Agency Context\n\nAgents can share state through the `AgencyContext`:\n\n```python\nasync def get_response(\n self,\n message: str,\n context_override: dict[str, Any] | None = None,\n agency_context: AgencyContext | None = None,\n ...\n) -> RunResult:\n # Access shared context\n if agency_context:\n shared_data = agency_context.get(\"key\")\n```\n\n### Message History\n\nAgents maintain conversation history through `RunResult`:\n\n```python\nresult = await agent.get_response(\"Hello\")\nfor message in result.messages:\n print(f\"{message.role}: {message.content}\")\n```\n\n## CLI Integration\n\n### Agent Template Creation\n\nThe CLI provides utilities for generating agent templates:\n\n```bash\nagency-swarm create-agent-template \"Data Analyst\" \\\n --description \"Performs data analysis\" \\\n --model \"gpt-5.4-mini\" \\\n --reasoning \"medium\" \\\n --temperature 0.3\n```\n\nThis generates the standard folder structure:\n\n```\nDataAnalyst/\n├── DataAnalyst.py\n├── __init__.py\n├── instructions.md\n├── files/\n├── schemas/\n└── tools/\n```\n\n资料来源：[src/agency_swarm/cli/main.py:30-80]()\n\n## Summary\n\nThe Agent Internals architecture demonstrates a modular design where:\n\n1. **Initialization** handles setup of files, tools, and schemas\n2. **Tools Management** provides flexible tool creation and loading\n3. **Execution** manages the runtime loop with hooks and guardrails\n4. **Communication** enables multi-agent collaboration through defined flows\n5. **Configuration** supports various models with appropriate defaults\n\nThis architecture allows agents to serve as self-contained, configurable units that can participate in complex multi-agent workflows while maintaining clear separation of concerns.\n\n---\n\n\n\n## Tools System\n\n### 相关页面\n\n相关主题：[Getting Started Guide](#page-getting-started), [Agent Internals](#page-agent-internal), [Communication Flows](#page-communication-flows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/tools/base_tool.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/base_tool.py)\n- [src/agency_swarm/tools/__init__.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/__init__.py)\n- [src/agency_swarm/tools/tool_factory.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory.py)\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/PersistentShellTool.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/PersistentShellTool.py)\n \n\n# Tools System\n\n## Overview\n\nThe Tools System in Agency Swarm provides a flexible mechanism for extending agent capabilities through custom tool implementations. Agents can use tools to interact with external services, execute code, run shell commands, search the web, and perform various other tasks that extend beyond natural language processing.\n\nTools in Agency Swarm serve as the primary interface between agents and external functionality. They enable agents to:\n\n- Execute Python code in isolated environments\n- Run persistent shell commands\n- Search the web for information\n- Process and analyze files\n- Interact with external APIs via OpenAPI schemas\n\nThe system supports two primary tool creation patterns: inheriting from `BaseTool` class and using the `@function_tool` decorator. Additionally, tools can be auto-generated from OpenAPI schemas using `ToolFactory`.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Agent] --> B[Tools System]\n B --> C[BaseTool Subclass]\n B --> D[@function_tool Decorator]\n B --> E[ToolFactory]\n C --> F[IPythonInterpreter]\n C --> G[PersistentShellTool]\n C --> H[Custom Tool]\n E --> I[OpenAPI Schema]\n F --> J[Code Execution Environment]\n G --> K[Shell Session]\n```\n\n## Core Components\n\n### BaseTool Class\n\nThe `BaseTool` class is the foundation for all tools in Agency Swarm. It provides a standardized interface for tool definition and execution.\n\n**File:** `src/agency_swarm/tools/base_tool.py`\n\n**Key Responsibilities:**\n- Define tool schema for OpenAI API compatibility\n- Validate input parameters using Pydantic\n- Execute the tool's core functionality via `run()` method\n- Support async execution when needed\n\n**Structure:**\n\n| Component | Description |\n|-----------|-------------|\n| `ToolConfig` | Pydantic model defining tool metadata (name, description, parameters) |\n| `BaseTool` | Abstract base class for all tools |\n| `run()` | Abstract method for tool execution |\n| `get_schema()` | Returns OpenAI-compatible tool schema |\n\n### ToolFactory\n\nThe `ToolFactory` class enables automatic generation of tools from OpenAPI schemas. This allows integration with existing REST APIs without manual tool implementation.\n\n**File:** `src/agency_swarm/tools/tool_factory.py`\n\n**Usage Pattern:**\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# From local file\nwith open(\"schemas/your_schema.json\") as f:\n tools = ToolFactory.from_openapi_schema(f.read())\n\n# From remote URL\nimport requests\ntools = ToolFactory.from_openapi_schema(\n requests.get(\"https://api.example.com/openapi.json\").json()\n)\n```\n\n### Built-in Tools\n\nAgency Swarm includes several pre-built tools for common use cases.\n\n#### IPythonInterpreter\n\n**File:** `src/agency_swarm/tools/built_in/IPythonInterpreter.py`\n\nProvides Python code execution capabilities within an agency. Key features:\n\n- Executes Python code in a persistent environment\n- Maintains state between executions\n- Supports file operations and data processing\n- Integrates with agent workflows for data analysis tasks\n\n**Configuration Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `timeout` | int | 60 | Maximum execution time in seconds |\n| `working_directory` | str | None | Directory for file operations |\n\n#### PersistentShellTool\n\n**File:** `src/agency_swarm/tools/built_in/PersistentShellTool.py`\n\nProvides persistent shell command execution. Unlike one-off command runners, this tool maintains an active shell session across multiple tool calls.\n\n**Features:**\n- Persistent shell state between commands\n- Environment variable preservation\n- Working directory consistency\n- Command history tracking\n\n### Function Tool Decorator\n\nThe `@function_tool` decorator provides a lightweight alternative to `BaseTool` subclassing. It's ideal for simpler tools that don't require extensive configuration.\n\n**Pattern:**\n\n```python\nfrom agency_swarm.tools import function_tool\nfrom pydantic import Field\n\n@function_tool\ndef calculate(a: float, b: float, operation: str = Field(\n description=\"Operation to perform: add, subtract, multiply, divide\"\n)) -> str:\n \"\"\"Perform basic arithmetic operations.\"\"\"\n if operation == \"add\":\n return str(a + b)\n elif operation == \"subtract\":\n return str(a - b)\n elif operation == \"multiply\":\n return str(a * b)\n elif operation == \"divide\":\n if b == 0:\n return \"Error: Division by zero\"\n return str(a / b)\n return \"Unknown operation\"\n```\n\n## Creating Custom Tools\n\n### Method 1: Using BaseTool Class\n\nFor complex tools requiring detailed configuration:\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 is used by the agent to determine when to use this tool.\n \"\"\"\n \n # Define fields with descriptions using Pydantic Field\n example_field: str = Field(\n ..., description=\"Description of the example field explaining its purpose\"\n )\n \n def run(self):\n \"\"\"\n The implementation of the run method.\n \"\"\"\n # Tool logic here\n return f\"Result: {self.example_field}\"\n```\n\n### Method 2: Using @function_tool Decorator\n\nFor simpler tools:\n\n```python\nfrom agency_swarm.tools import function_tool\n\n@function_tool\ndef my_simple_tool(input_text: str) -> str:\n \"\"\"Process input text and return result.\"\"\"\n return input_text.upper()\n```\n\n### Method 3: From OpenAPI Schema\n\nFor API integration:\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# Generate tools from OpenAPI specification\ntools = ToolFactory.from_openapi_schema(openapi_schema_dict)\n\n# tools is a list of BaseTool instances\nfor tool in tools:\n print(tool.name, tool.description)\n```\n\n## Tool Integration with Agents\n\n### Adding Tools to Agents\n\nTools are passed to agents via the `tools` parameter during initialization:\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools import BaseTool, function_tool\n\n# Custom tool class\nclass DataProcessor(BaseTool):\n name: str = \"DataProcessor\"\n description: str = \"Processes data according to specified rules\"\n \n data: str = Field(description=\"Data to process\")\n rule: str = Field(description=\"Processing rule to apply\")\n \n def run(self):\n return f\"Processed {self.data} with rule {self.rule}\"\n\n# Function tool\n@function_tool\ndef calculator(a: float, b: float) -> float:\n return a + b\n\n# Create agent with tools\nagent = Agent(\n name=\"DataAgent\",\n description=\"Handles data processing tasks\",\n tools=[DataProcessor, calculator]\n)\n```\n\n### Tool Discovery from Folders\n\nAgents can automatically discover and load tools from a specified directory:\n\n```python\nagent = Agent(\n name=\"FileAgent\",\n description=\"Handles file operations\",\n tools_folder=\"./tools\" # Auto-loads all tools from this directory\n)\n```\n\nThis approach scans the specified folder for tool definitions and makes them available to the agent without explicit listing.\n\n## Tool Schema Generation\n\nEach tool automatically generates an OpenAI-compatible schema used for function calling:\n\n```mermaid\ngraph LR\n A[Tool Definition] --> B[Schema Generator]\n B --> C[OpenAI Tool Schema]\n C --> D[Agent System Prompt]\n D --> E[Model Function Calling]\n```\n\n**Schema Structure:**\n\n```json\n{\n \"type\": \"function\",\n \"function\": {\n \"name\": \"tool_name\",\n \"description\": \"Tool description\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {...},\n \"required\": [...]\n }\n }\n}\n```\n\n## Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Tool as Tool Instance\n participant Runtime as Tool Runtime\n \n Agent->>Tool: Calls tool with parameters\n Tool->>Tool: Validate parameters (Pydantic)\n Tool->>Runtime: Execute run() method\n Runtime-->>Tool: Return result\n Tool-->>Agent: Return tool result\n \n Note over Agent,Tool: Tool can be sync or async\n```\n\n## Testing Tools\n\nTools should include comprehensive test coverage. Tests are located in `agency_swarm/tests/test_tools.py`.\n\n**Test Template:**\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**Running Tool Tests:**\n\n```bash\nmake coverage\n```\n\n## CLI Tool Import\n\nAgency Swarm CLI provides built-in tool import functionality:\n\n```bash\n# List available built-in tools\nagency-swarm import-tool --list\n\n# Import a specific tool\nagency-swarm import-tool IPythonInterpreter --directory ./my_tools\n```\n\nThis command copies the selected tool's source files into the specified directory, allowing for customization.\n\n## Best Practices\n\n1. **Clear Descriptions**: Use descriptive docstrings that explain when and why the agent should use the tool\n2. **Field Documentation**: Every parameter field should have a clear `description` for agent understanding\n3. **Error Handling**: Implement proper error handling in the `run()` method\n4. **Type Safety**: Use Pydantic models for all parameters to ensure validation\n5. **Idempotency**: Design tools to be safely re-executable when possible\n6. **Resource Management**: Clean up resources (files, connections) after execution\n\n## File Structure\n\n```\nagency_swarm/tools/\n├── __init__.py # Public exports\n├── base_tool.py # BaseTool class definition\n├── tool_factory.py # ToolFactory for OpenAPI schemas\n├── function_tool.py # @function_tool decorator\n└── built_in/ # Pre-built tool implementations\n ├── IPythonInterpreter.py\n ├── PersistentShellTool.py\n └── ...\n```\n\n## Summary\n\nThe Tools System provides a comprehensive framework for extending agent capabilities in Agency Swarm. With support for custom tool creation, OpenAPI schema integration, and built-in tools for common tasks, developers can flexibly enhance their agents' functionality. The system leverages Pydantic for robust parameter validation and follows consistent patterns that make tool development straightforward and maintainable.\n\n---\n\n\n\n## Communication Flows\n\n### 相关页面\n\n相关主题：[Core Architecture](#page-core-architecture), [Tools System](#page-tools-system), [Messaging System](#page-messaging-system)\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/tools/send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py)\n- [src/agency_swarm/agent/agent_flow.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/agent_flow.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- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n \n\n# Communication Flows\n\n## Overview\n\nCommunication Flows define how agents interact with each other within an Agency. They establish the rules and pathways for agent-to-agent messaging, control transfers, and collaborative workflows. This system enables multi-agent collaboration by specifying which agents can communicate, through what mechanisms, and in what directions.\n\nCommunication Flows are a core architectural component of agency-swarm that transforms a collection of individual agents into a coordinated multi-agent system. Without explicit communication flows, agents cannot interact with each other—they can only respond to direct user input.\n\n## Core Concepts\n\n### Agent Communication Patterns\n\nAgency-swarm supports two primary communication mechanisms:\n\n| Pattern | Purpose | Use Case |\n|---------|---------|----------|\n| **SendMessage** | Direct message passing with optional context | Coordinated workflows, task delegation |\n| **Handoff** | Transfer of conversational control | Escalation, specialized handling, task completion |\n\n### Flow Directionality\n\nCommunication flows are directional, meaning you can specify asymmetric communication patterns:\n\n- **Unidirectional**: Agent A can send messages to Agent B, but not vice versa\n- **Bidirectional**: Agents can communicate in both directions\n- **Broadcast-capable**: Certain patterns allow multi-recipient messaging\n\n## Architecture\n\n### Flow Processing Pipeline\n\n```mermaid\ngraph TD\n A[User Input] --> B[Entry Point Agent]\n B --> C{Communication Flow Check}\n C -->|SendMessage| D[SendMessage Tool Execution]\n C -->|Handoff| E[Handoff Tool Execution]\n D --> F[Recipient Agent Processing]\n E --> G[Control Transfer to Recipient]\n F --> H{More Flows?}\n G --> H\n H -->|Yes| C\n H -->|No| I[Final Response]\n```\n\n### Flow Definition in Agency Class\n\nThe `Agency` class in `src/agency_swarm/agency/core.py` manages communication flows through the `communication_flows` parameter:\n\n```python\nAgency(\n agents,\n communication_flows=[...],\n shared_instructions=\"...\",\n send_message_tool_class=SendMessage\n)\n```\n\n资料来源：[examples/agency_visualization.py:25-35]()\n\n### Flow Tuple Structure\n\nCommunication flows are defined as tuples with the following structure:\n\n```python\ncommunication_flows=[\n (agent_a > agent_b), # Simple unidirectional\n (agent_c < agent_d), # Reverse direction\n (agent_e > agent_f, Handoff), # With specific tool class\n (agent_g < agent_h > agent_i), # Multi-agent chain\n]\n```\n\n## Configuration Options\n\n### Basic Flow Definition\n\nSimple directional flows use the default `SendMessage` tool:\n\n```python\nfrom agency_swarm import Agent, Agency\n\nceo = Agent(name=\"CEO\", instructions=\"Manage the workflow\")\ndeveloper = Agent(name=\"Developer\", instructions=\"Write code\")\n\nagency = Agency(\n ceo,\n developer,\n communication_flows=[\n (ceo > developer), # CEO can delegate to Developer\n (developer > ceo), # Developer can report back to CEO\n ]\n)\n```\n\n### Handoff-Based Flows\n\nHandoffs transfer conversational control to another agent:\n\n```python\nfrom agency_swarm.tools import Handoff\n\nsupport = Agent(name=\"Support\", instructions=\"Handle basic queries\")\nspecialist = Agent(name=\"Specialist\", instructions=\"Handle complex issues\")\n\nagency = Agency(\n support,\n specialist,\n communication_flows=[\n (support > specialist, Handoff), # Support escalates to Specialist\n ]\n)\n```\n\n资料来源：[examples/interactive/tui.py:48-52]()\n\n### Custom SendMessage Classes\n\nFor flows requiring additional context passing, use custom SendMessage classes:\n\n```python\nfrom agency_swarm.tools import SendMessage\nfrom agency_swarm import Agent, Agency\n\nclass SendMessageWithContext(SendMessage):\n \"\"\"Custom SendMessage that includes context about key decisions.\"\"\"\n pass\n\ncoordinator = Agent(name=\"Coordinator\", instructions=\"Coordinate tasks\")\nspecialist = Agent(name=\"Specialist\", instructions=\"Execute specialized tasks\")\n\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 send_message_tool_class=SendMessageWithContext,\n)\n```\n\n资料来源：[examples/custom_send_message.py:20-32]()\n\n### Multi-Agent Communication Chains\n\nComplex workflows can involve multiple agents in a single flow definition:\n\n```python\ndev = Agent(name=\"Developer\", instructions=\"Write code\")\nqa = Agent(name=\"QA\", instructions=\"Test code\")\npm = Agent(name=\"PM\", instructions=\"Manage project\")\n\nagency = Agency(\n dev,\n qa,\n pm,\n communication_flows=[\n (dev < ceo > pm > dev), # Multi-agent chain with CEO\n (dev > qa, Handoff), # Developer can hand off to QA\n ]\n)\n```\n\n资料来源：[examples/agency_visualization.py:25-35]()\n\n## Flow Visualization\n\nThe Agency class provides visualization capabilities for communication flows:\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\nThis generates an interactive HTML visualization showing:\n\n- Agent nodes and their connections\n- Communication flow directions\n- Tool availability per agent\n- Entry point indicators\n\n## SendMessage Tool Reference\n\n### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `recipient` | Agent | Yes | Target agent for the message |\n| `message` | str | Yes | Content to send |\n| `images` | list | No | Image attachments |\n| `files` | list | No | File attachments |\n\n### Configuration via Agency\n\nSet default behavior for all flows:\n\n```python\nagency = Agency(\n agent_a,\n agent_b,\n communication_flows=[agent_a > agent_b],\n send_message_tool_class=CustomSendMessage, # Default for all flows\n)\n```\n\n资料来源：[src/agency_swarm/tools/send_message.py]()\n\n## Handoff Tool Reference\n\n### Behavior\n\nWhen an agent executes a Handoff:\n\n1. Current agent's response is terminated\n2. Control transfers to the target agent\n3. Original message context is preserved\n4. Target agent receives the conversation state\n\n### Use Cases\n\n| Scenario | Benefit |\n|----------|---------|\n| Escalation | Route to specialized agents |\n| Task completion | Transfer to confirmation agent |\n| Parallel processing | Split work across specialists |\n\n## Shared Instructions\n\nCommunication flows can leverage shared instructions for consistent behavior:\n\n```python\nagency = Agency(\n coordinator,\n specialist,\n communication_flows=[coordinator > specialist],\n shared_instructions=\"All agents should use key decisions to guide their actions.\",\n)\n```\n\nShared instructions are available to all agents in the agency and provide context for communication decisions.\n\n## Best Practices\n\n### Flow Design Principles\n\n1. **Explicit Over Implicit**: Always define flows explicitly rather than relying on defaults\n2. **Minimal Paths**: Only create necessary communication pathways\n3. **Directional Clarity**: Design flows with clear escalation paths\n4. **Context Preservation**: Use custom SendMessage classes when context matters\n\n### Security Considerations\n\n- Limit communication flows to only necessary agent pairs\n- Use shared instructions to establish boundaries\n- Review flow visualizations for unintended pathways\n\n### Performance\n\n- Avoid circular flows without exit conditions\n- Limit the depth of multi-agent chains\n- Consider async patterns for long-running workflows\n\n## Example: Complete Multi-Agent Workflow\n\n```python\nfrom agency_swarm import Agent, Agency\nfrom agency_swarm.tools import SendMessage, Handoff\n\n# Define agents\nceo = Agent(\n name=\"CEO\",\n instructions=\"You manage the overall workflow and delegate tasks.\"\n)\ncoordinator = Agent(\n name=\"Coordinator\", \n instructions=\"Coordinate between teams and track progress.\"\n)\ndeveloper = Agent(\n name=\"Developer\",\n instructions=\"Implement technical solutions.\"\n)\nqa = Agent(\n name=\"QA\",\n instructions=\"Test and validate deliverables.\"\n)\n\n# Create agency with communication flows\nagency = Agency(\n ceo, # Entry point (positional argument)\n coordinator,\n developer,\n qa,\n communication_flows=[\n (ceo > coordinator), # CEO delegates to Coordinator\n (coordinator > developer), # Coordinator assigns to Developer\n (coordinator > qa), # Coordinator assigns to QA\n (developer > qa, Handoff), # Developer hands off to QA for testing\n (qa > coordinator), # QA reports back to Coordinator\n (coordinator > ceo), # Coordinator reports to CEO\n ],\n shared_instructions=\"Follow the standard workflow: develop, test, then report.\"\n)\n\n# Execute workflow\nasync def main():\n result = await agency.get_response(\"Start the Q4 optimization project.\")\n print(result.final_output)\n```\n\n## See Also\n\n- [Agent Documentation](agents) - Individual agent configuration\n- [Tools Reference](tools) - SendMessage and Handoff tools\n- [Agency Visualization](visualization) - Interactive flow visualization\n- [FastAPI Integration](fastapi-integration) - Deploying agencies with communication flows\n\n---\n\n\n\n## Context Management\n\n### 相关页面\n\n相关主题：[Core Architecture](#page-core-architecture), [Agent Internals](#page-agent-internal), [Messaging System](#page-messaging-system)\n\n\nRelevant Source Files
\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- [examples/agency_context.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_context.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- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n \n\n# Context Management\n\n## Overview\n\nContext Management in Agency Swarm refers to the mechanisms by which state, instructions, and runtime data are shared and propagated across agents within an agency. This system enables multi-agent collaboration by allowing agents to access shared information, communicate effectively, and maintain coherent workflows across complex task execution pipelines.\n\nThe context management architecture supports multiple layers of data sharing:\n\n1. **Agency-level shared instructions** that apply to all agents\n2. **Per-agent instructions** for role-specific guidance\n3. **Runtime context propagation** through the `AgencyContext` type\n4. **Message context** for passing additional data through communication flows\n\n资料来源：[examples/agency_context.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_context.py) \n资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n---\n\n## Core Context Types\n\n### AgencyContext\n\nThe `AgencyContext` type serves as the runtime container for contextual data passed between agents during execution. It flows through the agency hierarchy and is available to all agents during their turn in the conversation loop.\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, # Context from agency, or None for standalone\n **kwargs: Any,\n) -> RunResult:\n```\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `message` | `str \\| list[TResponseInputItem]` | The input message or list of message items |\n| `sender_name` | `str \\| None` | Identifier of the sending agent or user |\n| `context_override` | `dict[str, Any] \\| None` | Override values merged into context |\n| `agency_context` | `AgencyContext \\| None` | Context from agency, or None for standalone agents |\n\n资料来源：[src/agency_swarm/agent/core.py:35-54](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n---\n\n## Shared Instructions\n\n### Purpose and Scope\n\nShared instructions are a foundational context mechanism that applies uniform behavioral guidance across all agents within an agency. When an agent is instantiated as part of an agency, these instructions are prepended to the agent's individual instructions.\n\n```python\nreturn Agency(\n support,\n math,\n communication_flows=[(support, math, Handoff)],\n shared_instructions=\"Demonstrate reasoning, web search, file search, and handoffs.\",\n name=\"TuiDemoAgency\",\n)\n```\n\n### Behavior\n\n- **Precedence**: Individual agent instructions take precedence, but shared instructions provide foundational context\n- **Propagation**: Shared instructions are visible to all agents in the agency\n- **Use Cases**: Agency-wide policies, common procedures, general guidelines for all agents\n\n资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n---\n\n## Context Propagation Flow\n\n```mermaid\ngraph TD\n A[User Input / Agent Message] --> B{Agency.get_response}\n B --> C[Initialize AgencyContext]\n C --> D[Load Shared Instructions]\n D --> E[Load Agent-specific Instructions]\n E --> F[Merge context_override if provided]\n F --> G[Execute Agent Turn]\n G --> H[Run Tools if needed]\n H --> I[Communicate via SendMessage]\n I --> J{Communication Flow defined?}\n J -->|Yes| K[Pass AgencyContext to target agent]\n J -->|No| L[Return RunResult]\n K --> G\n L --> M[Final Output]\n\n style C fill:#e1f5fe\n style D fill:#fff3e0\n style F fill:#e8f5e9\n```\n\n---\n\n## Communication Flows and Context\n\n### SendMessageWithContext\n\nWhen agents communicate through defined flows, they can pass additional contextual data using `SendMessageWithContext`. This allows the sending agent to inject specific data into the recipient's context before processing.\n\n```python\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### Key Communication Patterns\n\n| Pattern | Class | Context Behavior |\n|---------|-------|------------------|\n| Direct Message | `SendMessage` | Basic message passing |\n| Message with Context | `SendMessageWithContext` | Includes additional context data |\n| Agent Handoff | `Handoff` | Transfers full control to another agent |\n\n资料来源：[examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n\n---\n\n## Context Override Mechanism\n\nThe `context_override` parameter allows runtime modification of the context dictionary. This is particularly useful when specific values need to be injected into an agent's execution context without modifying the core agency configuration.\n\n```python\ncontext_override: dict[str, Any] | None = None\n```\n\n**Use Cases:**\n\n1. Injecting user-specific data for a particular interaction\n2. Providing one-time instructions for a specific task\n3. Overriding default values based on runtime conditions\n\n资料来源：[src/agency_swarm/agent/core.py:40](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n---\n\n## Context in Multi-Agent Workflows\n\n### Agency-Level Context Example\n\nThe following demonstrates a complete context management pattern in a multi-agent setup:\n\n```python\ndef create_demo_agency():\n support = Agent(\n name=\"SupportAgent\",\n description=\"Handles user support requests with file search and web search.\",\n instructions=(\n \"You are a helpful support agent. Use your tools to assist users. \"\n \"You can analyze files and search the web to find answers. \"\n \"You can also use the calculate tool for math. \"\n \"When the user asks about something you don't know, use the web search tool to \"\n \"inspect them before answering.\"\n ),\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 conversation_starters=[\n \"Tell me about daily_revenue_report.pdf.\",\n \"Search the web for the latest Bun release notes.\",\n \"What is 345 * 18?\",\n \"Compare research_report.txt with daily_revenue_report.pdf.\",\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(reasoning=Reasoning(effort=\"high\", summary=\"auto\")),\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 name=\"TuiDemoAgency\",\n )\n```\n\n**Context Flow in This Example:**\n\n1. **Shared Instructions**: \"Demonstrate reasoning, web search, file search, and handoffs.\" applies to both agents\n2. **Communication Flow**: SupportAgent can hand off to MathAgent for calculation tasks\n3. **Agent-Specific Instructions**: Each agent has its own detailed instructions\n4. **Tool Context**: Each agent has access to specific tools with their own execution contexts\n\n资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n---\n\n## Context and Visualization\n\nThe agency visualization feature can display communication flows and context relationships:\n\n```python\nagency = create_demo_agency()\n\n# Generate interactive HTML visualization\nhtml_file = agency.visualize(\n output_file=\"agency_interactive_demo.html\",\n include_tools=True,\n open_browser=True,\n)\n```\n\nThis visualization shows:\n- How context flows between agents\n- Communication flow definitions\n- Entry points where context originates\n- Tool relationships within the context\n\n资料来源：[examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n\n---\n\n## Summary Table: Context Management Components\n\n| Component | Type | Scope | Purpose |\n|-----------|------|-------|---------|\n| `AgencyContext` | Class | Runtime | Container for runtime contextual data |\n| `shared_instructions` | Parameter | Agency-wide | Instructions applying to all agents |\n| `context_override` | Parameter | Per-call | Runtime injection of context values |\n| `additional_instructions` | Parameter | Per-call | Supplemental instructions for single execution |\n| `SendMessageWithContext` | Class | Communication | Pass context through agent messaging |\n\n---\n\n## Best Practices\n\n1. **Use Shared Instructions Sparingly**: Keep shared instructions concise and universally applicable\n2. **Leverage context_override for One-time Data**: Avoid modifying core configuration for transient data\n3. **Define Clear Communication Flows**: Explicit flows ensure predictable context propagation\n4. **Document Agent Instructions**: Clear instructions reduce ambiguity in context interpretation\n5. **Use Handoffs for Complete Transfers**: When full control should pass to another agent, use Handoff instead of basic messaging\n\n---\n\n\n\n## Messaging System\n\n### 相关页面\n\n相关主题：[Communication Flows](#page-communication-flows), [Context Management](#page-context-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/messages/__init__.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/__init__.py)\n- [src/agency_swarm/messages/message_formatter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/message_formatter.py)\n- [src/agency_swarm/messages/message_filter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/message_filter.py)\n- [src/agency_swarm/messages/response_input_sanitizer.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/response_input_sanitizer.py)\n- [src/agency_swarm/agent/execution_streaming.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/execution_streaming.py)\n \n\n# Messaging System\n\nThe Messaging System in Agency Swarm is a foundational layer responsible for handling all communication between agents, users, and external systems. It manages message formatting, filtering, sanitization, streaming, and conversion to ensure reliable and secure inter-agent communication.\n\n## Architecture Overview\n\nThe messaging system consists of several interconnected modules that process messages at different stages of agent execution.\n\n```mermaid\ngraph TD\n A[User/Agent Input] --> B[Message Filter]\n B --> C[Response Input Sanitizer]\n C --> D[Message Formatter]\n D --> E[Agent Core]\n E --> F[Execution Streaming]\n F --> G[Output Messages]\n \n H[Tool Calls] --> D\n I[Guardrails] --> D\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `__init__.py` | `messages/__init__.py` | Module exports and public API |\n| `message_formatter.py` | `messages/message_formatter.py` | Formats messages for different contexts |\n| `message_filter.py` | `messages/message_filter.py` | Filters and validates incoming messages |\n| `response_input_sanitizer.py` | `messages/response_input_sanitizer.py` | Sanitizes input for security |\n| `execution_streaming.py` | `agent/execution_streaming.py` | Handles streaming responses |\n\n## Message Flow Pipeline\n\nMessages traverse a multi-stage pipeline before reaching their destination. Each stage performs specific transformations or validations.\n\n```mermaid\ngraph LR\n subgraph Input_Processing\n F1[Filter] --> F2[Sanitize] --> F3[Format]\n end\n \n subgraph Core_Processing\n F3 --> F4[Agent Execution]\n end\n \n subgraph Output_Processing\n F4 --> F5[Streaming Output]\n end\n```\n\n### Stage 1: Message Filtering\n\nThe `MessageFilter` class provides initial validation and filtering capabilities for incoming messages. It ensures that messages meet basic structural requirements before further processing.\n\n资料来源：[src/agency_swarm/messages/message_filter.py:1-50]()\n\n### Stage 2: Input Sanitization\n\nThe `ResponseInputSanitizer` module sanitizes user input to prevent injection attacks and ensure compatibility with the OpenAI API response format requirements.\n\n```python\n# Sanitization removes or escapes potentially harmful content\nsanitized_input = ResponseInputSanitizer.sanitize(raw_message)\n```\n\n资料来源：[src/agency_swarm/messages/response_input_sanitizer.py:1-30]()\n\n### Stage 3: Message Formatting\n\nThe `MessageFormatter` handles the final transformation of messages, adapting them for different contexts such as agent-to-agent communication, tool execution, or user display.\n\n资料来源：[src/agency_swarm/messages/message_formatter.py:1-40]()\n\n## Streaming Execution\n\nThe streaming system provides real-time message delivery during agent execution, enabling responsive user experiences.\n\n### Streaming Architecture\n\n```mermaid\ngraph TD\n A[get_response_stream] --> B[StreamingRunResponse]\n B --> C[Event Stream]\n C --> D[text/event-stream]\n D --> E[Client Application]\n \n F[RunResult] --> G[new_items]\n G --> H[message_history]\n H --> I[Final Output]\n```\n\n### Streaming Methods\n\n| Method | Return Type | Purpose |\n|--------|-------------|---------|\n| `get_response_stream()` | `StreamingRunResponse` | Initiates streaming execution |\n| `get_response()` | `RunResult` | Returns complete result after execution |\n\n资料来源：[src/agency_swarm/agent/core.py:100-130]()\n\n### Streaming Configuration\n\nThe streaming system integrates with the execution layer to provide real-time updates:\n\n```python\ndef get_response_stream(\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) -> StreamingRunResponse:\n```\n\n资料来源：[src/agency_swarm/agent/core.py:130-160]()\n\n## Message Conversion\n\nThe system includes utilities for converting between different message formats, particularly between internal `RunItem` objects and OpenAI-compatible `TResponseInputItem` format.\n\n### RunItem to TResponseInputItem Conversion\n\n```mermaid\ngraph TD\n A[RunItem] --> B[run_item_to_tresponse_input_item]\n B --> C{TResponseInputItem}\n \n C --> D[message]\n C --> E[image_url]\n C --> F[tool_call]\n C --> E[tool_result]\n```\n\nThe conversion function uses the SDK's built-in conversion method:\n\n```python\ndef run_item_to_tresponse_input_item(item: RunItem) -> TResponseInputItem | None:\n try:\n converted_item = item.to_input_item()\n return converted_item\n except Exception as e:\n logger.warning(f\"Failed to convert {type(item).__name__}\")\n return None\n```\n\n资料来源：[src/agency_swarm/agent/execution_helpers.py:80-100]()\n\n## Message Types and Structures\n\n### TResponseInputItem Format\n\nThe system uses `TResponseInputItem` for message representation, supporting multiple content types:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `role` | `str` | Message role (user, assistant, system) |\n| `content` | `str` | Text content |\n| `name` | `str` | Sender name |\n| `tool_calls` | `list` | Tool call requests |\n| `tool_call_id` | `str` | Tool result identifier |\n\n### RunResult Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `input` | `list` | Original input messages |\n| `new_items` | `list[RunItem]` | New items generated during run |\n| `raw_responses` | `list` | Raw API responses |\n| `final_output` | `Any` | Processed final output |\n| `input_guardrail_results` | `list` | Input validation results |\n| `output_guardrail_results` | `list` | Output validation results |\n\n资料来源：[src/agency_swarm/agent/execution_helpers.py:50-75]()\n\n## Context Management\n\n### AgencyContext\n\nThe `AgencyContext` provides shared context for message processing across agents:\n\n```mermaid\ngraph TD\n A[AgencyContext] --> B[Shared State]\n A --> C[Agent Registry]\n A --> D[Communication Flows]\n A --> E[Message History]\n```\n\nContext is automatically created for standalone agent usage:\n\n```python\nif agency_context is None:\n agency_context = self._create_minimal_context()\n```\n\n资料来源：[src/agency_swarm/agent/core.py:85-95]()\n\n## Integration with Agent Execution\n\n### Execution Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Agent\n participant MessageSystem\n participant OpenAI_API\n \n User->>Agent: get_response(message)\n Agent->>MessageSystem: Filter & Sanitize\n MessageSystem->>MessageSystem: Format\n Agent->>OpenAI_API: Run Request\n OpenAI_API-->>Agent: Streaming Events\n Agent->>MessageSystem: Convert RunItem\n MessageSystem->>User: Final Output\n```\n\n### Method Signatures\n\n**Async Response Method:**\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**Streaming Response Method:**\n```python\ndef get_response_stream(\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) -> StreamingRunResponse:\n```\n\n资料来源：[src/agency_swarm/agent/core.py:95-160]()\n\n## Configuration Options\n\n### RunConfig Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `temperature` | `float` | `None` | Sampling temperature |\n| `top_p` | `float` | `None` | Nucleus sampling threshold |\n| `reasoning` | `Reasoning` | `None` | Reasoning configuration |\n| `max_tokens` | `int` | `None` | Maximum output tokens |\n\n### Message Filtering Options\n\n| Option | Description |\n|--------|-------------|\n| `strict_mode` | Enable strict validation |\n| `allowed_roles` | Restrict message roles |\n| `max_length` | Maximum message length |\n\n## Error Handling\n\nThe messaging system implements comprehensive error handling:\n\n```python\ntry:\n converted_item = item.to_input_item()\n logger.debug(f\"Converting {type(item).__name__} using SDK to_input_item()\")\n return converted_item\nexcept Exception as e:\n logger.warning(f\"Failed to convert {type(item).__name__}\")\n return None\n```\n\n资料来源：[src/agency_swarm/agent/execution_helpers.py:85-95]()\n\n## Usage Examples\n\n### Basic Message Flow\n\n```python\nfrom agency_swarm import Agent\n\nagent = Agent(name=\"Assistant\")\n\n# Synchronous message\nresult = await agent.get_response(\"Hello, how are you?\")\nprint(result.final_output)\n\n# Streaming message\nstream = agent.get_response_stream(\"Tell me a story\")\nfor event in stream:\n print(event, end=\"\", flush=True)\n```\n\n### Tool Message Handling\n\n```python\n# Tool results are automatically converted to message format\ntool_result = {\n \"tool_call_id\": \"call_abc123\",\n \"output\": \"File content here\"\n}\n# Converted to TResponseInputItem automatically\n```\n\n## Best Practices\n\n1. **Always provide `agency_context`** when agents communicate within an agency\n2. **Use streaming** for long-running operations to improve responsiveness\n3. **Implement guardrails** for input/output validation at the message level\n4. **Monitor message size** to prevent token limit issues\n5. **Handle conversion errors** gracefully with fallback mechanisms\n\n---\n\n\n\n## File Management\n\n### 相关页面\n\n相关主题：[Agent Internals](#page-agent-internal), [Tools System](#page-tools-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/agent/file_manager.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/file_manager.py)\n- [src/agency_swarm/agent/file_sync.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/file_sync.py)\n- [src/agency_swarm/agent/attachment_manager.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/attachment_manager.py)\n- [examples/agent_file_storage.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agent_file_storage.py)\n- [examples/message_attachments.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/message_attachments.py)\n \n\n# File Management\n\n## Overview\n\nFile Management in Agency Swarm provides a comprehensive system for handling file uploads, vector store creation, file search capabilities, and message attachments across multi-agent workflows. The system enables agents to work with persistent file storage, search through uploaded documents, and exchange files as part of their communication protocols.\n\nThe file management architecture consists of three primary components that work together to provide seamless file handling: `FileManager`, `FileSync`, and `AttachmentManager`. Each serves a distinct role in the file lifecycle from upload through search and message integration.\n\n资料来源：[examples/README.md]()\n\n## Core Components\n\n### FileManager\n\nThe `FileManager` class handles the core file operations for an agent, including uploading files to OpenAI's vector stores and managing file associations. It provides the primary interface for agents to work with persistent file storage.\n\n**Key Responsibilities:**\n- Upload files to OpenAI vector stores\n- Associate files with specific agents\n- Enable file search capabilities through vector store integration\n- Manage file lifecycle within agent contexts\n\n**API Reference:**\n\n| Method | Parameters | Return Type | Description |\n|--------|------------|-------------|-------------|\n| `upload_file` | `file_path: str`, `include_in_vector_store: bool = True` | `str` | Upload a file and optionally add to vector store |\n| `create_vector_store` | Various configuration params | `VectorStore` | Create a new vector store for the agent |\n\n资料来源：[src/agency_swarm/agent/core.py:68-73]()\n\n### FileSync\n\n`FileSync` manages the synchronization of files across agent instances, ensuring that file references remain consistent when agents share context or communicate. It handles the transfer and validation of file metadata between agents in an agency.\n\n### AttachmentManager\n\nThe `AttachmentManager` handles file attachments in messages, enabling agents to include files in their communications. This component supports multimodal outputs and file references within the message protocol.\n\n资料来源：[examples/message_attachments.py]()\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"File Management Architecture\"\n FM[FileManager] --> VS[Vector Store]\n FM --> A[Agent Instance]\n FS[FileSync] --> FM\n FS --> A2[Other Agents]\n AM[AttachmentManager] --> M[Messages]\n M --> A\n VS --> FSR[File Search Results]\n end\n \n subgraph \"External Services\"\n OpenAI[OpenAI API]\n OpenAI --> VS\n OpenAI --> M\n end\n```\n\n## File Upload Workflow\n\nFiles can be uploaded to an agent's context using the `upload_file` method. The workflow follows a sequential process:\n\n1. File is validated for existence and accessibility\n2. File is uploaded to OpenAI's storage system\n3. Optionally, file is indexed in a vector store for search\n4. File reference is associated with the agent's session\n\n```python\n# From agent instance\nagent = Agent(name=\"DocumentProcessor\", ...)\n\n# Upload file and include in vector store for search\nfile_id = agent.upload_file(\n file_path=\"documents/report.pdf\",\n include_in_vector_store=True\n)\n```\n\n资料来源：[src/agency_swarm/agent/core.py:68-73]()\n\n## Vector Store Integration\n\nAgency Swarm integrates with OpenAI's File Search tool through vector store creation. This enables agents to semantic search through uploaded documents.\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools import FileSearchTool\n\nagent = Agent(\n name=\"ResearchAgent\",\n description=\"Processes and searches through research documents\",\n tools=[FileSearchTool], # Enables semantic file search\n files_folder=\"./research_papers\",\n)\n```\n\n资料来源：[examples/agent_file_storage.py]()\n资料来源：[examples/README.md]()\n\n## File Handling in Messages\n\nThe AttachmentManager enables files to be included in agent messages, supporting multimodal interactions where agents can reference, process, and respond to file contents.\n\n**Supported File Types:**\n- Documents (PDF, TXT, MD)\n- Images (PNG, JPG, GIF)\n- Data files (CSV, JSON)\n- Code files\n\n**Output Types:**\n\n| Type | Description | Use Case |\n|------|-------------|----------|\n| `ToolOutputImage` | Image outputs from tools | Visualization, charts |\n| `ToolOutputFileContent` | File attachments in responses | Reports, generated documents |\n| `ToolOutputFileFromUrl` | Remote file serving | PDF reports, external data |\n\n资料来源：[examples/multimodal_outputs.py]()\n\n## Agent Folder Structure\n\nAgents that handle files should follow a specific folder structure:\n\n```\nAgentName/\n├── files/ # Files uploaded to OpenAI\n├── schemas/ # OpenAPI schemas for tool generation\n├── tools/ # Custom tool implementations\n├── AgentName.py # Main agent class\n├── __init__.py # Package initialization\n└── instructions.md # Agent instructions\n```\n\n资料来源：[CONTRIBUTING.md]()\n资料来源：[README.md]()\n\n## Configuration Options\n\n### Agent File Configuration\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `files_folder` | `str` | `None` | Path to folder containing files to upload |\n| `include_search_results` | `bool` | `False` | Include search results in responses |\n| `schemas_folder` | `str` | `None` | Path to OpenAPI schema files |\n\n### Model Settings for File Processing\n\nWhen processing files, consider adjusting model settings for better performance:\n\n```python\nfrom agency_swarm import Agent, ModelSettings\nfrom agency_swarm.util.builtins import Reasoning\n\nagent = Agent(\n name=\"FileAnalyzer\",\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]()\n\n## Examples\n\n### Vector Store Creation and File Search\n\n```python\n# Complete example from agent_file_storage.py\nfrom agency_swarm import Agent, Agency\n\n# Create agent with file search capability\ndocument_agent = Agent(\n name=\"DocumentAgent\",\n description=\"Handles document storage and search\",\n tools=[FileSearchTool], # Built-in tool for semantic search\n)\n\n# Agency with document handling\nagency = Agency([document_agent])\n\n# Upload documents for search\nresponse = agency.get_response_sync(\n \"Please analyze the quarterly_reports folder\"\n)\n```\n\n### Message Attachments\n\n```python\n# Example from message_attachments.py\nfrom agency_swarm.tools.utils import (\n tool_output_file_from_url,\n tool_output_image_from_path\n)\n\nclass GenerateReportTool(BaseTool):\n def run(self) -> ToolOutputFileContent:\n return tool_output_file_from_url(\n \"https://example.com/report.pdf\"\n )\n```\n\n资料来源：[examples/agent_file_storage.py]()\n资料来源：[examples/message_attachments.py]()\n\n## Best Practices\n\n1. **File Organization**: Maintain clean `files/` directories per agent to avoid confusion in multi-agent setups\n\n2. **Vector Store Management**: Only include files that need semantic search in vector stores to optimize costs and performance\n\n3. **File Size Limits**: Be mindful of OpenAI's file size limits (512 MB maximum per file)\n\n4. **Persistent Sessions**: Use `CustomizableChatHistory` for maintaining file context across sessions\n\n5. **Tool Output Efficiency**: Use `tool_output_file_from_url` for remote files instead of downloading and re-uploading\n\n资料来源：[examples/README.md]()\n资料来源：[examples/custom_persistence.py]()\n\n## Related Components\n\n| Component | File Path | Purpose |\n|-----------|-----------|---------|\n| BaseTool | `src/agency_swarm/tools/` | Custom tool creation with file outputs |\n| ToolFactory | `src/agency_swarm/tools/` | OpenAPI schema to tools conversion |\n| FileSearchTool | `src/agency_swarm/tools/` | Built-in semantic search capability |\n| OpenAI Integrations | `src/agency_swarm/integrations/` | External service file handling |\n\n## Summary\n\nThe File Management system in Agency Swarm provides a robust foundation for handling file operations across multi-agent workflows. By leveraging `FileManager` for core operations, `FileSync` for cross-agent synchronization, and `AttachmentManager` for message integration, developers can build sophisticated agentic systems that process, search, and communicate with files seamlessly.\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 项目说明书",
"目录",
"Introduction to Agency Swarm",
"Overview",
"Architecture Overview",
"Creating Agents",
"Tools System",
"Agency Structure",
"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- **Introduction to Agency Swarm**：importance `high`\n - source_paths: README.md, src/agency_swarm/__init__.py\n- **Installation and Setup**：importance `high`\n - source_paths: pyproject.toml, docs/welcome/installation.mdx, docs/welcome/getting-started/from-scratch.mdx\n- **Getting Started Guide**：importance `high`\n - source_paths: examples/tools.py, examples/multi_agent_workflow.py, examples/README.md\n- **Core Architecture**：importance `high`\n - source_paths: src/agency_swarm/agency/core.py, src/agency_swarm/agent/core.py, src/agency_swarm/agent/agent_flow.py\n- **Agent Internals**：importance `medium`\n - source_paths: src/agency_swarm/agent/core.py, src/agency_swarm/agent/initialization.py, src/agency_swarm/agent/tools.py, src/agency_swarm/agent/execution.py, src/agency_swarm/agent/execution_guardrails.py\n- **Tools System**：importance `high`\n - source_paths: src/agency_swarm/tools/base_tool.py, src/agency_swarm/tools/__init__.py, src/agency_swarm/tools/tool_factory.py, src/agency_swarm/tools/built_in/IPythonInterpreter.py, src/agency_swarm/tools/built_in/PersistentShellTool.py\n- **Communication Flows**：importance `high`\n - source_paths: src/agency_swarm/agency/core.py, src/agency_swarm/tools/send_message.py, src/agency_swarm/agent/agent_flow.py, examples/custom_send_message.py\n- **Context Management**：importance `medium`\n - source_paths: src/agency_swarm/context.py, src/agency_swarm/agent/context_types.py, examples/agency_context.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-15 11:07:28 UTC\n\n## 目录\n\n- [Introduction to Agency Swarm](#page-introduction)\n- [Installation and Setup](#page-installation)\n- [Getting Started Guide](#page-getting-started)\n- [Core Architecture](#page-core-architecture)\n- [Agent Internals](#page-agent-internal)\n- [Tools System](#page-tools-system)\n- [Communication Flows](#page-communication-flows)\n- [Context Management](#page-context-management)\n- [Messaging System](#page-messaging-system)\n- [File Management](#page-file-management)\n\n\n\n## Introduction to Agency Swarm\n\n### 相关页面\n\n相关主题：[Installation and Setup](#page-installation), [Getting Started Guide](#page-getting-started), [Core Architecture](#page-core-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- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\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/utils/create_agent_template.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)\n- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n- [src/agency_swarm/integrations/README.md](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/integrations/README.md)\n \n\n# Introduction to Agency Swarm\n\nAgency Swarm is a multi-agent orchestration framework designed for building autonomous AI agent systems that can collaborate, communicate, and delegate tasks between specialized agents. The framework enables developers to create complex workflows where multiple AI agents work together to accomplish tasks that require diverse capabilities.\n\n## Overview\n\nAgency Swarm provides a structured approach to building multi-agent systems with the following core capabilities:\n\n- **Agent Definition**: Create specialized agents with specific roles, instructions, and tools\n- **Inter-Agent Communication**: Enable agents to communicate and transfer control via handoffs\n- **Tool Integration**: Support for custom tools, OpenAPI schema conversion, and built-in capabilities\n- **Agency Management**: Orchestrate multiple agents within an agency context\n- **User Interfaces**: Multiple UI options including Terminal UI (TUI), Copilot UI, and visualization\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Architecture Overview\n\nThe framework is built around two primary concepts: **Agents** and **Agencies**. Agents represent individual AI workers with specific responsibilities, while Agencies coordinate multiple agents to accomplish complex tasks.\n\n```mermaid\ngraph TD\n A[User] --> B[Agency]\n B --> C[CEO Agent]\n C --> D[Developer Agent]\n C --> E[Support Agent]\n D --> F[Custom Tools]\n E --> G[WebSearch Tool]\n D --> H[File Management]\n E --> D\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n### Core Components\n\n| Component | Description | Location |\n|-----------|-------------|----------|\n| Agent | Base class for all agents with core execution methods | `src/agency_swarm/agent/core.py` |\n| Agency | Orchestrates multiple agents and their communication | Main orchestration layer |\n| Tool | Base class for custom tools and decorators | Tool infrastructure |\n| ModelSettings | Configuration for model parameters | Configuration layer |\n\n## Creating Agents\n\nAgents are the fundamental building blocks of Agency Swarm. Each agent has a name, description, instructions, tools, and model configuration.\n\n### Agent Folder Structure\n\n```\nAgentName/\n├── files/ # Files to upload to OpenAI\n├── schemas/ # OpenAPI schemas for tool generation\n├── tools/ # Agent-specific tools\n├── AgentName.py # Main agent class\n├── __init__.py # Package initialization\n└── instructions.md # Agent instruction document\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n### Agent Implementation Example\n\n```python\nfrom agency_swarm import Agent, ModelSettings\nfrom agency_swarm.tools.example import ExampleTool\n\nclass SupportAgent(Agent):\n def __init__(self):\n super().__init__(\n name=\"SupportAgent\",\n description=\"Handles customer support requests\",\n instructions=\"./instructions.md\",\n files_folder=\"./files\",\n tools=[ExampleTool],\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n temperature=0.3,\n max_tokens=25000,\n ),\n )\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n### Agent Core Methods\n\nThe `Agent` class provides several core execution methods for handling interactions:\n\n| Method | Description |\n|--------|-------------|\n| `get_response()` | Async method for running agent turns in conversation loop |\n| `get_response_sync()` | Synchronous wrapper for `get_response()` |\n| `upload_file()` | Upload files using the agent's file manager |\n\n资料来源：[src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n## Tools System\n\nAgency Swarm supports multiple tool definition patterns to give agents capabilities beyond plain text generation.\n\n### Tool Definition Patterns\n\n| Pattern | Description | Use Case |\n|---------|-------------|----------|\n| `@function_tool` decorator | Lightweight function-based tool | Quick tool definitions |\n| `BaseTool` subclass | Full Pydantic-based tool | Complex tools with validation |\n| `ToolFactory` | OpenAPI schema conversion | API integration |\n\n### BaseTool Implementation\n\n```python\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\n\nclass MyCustomTool(BaseTool):\n example_field: str = Field(\n ..., description=\"Description of the example field\"\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### OpenAPI Schema Conversion\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资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Agency Structure\n\nThe Agency class orchestrates multiple agents and defines how they communicate with each other.\n\n### Defining an Agency\n\n```python\nfrom agency_swarm import Agency, Agent\n\nceo = Agent(name=\"CEO\", ...)\ndeveloper = Agent(name=\"Developer\", ...)\nsupport = Agent(name=\"Support\", ...)\n\nagency = Agency(\n ceo,\n developer,\n support,\n communication_flows=[\n (ceo, developer), # CEO can delegate to Developer\n (ceo, support), # CEO can delegate to Support\n (support, developer), # Support can handoff to Developer\n ],\n shared_instructions=\"Agency-wide guidelines\",\n)\n```\n\n### Communication Flows\n\nCommunication flows define the allowed message paths between agents. The framework supports two primary communication patterns:\n\n| Pattern | Description |\n|---------|-------------|\n| `SendMessage` | Direct message passing between agents |\n| `Handoff` | Transfer of control to another agent |\n\n资料来源：[examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n\n## User Interfaces\n\nAgency Swarm provides multiple UI options for interacting with agencies.\n\n### Available UIs\n\n| UI Type | Description | Location |\n|---------|-------------|----------|\n| Terminal UI (TUI) | Command-line chat interface | `examples/interactive/tui.py` |\n| Copilot UI | Next.js-based copilot interface | `src/agency_swarm/ui/demos/copilot/` |\n| Visualization | HTML-based agency visualization | `src/agency_swarm/ui/templates/` |\n| FastAPI | REST API integration | `src/agency_swarm/integrations/` |\n\n### Terminal UI Example\n\n```python\nif __name__ == \"__main__\":\n create_demo_agency().tui(show_reasoning=True)\n```\n\n资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n## Running the Agency\n\n### Synchronous Execution\n\n```python\nagency = Agency(ceo, developer, support)\nresponse = agency.get_response_sync(\"Create a project skeleton\")\n```\n\n### Asynchronous Execution\n\n```python\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资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Model Configuration\n\nAgents can be configured with specific model settings for fine-tuned control over generation behavior.\n\n### ModelSettings Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `temperature` | float | 0.3 | Sampling temperature (0-2) |\n| `max_tokens` | int | None | Maximum tokens in response |\n| `top_p` | float | None | Nucleus sampling parameter |\n| `reasoning` | Reasoning | None | Reasoning effort for reasoning models |\n\n### Reasoning Models\n\nFor reasoning models (like o1 series), the framework automatically handles compatibility:\n\n- Temperature parameter is disabled for reasoning models\n- Reasoning effort can be configured via `ModelSettings(reasoning=Reasoning(effort=\"low\"))`\n\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\n## Integration with External Services\n\nAgency Swarm supports integration with external frameworks like FastAPI and OpenClaw.\n\n### FastAPI Integration\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资料来源：[src/agency_swarm/integrations/README.md](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/integrations/README.md)\n\n## Example Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Agency\n participant CEO\n participant Developer\n participant Support\n\n User->>Agency: Initial Request\n Agency->>CEO: Process Request\n CEO->>Support: Route to Support\n Support->>CEO: Needs Development\n CEO->>Developer: Delegate Task\n Developer-->>CEO: Task Complete\n CEO-->>Agency: Final Response\n Agency-->>User: Response\n```\n\n## Key Features Summary\n\n| Feature | Description |\n|---------|-------------|\n| Multi-Agent Orchestration | Coordinate multiple specialized agents |\n| Inter-Agent Communication | Built-in message passing and handoffs |\n| Tool System | Custom tools, OpenAPI conversion, built-in tools |\n| Model Flexibility | Support for various OpenAI models |\n| UI Options | TUI, Copilot, Visualization, FastAPI |\n| File Management | Vector stores and file search capabilities |\n| Streaming | Real-time response streaming |\n| Guardrails | Input and output validation |\n\n资料来源：[examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n\n## Getting Started\n\n1. Install Agency Swarm: `pip install agency-swarm`\n2. Create your first agent with the CLI: `agency-swarm create-agent`\n3. Define tools and instructions\n4. Compose agents into an agency\n5. Run the agency with `get_response_sync()` or async `get_response()`\n\n---\n\n\n\n## Installation and Setup\n\n### 相关页面\n\n相关主题：[Introduction to Agency Swarm](#page-introduction), [Getting Started Guide](#page-getting-started)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n- [src/agency_swarm/cli/main.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/main.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/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n \n\n# Installation and Setup\n\nThis guide covers how to install Agency Swarm, configure your development environment, and set up your first multi-agent project.\n\n## Prerequisites\n\nBefore installing Agency Swarm, ensure you have the following:\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| Python | 3.10+ | Required for async/await support |\n| pip / uv | Latest | Package manager |\n| OpenAI API Key | - | Set as environment variable |\n| Git | - | For cloning and version control |\n\n## Installation Methods\n\n### From PyPI (Recommended)\n\n```bash\npip install agency-swarm\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/VRSEN/agency-swarm.git\ncd agency-swarm\npip install -e .\n```\n\n### Development Installation\n\nFor contributors working on Agency Swarm itself:\n\n```bash\ngit clone https://github.com/VRSEN/agency-swarm.git\ncd agency-swarm\npip install -e \".[dev]\"\n```\n\n资料来源：[CONTRIBUTING.md:1-20]()\n\n## Environment Configuration\n\n### Required Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `OPENAI_API_KEY` | Your OpenAI API key | Yes |\n\n```bash\nexport OPENAI_API_KEY=\"sk-your-key-here\"\n```\n\nFor persistent configuration, add this to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.).\n\n### Optional Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `OPENAI_BASE_URL` | OpenAI default | Custom API endpoint |\n| `AGENCY_SWARM_LOG_LEVEL` | `INFO` | Logging verbosity |\n\n## CLI Installation and Setup\n\nAgency Swarm provides a command-line interface for agent creation and management.\n\n### Verify CLI Installation\n\n```bash\nagency-swarm --version\n```\n\n### CLI Command Reference\n\n资料来源：[src/agency_swarm/cli/main.py:1-50]()\n\n| Command | Description |\n|---------|-------------|\n| `agency-swarm create-agent` | Scaffold a new agent template |\n| `agency-swarm migrate-agent` | Generate agent from Assistants API settings.json |\n| `agency-swarm import-tool` | Import built-in tools into project |\n\n#### Create Agent Command Options\n\n```bash\nagency-swarm create-agent [AGENT_NAME] [options]\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--model` | string | `gpt-5.4` | Model identifier |\n| `--reasoning` | string | - | Reasoning effort level |\n| `--max-tokens` | int | - | Maximum completion tokens |\n| `--temperature` | float | `0.3` | Sampling temperature (non-reasoning models only) |\n| `--instructions` | string | - | Custom instructions for agent |\n| `--use-txt` | flag | False | Use .txt instead of .md for instructions |\n| `--path` | string | `./` | Output directory for agent template |\n\n资料来源：[src/agency_swarm/utils/create_agent_template.py:1-40]()\n\n#### Migrate Agent Command\n\n```bash\nagency-swarm migrate-agent path_to_settings.json [--output-dir DIR]\n```\n\nThis converts an OpenAI Assistant configuration into an Agency Swarm agent definition.\n\n资料来源：[src/agency_swarm/cli/main.py:80-95]()\n\n## Project Structure Setup\n\nWhen creating a new agent using the CLI, the following structure is generated:\n\n```\nagency_swarm/agents/AgentName/\n├── AgentName/\n│ ├── files/ # Files uploaded to OpenAI\n│ ├── tools/ # Agent-specific tools\n│ ├── schemas/ # OpenAPI schemas\n│ ├── AgentName.py # Main agent class\n│ ├── __init__.py # Package initialization\n│ └── instructions.md # Agent instructions\n```\n\n资料来源：[CONTRIBUTING.md:60-75]()\n\n### Agent Template Example\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-15]()\n\n## Tool Installation\n\nAgency Swarm provides pre-built tools that can be imported into your project.\n\n### List Available Tools\n\n```bash\nagency-swarm import-tool --list\n```\n\n### Import a Tool\n\n```bash\nagency-swarm import-tool ToolName [--directory ./tools]\n```\n\nTools are organized by category in the `agency_swarm/tools/` directory:\n\n```\nagency_swarm/tools/{category}/\n├── YourNewTool.py\n└── __init__.py\n```\n\n资料来源：[CONTRIBUTING.md:40-55]()\n\n## Development Dependencies\n\n### Install Dev Dependencies\n\n```bash\nmake sync\n```\n\n### Run Test Suite\n\n```bash\nmake coverage\n```\n\nThe `make coverage` command runs the test suite with coverage reporting.\n\n资料来源：[CONTRIBUTING.md:25-35]()\n\n## Quick Start: Your First Agency\n\n```mermaid\ngraph TD\n A[Install agency-swarm] --> B[Set OPENAI_API_KEY]\n B --> C[Create Agent Templates]\n C --> D[Define Communication Flows]\n D --> E[Initialize Agency]\n E --> F[Run get_response]\n```\n\n### Complete Example\n\n```python\nfrom agency_swarm import Agency, Agent\nfrom agency_swarm.tools import WebSearchTool\n\n# Create agents\nsupport = Agent(\n name=\"SupportAgent\",\n description=\"Handles user inquiries\",\n instructions=\"You are a helpful support agent.\",\n tools=[WebSearchTool()],\n model=\"gpt-5.4-mini\",\n)\n\n# Initialize agency\nagency = Agency(support)\n\n# Run\nresult = agency.get_response_sync(\"Hello!\")\n```\n\n资料来源：[examples/README.md:1-20]()\n\n## Troubleshooting\n\n### Common Installation Issues\n\n| Issue | Solution |\n|-------|----------|\n| `ModuleNotFoundError` | Reinstall: `pip install agency-swarm` |\n| Python version error | Ensure Python 3.10+ with `python --version` |\n| API key not found | Verify `OPENAI_API_KEY` environment variable |\n\n### Verify Installation\n\n```python\nimport agency_swarm\nprint(agency_swarm.__version__)\n```\n\n### Running Examples\n\nExamples are located in the `examples/` directory. Each can be run directly:\n\n```bash\ncd examples\npython multi_agent_workflow.py\n```\n\n资料来源：[examples/README.md:1-30]()\n\n## Next Steps\n\nAfter installation, explore:\n\n- [Getting Started Guide](/docs/getting-started/from-scratch.mdx) - Build your first agency\n- [Agent Communication](/docs/features/communication.mdx) - Configure agent-to-agent messaging\n- [Tool Development](/docs/features/tools.mdx) - Create custom tools\n- [FastAPI Integration](/docs/additional-features/fastapi-integration.mdx) - Deploy as API service\n\n---\n\n\n\n## Getting Started Guide\n\n### 相关页面\n\n相关主题：[Introduction to Agency Swarm](#page-introduction), [Installation and Setup](#page-installation), [Core Architecture](#page-core-architecture), [Tools System](#page-tools-system)\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- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n- [examples/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/tools.py)\n- [examples/multi_agent_workflow.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/multi_agent_workflow.py)\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- [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 \n\n# Getting Started Guide\n\nWelcome to the Agency Swarm Getting Started Guide. This guide provides comprehensive instructions for setting up your development environment, understanding the project structure, and building your first multi-agent application using the Agency Swarm framework.\n\n## Overview\n\nAgency Swarm is a framework for building multi-agent systems that enables multiple AI agents to collaborate through defined communication flows. The framework provides tools for creating agents, defining their capabilities through tools, establishing communication patterns between agents, and visualizing agent hierarchies.\n\nThis guide covers the essential steps from initial environment setup to running your first multi-agent workflow, with practical examples drawn from the repository's example implementations.\n\n## Prerequisites\n\nBefore beginning with Agency Swarm, ensure your development environment meets the following requirements:\n\n| Requirement | Minimum Version | Notes |\n|-------------|-----------------|-------|\n| Python | 3.10+ | Required for type hints and async features |\n| pip | Latest | For dependency management |\n| Git | Any recent version | For cloning the repository |\n| OpenAI API Key | Valid key | Required for agent execution |\n\n## Environment Setup\n\n### Cloning the Repository\n\nBegin by cloning the Agency Swarm repository to your local machine:\n\n```bash\ngit clone https://github.com/VRSEN/agency-swarm.git\ncd agency-swarm\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n### Creating a Virtual Environment\n\nCreating an isolated Python environment is recommended to avoid dependency conflicts:\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate # On Windows use `venv\\Scripts\\activate`\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n### Installing Dependencies\n\nAgency Swarm uses a Makefile for dependency management. Install all required packages with the sync command:\n\n```bash\nmake sync\n```\n\nThis command installs both runtime and development dependencies, including pre-commit hooks for code quality checks. To also install pre-commit hooks manually:\n\n```bash\npip install pre-commit\npre-commit install\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n## Project Structure\n\nUnderstanding the Agency Swarm directory structure is essential for effective development:\n\n```mermaid\ngraph TD\n A[agency-swarm Root] --> B[examples/]\n A --> C[src/agency_swarm/]\n A --> D[agency_swarm/]\n \n B --> B1[Core Examples]\n B --> B2[interactive/]\n B --> B3[fastapi_integration/]\n \n C --> C1[agent/]\n C --> C2[tools/]\n C --> C3[cli/]\n C --> C4[ui/]\n \n D --> D1[agents/]\n D --> D2[tools/]\n```\n\n### Key Directories\n\n| Directory | Purpose |\n|-----------|---------|\n| `examples/` | Runnable example scripts demonstrating various features |\n| `examples/interactive/` | Interactive UI demos including TUI and copilot interfaces |\n| `examples/fastapi_integration/` | FastAPI server and client examples |\n| `src/agency_swarm/` | Core framework source code |\n| `agency_swarm/` | User-defined agents and custom tools |\n\n### Recommended Agent Folder Structure\n\nEach agent should follow a consistent folder structure:\n\n```\nAgentName/\n├── files/ # Files to be uploaded to OpenAI\n├── schemas/ # OpenAPI schemas for tool generation\n├── tools/ # Agent-specific tool definitions\n├── AgentName.py # Main agent class\n├── __init__.py # Package initialization\n└── instructions.md # Agent instruction document\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Creating Your First Agent\n\n### Using the CLI Template Generator\n\nAgency Swarm provides a CLI command to scaffold agent templates automatically:\n\n```bash\nagency-swarm create-agent AgentName --model gpt-5.4-mini\n```\n\nThe CLI supports the following parameters:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `--name` | string | (prompt) | Name of the agent |\n| `--description` | string | (prompt) | Agent description |\n| `--model` | string | gpt-5.4 | Model to use |\n| `--temperature` | float | 0.3 | Sampling temperature (not for reasoning models) |\n| `--reasoning` | string | null | Reasoning effort for reasoning models |\n| `--instructions` | string | null | Custom instructions |\n| `--path` | string | ./ | Output directory |\n\n资料来源：[src/agency_swarm/cli/main.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/main.py)\n\n### Manual Agent Definition\n\nAlternatively, define agents programmatically using the Agent class:\n\n```python\nfrom agency_swarm import Agent, ModelSettings\n\nceo = Agent(\n name=\"CEO\",\n description=\"Responsible for client communication, task planning and management.\",\n instructions=\"You must converse with other agents to ensure complete task execution.\",\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## Defining Tools\n\nAgency Swarm supports multiple tool definition patterns.\n\n### Function Tool with Decorator\n\nThe simplest approach uses the `@function_tool` decorator:\n\n```python\nfrom agency_swarm import function_tool\n\n@function_tool\ndef calculate(a: int, b: int) -> int:\n \"\"\"A brief description of what the custom tool does.\"\"\"\n return a + b\n```\n\n资料来源：[examples/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/tools.py)\n\n### BaseTool Class\n\nFor more complex tools with validation, use the `BaseTool` class:\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.\n \"\"\"\n\n example_field: str = Field(\n ..., description=\"Description of the example field\"\n )\n\n def run(self):\n return \"Result of MyCustomTool operation\"\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n### OpenAPI Schema to Tools\n\nConvert existing OpenAPI schemas into Agency Swarm tools:\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# Using local file\nwith open(\"schemas/your_schema.json\") as f:\n tools = ToolFactory.from_openapi_schema(f.read())\n\n# Using remote URL\nimport requests\ntools = ToolFactory.from_openapi_schema(\n requests.get(\"https://api.example.com/openapi.json\").json()\n)\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Building Multi-Agent Workflows\n\n### Defining Communication Flows\n\nAgents communicate through defined flows using `SendMessage` and `Handoff`:\n\n```python\nfrom agency_swarm import Agency, Agent, SendMessage, Handoff\n\nceo = Agent(name=\"CEO\", ...)\ndeveloper = Agent(name=\"Developer\", ...)\nmanager = Agent(name=\"Manager\", ...)\n\nagency = Agency(\n ceo, # Entry point agent\n communication_flows=[\n (ceo > developer, SendMessage), # CEO sends to Developer\n (developer < manager), # Bidirectional with handoff\n (developer > ceo, Handoff), # Developer hands off to CEO\n ]\n)\n```\n\n资料来源：[examples/multi_agent_workflow.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/multi_agent_workflow.py)\n\n### Communication Flow Syntax\n\n| Syntax | Meaning |\n|--------|---------|\n| `(agent_a > agent_b)` | A sends to B with default SendMessage |\n| `(agent_a > agent_b, SendMessage)` | Explicit SendMessage tool |\n| `(agent_a < agent_b)` | Bidirectional communication |\n| `(agent_a < agent_b, Handoff)` | Bidirectional with handoff |\n| `(a < b > c)` | Multi-agent pattern |\n\n### Running the Agency\n\nExecute the agency asynchronously:\n\n```python\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\nFor synchronous execution:\n\n```python\nresp = agency.get_response_sync(\"Create a project skeleton.\")\n```\n\n资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Running Examples\n\nThe repository includes numerous runnable examples demonstrating key features:\n\n### Available Example Scripts\n\n| Example | Purpose |\n|---------|---------|\n| `multi_agent_workflow.py` | Multi-agent collaboration with validation |\n| `agency_context.py` | Data sharing between agents |\n| `streaming.py` | Real-time streaming responses |\n| `guardrails.py` | Input and output validation |\n| `tools.py` | Tool patterns with BaseTool and @function_tool |\n| `agent_file_storage.py` | Vector store and FileSearch tool usage |\n| `message_attachments.py` | File processing in messages |\n| `custom_send_message.py` | Custom SendMessage configurations |\n\n资料来源：[examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n\n### Running an Example\n\nNavigate to the examples directory and run any example script:\n\n```bash\ncd examples\npython multi_agent_workflow.py\n```\n\n## Interactive Interfaces\n\nAgency Swarm provides multiple interactive UI options.\n\n### Terminal UI\n\nThe terminal UI provides a chat interface in the terminal:\n\n```python\nfrom agency_swarm import Agency\n\nagency = create_demo_agency()\nagency.tui(show_reasoning=True)\n```\n\n资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n### Agency Visualization\n\nGenerate interactive HTML visualizations of your agency structure:\n\n```python\nfrom agency_swarm import Agency\n\nagency = create_demo_agency()\nhtml_file = agency.visualize(\n output_file=\"agency.html\",\n include_tools=True,\n open_browser=True,\n)\n```\n\n资料来源：[examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n\n## Testing\n\nRun the test suite to ensure your implementation works correctly:\n\n```bash\nmake coverage\n```\n\nThe coverage command runs pytest with coverage reporting. Review the output to ensure adequate test coverage for your changes.\n\n资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)\n\n## Additional Resources\n\n### Cursor IDE Integration\n\nFor enhanced development with AI coding assistants, use the `.cursorrules` file at the repository root. See the Cursor IDE guide at https://agency-swarm.ai/welcome/getting-started/cursor-ide for detailed setup instructions.\n\n### FastAPI Integration\n\nAgency Swarm supports FastAPI integration for serving agents as REST endpoints:\n\n```bash\ncd examples/fastapi_integration\npython server.py\n```\n\nThis exposes endpoints for streaming responses and agency metadata. See the `examples/fastapi_integration/README.md` for complete documentation.\n\n### CLI Commands Reference\n\n| Command | Description |\n|---------|-------------|\n| `agency-swarm create-agent` | Create a new agent template |\n| `agency-swarm migrate-agent` | Generate agent from OpenAI settings.json |\n| `agency-swarm import-tool` | Import built-in tools into your project |\n\n资料来源：[src/agency_swarm/cli/main.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/main.py)\n\n## Next Steps\n\nAfter completing this guide, consider exploring:\n\n1. **Advanced Communication Patterns** - Study `examples/interactive/hybrid_communication_flows.py` for complex agent interaction patterns\n2. **Custom Tool Development** - Create domain-specific tools following the patterns in `examples/tools.py`\n3. **Persistence** - Implement chat history persistence using `examples/custom_persistence.py`\n4. **Guardrails** - Add input/output validation as demonstrated in `examples/guardrails.py`\n\nFor comprehensive documentation, visit https://agency-swarm.ai/welcome/getting-started/from-scratch for the full tutorial.\n\n---\n\n\n\n## Core Architecture\n\n### 相关页面\n\n相关主题：[Introduction to Agency Swarm](#page-introduction), [Agent Internals](#page-agent-internal), [Communication Flows](#page-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/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n- [src/agency_swarm/agent/agent_flow.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/agent_flow.py)\n- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.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/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n- [src/agency_swarm/cli/utils/generate-agent-from-settings.ts](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/utils/generate-agent-from-settings.ts)\n \n\n# Core Architecture\n\nAgency Swarm is a multi-agent framework built on OpenAI's Agents SDK that enables the creation of collaborative AI agent systems. The core architecture comprises three fundamental layers: the **Agency Layer**, the **Agent Layer**, and the **Communication Layer**. This document provides an in-depth analysis of how these components interact to form a cohesive multi-agent system.\n\n## Architecture Overview\n\nThe framework follows a hierarchical design where the Agency serves as the top-level orchestrator, managing multiple Agents that collaborate through well-defined communication channels.\n\n```mermaid\ngraph TB\n subgraph Agency[\"Agency Layer\"]\n A[Agency]\n AC[AgencyContext]\n AF[Communication Flows]\n end\n \n subgraph Agent[\"Agent Layer\"]\n AG1[Agent Instance]\n AG2[Agent Instance]\n AGn[Agent Instance]\n end\n \n subgraph Tools[\"Tool Layer\"]\n BT[BaseTool]\n FT[FunctionTool]\n TF[ToolFactory]\n end\n \n subgraph Model[\"Model Layer\"]\n MS[ModelSettings]\n RM[Reasoning Models]\n end\n \n A --> AG1\n A --> AG2\n A --> AGn\n A --> AC\n A --> AF\n \n AG1 --> BT\n AG2 --> FT\n AGn --> TF\n \n AG1 --> MS\n AG2 --> RM\n```\n\n## The Agency Layer\n\n### Purpose and Role\n\nThe Agency acts as the central coordinator for all agents within the system. It manages agent initialization, communication routing, shared context distribution, and the overall execution flow.\n\n**资料来源:** [examples/README.md:1-30](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n\n### Agency Initialization\n\nThe Agency is initialized with a collection of agents and optional communication flows:\n\n```python\nfrom agency_swarm import Agency, Agent\n\nsupport = Agent(name=\"SupportAgent\", ...)\nmath = Agent(name=\"MathAgent\", ...)\n\nagency = Agency(\n support,\n math,\n communication_flows=[(support, math, Handoff)],\n shared_instructions=\"Demonstrate reasoning, web search, file search, and handoffs.\",\n name=\"DemoAgency\"\n)\n```\n\n**资料来源:** [examples/interactive/tui.py:40-68](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n### Key Agency Components\n\n| Component | Description |\n|-----------|-------------|\n| `agents` | Dictionary of initialized Agent instances |\n| `communication_flows` | Defines allowed communication paths between agents |\n| `shared_instructions` | Common instructions for all agents |\n| `agency_context` | Shared data store accessible by all agents |\n\n## The Agent Layer\n\n### Agent Class Structure\n\nThe `Agent` class is the fundamental building block of Agency Swarm. Each agent encapsulates a specific role, set of tools, instructions, and model configuration.\n\n**资料来源:** [src/agency_swarm/agent/core.py:1-100](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n### Agent Initialization Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `name` | `str` | Yes | Unique identifier for the agent |\n| `description` | `str` | Yes | Role description for the agent |\n| `instructions` | `str` | Yes | Instructions or path to instructions file |\n| `tools` | `list[BaseTool]` | No | List of tool instances |\n| `files_folder` | `str` | No | Path to files for vector store |\n| `schemas_folder` | `str` | No | Path to OpenAPI schemas |\n| `model` | `str` | No | Model identifier (default: \"gpt-5.4\") |\n| `model_settings` | `ModelSettings` | No | Model configuration |\n| `output_type` | `type` | No | Output schema for structured responses |\n\n**资料来源:** [src/agency_swarm/agent/core.py:50-150](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n### Tool Loading Mechanism\n\nAgents support three distinct tool loading mechanisms:\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**资料来源:** [src/agency_swarm/agent/core.py:120-130](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n### OpenAPI Schema Parsing\n\nAgents can automatically convert OpenAPI schemas into usable tools:\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**资料来源:** [src/agency_swarm/agent/core.py:135-140](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n## Communication Architecture\n\n### Agent-to-Agent Communication\n\nAgents communicate through two primary mechanisms:\n\n1. **Direct Messaging** (`SendMessage`)\n2. **Handoffs** - Transfer of control between agents\n\n```python\nfrom agency_swarm import Handoff\n\nagency = Agency(\n support,\n math,\n communication_flows=[(support, math, Handoff)],\n)\n```\n\n**资料来源:** [examples/interactive/tui.py:55-57](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n### Communication Flow Definition\n\nCommunication flows are defined as a list of tuples specifying source agent, target agent, and the communication type:\n\n```python\ncommunication_flows=[\n (agent_a, agent_b, Handoff),\n (agent_b, agent_c, SendMessage),\n]\n```\n\n## Execution Flow\n\n### The get_response Method\n\nThe primary method for agent execution is `get_response`, which handles both user and agent-to-agent interactions:\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**资料来源:** [src/agency_swarm/agent/core.py:150-200](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n### Synchronous Execution\n\nFor synchronous use cases, `get_response_sync` provides a blocking interface:\n\n```python\nresp = agency.get_response_sync(\"What's your name?\")\n```\n\n### Streaming Responses\n\nThe framework supports real-time streaming for interactive applications:\n\n```python\n# See streaming.py in examples\n```\n\n**资料来源:** [examples/README.md:8](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)\n\n## Model Configuration\n\n### ModelSettings\n\nModel configuration is handled through the `ModelSettings` class:\n\n```python\nfrom agency_swarm import ModelSettings, Reasoning\n\nmodel_settings=ModelSettings(\n temperature=0.3,\n top_p=0.9,\n max_tokens=25000,\n reasoning=Reasoning(effort=\"high\", summary=\"auto\")\n)\n```\n\n**资料来源:** [src/agency_swarm/cli/utils/generate-agent-from-settings.ts:50-80](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/utils/generate-agent-from-settings.ts)\n\n### Reasoning Models\n\nThe framework supports OpenAI's reasoning models with special configuration:\n\n```python\ndef is_reasoning_model(model: str) -> bool:\n \"\"\"Check if the model is a reasoning model.\"\"\"\n # Reasoning models do not support temperature parameter\n```\n\n**资料来源:** [src/agency_swarm/utils/create_agent_template.py:10-25](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)\n\n### ModelSettings Parameters\n\n| Parameter | Type | Description | Reasoning Model Compatible |\n|-----------|------|-------------|---------------------------|\n| `temperature` | `float` | Sampling temperature | No |\n| `top_p` | `float` | Nucleus sampling | No |\n| `max_tokens` | `int` | Maximum tokens in response | Yes |\n| `reasoning` | `Reasoning` | Reasoning effort configuration | Yes |\n\n## File Management\n\n### Vector Store Integration\n\nAgents can upload files to OpenAI's vector stores for semantic search:\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**资料来源:** [src/agency_swarm/agent/core.py:145-152](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n### File Search Tool Configuration\n\nThe `FileSearchTool` can be configured with vector store IDs:\n\n```python\ntoolImports.push(\"FileSearchTool\");\nconfigParts.push(`vector_store_ids=[${vectorStoreIds}]`);\n```\n\n**资料来源:** [src/agency_swarm/cli/utils/generate-agent-from-settings.ts:100-120](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/utils/generate-agent-from-settings.ts)\n\n## Tool System Architecture\n\n### Tool Types\n\n| Tool Type | Description | Base Class |\n|-----------|-------------|------------|\n| `BaseTool` | Pydantic-based tool definition | `BaseTool` |\n| `FunctionTool` | Decorator-based tool creation | `@function_tool` |\n| `ToolFactory` | OpenAPI schema conversion | `ToolFactory.from_openapi_schema()` |\n\n### BaseTool Implementation\n\n```python\nfrom agency_swarm.tools import BaseTool\nfrom pydantic import Field\n\nclass MyCustomTool(BaseTool):\n example_field: str = Field(\n ..., description=\"Description of the example field\"\n )\n\n def run(self):\n return f\"Result: {self.example_field}\"\n```\n\n**资料来源:** [README.md:100-130](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n### ToolFactory for OpenAPI Schemas\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\ntools = ToolFactory.from_openapi_schema(\n openapi_schema_json # Can be dict or loaded from file\n)\n```\n\n## Agent Flow State Machine\n\nThe `agent_flow.py` module manages the state transitions within an agent's execution cycle:\n\n```mermaid\ngraph LR\n A[Init] --> B[Process Input]\n B --> C{Tool Call?}\n C -->|Yes| D[Execute Tool]\n D --> B\n C -->|No| E[Generate Response]\n E --> F[Check Handoff]\n F -->|Yes| G[Transfer Control]\n G --> H[End]\n F -->|No| I[Final Output]\n I --> H\n```\n\n**资料来源:** [src/agency_swarm/agent/agent_flow.py:1-50](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/agent_flow.py)\n\n## CLI and Template Generation\n\n### Agent Template Creation\n\nThe CLI provides utilities for generating agent templates with validation:\n\n```python\ndef create_agent_template(\n agent_name=None,\n agent_description=None,\n model=\"gpt-5.4\",\n reasoning=None,\n max_tokens=None,\n temperature=None,\n path=\"./\",\n instructions=None,\n use_txt=False,\n include_example_tool=True,\n) -> bool:\n```\n\n**资料来源:** [src/agency_swarm/utils/create_agent_template.py:15-40](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)\n\n### Input Validation\n\nThe framework validates agent names and parameters:\n\n```python\ndef _validate_agent_name(agent_name):\n \"\"\"Validate agent name follows CamelCase convention.\"\"\"\n\ndef _validate_temperature(temperature):\n \"\"\"Validate temperature is within valid range (0-2).\"\"\"\n```\n\n**资料来源:** [src/agency_swarm/utils/create_agent_template.py:40-70](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)\n\n## Recommended Folder Structure\n\n```\nagency_project/\n├── agency_manifesto.md # Agency's guiding principles\n└── AgentName/\n ├── files/ # Files for vector store upload\n ├── schemas/ # OpenAPI schemas for tools\n ├── tools/ # Custom tool modules\n ├── AgentName.py # Agent class definition\n ├── __init__.py # Package initialization\n └── instructions.md # Agent instructions\n```\n\n**资料来源:** [README.md:60-80](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n\n## Programmatic Usage Patterns\n\n### Async Execution\n\n```python\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### Sync Execution\n\n```python\nresp = agency.get_response_sync(\"What's your name?\")\n```\n\n## Summary\n\nThe Agency Swarm core architecture consists of three interdependent layers:\n\n1. **Agency Layer**: Orchestrates multiple agents, manages communication flows, and maintains shared context\n2. **Agent Layer**: Encapsulates individual agent capabilities including tools, instructions, and model configurations\n3. **Communication Layer**: Enables agent-to-agent messaging and handoff mechanisms\n\nThe architecture follows a modular design pattern where tools, models, and communication mechanisms can be independently configured and composed to create complex multi-agent workflows.\n\n---\n\n\n\n## Agent Internals\n\n### 相关页面\n\n相关主题：[Core Architecture](#page-core-architecture), [Tools System](#page-tools-system)\n\n\nRelevant Source Files
\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/initialization.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/initialization.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/execution.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/execution.py)\n- [src/agency_swarm/agent/execution_guardrails.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/execution_guardrails.py)\n \n\n# Agent Internals\n\n## Overview\n\nThe Agent is the fundamental execution unit in Agency Swarm. It represents an autonomous entity capable of processing messages, executing tools, and communicating with other agents within an agency. Agents are built on OpenAI's Responses API and encapsulate configuration for model selection, tool definitions, file management, and communication protocols.\n\nAgents serve as the building blocks for multi-agent systems, enabling complex workflows where specialized agents collaborate through defined communication flows. Each agent maintains its own state, toolset, and instruction set while participating in the broader agency ecosystem.\n\n资料来源：[src/agency_swarm/agent/core.py:1-50]()\n\n## Architecture Overview\n\nThe Agent module is organized into several interconnected components that handle different aspects of agent behavior:\n\n```mermaid\ngraph TD\n A[Agent] --> B[Initialization]\n A --> C[Core Execution]\n A --> D[Tools Management]\n A --> E[Guardrails]\n \n B --> B1[__init__]\n B --> B2[_init_files]\n B --> B3[_load_tools_from_folder]\n B --> B4[_parse_schemas]\n \n C --> C1[get_response]\n C --> C2[Run Hooks]\n C --> C3[Run Config]\n \n D --> D1[BaseTool]\n D --> D2[FunctionTool]\n D --> D3[ToolFactory]\n \n E --> E1[Input Guardrails]\n E --> E2[Output Guardrails]\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `core.py` | Main Agent class | Primary interface for agent operations |\n| `initialization.py` | Agent setup | Initialization logic and factory methods |\n| `tools.py` | Tool management | Tool loading, parsing, and factory utilities |\n| `execution.py` | Runtime execution | Response processing and hooks |\n| `execution_guardrails.py` | Validation | Input/output validation pipelines |\n\n资料来源：[src/agency_swarm/agent/core.py:1-30]()\n\n## Agent Initialization\n\n### Constructor Parameters\n\nThe Agent class accepts the following core parameters during initialization:\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `name` | `str` | Yes | - | Unique identifier for the agent |\n| `description` | `str` | Yes | - | Human-readable description of agent's role |\n| `instructions` | `str` | Yes | - | Instructions file path or inline text |\n| `files_folder` | `str` | No | `None` | Path to files for vector store upload |\n| `schemas_folder` | `str` | No | `None` | Path to OpenAPI schema files |\n| `tools` | `list[Tool]` | No | `[]` | List of tool instances to attach |\n| `tools_folder` | `str` | No | `None` | Directory to auto-load tools from |\n| `model` | `str` | No | `\"gpt-5.4\"` | OpenAI model identifier |\n| `model_settings` | `ModelSettings` | No | `None` | Configuration for temperature, max_tokens, etc. |\n| `response_format` | `ResponseFormat` | No | `None` | Output format specification |\n\n资料来源：[src/agency_swarm/agent/core.py:50-120]()\n\n### Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Agent\n participant FileManager\n participant ToolLoader\n participant SchemaParser\n \n User->>Agent: __init__(params)\n Agent->>Agent: _validate_params()\n Agent->>FileManager: _init_files()\n Agent->>ToolLoader: _load_tools_from_folder()\n Agent->>SchemaParser: _parse_schemas()\n Agent-->>User: Agent instance\n```\n\nThe initialization process follows these steps:\n\n1. **Parameter Validation**: All required parameters are validated\n2. **File Manager Setup**: Files in `files_folder` are prepared for upload\n3. **Tool Loading**: Tools are loaded from both the `tools` parameter and `tools_folder`\n4. **Schema Parsing**: OpenAPI schemas in `schemas_folder` are converted to tools\n\n资料来源：[src/agency_swarm/agent/initialization.py:1-80]()\n\n### Model Configuration\n\nAgents support various OpenAI models with appropriate default settings:\n\n```python\n# Reasoning models (e.g., o3, o4-mini) - no temperature\nmodel=\"gpt-5.4\"\nmodel_settings=ModelSettings(\n reasoning=Reasoning(effort=\"medium\")\n)\n\n# Non-reasoning models - temperature defaults to 0.3\nmodel=\"gpt-4o\"\nmodel_settings=ModelSettings(\n temperature=0.3,\n max_tokens=25000\n)\n```\n\n资料来源：[src/agency_swarm/utils/create_agent_template.py:40-70]()\n\n## Tools Management\n\n### Tool Types\n\nThe framework supports two primary tool paradigms:\n\n| Type | Base Class | Use Case |\n|------|------------|----------|\n| `BaseTool` | Abstract class | Complex tools with custom state and validation |\n| `FunctionTool` | Decorator-based | Simple functions wrapped as tools |\n\n### BaseTool Implementation\n\n`BaseTool` subclasses must implement the following interface:\n\n```python\nfrom agency_swarm.tools import BaseTool\n\nclass MyTool(BaseTool):\n name: str = \"my_tool\"\n description: str = \"Description of what the tool does\"\n \n def run(self) -> str:\n \"\"\"Execute the tool's primary function.\"\"\"\n return \"result\"\n```\n\n资料来源：[src/agency_swarm/agent/tools.py:1-50]()\n\n### FunctionTool Decorator\n\nFor simpler use cases, the `@function_tool` decorator wraps regular Python functions:\n\n```python\nfrom agency_swarm import function_tool\n\n@function_tool\ndef calculate(expression: str) -> str:\n \"\"\"Evaluate a mathematical expression.\"\"\"\n return str(eval(expression))\n```\n\n### Tool Loading from Folder\n\nThe `_load_tools_from_folder()` method dynamically imports tools from a directory structure:\n\n```\nAgentName/tools/\n├── __init__.py\n├── MyTool.py\n└── AnotherTool.py\n```\n\nThe loader:\n- Scans the folder for Python files\n- Imports classes inheriting from `BaseTool`\n- Includes `FunctionTool` instances defined in `__init__.py`\n- Adds all discovered tools to the agent's toolset\n\n资料来源：[src/agency_swarm/agent/core.py:100-120]()\n\n### OpenAPI Schema Parsing\n\nAgents can automatically convert OpenAPI schemas into callable tools:\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# From file\ntools = ToolFactory.from_openapi_schema(\n openapi_schema=json.load(open(\"schema.json\"))\n)\n\n# From URL\ntools = ToolFactory.from_openapi_schema(\n requests.get(\"https://api.example.com/openapi.json\").json()\n)\n```\n\nThe `_parse_schemas()` method processes schemas from `schemas_folder` and creates corresponding tools.\n\n资料来源：[README.md:50-80]()\n\n## Execution Flow\n\n### Core Execution Method\n\nThe `get_response()` method is the primary interface for agent execution:\n\n```mermaid\ngraph LR\n A[Message Input] --> B[Context Override]\n B --> C[Run Hooks]\n C --> D[OpenAI API Call]\n D --> E[Tool Execution]\n E --> D\n D --> F[Output Processing]\n F --> G[Response Format]\n G --> H[RunResult]\n```\n\n### Method Signature\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### Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `message` | `str \\| list[TResponseInputItem]` | Input message or list of message items |\n| `sender_name` | `str \\| None` | Name of the sending agent (for agent-to-agent) |\n| `context_override` | `dict \\| None` | Override agency context values |\n| `hooks_override` | `RunHooks \\| None` | Custom hooks for this execution |\n| `run_config_override` | `RunConfig \\| None` | Custom run configuration |\n| `file_ids` | `list[str] \\| None` | Pre-uploaded file IDs to include |\n| `additional_instructions` | `str \\| None` | Extra instructions appended to agent prompt |\n| `agency_context` | `AgencyContext \\| None` | Context from parent agency |\n\n资料来源：[src/agency_swarm/agent/core.py:150-200]()\n\n### Run Result\n\nThe execution returns a `RunResult` object containing:\n\n- `messages`: Conversation history\n- `final_output`: Text response from the model\n- `tool_calls`: List of tool invocations made\n- `usage`: Token and cost information\n\n## Execution Guardrails\n\nGuardrails provide validation hooks at the input and output boundaries of agent execution.\n\n### Guardrail Interface\n\n```python\nclass BaseExecutionGuardrail(ABC):\n @abstractmethod\n async def validate(\n self,\n agent: Agent,\n messages: list[Message],\n ) -> tuple[bool, str | None]:\n \"\"\"Validate input or output. Returns (passed, error_message).\"\"\"\n pass\n```\n\n### Guardrail Pipeline\n\n```mermaid\ngraph TD\n A[Input Messages] --> B[Input Guardrails]\n B -->|pass| C[Execute Agent]\n B -->|fail| D[Return Error]\n C --> E[Output Processing]\n E --> F[Output Guardrails]\n F -->|pass| G[Return Result]\n F -->|fail| D\n \n style D fill:#ff6b6b\n style G fill:#51cf66\n```\n\n### Configuration\n\nGuardrails are configured per-agent:\n\n```python\nfrom agency_swarm.agent import Agent, InputGuardrail, OutputGuardrail\n\nagent = Agent(\n name=\"SecureAgent\",\n instructions=\"...\",\n input_guardrails=[MyInputGuardrail()],\n output_guardrails=[MyOutputGuardrail()],\n)\n```\n\n资料来源：[src/agency_swarm/agent/execution_guardrails.py:1-60]()\n\n## File Handling\n\n### File Manager Integration\n\nAgents can manage files for upload to OpenAI's vector stores:\n\n```python\nagent = Agent(\n name=\"Researcher\",\n instructions=\"...\",\n files_folder=\"./files\",\n)\n```\n\n### Upload Method\n\n```python\ndef upload_file(\n self,\n file_path: str,\n include_in_vector_store: bool = True\n) -> str:\n \"\"\"Upload a file using the agent's file manager.\n \n Returns:\n str: The uploaded file ID\n \"\"\"\n if self.file_manager:\n return self.file_manager.upload_file(\n file_path,\n include_in_vector_store\n )\n raise RuntimeError(f\"Agent {self.name} has no file manager configured\")\n```\n\n资料来源：[src/agency_swarm/agent/core.py:130-145]()\n\n## Communication Patterns\n\n### Agent-to-Agent Messaging\n\nAgents communicate through defined flows using specialized message tools:\n\n```python\nfrom agency_swarm import Agency, Agent, SendMessage, Handoff\n\nceo = Agent(name=\"CEO\", ...)\ndeveloper = Agent(name=\"Developer\", ...)\n\nagency = Agency(\n ceo,\n developer,\n communication_flows=[\n (ceo > developer, SendMessage), # CEO sends to Developer\n (developer > ceo, Handoff), # Developer returns to CEO\n ]\n)\n```\n\n### Message Types\n\n| Type | Purpose |\n|------|---------|\n| `SendMessage` | Direct message with optional context |\n| `SendMessageWithContext` | Message preserving agency context |\n| `Handoff` | Transfer control back to calling agent |\n\n## Model Settings\n\nThe `ModelSettings` class configures LLM behavior:\n\n```python\nfrom agency_swarm import Agent, ModelSettings, Reasoning\n\nagent = Agent(\n name=\"Analyzer\",\n model=\"gpt-5.4-mini\",\n model_settings=ModelSettings(\n temperature=0.3,\n max_tokens=25000,\n reasoning=Reasoning(effort=\"high\", summary=\"auto\"),\n top_p=0.9,\n ),\n)\n```\n\n### Settings Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `temperature` | `float` | `0.3` | Sampling temperature (0-2) |\n| `max_tokens` | `int` | varies | Maximum completion tokens |\n| `top_p` | `float` | `None` | Nucleus sampling threshold |\n| `reasoning` | `Reasoning` | `None` | Reasoning effort configuration |\n| `response_include` | `list` | `None` | Include additional metadata |\n\n资料来源：[src/agency_swarm/cli/utils/generate-agent-from-settings.ts:60-100]()\n\n## State Management\n\n### Agency Context\n\nAgents can share state through the `AgencyContext`:\n\n```python\nasync def get_response(\n self,\n message: str,\n context_override: dict[str, Any] | None = None,\n agency_context: AgencyContext | None = None,\n ...\n) -> RunResult:\n # Access shared context\n if agency_context:\n shared_data = agency_context.get(\"key\")\n```\n\n### Message History\n\nAgents maintain conversation history through `RunResult`:\n\n```python\nresult = await agent.get_response(\"Hello\")\nfor message in result.messages:\n print(f\"{message.role}: {message.content}\")\n```\n\n## CLI Integration\n\n### Agent Template Creation\n\nThe CLI provides utilities for generating agent templates:\n\n```bash\nagency-swarm create-agent-template \"Data Analyst\" \\\n --description \"Performs data analysis\" \\\n --model \"gpt-5.4-mini\" \\\n --reasoning \"medium\" \\\n --temperature 0.3\n```\n\nThis generates the standard folder structure:\n\n```\nDataAnalyst/\n├── DataAnalyst.py\n├── __init__.py\n├── instructions.md\n├── files/\n├── schemas/\n└── tools/\n```\n\n资料来源：[src/agency_swarm/cli/main.py:30-80]()\n\n## Summary\n\nThe Agent Internals architecture demonstrates a modular design where:\n\n1. **Initialization** handles setup of files, tools, and schemas\n2. **Tools Management** provides flexible tool creation and loading\n3. **Execution** manages the runtime loop with hooks and guardrails\n4. **Communication** enables multi-agent collaboration through defined flows\n5. **Configuration** supports various models with appropriate defaults\n\nThis architecture allows agents to serve as self-contained, configurable units that can participate in complex multi-agent workflows while maintaining clear separation of concerns.\n\n---\n\n\n\n## Tools System\n\n### 相关页面\n\n相关主题：[Getting Started Guide](#page-getting-started), [Agent Internals](#page-agent-internal), [Communication Flows](#page-communication-flows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/tools/base_tool.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/base_tool.py)\n- [src/agency_swarm/tools/__init__.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/__init__.py)\n- [src/agency_swarm/tools/tool_factory.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory.py)\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/PersistentShellTool.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/PersistentShellTool.py)\n \n\n# Tools System\n\n## Overview\n\nThe Tools System in Agency Swarm provides a flexible mechanism for extending agent capabilities through custom tool implementations. Agents can use tools to interact with external services, execute code, run shell commands, search the web, and perform various other tasks that extend beyond natural language processing.\n\nTools in Agency Swarm serve as the primary interface between agents and external functionality. They enable agents to:\n\n- Execute Python code in isolated environments\n- Run persistent shell commands\n- Search the web for information\n- Process and analyze files\n- Interact with external APIs via OpenAPI schemas\n\nThe system supports two primary tool creation patterns: inheriting from `BaseTool` class and using the `@function_tool` decorator. Additionally, tools can be auto-generated from OpenAPI schemas using `ToolFactory`.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Agent] --> B[Tools System]\n B --> C[BaseTool Subclass]\n B --> D[@function_tool Decorator]\n B --> E[ToolFactory]\n C --> F[IPythonInterpreter]\n C --> G[PersistentShellTool]\n C --> H[Custom Tool]\n E --> I[OpenAPI Schema]\n F --> J[Code Execution Environment]\n G --> K[Shell Session]\n```\n\n## Core Components\n\n### BaseTool Class\n\nThe `BaseTool` class is the foundation for all tools in Agency Swarm. It provides a standardized interface for tool definition and execution.\n\n**File:** `src/agency_swarm/tools/base_tool.py`\n\n**Key Responsibilities:**\n- Define tool schema for OpenAI API compatibility\n- Validate input parameters using Pydantic\n- Execute the tool's core functionality via `run()` method\n- Support async execution when needed\n\n**Structure:**\n\n| Component | Description |\n|-----------|-------------|\n| `ToolConfig` | Pydantic model defining tool metadata (name, description, parameters) |\n| `BaseTool` | Abstract base class for all tools |\n| `run()` | Abstract method for tool execution |\n| `get_schema()` | Returns OpenAI-compatible tool schema |\n\n### ToolFactory\n\nThe `ToolFactory` class enables automatic generation of tools from OpenAPI schemas. This allows integration with existing REST APIs without manual tool implementation.\n\n**File:** `src/agency_swarm/tools/tool_factory.py`\n\n**Usage Pattern:**\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# From local file\nwith open(\"schemas/your_schema.json\") as f:\n tools = ToolFactory.from_openapi_schema(f.read())\n\n# From remote URL\nimport requests\ntools = ToolFactory.from_openapi_schema(\n requests.get(\"https://api.example.com/openapi.json\").json()\n)\n```\n\n### Built-in Tools\n\nAgency Swarm includes several pre-built tools for common use cases.\n\n#### IPythonInterpreter\n\n**File:** `src/agency_swarm/tools/built_in/IPythonInterpreter.py`\n\nProvides Python code execution capabilities within an agency. Key features:\n\n- Executes Python code in a persistent environment\n- Maintains state between executions\n- Supports file operations and data processing\n- Integrates with agent workflows for data analysis tasks\n\n**Configuration Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `timeout` | int | 60 | Maximum execution time in seconds |\n| `working_directory` | str | None | Directory for file operations |\n\n#### PersistentShellTool\n\n**File:** `src/agency_swarm/tools/built_in/PersistentShellTool.py`\n\nProvides persistent shell command execution. Unlike one-off command runners, this tool maintains an active shell session across multiple tool calls.\n\n**Features:**\n- Persistent shell state between commands\n- Environment variable preservation\n- Working directory consistency\n- Command history tracking\n\n### Function Tool Decorator\n\nThe `@function_tool` decorator provides a lightweight alternative to `BaseTool` subclassing. It's ideal for simpler tools that don't require extensive configuration.\n\n**Pattern:**\n\n```python\nfrom agency_swarm.tools import function_tool\nfrom pydantic import Field\n\n@function_tool\ndef calculate(a: float, b: float, operation: str = Field(\n description=\"Operation to perform: add, subtract, multiply, divide\"\n)) -> str:\n \"\"\"Perform basic arithmetic operations.\"\"\"\n if operation == \"add\":\n return str(a + b)\n elif operation == \"subtract\":\n return str(a - b)\n elif operation == \"multiply\":\n return str(a * b)\n elif operation == \"divide\":\n if b == 0:\n return \"Error: Division by zero\"\n return str(a / b)\n return \"Unknown operation\"\n```\n\n## Creating Custom Tools\n\n### Method 1: Using BaseTool Class\n\nFor complex tools requiring detailed configuration:\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 is used by the agent to determine when to use this tool.\n \"\"\"\n \n # Define fields with descriptions using Pydantic Field\n example_field: str = Field(\n ..., description=\"Description of the example field explaining its purpose\"\n )\n \n def run(self):\n \"\"\"\n The implementation of the run method.\n \"\"\"\n # Tool logic here\n return f\"Result: {self.example_field}\"\n```\n\n### Method 2: Using @function_tool Decorator\n\nFor simpler tools:\n\n```python\nfrom agency_swarm.tools import function_tool\n\n@function_tool\ndef my_simple_tool(input_text: str) -> str:\n \"\"\"Process input text and return result.\"\"\"\n return input_text.upper()\n```\n\n### Method 3: From OpenAPI Schema\n\nFor API integration:\n\n```python\nfrom agency_swarm.tools import ToolFactory\n\n# Generate tools from OpenAPI specification\ntools = ToolFactory.from_openapi_schema(openapi_schema_dict)\n\n# tools is a list of BaseTool instances\nfor tool in tools:\n print(tool.name, tool.description)\n```\n\n## Tool Integration with Agents\n\n### Adding Tools to Agents\n\nTools are passed to agents via the `tools` parameter during initialization:\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools import BaseTool, function_tool\n\n# Custom tool class\nclass DataProcessor(BaseTool):\n name: str = \"DataProcessor\"\n description: str = \"Processes data according to specified rules\"\n \n data: str = Field(description=\"Data to process\")\n rule: str = Field(description=\"Processing rule to apply\")\n \n def run(self):\n return f\"Processed {self.data} with rule {self.rule}\"\n\n# Function tool\n@function_tool\ndef calculator(a: float, b: float) -> float:\n return a + b\n\n# Create agent with tools\nagent = Agent(\n name=\"DataAgent\",\n description=\"Handles data processing tasks\",\n tools=[DataProcessor, calculator]\n)\n```\n\n### Tool Discovery from Folders\n\nAgents can automatically discover and load tools from a specified directory:\n\n```python\nagent = Agent(\n name=\"FileAgent\",\n description=\"Handles file operations\",\n tools_folder=\"./tools\" # Auto-loads all tools from this directory\n)\n```\n\nThis approach scans the specified folder for tool definitions and makes them available to the agent without explicit listing.\n\n## Tool Schema Generation\n\nEach tool automatically generates an OpenAI-compatible schema used for function calling:\n\n```mermaid\ngraph LR\n A[Tool Definition] --> B[Schema Generator]\n B --> C[OpenAI Tool Schema]\n C --> D[Agent System Prompt]\n D --> E[Model Function Calling]\n```\n\n**Schema Structure:**\n\n```json\n{\n \"type\": \"function\",\n \"function\": {\n \"name\": \"tool_name\",\n \"description\": \"Tool description\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {...},\n \"required\": [...]\n }\n }\n}\n```\n\n## Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Tool as Tool Instance\n participant Runtime as Tool Runtime\n \n Agent->>Tool: Calls tool with parameters\n Tool->>Tool: Validate parameters (Pydantic)\n Tool->>Runtime: Execute run() method\n Runtime-->>Tool: Return result\n Tool-->>Agent: Return tool result\n \n Note over Agent,Tool: Tool can be sync or async\n```\n\n## Testing Tools\n\nTools should include comprehensive test coverage. Tests are located in `agency_swarm/tests/test_tools.py`.\n\n**Test Template:**\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**Running Tool Tests:**\n\n```bash\nmake coverage\n```\n\n## CLI Tool Import\n\nAgency Swarm CLI provides built-in tool import functionality:\n\n```bash\n# List available built-in tools\nagency-swarm import-tool --list\n\n# Import a specific tool\nagency-swarm import-tool IPythonInterpreter --directory ./my_tools\n```\n\nThis command copies the selected tool's source files into the specified directory, allowing for customization.\n\n## Best Practices\n\n1. **Clear Descriptions**: Use descriptive docstrings that explain when and why the agent should use the tool\n2. **Field Documentation**: Every parameter field should have a clear `description` for agent understanding\n3. **Error Handling**: Implement proper error handling in the `run()` method\n4. **Type Safety**: Use Pydantic models for all parameters to ensure validation\n5. **Idempotency**: Design tools to be safely re-executable when possible\n6. **Resource Management**: Clean up resources (files, connections) after execution\n\n## File Structure\n\n```\nagency_swarm/tools/\n├── __init__.py # Public exports\n├── base_tool.py # BaseTool class definition\n├── tool_factory.py # ToolFactory for OpenAPI schemas\n├── function_tool.py # @function_tool decorator\n└── built_in/ # Pre-built tool implementations\n ├── IPythonInterpreter.py\n ├── PersistentShellTool.py\n └── ...\n```\n\n## Summary\n\nThe Tools System provides a comprehensive framework for extending agent capabilities in Agency Swarm. With support for custom tool creation, OpenAPI schema integration, and built-in tools for common tasks, developers can flexibly enhance their agents' functionality. The system leverages Pydantic for robust parameter validation and follows consistent patterns that make tool development straightforward and maintainable.\n\n---\n\n\n\n## Communication Flows\n\n### 相关页面\n\n相关主题：[Core Architecture](#page-core-architecture), [Tools System](#page-tools-system), [Messaging System](#page-messaging-system)\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/tools/send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py)\n- [src/agency_swarm/agent/agent_flow.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/agent_flow.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- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n \n\n# Communication Flows\n\n## Overview\n\nCommunication Flows define how agents interact with each other within an Agency. They establish the rules and pathways for agent-to-agent messaging, control transfers, and collaborative workflows. This system enables multi-agent collaboration by specifying which agents can communicate, through what mechanisms, and in what directions.\n\nCommunication Flows are a core architectural component of agency-swarm that transforms a collection of individual agents into a coordinated multi-agent system. Without explicit communication flows, agents cannot interact with each other—they can only respond to direct user input.\n\n## Core Concepts\n\n### Agent Communication Patterns\n\nAgency-swarm supports two primary communication mechanisms:\n\n| Pattern | Purpose | Use Case |\n|---------|---------|----------|\n| **SendMessage** | Direct message passing with optional context | Coordinated workflows, task delegation |\n| **Handoff** | Transfer of conversational control | Escalation, specialized handling, task completion |\n\n### Flow Directionality\n\nCommunication flows are directional, meaning you can specify asymmetric communication patterns:\n\n- **Unidirectional**: Agent A can send messages to Agent B, but not vice versa\n- **Bidirectional**: Agents can communicate in both directions\n- **Broadcast-capable**: Certain patterns allow multi-recipient messaging\n\n## Architecture\n\n### Flow Processing Pipeline\n\n```mermaid\ngraph TD\n A[User Input] --> B[Entry Point Agent]\n B --> C{Communication Flow Check}\n C -->|SendMessage| D[SendMessage Tool Execution]\n C -->|Handoff| E[Handoff Tool Execution]\n D --> F[Recipient Agent Processing]\n E --> G[Control Transfer to Recipient]\n F --> H{More Flows?}\n G --> H\n H -->|Yes| C\n H -->|No| I[Final Response]\n```\n\n### Flow Definition in Agency Class\n\nThe `Agency` class in `src/agency_swarm/agency/core.py` manages communication flows through the `communication_flows` parameter:\n\n```python\nAgency(\n agents,\n communication_flows=[...],\n shared_instructions=\"...\",\n send_message_tool_class=SendMessage\n)\n```\n\n资料来源：[examples/agency_visualization.py:25-35]()\n\n### Flow Tuple Structure\n\nCommunication flows are defined as tuples with the following structure:\n\n```python\ncommunication_flows=[\n (agent_a > agent_b), # Simple unidirectional\n (agent_c < agent_d), # Reverse direction\n (agent_e > agent_f, Handoff), # With specific tool class\n (agent_g < agent_h > agent_i), # Multi-agent chain\n]\n```\n\n## Configuration Options\n\n### Basic Flow Definition\n\nSimple directional flows use the default `SendMessage` tool:\n\n```python\nfrom agency_swarm import Agent, Agency\n\nceo = Agent(name=\"CEO\", instructions=\"Manage the workflow\")\ndeveloper = Agent(name=\"Developer\", instructions=\"Write code\")\n\nagency = Agency(\n ceo,\n developer,\n communication_flows=[\n (ceo > developer), # CEO can delegate to Developer\n (developer > ceo), # Developer can report back to CEO\n ]\n)\n```\n\n### Handoff-Based Flows\n\nHandoffs transfer conversational control to another agent:\n\n```python\nfrom agency_swarm.tools import Handoff\n\nsupport = Agent(name=\"Support\", instructions=\"Handle basic queries\")\nspecialist = Agent(name=\"Specialist\", instructions=\"Handle complex issues\")\n\nagency = Agency(\n support,\n specialist,\n communication_flows=[\n (support > specialist, Handoff), # Support escalates to Specialist\n ]\n)\n```\n\n资料来源：[examples/interactive/tui.py:48-52]()\n\n### Custom SendMessage Classes\n\nFor flows requiring additional context passing, use custom SendMessage classes:\n\n```python\nfrom agency_swarm.tools import SendMessage\nfrom agency_swarm import Agent, Agency\n\nclass SendMessageWithContext(SendMessage):\n \"\"\"Custom SendMessage that includes context about key decisions.\"\"\"\n pass\n\ncoordinator = Agent(name=\"Coordinator\", instructions=\"Coordinate tasks\")\nspecialist = Agent(name=\"Specialist\", instructions=\"Execute specialized tasks\")\n\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 send_message_tool_class=SendMessageWithContext,\n)\n```\n\n资料来源：[examples/custom_send_message.py:20-32]()\n\n### Multi-Agent Communication Chains\n\nComplex workflows can involve multiple agents in a single flow definition:\n\n```python\ndev = Agent(name=\"Developer\", instructions=\"Write code\")\nqa = Agent(name=\"QA\", instructions=\"Test code\")\npm = Agent(name=\"PM\", instructions=\"Manage project\")\n\nagency = Agency(\n dev,\n qa,\n pm,\n communication_flows=[\n (dev < ceo > pm > dev), # Multi-agent chain with CEO\n (dev > qa, Handoff), # Developer can hand off to QA\n ]\n)\n```\n\n资料来源：[examples/agency_visualization.py:25-35]()\n\n## Flow Visualization\n\nThe Agency class provides visualization capabilities for communication flows:\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\nThis generates an interactive HTML visualization showing:\n\n- Agent nodes and their connections\n- Communication flow directions\n- Tool availability per agent\n- Entry point indicators\n\n## SendMessage Tool Reference\n\n### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `recipient` | Agent | Yes | Target agent for the message |\n| `message` | str | Yes | Content to send |\n| `images` | list | No | Image attachments |\n| `files` | list | No | File attachments |\n\n### Configuration via Agency\n\nSet default behavior for all flows:\n\n```python\nagency = Agency(\n agent_a,\n agent_b,\n communication_flows=[agent_a > agent_b],\n send_message_tool_class=CustomSendMessage, # Default for all flows\n)\n```\n\n资料来源：[src/agency_swarm/tools/send_message.py]()\n\n## Handoff Tool Reference\n\n### Behavior\n\nWhen an agent executes a Handoff:\n\n1. Current agent's response is terminated\n2. Control transfers to the target agent\n3. Original message context is preserved\n4. Target agent receives the conversation state\n\n### Use Cases\n\n| Scenario | Benefit |\n|----------|---------|\n| Escalation | Route to specialized agents |\n| Task completion | Transfer to confirmation agent |\n| Parallel processing | Split work across specialists |\n\n## Shared Instructions\n\nCommunication flows can leverage shared instructions for consistent behavior:\n\n```python\nagency = Agency(\n coordinator,\n specialist,\n communication_flows=[coordinator > specialist],\n shared_instructions=\"All agents should use key decisions to guide their actions.\",\n)\n```\n\nShared instructions are available to all agents in the agency and provide context for communication decisions.\n\n## Best Practices\n\n### Flow Design Principles\n\n1. **Explicit Over Implicit**: Always define flows explicitly rather than relying on defaults\n2. **Minimal Paths**: Only create necessary communication pathways\n3. **Directional Clarity**: Design flows with clear escalation paths\n4. **Context Preservation**: Use custom SendMessage classes when context matters\n\n### Security Considerations\n\n- Limit communication flows to only necessary agent pairs\n- Use shared instructions to establish boundaries\n- Review flow visualizations for unintended pathways\n\n### Performance\n\n- Avoid circular flows without exit conditions\n- Limit the depth of multi-agent chains\n- Consider async patterns for long-running workflows\n\n## Example: Complete Multi-Agent Workflow\n\n```python\nfrom agency_swarm import Agent, Agency\nfrom agency_swarm.tools import SendMessage, Handoff\n\n# Define agents\nceo = Agent(\n name=\"CEO\",\n instructions=\"You manage the overall workflow and delegate tasks.\"\n)\ncoordinator = Agent(\n name=\"Coordinator\", \n instructions=\"Coordinate between teams and track progress.\"\n)\ndeveloper = Agent(\n name=\"Developer\",\n instructions=\"Implement technical solutions.\"\n)\nqa = Agent(\n name=\"QA\",\n instructions=\"Test and validate deliverables.\"\n)\n\n# Create agency with communication flows\nagency = Agency(\n ceo, # Entry point (positional argument)\n coordinator,\n developer,\n qa,\n communication_flows=[\n (ceo > coordinator), # CEO delegates to Coordinator\n (coordinator > developer), # Coordinator assigns to Developer\n (coordinator > qa), # Coordinator assigns to QA\n (developer > qa, Handoff), # Developer hands off to QA for testing\n (qa > coordinator), # QA reports back to Coordinator\n (coordinator > ceo), # Coordinator reports to CEO\n ],\n shared_instructions=\"Follow the standard workflow: develop, test, then report.\"\n)\n\n# Execute workflow\nasync def main():\n result = await agency.get_response(\"Start the Q4 optimization project.\")\n print(result.final_output)\n```\n\n## See Also\n\n- [Agent Documentation](agents) - Individual agent configuration\n- [Tools Reference](tools) - SendMessage and Handoff tools\n- [Agency Visualization](visualization) - Interactive flow visualization\n- [FastAPI Integration](fastapi-integration) - Deploying agencies with communication flows\n\n---\n\n\n\n## Context Management\n\n### 相关页面\n\n相关主题：[Core Architecture](#page-core-architecture), [Agent Internals](#page-agent-internal), [Messaging System](#page-messaging-system)\n\n\nRelevant Source Files
\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- [examples/agency_context.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_context.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- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)\n- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n \n\n# Context Management\n\n## Overview\n\nContext Management in Agency Swarm refers to the mechanisms by which state, instructions, and runtime data are shared and propagated across agents within an agency. This system enables multi-agent collaboration by allowing agents to access shared information, communicate effectively, and maintain coherent workflows across complex task execution pipelines.\n\nThe context management architecture supports multiple layers of data sharing:\n\n1. **Agency-level shared instructions** that apply to all agents\n2. **Per-agent instructions** for role-specific guidance\n3. **Runtime context propagation** through the `AgencyContext` type\n4. **Message context** for passing additional data through communication flows\n\n资料来源：[examples/agency_context.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_context.py) \n资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n---\n\n## Core Context Types\n\n### AgencyContext\n\nThe `AgencyContext` type serves as the runtime container for contextual data passed between agents during execution. It flows through the agency hierarchy and is available to all agents during their turn in the conversation loop.\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, # Context from agency, or None for standalone\n **kwargs: Any,\n) -> RunResult:\n```\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `message` | `str \\| list[TResponseInputItem]` | The input message or list of message items |\n| `sender_name` | `str \\| None` | Identifier of the sending agent or user |\n| `context_override` | `dict[str, Any] \\| None` | Override values merged into context |\n| `agency_context` | `AgencyContext \\| None` | Context from agency, or None for standalone agents |\n\n资料来源：[src/agency_swarm/agent/core.py:35-54](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n---\n\n## Shared Instructions\n\n### Purpose and Scope\n\nShared instructions are a foundational context mechanism that applies uniform behavioral guidance across all agents within an agency. When an agent is instantiated as part of an agency, these instructions are prepended to the agent's individual instructions.\n\n```python\nreturn Agency(\n support,\n math,\n communication_flows=[(support, math, Handoff)],\n shared_instructions=\"Demonstrate reasoning, web search, file search, and handoffs.\",\n name=\"TuiDemoAgency\",\n)\n```\n\n### Behavior\n\n- **Precedence**: Individual agent instructions take precedence, but shared instructions provide foundational context\n- **Propagation**: Shared instructions are visible to all agents in the agency\n- **Use Cases**: Agency-wide policies, common procedures, general guidelines for all agents\n\n资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n---\n\n## Context Propagation Flow\n\n```mermaid\ngraph TD\n A[User Input / Agent Message] --> B{Agency.get_response}\n B --> C[Initialize AgencyContext]\n C --> D[Load Shared Instructions]\n D --> E[Load Agent-specific Instructions]\n E --> F[Merge context_override if provided]\n F --> G[Execute Agent Turn]\n G --> H[Run Tools if needed]\n H --> I[Communicate via SendMessage]\n I --> J{Communication Flow defined?}\n J -->|Yes| K[Pass AgencyContext to target agent]\n J -->|No| L[Return RunResult]\n K --> G\n L --> M[Final Output]\n\n style C fill:#e1f5fe\n style D fill:#fff3e0\n style F fill:#e8f5e9\n```\n\n---\n\n## Communication Flows and Context\n\n### SendMessageWithContext\n\nWhen agents communicate through defined flows, they can pass additional contextual data using `SendMessageWithContext`. This allows the sending agent to inject specific data into the recipient's context before processing.\n\n```python\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### Key Communication Patterns\n\n| Pattern | Class | Context Behavior |\n|---------|-------|------------------|\n| Direct Message | `SendMessage` | Basic message passing |\n| Message with Context | `SendMessageWithContext` | Includes additional context data |\n| Agent Handoff | `Handoff` | Transfers full control to another agent |\n\n资料来源：[examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)\n\n---\n\n## Context Override Mechanism\n\nThe `context_override` parameter allows runtime modification of the context dictionary. This is particularly useful when specific values need to be injected into an agent's execution context without modifying the core agency configuration.\n\n```python\ncontext_override: dict[str, Any] | None = None\n```\n\n**Use Cases:**\n\n1. Injecting user-specific data for a particular interaction\n2. Providing one-time instructions for a specific task\n3. Overriding default values based on runtime conditions\n\n资料来源：[src/agency_swarm/agent/core.py:40](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)\n\n---\n\n## Context in Multi-Agent Workflows\n\n### Agency-Level Context Example\n\nThe following demonstrates a complete context management pattern in a multi-agent setup:\n\n```python\ndef create_demo_agency():\n support = Agent(\n name=\"SupportAgent\",\n description=\"Handles user support requests with file search and web search.\",\n instructions=(\n \"You are a helpful support agent. Use your tools to assist users. \"\n \"You can analyze files and search the web to find answers. \"\n \"You can also use the calculate tool for math. \"\n \"When the user asks about something you don't know, use the web search tool to \"\n \"inspect them before answering.\"\n ),\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 conversation_starters=[\n \"Tell me about daily_revenue_report.pdf.\",\n \"Search the web for the latest Bun release notes.\",\n \"What is 345 * 18?\",\n \"Compare research_report.txt with daily_revenue_report.pdf.\",\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(reasoning=Reasoning(effort=\"high\", summary=\"auto\")),\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 name=\"TuiDemoAgency\",\n )\n```\n\n**Context Flow in This Example:**\n\n1. **Shared Instructions**: \"Demonstrate reasoning, web search, file search, and handoffs.\" applies to both agents\n2. **Communication Flow**: SupportAgent can hand off to MathAgent for calculation tasks\n3. **Agent-Specific Instructions**: Each agent has its own detailed instructions\n4. **Tool Context**: Each agent has access to specific tools with their own execution contexts\n\n资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)\n\n---\n\n## Context and Visualization\n\nThe agency visualization feature can display communication flows and context relationships:\n\n```python\nagency = create_demo_agency()\n\n# Generate interactive HTML visualization\nhtml_file = agency.visualize(\n output_file=\"agency_interactive_demo.html\",\n include_tools=True,\n open_browser=True,\n)\n```\n\nThis visualization shows:\n- How context flows between agents\n- Communication flow definitions\n- Entry points where context originates\n- Tool relationships within the context\n\n资料来源：[examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)\n\n---\n\n## Summary Table: Context Management Components\n\n| Component | Type | Scope | Purpose |\n|-----------|------|-------|---------|\n| `AgencyContext` | Class | Runtime | Container for runtime contextual data |\n| `shared_instructions` | Parameter | Agency-wide | Instructions applying to all agents |\n| `context_override` | Parameter | Per-call | Runtime injection of context values |\n| `additional_instructions` | Parameter | Per-call | Supplemental instructions for single execution |\n| `SendMessageWithContext` | Class | Communication | Pass context through agent messaging |\n\n---\n\n## Best Practices\n\n1. **Use Shared Instructions Sparingly**: Keep shared instructions concise and universally applicable\n2. **Leverage context_override for One-time Data**: Avoid modifying core configuration for transient data\n3. **Define Clear Communication Flows**: Explicit flows ensure predictable context propagation\n4. **Document Agent Instructions**: Clear instructions reduce ambiguity in context interpretation\n5. **Use Handoffs for Complete Transfers**: When full control should pass to another agent, use Handoff instead of basic messaging\n\n---\n\n\n\n## Messaging System\n\n### 相关页面\n\n相关主题：[Communication Flows](#page-communication-flows), [Context Management](#page-context-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/messages/__init__.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/__init__.py)\n- [src/agency_swarm/messages/message_formatter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/message_formatter.py)\n- [src/agency_swarm/messages/message_filter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/message_filter.py)\n- [src/agency_swarm/messages/response_input_sanitizer.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/response_input_sanitizer.py)\n- [src/agency_swarm/agent/execution_streaming.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/execution_streaming.py)\n \n\n# Messaging System\n\nThe Messaging System in Agency Swarm is a foundational layer responsible for handling all communication between agents, users, and external systems. It manages message formatting, filtering, sanitization, streaming, and conversion to ensure reliable and secure inter-agent communication.\n\n## Architecture Overview\n\nThe messaging system consists of several interconnected modules that process messages at different stages of agent execution.\n\n```mermaid\ngraph TD\n A[User/Agent Input] --> B[Message Filter]\n B --> C[Response Input Sanitizer]\n C --> D[Message Formatter]\n D --> E[Agent Core]\n E --> F[Execution Streaming]\n F --> G[Output Messages]\n \n H[Tool Calls] --> D\n I[Guardrails] --> D\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `__init__.py` | `messages/__init__.py` | Module exports and public API |\n| `message_formatter.py` | `messages/message_formatter.py` | Formats messages for different contexts |\n| `message_filter.py` | `messages/message_filter.py` | Filters and validates incoming messages |\n| `response_input_sanitizer.py` | `messages/response_input_sanitizer.py` | Sanitizes input for security |\n| `execution_streaming.py` | `agent/execution_streaming.py` | Handles streaming responses |\n\n## Message Flow Pipeline\n\nMessages traverse a multi-stage pipeline before reaching their destination. Each stage performs specific transformations or validations.\n\n```mermaid\ngraph LR\n subgraph Input_Processing\n F1[Filter] --> F2[Sanitize] --> F3[Format]\n end\n \n subgraph Core_Processing\n F3 --> F4[Agent Execution]\n end\n \n subgraph Output_Processing\n F4 --> F5[Streaming Output]\n end\n```\n\n### Stage 1: Message Filtering\n\nThe `MessageFilter` class provides initial validation and filtering capabilities for incoming messages. It ensures that messages meet basic structural requirements before further processing.\n\n资料来源：[src/agency_swarm/messages/message_filter.py:1-50]()\n\n### Stage 2: Input Sanitization\n\nThe `ResponseInputSanitizer` module sanitizes user input to prevent injection attacks and ensure compatibility with the OpenAI API response format requirements.\n\n```python\n# Sanitization removes or escapes potentially harmful content\nsanitized_input = ResponseInputSanitizer.sanitize(raw_message)\n```\n\n资料来源：[src/agency_swarm/messages/response_input_sanitizer.py:1-30]()\n\n### Stage 3: Message Formatting\n\nThe `MessageFormatter` handles the final transformation of messages, adapting them for different contexts such as agent-to-agent communication, tool execution, or user display.\n\n资料来源：[src/agency_swarm/messages/message_formatter.py:1-40]()\n\n## Streaming Execution\n\nThe streaming system provides real-time message delivery during agent execution, enabling responsive user experiences.\n\n### Streaming Architecture\n\n```mermaid\ngraph TD\n A[get_response_stream] --> B[StreamingRunResponse]\n B --> C[Event Stream]\n C --> D[text/event-stream]\n D --> E[Client Application]\n \n F[RunResult] --> G[new_items]\n G --> H[message_history]\n H --> I[Final Output]\n```\n\n### Streaming Methods\n\n| Method | Return Type | Purpose |\n|--------|-------------|---------|\n| `get_response_stream()` | `StreamingRunResponse` | Initiates streaming execution |\n| `get_response()` | `RunResult` | Returns complete result after execution |\n\n资料来源：[src/agency_swarm/agent/core.py:100-130]()\n\n### Streaming Configuration\n\nThe streaming system integrates with the execution layer to provide real-time updates:\n\n```python\ndef get_response_stream(\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) -> StreamingRunResponse:\n```\n\n资料来源：[src/agency_swarm/agent/core.py:130-160]()\n\n## Message Conversion\n\nThe system includes utilities for converting between different message formats, particularly between internal `RunItem` objects and OpenAI-compatible `TResponseInputItem` format.\n\n### RunItem to TResponseInputItem Conversion\n\n```mermaid\ngraph TD\n A[RunItem] --> B[run_item_to_tresponse_input_item]\n B --> C{TResponseInputItem}\n \n C --> D[message]\n C --> E[image_url]\n C --> F[tool_call]\n C --> E[tool_result]\n```\n\nThe conversion function uses the SDK's built-in conversion method:\n\n```python\ndef run_item_to_tresponse_input_item(item: RunItem) -> TResponseInputItem | None:\n try:\n converted_item = item.to_input_item()\n return converted_item\n except Exception as e:\n logger.warning(f\"Failed to convert {type(item).__name__}\")\n return None\n```\n\n资料来源：[src/agency_swarm/agent/execution_helpers.py:80-100]()\n\n## Message Types and Structures\n\n### TResponseInputItem Format\n\nThe system uses `TResponseInputItem` for message representation, supporting multiple content types:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `role` | `str` | Message role (user, assistant, system) |\n| `content` | `str` | Text content |\n| `name` | `str` | Sender name |\n| `tool_calls` | `list` | Tool call requests |\n| `tool_call_id` | `str` | Tool result identifier |\n\n### RunResult Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `input` | `list` | Original input messages |\n| `new_items` | `list[RunItem]` | New items generated during run |\n| `raw_responses` | `list` | Raw API responses |\n| `final_output` | `Any` | Processed final output |\n| `input_guardrail_results` | `list` | Input validation results |\n| `output_guardrail_results` | `list` | Output validation results |\n\n资料来源：[src/agency_swarm/agent/execution_helpers.py:50-75]()\n\n## Context Management\n\n### AgencyContext\n\nThe `AgencyContext` provides shared context for message processing across agents:\n\n```mermaid\ngraph TD\n A[AgencyContext] --> B[Shared State]\n A --> C[Agent Registry]\n A --> D[Communication Flows]\n A --> E[Message History]\n```\n\nContext is automatically created for standalone agent usage:\n\n```python\nif agency_context is None:\n agency_context = self._create_minimal_context()\n```\n\n资料来源：[src/agency_swarm/agent/core.py:85-95]()\n\n## Integration with Agent Execution\n\n### Execution Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Agent\n participant MessageSystem\n participant OpenAI_API\n \n User->>Agent: get_response(message)\n Agent->>MessageSystem: Filter & Sanitize\n MessageSystem->>MessageSystem: Format\n Agent->>OpenAI_API: Run Request\n OpenAI_API-->>Agent: Streaming Events\n Agent->>MessageSystem: Convert RunItem\n MessageSystem->>User: Final Output\n```\n\n### Method Signatures\n\n**Async Response Method:**\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**Streaming Response Method:**\n```python\ndef get_response_stream(\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) -> StreamingRunResponse:\n```\n\n资料来源：[src/agency_swarm/agent/core.py:95-160]()\n\n## Configuration Options\n\n### RunConfig Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `temperature` | `float` | `None` | Sampling temperature |\n| `top_p` | `float` | `None` | Nucleus sampling threshold |\n| `reasoning` | `Reasoning` | `None` | Reasoning configuration |\n| `max_tokens` | `int` | `None` | Maximum output tokens |\n\n### Message Filtering Options\n\n| Option | Description |\n|--------|-------------|\n| `strict_mode` | Enable strict validation |\n| `allowed_roles` | Restrict message roles |\n| `max_length` | Maximum message length |\n\n## Error Handling\n\nThe messaging system implements comprehensive error handling:\n\n```python\ntry:\n converted_item = item.to_input_item()\n logger.debug(f\"Converting {type(item).__name__} using SDK to_input_item()\")\n return converted_item\nexcept Exception as e:\n logger.warning(f\"Failed to convert {type(item).__name__}\")\n return None\n```\n\n资料来源：[src/agency_swarm/agent/execution_helpers.py:85-95]()\n\n## Usage Examples\n\n### Basic Message Flow\n\n```python\nfrom agency_swarm import Agent\n\nagent = Agent(name=\"Assistant\")\n\n# Synchronous message\nresult = await agent.get_response(\"Hello, how are you?\")\nprint(result.final_output)\n\n# Streaming message\nstream = agent.get_response_stream(\"Tell me a story\")\nfor event in stream:\n print(event, end=\"\", flush=True)\n```\n\n### Tool Message Handling\n\n```python\n# Tool results are automatically converted to message format\ntool_result = {\n \"tool_call_id\": \"call_abc123\",\n \"output\": \"File content here\"\n}\n# Converted to TResponseInputItem automatically\n```\n\n## Best Practices\n\n1. **Always provide `agency_context`** when agents communicate within an agency\n2. **Use streaming** for long-running operations to improve responsiveness\n3. **Implement guardrails** for input/output validation at the message level\n4. **Monitor message size** to prevent token limit issues\n5. **Handle conversion errors** gracefully with fallback mechanisms\n\n---\n\n\n\n## File Management\n\n### 相关页面\n\n相关主题：[Agent Internals](#page-agent-internal), [Tools System](#page-tools-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agency_swarm/agent/file_manager.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/file_manager.py)\n- [src/agency_swarm/agent/file_sync.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/file_sync.py)\n- [src/agency_swarm/agent/attachment_manager.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/attachment_manager.py)\n- [examples/agent_file_storage.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agent_file_storage.py)\n- [examples/message_attachments.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/message_attachments.py)\n \n\n# File Management\n\n## Overview\n\nFile Management in Agency Swarm provides a comprehensive system for handling file uploads, vector store creation, file search capabilities, and message attachments across multi-agent workflows. The system enables agents to work with persistent file storage, search through uploaded documents, and exchange files as part of their communication protocols.\n\nThe file management architecture consists of three primary components that work together to provide seamless file handling: `FileManager`, `FileSync`, and `AttachmentManager`. Each serves a distinct role in the file lifecycle from upload through search and message integration.\n\n资料来源：[examples/README.md]()\n\n## Core Components\n\n### FileManager\n\nThe `FileManager` class handles the core file operations for an agent, including uploading files to OpenAI's vector stores and managing file associations. It provides the primary interface for agents to work with persistent file storage.\n\n**Key Responsibilities:**\n- Upload files to OpenAI vector stores\n- Associate files with specific agents\n- Enable file search capabilities through vector store integration\n- Manage file lifecycle within agent contexts\n\n**API Reference:**\n\n| Method | Parameters | Return Type | Description |\n|--------|------------|-------------|-------------|\n| `upload_file` | `file_path: str`, `include_in_vector_store: bool = True` | `str` | Upload a file and optionally add to vector store |\n| `create_vector_store` | Various configuration params | `VectorStore` | Create a new vector store for the agent |\n\n资料来源：[src/agency_swarm/agent/core.py:68-73]()\n\n### FileSync\n\n`FileSync` manages the synchronization of files across agent instances, ensuring that file references remain consistent when agents share context or communicate. It handles the transfer and validation of file metadata between agents in an agency.\n\n### AttachmentManager\n\nThe `AttachmentManager` handles file attachments in messages, enabling agents to include files in their communications. This component supports multimodal outputs and file references within the message protocol.\n\n资料来源：[examples/message_attachments.py]()\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"File Management Architecture\"\n FM[FileManager] --> VS[Vector Store]\n FM --> A[Agent Instance]\n FS[FileSync] --> FM\n FS --> A2[Other Agents]\n AM[AttachmentManager] --> M[Messages]\n M --> A\n VS --> FSR[File Search Results]\n end\n \n subgraph \"External Services\"\n OpenAI[OpenAI API]\n OpenAI --> VS\n OpenAI --> M\n end\n```\n\n## File Upload Workflow\n\nFiles can be uploaded to an agent's context using the `upload_file` method. The workflow follows a sequential process:\n\n1. File is validated for existence and accessibility\n2. File is uploaded to OpenAI's storage system\n3. Optionally, file is indexed in a vector store for search\n4. File reference is associated with the agent's session\n\n```python\n# From agent instance\nagent = Agent(name=\"DocumentProcessor\", ...)\n\n# Upload file and include in vector store for search\nfile_id = agent.upload_file(\n file_path=\"documents/report.pdf\",\n include_in_vector_store=True\n)\n```\n\n资料来源：[src/agency_swarm/agent/core.py:68-73]()\n\n## Vector Store Integration\n\nAgency Swarm integrates with OpenAI's File Search tool through vector store creation. This enables agents to semantic search through uploaded documents.\n\n```python\nfrom agency_swarm import Agent\nfrom agency_swarm.tools import FileSearchTool\n\nagent = Agent(\n name=\"ResearchAgent\",\n description=\"Processes and searches through research documents\",\n tools=[FileSearchTool], # Enables semantic file search\n files_folder=\"./research_papers\",\n)\n```\n\n资料来源：[examples/agent_file_storage.py]()\n资料来源：[examples/README.md]()\n\n## File Handling in Messages\n\nThe AttachmentManager enables files to be included in agent messages, supporting multimodal interactions where agents can reference, process, and respond to file contents.\n\n**Supported File Types:**\n- Documents (PDF, TXT, MD)\n- Images (PNG, JPG, GIF)\n- Data files (CSV, JSON)\n- Code files\n\n**Output Types:**\n\n| Type | Description | Use Case |\n|------|-------------|----------|\n| `ToolOutputImage` | Image outputs from tools | Visualization, charts |\n| `ToolOutputFileContent` | File attachments in responses | Reports, generated documents |\n| `ToolOutputFileFromUrl` | Remote file serving | PDF reports, external data |\n\n资料来源：[examples/multimodal_outputs.py]()\n\n## Agent Folder Structure\n\nAgents that handle files should follow a specific folder structure:\n\n```\nAgentName/\n├── files/ # Files uploaded to OpenAI\n├── schemas/ # OpenAPI schemas for tool generation\n├── tools/ # Custom tool implementations\n├── AgentName.py # Main agent class\n├── __init__.py # Package initialization\n└── instructions.md # Agent instructions\n```\n\n资料来源：[CONTRIBUTING.md]()\n资料来源：[README.md]()\n\n## Configuration Options\n\n### Agent File Configuration\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `files_folder` | `str` | `None` | Path to folder containing files to upload |\n| `include_search_results` | `bool` | `False` | Include search results in responses |\n| `schemas_folder` | `str` | `None` | Path to OpenAPI schema files |\n\n### Model Settings for File Processing\n\nWhen processing files, consider adjusting model settings for better performance:\n\n```python\nfrom agency_swarm import Agent, ModelSettings\nfrom agency_swarm.util.builtins import Reasoning\n\nagent = Agent(\n name=\"FileAnalyzer\",\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]()\n\n## Examples\n\n### Vector Store Creation and File Search\n\n```python\n# Complete example from agent_file_storage.py\nfrom agency_swarm import Agent, Agency\n\n# Create agent with file search capability\ndocument_agent = Agent(\n name=\"DocumentAgent\",\n description=\"Handles document storage and search\",\n tools=[FileSearchTool], # Built-in tool for semantic search\n)\n\n# Agency with document handling\nagency = Agency([document_agent])\n\n# Upload documents for search\nresponse = agency.get_response_sync(\n \"Please analyze the quarterly_reports folder\"\n)\n```\n\n### Message Attachments\n\n```python\n# Example from message_attachments.py\nfrom agency_swarm.tools.utils import (\n tool_output_file_from_url,\n tool_output_image_from_path\n)\n\nclass GenerateReportTool(BaseTool):\n def run(self) -> ToolOutputFileContent:\n return tool_output_file_from_url(\n \"https://example.com/report.pdf\"\n )\n```\n\n资料来源：[examples/agent_file_storage.py]()\n资料来源：[examples/message_attachments.py]()\n\n## Best Practices\n\n1. **File Organization**: Maintain clean `files/` directories per agent to avoid confusion in multi-agent setups\n\n2. **Vector Store Management**: Only include files that need semantic search in vector stores to optimize costs and performance\n\n3. **File Size Limits**: Be mindful of OpenAI's file size limits (512 MB maximum per file)\n\n4. **Persistent Sessions**: Use `CustomizableChatHistory` for maintaining file context across sessions\n\n5. **Tool Output Efficiency**: Use `tool_output_file_from_url` for remote files instead of downloading and re-uploading\n\n资料来源：[examples/README.md]()\n资料来源：[examples/custom_persistence.py]()\n\n## Related Components\n\n| Component | File Path | Purpose |\n|-----------|-----------|---------|\n| BaseTool | `src/agency_swarm/tools/` | Custom tool creation with file outputs |\n| ToolFactory | `src/agency_swarm/tools/` | OpenAPI schema to tools conversion |\n| FileSearchTool | `src/agency_swarm/tools/` | Built-in semantic search capability |\n| OpenAI Integrations | `src/agency_swarm/integrations/` | External service file handling |\n\n## Summary\n\nThe File Management system in Agency Swarm provides a robust foundation for handling file operations across multi-agent workflows. By leveraging `FileManager` for core operations, `FileSync` for cross-agent synchronization, and `AttachmentManager` for message integration, developers can build sophisticated agentic systems that process, search, and communicate with files seamlessly.\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. page-introduction：Introduction to Agency Swarm。围绕“Introduction to Agency Swarm”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：Installation and Setup。围绕“Installation and Setup”模拟一次用户任务，不展示安装或运行结果。\n3. page-getting-started：Getting Started Guide。围绕“Getting Started Guide”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-architecture：Core Architecture。围绕“Core Architecture”模拟一次用户任务，不展示安装或运行结果。\n5. page-tools-system：Tools System。围绕“Tools System”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Introduction to Agency Swarm”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“Installation and Setup”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-getting-started\n输入：用户提供的“Getting Started Guide”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-architecture\n输入：用户提供的“Core Architecture”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-tools-system\n输入：用户提供的“Tools System”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Introduction to Agency Swarm”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“Installation and Setup”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-getting-started：Step 3 必须围绕“Getting Started Guide”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-architecture：Step 4 必须围绕“Core Architecture”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-tools-system：Step 5 必须围绕“Tools System”形成一个小中间产物，并等待用户确认。\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- docs/welcome/installation.mdx\n- docs/welcome/getting-started/from-scratch.mdx\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"
}