{
"canonical_name": "openai/openai-agents-python",
"compilation_id": "pack_9f4a8adffcfa482c888e6146823a0afa",
"created_at": "2026-05-11T16:56:39.614937+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 openai-agents` 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 openai-agents",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_257edd4094dd4a6a99c62978cc705e4c"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_8752be4b06039a2da37314148c77fa7d",
"canonical_name": "openai/openai-agents-python",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/openai/openai-agents-python",
"slug": "openai-agents-python",
"source_packet_id": "phit_f4776ce49b7247d8b3baa7b9d90cee19",
"source_validation_id": "dval_a44f7347bf66437e874a64a265e0fceb"
},
"merchandising": {
"best_for": "需要流程自动化能力，并使用 chatgpt的用户",
"github_forks": 4024,
"github_stars": 26261,
"one_liner_en": "A lightweight, powerful framework for multi-agent workflows",
"one_liner_zh": "A lightweight, powerful framework for multi-agent workflows",
"primary_category": {
"category_id": "workflow-automation",
"confidence": "medium",
"name_en": "Workflow Automation",
"name_zh": "流程自动化",
"reason": "matched_keywords:workflow, agent"
},
"target_user": "使用 chatgpt 等宿主 AI 的用户",
"title_en": "openai-agents-python",
"title_zh": "openai-agents-python 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Page Observation and Action Planning",
"label_zh": "页面观察与动作规划",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-page-observation-and-action-planning",
"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_f4776ce49b7247d8b3baa7b9d90cee19",
"page_model": {
"artifacts": {
"artifact_slug": "openai-agents-python",
"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 openai-agents",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/openai/openai-agents-python#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"页面观察与动作规划",
"评测体系"
],
"eyebrow": "流程自动化",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要流程自动化能力，并使用 chatgpt的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "A lightweight, powerful framework for multi-agent workflows"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "chatgpt",
"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": "仓库名 `openai-agents-python` 与安装入口 `openai-agents` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:946380199 | https://github.com/openai/openai-agents-python | repo=openai-agents-python; install=openai-agents"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the base table",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_d867c75f80af49c9968398851ff8bf6a | https://github.com/openai/openai-agents-python/issues/3346 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the base table",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Clarify whether retry-after delays should respect retry max_delay",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_f486d2247bf24df8bbc7a2bd6fddbd65 | https://github.com/openai/openai-agents-python/issues/3266 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Clarify whether retry-after delays should respect retry max_delay",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenAIConversationsSession persists empty reasoning item {\"type\":\"reasoning\",\"summary\":[]} and Conversations API rejects it as invalid",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_d6bad5c23bf3457eb546c22a1636cc26 | https://github.com/openai/openai-agents-python/issues/3268 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：OpenAIConversationsSession persists empty reasoning item {\"type\":\"reasoning\",\"summary\":[]} and Conversations API reject…",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Tracing shutdown cannot interrupt exporter retry backoff",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_e1ceae098cf84c8aafae7082b13c5345 | https://github.com/openai/openai-agents-python/issues/3354 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Tracing shutdown cannot interrupt exporter retry backoff",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.15.2",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_b73472b5ae90447199984775aacdca67 | https://github.com/openai/openai-agents-python/releases/tag/v0.15.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.15.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.15.3",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_7e05a382001a4d07b74eda1e1316320b | https://github.com/openai/openai-agents-python/releases/tag/v0.15.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.15.3",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.16.1",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_44335088ff52486e9f2f41f72a274c35 | https://github.com/openai/openai-agents-python/releases/tag/v0.16.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.16.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.17.0",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_86b81f310a6e45feadc65196a057b23b | https://github.com/openai/openai-agents-python/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.17.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.15.1",
"category": "能力坑",
"evidence": [
"community_evidence:github | cevd_4c70d563ac704aeaa14b8e2c49976bc5 | https://github.com/openai/openai-agents-python/releases/tag/v0.15.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.15.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:946380199 | https://github.com/openai/openai-agents-python | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.14.8",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_a31947cfee3a4299923f7714bfb54f42 | https://github.com/openai/openai-agents-python/releases/tag/v0.14.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.14.8",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：AdvancedSQLiteSession.add_items can report success after structure metadata failure",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_0fed2dd63d55400d9e0d9adaf08570e5 | https://github.com/openai/openai-agents-python/issues/3348 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：AdvancedSQLiteSession.add_items can report success after structure metadata failure",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Chat Completions converter can send empty tool output for non-text results",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_34a35e920a01467e957cdd59b4179cc1 | https://github.com/openai/openai-agents-python/issues/3310 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Chat Completions converter can send empty tool output for non-text results",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.15.0",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_33cd0193aea84f9b82b15a02098d85cd | https://github.com/openai/openai-agents-python/releases/tag/v0.15.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.15.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:946380199 | https://github.com/openai/openai-agents-python | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 24 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 269,
"forks": 4024,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 26261,
"open_issues": 85,
"pushed_at": null
},
"source_url": "https://github.com/openai/openai-agents-python",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "A lightweight, powerful framework for multi-agent workflows",
"title": "openai-agents-python 能力包",
"trial_prompt": "# openai-agents-python - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 openai-agents-python 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的流程自动化任务。\n我常用的宿主 AI：chatgpt\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. overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. quickstart：快速开始指南。围绕“快速开始指南”模拟一次用户任务，不展示安装或运行结果。\n3. core-concepts：核心概念。围绕“核心概念”模拟一次用户任务，不展示安装或运行结果。\n4. agent-core：Agent 核心框架。围绕“Agent 核心框架”模拟一次用户任务，不展示安装或运行结果。\n5. tools：工具系统。围绕“工具系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quickstart\n输入：用户提供的“快速开始指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. core-concepts\n输入：用户提供的“核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. agent-core\n输入：用户提供的“Agent 核心框架”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. tools\n输入：用户提供的“工具系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / quickstart：Step 2 必须围绕“快速开始指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / core-concepts：Step 3 必须围绕“核心概念”形成一个小中间产物，并等待用户确认。\n- Step 4 / agent-core：Step 4 必须围绕“Agent 核心框架”形成一个小中间产物，并等待用户确认。\n- Step 5 / tools：Step 5 必须围绕“工具系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/openai/openai-agents-python\n- https://github.com/openai/openai-agents-python#readme\n- .agents/skills/code-change-verification/SKILL.md\n- .agents/skills/docs-sync/SKILL.md\n- .agents/skills/examples-auto-run/SKILL.md\n- .agents/skills/final-release-review/SKILL.md\n- .agents/skills/implementation-strategy/SKILL.md\n- .agents/skills/openai-knowledge/SKILL.md\n- .agents/skills/pr-draft-summary/SKILL.md\n- .agents/skills/runtime-behavior-probe/SKILL.md\n- .agents/skills/test-coverage-improver/SKILL.md\n- examples/sandbox/docs/skills/credit-note-fixer/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 openai-agents-python 的核心服务。\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: Tracing shutdown cannot interrupt exporter retry backoff（https://github.com/openai/openai-agents-python/issues/3354）；github/github_issue: Proposal: per-run BudgetGuard for token / request / cost limits (follow-（https://github.com/openai/openai-agents-python/issues/3353）；github/github_issue: OpenAIConversationsSession persists empty reasoning item {\"type\":\"reason（https://github.com/openai/openai-agents-python/issues/3268）；github/github_issue: Chat Completions converter can send empty tool output for non-text resul（https://github.com/openai/openai-agents-python/issues/3310）；github/github_issue: Clarify whether retry-after delays should respect retry max_delay（https://github.com/openai/openai-agents-python/issues/3266）；github/github_issue: AdvancedSQLiteSession.add_items can report success after structure metad（https://github.com/openai/openai-agents-python/issues/3348）；github/github_issue: AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the（https://github.com/openai/openai-agents-python/issues/3346）；github/github_release: v0.17.1（https://github.com/openai/openai-agents-python/releases/tag/v0.17.1）；github/github_release: v0.17.0（https://github.com/openai/openai-agents-python/releases/tag/v0.17.0）；github/github_release: v0.16.1（https://github.com/openai/openai-agents-python/releases/tag/v0.16.1）；github/github_release: v0.16.0（https://github.com/openai/openai-agents-python/releases/tag/v0.16.0）；github/github_release: v0.15.3（https://github.com/openai/openai-agents-python/releases/tag/v0.15.3）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Tracing shutdown cannot interrupt exporter retry backoff",
"url": "https://github.com/openai/openai-agents-python/issues/3354"
},
{
"kind": "github_issue",
"source": "github",
"title": "Proposal: per-run BudgetGuard for token / request / cost limits (follow-",
"url": "https://github.com/openai/openai-agents-python/issues/3353"
},
{
"kind": "github_issue",
"source": "github",
"title": "OpenAIConversationsSession persists empty reasoning item {\"type\":\"reason",
"url": "https://github.com/openai/openai-agents-python/issues/3268"
},
{
"kind": "github_issue",
"source": "github",
"title": "Chat Completions converter can send empty tool output for non-text resul",
"url": "https://github.com/openai/openai-agents-python/issues/3310"
},
{
"kind": "github_issue",
"source": "github",
"title": "Clarify whether retry-after delays should respect retry max_delay",
"url": "https://github.com/openai/openai-agents-python/issues/3266"
},
{
"kind": "github_issue",
"source": "github",
"title": "AdvancedSQLiteSession.add_items can report success after structure metad",
"url": "https://github.com/openai/openai-agents-python/issues/3348"
},
{
"kind": "github_issue",
"source": "github",
"title": "AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the",
"url": "https://github.com/openai/openai-agents-python/issues/3346"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.17.1",
"url": "https://github.com/openai/openai-agents-python/releases/tag/v0.17.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.17.0",
"url": "https://github.com/openai/openai-agents-python/releases/tag/v0.17.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.16.1",
"url": "https://github.com/openai/openai-agents-python/releases/tag/v0.16.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.16.0",
"url": "https://github.com/openai/openai-agents-python/releases/tag/v0.16.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.15.3",
"url": "https://github.com/openai/openai-agents-python/releases/tag/v0.15.3"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "流程自动化",
"desc": "A lightweight, powerful framework for multi-agent workflows",
"effort": "安装已验证",
"forks": 4016,
"icon": "bolt",
"name": "openai-agents-python 能力包",
"risk": "可发布",
"slug": "openai-agents-python",
"stars": 26190,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"页面观察与动作规划",
"评测体系"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/openai/openai-agents-python 项目说明书\n\n生成时间：2026-05-11 16:45:26 UTC\n\n## 目录\n\n- [项目概述](#overview)\n- [快速开始指南](#quickstart)\n- [核心概念](#core-concepts)\n- [Agent 核心框架](#agent-core)\n- [工具系统](#tools)\n- [MCP 协议集成](#mcp)\n- [Agent 转交机制](#handoffs)\n- [Guardrails 安全机制](#guardrails)\n- [沙箱 Agent 概述](#sandbox-agent)\n- [沙箱会话管理](#sandbox-session)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[快速开始指南](#quickstart), [核心概念](#core-concepts)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/openai/openai-agents-python/blob/main/README.md)\n- [pyproject.toml](https://github.com/openai/openai-agents-python/blob/main/pyproject.toml)\n- [src/agents/version.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/version.py)\n- [examples/sandbox/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/README.md)\n- [examples/research_bot/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/research_bot/README.md)\n- [examples/mcp/tool_filter_example/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/mcp/tool_filter_example/README.md)\n \n\n# 项目概述\n\n## 项目简介\n\nOpenAI Agents Python SDK 是一个强大的 Python 多智能体（Multi-Agent）编排框架，专为构建复杂的人工智能工作流和应用而设计。该项目源自 OpenAI 的前沿研究成果，旨在为开发者提供一套完整的工具集，用于创建能够协同工作、共享信息、相互交接任务的智能代理系统。\n\n该框架的核心价值在于其灵活性和可扩展性。它不仅支持单代理执行，还支持多代理架构，其中多个专业化的代理可以并行或顺序执行任务，通过**交接（Handoff）机制**实现复杂的业务流程自动化。开发者可以轻松创建自定义代理、定义工具、设置审批流程，并将其部署到各种沙箱执行环境中。\n\n资料来源：[README.md]()\n\n## 核心架构\n\n### 系统组件\n\nOpenAI Agents Python SDK 的架构由以下几个核心组件构成：\n\n| 组件名称 | 功能描述 | 关键文件位置 |\n|---------|---------|------------|\n| **Runner** | 主运行引擎，负责协调代理执行流程 | `src/agents/run_internal/` |\n| **Agent** | 智能代理基类，封装LLM调用和工具管理 | `src/agents/agent.py` |\n| **Sandbox** | 隔离执行环境，提供安全的代码运行环境 | `src/agents/sandbox/` |\n| **Handoffs** | 代理间交接机制，支持任务传递 | `src/agents/handoffs/` |\n| **MCP Server** | Model Context Protocol 服务器集成 | `src/agents/mcp/server.py` |\n| **Tools** | 可扩展的工具系统，支持自定义工具 | `src/agents/tools/` |\n\n资料来源：[src/agents/run_internal/turn_resolution.py](), [src/agents/handoffs/history.py]()\n\n### 架构层次图\n\n```mermaid\ngraph TD\n A[用户应用层] --> B[Runner 执行引擎]\n B --> C[Agent 代理层]\n C --> D[工具系统 Tools]\n C --> E[交接系统 Handoffs]\n C --> F[MCP 协议层]\n D --> G[沙箱执行层 Sandbox]\n E --> C2[其他 Agent]\n G --> H[云端后端 E2B/Modal/Cloudflare...]\n F --> I[外部 MCP 服务]\n```\n\n## 关键特性\n\n### 1. 智能代理系统\n\n代理（Agent）是框架的核心执行单元。每个代理包含：\n\n- **系统提示词**：定义代理的角色和行为\n- **工具集**：代理可调用的功能函数\n- **交接配置**：与其他代理的协作关系\n- **输出格式**：响应数据的结构定义\n\n代理通过 `Runner` 统一调度，支持流式输出、增量响应和完整的结果返回。\n\n### 2. 沙箱执行环境\n\n框架提供了强大的沙箱（Sandbox）功能，用于隔离执行代码和敏感操作：\n\n```mermaid\ngraph LR\n A[Manifest 定义] --> B[沙箱会话创建]\n B --> C[工作空间初始化]\n C --> D[工具执行]\n D --> E[结果收集]\n E --> F[会话结束/快照保存]\n```\n\n支持的沙箱后端包括：\n\n| 后端名称 | 特点 | 典型用例 |\n|---------|------|---------|\n| **E2B** | 通用 bash 环境 | 通用代码执行 |\n| **Modal** | Serverless 计算 | 长时间运行任务 |\n| **Cloudflare** | 边缘计算 | 低延迟应用 |\n| **Daytona** | 容器化执行 | 隔离测试环境 |\n| **Vercel** | 云函数集成 | 快速部署 |\n| **Blaxel** | 云存储挂载 | 数据密集型任务 |\n\n资料来源：[examples/sandbox/README.md](), [examples/sandbox/extensions/README.md]()\n\n### 3. 多代理协作与交接\n\n交接（Handoff）机制允许代理之间传递控制权和上下文信息：\n\n- **顺序交接**：一个代理完成后将任务交给下一个代理\n- **并行执行**：多个代理同时处理不同子任务\n- **上下文继承**：交接时自动传递对话历史和状态\n\n```python\n# 典型的交接流程\nagent_a -> (handoff) -> agent_b -> (handoff) -> agent_c\n```\n\n资料来源：[src/agents/handoffs/history.py]()\n\n### 4. MCP 协议支持\n\n框架完整支持 Model Context Protocol (MCP)，允许代理与外部 MCP 服务器通信：\n\n- 资源管理（Resources）\n- 工具调用（Tools）\n- 提示模板（Prompts）\n- 资源模板（Resource Templates）\n\n资料来源：[src/agents/mcp/server.py]()\n\n### 5. 人机协作与审批\n\n框架内置了完善的人工介入（Human-in-the-Loop）机制：\n\n- **审批门控**：代理在执行敏感操作前等待人工批准\n- **中断恢复**：人工审批后可从中断点恢复执行\n- **自动模式**：支持无干预的自动化运行\n\n资料来源：[examples/mcp/tool_filter_example/README.md]()\n\n## 应用场景\n\n### 研究助手\n\n框架可用于构建复杂的研究代理系统：\n\n```mermaid\ngraph TD\n A[用户输入研究主题] --> B[规划代理 Planner]\n B --> C{搜索查询列表}\n C --> D[搜索代理 1]\n C --> E[搜索代理 2]\n C --> F[搜索代理 N]\n D --> G[汇总代理 Writer]\n E --> G\n F --> G\n G --> H[最终研究报告]\n```\n\n资料来源：[examples/research_bot/README.md]()\n\n### 金融研究代理\n\n专业化的金融分析工作流，包括：\n\n- 财务数据分析\n- 风险评估分析\n- 基础面分析\n- 投资报告生成\n\n资料来源：[examples/financial_research_agent/README.md]()\n\n### 医疗支持系统\n\n复杂的医疗信息查询和验证系统，支持：\n\n- 保险福利查询\n- 先前授权检查\n- 医疗政策分析\n- 记忆回顾机制\n\n资料来源：[examples/sandbox/healthcare_support/README.md]()\n\n## 快速开始\n\n### 环境要求\n\n- Python 3.10+\n- OpenAI API Key\n\n### 安装方式\n\n```bash\n# 基础安装\nuv sync\n\n# 包含可选依赖的完整安装\nuv sync --extra blaxel --extra modal --extra vercel\n```\n\n### 基本使用示例\n\n```python\nfrom agents import Agent, Runner\n\nagent = Agent(name=\"助手\", instructions=\"你是一个有帮助的助手\")\n\nresult = Runner.run_sync(agent, \"你好，请介绍一下你自己\")\nprint(result.final_output)\n```\n\n资料来源：[pyproject.toml]()\n\n## 项目结构\n\n```\nopenai-agents-python/\n├── src/agents/ # 核心源代码\n│ ├── agent.py # 代理基类\n│ ├── runner.py # 执行引擎\n│ ├── handoffs/ # 交接系统\n│ ├── sandbox/ # 沙箱实现\n│ ├── mcp/ # MCP 协议支持\n│ └── tools/ # 工具系统\n├── examples/ # 示例应用\n│ ├── sandbox/ # 沙箱示例\n│ ├── research_bot/ # 研究代理示例\n│ └── mcp/ # MCP 使用示例\n└── README.md # 项目文档\n```\n\n## 版本信息\n\n当前版本定义在 `src/agents/version.py` 中，采用语义化版本管理。\n\n资料来源：[src/agents/version.py]()\n\n## 总结\n\nOpenAI Agents Python SDK 代表了现代 AI 应用开发的新范式。它通过提供：\n\n- **统一的代理抽象**：简化复杂 AI 工作流的构建\n- **灵活的沙箱执行**：确保代码安全隔离运行\n- **强大的协作机制**：支持多代理并行和顺序执行\n- **完善的协议支持**：无缝集成 MCP 等开放标准\n\n使开发者能够快速构建生产级别的人工智能应用，无论是简单的问答系统还是复杂的企业级工作流自动化。\n\n资料来源：[README.md](), [examples/sandbox/README.md]()\n\n---\n\n\n\n## 快速开始指南\n\n### 相关页面\n\n相关主题：[项目概述](#overview), [Agent 核心框架](#agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/sandbox/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/README.md)\n- [examples/research_bot/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/research_bot/README.md)\n- [examples/mcp/streamable_http_remote_example/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/mcp/streamable_http_remote_example/README.md)\n- [examples/mcp/tool_filter_example/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/mcp/tool_filter_example/README.md)\n- [examples/model_providers/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/model_providers/README.md)\n- [examples/sandbox/healthcare_support/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/healthcare_support/README.md)\n \n\n# 快速开始指南\n\n## 概述\n\n快速开始指南旨在帮助开发者快速上手 OpenAI Agents Python SDK，掌握核心概念和基础用法。通过本指南，您将了解如何安装 SDK、创建代理（Agent）、配置工具、执行运行流程，以及运行各种示例代码。\n\n本指南覆盖以下主要内容：\n\n- 环境准备与安装\n- 核心概念与架构\n- 基本使用流程\n- 示例代码运行指南\n\n资料来源：[examples/sandbox/README.md:1-15]()\n\n## 环境准备\n\n### 系统要求\n\n| 要求项 | 说明 |\n|--------|------|\n| Python 版本 | 3.12 及以上 |\n| 包管理器 | uv 或 pip |\n| 网络要求 | 能够访问 OpenAI API |\n\n### 安装步骤\n\n使用 `uv` 安装 SDK 及其依赖：\n\n```bash\nuv pip install openai-agents\n```\n\n安装特定扩展功能（如需要）：\n\n```bash\nuv sync --extra e2b # E2B 沙箱支持\nuv sync --extra modal # Modal 后端支持\nuv sync --extra blaxel # Blaxel 沙箱支持\nuv sync --extra vercel # Vercel 后端支持\nuv sync --extra daytona # Daytona 后端支持\nuv sync --extra runloop # Runloop 后端支持\n```\n\n### 环境变量配置\n\n设置 OpenAI API 密钥：\n\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\n```\n\n对于其他后端服务，需要额外配置相应的 API 密钥：\n\n| 后端服务 | 环境变量 |\n|----------|----------|\n| Blaxel | `BL_API_KEY`, `BL_WORKSPACE` |\n| Vercel | `VERCEL_OIDC_TOKEN` 或 `VERCEL_TOKEN`, `VERCEL_PROJECT_ID`, `VERCEL_TEAM_ID` |\n| Daytona | `DAYTONA_API_KEY` |\n| E2B | `E2B_API_KEY` |\n| Modal | `MODAL_TOKEN_ID`, `MODAL_TOKEN_SECRET` |\n| Runloop | 需在 platform.runloop.ai 注册 |\n\n资料来源：[examples/sandbox/extensions/README.md:1-50]()\n资料来源：[examples/sandbox/extensions/blaxel/README.md:1-20]()\n\n## 核心概念\n\n### 代理（Agent）\n\n代理是能够执行特定任务的 AI 实体。每个代理具有：\n\n- **名称与指令**：定义代理的角色和行为\n- **工具能力**：代理可调用的功能\n- **模型配置**：使用的语言模型\n\n### Runner 执行器\n\n`Runner` 是 SDK 的核心执行组件，负责：\n\n1. 管理代理的生命周期\n2. 处理工具调用循环\n3. 维护对话状态\n4. 返回最终结果\n\n### 工具（Tools）\n\n工具允许代理与外部系统交互，包括：\n\n- **内置工具**：文件搜索、代码执行等\n- **MCP 工具**：通过 Model Context Protocol 扩展\n- **自定义工具**：用户定义的函数\n\n资料来源：[examples/research_bot/README.md:1-30]()\n\n## 基础使用流程\n\n### 流程图\n\n```mermaid\ngraph TD\n A[初始化 Runner] --> B[创建 Agent]\n B --> C[配置 Tools]\n C --> D[设置 RunConfig]\n D --> E[执行 run 方法]\n E --> F{是否需要工具调用}\n F -->|是| G[执行工具]\n G --> E\n F -->|否| H[返回结果]\n H --> I[输出最终响应]\n```\n\n### 基础代码示例\n\n#### 步骤一：导入依赖\n\n```python\nfrom agents import Agent, Runner\nfrom agents.mcp import MCPServer\n```\n\n#### 步骤二：创建代理\n\n```python\nagent = Agent(\n name=\"研究助手\",\n instructions=\"你是一个专业的金融分析师，帮助用户研究市场趋势。\",\n model=\"gpt-4o\"\n)\n```\n\n#### 步骤三：执行运行\n\n```python\nresult = await Runner.run(\n agent,\n input=\"分析当前科技行业的发展趋势\"\n)\nprint(result.final_output)\n```\n\n资料来源：[examples/research_bot/README.md:15-25]()\n\n## 示例代码指南\n\n### 沙箱示例\n\nSDK 提供了多种沙箱执行环境的示例，位于 `examples/sandbox/` 目录下。\n\n#### 小型 API 示例\n\n| 示例文件 | 功能说明 | 运行命令 |\n|----------|----------|----------|\n| `basic.py` | 创建沙箱会话，运行 SandboxAgent，流式输出结果 | `uv run python examples/sandbox/basic.py` |\n| `handoffs.py` | 代理之间的交接功能 | `uv run python examples/sandbox/handoffs.py` |\n| `sandbox_agent_capabilities.py` | 配置沙箱代理的工作区能力 | `uv run python examples/sandbox/sandbox_agent_capabilities.py` |\n| `sandbox_agent_with_tools.py` | 组合沙箱能力与主机定义工具 | `uv run python examples/sandbox/sandbox_agent_with_tools.py` |\n| `sandbox_agents_as_tools.py` | 将沙箱代理作为工具暴露给其他代理 | `uv run python examples/sandbox/sandbox_agents_as_tools.py` |\n\n#### 扩展后端示例\n\n扩展示例支持多种后端执行环境：\n\n- **E2B**：提供 bash 风格接口（默认）或 Jupyter 风格接口（`e2b_code_interpreter`）\n- **Modal**：支持多种工作区持久化方式（tar、snapshot_filesystem、snapshot_directory）\n- **Blaxel**：支持 PTY 驱动的交互式 Python 会话和 Drive 挂载\n- **Vercel**：非 PTY 路径，支持命令执行和工作区物化\n- **Daytona**：轻量级沙箱执行\n- **Runloop**：云端沙箱服务\n\n资料来源：[examples/sandbox/README.md:20-45]()\n资料来源：[examples/sandbox/extensions/README.md:1-80]()\n\n### 多代理研究机器人\n\n研究机器人示例展示了多代理协作的工作流程：\n\n```mermaid\ngraph LR\n A[用户输入研究主题] --> B[Planner Agent 制定搜索计划]\n B --> C[多个 Search Agent 并行搜索]\n C --> D[Writer Agent 综合撰写报告]\n D --> E[输出研究报告]\n```\n\n运行命令：\n\n```bash\npython -m examples.research_bot.main\n```\n\n资料来源：[examples/research_bot/README.md:1-35]()\n\n### MCP 示例\n\n#### MCP 工具过滤示例\n\n展示如何：\n\n- 本地运行文件系统 MCP 服务器（通过 `npx`）\n- 应用静态工具过滤，暴露特定工具\n- 启用强制批准模式测试人机交互路径\n\n运行命令：\n\n```bash\nuv run python examples/mcp/tool_filter_example/main.py\n```\n\n前置条件：\n\n- `npx` 可用\n- `OPENAI_API_KEY` 已配置\n\n#### 流式 HTTP 远程示例\n\n连接 DeepWiki 的 MCP 服务，使用流式 HTTP 传输协议：\n\n```bash\nuv run python examples/mcp/streamable_http_remote_example/main.py\n```\n\n资料来源：[examples/mcp/tool_filter_example/README.md:1-25]()\n资料来源：[examples/mcp/streamable_http_remote_example/README.md:1-20]()\n\n### 模型提供者示例\n\n支持通过适配器层路由模型请求，默认使用 OpenRouter：\n\n```bash\nexport OPENROUTER_API_KEY=\"...\"\nuv run examples/model_providers/any_llm_provider.py\nuv run examples/model_providers/any_llm_auto.py\nuv run examples/model_providers/litellm_provider.py\nuv run examples/model_providers/litellm_auto.py\n```\n\n自定义模型：\n\n```bash\nuv run examples/model_providers/any_llm_provider.py --model openrouter/openai/gpt-5.4-mini\n```\n\n资料来源：[examples/model_providers/README.md:1-25]()\n\n## 医疗支持示例\n\n医疗支持演示工作流展示了复杂的人机协作场景：\n\n### 核心文件结构\n\n| 文件 | 职责 |\n|------|------|\n| `main.py` | CLI 演示入口 |\n| `workflow.py` | 共享工作流执行逻辑、沙箱设置、追踪、批准恢复循环 |\n| `support_agents.py` | 定义协调器、福利子代理、沙箱策略代理、记忆摘要代理 |\n| `tools.py` | 本地查询工具和批准门控人工交接工具 |\n| `skills/prior-auth-packet-builder/SKILL.md` | 运行时加载的沙箱技能 |\n\n### 运行方式\n\n```bash\nuv run python examples/sandbox/healthcare_support/main.py --list-scenarios\nuv run python examples/sandbox/healthcare_support/main.py --scenario blue_cross_pt_benefits\nuv run python examples/sandbox/healthcare_support/main.py --scenario messy_ambiguous_knee_case\nuv run python examples/sandbox/healthcare_support/main.py --reset-memory\n```\n\n非交互模式运行：\n\n```bash\nEXAMPLES_INTERACTIVE_MODE=auto uv run python examples/sandbox/healthcare_support/main.py --scenario messy_ambiguous_knee_case\n```\n\n资料来源：[examples/sandbox/healthcare_support/README.md:1-40]()\n\n## 常用配置选项\n\n### RunConfig 配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | str | \"gpt-4o\" | 使用的语言模型 |\n| `temperature` | float | 0.7 | 生成温度参数 |\n| `max_tokens` | int | None | 最大输出令牌数 |\n| `tools` | list | [] | 代理可用工具列表 |\n| `tool_override` | list | None | 覆盖默认工具 |\n| `tracing_disabled` | bool | False | 是否禁用追踪 |\n| `stream_intermediate_steps` | bool | True | 是否流式输出中间步骤 |\n\n### 沙箱配置选项\n\n不同后端支持特定的配置参数：\n\n- **E2B**：`--template`, `--timeout`\n- **Modal**：`--workspace-persistence`, `--sandbox-create-timeout-s`\n- **Blaxel**：`--image`, `--region`, `--memory`, `--ttl`, `--pause-on-exit`\n- **Vercel**：`--runtime`, `--timeout-ms`\n\n资料来源：[examples/sandbox/extensions/README.md:80-120]()\n\n## 最佳实践\n\n### 环境隔离\n\n- 生产环境建议使用沙箱执行代码，避免安全风险\n- 使用快照（Snapshot）功能实现工作区持久化\n- 为不同任务配置独立的沙箱环境\n\n### 错误处理\n\nSDK 在检测到异常情况时会抛出特定错误类：\n\n| 错误类型 | 触发条件 |\n|----------|----------|\n| `InvalidManifestPathError` | 清单路径无效（exit_code=111） |\n| `WorkspaceArchiveWriteError` | 工作区归档写入失败（exit_code=114） |\n| `ExecNonZeroError` | 命令执行返回非零退出码 |\n\n### 调试技巧\n\n1. 启用流式中间步骤输出，监控代理行为\n2. 使用 `tracing_disabled=False` 保留追踪记录\n3. 结合 Temporal 等工具进行分布式追踪\n\n资料来源：[src/agents/sandbox/session/base_sandbox_session.py:40-80]()\n\n## 下一步\n\n完成快速开始指南后，建议继续探索：\n\n- **高级代理配置**：学习如何构建复杂的多代理系统\n- **工具开发**：创建自定义工具扩展代理能力\n- **MCP 集成**：连接更多外部服务\n- **沙箱高级功能**：深入了解各种沙箱后端的特性和配置\n- **生产部署**：了解在生产环境中运行代理的最佳实践\n\n---\n\n\n\n## 核心概念\n\n### 相关页面\n\n相关主题：[Agent 核心框架](#agent-core), [工具系统](#tools), [Agent 转交机制](#handoffs)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/agent.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py)\n- [src/agents/tool.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool.py)\n- [src/agents/guardrail.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/guardrail.py)\n- [src/agents/handoffs/__init__.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/handoffs/__init__.py)\n- [src/agents/items.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/items.py)\n- [src/agents/result.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/result.py)\n \n\n# 核心概念\n\n本文档介绍 openai-agents-python 项目中的核心概念与架构组件。该项目是一个用于构建 AI Agent 系统的 Python 框架，提供了 Agent、Tool、Handoff、Guardrail 等核心抽象，使开发者能够构建复杂的多代理协作应用。\n\n## 1. Agent（代理）\n\nAgent 是整个系统的核心执行单元，代表一个能够接收输入、执行任务并返回结果的 AI 实体。\n\n### 1.1 Agent 的定义与组成\n\n一个 Agent 主要由以下几个部分构成：\n\n| 组件 | 说明 | 资料来源 |\n|------|------|---------|\n| name | Agent 的唯一标识名称 | src/agents/agent.py |\n| instructions | 给 Agent 的系统指令/提示词 | src/agents/agent.py |\n| tools | Agent 可调用的工具列表 | src/agents/agent.py |\n| handoffs | Agent 可转交到的其他 Agent | src/agents/agent.py |\n| input_guardrails | 输入护栏 | src/agents/guardrail.py |\n| output_guardrails | 输出护栏 | src/agents/guardrail.py |\n\n### 1.2 Agent 架构图\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Agent]\n B --> C{指令解析}\n C -->|执行工具| D[Tools]\n C -->|转交代理| E[Handoffs]\n C -->|安全检查| F[Guardrails]\n D --> G[工具执行结果]\n E --> H[目标Agent]\n F --> I{检查通过?}\n I -->|是| G\n I -->|否| J[拒绝/过滤]\n G --> K[响应输出]\n H --> B\n J --> K\n```\n\n### 1.3 Agent 的核心职责\n\nAgent 在系统中承担以下核心职责：\n\n1. **指令解析**：解析用户输入并理解任务意图\n2. **工具调用**：根据任务需要调用适当的工具\n3. **代理转交**：在多代理场景下，将任务转交给其他专业 Agent\n4. **结果生成**：综合工具执行结果生成最终响应\n\n```python\n# Agent 的基本定义结构示例\nagent = Agent(\n name=\"assistant\",\n instructions=\"你是一个有用的助手\",\n tools=[search_tool, calculator_tool],\n handoffs=[specialist_agent],\n output_guardrails=[content_filter]\n)\n```\n\n## 2. Tool（工具）\n\nTool 是 Agent 与外部世界交互的桥梁，允许 Agent 执行特定的操作如搜索、计算、文件处理等。\n\n### 2.1 Tool 的类型\n\n| 工具类型 | 用途 | 典型应用场景 |\n|----------|------|-------------|\n| FunctionTool | 封装 Python 函数 | 数据处理、计算 |\n| MCPTool | MCP 协议工具 | 与外部服务集成 |\n| SandboxedTool | 沙箱环境工具 | 安全执行代码 |\n\n### 2.2 Tool 的定义\n\n```python\n# Tool 的基本结构\ntool = Tool(\n name=\"search\",\n description=\"搜索网络信息\",\n parameters={...}, # 工具参数定义\n handler=async def search(query): ...\n)\n```\n\n### 2.3 Tool 执行流程\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Tool\n participant External\n Agent->>Tool: 调用工具\n Tool->>Tool: 参数验证\n Tool->>External: 执行外部操作\n External-->>Tool: 返回结果\n Tool->>Tool: 结果格式化\n Tool-->>Agent: 返回处理结果\n```\n\n## 3. Handoff（代理转交）\n\nHandoff 是一种在多个 Agent 之间传递对话控制权的机制，是构建多代理系统的关键特性。\n\n### 3.1 Handoff 的工作原理\n\nHandoff 允许一个 Agent 将当前对话上下文转交给另一个 Agent，实现专业分工和任务分解。资料来源：[src/agents/handoffs/__init__.py]()\n\n```mermaid\ngraph LR\n A[用户] -->|输入| B[主Agent]\n B -->|转交| C[研究Agent]\n B -->|转交| D[写作Agent]\n C -->|结果| B\n D -->|结果| B\n B -->|最终输出| A\n```\n\n### 3.2 Handoff 的配置选项\n\n| 选项 | 说明 | 必填 |\n|------|------|------|\n| agent | 目标 Agent 对象 | 是 |\n| agent_name | 目标 Agent 名称 | 是 |\n| tool_name | 触发转交的调用名 | 否 |\n| description | 转交描述 | 否 |\n| on_invoke | 转交触发回调 | 否 |\n\n### 3.3 Handoff 与历史记录\n\n系统在转交时会自动处理对话历史，确保新 Agent 能够获取完整的上下文信息：\n\n```python\n# Handoff 会自动传递：\n# - 原始用户输入\n# - 当前对话历史\n# - 之前 Agent 的分析结果\n# - 工具执行结果\n```\n\n## 4. Guardrail（护栏）\n\nGuardrail 是一种安全机制，用于在 Agent 执行过程中对输入和输出进行验证和过滤。\n\n### 4.1 Guardrail 的类型\n\n| 类型 | 作用位置 | 用途 |\n|------|----------|------|\n| input_guardrail | 工具执行前 | 验证用户输入安全性 |\n| output_guardrail | 响应生成后 | 过滤敏感输出内容 |\n| tool_input_guardrail | 工具参数传入前 | 验证工具参数 |\n| tool_output_guardrail | 工具执行完成后 | 检查工具返回结果 |\n\n### 4.2 Guardrail 执行流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Input Guardrail]\n B --> C{验证通过?}\n C -->|是| D[Agent 处理]\n C -->|否| E[拒绝请求]\n D --> F[工具调用]\n F --> G[Tool Output Guardrail]\n G --> H{检查通过?}\n H -->|是| I[Agent 生成响应]\n H -->|否| J[过滤/阻断]\n I --> K[Output Guardrail]\n K --> L{通过?}\n L -->|是| M[返回结果]\n L -->|否| N[内容过滤]\n```\n\n### 4.3 Guardrail 配置示例\n\n```python\n# Guardrail 配置结构\nguardrail = Guardrail(\n name=\"content_filter\",\n description=\"过滤不当内容\",\n validator=async def check_content(ctx, result): ...\n)\n```\n\n## 5. Item（消息项）\n\nItem 是对话系统中表示各种消息和事件的标准化数据结构。\n\n### 5.1 Item 的类型\n\n| 类型 | 说明 | 资料来源 |\n|------|------|---------|\n| MessageOutputItem | 模型生成的消息 | src/agents/items.py |\n| ToolCallItem | 工具调用请求 | src/agents/items.py |\n| ToolCallOutputItem | 工具执行结果 | src/agents/items.py |\n| HandoffItem | 代理转交事件 | src/agents/items.py |\n| GuardrailResultItem | 护栏检查结果 | src/agents/items.py |\n\n### 5.2 Item 层次结构\n\n```mermaid\ngraph TD\n A[Item 基类]\n A --> B[MessageOutputItem]\n A --> C[ToolCallItem]\n A --> D[HandoffItem]\n A --> E[GuardrailResultItem]\n C --> F[ToolCallOutputItem]\n```\n\n## 6. Result（结果）\n\nResult 是 Agent 执行完成后返回给调用者的数据结构，包含完整的执行信息。\n\n### 6.1 Result 结构\n\n| 字段 | 说明 |\n|------|------|\n| final_output | 最终输出文本 |\n| items | 执行过程中的所有 Item 列表 |\n| last_agent | 最后执行的 Agent 信息 |\n| raw_responses | 原始模型响应 |\n| handoff_history | 转交历史记录 |\n\n### 6.2 Result 生成流程\n\n```mermaid\ngraph TD\n A[Agent 执行] --> B[收集 Items]\n B --> C[生成响应]\n C --> D[护栏检查]\n D --> E{检查结果}\n E -->|通过| F[构建 Result]\n E -->|失败| G[返回错误]\n F --> H[返回 Result]\n```\n\n## 7. 核心概念协作关系\n\n### 7.1 完整执行流程\n\n```mermaid\ngraph TD\n subgraph 输入处理\n A[用户输入] --> B[Input Guardrail]\n B --> C[Agent]\n end\n \n subgraph 执行阶段\n C --> D{需要工具?}\n D -->|是| E[Tool Call]\n D -->|否| F{需要转交?}\n E --> G[Tool Output Guardrail]\n G --> H[结果处理]\n F -->|是| I[Handoff]\n F -->|否| J[生成响应]\n end\n \n subgraph 输出处理\n H --> J\n J --> K[Output Guardrail]\n K --> L[Result]\n end\n \n I --> C\n```\n\n### 7.2 组件交互总结\n\n| 交互关系 | 说明 |\n|----------|------|\n| Agent → Tool | Agent 调用工具执行具体操作 |\n| Agent → Handoff | Agent 将任务转交给其他专业 Agent |\n| Tool → Guardrail | 工具执行结果需要通过护栏检查 |\n| Handoff → Item | 转交事件记录为 HandoffItem |\n| Result → Items | 最终结果汇总所有执行过程中的 Item |\n\n## 8. 最佳实践\n\n### 8.1 Agent 设计原则\n\n1. **单一职责**：每个 Agent 应专注于特定领域\n2. **清晰指令**：提供明确、详细的 instructions\n3. **适当工具**：只提供任务所需的最小工具集\n4. **合理护栏**：根据安全性需求配置适当的护栏\n\n### 8.2 Tool 开发规范\n\n1. **清晰描述**：提供准确的 tool description\n2. **参数验证**：实现严格的输入参数验证\n3. **错误处理**：优雅处理执行中的异常\n4. **结果格式化**：返回结构化的执行结果\n\n### 8.3 Handoff 使用建议\n\n1. **明确转交条件**：在 instructions 中说明何时应该转交\n2. **保持上下文**：利用 Handoff 自动传递历史记录的特性\n3. **避免循环**：防止 Agent 之间形成死循环转交\n\n## 9. 相关资源\n\n- [Agent 完整文档](../agents/agent.md)\n- [Tool 使用指南](../tools/tool.md)\n- [Handoff 机制详解](../handoffs/handoff.md)\n- [Guardrail 配置参考](../guardrails/guardrail.md)\n- [示例代码](../examples/)\n\n---\n\n\n\n## Agent 核心框架\n\n### 相关页面\n\n相关主题：[工具系统](#tools), [Agent 转交机制](#handoffs)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/agent.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py)\n- [src/agents/run.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/run.py)\n- [src/agents/run_config.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_config.py)\n- [src/agents/run_context.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_context.py)\n- [src/agents/run_state.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_state.py)\n- [src/agents/lifecycle.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/lifecycle.py)\n- [src/agents/stream_events.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/stream_events.py)\n \n\n# Agent 核心框架\n\n## 概述\n\nAgent 核心框架是 openai-agents-python 项目的核心组成部分，负责管理 AI Agent 的创建、配置、执行和生命周期管理。该框架提供了一套完整的抽象，使开发者能够轻松构建多代理系统，处理任务编排、工具调用、代理间交接（handoff）等复杂场景。\n\n核心框架主要由以下几个模块组成：\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| Agent | `src/agents/agent.py` | 定义代理的行为和配置 |\n| Runner | `src/agents/run.py` | 执行代理任务的主入口 |\n| RunConfig | `src/agents/run_config.py` | 运行时的配置参数 |\n| RunContext | `src/agents/run_context.py` | 执行上下文管理 |\n| RunState | `src/agents/run_state.py` | 运行时状态追踪 |\n| Lifecycle | `src/agents/lifecycle.py` | 生命周期钩子管理 |\n| StreamEvents | `src/agents/stream_events.py` | 事件流式输出 |\n\n资料来源：[src/agents/agent.py:1-50](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py)\n\n## 架构图\n\n以下 Mermaid 图展示了 Agent 核心框架的整体架构：\n\n```mermaid\ngraph TD\n subgraph 核心组件\n A[Agent] --> B[Runner]\n B --> C[RunConfig]\n B --> D[RunContext]\n B --> E[RunState]\n B --> F[Lifecycle]\n B --> G[StreamEvents]\n end\n \n subgraph 执行层\n B --> H[模型调用]\n B --> I[工具执行]\n B --> J[代理交接]\n end\n \n subgraph 上下文\n D --> K[输入历史]\n D --> L[工具结果]\n D --> M[运行时数据]\n end\n```\n\n## Agent 类\n\n### 类的定义与核心属性\n\n`Agent` 类是框架的核心抽象，封装了代理的名称、模型配置、指令、工具集等关键属性。\n\n```python\nclass Agent:\n def __init__(\n self,\n name: str,\n instructions: str | Callable | None = None,\n model: str | Model = \"gpt-4o\",\n tools: list[Tool] | None = None,\n handoffs: list[Handoff | Agent] | None = None,\n input_guardrails: list[InputGuardrail] | None = None,\n output_guardrails: list[OutputGuardrail] | None = None,\n tool_validator: ToolValidator | None = None,\n response_format: type[BaseModel] | None = None,\n )\n```\n\n**核心属性说明：**\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `name` | `str` | 代理的唯一标识名称 |\n| `instructions` | `str \\| Callable \\| None` | 代理的系统指令 |\n| `model` | `str \\| Model` | 使用的模型名称或对象 |\n| `tools` | `list[Tool] \\| None` | 代理可用的工具列表 |\n| `handoffs` | `list[Handoff \\| Agent] \\| None` | 可交接给其他代理的配置 |\n| `input_guardrails` | `list[InputGuardrail] \\| None` | 输入验证器 |\n| `output_guardrails` | `list[OutputGuardrail] \\| None` | 输出验证器 |\n\n资料来源：[src/agents/agent.py:50-100](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py)\n\n### 代理指令处理\n\n代理的 `instructions` 属性支持多种形式：\n\n1. **静态字符串**：直接提供系统提示\n2. **可调用函数**：动态生成指令，支持根据上下文信息生成个性化指令\n3. **None**：使用默认指令\n\n```python\n# 静态字符串示例\nagent = Agent(name=\"分析师\", instructions=\"你是一个专业的数据分析师\")\n\n# 动态指令示例\ndef dynamic_instructions(ctx: RunContextWrapper, agent: Agent) -> str:\n user_preference = ctx.get(\"user_preference\", \"默认\")\n return f\"用户偏好：{user_preference}\"\n\nagent = Agent(name=\"个性化助手\", instructions=dynamic_instructions)\n```\n\n资料来源：[src/agents/agent.py:100-150](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py)\n\n## Runner 执行器\n\n### Runner 概述\n\n`Runner` 是执行代理任务的主入口类，负责协调整个执行流程。\n\n```python\nclass Runner:\n @staticmethod\n async def run(\n agent: Agent,\n input: str | list[Message] | list[ToolResult],\n *,\n context: dict[str, Any] | None = None,\n max_steps: int = 150,\n config: RunConfig | None = None,\n ) -> FinalOutput\n```\n\n### 异步执行流程\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant Runner\n participant Agent\n participant 工具\n participant 模型\n \n 用户->>Runner: run(agent, input)\n Runner->>RunContext: 创建上下文\n Runner->>Agent: 执行指令\n Agent->>模型: 生成响应\n 循环 while 需要工具调用\n 模型->>工具: 调用工具\n 工具-->>模型: 返回结果\n end\n 模型-->>Runner: 最终输出\n Runner-->>用户: FinalOutput\n```\n\n### 核心执行方法\n\nRunner 提供了多个静态方法用于不同场景：\n\n| 方法 | 说明 | 使用场景 |\n|------|------|----------|\n| `run()` | 标准异步执行 | 大多数场景 |\n| `run_single_agent()` | 单代理快速执行 | 简单任务 |\n| `run_concurrently()` | 并发执行多个代理 | 批量处理 |\n| `run_stream_events()` | 流式事件输出 | 实时展示 |\n\n资料来源：[src/agents/run.py:50-200](https://github.com/openai/openai-agents-python/blob/main/src/agents/run.py)\n\n## RunConfig 配置\n\n### 配置参数详解\n\n`RunConfig` 类封装了运行时的所有配置选项：\n\n```python\nclass RunConfig(BaseModel):\n model: str = \"gpt-4o\"\n model_provider: str = \"openai\"\n max_tokens: int | None = 16384\n temperature: float = 1.0\n top_p: float | None = None\n stop: str | list[str] | None = None\n stream: bool = False\n stream_intermediate_steps: bool = False\n parallel_tool_calls: bool = True\n max_parallel_tool_calls: int | None = None\n tracing: TracingExportType | TracingDisabledReason | None = None\n```\n\n**配置参数说明：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | `str` | `\"gpt-4o\"` | 模型名称 |\n| `model_provider` | `str` | `\"openai\"` | 模型提供商 |\n| `max_tokens` | `int \\| None` | `16384` | 最大输出 token 数 |\n| `temperature` | `float` | `1.0` | 采样温度 |\n| `top_p` | `float \\| None` | `None` | Nucleus 采样参数 |\n| `stop` | `str \\| list[str]` | `None` | 停止序列 |\n| `stream` | `bool` | `False` | 是否启用流式输出 |\n| `parallel_tool_calls` | `bool` | `True` | 是否并行执行工具调用 |\n| `max_parallel_tool_calls` | `int \\| None` | `None` | 最大并行工具调用数 |\n| `tracing` | `TracingExportType \\| None` | `None` | 追踪导出配置 |\n\n资料来源：[src/agents/run_config.py:30-100](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_config.py)\n\n### 模型提供商配置\n\n框架支持多种模型提供商，通过 `model_provider` 参数指定：\n\n```python\n# OpenAI\nconfig = RunConfig(model_provider=\"openai\", model=\"gpt-4o\")\n\n# Anthropic\nconfig = RunConfig(model_provider=\"anthropic\", model=\"claude-3-opus-20240229\")\n\n# Azure OpenAI\nconfig = RunConfig(model_provider=\"azure\", model=\"gpt-4o\")\n\n# 自定义提供商\nconfig = RunConfig(model_provider=\"my-provider\", model=\"custom-model\")\n```\n\n## RunContext 上下文管理\n\n### 上下文的作用\n\n`RunContext` 负责管理代理执行过程中的上下文信息，包括输入历史、工具调用结果、运行时数据等。\n\n```python\nclass RunContextWrapper(Generic[AgentStateT]):\n def __init__(\n self,\n trace_id: str,\n session_id: str,\n agent: Agent,\n messages: list[ChatMessage],\n state: AgentStateT,\n current_agent: Agent,\n agent_history: dict[str, list[ChatMessage]],\n pending_handoffs: list[Handoff],\n tools: list[Tool],\n turn_context: TurnContext | None,\n )\n```\n\n### 上下文数据访问\n\n| 方法 | 说明 |\n|------|------|\n| `get(key)` | 获取上下文中的值 |\n| `set(key, value)` | 设置上下文中的值 |\n| `get_messages()` | 获取消息历史 |\n| `get_state()` | 获取代理状态 |\n| `update_state(**kwargs)` | 更新代理状态 |\n\n资料来源：[src/agents/run_context.py:30-80](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_context.py)\n\n### 上下文数据流\n\n```mermaid\ngraph LR\n A[用户输入] --> B[RunContext]\n B --> C[消息历史]\n B --> D[状态存储]\n B --> E[代理历史]\n C --> F[模型调用]\n F --> G[工具执行]\n G --> B\n F --> H[最终输出]\n```\n\n## RunState 状态管理\n\n### 状态追踪\n\n`RunState` 负责追踪代理执行过程中的所有状态信息：\n\n```python\nclass RunState(BaseModel):\n run_id: str\n turn_count: int = 0\n step_count: int = 0\n messages: list[ChatMessage] = Field(default_factory=list)\n tool_results: list[ToolResult] = Field(default_factory=list)\n agent_history: dict[str, list[ChatMessage]] = Field(default_factory=dict)\n pending_handoffs: list[Handoff] = Field(default_factory=list)\n output_guardrail_results: list[GuardrailResult] = Field(default_factory=list)\n input_guardrail_results: list[GuardrailResult] = Field(default_factory=list)\n```\n\n### 状态字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `run_id` | `str` | 唯一运行标识符 |\n| `turn_count` | `int` | 代理轮次计数 |\n| `step_count` | `int` | 执行步骤计数 |\n| `messages` | `list[ChatMessage]` | 完整消息历史 |\n| `tool_results` | `list[ToolResult]` | 工具执行结果 |\n| `agent_history` | `dict[str, list[ChatMessage]]` | 各代理的消息历史 |\n| `pending_handoffs` | `list[Handoff]` | 待处理的交接请求 |\n| `output_guardrail_results` | `list[GuardrailResult]` | 输出验证结果 |\n| `input_guardrail_results` | `list[GuardrailResult]` | 输入验证结果 |\n\n资料来源：[src/agents/run_state.py:20-60](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_state.py)\n\n## Lifecycle 生命周期钩子\n\n### 钩子类型\n\n框架提供了完整的生命周期钩子系统，允许开发者在代理执行的各个阶段注入自定义逻辑：\n\n```python\nclass Hooks(Generic[AgentStateT]):\n async def on_agent_start(\n self,\n context_wrapper: RunContextWrapper[AgentStateT],\n agent: Agent,\n ) -> None\n \n async def on_agent_end(\n self,\n context_wrapper: RunContextWrapper[AgentStateT],\n agent: Agent,\n output: str,\n ) -> None\n \n async def on_tool_start(\n self,\n context_wrapper: RunContextWrapper[AgentStateT],\n tool: Tool,\n parameters: dict[str, Any],\n ) -> None\n \n async def on_tool_end(\n self,\n context_wrapper: RunContextWrapper[AgentStateT],\n tool: Tool,\n result: Any,\n ) -> None\n```\n\n### 钩子执行流程\n\n```mermaid\ngraph TD\n A[开始运行] --> B{on_agent_start}\n B --> C[执行代理]\n C --> D{工具调用?}\n D -->|是| E[on_tool_start]\n E --> F[执行工具]\n F --> G[on_tool_end]\n G --> D\n D -->|否| H{交接?}\n H -->|是| I[处理交接]\n I --> J{结束?}\n H -->|否| J\n C --> J\n J -->|否| C\n J -->|是| K[on_agent_end]\n K --> L[输出结果]\n```\n\n### 可用钩子列表\n\n| 钩子名称 | 触发时机 | 用途示例 |\n|----------|----------|----------|\n| `on_agent_start` | 代理开始执行前 | 记录开始时间、初始化资源 |\n| `on_agent_end` | 代理执行完成后 | 记录结束时间、清理资源 |\n| `on_tool_start` | 工具开始执行前 | 记录工具调用、参数验证 |\n| `on_tool_end` | 工具执行完成后 | 记录工具结果、错误处理 |\n| `on_handoff` | 代理交接时 | 传递上下文、更新状态 |\n| `on_exception` | 异常发生时 | 错误日志、告警通知 |\n\n资料来源：[src/agents/lifecycle.py:30-150](https://github.com/openai/openai-agents-python/blob/main/src/agents/lifecycle.py)\n\n## StreamEvents 事件流\n\n### 事件类型\n\n`StreamEvents` 定义了所有可流式输出的事件类型：\n\n```python\nclass StreamEvents:\n AGENT_DETAIL_STREAMING = \"agent_detail_streaming\"\n RUN_ITEM_STOPPED = \"run_item_stopped\"\n RUN_ITEM_DELTA = \"run_item_delta\"\n RUN_ITEM_ADDED = \"run_item_added\"\n TEXT_DONE = \"text_done\"\n TEXT_DELTA = \"text_delta\"\n IMAGE_DETAIL_DONE = \"image_detail_done\"\n ABORTED_ERROR = \"aborted_error\"\n CONNECTION_ERROR = \"connection_error\"\n ERROR = \"error\"\n TOOL_CALL = \"tool_call\"\n TOOL_CALL_DETAILS = \"tool_call_details\"\n HANDOVER = \"handover\"\n PAUSED = \"paused\"\n RESUMED = \"resumed\"\n```\n\n### 事件数据结构\n\n| 事件类型 | 数据结构 | 说明 |\n|----------|----------|------|\n| `RUN_ITEM_DELTA` | `RunItemDeltaEvent` | 运行项的增量更新 |\n| `RUN_ITEM_ADDED` | `RunItemAddedEvent` | 新增运行项 |\n| `TEXT_DELTA` | `TextDeltaEvent` | 文本增量 |\n| `TOOL_CALL` | `ToolCallEvent` | 工具调用事件 |\n| `HANDOVER` | `HandoverEvent` | 代理交接事件 |\n\n资料来源：[src/agents/stream_events.py:20-100](https://github.com/openai/openai-agents-python/blob/main/src/agents/stream_events.py)\n\n### 流式使用示例\n\n```python\nasync def run_with_stream():\n config = RunConfig(stream=True, stream_intermediate_steps=True)\n \n events = Runner.run_stream_events(\n agent=my_agent,\n input=\"用户问题\",\n config=config\n )\n \n async for event in events:\n if event.type == StreamEvents.TEXT_DELTA:\n print(event.data.text, end=\"\", flush=True)\n elif event.type == StreamEvents.TOOL_CALL:\n print(f\"\\n调用工具: {event.data.name}\")\n```\n\n## 执行流程详解\n\n### 完整执行流程图\n\n```mermaid\nflowchart TD\n A[初始化 Runner] --> B[创建 RunContext]\n B --> C[验证输入]\n C --> D[执行输入 Guardrails]\n D --> E{验证通过?}\n E -->|否| F[返回错误]\n E -->|是| G[加载代理配置]\n G --> H[开始生命周期钩子]\n H --> I[构建系统提示]\n I --> J[调用模型]\n J --> K{需要工具调用?}\n K -->|是| L[执行工具]\n L --> M[收集工具结果]\n M --> J\n K -->|否| N{需要交接?}\n N -->|是| O[执行交接]\n O --> P[加载新代理]\n P --> I\n N -->|否| Q{执行输出 Guardrails?}\n Q -->|是| R[验证输出]\n R --> S{验证通过?}\n S -->|否| F\n S -->|是| T[触发结束钩子]\n Q -->|否| T\n T --> U[返回 FinalOutput]\n```\n\n### Turn Resolution 机制\n\nTurn resolution 是框架处理多轮对话和状态更新的核心机制，位于 `src/agents/run_internal/turn_resolution.py`：\n\n```python\nasync def _resolve_turn(\n public_agent: Agent,\n original_input: str | list[Message] | list[ToolResult],\n pre_step_items: list[RunItem],\n new_step_items: list[RunItem],\n function_results: list[ToolResult],\n # ... 其他参数\n) -> TurnResult:\n```\n\n该机制负责：\n1. 处理工具调用结果\n2. 管理消息历史\n3. 处理代理交接\n4. 生成最终输出\n\n资料来源：[src/agents/run_internal/turn_resolution.py:50-150](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/turn_resolution.py)\n\n## 代理交接 (Handoffs)\n\n### 交接机制\n\n代理交接允许一个代理将控制权传递给另一个代理，同时传递必要的上下文信息：\n\n```python\nhandoff = Handoff(\n agent=target_agent,\n tool_name=\"transfer_to_target\",\n tool_description=\"切换到目标代理\",\n metadata={\"reason\": \"需要专门知识\"}\n)\n\nsource_agent = Agent(\n name=\"路由器\",\n handoffs=[handoff]\n)\n```\n\n### 交接数据传递\n\n交接时传递的数据结构：\n\n| 字段 | 说明 |\n|------|------|\n| `agent_name` | 目标代理名称 |\n| `handoff_config` | 交接配置 |\n| `input_items` | 传递给目标代理的输入项 |\n| `history_items` | 完整的对话历史 |\n| `metadata` | 附加元数据 |\n\n资料来源：[src/agents/handoffs/history.py:30-80](https://github.com/openai/openai-agents-python/blob/main/src/agents/handoffs/history.py)\n\n## Guardrails 防护机制\n\n### 输入防护\n\n输入防护在模型调用前验证用户输入：\n\n```python\nclass InputGuardrail:\n async def check(\n self,\n context: RunContextWrapper,\n agent: Agent,\n input: str | list[Message],\n ) -> GuardrailResult:\n # 自定义验证逻辑\n pass\n```\n\n### 输出防护\n\n输出防护在模型生成后验证输出：\n\n```python\nclass OutputGuardrail:\n async def check(\n self,\n context: RunContextWrapper,\n agent: Agent,\n output: str | BaseModel,\n ) -> GuardrailResult:\n # 自定义验证逻辑\n pass\n```\n\n### 防护结果\n\n```python\nclass GuardrailResult(BaseModel):\n pass_result: bool\n tripwire_triggered: bool = False\n data: Any = None\n message: str | None = None\n```\n\n| 结果字段 | 说明 |\n|----------|------|\n| `pass_result` | 验证是否通过 |\n| `tripwire_triggered` | 是否触发安全开关 |\n| `data` | 验证返回的数据 |\n| `message` | 验证消息 |\n\n## 最佳实践\n\n### 1. 合理设置 Max Steps\n\n```python\n# 简单任务\nconfig = RunConfig(max_steps=10)\n\n# 复杂多步骤任务\nconfig = RunConfig(max_steps=150)\n```\n\n### 2. 使用生命周期钩子进行监控\n\n```python\nclass MyHooks(Hooks):\n async def on_agent_start(self, context, agent):\n logger.info(f\"开始执行代理: {agent.name}\")\n \n async def on_tool_end(self, context, tool, result):\n logger.info(f\"工具 {tool.name} 执行完成\")\n```\n\n### 3. 流式输出的正确使用\n\n```python\nasync for event in Runner.run_stream_events(agent, input, config=config):\n if event.type == StreamEvents.TEXT_DELTA:\n # 增量处理文本\n accumulated_text += event.data.text\n```\n\n## 总结\n\nAgent 核心框架提供了一套完整、模块化的代理系统架构：\n\n- **Agent** 负责代理的行为定义\n- **Runner** 协调整个执行流程\n- **RunConfig** 管理运行时配置\n- **RunContext** 维护执行上下文\n- **RunState** 追踪运行时状态\n- **Lifecycle** 提供生命周期钩子扩展\n- **StreamEvents** 支持事件流式输出\n\n这些组件协同工作，使开发者能够灵活构建复杂的 AI Agent 应用，同时保持代码的可维护性和可扩展性。\n\n---\n\n\n\n## 工具系统\n\n### 相关页面\n\n相关主题：[MCP 协议集成](#mcp), [Agent 核心框架](#agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/tool.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool.py)\n- [src/agents/function_schema.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/function_schema.py)\n- [src/agents/tool_context.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool_context.py)\n- [src/agents/tool_guardrails.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool_guardrails.py)\n- [examples/basic/tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/basic/tools.py)\n- [examples/tools/shell.py](https://github.com/openai/openai-agents-python/blob/main/examples/tools/shell.py)\n- [examples/tools/code_interpreter.py](https://github.com/openai/openai-agents-python/blob/main/examples/tools/code_interpreter.py)\n \n\n# 工具系统\n\n## 概述\n\n工具系统（Tool System）是 openai-agents-python 框架的核心组件之一，它为 AI Agent 提供了与外部世界交互的能力。通过工具系统，Agent 可以执行代码、搜索网络、操作文件系统、调用外部 API 等。工具在 Agent 执行循环中扮演着关键角色，使语言模型能够执行实际操作而不仅仅是生成文本响应。\n\n工具系统的设计遵循以下核心原则：\n\n- **声明式配置**：工具通过 Pydantic 模型进行类型安全的声明式配置\n- **上下文感知**：工具可以访问运行时上下文信息，包括对话历史和中间结果\n- **安全隔离**：通过沙箱（Sandbox）机制执行危险操作，保护主机系统安全\n- **可扩展架构**：支持自定义工具、MCP 服务器集成以及第三方扩展\n\n资料来源：[src/agents/tool.py]()\n\n## 架构设计\n\n### 整体架构\n\n工具系统的架构采用分层设计，主要包含以下几个层次：\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Agent Layer │\n│ (Agent, SandboxAgent, etc.) │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ Tool Layer │\n│ ┌─────────────┬──────────────┬──────────────────┐ │\n│ │ FunctionTool│ MCPTool │ Custom Tools │ │\n│ └─────────────┴──────────────┴──────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ Execution Layer │\n│ ┌─────────────┬──────────────┬──────────────────┐ │\n│ │ Sandbox │ Local Exec │ Remote Service │ │\n│ └─────────────┴──────────────┴──────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n### 核心组件关系\n\n工具系统由多个核心组件构成，它们之间通过清晰的接口进行交互：\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| `Tool` | 工具基类，定义工具的通用接口和元数据 | `src/agents/tool.py` |\n| `FunctionTool` | 函数工具，将 Python 函数包装为 Agent 可调用的工具 | `src/agents/tool.py` |\n| `ToolContext` | 工具执行上下文，提供运行时信息和状态管理 | `src/agents/tool_context.py` |\n| `FunctionSchema` | 函数模式生成器，从 Python 函数生成 OpenAI 兼容的模式 | `src/agents/function_schema.py` |\n| `ToolGuardrails` | 工具护栏，对工具输入输出进行安全校验 | `src/agents/tool_guardrails.py` |\n| `MCPTool` | MCP 协议工具，集成 Model Context Protocol 服务器 | `src/agents/mcp/server.py` |\n\n资料来源：[src/agents/tool.py:1-50]()\n\n## 工具类型\n\n### FunctionTool\n\n`FunctionTool` 是最常用的工具类型，它将 Python 函数包装为 Agent 可调用的工具。FunctionTool 自动处理参数解析、类型转换和结果序列化。\n\n```python\n# 典型的 FunctionTool 使用方式\nfrom agents import FunctionTool\n\ndef add_numbers(a: int, b: int) -> int:\n \"\"\"将两个数字相加\"\"\"\n return a + b\n\ntool = FunctionTool.from_function(add_numbers)\n```\n\nFunctionTool 支持的功能包括：\n\n- **自动模式生成**：从函数签名和文档字符串生成 OpenAI 函数调用模式\n- **类型验证**：使用 Pydantic 进行参数和返回值的类型验证\n- **描述覆盖**：允许通过参数覆盖自动生成的描述信息\n- **输入过滤器**：支持对输入参数进行预处理\n- **输出格式化**：支持对返回结果进行后处理\n\n资料来源：[src/agents/tool.py:50-150]()\n\n### MCPTool\n\nMCPTool 提供了对 Model Context Protocol（MCP）服务器的支持，使 Agent 能够调用通过 MCP 协议暴露的工具。MCP 是一种标准化的工具发现和调用协议。\n\n```python\nfrom agents import MCPTool\n\n# 从 MCP 服务器创建工具\nmcp_tool = MCPTool.from_server(\n name=\"filesystem\",\n command=\"npx\",\n args=[\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/dir\"]\n)\n```\n\nMCPTool 支持的特性：\n\n- **资源模板**：MCP 服务器可以暴露资源模板供 Agent 使用\n- **资源读取**：支持读取 MCP 服务器暴露的资源内容\n- **工具发现**：自动发现并暴露 MCP 服务器提供的所有工具\n- **需求审批**：支持对特定工具配置需要人工审批的策略\n\n资料来源：[src/agents/mcp/server.py:1-80]()\n\n### SandboxAgent 内置工具\n\nSandboxAgent 提供了一组内置工具，专门用于在隔离环境中执行操作：\n\n| 工具名称 | 功能 | 源码位置 |\n|----------|------|----------|\n| `read_file` | 读取文件内容 | Sandbox 实现 |\n| `write_file` | 写入文件内容 | Sandbox 实现 |\n| `list_directory` | 列出目录内容 | Sandbox 实现 |\n| `run_terminal_command` | 执行终端命令 | Sandbox 实现 |\n\n资料来源：[examples/sandbox/basic.py]()\n\n## 函数模式\n\n### 模式生成机制\n\n`FunctionSchema` 类负责从 Python 函数生成 OpenAI 兼容的函数模式。这个过程包括：\n\n1. **函数签名分析**：使用 `inspect` 模块分析函数参数和类型注解\n2. **文档解析**：提取 docstring 中的描述信息\n3. **默认值处理**：处理可选参数和默认值\n4. **Pydantic 模型转换**：将复杂类型转换为 JSON Schema\n\n```python\n# FunctionSchema 生成的结果示例\n{\n \"type\": \"function\",\n \"function\": {\n \"name\": \"search_web\",\n \"description\": \"搜索网络获取信息\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"query\": {\n \"type\": \"string\",\n \"description\": \"搜索查询词\"\n }\n },\n \"required\": [\"query\"]\n }\n }\n}\n```\n\n资料来源：[src/agents/function_schema.py:1-60]()\n\n### 工具描述优化\n\n系统支持对自动生成的工具描述进行优化和覆盖，确保模型能够准确理解工具的用途：\n\n```python\ntool = FunctionTool.from_function(\n my_function,\n name_override=\"custom_tool_name\",\n description_override=\"自定义工具描述\",\n parameters_override={\"query\": {\"description\": \"优化后的描述\"}}\n)\n```\n\n资料来源：[src/agents/tool.py:150-200]()\n\n## 工具上下文\n\n### 上下文结构\n\n`ToolContext` 为工具执行提供了完整的上下文信息，使工具能够访问运行时状态：\n\n```python\n@dataclass\nclass ToolContext:\n run_context: RunContextWrapper[Any] # 运行上下文\n tool_name: str # 当前工具名称\n tool_call_id: str # 工具调用 ID\n input_json: str # 输入参数 JSON\n current_agent: Agent # 当前 Agent\n round_manager: RoundManager # 轮次管理器\n```\n\n工具上下文提供的能力：\n\n- **对话历史访问**：通过 `run_context.messages` 访问完整的对话历史\n- **中间结果引用**：访问同一轮次中其他工具的执行结果\n- **状态管理**：在多次工具调用之间保持状态\n- **Agent 信息**：获取当前执行 Agent 的详细信息\n\n资料来源：[src/agents/tool_context.py:1-50]()\n\n### 输入过滤机制\n\n工具支持通过 `input_filter` 对输入进行预处理：\n\n```python\ndef filter_input(input_json: str, context: ToolContext) -> str:\n # 自定义输入过滤逻辑\n data = json.loads(input_json)\n data[\"filtered_param\"] = \"modified_value\"\n return json.dumps(data)\n\ntool = FunctionTool.from_function(\n my_function,\n input_filter=filter_input\n)\n```\n\n资料来源：[src/agents/tool.py:200-250]()\n\n## 工具护栏\n\n### 护栏机制\n\n`ToolGuardrails` 提供了对工具调用的安全检查机制，分为输入护栏和输出护栏两类：\n\n```python\n@dataclass\nclass ToolGuardrail:\n name: str\n check: Callable[[RunContextWrapper, Tool, str], Awaitable[GuardrailFunctionOutput]]\n config: dict[str, Any] = field(default_factory=dict)\n```\n\n### 输入护栏\n\n输入护栏在工具执行前对参数进行检查：\n\n```python\nasync def validate_input(\n context: RunContextWrapper,\n tool: Tool,\n input_json: str\n) -> GuardrailFunctionOutput:\n # 检查输入参数是否符合预期\n data = json.loads(input_json)\n if \"sensitive_field\" in data:\n return GuardrailFunctionOutput(\n pass_percentage=0.0, # 阻止执行\n action_info=ActionInfo(\n action_type=ActionType.INPUT_CORRECTION,\n message=\"检测到敏感数据\"\n )\n )\n return GuardrailFunctionOutput(pass_percentage=1.0)\n```\n\n### 输出护栏\n\n输出护栏在工具执行后对结果进行检查：\n\n```python\nasync def validate_output(\n context: RunContextWrapper,\n tool: Tool,\n output: str\n) -> GuardrailFunctionOutput:\n # 检查输出内容\n if contains_sensitive_data(output):\n return GuardrailFunctionOutput(\n pass_percentage=0.0,\n action_info=ActionInfo(\n action_type=ActionType.OUTPUT_FILTER,\n message=\"输出包含敏感信息\"\n )\n )\n return GuardrailFunctionOutput(pass_percentage=1.0)\n```\n\n资料来源：[src/agents/tool_guardrails.py:1-100]()\n\n## 使用示例\n\n### 基础工具创建\n\n```python\n# examples/basic/tools.py\nfrom agents import FunctionTool\n\ndef get_weather(location: str, unit: str = \"celsius\") -> str:\n \"\"\"获取指定位置的天气信息\n \n Args:\n location: 城市名称\n unit: 温度单位 (celsius 或 fahrenheit)\n \"\"\"\n # 实际实现中会调用天气 API\n return f\"{location} 当前温度为 22°C\"\n\nweather_tool = FunctionTool.from_function(\n get_weather,\n name_override=\"get_weather\",\n description_override=\"获取指定城市的天气信息\"\n)\n```\n\n资料来源：[examples/basic/tools.py:1-30]()\n\n### Shell 工具\n\n```python\n# examples/tools/shell.py\nfrom agents import FunctionTool\nimport subprocess\n\ndef execute_shell(command: str, timeout: int = 30) -> str:\n \"\"\"在终端执行 shell 命令\n \n Args:\n command: 要执行的命令\n timeout: 超时时间（秒）\n \"\"\"\n try:\n result = subprocess.run(\n command,\n shell=True,\n capture_output=True,\n text=True,\n timeout=timeout\n )\n return result.stdout if result.returncode == 0 else f\"Error: {result.stderr}\"\n except subprocess.TimeoutExpired:\n return \"命令执行超时\"\n```\n\n资料来源：[examples/tools/shell.py:1-30]()\n\n### 代码解释器工具\n\n```python\n# examples/tools/code_interpreter.py\nfrom agents import FunctionTool\nimport contextlib\nimport io\n\ndef run_python(code: str) -> str:\n \"\"\"执行 Python 代码\n \n Args:\n code: 要执行的 Python 代码\n \"\"\"\n stdout = io.StringIO()\n stderr = io.StringIO()\n \n with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):\n try:\n exec(code, {})\n output = stdout.getvalue()\n return output if output else \"代码执行完成，无输出\"\n except Exception as e:\n return f\"执行错误: {str(e)}\"\n```\n\n资料来源：[examples/tools/code_interpreter.py:1-30]()\n\n## 工具与 Agent 的集成\n\n### Agent 工具配置\n\nAgent 在初始化时通过 `tools` 参数接收工具列表：\n\n```python\nfrom agents import Agent\n\nagent = Agent(\n name=\"research_assistant\",\n instructions=\"你是一个研究助手，可以使用工具来完成任务\",\n tools=[\n web_search_tool,\n file_read_tool,\n code_interpreter_tool\n ]\n)\n```\n\n### 工具可视化\n\n工具系统提供了可视化功能，可以生成 Agent 和工具的关系图：\n\n```python\nfrom agents.extensions.visualization import get_all_nodes, get_all_edges\n\n# 生成 DOT 格式的图描述\nnodes = get_all_nodes(agent)\nedges = get_all_edges(agent)\ndot_graph = f\"digraph {{\\n{nodes}\\n{edges}\\n}}\"\n```\n\n资料来源：[src/agents/extensions/visualization.py:1-80]()\n\n## 执行流程\n\n### 工具调用生命周期\n\n```\n┌──────────────────────────────────────────────────────────┐\n│ 工具调用流程 │\n└──────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 1. 工具选择 │\n│ - 模型根据工具描述选择合适的工具 │\n│ - 生成工具调用参数 │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 2. 输入护栏检查 │\n│ - 验证参数类型和格式 │\n│ - 安全检查（可选） │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 3. 工具执行 │\n│ - 调用实际的工具函数 │\n│ - 处理异常情况 │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 4. 输出护栏检查 │\n│ - 验证返回结果 │\n│ - 内容过滤（可选） │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 5. 结果返回 │\n│ - 将结果传递给模型 │\n│ - 继续执行循环 │\n└─────────────────────────────────────────────────────────┘\n```\n\n## 配置选项\n\n### 工具级别配置\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `name` | `str` | 函数名 | 工具在模型调用时的名称 |\n| `description` | `str` | docstring | 工具的功能描述 |\n| `parameters_override` | `dict` | `None` | 参数模式的覆盖配置 |\n| `input_filter` | `Callable` | `None` | 输入预处理函数 |\n| `output_formatter` | `Callable` | `None` | 输出格式化函数 |\n| `require_approval` | `bool` | `False` | 是否需要人工审批 |\n\n### Agent 工具配置\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `tools` | `list[Tool]` | 分配给 Agent 的工具列表 |\n| `tool_choice` | `str \\| None` | 强制模型使用特定工具 |\n| `parallel_tool_calls` | `bool` | 是否允许并行工具调用 |\n\n## 最佳实践\n\n### 工具命名规范\n\n- 使用清晰、简洁的英文名称\n- 采用 snake_case 命名法\n- 名称应该反映工具的核心功能\n\n### 描述撰写建议\n\n- 第一行应该是简短的总结性描述\n- 详细说明参数含义和预期格式\n- 提供使用示例（如果适用）\n- 明确标注必选和可选参数\n\n### 错误处理\n\n- 返回有意义的错误信息\n- 区分不同类型的错误\n- 避免暴露敏感的系统信息\n\n### 安全考虑\n\n- 对敏感操作配置人工审批\n- 使用输入护栏验证参数\n- 使用输出护栏过滤敏感数据\n- 在沙箱环境中执行危险操作\n\n## 相关资源\n\n- 源码：[src/agents/tool.py]()\n- 函数模式：[src/agents/function_schema.py]()\n- 工具上下文：[src/agents/tool_context.py]()\n- 工具护栏：[src/agents/tool_guardrails.py]()\n- MCP 支持：[src/agents/mcp/server.py]()\n- 示例：[examples/basic/tools.py]()\n\n---\n\n\n\n## MCP 协议集成\n\n### 相关页面\n\n相关主题：[工具系统](#tools), [Agent 核心框架](#agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/mcp/manager.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/mcp/manager.py)\n- [src/agents/mcp/server.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/mcp/server.py)\n- [src/agents/mcp/util.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/mcp/util.py)\n- [src/agents/_mcp_tool_metadata.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/_mcp_tool_metadata.py)\n- [examples/mcp](https://github.com/openai/openai-agents-python/blob/main/examples/mcp)\n \n\n# MCP 协议集成\n\n## 概述\n\nMCP（Model Context Protocol）协议集成是 openai-agents-python 框架的核心功能之一，它允许 AI Agent 与外部 MCP 服务器建立连接，并调用服务器提供的各种工具和资源。通过 MCP 集成，开发者可以扩展 Agent 的能力边界，使其能够访问文件系统、数据库、Web 服务等外部系统。\n\n本框架提供了完整的 MCP 客户端实现，支持本地 MCP 服务器和远程 MCP 服务器两种连接方式，并提供了工具过滤、审批流程等企业级功能。\n\n## 核心组件\n\n### MCPManager\n\n`MCPManager` 是 MCP 集成的核心管理类，负责维护与 MCP 服务器的连接状态和交互逻辑。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `servers` | `dict[str, MCPServer]` | 已注册的 MCP 服务器映射表 |\n| `tools` | `list[MCPTool]` | 从所有服务器获取的工具列表 |\n| `resource_templates` | `list[Any]` | 资源模板列表 |\n\n### MCPServer\n\n`MCPServer` 是 MCP 服务器的抽象基类，定义了与服务器交互的标准接口。\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `list_resources(cursor)` | `ListResourcesResult` | 列出服务器提供的资源 |\n| `list_resource_templates(cursor)` | `ListResourceTemplatesResult` | 列出资源模板 |\n| `read_resource(uri)` | `ReadResourceResult` | 读取指定 URI 的资源内容 |\n| `call_tool(name, arguments)` | 工具调用结果 | 执行服务器上的工具 |\n\n### MCPUtil\n\n`MCPUtil` 工具类提供了便捷的 MCP 工具获取方法：\n\n- `get_all_function_tools()` - 从配置的 MCP 服务器预获取所有可用工具\n- 支持构建使用预获取工具的 Agent，而非在运行时动态发现\n\n## 架构设计\n\n```mermaid\ngraph TD\n A[Agent] --> B[MCPManager]\n B --> C[MCPServer 1]\n B --> D[MCPServer 2]\n B --> E[MCPServer N]\n C --> F[本地 MCP Server
npx/stdio]\n D --> G[远程 MCP Server
Streamable HTTP]\n E --> H[MCP Server
其他传输协议]\n F --> I[本地文件系统工具]\n G --> J[DeepWiki API]\n H --> K[自定义 MCP 服务]\n```\n\n## 工具过滤机制\n\n框架支持静态工具过滤，允许开发者限制 Agent 可访问的 MCP 工具范围。这对于安全控制和界面简化非常重要。\n\n```mermaid\ngraph LR\n A[MCP 服务器
所有工具] --> B[工具过滤器]\n B --> C[过滤后的
可用工具集]\n C --> D[Agent 可见]\n```\n\n工具过滤通过 `MCPToolFilter` 接口实现，开发者可以自定义过滤规则：\n\n```python\n# 伪代码示例\ntool_filter = ToolFilter(allowed_tools=[\"read_file\", \"write_file\"])\nagent = Agent(..., mcp_servers=[server], tool_filter=tool_filter)\n```\n\n## 审批流程集成\n\nMCP 工具调用支持 `require_approval` 配置选项，实现人机协作审批流程。\n\n### 审批设置类型\n\n| 设置值 | 说明 |\n|--------|------|\n| `\"always\"` | 每次工具调用都需要人工审批 |\n| `\"never\"` | 不需要审批，自动执行 |\n| `Callable` | 自定义审批逻辑函数 |\n\n### 审批逻辑处理\n\n```python\n# 来自 server.py 的审批逻辑签名\n@staticmethod\ndef _normalize_needs_approval(\n *,\n require_approval: RequireApprovalSetting,\n) -> (\n bool\n | dict[str, bool]\n | Callable[[RunContextWrapper[Any], AgentBase, MCPTool], MaybeAwaitable[bool]]\n)\n```\n\n开发者可以传入布尔值、字典或可调用对象来自定义审批行为。当设置为 `\"always\"` 时，框架会自动进入 HITL（Human-In-The-Loop）流程，等待人工确认后继续执行。\n\n## 资源管理\n\nMCP 服务器可以暴露两种类型的资源访问接口：\n\n### 资源列表\n\n`list_resources` 方法返回服务器上可用的资源列表，支持分页：\n\n```python\nasync def list_resources(self, cursor: str | None = None) -> ListResourcesResult:\n \"\"\"\n Args:\n cursor: 分页游标，用于获取下一页结果\n \"\"\"\n```\n\n返回结果包含 `nextCursor` 字段用于后续分页请求。\n\n### 资源模板\n\n`list_resource_templates` 方法列出资源模板，模板支持参数化资源访问：\n\n```python\nasync def list_resource_templates(\n self, cursor: str | None = None\n) -> ListResourceTemplatesResult:\n \"\"\"\n 支持的参数化资源模板查询\n \"\"\"\n```\n\n### 资源读取\n\n`read_resource` 方法根据 URI 读取具体资源内容：\n\n```python\nasync def read_resource(self, uri: str) -> ReadResourceResult:\n \"\"\"\n Args:\n uri: 资源的 URI 地址\n \"\"\"\n```\n\n## 连接示例\n\n### 本地 MCP 服务器\n\n通过 `npx` 启动本地文件系统 MCP 服务器：\n\n```bash\nnpx -y @modelcontextprotocol/server-filesystem /path/to/directory\n```\n\n在代码中配置：\n\n```python\nfrom agents import Agent, MCPServer\nfrom agents.mcp import StreamableHTTPServer\n\nserver = StreamableHTTPServer(\n name=\"filesystem\",\n command=\"npx\",\n args=[\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/directory\"]\n)\n\nagent = Agent(mcp_servers=[server])\n```\n\n### 远程 MCP 服务器\n\n通过 Streamable HTTP 协议连接远程 MCP 服务器：\n\n```python\nfrom agents.mcp import StreamableHTTPServer\n\nserver = StreamableHTTPServer(\n name=\"deepwiki\",\n url=\"https://mcp.deepwiki.com/mcp\",\n auth_token=\"your-auth-token\" # 可选\n)\n\nagent = Agent(mcp_servers=[server])\n```\n\n## 错误处理\n\n框架为 MCP 操作定义了专门的异常类型：\n\n| 异常类型 | 触发场景 |\n|----------|----------|\n| `NotImplementedError` | 服务器不支持特定功能（如资源读取） |\n| `ExecNonZeroError` | 命令执行返回非零退出码 |\n| `InvalidManifestPathError` | manifest 路径无效（exit_code=111） |\n| `WorkspaceArchiveWriteError` | 工作空间归档写入失败 |\n\n## 应用场景\n\n### 1. 文件系统访问\n\n使用官方 MCP 文件系统服务器，为 Agent 添加读写本地文件的能力。\n\n### 2. 外部 API 集成\n\n通过 MCP 协议连接第三方服务（如 DeepWiki），扩展 Agent 的知识获取能力。\n\n### 3. 数据库操作\n\n部署自定义 MCP 服务器，实现结构化数据查询和操作。\n\n### 4. 开发工具集成\n\n集成开发相关的 MCP 工具，如代码搜索、版本控制、持续集成等。\n\n## 配置选项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `timeout` | `float` | 60.0 | 工具调用超时时间（秒） |\n| `require_approval` | `str\\|Callable` | `\"never\"` | 工具调用审批设置 |\n| `tool_filter` | `ToolFilter` | `None` | 工具过滤规则 |\n| `env_vars` | `dict` | `{}` | 传递给服务器的环境变量 |\n\n## 相关资源\n\n- 官方 MCP 服务器列表：[Model Context Protocol Servers](https://github.com/modelcontextprotocol/servers)\n- MCP 协议规范：[MCP Protocol Specification](https://modelcontextprotocol.io/specification)\n\n---\n\n\n\n## Agent 转交机制\n\n### 相关页面\n\n相关主题：[Agent 核心框架](#agent-core), [核心概念](#core-concepts)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/handoffs/__init__.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/handoffs/__init__.py)\n- [src/agents/handoffs/history.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/handoffs/history.py)\n- [src/agents/extensions/handoff_filters.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/extensions/handoff_filters.py)\n- [src/agents/extensions/handoff_prompt.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/extensions/handoff_prompt.py)\n- [examples/handoffs/message_filter.py](https://github.com/openai/openai-agents-python/blob/main/examples/handoffs/message_filter.py)\n \n\n# Agent 转交机制\n\n## 概述\n\nAgent 转交（Handoff）机制是 openai-agents-python 框架中实现多代理协作的核心功能。该机制允许一个 Agent 在执行过程中将控制权转移给另一个 Agent，同时支持传递上下文信息、过滤输入内容、以及管理对话历史。\n\n转交机制在以下场景中发挥关键作用：\n\n- 将复杂任务分解为多个专门化的子任务\n- 实现代理之间的专业分工（如数据分析代理、写作代理、审核代理）\n- 支持条件分支和动态路由\n- 管理用户请求与专门代理之间的映射关系\n\n## 核心组件\n\n### Handoff 类\n\n`Handoff` 类是转交机制的核心数据模型，封装了转交的所有配置信息。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `name` | `str` | 转交工具的名称 |\n| `tool_description` | `str` | 转交工具的描述，供 LLM 理解何时触发转交 |\n| `input_json_schema` | `dict[str, Any]` | 转交工具调用参数的 JSON Schema |\n| `on_invoke_handoff` | `Callable[[RunContextWrapper[Any], str], Awaitable[TAgent]]` | 执行转交的回调函数，接收运行上下文和 JSON 参数字符串，返回目标 Agent |\n| `agent_name` | `str` | 目标 Agent 的名称 |\n| `input_filter` | `HandoffInputFilter \\| None` | 过滤传递给下一 Agent 的输入历史 |\n| `on_handoff` | `Callable \\| None` | 转交触发时执行的副作用函数 |\n| `input_type` | `type \\| None` | 转交参数的 Pydantic 类型定义 |\n| `nest_handoff_history` | `bool \\| None` | 是否嵌套转交历史摘要 |\n| `is_enabled` | `bool \\| Callable[[RunContextWrapper[Any], AgentBase, MCPTool], bool]` | 转交是否启用，支持动态判断 |\n\n资料来源：[src/agents/handoffs/__init__.py]()\n\n### HandoffInputFilter 过滤器\n\n`HandoffInputFilter` 是一个函数类型，用于在转交发生时过滤和转换传递给下一 Agent 的输入历史。\n\n```python\nHandoffInputFilter = Callable[\n [list[RunItem], HandoffInputData], tuple[list[RunItem], list[TResponseInputItem]]\n]\n```\n\n该函数接收：\n- 转交前的完整运行项列表\n- `HandoffInputData` 对象\n\n返回经过过滤和修改后的运行项列表以及新的输入项列表。\n\n资料来源：[src/agents/handoffs/history.py]()\n\n### HandoffInputData 数据结构\n\n```python\nclass HandoffInputData:\n input_history: list[RunItem]\n pre_handoff_items: list[RunItem]\n```\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `input_history` | `list[RunItem]` | 整个对话历史 |\n| `pre_handoff_items` | `list[RunItem]` | 转交触发前的运行项集合 |\n\n资料来源：[src/agents/handoffs/history.py]()\n\n## 转交工作流程\n\n```mermaid\ngraph TD\n A[Agent A 执行中] --> B{触发转交条件}\n B -->|检测到转交工具调用| C[调用 on_handoff 回调]\n C --> D{存在 input_filter?}\n D -->|是| E[执行输入过滤]\n D -->|否| F[使用默认历史]\n E --> G[nest_handoff_history 启用?]\n F --> G\n G -->|是| H[生成历史摘要]\n G -->|否| I[直接传递原始历史]\n H --> J[调用 on_invoke_handoff]\n I --> J\n J --> K[Agent B 开始执行]\n```\n\n## 历史管理机制\n\n### 嵌套历史摘要\n\n当 `nest_handoff_history` 设置为 `True` 时，系统会对转交前的对话历史进行压缩摘要处理，以避免上下文窗口溢出。\n\n```python\ndef nest_handoff_history(\n handoff_input_data: HandoffInputData,\n *,\n history_mapper: HandoffHistoryMapper | None = None,\n) -> HandoffInputData:\n \"\"\"Summarize the previous transcript for the next agent.\"\"\"\n```\n\n处理流程：\n\n1. **规范化历史** - 调用 `_normalize_input_history()` 标准化输入格式\n2. **扁平化嵌套** - 调用 `_flatten_nested_history_messages()` 处理嵌套结构\n3. **转换格式** - 将 `RunItem` 转换为 `TResponseInputItem`\n4. **过滤项目** - 跳过 `ToolApprovalItem` 等特定类型\n5. **生成摘要** - 使用 LLM 生成压缩后的历史摘要\n\n资料来源：[src/agents/handoffs/history.py]()\n\n### 历史包装器\n\n系统使用标记符号包围嵌套的历史摘要：\n\n```python\n_DEFAULT_CONVERSATION_HISTORY_START = \"\"\n_DEFAULT_CONVERSATION_HISTORY_END = \"\"\n```\n\n可通过以下函数自定义：\n\n```python\nset_conversation_history_wrappers(start=\"\", end=\"\")\nreset_conversation_history_wrappers()\nget_conversation_history_wrappers() -> tuple[str, str]\n```\n\n资料来源：[src/agents/handoffs/history.py]()\n\n## 输入过滤详解\n\n### 过滤执行流程\n\n```mermaid\ngraph LR\n A[原始输入历史] --> B[HandoffInputFilter]\n B --> C[过滤后的历史]\n B --> D[新增输入项]\n C --> E[传递给目标 Agent]\n D --> E\n```\n\n### 内置过滤器\n\n框架在 `src/agents/extensions/handoff_filters.py` 中提供了常用的过滤器实现：\n\n| 过滤器 | 功能描述 |\n|--------|----------|\n| `filter_tool_messages` | 移除历史中的工具调用消息 |\n| `filter_non_agent_messages` | 仅保留 Agent 生成的消息 |\n| `filter_by_role` | 按角色过滤消息 |\n| `truncate_history` | 截断过长的历史记录 |\n\n资料来源：[src/agents/extensions/handoff_filters.py]()\n\n### 自定义过滤器示例\n\n```python\ndef my_input_filter(\n items: list[RunItem], \n data: HandoffInputData\n) -> tuple[list[RunItem], list[TResponseInputItem]]:\n # 只保留最近10条消息\n recent_items = items[-10:]\n new_items = [create_summary_item(data)]\n return recent_items, new_items\n\nhandoff = Handoff(\n name=\"transfer_to_analyst\",\n agent_name=\"analyst\",\n on_invoke_handoff=invoke_analyst,\n input_filter=my_input_filter,\n)\n```\n\n## 转交提示词\n\n### 提示词模板\n\n系统在 `src/agents/extensions/handoff_prompt.py` 中定义了转交相关的提示词模板，用于指导 LLM 理解何时以及如何触发转交。\n\n主要提示词组件包括：\n\n| 组件 | 用途 |\n|------|------|\n| `handoff_trigger_prompt` | 指导 LLM 判断触发转交的时机 |\n| `handoff_args_prompt` | 指导 LLM 生成转交参数 |\n| `handoff_summary_prompt` | 用于生成历史摘要 |\n\n资料来源：[src/agents/extensions/handoff_prompt.py]()\n\n## 高级配置\n\n### 条件启用转交\n\n```python\ndef dynamic_enabled(\n context: RunContextWrapper[Any], \n agent: AgentBase, \n tool: MCPTool\n) -> bool:\n # 根据上下文条件判断是否启用\n return context.metadata.get(\"user_tier\") == \"premium\"\n\nhandoff = Handoff(\n name=\"transfer_to_expert\",\n agent_name=\"expert\",\n on_invoke_handoff=invoke_expert,\n is_enabled=dynamic_enabled,\n)\n```\n\n### 带参数的转交\n\n```python\nfrom pydantic import BaseModel\n\nclass TransferArgs(BaseModel):\n reason: str\n priority: str = \"normal\"\n\ndef handle_handoff(context: RunContextWrapper, args: TransferArgs):\n logger.info(f\"Transferring to expert: {args.reason}\")\n return expert_agent\n\nhandoff = Handoff(\n name=\"transfer_to_expert\",\n agent_name=\"expert\",\n on_invoke_handoff=handle_handoff,\n input_type=TransferArgs,\n on_handoff=lambda ctx, args: print(f\"Transfer: {args}\"),\n)\n```\n\n### 禁用转交\n\n```python\n# 完全禁用\nhandoff = Handoff(\n name=\"transfer_to_debug\",\n agent_name=\"debugger\",\n on_invoke_handoff=invoke_debugger,\n is_enabled=False, # 对 LLM 隐藏此转交\n)\n```\n\n## 使用示例\n\n### 基本转交模式\n\n```python\nfrom agents import Agent, Runner, handoff\n\n# 定义两个 Agent\ngeneral_agent = Agent(\n name=\"general\",\n instructions=\"你是一个通用助手。\",\n handoffs=[\n handoff(\n agent=analytics_agent,\n on_handoff=lambda ctx, input: print(\"转移到分析代理\")\n )\n ]\n)\n\nanalytics_agent = Agent(\n name=\"analytics\",\n instructions=\"你是一个数据分析专家。\"\n)\n\n# 执行转交\nresult = await Runner.run(general_agent, \"分析本月的销售数据\")\n```\n\n### 带输入过滤的转交\n\n```python\nfrom agents.handoffs import HandoffInputFilter\n\ndef clean_history_filter(\n items: list[RunItem], \n data: HandoffInputData\n) -> tuple[list[RunItem], list[TResponseInputItem]]:\n # 移除所有工具调用记录\n clean_items = [i for i in items if not isinstance(i, ToolCallItem)]\n return clean_items, []\n\nhandoff = Handoff(\n name=\"escalate\",\n agent_name=\"supervisor\",\n on_invoke_handoff=invoke_supervisor,\n input_filter=clean_history_filter,\n)\n```\n\n资料来源：[examples/handoffs/message_filter.py]()\n\n## 错误处理\n\n### 常见错误场景\n\n| 错误类型 | 触发条件 | 处理建议 |\n|----------|----------|----------|\n| `UserError` | 提供了 `input_type` 但未提供 `on_handoff` | 确保两者同时配置 |\n| `UserError` | `on_handoff` 参数数量不为 2 | 回调必须接收 `context` 和 `input` 两个参数 |\n| `NotImplementedError` | MCP 服务器不支持特定资源操作 | 检查服务器能力 |\n\n资料来源：[src/agents/handoffs/__init__.py](), [src/agents/mcp/server.py]()\n\n## 架构总结\n\n```mermaid\ngraph TD\n subgraph \"转交发起方\"\n A[Agent A] --> B[Handoff 配置]\n B --> C[工具调用]\n end\n \n subgraph \"转交处理\"\n C --> D[on_handoff 回调]\n D --> E[input_filter 处理]\n E --> F[历史摘要生成]\n F --> G[on_invoke_handoff]\n end\n \n subgraph \"转交接收方\"\n G --> H[Agent B]\n H --> I[处理任务]\n end\n```\n\nAgent 转交机制通过解耦转交配置、转交执行、输入处理和历史管理四个关键环节，实现了灵活且可扩展的多代理协作模式。开发者可以通过组合不同的过滤器、回调函数和配置选项，构建复杂的代理工作流程。\n\n---\n\n\n\n## Guardrails 安全机制\n\n### 相关页面\n\n相关主题：[Agent 核心框架](#agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/guardrail.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/guardrail.py)\n- [src/agents/tool_guardrails.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool_guardrails.py)\n- [src/agents/run_internal/guardrails.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/guardrails.py)\n- [examples/agent_patterns/input_guardrails.py](https://github.com/openai/openai-agents-python/blob/main/examples/agent_patterns/input_guardrails.py)\n- [examples/agent_patterns/output_guardrails.py](https://github.com/openai/openai-agents-python/blob/main/examples/agent_patterns/output_guardrails.py)\n \n\n# Guardrails 安全机制\n\n## 概述\n\nGuardrails（安全护栏）机制是 openai-agents-python 框架中用于验证和过滤输入输出内容的关键安全组件。该机制在整个 Agent 运行周期中提供多层次的防护，确保模型行为符合预期规范，防止敏感信息泄露和危险操作执行。\n\nGuardrails 系统主要解决以下安全问题：\n\n- **输入验证**：在用户输入到达 Agent 之前进行安全检查\n- **输出过滤**：对模型生成的内容进行合规性验证\n- **工具调用保护**：在工具输入和输出阶段进行安全校验\n- **追踪审计**：记录安全检查的触发和执行情况\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户输入] --> B[输入 Guardrails 检查]\n B --> C{检查结果}\n C -->|通过| D[Agent 处理]\n C -->|触发| E[拒绝/拦截]\n D --> F[模型响应]\n F --> G[输出 Guardrails 检查]\n G --> H{检查结果}\n H -->|通过| I[返回结果]\n H -->|触发| J[内容过滤/拒绝]\n D --> K[工具调用]\n K --> L[工具输入 Guardrails]\n K --> M[工具执行]\n M --> N[工具输出 Guardrails]\n```\n\n### 组件层次\n\nGuardrails 机制由以下核心组件构成：\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| `Guardrail` | `src/agents/guardrail.py` | 基础 Guardrail 抽象类定义 |\n| `ToolInputGuardrail` | `src/agents/tool_guardrails.py` | 工具输入验证 |\n| `ToolOutputGuardrail` | `src/agents/tool_guardrails.py` | 工具输出验证 |\n| `InputGuardrailFunction` | `examples/agent_patterns/input_guardrails.py` | 输入检查函数示例 |\n| `OutputGuardrailFunction` | `examples/agent_patterns/output_guardrails.py` | 输出检查函数示例 |\n\n## 核心类型定义\n\n### GuardrailSpanData\n\n在追踪系统中，Guardrail 的执行状态通过 `GuardrailSpanData` 进行封装：\n\n```python\nclass GuardrailSpanData:\n name: str # Guardrail 名称标识\n triggered: bool # 是否被触发\n```\n\n### Guardrail 函数签名\n\n```python\nasync def guardrail_function(\n ctx: RunContext,\n agent: Agent,\n input: str | list[Message]\n) -> GuardrailResult:\n \"\"\"\n Args:\n ctx: 运行上下文\n agent: 当前 Agent 实例\n input: 待验证的输入内容\n Returns:\n GuardrailResult: 包含触发状态和输出信息\n \"\"\"\n```\n\n## 输入 Guardrails\n\n### 功能描述\n\n输入 Guardrails 在用户输入进入 Agent 处理流程之前进行安全检查。资料来源：[examples/agent_patterns/input_guardrails.py:1-50]()\n\n### 配置方式\n\n```python\nfrom agents import Agent, InputGuardrail, InputGuardrailFunction\n\nasync def check_sensitive_input(ctx, agent, input) -> GuardrailResult:\n \"\"\"检查输入是否包含敏感内容\"\"\"\n if contains_problematic_content(input):\n return GuardrailResult(\n triggerred=True,\n message=\"输入包含敏感内容，已被拦截\"\n )\n return GuardrailResult(triggerred=False)\n\nagent = Agent(\n name=\"安全助手\",\n instructions=\"你是一个有帮助的助手\",\n input_guardrails=[\n InputGuardrail(function=check_sensitive_input)\n ]\n)\n```\n\n### 执行流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户输入\n participant IG as 输入 Guardrail\n participant A as Agent\n participant T as 追踪系统\n\n U->>IG: 原始输入内容\n IG->>T: guardrail_span(name=\"input_check\")\n IG->>IG: 执行检查逻辑\n alt 检查通过\n IG->>A: 传递输入\n A-->>U: 正常响应\n else 检查触发\n IG-->>U: 返回错误信息\n end\n```\n\n## 输出 Guardrails\n\n### 功能描述\n\n输出 Guardrails 负责在模型生成响应后、返回给用户之前进行内容验证和过滤。资料来源：[examples/agent_patterns/output_guardrails.py:1-50]()\n\n### 配置方式\n\n```python\nfrom agents import Agent, OutputGuardrail, OutputGuardrailFunction\n\nasync def check_output_content(ctx, agent, output) -> GuardrailResult:\n \"\"\"检查输出内容的安全性\"\"\"\n if contains_harmful_content(output.content):\n return GuardrailResult(\n triggerred=True,\n message=\"输出内容包含不当信息\"\n )\n return GuardrailResult(triggerred=False)\n\nagent = Agent(\n name=\"内容审核助手\",\n instructions=\"生成安全的内容\",\n output_guardrails=[\n OutputGuardrail(function=check_output_content)\n ]\n)\n```\n\n## 工具级 Guardrails\n\n### 工具输入检查\n\nToolInputGuardrail 在工具执行前验证传入参数的安全性：\n\n```python\nclass ToolInputGuardrail(Guardrail):\n \"\"\"工具输入安全检查\"\"\"\n \n async def check(\n self,\n ctx: RunContext,\n agent: Agent,\n tool: Tool,\n input_data: dict\n ) -> GuardrailResult:\n # 验证输入参数是否符合预期格式和范围\n pass\n```\n\n### 工具输出检查\n\nToolOutputGuardrail 在工具执行后验证返回结果：\n\n```python\nclass ToolOutputGuardrail(Guardrail):\n \"\"\"工具输出安全检查\"\"\"\n \n async def check(\n self,\n ctx: RunContext,\n agent: Agent,\n tool: Tool,\n output: Any\n ) -> GuardrailResult:\n # 验证输出是否包含敏感信息\n pass\n```\n\n### 执行上下文\n\n工具级 Guardrails 的检查结果通过 `tool_input_guardrail_results` 和 `tool_output_guardrail_results` 参数在执行流程中传递。资料来源：[src/agents/run_internal/turn_resolution.py:50-80]()\n\n## 追踪与监控\n\n### Guardrail Span 创建\n\n每个 Guardrail 检查都会生成对应的追踪 Span：\n\n```python\ndef guardrail_span(\n name: str,\n triggered: bool = False,\n span_id: str | None = None,\n parent: Trace | Span[Any] | None = None,\n disabled: bool = False,\n) -> Span[GuardrailSpanData]:\n \"\"\"创建 Guardrail 追踪 Span\"\"\"\n```\n\n资料来源：[src/agents/tracing/create.py:40-60]()\n\n### 追踪数据结构\n\n```mermaid\nclassDiagram\n class GuardrailSpanData {\n +str name\n +bool triggered\n }\n \n class Span {\n +start()\n +finish()\n +set_status()\n }\n \n class Trace {\n +create_span()\n +get_spans()\n }\n \n Span --> GuardrailSpanData\n Trace ..> Span : creates\n```\n\n## Agent 配置集成\n\n### 完整配置示例\n\n```python\nfrom agents import Agent, RunContext\n\nagent = Agent(\n name=\"安全问答助手\",\n instructions=\"提供安全、准确的信息\",\n input_guardrails=[\n InputGuardrail(function=validate_user_input),\n ],\n output_guardrails=[\n OutputGuardrail(function=validate_model_output),\n ],\n tool_input_guardrails=[\n ToolInputGuardrail(function=validate_tool_params),\n ],\n tool_output_guardrails=[\n ToolOutputGuardrail(function=validate_tool_result),\n ],\n)\n```\n\n### 配置参数说明\n\n| 参数 | 类型 | 说明 | 必填 |\n|------|------|------|------|\n| `input_guardrails` | `list[InputGuardrail]` | 输入检查列表 | 否 |\n| `output_guardrails` | `list[OutputGuardrail]` | 输出检查列表 | 否 |\n| `tool_input_guardrails` | `list[ToolInputGuardrail]` | 工具输入检查 | 否 |\n| `tool_output_guardrails` | `list[ToolOutputGuardrail]` | 工具输出检查 | 否 |\n\n## 执行流程详解\n\n### 单轮对话中的 Guardrails 执行\n\n```mermaid\ngraph LR\n subgraph 输入阶段\n A1[用户消息] --> A2[Input Guardrails]\n A2 --> A3{触发?}\n end\n \n subgraph 处理阶段\n A3 -->|否| B1[Agent 处理]\n B1 --> B2[工具调用]\n end\n \n subgraph 工具阶段\n B2 --> C1[Tool Input Guardrails]\n C1 --> C2{触发?}\n C2 -->|是| C4[拦截]\n C2 -->|否| B3[执行工具]\n B3 --> C3[Tool Output Guardrails]\n C3 --> C5{触发?}\n C5 -->|是| C4\n end\n \n subgraph 输出阶段\n C5 -->|否| D1[Agent 响应生成]\n D1 --> D2[Output Guardrails]\n D2 --> D3{触发?}\n D3 -->|否| D4[返回结果]\n D3 -->|是| D5[返回错误]\n end\n```\n\n### 检查结果处理\n\n当 Guardrail 被触发时，系统会中断当前执行流程：\n\n1. **输入检查触发**：返回验证错误，拒绝处理请求\n2. **输出检查触发**：过滤或拒绝返回内容\n3. **工具检查触发**：阻止工具执行或过滤返回数据\n\n资料来源：[src/agents/run_internal/guardrails.py:1-100]()\n\n## 最佳实践\n\n### 1. 分层检查策略\n\n建议采用多层防护策略：\n\n```python\n# 基础层：快速检查\nasync def basic_check(ctx, agent, input):\n # 使用正则或关键词快速匹配\n pass\n\n# 深度层：复杂分析\nasync def deep_check(ctx, agent, input):\n # 使用模型或更复杂的逻辑\n pass\n\nagent = Agent(\n input_guardrails=[\n InputGuardrail(function=basic_check, timeout=1.0),\n InputGuardrail(function=deep_check, timeout=10.0),\n ]\n)\n```\n\n### 2. 性能优化\n\n- 将简单快速的检查放在前面\n- 使用缓存避免重复检查\n- 设置合理的超时时间\n\n### 3. 错误处理\n\n```python\nasync def safe_guardrail(ctx, agent, input):\n try:\n return await perform_check(input)\n except CheckError as e:\n # 保守策略：检查失败时拒绝\n return GuardrailResult(triggerred=True, message=str(e))\n```\n\n## 与其他系统的协作\n\n### 与 Tracing 系统集成\n\nGuardrails 的执行状态会自动记录到追踪系统中，便于审计和问题排查。\n\n### 与 Handoff 系统协作\n\n在 Agent 间交接时，Guardrail 配置会随 Agent 定义一起传递，但历史对话内容不重复检查。资料来源：[src/agents/handoffs/history.py:1-50]()\n\n## 总结\n\nGuardrails 安全机制为 openai-agents-python 提供了完整的多层次安全防护能力，覆盖从用户输入到模型输出再到工具调用的完整流程。通过灵活的接口设计，开发者可以轻松实现自定义的安全检查逻辑，同时追踪系统提供了完整的审计能力。\n\n---\n\n\n\n## 沙箱 Agent 概述\n\n### 相关页面\n\n相关主题：[沙箱会话管理](#sandbox-session)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/sandbox/sandbox_agent.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/sandbox_agent.py)\n- [src/agents/sandbox/runtime.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/runtime.py)\n- [src/agents/sandbox/manifest.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/manifest.py)\n- [src/agents/sandbox/capabilities/capabilities.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/capabilities/capabilities.py)\n- [examples/sandbox/basic.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/basic.py)\n- [examples/sandbox/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/README.md)\n- [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)\n- [src/agents/sandbox/util/tar_utils.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/util/tar_utils.py)\n- [examples/sandbox/tutorials/dataroom_metric_extract/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tutorials/dataroom_metric_extract/README.md)\n- [examples/sandbox/tutorials/repo_code_review/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tutorials/repo_code_review/README.md)\n \n\n# 沙箱 Agent 概述\n\n## 简介\n\n沙箱 Agent（Sandbox Agent）是 openai-agents-python 框架中用于在隔离环境中执行 AI 代理任务的组件。沙箱提供了安全的运行时环境，代理可以在其中执行文件操作、运行命令、安装依赖等操作，而不会影响宿主机系统。\n\n沙箱 Agent 的核心价值在于：\n\n- **隔离性**：代理在独立的虚拟工作空间中运行，与宿主环境完全隔离\n- **安全性**：通过路径验证和权限控制防止恶意操作\n- **可重现性**：支持快照（Snapshot）和持久化工作区，便于恢复和复用\n- **多后端支持**：支持多种沙箱提供商，包括 E2B、Modal、Cloudflare、Blaxel、Vercel、Daytona 等\n\n资料来源：[examples/sandbox/README.md:1-15]()\n\n## 核心组件\n\n### 组件架构图\n\n```mermaid\ngraph TD\n A[用户代码] --> B[SandboxAgent]\n B --> C[SandboxRuntime]\n C --> D[Manifest]\n C --> E[Capabilities]\n D --> F[Workspace]\n E --> G[Shell工具]\n E --> H[File工具]\n E --> I[其他工具]\n F --> J[E2B后端]\n F --> K[Modal后端]\n F --> L[Cloudflare后端]\n F --> M[其他后端]\n```\n\n### SandboxAgent\n\n`SandboxAgent` 是沙箱代理的核心类，继承自 `AgentBase`。它负责在沙箱环境中执行代理任务。\n\n**主要职责：**\n\n- 创建和管理沙箱会话\n- 配置工作区清单（Manifest）\n- 应用沙箱能力（Capabilities）\n- 处理代理与沙箱之间的交互\n\n资料来源：[src/agents/sandbox/sandbox_agent.py]()\n\n### SandboxRuntime\n\n`SandboxRuntime` 是沙箱的运行时环境，负责实际执行命令和文件操作。\n\n**主要职责：**\n\n- 初始化沙箱会话\n- 执行 shell 命令\n- 管理文件系统操作\n- 处理工作区持久化\n\n资料来源：[src/agents/sandbox/runtime.py]()\n\n### Manifest\n\nManifest 定义了沙箱工作区的初始状态和配置。它描述了需要注入到沙箱中的文件、目录和环境变量。\n\n**Manifest 核心配置项：**\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `name` | str | Manifest 名称 |\n| `description` | str | 描述信息 |\n| `image` | str | 容器镜像（可选） |\n| `env_vars` | dict | 环境变量 |\n| `files` | list | 要注入的文件列表 |\n| `setup` | list | 初始化命令列表 |\n| `index_url` | str | Python 包索引 URL |\n\n资料来源：[src/agents/sandbox/manifest.py]()\n\n### Capabilities\n\nCapabilities 定义了沙箱代理可以使用的工具集。这些能力通过 `SandboxToolset` 提供给代理使用。\n\n**内置能力：**\n\n| 能力名称 | 说明 |\n|----------|------|\n| `bash` | 执行 bash 命令 |\n| `read` | 读取文件内容 |\n| `write` | 写入文件内容 |\n| `edit` | 编辑文件 |\n| `glob` | 文件模式匹配 |\n| `grep` | 文本搜索 |\n| `web_search` | 网络搜索 |\n\n资料来源：[src/agents/sandbox/capabilities/capabilities.py]()\n\n## 快速开始\n\n### 基础使用示例\n\n以下示例展示了如何创建和运行一个基本的沙箱 Agent：\n\n```python\nfrom agents import SandboxAgent, Runner\nfrom agents.sandbox import Sandbox\n\nasync def main():\n sandbox = Sandbox()\n \n agent = SandboxAgent(\n name=\"文件分析助手\",\n instructions=\"分析工作区中的文件并提供摘要\",\n sandbox=sandbox,\n )\n \n result = await Runner.run(agent, \"查看当前目录下的所有 Python 文件\")\n print(result.final_output)\n```\n\n资料来源：[examples/sandbox/basic.py:1-30]()\n\n### 带 Manifest 的配置\n\n```python\nfrom agents import SandboxAgent, Runner\nfrom agents.sandbox import Sandbox, Manifest\n\nasync def main():\n manifest = Manifest(\n name=\"数据分析环境\",\n description=\"用于数据分析的 Python 环境\",\n files=[\n {\"path\": \"data.csv\", \"content\": \"...\"},\n ],\n setup=[\n \"pip install pandas numpy\",\n ],\n )\n \n sandbox = Sandbox(manifest=manifest)\n agent = SandboxAgent(\n name=\"数据分析师\",\n instructions=\"使用 Python 分析数据文件\",\n sandbox=sandbox,\n )\n```\n\n## 工作流程\n\n### 执行流程图\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as SandboxAgent\n participant Runtime as SandboxRuntime\n participant Sandbox as Sandbox Backend\n participant Workspace as Workspace\n\n User->>Agent: 启动代理\n Agent->>Runtime: 初始化沙箱\n Runtime->>Sandbox: 创建会话\n Sandbox->>Workspace: 注入 Manifest\n Workspace-->>Sandbox: 工作区就绪\n Sandbox-->>Runtime: 会话建立\n Runtime-->>Agent: 沙箱就绪\n Agent->>Runtime: 执行任务\n Runtime->>Workspace: 文件操作\n Runtime->>Sandbox: Shell 命令\n Workspace-->>Runtime: 结果\n Sandbox-->>Runtime: 输出\n Runtime-->>Agent: 任务结果\n Agent-->>User: 最终输出\n```\n\n### Manifest 处理流程\n\n1. **Manifest 验证**：检查 Manifest 配置的有效性\n2. **文件注入**：将 Manifest 中定义的文件注入到工作区\n3. **环境设置**：配置环境变量和初始化命令\n4. **路径解析**：验证所有路径都在工作区根目录内\n\n资料来源：[src/agents/sandbox/util/tar_utils.py:1-50]()\n\n## 多后端支持\n\n框架支持多种沙箱后端实现，开发者可以根据需求选择合适的后端。\n\n### 支持的后端\n\n| 后端 | 说明 | 特点 |\n|------|------|------|\n| E2B | 云端沙箱服务 | 成熟稳定，支持 PTY |\n| Modal | Modal 平台沙箱 | 支持持久化工作区 |\n| Cloudflare | Cloudflare 沙箱 | 支持云存储挂载 |\n| Blaxel | Blaxel 平台 | 支持 Drive 挂载 |\n| Vercel | Vercel 平台 | 支持 Node.js 运行时 |\n| Daytona | Daytona 沙箱 | 轻量级方案 |\n\n资料来源：[examples/sandbox/extensions/README.md:1-100]()\n\n### 后端选择示例\n\n```python\n# 使用 E2B 后端\nsandbox = Sandbox(backend=\"e2b\")\n\n# 使用 Modal 后端\nsandbox = Sandbox(backend=\"modal\")\n\n# 使用自定义后端\nfrom agents.sandbox.backends.modal import ModalSandbox\nsandbox = ModalSandbox(\n app_name=\"my-sandbox\",\n workspace_persistence=\"snapshot\"\n)\n```\n\n## 工具集成\n\n### 沙箱代理与工具的结合\n\n沙箱 Agent 可以与其他框架工具结合使用，实现更复杂的功能。\n\n```python\nfrom agents import SandboxAgent, Runner, function_tool\n\n@function_tool\ndef get_external_data(query: str) -> str:\n \"\"\"获取外部数据源\"\"\"\n return f\"External data for: {query}\"\n\nasync def main():\n sandbox = Sandbox()\n \n agent = SandboxAgent(\n name=\"研究助手\",\n instructions=\"结合外部数据和沙箱内文件完成研究任务\",\n sandbox=sandbox,\n tools=[get_external_data],\n )\n \n result = await Runner.run(\n agent, \n \"分析沙箱中的数据并结合外部信息源给出建议\"\n )\n```\n\n资料来源：[examples/sandbox/sandbox_agent_with_tools.py]()\n\n### 工作区能力\n\n沙箱 Agent 可以配置工作区能力（Workspace Capabilities），以更精细地控制代理的操作范围。\n\n```python\nfrom agents.sandbox.capabilities import (\n WorkspaceCapabilities,\n BashCapability,\n FileReadCapability,\n)\n\ncapabilities = WorkspaceCapabilities(\n tools=[\n BashCapability(timeout=30),\n FileReadCapability(allowed_paths=[\"/workspace/data\"]),\n ],\n)\n\nsandbox = Sandbox(capabilities=capabilities)\n```\n\n资料来源：[src/agents/sandbox/capabilities/capabilities.py]()\n\n## 安全机制\n\n### 路径安全\n\n框架实现了多层路径安全检查，防止路径遍历攻击：\n\n1. **根目录限制**：所有文件操作必须在工作区根目录下\n2. **符号链接检查**：禁止通过符号链接访问工作区外的路径\n3. **符号链接验证**：检查 tar 包中的符号链接是否安全\n\n```python\ndef validate_tarfile(\n tar: tarfile.TarFile,\n *,\n reject_symlink_rel_paths: Iterable[str | Path] = (),\n skip_rel_paths: Iterable[str | Path] = (),\n root_name: str | None = None,\n allow_symlinks: bool = True,\n allow_external_symlink_targets: bool = True,\n) -> None:\n # 检查路径是否逃逸根目录\n # 验证符号链接安全性\n```\n\n资料来源：[src/agents/sandbox/util/tar_utils.py:50-100]()\n\n### 执行权限控制\n\n- **命令白名单**：可以配置允许执行的命令列表\n- **超时控制**：防止无限循环或长时间运行\n- **资源限制**：限制 CPU、内存使用\n\n## 持久化与快照\n\n### 工作区持久化\n\n沙箱支持多种工作区持久化策略：\n\n| 策略 | 说明 | 适用场景 |\n|------|------|----------|\n| `tar` | 打包保存为 tar 文件 | 完整保存和传输 |\n| `snapshot` | 创建快照 | 快速恢复 |\n| `snapshot_filesystem` | 文件系统快照 | 大型工作区 |\n| `snapshot_directory` | 目录快照 | 简单场景 |\n\n```python\nsandbox = Sandbox(\n workspace_persistence=\"tar\",\n workspace_persistence_path=\"/path/to/save\"\n)\n```\n\n### 远程快照\n\n支持从远程快照启动沙箱：\n\n```python\nsandbox = Sandbox(\n snapshot_url=\"https://storage.example.com/snapshots/snapshot-001.tar\"\n)\n```\n\n资料来源：[examples/sandbox/sandbox_agent_with_remote_snapshot.py]()\n\n## 应用场景\n\n### 数据分析\n\n沙箱可以用于安全地分析敏感数据：\n\n```mermaid\ngraph LR\n A[敏感数据] --> B[沙箱环境]\n B --> C[数据处理]\n C --> D[分析结果]\n D --> E[报告输出]\n```\n\n**示例流程：**\n\n1. 将数据文件注入沙箱 Manifest\n2. 在隔离环境中执行数据分析代码\n3. 导出分析结果而不暴露原始数据\n\n资料来源：[examples/sandbox/tutorials/dataroom_metric_extract/README.md:1-30]()\n\n### 代码审查\n\n沙箱可用于自动化的代码审查任务：\n\n```mermaid\ngraph TD\n A[代码仓库] --> B[沙箱环境]\n B --> C[克隆代码]\n C --> D[运行审查工具]\n D --> E[生成报告]\n E --> F[修复建议]\n```\n\n资料来源：[examples/sandbox/tutorials/repo_code_review/README.md:1-25]()\n\n### 自动化测试\n\n沙箱提供隔离环境用于执行测试：\n\n- 隔离测试环境，避免污染宿主系统\n- 支持多种编程语言和测试框架\n- 自动收集测试结果和覆盖率报告\n\n## 配置选项\n\n### Sandbox 构造函数参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `backend` | str | \"e2b\" | 沙箱后端类型 |\n| `manifest` | Manifest | None | 工作区清单 |\n| `capabilities` | Capabilities | None | 能力配置 |\n| `timeout` | int | 300 | 超时时间（秒） |\n| `workspace_persistence` | str | None | 持久化策略 |\n| `workspace_persistence_path` | str | None | 持久化路径 |\n\n### 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥（必需） |\n| `E2B_API_KEY` | E2B 服务密钥 |\n| `MODAL_TOKEN_ID` | Modal Token ID |\n| `MODAL_TOKEN_SECRET` | Modal Token Secret |\n| `CLOUDFLARE_SANDBOX_API_KEY` | Cloudflare API 密钥 |\n\n## 最佳实践\n\n### 1. Manifest 优化\n\n- 仅注入必要的文件，减少启动时间\n- 使用 `.dockerignore` 类似规则排除不相关文件\n- 合理设置初始化命令，避免重复安装\n\n### 2. 安全性考虑\n\n- 始终设置合理的超时时间\n- 使用路径白名单限制文件访问\n- 避免在 Manifest 中包含敏感信息\n\n### 3. 性能优化\n\n- 对于重复任务，使用快照恢复而非重新初始化\n- 合理配置并发沙箱数量\n- 使用轻量级后端（如 Daytona）处理简单任务\n\n### 4. 调试技巧\n\n```python\n# 启用详细日志\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\n# 使用暂停模式检查状态\nsandbox = Sandbox(pause_on_exit=True)\n\n# 查看沙箱输出\nresult = await Runner.run(agent, \"ls -la\", stream=True)\n```\n\n## 扩展开发\n\n### 自定义后端\n\n开发者可以实现 `SandboxBackend` 接口来添加新的沙箱后端：\n\n```python\nfrom agents.sandbox.backends.base import SandboxBackend\n\nclass MyCustomSandbox(SandboxBackend):\n async def create_session(self, manifest: Manifest) -> SandboxSession:\n # 实现自定义会话创建逻辑\n pass\n \n async def execute(self, command: str) -> ExecutionResult:\n # 实现命令执行逻辑\n pass\n```\n\n### 自定义能力\n\n扩展沙箱能力以支持特定工具：\n\n```python\nfrom agents.sandbox.capabilities import BaseCapability\n\nclass CustomCapability(BaseCapability):\n name = \"custom_tool\"\n description = \"自定义工具\"\n \n def get_tools(self) -> list[FunctionTool]:\n return [self.custom_function_tool]\n```\n\n## 相关资源\n\n- [沙箱基础示例](examples/sandbox/basic.py)\n- [沙箱扩展后端](examples/sandbox/extensions/README.md)\n- [沙箱教程 - 数据提取](examples/sandbox/tutorials/dataroom_metric_extract/README.md)\n- [沙箱教程 - 代码审查](examples/sandbox/tutorials/repo_code_review/README.md)\n- [沙箱教程 - 视觉网站克隆](examples/sandbox/tutorials/vision_website_clone/README.md)\n\n---\n\n\n\n## 沙箱会话管理\n\n### 相关页面\n\n相关主题：[沙箱 Agent 概述](#sandbox-agent)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/sandbox/session/sandbox_session.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/session/sandbox_session.py)\n- [src/agents/sandbox/session/base_sandbox_session.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/session/base_sandbox_session.py)\n- [src/agents/sandbox/session/manager.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/session/manager.py)\n- [src/agents/sandbox/snapshot.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/snapshot.py)\n- [src/agents/sandbox/files.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/files.py)\n- [src/agents/sandbox/entries/artifacts.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/entries/artifacts.py)\n \n\n# 沙箱会话管理\n\n## 概述\n\n沙箱会话管理是 openai-agents-python 框架中用于隔离执行 AI Agent 操作的核心子系统。它为每个 Agent 提供独立的虚拟工作空间，支持文件操作、命令执行、状态持久化以及工作区快照功能。沙箱机制确保 Agent 的操作不会影响主机系统安全，同时提供灵活的资源管理和跨后端支持。\n\n## 核心架构\n\n### 组件层次结构\n\n沙箱会话管理系统由以下核心组件构成：\n\n```mermaid\ngraph TD\n A[沙箱管理器 SessionManager] --> B[基础会话 BaseSandboxSession]\n B --> C[沙箱会话 SandboxSession]\n B --> D[工作区管理 FilesManager]\n B --> E[快照管理 SnapshotManager]\n C --> F[工件管理 ArtifactsManager]\n B --> G[后端实现 UnixLocal Cloudflare E2B Modal Vercel Daytona]\n```\n\n### 核心组件说明\n\n| 组件 | 文件位置 | 职责 |\n|------|---------|------|\n| `SessionManager` | `src/agents/sandbox/session/manager.py` | 管理多个沙箱会话的生命周期、创建和销毁 |\n| `BaseSandboxSession` | `src/agents/sandbox/session/base_sandbox_session.py` | 定义所有沙箱后端的抽象接口 |\n| `SandboxSession` | `src/agents/sandbox/session/sandbox_session.py` | 提供具体的工作区操作实现 |\n| `FilesManager` | `src/agents/sandbox/files.py` | 处理工作区的文件读写操作 |\n| `SnapshotManager` | `src/agents/sandbox/snapshot.py` | 管理工作区的快照保存和恢复 |\n\n## 会话生命周期管理\n\n### 创建流程\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant SessionManager\n participant BaseSandboxSession\n participant 后端实现\n participant Workspace\n\n 用户->>SessionManager: 创建会话请求\n SessionManager->>BaseSandboxSession: 初始化沙箱后端\n BaseSandboxSession->>后端实现: 创建沙箱实例\n 后端实现->>Workspace: 准备工作区\n Workspace-->>BaseSandboxSession: 工作区就绪\n BaseSandboxSession-->>SessionManager: 返回会话对象\n SessionManager-->>用户: 会话可用\n```\n\n### 核心方法\n\n沙箱会话提供以下核心生命周期方法：\n\n| 方法 | 功能 | 资料来源 |\n|------|------|---------|\n| `create()` | 创建新的沙箱会话实例 | `manager.py:1-50` |\n| `close()` | 关闭并清理沙箱资源 | `manager.py:50-80` |\n| `persist_workspace()` | 持久化当前工作区状态 | `base_sandbox_session.py:100-150` |\n| `hydrate_workspace()` | 从归档恢复工作区 | `unix_local.py:200-250` |\n\n## 工作区管理\n\n### 工作区文件系统\n\n沙箱工作区采用分层目录结构：\n\n```mermaid\ngraph TD\n Workspace[\"工作区根目录\"]\n Workspace --> Manifest[\"Manifest 定义\"]\n Workspace --> Scratch[\"临时文件目录\"]\n Workspace --> Output[\"输出产物目录\"]\n \n Manifest --> Binaries[\"二进制文件\"]\n Manifest --> SourceFiles[\"源码文件\"]\n Manifest --> ConfigFiles[\"配置文件\"]\n```\n\n### 文件操作接口\n\n`FilesManager` 类提供统一的工作区文件操作接口，资料来源：`src/agents/sandbox/files.py`\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `write()` | `path`, `content` | `None` | 写入文件内容 |\n| `read()` | `path` | `str` | 读取文件内容 |\n| `list()` | `path` | `list[Path]` | 列出目录内容 |\n| `delete()` | `path` | `None` | 删除文件或目录 |\n| `exists()` | `path` | `bool` | 检查路径是否存在 |\n\n### 安全机制\n\n系统实现了多层安全防护来防止路径遍历攻击：\n\n- **符号链接检查**：验证归档中的符号链接不会指向工作区外部 资料来源：`src/agents/sandbox/util/tar_utils.py:50-80`\n- **相对路径验证**：所有操作路径必须相对于工作区根目录\n- **根目录隔离**：确保文件操作被限制在工作区范围内\n\n```python\n# 安全路径验证示例\ndef validate_path_safety(dest: Path, root: Path) -> None:\n root_resolved = root.resolve()\n dest_resolved = dest.resolve()\n if not dest_resolved.is_relative_to(root_resolved):\n raise UnsafeTarMemberError(...)\n```\n\n## 快照管理系统\n\n### 快照类型\n\n快照系统支持两种主要模式：\n\n| 快照类型 | 用途 | 持久化方式 |\n|---------|------|-----------|\n| `SnapshotBase` | 完整工作区镜像 | 文件系统或远程存储 |\n| `SnapshotSpec` | 工作区配置规范 | 仅元数据 |\n\n### 快照操作流程\n\n```mermaid\ngraph LR\n A[创建快照] --> B[序列化工作区]\n B --> C[压缩为Tarball]\n C --> D[存储快照]\n D --> E[返回快照ID]\n \n F[恢复快照] --> G[获取快照数据]\n G --> H[解压到工作区]\n H --> I[验证完整性]\n I --> J[会话恢复]\n```\n\n资料来源：`src/agents/sandbox/snapshot.py`\n\n### 快照恢复机制\n\n```python\nasync def hydrate_workspace(self, data: io.IOBase) -> None:\n root = Path(self.state.manifest.root)\n root.mkdir(parents=True, exist_ok=True)\n with tarfile.open(fileobj=data, mode=\"r:*\") as tar:\n safe_extract_tarfile(tar, root=root, ...)\n```\n\n## 工件管理系统\n\n### 工件类型\n\n`ArtifactsManager` 负责管理沙箱会话生成的可交付产物，资料来源：`src/agents/sandbox/entries/artifacts.py`\n\n| 类型 | 描述 | 典型用途 |\n|------|------|---------|\n| `FileArtifact` | 单个文件产物 | 生成的代码、文档 |\n| `DirectoryArtifact` | 目录结构 | 项目输出、构建产物 |\n| `ArtifactBatch` | 批量产物 | 多文件导出 |\n\n### 工件生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 生成中: Agent 执行操作\n 生成中 --> 验证中: 写入完成\n 验证中 --> 已确认: 通过验证\n 验证中 --> 失败: 验证失败\n 已确认 --> [*]: 会话结束\n 失败 --> [*]: 错误报告\n```\n\n## 错误处理\n\n### 错误类层次结构\n\n```mermaid\ngraph TD\n SandboxError --> SandboxRuntimeError\n SandboxRuntimeError --> WorkspaceIOError\n SandboxRuntimeError --> ApplyPatchError\n SandboxError --> PTYSessionNotFoundError\n SandboxError --> UnsafeTarMemberError\n```\n\n### 核心错误类\n\n| 错误类 | 错误码 | 说明 |\n|-------|--------|------|\n| `WorkspaceArchiveWriteError` | `WORKSPACE_ARCHIVE_WRITE_ERROR` | 工作区归档写入失败 |\n| `ApplyPatchPathError` | `APPLY_PATCH_INVALID_PATH` | 路径验证失败 |\n| `UnsafeTarMemberError` | `UNSAFE_TAR_MEMBER` | Tar 归档包含不安全成员 |\n| `PTYSessionNotFoundError` | `PTY_SESSION_NOT_FOUND` | PTY 会话不存在 |\n\n资料来源：`src/agents/sandbox/errors.py:1-100`\n\n## 多后端支持\n\n### 后端实现矩阵\n\n| 后端 | 后端ID | 特点 | 部署方式 |\n|------|--------|------|---------|\n| UnixLocal | `unix_local` | 本地进程隔离 | 本地开发 |\n| E2B | `e2b` | 云端沙箱 | 远程服务 |\n| Cloudflare | `cloudflare` | 边缘计算 | 云端 Workers |\n| Modal | `modal` | Serverless 函数 | 按需计算 |\n| Vercel | `vercel` | 边缘部署 | Edge Runtime |\n| Daytona | `daytona` | 容器化隔离 | 容器环境 |\n\n### 后端统一接口\n\n所有后端必须实现以下核心方法：\n\n```python\nclass BaseSandboxClient(Generic[TSandboxClientOptions]):\n backend_id: str\n supports_default_options: bool\n \n async def create(\n self,\n *,\n snapshot: SnapshotSpec | SnapshotBase | None = None,\n manifest: Manifest | None = None,\n options: TSandboxClientOptions | None = None,\n ) -> SandboxSession: ...\n```\n\n资料来源：`src/agents/sandbox/sandboxes/unix_local.py:100-150`\n\n## 配置选项\n\n### 沙箱会话选项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `timeout` | `int` | `300` | 执行超时时间(秒) |\n| `memory` | `int` | `1024` | 内存限制(MB) |\n| `cpu` | `float` | `1.0` | CPU 核心数 |\n| `image` | `str` | `None` | 容器镜像名称 |\n| `region` | `str` | `None` | 部署区域 |\n\n### 环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| `OPENAI_API_KEY` | 是 | OpenAI API 密钥 |\n| `E2B_API_KEY` | E2B后端 | E2B 服务密钥 |\n| `CLOUDFLARE_SANDBOX_API_KEY` | Cloudflare后端 | Cloudflare 服务密钥 |\n\n## 最佳实践\n\n### 会话管理建议\n\n1. **生命周期控制**：始终使用上下文管理器或显式调用 `close()` 确保资源释放\n2. **超时设置**：根据 Agent 任务复杂度合理设置 timeout 参数\n3. **状态持久化**：长时间任务应定期调用 `persist_workspace()` 保存进度\n4. **错误处理**：捕获 `SandboxRuntimeError` 并实现重试逻辑\n\n### 性能优化\n\n- **批量操作**：合并多个文件写入操作减少 I/O 开销\n- **快照策略**：仅在必要时创建完整快照，使用增量更新\n- **资源清理**：会话结束后及时清理临时文件和符号链接\n\n## 相关文档\n\n- [沙箱示例](../examples/sandbox/README.md)\n- [云端沙箱扩展](../examples/sandbox/extensions/README.md)\n- [医疗支持示例](../examples/sandbox/healthcare_support/README.md)\n- [视觉网站克隆教程](../examples/sandbox/tutorials/vision_website_clone/README.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：openai/openai-agents-python\n\n摘要：发现 24 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `openai-agents-python` 与安装入口 `openai-agents` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install openai-agents`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:946380199 | https://github.com/openai/openai-agents-python | repo=openai-agents-python; install=openai-agents\n\n## 2. 配置坑 · 来源证据：AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the base table\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the base table\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d867c75f80af49c9968398851ff8bf6a | https://github.com/openai/openai-agents-python/issues/3346 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：Clarify whether retry-after delays should respect retry max_delay\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Clarify whether retry-after delays should respect retry max_delay\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f486d2247bf24df8bbc7a2bd6fddbd65 | https://github.com/openai/openai-agents-python/issues/3266 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：OpenAIConversationsSession persists empty reasoning item {\"type\":\"reasoning\",\"summary\":[]} and Conversations API reject…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenAIConversationsSession persists empty reasoning item {\"type\":\"reasoning\",\"summary\":[]} and Conversations API rejects it as invalid\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d6bad5c23bf3457eb546c22a1636cc26 | https://github.com/openai/openai-agents-python/issues/3268 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Tracing shutdown cannot interrupt exporter retry backoff\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Tracing shutdown cannot interrupt exporter retry backoff\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e1ceae098cf84c8aafae7082b13c5345 | https://github.com/openai/openai-agents-python/issues/3354 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 来源证据：v0.15.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.15.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b73472b5ae90447199984775aacdca67 | https://github.com/openai/openai-agents-python/releases/tag/v0.15.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 来源证据：v0.15.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.15.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7e05a382001a4d07b74eda1e1316320b | https://github.com/openai/openai-agents-python/releases/tag/v0.15.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：v0.16.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.16.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_44335088ff52486e9f2f41f72a274c35 | https://github.com/openai/openai-agents-python/releases/tag/v0.16.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 来源证据：v0.17.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.17.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_86b81f310a6e45feadc65196a057b23b | https://github.com/openai/openai-agents-python/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 来源证据：v0.15.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.15.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4c70d563ac704aeaa14b8e2c49976bc5 | https://github.com/openai/openai-agents-python/releases/tag/v0.15.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 能力坑 · 能力判断依赖假设\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:946380199 | https://github.com/openai/openai-agents-python | README/documentation is current enough for a first validation pass.\n\n## 12. 运行坑 · 来源证据：v0.14.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.14.8\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a31947cfee3a4299923f7714bfb54f42 | https://github.com/openai/openai-agents-python/releases/tag/v0.14.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 维护坑 · 来源证据：AdvancedSQLiteSession.add_items can report success after structure metadata failure\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：AdvancedSQLiteSession.add_items can report success after structure metadata failure\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0fed2dd63d55400d9e0d9adaf08570e5 | https://github.com/openai/openai-agents-python/issues/3348 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 来源证据：Chat Completions converter can send empty tool output for non-text results\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Chat Completions converter can send empty tool output for non-text results\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_34a35e920a01467e957cdd59b4179cc1 | https://github.com/openai/openai-agents-python/issues/3310 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. 维护坑 · 来源证据：v0.15.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.15.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_33cd0193aea84f9b82b15a02098d85cd | https://github.com/openai/openai-agents-python/releases/tag/v0.15.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:946380199 | https://github.com/openai/openai-agents-python | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:946380199 | https://github.com/openai/openai-agents-python | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在安全注意事项\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:946380199 | https://github.com/openai/openai-agents-python | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 19. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:946380199 | https://github.com/openai/openai-agents-python | no_demo; severity=medium\n\n## 20. 安全/权限坑 · 来源证据：Proposal: per-run BudgetGuard for token / request / cost limits (follow-up to #2848)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Proposal: per-run BudgetGuard for token / request / cost limits (follow-up to #2848)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_00884163bb274aecb62eeff18df12634 | https://github.com/openai/openai-agents-python/issues/3353 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：v0.16.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.16.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a9d11d6b8fd24b22882ee03998b45d63 | https://github.com/openai/openai-agents-python/releases/tag/v0.16.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 22. 安全/权限坑 · 来源证据：v0.17.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.17.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d47be3955c747baadea812c5f4c6487 | https://github.com/openai/openai-agents-python/releases/tag/v0.17.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 23. 维护坑 · 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:946380199 | https://github.com/openai/openai-agents-python | issue_or_pr_quality=unknown\n\n## 24. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:946380199 | https://github.com/openai/openai-agents-python | release_recency=unknown\n\n\n",
"markdown_key": "openai-agents-python",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:946380199",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/openai/openai-agents-python"
},
{
"evidence_id": "art_6011864ffb544ed1b0e793253ce40dd1",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/openai/openai-agents-python#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "openai-agents-python 说明书",
"toc": [
"https://github.com/openai/openai-agents-python 项目说明书",
"目录",
"项目概述",
"项目简介",
"核心架构",
"关键特性",
"典型的交接流程",
"应用场景",
"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": "92e014a4cc4d3cbaac6934cd12af1b641f204ab4",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/tracing.md",
"docs/tools.md",
"docs/repl.md",
"docs/human_in_the_loop.md",
"docs/index.md",
"docs/context.md",
"docs/quickstart.md",
"docs/streaming.md",
"docs/usage.md",
"docs/multi_agent.md",
"docs/examples.md",
"docs/sandbox_agents.md",
"docs/results.md",
"docs/running_agents.md",
"docs/agents.md",
"docs/handoffs.md",
"docs/mcp.md",
"docs/release.md",
"docs/guardrails.md",
"docs/visualization.md",
"docs/config.md",
"docs/voice/tracing.md",
"docs/voice/pipeline.md",
"docs/voice/quickstart.md",
"docs/ja/tracing.md",
"docs/ja/tools.md",
"docs/ja/repl.md",
"docs/ja/human_in_the_loop.md",
"docs/ja/sessions.md",
"docs/ja/index.md",
"docs/ja/context.md",
"docs/ja/quickstart.md",
"docs/ja/streaming.md",
"docs/ja/usage.md",
"docs/ja/multi_agent.md",
"docs/ja/examples.md",
"docs/ja/sandbox_agents.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# openai-agents-python - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 openai-agents-python 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md`, `.agents/skills/final-release-review/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md`, `.agents/skills/final-release-review/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `docs/ja/quickstart.md`, `docs/ja/voice/quickstart.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install openai-agents` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0005` unverified 0.25, `clm_0006` unverified 0.25\n- `pip install 'openai-agents[voice]'` 证据：`docs/ja/voice/quickstart.md` Claim：`clm_0005` unverified 0.25\n- `pip install openai-agents # or` 证据：`docs/ja/quickstart.md` Claim：`clm_0006` unverified 0.25\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md`, `.agents/skills/final-release-review/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md`, `.agents/skills/final-release-review/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `docs/ja/quickstart.md`, `docs/ja/voice/quickstart.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0005` unverified 0.25, `clm_0006` unverified 0.25\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md`, `.agents/skills/final-release-review/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `docs/ja/quickstart.md`, `docs/ja/voice/quickstart.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md`, `.agents/skills/final-release-review/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `docs/ja/quickstart.md`, `docs/ja/voice/quickstart.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `docs/ja/quickstart.md`, `docs/ja/voice/quickstart.md` Claim：`clm_0008` 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 体验。 证据：`.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md`, `.agents/skills/final-release-review/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `docs/ja/quickstart.md`, `docs/ja/voice/quickstart.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：1306\n- 重要文件覆盖：40/1306\n- 证据索引条目：80\n- 角色 / Skill 条目：13\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请基于 openai-agents-python 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 openai-agents-python 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 openai-agents-python 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 13 个角色 / Skill / 项目文档条目。\n\n- **code-change-verification**（skill）：Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents Python repository. 激活提示：当用户任务与“code-change-verification”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/code-change-verification/SKILL.md`\n- **docs-sync**（skill）：Analyze main branch implementation and configuration to find missing, incorrect, or outdated documentation in docs/. Use when asked to audit doc coverage, sync docs with code, or propose doc updates/structure changes. Only update English docs under docs/ and never touch translated docs under docs/ja, docs/ko, or docs/zh. Provide a report and ask for approval before editing docs. 激活提示：当用户任务与“docs-sync”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/docs-sync/SKILL.md`\n- **examples-auto-run**（skill）：Run python examples in auto mode with logging, rerun helpers, and background control. 激活提示：当用户任务与“examples-auto-run”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/examples-auto-run/SKILL.md`\n- **final-release-review**（skill）：Perform a release-readiness review by locating the previous release tag from remote tags and auditing the diff e.g., v1.2.3... for breaking changes, regressions, improvement opportunities, and risks before releasing openai-agents-python. 激活提示：当用户任务与“final-release-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/final-release-review/SKILL.md`\n- **implementation-strategy**（skill）：Decide how to implement runtime and API changes in openai-agents-python before editing code. Use when a task changes exported APIs, runtime behavior, serialized state, tests, or docs and you need to choose the compatibility boundary, whether shims or migrations are warranted, and when unreleased interfaces can be rewritten directly. 激活提示：当用户任务与“implementation-strategy”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/implementation-strategy/SKILL.md`\n- **openai-knowledge**（skill）：Use when working with the OpenAI API Responses API or OpenAI platform features tools, streaming, Realtime API, auth, models, rate limits, MCP and you need authoritative, up-to-date documentation schemas, examples, limits, edge cases . Prefer the OpenAI Developer Documentation MCP server tools when available; otherwise guide the user to enable openaiDeveloperDocs . 激活提示：当用户任务与“openai-knowledge”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/openai-knowledge/SKILL.md`\n- **pr-draft-summary**（skill）：Create the required PR-ready summary block, branch suggestion, title, and draft description for openai-agents-python. Use in the final handoff after moderate-or-larger changes to runtime code, tests, examples, build/test configuration, or docs with behavior impact; skip only for trivial or conversation-only tasks, repo-meta/doc-only tasks without behavior impact, or when the user explicitly says not to include the P… 激活提示：当用户任务与“pr-draft-summary”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/pr-draft-summary/SKILL.md`\n- **runtime-behavior-probe**（skill）：Plan and execute runtime-behavior investigations with temporary probe scripts, validation matrices, state controls, and findings-first reports. Use only when the user explicitly invokes this skill to verify actual runtime behavior beyond normal code-level checks, especially to uncover edge cases, undocumented behavior, or common failure modes in local or live integrations. A baseline smoke check is fine as an entry… 激活提示：当用户任务与“runtime-behavior-probe”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/runtime-behavior-probe/SKILL.md`\n- **test-coverage-improver**（skill）：Improve test coverage in the OpenAI Agents Python repository: run make coverage , inspect coverage artifacts, identify low-coverage files, propose high-impact tests, and confirm with the user before writing tests. 激活提示：当用户任务与“test-coverage-improver”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/test-coverage-improver/SKILL.md`\n- **credit-note-fixer**（skill）：Fix the tiny credit-note formatting bug and rerun the exact targeted test command. 激活提示：当用户任务与“credit-note-fixer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`examples/sandbox/docs/skills/credit-note-fixer/SKILL.md`\n- **prior-auth-packet-builder**（skill）：Build a concise prior authorization packet from local case files and payer policy docs. 激活提示：当用户任务与“prior-auth-packet-builder”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`examples/sandbox/healthcare_support/skills/prior-auth-packet-builder/SKILL.md`\n- **playwright**（skill）：Use when the task requires capturing or automating a real browser from the terminal. 激活提示：当用户任务与“playwright”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`examples/sandbox/tutorials/vision_website_clone/skills/playwright/SKILL.md`\n- **csv-workbench**（skill）：Analyze CSV files in /mnt/data and return concise numeric summaries. 激活提示：当用户任务与“csv-workbench”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`examples/tools/skills/csv-workbench/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Agents**（documentation）：Agents are the core building block in your apps. An agent is a large language model LLM configured with instructions, tools, and optional runtime behavior such as handoffs, guardrails, and structured outputs. 证据：`docs/agents.md`\n- **エージェント**（documentation）：エージェントは、アプリにおける中核的な構成要素です。エージェントは、 instructions、tools、およびハンドオフ、ガードレール、structured outputs などの任意のランタイム動作で設定された大規模言語モデル LLM です。 证据：`docs/ja/agents.md`\n- **에이전트**（documentation）：에이전트는 앱의 핵심 구성 요소입니다. 에이전트는 instructions, tools, 그리고 핸드오프, 가드레일, structured outputs 같은 선택적 런타임 동작으로 구성된 대규모 언어 모델 LLM 입니다. 证据：`docs/ko/agents.md`\n- **智能体**（documentation）：智能体是应用中的核心构建块。智能体是一个大语言模型（LLM），配置了 instructions、工具，以及可选的运行时行为，例如任务转移、安全防护措施和 structured outputs。 证据：`docs/zh/agents.md`\n- **Credit Note Example Repo**（documentation）：This tiny repo exists to support examples/sandbox/docs/coding task.py . 证据：`examples/sandbox/docs/repo/README.md`\n- **Credit Note Fixer**（skill_instruction）：1. Read repo/task.md . 2. Inspect repo/credit note.sh and repo/tests/test credit note.sh . 3. Make the smallest correct change that keeps the output label as credit and the amount positive. If you use apply patch , use workspace-root-relative paths such as repo/credit note.sh and repo/tests/test credit note.sh . 4. Run exactly sh tests/test credit note.sh from repo/ . 5. In the final answer, summarize the bug, the fix, and the exact verification command. 证据：`examples/sandbox/docs/skills/credit-note-fixer/SKILL.md`\n- **Contributor Guide**（documentation）：This guide helps new contributors get started with the OpenAI Agents Python repository. It covers repo structure, how to test your work, available utilities, and guidelines for commits and PRs. 证据：`AGENTS.md`\n- **OpenAI Agents SDK ! PyPI https://img.shields.io/pypi/v/openai-agents?label=pypi%20package https://pypi.org/project/open…**（documentation）：OpenAI Agents SDK ! PyPI https://img.shields.io/pypi/v/openai-agents?label=pypi%20package https://pypi.org/project/openai-agents/ 证据：`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- **Common agentic patterns**（documentation）：This folder contains examples of different common patterns for agents. 证据：`examples/agent_patterns/README.md`\n- **Financial Research Agent Example**（documentation）：This example shows how you might compose a richer financial research agent using the Agents SDK. The pattern is similar to the research bot example, but with more specialized sub‑agents and a verification step. 证据：`examples/financial_research_agent/README.md`\n- **MCP Filesystem Example**（documentation）：This example uses the filesystem MCP server https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem , running locally via npx . 证据：`examples/mcp/filesystem_example/README.md`\n- **MCP get all mcp tools Example**（documentation）：Python port of the JS examples/mcp/get-all-mcp-tools-example.ts . It demonstrates: 证据：`examples/mcp/get_all_mcp_tools_example/README.md`\n- **MCP Git Example**（documentation）：This example uses the git MCP server https://github.com/modelcontextprotocol/servers/tree/main/src/git , running locally via uvx . 证据：`examples/mcp/git_example/README.md`\n- **MCP Manager Example FastAPI**（documentation）：This example shows how to use MCPServerManager to keep MCP server lifecycle management in a single task inside a FastAPI app with the Streamable HTTP transport. 证据：`examples/mcp/manager_example/README.md`\n- **MCP Prompt Server Example**（documentation）：This example uses a local MCP prompt server in server.py server.py . 证据：`examples/mcp/prompt_server/README.md`\n- **MCP SSE Example**（documentation）：This example uses a local SSE server in server.py server.py . 证据：`examples/mcp/sse_example/README.md`\n- **MCP SSE Remote Example**（documentation）：Python port of the JS examples/mcp/sse-example.ts . By default it starts the bundled local SSE MCP server and lets the agent use those tools. Set MCP SSE REMOTE URL to try a compatible remote SSE server instead. 证据：`examples/mcp/sse_remote_example/README.md`\n- **MCP Streamable HTTP Remote Example**（documentation）：Python port of the JS examples/mcp/streamable-http-example.ts . It connects to DeepWiki over the Streamable HTTP transport https://mcp.deepwiki.com/mcp and lets the agent use those tools. 证据：`examples/mcp/streamable_http_remote_example/README.md`\n- **Custom HTTP Client Factory Example**（documentation）：This example demonstrates how to use the new httpx client factory parameter in MCPServerStreamableHttp to configure custom HTTP client behavior for MCP StreamableHTTP connections. 证据：`examples/mcp/streamablehttp_custom_client_example/README.md`\n- **MCP Streamable HTTP Example**（documentation）：This example uses a local Streamable HTTP server in server.py server.py . 证据：`examples/mcp/streamablehttp_example/README.md`\n- **MCP Tool Filter Example**（documentation）：Python port of the JS examples/mcp/tool-filter-example.ts . It shows how to: 证据：`examples/mcp/tool_filter_example/README.md`\n- **Model provider examples**（documentation）：The examples in this directory show how to route models through adapter layers such as LiteLLM and any-llm. The default examples all use OpenRouter so you only need one API key: 证据：`examples/model_providers/README.md`\n- **Realtime Demo App**（documentation）：A web-based realtime voice assistant demo with a FastAPI backend and HTML/JS frontend. 证据：`examples/realtime/app/README.md`\n- **Realtime Twilio Integration**（documentation）：This example demonstrates how to connect the OpenAI Realtime API to a phone call using Twilio's Media Streams. The server handles incoming phone calls and streams audio between Twilio and the OpenAI Realtime API, enabling real-time voice conversations with an AI agent over the phone. 证据：`examples/realtime/twilio/README.md`\n- **Twilio SIP Realtime Example**（documentation）：This example shows how to handle OpenAI Realtime SIP calls with the Agents SDK. Incoming calls are accepted through the Realtime Calls API, a triage agent answers with a fixed greeting, and handoffs route the caller to specialist agents FAQ lookup and record updates similar to the realtime UI demo. 证据：`examples/realtime/twilio_sip/README.md`\n- **Research bot**（documentation）：This is a simple example of a multi-agent research bot. To run it: 证据：`examples/research_bot/README.md`\n- **Sandbox examples**（documentation）：These examples show how to run agents with an isolated workspace. Start with the small API examples when you want the smallest surface area, or use the tutorial scaffold when you want the shared layout for guided sandbox tutorials. 证据：`examples/sandbox/README.md`\n- **Cloud Sandbox Extension Examples**（documentation）：These examples are for manual verification of the cloud sandbox backends that live under agents.extensions.sandbox . 证据：`examples/sandbox/extensions/README.md`\n- **NASA Spending Text-to-SQL Agent**（documentation）：Multi-turn conversational agent that translates natural-language questions about NASA federal spending into SQL queries, executes them against a local SQLite database, and returns structured tabular results. 证据：`examples/sandbox/extensions/daytona/usaspending_text2sql/README.md`\n- **Temporal Sandbox Agent**（documentation）：A conversational coding agent that runs as a durable Temporal workflow with support for multiple sandbox backends Daytona, Docker, E2B, local unix . 证据：`examples/sandbox/extensions/temporal/README.md`\n- **Healthcare support**（documentation）：This example shows how to build a healthcare support workflow with Agents SDK using both standard agents and a sandbox agent. The scenario is intentionally synthetic and generic: a patient asks a billing or coverage question, the workflow checks local records, inspects policy documents in an isolated sandbox workspace, writes support artifacts, and optionally routes one ambiguous case to a human reviewer. 证据：`examples/sandbox/healthcare_support/README.md`\n- **Dataroom metric extract**（documentation）：Extract financial metrics from a synthetic 10-K packet, write the resulting table as CSV or JSONL, then validate the generated artifact with a deterministic eval script. 证据：`examples/sandbox/tutorials/dataroom_metric_extract/README.md`\n- **Dataroom Q&A**（documentation）：Answer grounded financial questions over a synthetic 10-K packet. 证据：`examples/sandbox/tutorials/dataroom_qa/README.md`\n- **Repo code review**（documentation）：Review a small public git repository, run its tests, leave line-level review comments in the structured output, and write a patch-oriented review artifact. 证据：`examples/sandbox/tutorials/repo_code_review/README.md`\n- **Sandbox resume**（documentation）：This example shows a small sandbox resume flow with AGENTS.md mounted in the sandbox and loaded into the agent instructions. It runs in two steps: first it builds the app and smoke tests it, then it serializes the sandbox session state, resumes the sandbox, and adds pytest coverage. 证据：`examples/sandbox/tutorials/sandbox_resume/README.md`\n- **Vision UI reproduction**（documentation）：Use the sandbox view image tool to inspect a reference app screenshot, then reproduce the visible screen as a static HTML/CSS artifact. This is a narrow UI repro target for vision and screenshot-debugging; it is not a web-app scaffold. 证据：`examples/sandbox/tutorials/vision_website_clone/README.md`\n- **Static voice demo**（documentation）：This demo operates by capturing a recording, then running a voice pipeline on it. 证据：`examples/voice/static/README.md`\n- **Streamed voice demo**（documentation）：This is an interactive demo, where you can talk to an Agent conversationally. It uses the voice pipeline's built in turn detection feature, so if you stop speaking the Agent responds. 证据：`examples/voice/streamed/README.md`\n- **Realtime**（documentation）：Realtime agents are in beta: expect some breaking changes over the next few weeks as we find issues and fix them. 证据：`src/agents/realtime/README.md`\n- **Code Change Verification**（skill_instruction）：Ensure work is only marked complete after formatting, linting, type checking, and tests pass. Use this skill when changes affect runtime code, tests, or build/test configuration. You can skip it for docs-only or repository metadata unless a user asks for the full stack. 证据：`.agents/skills/code-change-verification/SKILL.md`\n- **Docs Sync**（skill_instruction）：Identify doc coverage gaps and inaccuracies by comparing main branch features and configuration options against the current docs structure, then propose targeted improvements. 证据：`.agents/skills/docs-sync/SKILL.md`\n- **examples-auto-run**（skill_instruction）：- Runs uv run examples/run examples.py with: - Optional dependency extras enabled by default: litellm , any-llm , sqlalchemy , redis , blaxel , modal , runloop , and temporal . - EXAMPLES INTERACTIVE MODE=auto auto-input/auto-approve . - Per-example logs under .tmp/examples-start-logs/ . - Main summary log path passed via --main-log also under .tmp/examples-start-logs/ . - Generates a rerun list of failures at .tmp/examples-rerun.txt when --write-rerun is set. - Provides start/stop/status/logs/tail/collect/rerun helpers via run.sh . - Background option keeps the process running with a pidfile; stop cleans it up. 证据：`.agents/skills/examples-auto-run/SKILL.md`\n- **Final Release Review**（skill_instruction）：Use this skill when validating the latest release candidate commit default tip of origin/main for release. It guides you to fetch remote tags, pick the previous release tag, and thoroughly inspect the BASE TAG...TARGET diff for breaking changes, introduced bugs/regressions, improvement opportunities, and release risks. 证据：`.agents/skills/final-release-review/SKILL.md`\n- **Implementation Strategy**（skill_instruction）：Use this skill before editing code when the task changes runtime behavior or anything that might look like a compatibility concern. The goal is to keep implementations simple while protecting real released contracts. 证据：`.agents/skills/implementation-strategy/SKILL.md`\n- **OpenAI Knowledge**（skill_instruction）：Use the OpenAI Developer Documentation MCP server to search and fetch exact docs markdown , then base your answer on that text instead of guessing. 证据：`.agents/skills/openai-knowledge/SKILL.md`\n- **PR Draft Summary**（skill_instruction）：Purpose Produce the PR-ready summary required in this repository after substantive code work is complete: a concise summary plus a PR-ready title and draft description that begins with \"This pull request ...\". The block should be ready to paste into a PR for openai-agents-python. 证据：`.agents/skills/pr-draft-summary/SKILL.md`\n- **Runtime Behavior Probe**（skill_instruction）：Use this skill to investigate real runtime behavior, not to restate code or documentation. Start by planning the investigation, then execute a case matrix, record observed behavior, and report both the findings and the method used to obtain them. 证据：`.agents/skills/runtime-behavior-probe/SKILL.md`\n- **Prior Auth Packet Builder**（skill_instruction）：Use this skill when a case requires prior authorization review, referral validation, imaging review, or payer-specific policy checks. 证据：`examples/sandbox/healthcare_support/skills/prior-auth-packet-builder/SKILL.md`\n- **Playwright**（skill_instruction）：Use Playwright to capture the static site directly. Do not start a server for this example. 证据：`examples/sandbox/tutorials/vision_website_clone/skills/playwright/SKILL.md`\n- **CSV Workbench**（skill_instruction）：Use this skill when the user asks for quick analysis of tabular data. 证据：`examples/tools/skills/csv-workbench/SKILL.md`\n- **Test Coverage Improver**（skill_instruction）：Use this skill whenever coverage needs assessment or improvement coverage regressions, failing thresholds, or user requests for stronger tests . It runs the coverage suite, analyzes results, highlights the biggest gaps, and prepares test additions while confirming with the user before changing code. 证据：`.agents/skills/test-coverage-improver/SKILL.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Configuration**（documentation）：This page covers SDK-wide defaults that you usually set once during application startup, such as the default OpenAI key or client, the default OpenAI API shape, tracing export defaults, and logging behavior. 证据：`docs/config.md`\n- **Context management**（documentation）：Context is an overloaded term. There are two main classes of context you might care about: 证据：`docs/context.md`\n- **Examples**（documentation）：Check out a variety of sample implementations of the SDK in the examples section of the repo https://github.com/openai/openai-agents-python/tree/main/examples . The examples are organized into several categories that demonstrate different patterns and capabilities. 证据：`docs/examples.md`\n- **Guardrails**（documentation）：Guardrails enable you to do checks and validations of user input and agent output. For example, imagine you have an agent that uses a very smart and hence slow/expensive model to help with customer requests. You wouldn't want malicious users to ask the model to help them with their math homework. So, you can run a guardrail with a fast/cheap model. If the guardrail detects malicious usage, it can immediately raise an error and prevent the expensive model from running, saving you time and money when using blocking guardrails; for parallel guardrails, the expensive model may have already started running before the guardrail completes. See \"Execution modes\" below for details . 证据：`docs/guardrails.md`\n- **Handoffs**（documentation）：Handoffs allow an agent to delegate tasks to another agent. This is particularly useful in scenarios where different agents specialize in distinct areas. For example, a customer support app might have agents that each specifically handle tasks like order status, refunds, FAQs, etc. 证据：`docs/handoffs.md`\n- **Human-in-the-loop**（documentation）：Use the human-in-the-loop HITL flow to pause agent execution until a person approves or rejects sensitive tool calls. Tools declare when they need approval, run results surface pending approvals as interruptions, and RunState lets you serialize and resume runs after decisions are made. 证据：`docs/human_in_the_loop.md`\n- **OpenAI Agents SDK**（documentation）：The OpenAI Agents SDK https://github.com/openai/openai-agents-python enables you to build agentic AI apps in a lightweight, easy-to-use package with very few abstractions. It's a production-ready upgrade of our previous experimentation for agents, Swarm https://github.com/openai/swarm/tree/main . The Agents SDK has a very small set of primitives: 证据：`docs/index.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/agents.md`, `docs/ja/agents.md`, `docs/ko/agents.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/agents.md`, `docs/ja/agents.md`, `docs/ko/agents.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, pyproject.toml, src/agents/version.py\n- **快速开始指南**：importance `high`\n - source_paths: docs/quickstart.md, examples/basic/hello_world.py, examples/basic/hello_world_jupyter.ipynb\n- **核心概念**：importance `high`\n - source_paths: src/agents/agent.py, src/agents/tool.py, src/agents/guardrail.py, src/agents/handoffs/__init__.py, src/agents/items.py\n- **Agent 核心框架**：importance `high`\n - source_paths: src/agents/agent.py, src/agents/run.py, src/agents/run_config.py, src/agents/run_context.py, src/agents/run_state.py\n- **工具系统**：importance `high`\n - source_paths: src/agents/tool.py, src/agents/function_schema.py, src/agents/tool_context.py, src/agents/tool_guardrails.py, examples/basic/tools.py\n- **MCP 协议集成**：importance `medium`\n - source_paths: src/agents/mcp/manager.py, src/agents/mcp/server.py, src/agents/mcp/util.py, src/agents/_mcp_tool_metadata.py, examples/mcp\n- **Agent 转交机制**：importance `medium`\n - source_paths: src/agents/handoffs/__init__.py, src/agents/handoffs/history.py, src/agents/extensions/handoff_filters.py, src/agents/extensions/handoff_prompt.py, examples/handoffs/message_filter.py\n- **Guardrails 安全机制**：importance `medium`\n - source_paths: src/agents/guardrail.py, src/agents/tool_guardrails.py, src/agents/run_internal/guardrails.py, examples/agent_patterns/input_guardrails.py, examples/agent_patterns/output_guardrails.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `92e014a4cc4d3cbaac6934cd12af1b641f204ab4`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/tracing.md`, `docs/tools.md`, `docs/repl.md`, `docs/human_in_the_loop.md`, `docs/index.md`, `docs/context.md`, `docs/quickstart.md`, `docs/streaming.md`, `docs/usage.md`, `docs/multi_agent.md`, `docs/examples.md`, `docs/sandbox_agents.md`, `docs/results.md`, `docs/running_agents.md`, `docs/agents.md`, `docs/handoffs.md`, `docs/mcp.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `openai-agents-python` 与安装入口 `openai-agents` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:946380199 | https://github.com/openai/openai-agents-python | repo=openai-agents-python; install=openai-agents\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the base table\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the base table\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d867c75f80af49c9968398851ff8bf6a | https://github.com/openai/openai-agents-python/issues/3346 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Clarify whether retry-after delays should respect retry max_delay\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Clarify whether retry-after delays should respect retry max_delay\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_f486d2247bf24df8bbc7a2bd6fddbd65 | https://github.com/openai/openai-agents-python/issues/3266 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：OpenAIConversationsSession persists empty reasoning item {\"type\":\"reasoning\",\"summary\":[]} and Conversations API reject…\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenAIConversationsSession persists empty reasoning item {\"type\":\"reasoning\",\"summary\":[]} and Conversations API rejects it as invalid\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d6bad5c23bf3457eb546c22a1636cc26 | https://github.com/openai/openai-agents-python/issues/3268 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Tracing shutdown cannot interrupt exporter retry backoff\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Tracing shutdown cannot interrupt exporter retry backoff\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_e1ceae098cf84c8aafae7082b13c5345 | https://github.com/openai/openai-agents-python/issues/3354 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v0.15.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.15.2\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b73472b5ae90447199984775aacdca67 | https://github.com/openai/openai-agents-python/releases/tag/v0.15.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v0.15.3\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.15.3\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_7e05a382001a4d07b74eda1e1316320b | https://github.com/openai/openai-agents-python/releases/tag/v0.15.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v0.16.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.16.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_44335088ff52486e9f2f41f72a274c35 | https://github.com/openai/openai-agents-python/releases/tag/v0.16.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v0.17.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.17.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_86b81f310a6e45feadc65196a057b23b | https://github.com/openai/openai-agents-python/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：v0.15.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.15.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_4c70d563ac704aeaa14b8e2c49976bc5 | https://github.com/openai/openai-agents-python/releases/tag/v0.15.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：openai/openai-agents-python\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 是否匹配：chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 来源证据：AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the base table（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Clarify whether retry-after delays should respect retry max_delay（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：OpenAIConversationsSession persists empty reasoning item {\"type\":\"reasoning\",\"summary\":[]} and Conversations API reject…（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Tracing shutdown cannot interrupt exporter retry backoff（medium）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/openai/openai-agents-python 项目说明书\n\n生成时间：2026-05-11 16:45:26 UTC\n\n## 目录\n\n- [项目概述](#overview)\n- [快速开始指南](#quickstart)\n- [核心概念](#core-concepts)\n- [Agent 核心框架](#agent-core)\n- [工具系统](#tools)\n- [MCP 协议集成](#mcp)\n- [Agent 转交机制](#handoffs)\n- [Guardrails 安全机制](#guardrails)\n- [沙箱 Agent 概述](#sandbox-agent)\n- [沙箱会话管理](#sandbox-session)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[快速开始指南](#quickstart), [核心概念](#core-concepts)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/openai/openai-agents-python/blob/main/README.md)\n- [pyproject.toml](https://github.com/openai/openai-agents-python/blob/main/pyproject.toml)\n- [src/agents/version.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/version.py)\n- [examples/sandbox/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/README.md)\n- [examples/research_bot/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/research_bot/README.md)\n- [examples/mcp/tool_filter_example/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/mcp/tool_filter_example/README.md)\n \n\n# 项目概述\n\n## 项目简介\n\nOpenAI Agents Python SDK 是一个强大的 Python 多智能体（Multi-Agent）编排框架，专为构建复杂的人工智能工作流和应用而设计。该项目源自 OpenAI 的前沿研究成果，旨在为开发者提供一套完整的工具集，用于创建能够协同工作、共享信息、相互交接任务的智能代理系统。\n\n该框架的核心价值在于其灵活性和可扩展性。它不仅支持单代理执行，还支持多代理架构，其中多个专业化的代理可以并行或顺序执行任务，通过**交接（Handoff）机制**实现复杂的业务流程自动化。开发者可以轻松创建自定义代理、定义工具、设置审批流程，并将其部署到各种沙箱执行环境中。\n\n资料来源：[README.md]()\n\n## 核心架构\n\n### 系统组件\n\nOpenAI Agents Python SDK 的架构由以下几个核心组件构成：\n\n| 组件名称 | 功能描述 | 关键文件位置 |\n|---------|---------|------------|\n| **Runner** | 主运行引擎，负责协调代理执行流程 | `src/agents/run_internal/` |\n| **Agent** | 智能代理基类，封装LLM调用和工具管理 | `src/agents/agent.py` |\n| **Sandbox** | 隔离执行环境，提供安全的代码运行环境 | `src/agents/sandbox/` |\n| **Handoffs** | 代理间交接机制，支持任务传递 | `src/agents/handoffs/` |\n| **MCP Server** | Model Context Protocol 服务器集成 | `src/agents/mcp/server.py` |\n| **Tools** | 可扩展的工具系统，支持自定义工具 | `src/agents/tools/` |\n\n资料来源：[src/agents/run_internal/turn_resolution.py](), [src/agents/handoffs/history.py]()\n\n### 架构层次图\n\n```mermaid\ngraph TD\n A[用户应用层] --> B[Runner 执行引擎]\n B --> C[Agent 代理层]\n C --> D[工具系统 Tools]\n C --> E[交接系统 Handoffs]\n C --> F[MCP 协议层]\n D --> G[沙箱执行层 Sandbox]\n E --> C2[其他 Agent]\n G --> H[云端后端 E2B/Modal/Cloudflare...]\n F --> I[外部 MCP 服务]\n```\n\n## 关键特性\n\n### 1. 智能代理系统\n\n代理（Agent）是框架的核心执行单元。每个代理包含：\n\n- **系统提示词**：定义代理的角色和行为\n- **工具集**：代理可调用的功能函数\n- **交接配置**：与其他代理的协作关系\n- **输出格式**：响应数据的结构定义\n\n代理通过 `Runner` 统一调度，支持流式输出、增量响应和完整的结果返回。\n\n### 2. 沙箱执行环境\n\n框架提供了强大的沙箱（Sandbox）功能，用于隔离执行代码和敏感操作：\n\n```mermaid\ngraph LR\n A[Manifest 定义] --> B[沙箱会话创建]\n B --> C[工作空间初始化]\n C --> D[工具执行]\n D --> E[结果收集]\n E --> F[会话结束/快照保存]\n```\n\n支持的沙箱后端包括：\n\n| 后端名称 | 特点 | 典型用例 |\n|---------|------|---------|\n| **E2B** | 通用 bash 环境 | 通用代码执行 |\n| **Modal** | Serverless 计算 | 长时间运行任务 |\n| **Cloudflare** | 边缘计算 | 低延迟应用 |\n| **Daytona** | 容器化执行 | 隔离测试环境 |\n| **Vercel** | 云函数集成 | 快速部署 |\n| **Blaxel** | 云存储挂载 | 数据密集型任务 |\n\n资料来源：[examples/sandbox/README.md](), [examples/sandbox/extensions/README.md]()\n\n### 3. 多代理协作与交接\n\n交接（Handoff）机制允许代理之间传递控制权和上下文信息：\n\n- **顺序交接**：一个代理完成后将任务交给下一个代理\n- **并行执行**：多个代理同时处理不同子任务\n- **上下文继承**：交接时自动传递对话历史和状态\n\n```python\n# 典型的交接流程\nagent_a -> (handoff) -> agent_b -> (handoff) -> agent_c\n```\n\n资料来源：[src/agents/handoffs/history.py]()\n\n### 4. MCP 协议支持\n\n框架完整支持 Model Context Protocol (MCP)，允许代理与外部 MCP 服务器通信：\n\n- 资源管理（Resources）\n- 工具调用（Tools）\n- 提示模板（Prompts）\n- 资源模板（Resource Templates）\n\n资料来源：[src/agents/mcp/server.py]()\n\n### 5. 人机协作与审批\n\n框架内置了完善的人工介入（Human-in-the-Loop）机制：\n\n- **审批门控**：代理在执行敏感操作前等待人工批准\n- **中断恢复**：人工审批后可从中断点恢复执行\n- **自动模式**：支持无干预的自动化运行\n\n资料来源：[examples/mcp/tool_filter_example/README.md]()\n\n## 应用场景\n\n### 研究助手\n\n框架可用于构建复杂的研究代理系统：\n\n```mermaid\ngraph TD\n A[用户输入研究主题] --> B[规划代理 Planner]\n B --> C{搜索查询列表}\n C --> D[搜索代理 1]\n C --> E[搜索代理 2]\n C --> F[搜索代理 N]\n D --> G[汇总代理 Writer]\n E --> G\n F --> G\n G --> H[最终研究报告]\n```\n\n资料来源：[examples/research_bot/README.md]()\n\n### 金融研究代理\n\n专业化的金融分析工作流，包括：\n\n- 财务数据分析\n- 风险评估分析\n- 基础面分析\n- 投资报告生成\n\n资料来源：[examples/financial_research_agent/README.md]()\n\n### 医疗支持系统\n\n复杂的医疗信息查询和验证系统，支持：\n\n- 保险福利查询\n- 先前授权检查\n- 医疗政策分析\n- 记忆回顾机制\n\n资料来源：[examples/sandbox/healthcare_support/README.md]()\n\n## 快速开始\n\n### 环境要求\n\n- Python 3.10+\n- OpenAI API Key\n\n### 安装方式\n\n```bash\n# 基础安装\nuv sync\n\n# 包含可选依赖的完整安装\nuv sync --extra blaxel --extra modal --extra vercel\n```\n\n### 基本使用示例\n\n```python\nfrom agents import Agent, Runner\n\nagent = Agent(name=\"助手\", instructions=\"你是一个有帮助的助手\")\n\nresult = Runner.run_sync(agent, \"你好，请介绍一下你自己\")\nprint(result.final_output)\n```\n\n资料来源：[pyproject.toml]()\n\n## 项目结构\n\n```\nopenai-agents-python/\n├── src/agents/ # 核心源代码\n│ ├── agent.py # 代理基类\n│ ├── runner.py # 执行引擎\n│ ├── handoffs/ # 交接系统\n│ ├── sandbox/ # 沙箱实现\n│ ├── mcp/ # MCP 协议支持\n│ └── tools/ # 工具系统\n├── examples/ # 示例应用\n│ ├── sandbox/ # 沙箱示例\n│ ├── research_bot/ # 研究代理示例\n│ └── mcp/ # MCP 使用示例\n└── README.md # 项目文档\n```\n\n## 版本信息\n\n当前版本定义在 `src/agents/version.py` 中，采用语义化版本管理。\n\n资料来源：[src/agents/version.py]()\n\n## 总结\n\nOpenAI Agents Python SDK 代表了现代 AI 应用开发的新范式。它通过提供：\n\n- **统一的代理抽象**：简化复杂 AI 工作流的构建\n- **灵活的沙箱执行**：确保代码安全隔离运行\n- **强大的协作机制**：支持多代理并行和顺序执行\n- **完善的协议支持**：无缝集成 MCP 等开放标准\n\n使开发者能够快速构建生产级别的人工智能应用，无论是简单的问答系统还是复杂的企业级工作流自动化。\n\n资料来源：[README.md](), [examples/sandbox/README.md]()\n\n---\n\n\n\n## 快速开始指南\n\n### 相关页面\n\n相关主题：[项目概述](#overview), [Agent 核心框架](#agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/sandbox/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/README.md)\n- [examples/research_bot/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/research_bot/README.md)\n- [examples/mcp/streamable_http_remote_example/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/mcp/streamable_http_remote_example/README.md)\n- [examples/mcp/tool_filter_example/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/mcp/tool_filter_example/README.md)\n- [examples/model_providers/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/model_providers/README.md)\n- [examples/sandbox/healthcare_support/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/healthcare_support/README.md)\n \n\n# 快速开始指南\n\n## 概述\n\n快速开始指南旨在帮助开发者快速上手 OpenAI Agents Python SDK，掌握核心概念和基础用法。通过本指南，您将了解如何安装 SDK、创建代理（Agent）、配置工具、执行运行流程，以及运行各种示例代码。\n\n本指南覆盖以下主要内容：\n\n- 环境准备与安装\n- 核心概念与架构\n- 基本使用流程\n- 示例代码运行指南\n\n资料来源：[examples/sandbox/README.md:1-15]()\n\n## 环境准备\n\n### 系统要求\n\n| 要求项 | 说明 |\n|--------|------|\n| Python 版本 | 3.12 及以上 |\n| 包管理器 | uv 或 pip |\n| 网络要求 | 能够访问 OpenAI API |\n\n### 安装步骤\n\n使用 `uv` 安装 SDK 及其依赖：\n\n```bash\nuv pip install openai-agents\n```\n\n安装特定扩展功能（如需要）：\n\n```bash\nuv sync --extra e2b # E2B 沙箱支持\nuv sync --extra modal # Modal 后端支持\nuv sync --extra blaxel # Blaxel 沙箱支持\nuv sync --extra vercel # Vercel 后端支持\nuv sync --extra daytona # Daytona 后端支持\nuv sync --extra runloop # Runloop 后端支持\n```\n\n### 环境变量配置\n\n设置 OpenAI API 密钥：\n\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\n```\n\n对于其他后端服务，需要额外配置相应的 API 密钥：\n\n| 后端服务 | 环境变量 |\n|----------|----------|\n| Blaxel | `BL_API_KEY`, `BL_WORKSPACE` |\n| Vercel | `VERCEL_OIDC_TOKEN` 或 `VERCEL_TOKEN`, `VERCEL_PROJECT_ID`, `VERCEL_TEAM_ID` |\n| Daytona | `DAYTONA_API_KEY` |\n| E2B | `E2B_API_KEY` |\n| Modal | `MODAL_TOKEN_ID`, `MODAL_TOKEN_SECRET` |\n| Runloop | 需在 platform.runloop.ai 注册 |\n\n资料来源：[examples/sandbox/extensions/README.md:1-50]()\n资料来源：[examples/sandbox/extensions/blaxel/README.md:1-20]()\n\n## 核心概念\n\n### 代理（Agent）\n\n代理是能够执行特定任务的 AI 实体。每个代理具有：\n\n- **名称与指令**：定义代理的角色和行为\n- **工具能力**：代理可调用的功能\n- **模型配置**：使用的语言模型\n\n### Runner 执行器\n\n`Runner` 是 SDK 的核心执行组件，负责：\n\n1. 管理代理的生命周期\n2. 处理工具调用循环\n3. 维护对话状态\n4. 返回最终结果\n\n### 工具（Tools）\n\n工具允许代理与外部系统交互，包括：\n\n- **内置工具**：文件搜索、代码执行等\n- **MCP 工具**：通过 Model Context Protocol 扩展\n- **自定义工具**：用户定义的函数\n\n资料来源：[examples/research_bot/README.md:1-30]()\n\n## 基础使用流程\n\n### 流程图\n\n```mermaid\ngraph TD\n A[初始化 Runner] --> B[创建 Agent]\n B --> C[配置 Tools]\n C --> D[设置 RunConfig]\n D --> E[执行 run 方法]\n E --> F{是否需要工具调用}\n F -->|是| G[执行工具]\n G --> E\n F -->|否| H[返回结果]\n H --> I[输出最终响应]\n```\n\n### 基础代码示例\n\n#### 步骤一：导入依赖\n\n```python\nfrom agents import Agent, Runner\nfrom agents.mcp import MCPServer\n```\n\n#### 步骤二：创建代理\n\n```python\nagent = Agent(\n name=\"研究助手\",\n instructions=\"你是一个专业的金融分析师，帮助用户研究市场趋势。\",\n model=\"gpt-4o\"\n)\n```\n\n#### 步骤三：执行运行\n\n```python\nresult = await Runner.run(\n agent,\n input=\"分析当前科技行业的发展趋势\"\n)\nprint(result.final_output)\n```\n\n资料来源：[examples/research_bot/README.md:15-25]()\n\n## 示例代码指南\n\n### 沙箱示例\n\nSDK 提供了多种沙箱执行环境的示例，位于 `examples/sandbox/` 目录下。\n\n#### 小型 API 示例\n\n| 示例文件 | 功能说明 | 运行命令 |\n|----------|----------|----------|\n| `basic.py` | 创建沙箱会话，运行 SandboxAgent，流式输出结果 | `uv run python examples/sandbox/basic.py` |\n| `handoffs.py` | 代理之间的交接功能 | `uv run python examples/sandbox/handoffs.py` |\n| `sandbox_agent_capabilities.py` | 配置沙箱代理的工作区能力 | `uv run python examples/sandbox/sandbox_agent_capabilities.py` |\n| `sandbox_agent_with_tools.py` | 组合沙箱能力与主机定义工具 | `uv run python examples/sandbox/sandbox_agent_with_tools.py` |\n| `sandbox_agents_as_tools.py` | 将沙箱代理作为工具暴露给其他代理 | `uv run python examples/sandbox/sandbox_agents_as_tools.py` |\n\n#### 扩展后端示例\n\n扩展示例支持多种后端执行环境：\n\n- **E2B**：提供 bash 风格接口（默认）或 Jupyter 风格接口（`e2b_code_interpreter`）\n- **Modal**：支持多种工作区持久化方式（tar、snapshot_filesystem、snapshot_directory）\n- **Blaxel**：支持 PTY 驱动的交互式 Python 会话和 Drive 挂载\n- **Vercel**：非 PTY 路径，支持命令执行和工作区物化\n- **Daytona**：轻量级沙箱执行\n- **Runloop**：云端沙箱服务\n\n资料来源：[examples/sandbox/README.md:20-45]()\n资料来源：[examples/sandbox/extensions/README.md:1-80]()\n\n### 多代理研究机器人\n\n研究机器人示例展示了多代理协作的工作流程：\n\n```mermaid\ngraph LR\n A[用户输入研究主题] --> B[Planner Agent 制定搜索计划]\n B --> C[多个 Search Agent 并行搜索]\n C --> D[Writer Agent 综合撰写报告]\n D --> E[输出研究报告]\n```\n\n运行命令：\n\n```bash\npython -m examples.research_bot.main\n```\n\n资料来源：[examples/research_bot/README.md:1-35]()\n\n### MCP 示例\n\n#### MCP 工具过滤示例\n\n展示如何：\n\n- 本地运行文件系统 MCP 服务器（通过 `npx`）\n- 应用静态工具过滤，暴露特定工具\n- 启用强制批准模式测试人机交互路径\n\n运行命令：\n\n```bash\nuv run python examples/mcp/tool_filter_example/main.py\n```\n\n前置条件：\n\n- `npx` 可用\n- `OPENAI_API_KEY` 已配置\n\n#### 流式 HTTP 远程示例\n\n连接 DeepWiki 的 MCP 服务，使用流式 HTTP 传输协议：\n\n```bash\nuv run python examples/mcp/streamable_http_remote_example/main.py\n```\n\n资料来源：[examples/mcp/tool_filter_example/README.md:1-25]()\n资料来源：[examples/mcp/streamable_http_remote_example/README.md:1-20]()\n\n### 模型提供者示例\n\n支持通过适配器层路由模型请求，默认使用 OpenRouter：\n\n```bash\nexport OPENROUTER_API_KEY=\"...\"\nuv run examples/model_providers/any_llm_provider.py\nuv run examples/model_providers/any_llm_auto.py\nuv run examples/model_providers/litellm_provider.py\nuv run examples/model_providers/litellm_auto.py\n```\n\n自定义模型：\n\n```bash\nuv run examples/model_providers/any_llm_provider.py --model openrouter/openai/gpt-5.4-mini\n```\n\n资料来源：[examples/model_providers/README.md:1-25]()\n\n## 医疗支持示例\n\n医疗支持演示工作流展示了复杂的人机协作场景：\n\n### 核心文件结构\n\n| 文件 | 职责 |\n|------|------|\n| `main.py` | CLI 演示入口 |\n| `workflow.py` | 共享工作流执行逻辑、沙箱设置、追踪、批准恢复循环 |\n| `support_agents.py` | 定义协调器、福利子代理、沙箱策略代理、记忆摘要代理 |\n| `tools.py` | 本地查询工具和批准门控人工交接工具 |\n| `skills/prior-auth-packet-builder/SKILL.md` | 运行时加载的沙箱技能 |\n\n### 运行方式\n\n```bash\nuv run python examples/sandbox/healthcare_support/main.py --list-scenarios\nuv run python examples/sandbox/healthcare_support/main.py --scenario blue_cross_pt_benefits\nuv run python examples/sandbox/healthcare_support/main.py --scenario messy_ambiguous_knee_case\nuv run python examples/sandbox/healthcare_support/main.py --reset-memory\n```\n\n非交互模式运行：\n\n```bash\nEXAMPLES_INTERACTIVE_MODE=auto uv run python examples/sandbox/healthcare_support/main.py --scenario messy_ambiguous_knee_case\n```\n\n资料来源：[examples/sandbox/healthcare_support/README.md:1-40]()\n\n## 常用配置选项\n\n### RunConfig 配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | str | \"gpt-4o\" | 使用的语言模型 |\n| `temperature` | float | 0.7 | 生成温度参数 |\n| `max_tokens` | int | None | 最大输出令牌数 |\n| `tools` | list | [] | 代理可用工具列表 |\n| `tool_override` | list | None | 覆盖默认工具 |\n| `tracing_disabled` | bool | False | 是否禁用追踪 |\n| `stream_intermediate_steps` | bool | True | 是否流式输出中间步骤 |\n\n### 沙箱配置选项\n\n不同后端支持特定的配置参数：\n\n- **E2B**：`--template`, `--timeout`\n- **Modal**：`--workspace-persistence`, `--sandbox-create-timeout-s`\n- **Blaxel**：`--image`, `--region`, `--memory`, `--ttl`, `--pause-on-exit`\n- **Vercel**：`--runtime`, `--timeout-ms`\n\n资料来源：[examples/sandbox/extensions/README.md:80-120]()\n\n## 最佳实践\n\n### 环境隔离\n\n- 生产环境建议使用沙箱执行代码，避免安全风险\n- 使用快照（Snapshot）功能实现工作区持久化\n- 为不同任务配置独立的沙箱环境\n\n### 错误处理\n\nSDK 在检测到异常情况时会抛出特定错误类：\n\n| 错误类型 | 触发条件 |\n|----------|----------|\n| `InvalidManifestPathError` | 清单路径无效（exit_code=111） |\n| `WorkspaceArchiveWriteError` | 工作区归档写入失败（exit_code=114） |\n| `ExecNonZeroError` | 命令执行返回非零退出码 |\n\n### 调试技巧\n\n1. 启用流式中间步骤输出，监控代理行为\n2. 使用 `tracing_disabled=False` 保留追踪记录\n3. 结合 Temporal 等工具进行分布式追踪\n\n资料来源：[src/agents/sandbox/session/base_sandbox_session.py:40-80]()\n\n## 下一步\n\n完成快速开始指南后，建议继续探索：\n\n- **高级代理配置**：学习如何构建复杂的多代理系统\n- **工具开发**：创建自定义工具扩展代理能力\n- **MCP 集成**：连接更多外部服务\n- **沙箱高级功能**：深入了解各种沙箱后端的特性和配置\n- **生产部署**：了解在生产环境中运行代理的最佳实践\n\n---\n\n\n\n## 核心概念\n\n### 相关页面\n\n相关主题：[Agent 核心框架](#agent-core), [工具系统](#tools), [Agent 转交机制](#handoffs)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/agent.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py)\n- [src/agents/tool.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool.py)\n- [src/agents/guardrail.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/guardrail.py)\n- [src/agents/handoffs/__init__.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/handoffs/__init__.py)\n- [src/agents/items.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/items.py)\n- [src/agents/result.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/result.py)\n \n\n# 核心概念\n\n本文档介绍 openai-agents-python 项目中的核心概念与架构组件。该项目是一个用于构建 AI Agent 系统的 Python 框架，提供了 Agent、Tool、Handoff、Guardrail 等核心抽象，使开发者能够构建复杂的多代理协作应用。\n\n## 1. Agent（代理）\n\nAgent 是整个系统的核心执行单元，代表一个能够接收输入、执行任务并返回结果的 AI 实体。\n\n### 1.1 Agent 的定义与组成\n\n一个 Agent 主要由以下几个部分构成：\n\n| 组件 | 说明 | 资料来源 |\n|------|------|---------|\n| name | Agent 的唯一标识名称 | src/agents/agent.py |\n| instructions | 给 Agent 的系统指令/提示词 | src/agents/agent.py |\n| tools | Agent 可调用的工具列表 | src/agents/agent.py |\n| handoffs | Agent 可转交到的其他 Agent | src/agents/agent.py |\n| input_guardrails | 输入护栏 | src/agents/guardrail.py |\n| output_guardrails | 输出护栏 | src/agents/guardrail.py |\n\n### 1.2 Agent 架构图\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Agent]\n B --> C{指令解析}\n C -->|执行工具| D[Tools]\n C -->|转交代理| E[Handoffs]\n C -->|安全检查| F[Guardrails]\n D --> G[工具执行结果]\n E --> H[目标Agent]\n F --> I{检查通过?}\n I -->|是| G\n I -->|否| J[拒绝/过滤]\n G --> K[响应输出]\n H --> B\n J --> K\n```\n\n### 1.3 Agent 的核心职责\n\nAgent 在系统中承担以下核心职责：\n\n1. **指令解析**：解析用户输入并理解任务意图\n2. **工具调用**：根据任务需要调用适当的工具\n3. **代理转交**：在多代理场景下，将任务转交给其他专业 Agent\n4. **结果生成**：综合工具执行结果生成最终响应\n\n```python\n# Agent 的基本定义结构示例\nagent = Agent(\n name=\"assistant\",\n instructions=\"你是一个有用的助手\",\n tools=[search_tool, calculator_tool],\n handoffs=[specialist_agent],\n output_guardrails=[content_filter]\n)\n```\n\n## 2. Tool（工具）\n\nTool 是 Agent 与外部世界交互的桥梁，允许 Agent 执行特定的操作如搜索、计算、文件处理等。\n\n### 2.1 Tool 的类型\n\n| 工具类型 | 用途 | 典型应用场景 |\n|----------|------|-------------|\n| FunctionTool | 封装 Python 函数 | 数据处理、计算 |\n| MCPTool | MCP 协议工具 | 与外部服务集成 |\n| SandboxedTool | 沙箱环境工具 | 安全执行代码 |\n\n### 2.2 Tool 的定义\n\n```python\n# Tool 的基本结构\ntool = Tool(\n name=\"search\",\n description=\"搜索网络信息\",\n parameters={...}, # 工具参数定义\n handler=async def search(query): ...\n)\n```\n\n### 2.3 Tool 执行流程\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Tool\n participant External\n Agent->>Tool: 调用工具\n Tool->>Tool: 参数验证\n Tool->>External: 执行外部操作\n External-->>Tool: 返回结果\n Tool->>Tool: 结果格式化\n Tool-->>Agent: 返回处理结果\n```\n\n## 3. Handoff（代理转交）\n\nHandoff 是一种在多个 Agent 之间传递对话控制权的机制，是构建多代理系统的关键特性。\n\n### 3.1 Handoff 的工作原理\n\nHandoff 允许一个 Agent 将当前对话上下文转交给另一个 Agent，实现专业分工和任务分解。资料来源：[src/agents/handoffs/__init__.py]()\n\n```mermaid\ngraph LR\n A[用户] -->|输入| B[主Agent]\n B -->|转交| C[研究Agent]\n B -->|转交| D[写作Agent]\n C -->|结果| B\n D -->|结果| B\n B -->|最终输出| A\n```\n\n### 3.2 Handoff 的配置选项\n\n| 选项 | 说明 | 必填 |\n|------|------|------|\n| agent | 目标 Agent 对象 | 是 |\n| agent_name | 目标 Agent 名称 | 是 |\n| tool_name | 触发转交的调用名 | 否 |\n| description | 转交描述 | 否 |\n| on_invoke | 转交触发回调 | 否 |\n\n### 3.3 Handoff 与历史记录\n\n系统在转交时会自动处理对话历史，确保新 Agent 能够获取完整的上下文信息：\n\n```python\n# Handoff 会自动传递：\n# - 原始用户输入\n# - 当前对话历史\n# - 之前 Agent 的分析结果\n# - 工具执行结果\n```\n\n## 4. Guardrail（护栏）\n\nGuardrail 是一种安全机制，用于在 Agent 执行过程中对输入和输出进行验证和过滤。\n\n### 4.1 Guardrail 的类型\n\n| 类型 | 作用位置 | 用途 |\n|------|----------|------|\n| input_guardrail | 工具执行前 | 验证用户输入安全性 |\n| output_guardrail | 响应生成后 | 过滤敏感输出内容 |\n| tool_input_guardrail | 工具参数传入前 | 验证工具参数 |\n| tool_output_guardrail | 工具执行完成后 | 检查工具返回结果 |\n\n### 4.2 Guardrail 执行流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Input Guardrail]\n B --> C{验证通过?}\n C -->|是| D[Agent 处理]\n C -->|否| E[拒绝请求]\n D --> F[工具调用]\n F --> G[Tool Output Guardrail]\n G --> H{检查通过?}\n H -->|是| I[Agent 生成响应]\n H -->|否| J[过滤/阻断]\n I --> K[Output Guardrail]\n K --> L{通过?}\n L -->|是| M[返回结果]\n L -->|否| N[内容过滤]\n```\n\n### 4.3 Guardrail 配置示例\n\n```python\n# Guardrail 配置结构\nguardrail = Guardrail(\n name=\"content_filter\",\n description=\"过滤不当内容\",\n validator=async def check_content(ctx, result): ...\n)\n```\n\n## 5. Item（消息项）\n\nItem 是对话系统中表示各种消息和事件的标准化数据结构。\n\n### 5.1 Item 的类型\n\n| 类型 | 说明 | 资料来源 |\n|------|------|---------|\n| MessageOutputItem | 模型生成的消息 | src/agents/items.py |\n| ToolCallItem | 工具调用请求 | src/agents/items.py |\n| ToolCallOutputItem | 工具执行结果 | src/agents/items.py |\n| HandoffItem | 代理转交事件 | src/agents/items.py |\n| GuardrailResultItem | 护栏检查结果 | src/agents/items.py |\n\n### 5.2 Item 层次结构\n\n```mermaid\ngraph TD\n A[Item 基类]\n A --> B[MessageOutputItem]\n A --> C[ToolCallItem]\n A --> D[HandoffItem]\n A --> E[GuardrailResultItem]\n C --> F[ToolCallOutputItem]\n```\n\n## 6. Result（结果）\n\nResult 是 Agent 执行完成后返回给调用者的数据结构，包含完整的执行信息。\n\n### 6.1 Result 结构\n\n| 字段 | 说明 |\n|------|------|\n| final_output | 最终输出文本 |\n| items | 执行过程中的所有 Item 列表 |\n| last_agent | 最后执行的 Agent 信息 |\n| raw_responses | 原始模型响应 |\n| handoff_history | 转交历史记录 |\n\n### 6.2 Result 生成流程\n\n```mermaid\ngraph TD\n A[Agent 执行] --> B[收集 Items]\n B --> C[生成响应]\n C --> D[护栏检查]\n D --> E{检查结果}\n E -->|通过| F[构建 Result]\n E -->|失败| G[返回错误]\n F --> H[返回 Result]\n```\n\n## 7. 核心概念协作关系\n\n### 7.1 完整执行流程\n\n```mermaid\ngraph TD\n subgraph 输入处理\n A[用户输入] --> B[Input Guardrail]\n B --> C[Agent]\n end\n \n subgraph 执行阶段\n C --> D{需要工具?}\n D -->|是| E[Tool Call]\n D -->|否| F{需要转交?}\n E --> G[Tool Output Guardrail]\n G --> H[结果处理]\n F -->|是| I[Handoff]\n F -->|否| J[生成响应]\n end\n \n subgraph 输出处理\n H --> J\n J --> K[Output Guardrail]\n K --> L[Result]\n end\n \n I --> C\n```\n\n### 7.2 组件交互总结\n\n| 交互关系 | 说明 |\n|----------|------|\n| Agent → Tool | Agent 调用工具执行具体操作 |\n| Agent → Handoff | Agent 将任务转交给其他专业 Agent |\n| Tool → Guardrail | 工具执行结果需要通过护栏检查 |\n| Handoff → Item | 转交事件记录为 HandoffItem |\n| Result → Items | 最终结果汇总所有执行过程中的 Item |\n\n## 8. 最佳实践\n\n### 8.1 Agent 设计原则\n\n1. **单一职责**：每个 Agent 应专注于特定领域\n2. **清晰指令**：提供明确、详细的 instructions\n3. **适当工具**：只提供任务所需的最小工具集\n4. **合理护栏**：根据安全性需求配置适当的护栏\n\n### 8.2 Tool 开发规范\n\n1. **清晰描述**：提供准确的 tool description\n2. **参数验证**：实现严格的输入参数验证\n3. **错误处理**：优雅处理执行中的异常\n4. **结果格式化**：返回结构化的执行结果\n\n### 8.3 Handoff 使用建议\n\n1. **明确转交条件**：在 instructions 中说明何时应该转交\n2. **保持上下文**：利用 Handoff 自动传递历史记录的特性\n3. **避免循环**：防止 Agent 之间形成死循环转交\n\n## 9. 相关资源\n\n- [Agent 完整文档](../agents/agent.md)\n- [Tool 使用指南](../tools/tool.md)\n- [Handoff 机制详解](../handoffs/handoff.md)\n- [Guardrail 配置参考](../guardrails/guardrail.md)\n- [示例代码](../examples/)\n\n---\n\n\n\n## Agent 核心框架\n\n### 相关页面\n\n相关主题：[工具系统](#tools), [Agent 转交机制](#handoffs)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/agent.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py)\n- [src/agents/run.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/run.py)\n- [src/agents/run_config.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_config.py)\n- [src/agents/run_context.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_context.py)\n- [src/agents/run_state.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_state.py)\n- [src/agents/lifecycle.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/lifecycle.py)\n- [src/agents/stream_events.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/stream_events.py)\n \n\n# Agent 核心框架\n\n## 概述\n\nAgent 核心框架是 openai-agents-python 项目的核心组成部分，负责管理 AI Agent 的创建、配置、执行和生命周期管理。该框架提供了一套完整的抽象，使开发者能够轻松构建多代理系统，处理任务编排、工具调用、代理间交接（handoff）等复杂场景。\n\n核心框架主要由以下几个模块组成：\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| Agent | `src/agents/agent.py` | 定义代理的行为和配置 |\n| Runner | `src/agents/run.py` | 执行代理任务的主入口 |\n| RunConfig | `src/agents/run_config.py` | 运行时的配置参数 |\n| RunContext | `src/agents/run_context.py` | 执行上下文管理 |\n| RunState | `src/agents/run_state.py` | 运行时状态追踪 |\n| Lifecycle | `src/agents/lifecycle.py` | 生命周期钩子管理 |\n| StreamEvents | `src/agents/stream_events.py` | 事件流式输出 |\n\n资料来源：[src/agents/agent.py:1-50](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py)\n\n## 架构图\n\n以下 Mermaid 图展示了 Agent 核心框架的整体架构：\n\n```mermaid\ngraph TD\n subgraph 核心组件\n A[Agent] --> B[Runner]\n B --> C[RunConfig]\n B --> D[RunContext]\n B --> E[RunState]\n B --> F[Lifecycle]\n B --> G[StreamEvents]\n end\n \n subgraph 执行层\n B --> H[模型调用]\n B --> I[工具执行]\n B --> J[代理交接]\n end\n \n subgraph 上下文\n D --> K[输入历史]\n D --> L[工具结果]\n D --> M[运行时数据]\n end\n```\n\n## Agent 类\n\n### 类的定义与核心属性\n\n`Agent` 类是框架的核心抽象，封装了代理的名称、模型配置、指令、工具集等关键属性。\n\n```python\nclass Agent:\n def __init__(\n self,\n name: str,\n instructions: str | Callable | None = None,\n model: str | Model = \"gpt-4o\",\n tools: list[Tool] | None = None,\n handoffs: list[Handoff | Agent] | None = None,\n input_guardrails: list[InputGuardrail] | None = None,\n output_guardrails: list[OutputGuardrail] | None = None,\n tool_validator: ToolValidator | None = None,\n response_format: type[BaseModel] | None = None,\n )\n```\n\n**核心属性说明：**\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `name` | `str` | 代理的唯一标识名称 |\n| `instructions` | `str \\| Callable \\| None` | 代理的系统指令 |\n| `model` | `str \\| Model` | 使用的模型名称或对象 |\n| `tools` | `list[Tool] \\| None` | 代理可用的工具列表 |\n| `handoffs` | `list[Handoff \\| Agent] \\| None` | 可交接给其他代理的配置 |\n| `input_guardrails` | `list[InputGuardrail] \\| None` | 输入验证器 |\n| `output_guardrails` | `list[OutputGuardrail] \\| None` | 输出验证器 |\n\n资料来源：[src/agents/agent.py:50-100](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py)\n\n### 代理指令处理\n\n代理的 `instructions` 属性支持多种形式：\n\n1. **静态字符串**：直接提供系统提示\n2. **可调用函数**：动态生成指令，支持根据上下文信息生成个性化指令\n3. **None**：使用默认指令\n\n```python\n# 静态字符串示例\nagent = Agent(name=\"分析师\", instructions=\"你是一个专业的数据分析师\")\n\n# 动态指令示例\ndef dynamic_instructions(ctx: RunContextWrapper, agent: Agent) -> str:\n user_preference = ctx.get(\"user_preference\", \"默认\")\n return f\"用户偏好：{user_preference}\"\n\nagent = Agent(name=\"个性化助手\", instructions=dynamic_instructions)\n```\n\n资料来源：[src/agents/agent.py:100-150](https://github.com/openai/openai-agents-python/blob/main/src/agents/agent.py)\n\n## Runner 执行器\n\n### Runner 概述\n\n`Runner` 是执行代理任务的主入口类，负责协调整个执行流程。\n\n```python\nclass Runner:\n @staticmethod\n async def run(\n agent: Agent,\n input: str | list[Message] | list[ToolResult],\n *,\n context: dict[str, Any] | None = None,\n max_steps: int = 150,\n config: RunConfig | None = None,\n ) -> FinalOutput\n```\n\n### 异步执行流程\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant Runner\n participant Agent\n participant 工具\n participant 模型\n \n 用户->>Runner: run(agent, input)\n Runner->>RunContext: 创建上下文\n Runner->>Agent: 执行指令\n Agent->>模型: 生成响应\n 循环 while 需要工具调用\n 模型->>工具: 调用工具\n 工具-->>模型: 返回结果\n end\n 模型-->>Runner: 最终输出\n Runner-->>用户: FinalOutput\n```\n\n### 核心执行方法\n\nRunner 提供了多个静态方法用于不同场景：\n\n| 方法 | 说明 | 使用场景 |\n|------|------|----------|\n| `run()` | 标准异步执行 | 大多数场景 |\n| `run_single_agent()` | 单代理快速执行 | 简单任务 |\n| `run_concurrently()` | 并发执行多个代理 | 批量处理 |\n| `run_stream_events()` | 流式事件输出 | 实时展示 |\n\n资料来源：[src/agents/run.py:50-200](https://github.com/openai/openai-agents-python/blob/main/src/agents/run.py)\n\n## RunConfig 配置\n\n### 配置参数详解\n\n`RunConfig` 类封装了运行时的所有配置选项：\n\n```python\nclass RunConfig(BaseModel):\n model: str = \"gpt-4o\"\n model_provider: str = \"openai\"\n max_tokens: int | None = 16384\n temperature: float = 1.0\n top_p: float | None = None\n stop: str | list[str] | None = None\n stream: bool = False\n stream_intermediate_steps: bool = False\n parallel_tool_calls: bool = True\n max_parallel_tool_calls: int | None = None\n tracing: TracingExportType | TracingDisabledReason | None = None\n```\n\n**配置参数说明：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | `str` | `\"gpt-4o\"` | 模型名称 |\n| `model_provider` | `str` | `\"openai\"` | 模型提供商 |\n| `max_tokens` | `int \\| None` | `16384` | 最大输出 token 数 |\n| `temperature` | `float` | `1.0` | 采样温度 |\n| `top_p` | `float \\| None` | `None` | Nucleus 采样参数 |\n| `stop` | `str \\| list[str]` | `None` | 停止序列 |\n| `stream` | `bool` | `False` | 是否启用流式输出 |\n| `parallel_tool_calls` | `bool` | `True` | 是否并行执行工具调用 |\n| `max_parallel_tool_calls` | `int \\| None` | `None` | 最大并行工具调用数 |\n| `tracing` | `TracingExportType \\| None` | `None` | 追踪导出配置 |\n\n资料来源：[src/agents/run_config.py:30-100](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_config.py)\n\n### 模型提供商配置\n\n框架支持多种模型提供商，通过 `model_provider` 参数指定：\n\n```python\n# OpenAI\nconfig = RunConfig(model_provider=\"openai\", model=\"gpt-4o\")\n\n# Anthropic\nconfig = RunConfig(model_provider=\"anthropic\", model=\"claude-3-opus-20240229\")\n\n# Azure OpenAI\nconfig = RunConfig(model_provider=\"azure\", model=\"gpt-4o\")\n\n# 自定义提供商\nconfig = RunConfig(model_provider=\"my-provider\", model=\"custom-model\")\n```\n\n## RunContext 上下文管理\n\n### 上下文的作用\n\n`RunContext` 负责管理代理执行过程中的上下文信息，包括输入历史、工具调用结果、运行时数据等。\n\n```python\nclass RunContextWrapper(Generic[AgentStateT]):\n def __init__(\n self,\n trace_id: str,\n session_id: str,\n agent: Agent,\n messages: list[ChatMessage],\n state: AgentStateT,\n current_agent: Agent,\n agent_history: dict[str, list[ChatMessage]],\n pending_handoffs: list[Handoff],\n tools: list[Tool],\n turn_context: TurnContext | None,\n )\n```\n\n### 上下文数据访问\n\n| 方法 | 说明 |\n|------|------|\n| `get(key)` | 获取上下文中的值 |\n| `set(key, value)` | 设置上下文中的值 |\n| `get_messages()` | 获取消息历史 |\n| `get_state()` | 获取代理状态 |\n| `update_state(**kwargs)` | 更新代理状态 |\n\n资料来源：[src/agents/run_context.py:30-80](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_context.py)\n\n### 上下文数据流\n\n```mermaid\ngraph LR\n A[用户输入] --> B[RunContext]\n B --> C[消息历史]\n B --> D[状态存储]\n B --> E[代理历史]\n C --> F[模型调用]\n F --> G[工具执行]\n G --> B\n F --> H[最终输出]\n```\n\n## RunState 状态管理\n\n### 状态追踪\n\n`RunState` 负责追踪代理执行过程中的所有状态信息：\n\n```python\nclass RunState(BaseModel):\n run_id: str\n turn_count: int = 0\n step_count: int = 0\n messages: list[ChatMessage] = Field(default_factory=list)\n tool_results: list[ToolResult] = Field(default_factory=list)\n agent_history: dict[str, list[ChatMessage]] = Field(default_factory=dict)\n pending_handoffs: list[Handoff] = Field(default_factory=list)\n output_guardrail_results: list[GuardrailResult] = Field(default_factory=list)\n input_guardrail_results: list[GuardrailResult] = Field(default_factory=list)\n```\n\n### 状态字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `run_id` | `str` | 唯一运行标识符 |\n| `turn_count` | `int` | 代理轮次计数 |\n| `step_count` | `int` | 执行步骤计数 |\n| `messages` | `list[ChatMessage]` | 完整消息历史 |\n| `tool_results` | `list[ToolResult]` | 工具执行结果 |\n| `agent_history` | `dict[str, list[ChatMessage]]` | 各代理的消息历史 |\n| `pending_handoffs` | `list[Handoff]` | 待处理的交接请求 |\n| `output_guardrail_results` | `list[GuardrailResult]` | 输出验证结果 |\n| `input_guardrail_results` | `list[GuardrailResult]` | 输入验证结果 |\n\n资料来源：[src/agents/run_state.py:20-60](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_state.py)\n\n## Lifecycle 生命周期钩子\n\n### 钩子类型\n\n框架提供了完整的生命周期钩子系统，允许开发者在代理执行的各个阶段注入自定义逻辑：\n\n```python\nclass Hooks(Generic[AgentStateT]):\n async def on_agent_start(\n self,\n context_wrapper: RunContextWrapper[AgentStateT],\n agent: Agent,\n ) -> None\n \n async def on_agent_end(\n self,\n context_wrapper: RunContextWrapper[AgentStateT],\n agent: Agent,\n output: str,\n ) -> None\n \n async def on_tool_start(\n self,\n context_wrapper: RunContextWrapper[AgentStateT],\n tool: Tool,\n parameters: dict[str, Any],\n ) -> None\n \n async def on_tool_end(\n self,\n context_wrapper: RunContextWrapper[AgentStateT],\n tool: Tool,\n result: Any,\n ) -> None\n```\n\n### 钩子执行流程\n\n```mermaid\ngraph TD\n A[开始运行] --> B{on_agent_start}\n B --> C[执行代理]\n C --> D{工具调用?}\n D -->|是| E[on_tool_start]\n E --> F[执行工具]\n F --> G[on_tool_end]\n G --> D\n D -->|否| H{交接?}\n H -->|是| I[处理交接]\n I --> J{结束?}\n H -->|否| J\n C --> J\n J -->|否| C\n J -->|是| K[on_agent_end]\n K --> L[输出结果]\n```\n\n### 可用钩子列表\n\n| 钩子名称 | 触发时机 | 用途示例 |\n|----------|----------|----------|\n| `on_agent_start` | 代理开始执行前 | 记录开始时间、初始化资源 |\n| `on_agent_end` | 代理执行完成后 | 记录结束时间、清理资源 |\n| `on_tool_start` | 工具开始执行前 | 记录工具调用、参数验证 |\n| `on_tool_end` | 工具执行完成后 | 记录工具结果、错误处理 |\n| `on_handoff` | 代理交接时 | 传递上下文、更新状态 |\n| `on_exception` | 异常发生时 | 错误日志、告警通知 |\n\n资料来源：[src/agents/lifecycle.py:30-150](https://github.com/openai/openai-agents-python/blob/main/src/agents/lifecycle.py)\n\n## StreamEvents 事件流\n\n### 事件类型\n\n`StreamEvents` 定义了所有可流式输出的事件类型：\n\n```python\nclass StreamEvents:\n AGENT_DETAIL_STREAMING = \"agent_detail_streaming\"\n RUN_ITEM_STOPPED = \"run_item_stopped\"\n RUN_ITEM_DELTA = \"run_item_delta\"\n RUN_ITEM_ADDED = \"run_item_added\"\n TEXT_DONE = \"text_done\"\n TEXT_DELTA = \"text_delta\"\n IMAGE_DETAIL_DONE = \"image_detail_done\"\n ABORTED_ERROR = \"aborted_error\"\n CONNECTION_ERROR = \"connection_error\"\n ERROR = \"error\"\n TOOL_CALL = \"tool_call\"\n TOOL_CALL_DETAILS = \"tool_call_details\"\n HANDOVER = \"handover\"\n PAUSED = \"paused\"\n RESUMED = \"resumed\"\n```\n\n### 事件数据结构\n\n| 事件类型 | 数据结构 | 说明 |\n|----------|----------|------|\n| `RUN_ITEM_DELTA` | `RunItemDeltaEvent` | 运行项的增量更新 |\n| `RUN_ITEM_ADDED` | `RunItemAddedEvent` | 新增运行项 |\n| `TEXT_DELTA` | `TextDeltaEvent` | 文本增量 |\n| `TOOL_CALL` | `ToolCallEvent` | 工具调用事件 |\n| `HANDOVER` | `HandoverEvent` | 代理交接事件 |\n\n资料来源：[src/agents/stream_events.py:20-100](https://github.com/openai/openai-agents-python/blob/main/src/agents/stream_events.py)\n\n### 流式使用示例\n\n```python\nasync def run_with_stream():\n config = RunConfig(stream=True, stream_intermediate_steps=True)\n \n events = Runner.run_stream_events(\n agent=my_agent,\n input=\"用户问题\",\n config=config\n )\n \n async for event in events:\n if event.type == StreamEvents.TEXT_DELTA:\n print(event.data.text, end=\"\", flush=True)\n elif event.type == StreamEvents.TOOL_CALL:\n print(f\"\\n调用工具: {event.data.name}\")\n```\n\n## 执行流程详解\n\n### 完整执行流程图\n\n```mermaid\nflowchart TD\n A[初始化 Runner] --> B[创建 RunContext]\n B --> C[验证输入]\n C --> D[执行输入 Guardrails]\n D --> E{验证通过?}\n E -->|否| F[返回错误]\n E -->|是| G[加载代理配置]\n G --> H[开始生命周期钩子]\n H --> I[构建系统提示]\n I --> J[调用模型]\n J --> K{需要工具调用?}\n K -->|是| L[执行工具]\n L --> M[收集工具结果]\n M --> J\n K -->|否| N{需要交接?}\n N -->|是| O[执行交接]\n O --> P[加载新代理]\n P --> I\n N -->|否| Q{执行输出 Guardrails?}\n Q -->|是| R[验证输出]\n R --> S{验证通过?}\n S -->|否| F\n S -->|是| T[触发结束钩子]\n Q -->|否| T\n T --> U[返回 FinalOutput]\n```\n\n### Turn Resolution 机制\n\nTurn resolution 是框架处理多轮对话和状态更新的核心机制，位于 `src/agents/run_internal/turn_resolution.py`：\n\n```python\nasync def _resolve_turn(\n public_agent: Agent,\n original_input: str | list[Message] | list[ToolResult],\n pre_step_items: list[RunItem],\n new_step_items: list[RunItem],\n function_results: list[ToolResult],\n # ... 其他参数\n) -> TurnResult:\n```\n\n该机制负责：\n1. 处理工具调用结果\n2. 管理消息历史\n3. 处理代理交接\n4. 生成最终输出\n\n资料来源：[src/agents/run_internal/turn_resolution.py:50-150](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/turn_resolution.py)\n\n## 代理交接 (Handoffs)\n\n### 交接机制\n\n代理交接允许一个代理将控制权传递给另一个代理，同时传递必要的上下文信息：\n\n```python\nhandoff = Handoff(\n agent=target_agent,\n tool_name=\"transfer_to_target\",\n tool_description=\"切换到目标代理\",\n metadata={\"reason\": \"需要专门知识\"}\n)\n\nsource_agent = Agent(\n name=\"路由器\",\n handoffs=[handoff]\n)\n```\n\n### 交接数据传递\n\n交接时传递的数据结构：\n\n| 字段 | 说明 |\n|------|------|\n| `agent_name` | 目标代理名称 |\n| `handoff_config` | 交接配置 |\n| `input_items` | 传递给目标代理的输入项 |\n| `history_items` | 完整的对话历史 |\n| `metadata` | 附加元数据 |\n\n资料来源：[src/agents/handoffs/history.py:30-80](https://github.com/openai/openai-agents-python/blob/main/src/agents/handoffs/history.py)\n\n## Guardrails 防护机制\n\n### 输入防护\n\n输入防护在模型调用前验证用户输入：\n\n```python\nclass InputGuardrail:\n async def check(\n self,\n context: RunContextWrapper,\n agent: Agent,\n input: str | list[Message],\n ) -> GuardrailResult:\n # 自定义验证逻辑\n pass\n```\n\n### 输出防护\n\n输出防护在模型生成后验证输出：\n\n```python\nclass OutputGuardrail:\n async def check(\n self,\n context: RunContextWrapper,\n agent: Agent,\n output: str | BaseModel,\n ) -> GuardrailResult:\n # 自定义验证逻辑\n pass\n```\n\n### 防护结果\n\n```python\nclass GuardrailResult(BaseModel):\n pass_result: bool\n tripwire_triggered: bool = False\n data: Any = None\n message: str | None = None\n```\n\n| 结果字段 | 说明 |\n|----------|------|\n| `pass_result` | 验证是否通过 |\n| `tripwire_triggered` | 是否触发安全开关 |\n| `data` | 验证返回的数据 |\n| `message` | 验证消息 |\n\n## 最佳实践\n\n### 1. 合理设置 Max Steps\n\n```python\n# 简单任务\nconfig = RunConfig(max_steps=10)\n\n# 复杂多步骤任务\nconfig = RunConfig(max_steps=150)\n```\n\n### 2. 使用生命周期钩子进行监控\n\n```python\nclass MyHooks(Hooks):\n async def on_agent_start(self, context, agent):\n logger.info(f\"开始执行代理: {agent.name}\")\n \n async def on_tool_end(self, context, tool, result):\n logger.info(f\"工具 {tool.name} 执行完成\")\n```\n\n### 3. 流式输出的正确使用\n\n```python\nasync for event in Runner.run_stream_events(agent, input, config=config):\n if event.type == StreamEvents.TEXT_DELTA:\n # 增量处理文本\n accumulated_text += event.data.text\n```\n\n## 总结\n\nAgent 核心框架提供了一套完整、模块化的代理系统架构：\n\n- **Agent** 负责代理的行为定义\n- **Runner** 协调整个执行流程\n- **RunConfig** 管理运行时配置\n- **RunContext** 维护执行上下文\n- **RunState** 追踪运行时状态\n- **Lifecycle** 提供生命周期钩子扩展\n- **StreamEvents** 支持事件流式输出\n\n这些组件协同工作，使开发者能够灵活构建复杂的 AI Agent 应用，同时保持代码的可维护性和可扩展性。\n\n---\n\n\n\n## 工具系统\n\n### 相关页面\n\n相关主题：[MCP 协议集成](#mcp), [Agent 核心框架](#agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/tool.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool.py)\n- [src/agents/function_schema.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/function_schema.py)\n- [src/agents/tool_context.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool_context.py)\n- [src/agents/tool_guardrails.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool_guardrails.py)\n- [examples/basic/tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/basic/tools.py)\n- [examples/tools/shell.py](https://github.com/openai/openai-agents-python/blob/main/examples/tools/shell.py)\n- [examples/tools/code_interpreter.py](https://github.com/openai/openai-agents-python/blob/main/examples/tools/code_interpreter.py)\n \n\n# 工具系统\n\n## 概述\n\n工具系统（Tool System）是 openai-agents-python 框架的核心组件之一，它为 AI Agent 提供了与外部世界交互的能力。通过工具系统，Agent 可以执行代码、搜索网络、操作文件系统、调用外部 API 等。工具在 Agent 执行循环中扮演着关键角色，使语言模型能够执行实际操作而不仅仅是生成文本响应。\n\n工具系统的设计遵循以下核心原则：\n\n- **声明式配置**：工具通过 Pydantic 模型进行类型安全的声明式配置\n- **上下文感知**：工具可以访问运行时上下文信息，包括对话历史和中间结果\n- **安全隔离**：通过沙箱（Sandbox）机制执行危险操作，保护主机系统安全\n- **可扩展架构**：支持自定义工具、MCP 服务器集成以及第三方扩展\n\n资料来源：[src/agents/tool.py]()\n\n## 架构设计\n\n### 整体架构\n\n工具系统的架构采用分层设计，主要包含以下几个层次：\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Agent Layer │\n│ (Agent, SandboxAgent, etc.) │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ Tool Layer │\n│ ┌─────────────┬──────────────┬──────────────────┐ │\n│ │ FunctionTool│ MCPTool │ Custom Tools │ │\n│ └─────────────┴──────────────┴──────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ Execution Layer │\n│ ┌─────────────┬──────────────┬──────────────────┐ │\n│ │ Sandbox │ Local Exec │ Remote Service │ │\n│ └─────────────┴──────────────┴──────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n### 核心组件关系\n\n工具系统由多个核心组件构成，它们之间通过清晰的接口进行交互：\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| `Tool` | 工具基类，定义工具的通用接口和元数据 | `src/agents/tool.py` |\n| `FunctionTool` | 函数工具，将 Python 函数包装为 Agent 可调用的工具 | `src/agents/tool.py` |\n| `ToolContext` | 工具执行上下文，提供运行时信息和状态管理 | `src/agents/tool_context.py` |\n| `FunctionSchema` | 函数模式生成器，从 Python 函数生成 OpenAI 兼容的模式 | `src/agents/function_schema.py` |\n| `ToolGuardrails` | 工具护栏，对工具输入输出进行安全校验 | `src/agents/tool_guardrails.py` |\n| `MCPTool` | MCP 协议工具，集成 Model Context Protocol 服务器 | `src/agents/mcp/server.py` |\n\n资料来源：[src/agents/tool.py:1-50]()\n\n## 工具类型\n\n### FunctionTool\n\n`FunctionTool` 是最常用的工具类型，它将 Python 函数包装为 Agent 可调用的工具。FunctionTool 自动处理参数解析、类型转换和结果序列化。\n\n```python\n# 典型的 FunctionTool 使用方式\nfrom agents import FunctionTool\n\ndef add_numbers(a: int, b: int) -> int:\n \"\"\"将两个数字相加\"\"\"\n return a + b\n\ntool = FunctionTool.from_function(add_numbers)\n```\n\nFunctionTool 支持的功能包括：\n\n- **自动模式生成**：从函数签名和文档字符串生成 OpenAI 函数调用模式\n- **类型验证**：使用 Pydantic 进行参数和返回值的类型验证\n- **描述覆盖**：允许通过参数覆盖自动生成的描述信息\n- **输入过滤器**：支持对输入参数进行预处理\n- **输出格式化**：支持对返回结果进行后处理\n\n资料来源：[src/agents/tool.py:50-150]()\n\n### MCPTool\n\nMCPTool 提供了对 Model Context Protocol（MCP）服务器的支持，使 Agent 能够调用通过 MCP 协议暴露的工具。MCP 是一种标准化的工具发现和调用协议。\n\n```python\nfrom agents import MCPTool\n\n# 从 MCP 服务器创建工具\nmcp_tool = MCPTool.from_server(\n name=\"filesystem\",\n command=\"npx\",\n args=[\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/dir\"]\n)\n```\n\nMCPTool 支持的特性：\n\n- **资源模板**：MCP 服务器可以暴露资源模板供 Agent 使用\n- **资源读取**：支持读取 MCP 服务器暴露的资源内容\n- **工具发现**：自动发现并暴露 MCP 服务器提供的所有工具\n- **需求审批**：支持对特定工具配置需要人工审批的策略\n\n资料来源：[src/agents/mcp/server.py:1-80]()\n\n### SandboxAgent 内置工具\n\nSandboxAgent 提供了一组内置工具，专门用于在隔离环境中执行操作：\n\n| 工具名称 | 功能 | 源码位置 |\n|----------|------|----------|\n| `read_file` | 读取文件内容 | Sandbox 实现 |\n| `write_file` | 写入文件内容 | Sandbox 实现 |\n| `list_directory` | 列出目录内容 | Sandbox 实现 |\n| `run_terminal_command` | 执行终端命令 | Sandbox 实现 |\n\n资料来源：[examples/sandbox/basic.py]()\n\n## 函数模式\n\n### 模式生成机制\n\n`FunctionSchema` 类负责从 Python 函数生成 OpenAI 兼容的函数模式。这个过程包括：\n\n1. **函数签名分析**：使用 `inspect` 模块分析函数参数和类型注解\n2. **文档解析**：提取 docstring 中的描述信息\n3. **默认值处理**：处理可选参数和默认值\n4. **Pydantic 模型转换**：将复杂类型转换为 JSON Schema\n\n```python\n# FunctionSchema 生成的结果示例\n{\n \"type\": \"function\",\n \"function\": {\n \"name\": \"search_web\",\n \"description\": \"搜索网络获取信息\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"query\": {\n \"type\": \"string\",\n \"description\": \"搜索查询词\"\n }\n },\n \"required\": [\"query\"]\n }\n }\n}\n```\n\n资料来源：[src/agents/function_schema.py:1-60]()\n\n### 工具描述优化\n\n系统支持对自动生成的工具描述进行优化和覆盖，确保模型能够准确理解工具的用途：\n\n```python\ntool = FunctionTool.from_function(\n my_function,\n name_override=\"custom_tool_name\",\n description_override=\"自定义工具描述\",\n parameters_override={\"query\": {\"description\": \"优化后的描述\"}}\n)\n```\n\n资料来源：[src/agents/tool.py:150-200]()\n\n## 工具上下文\n\n### 上下文结构\n\n`ToolContext` 为工具执行提供了完整的上下文信息，使工具能够访问运行时状态：\n\n```python\n@dataclass\nclass ToolContext:\n run_context: RunContextWrapper[Any] # 运行上下文\n tool_name: str # 当前工具名称\n tool_call_id: str # 工具调用 ID\n input_json: str # 输入参数 JSON\n current_agent: Agent # 当前 Agent\n round_manager: RoundManager # 轮次管理器\n```\n\n工具上下文提供的能力：\n\n- **对话历史访问**：通过 `run_context.messages` 访问完整的对话历史\n- **中间结果引用**：访问同一轮次中其他工具的执行结果\n- **状态管理**：在多次工具调用之间保持状态\n- **Agent 信息**：获取当前执行 Agent 的详细信息\n\n资料来源：[src/agents/tool_context.py:1-50]()\n\n### 输入过滤机制\n\n工具支持通过 `input_filter` 对输入进行预处理：\n\n```python\ndef filter_input(input_json: str, context: ToolContext) -> str:\n # 自定义输入过滤逻辑\n data = json.loads(input_json)\n data[\"filtered_param\"] = \"modified_value\"\n return json.dumps(data)\n\ntool = FunctionTool.from_function(\n my_function,\n input_filter=filter_input\n)\n```\n\n资料来源：[src/agents/tool.py:200-250]()\n\n## 工具护栏\n\n### 护栏机制\n\n`ToolGuardrails` 提供了对工具调用的安全检查机制，分为输入护栏和输出护栏两类：\n\n```python\n@dataclass\nclass ToolGuardrail:\n name: str\n check: Callable[[RunContextWrapper, Tool, str], Awaitable[GuardrailFunctionOutput]]\n config: dict[str, Any] = field(default_factory=dict)\n```\n\n### 输入护栏\n\n输入护栏在工具执行前对参数进行检查：\n\n```python\nasync def validate_input(\n context: RunContextWrapper,\n tool: Tool,\n input_json: str\n) -> GuardrailFunctionOutput:\n # 检查输入参数是否符合预期\n data = json.loads(input_json)\n if \"sensitive_field\" in data:\n return GuardrailFunctionOutput(\n pass_percentage=0.0, # 阻止执行\n action_info=ActionInfo(\n action_type=ActionType.INPUT_CORRECTION,\n message=\"检测到敏感数据\"\n )\n )\n return GuardrailFunctionOutput(pass_percentage=1.0)\n```\n\n### 输出护栏\n\n输出护栏在工具执行后对结果进行检查：\n\n```python\nasync def validate_output(\n context: RunContextWrapper,\n tool: Tool,\n output: str\n) -> GuardrailFunctionOutput:\n # 检查输出内容\n if contains_sensitive_data(output):\n return GuardrailFunctionOutput(\n pass_percentage=0.0,\n action_info=ActionInfo(\n action_type=ActionType.OUTPUT_FILTER,\n message=\"输出包含敏感信息\"\n )\n )\n return GuardrailFunctionOutput(pass_percentage=1.0)\n```\n\n资料来源：[src/agents/tool_guardrails.py:1-100]()\n\n## 使用示例\n\n### 基础工具创建\n\n```python\n# examples/basic/tools.py\nfrom agents import FunctionTool\n\ndef get_weather(location: str, unit: str = \"celsius\") -> str:\n \"\"\"获取指定位置的天气信息\n \n Args:\n location: 城市名称\n unit: 温度单位 (celsius 或 fahrenheit)\n \"\"\"\n # 实际实现中会调用天气 API\n return f\"{location} 当前温度为 22°C\"\n\nweather_tool = FunctionTool.from_function(\n get_weather,\n name_override=\"get_weather\",\n description_override=\"获取指定城市的天气信息\"\n)\n```\n\n资料来源：[examples/basic/tools.py:1-30]()\n\n### Shell 工具\n\n```python\n# examples/tools/shell.py\nfrom agents import FunctionTool\nimport subprocess\n\ndef execute_shell(command: str, timeout: int = 30) -> str:\n \"\"\"在终端执行 shell 命令\n \n Args:\n command: 要执行的命令\n timeout: 超时时间（秒）\n \"\"\"\n try:\n result = subprocess.run(\n command,\n shell=True,\n capture_output=True,\n text=True,\n timeout=timeout\n )\n return result.stdout if result.returncode == 0 else f\"Error: {result.stderr}\"\n except subprocess.TimeoutExpired:\n return \"命令执行超时\"\n```\n\n资料来源：[examples/tools/shell.py:1-30]()\n\n### 代码解释器工具\n\n```python\n# examples/tools/code_interpreter.py\nfrom agents import FunctionTool\nimport contextlib\nimport io\n\ndef run_python(code: str) -> str:\n \"\"\"执行 Python 代码\n \n Args:\n code: 要执行的 Python 代码\n \"\"\"\n stdout = io.StringIO()\n stderr = io.StringIO()\n \n with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):\n try:\n exec(code, {})\n output = stdout.getvalue()\n return output if output else \"代码执行完成，无输出\"\n except Exception as e:\n return f\"执行错误: {str(e)}\"\n```\n\n资料来源：[examples/tools/code_interpreter.py:1-30]()\n\n## 工具与 Agent 的集成\n\n### Agent 工具配置\n\nAgent 在初始化时通过 `tools` 参数接收工具列表：\n\n```python\nfrom agents import Agent\n\nagent = Agent(\n name=\"research_assistant\",\n instructions=\"你是一个研究助手，可以使用工具来完成任务\",\n tools=[\n web_search_tool,\n file_read_tool,\n code_interpreter_tool\n ]\n)\n```\n\n### 工具可视化\n\n工具系统提供了可视化功能，可以生成 Agent 和工具的关系图：\n\n```python\nfrom agents.extensions.visualization import get_all_nodes, get_all_edges\n\n# 生成 DOT 格式的图描述\nnodes = get_all_nodes(agent)\nedges = get_all_edges(agent)\ndot_graph = f\"digraph {{\\n{nodes}\\n{edges}\\n}}\"\n```\n\n资料来源：[src/agents/extensions/visualization.py:1-80]()\n\n## 执行流程\n\n### 工具调用生命周期\n\n```\n┌──────────────────────────────────────────────────────────┐\n│ 工具调用流程 │\n└──────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 1. 工具选择 │\n│ - 模型根据工具描述选择合适的工具 │\n│ - 生成工具调用参数 │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 2. 输入护栏检查 │\n│ - 验证参数类型和格式 │\n│ - 安全检查（可选） │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 3. 工具执行 │\n│ - 调用实际的工具函数 │\n│ - 处理异常情况 │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 4. 输出护栏检查 │\n│ - 验证返回结果 │\n│ - 内容过滤（可选） │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 5. 结果返回 │\n│ - 将结果传递给模型 │\n│ - 继续执行循环 │\n└─────────────────────────────────────────────────────────┘\n```\n\n## 配置选项\n\n### 工具级别配置\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `name` | `str` | 函数名 | 工具在模型调用时的名称 |\n| `description` | `str` | docstring | 工具的功能描述 |\n| `parameters_override` | `dict` | `None` | 参数模式的覆盖配置 |\n| `input_filter` | `Callable` | `None` | 输入预处理函数 |\n| `output_formatter` | `Callable` | `None` | 输出格式化函数 |\n| `require_approval` | `bool` | `False` | 是否需要人工审批 |\n\n### Agent 工具配置\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `tools` | `list[Tool]` | 分配给 Agent 的工具列表 |\n| `tool_choice` | `str \\| None` | 强制模型使用特定工具 |\n| `parallel_tool_calls` | `bool` | 是否允许并行工具调用 |\n\n## 最佳实践\n\n### 工具命名规范\n\n- 使用清晰、简洁的英文名称\n- 采用 snake_case 命名法\n- 名称应该反映工具的核心功能\n\n### 描述撰写建议\n\n- 第一行应该是简短的总结性描述\n- 详细说明参数含义和预期格式\n- 提供使用示例（如果适用）\n- 明确标注必选和可选参数\n\n### 错误处理\n\n- 返回有意义的错误信息\n- 区分不同类型的错误\n- 避免暴露敏感的系统信息\n\n### 安全考虑\n\n- 对敏感操作配置人工审批\n- 使用输入护栏验证参数\n- 使用输出护栏过滤敏感数据\n- 在沙箱环境中执行危险操作\n\n## 相关资源\n\n- 源码：[src/agents/tool.py]()\n- 函数模式：[src/agents/function_schema.py]()\n- 工具上下文：[src/agents/tool_context.py]()\n- 工具护栏：[src/agents/tool_guardrails.py]()\n- MCP 支持：[src/agents/mcp/server.py]()\n- 示例：[examples/basic/tools.py]()\n\n---\n\n\n\n## MCP 协议集成\n\n### 相关页面\n\n相关主题：[工具系统](#tools), [Agent 核心框架](#agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/mcp/manager.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/mcp/manager.py)\n- [src/agents/mcp/server.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/mcp/server.py)\n- [src/agents/mcp/util.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/mcp/util.py)\n- [src/agents/_mcp_tool_metadata.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/_mcp_tool_metadata.py)\n- [examples/mcp](https://github.com/openai/openai-agents-python/blob/main/examples/mcp)\n \n\n# MCP 协议集成\n\n## 概述\n\nMCP（Model Context Protocol）协议集成是 openai-agents-python 框架的核心功能之一，它允许 AI Agent 与外部 MCP 服务器建立连接，并调用服务器提供的各种工具和资源。通过 MCP 集成，开发者可以扩展 Agent 的能力边界，使其能够访问文件系统、数据库、Web 服务等外部系统。\n\n本框架提供了完整的 MCP 客户端实现，支持本地 MCP 服务器和远程 MCP 服务器两种连接方式，并提供了工具过滤、审批流程等企业级功能。\n\n## 核心组件\n\n### MCPManager\n\n`MCPManager` 是 MCP 集成的核心管理类，负责维护与 MCP 服务器的连接状态和交互逻辑。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `servers` | `dict[str, MCPServer]` | 已注册的 MCP 服务器映射表 |\n| `tools` | `list[MCPTool]` | 从所有服务器获取的工具列表 |\n| `resource_templates` | `list[Any]` | 资源模板列表 |\n\n### MCPServer\n\n`MCPServer` 是 MCP 服务器的抽象基类，定义了与服务器交互的标准接口。\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `list_resources(cursor)` | `ListResourcesResult` | 列出服务器提供的资源 |\n| `list_resource_templates(cursor)` | `ListResourceTemplatesResult` | 列出资源模板 |\n| `read_resource(uri)` | `ReadResourceResult` | 读取指定 URI 的资源内容 |\n| `call_tool(name, arguments)` | 工具调用结果 | 执行服务器上的工具 |\n\n### MCPUtil\n\n`MCPUtil` 工具类提供了便捷的 MCP 工具获取方法：\n\n- `get_all_function_tools()` - 从配置的 MCP 服务器预获取所有可用工具\n- 支持构建使用预获取工具的 Agent，而非在运行时动态发现\n\n## 架构设计\n\n```mermaid\ngraph TD\n A[Agent] --> B[MCPManager]\n B --> C[MCPServer 1]\n B --> D[MCPServer 2]\n B --> E[MCPServer N]\n C --> F[本地 MCP Server
npx/stdio]\n D --> G[远程 MCP Server
Streamable HTTP]\n E --> H[MCP Server
其他传输协议]\n F --> I[本地文件系统工具]\n G --> J[DeepWiki API]\n H --> K[自定义 MCP 服务]\n```\n\n## 工具过滤机制\n\n框架支持静态工具过滤，允许开发者限制 Agent 可访问的 MCP 工具范围。这对于安全控制和界面简化非常重要。\n\n```mermaid\ngraph LR\n A[MCP 服务器
所有工具] --> B[工具过滤器]\n B --> C[过滤后的
可用工具集]\n C --> D[Agent 可见]\n```\n\n工具过滤通过 `MCPToolFilter` 接口实现，开发者可以自定义过滤规则：\n\n```python\n# 伪代码示例\ntool_filter = ToolFilter(allowed_tools=[\"read_file\", \"write_file\"])\nagent = Agent(..., mcp_servers=[server], tool_filter=tool_filter)\n```\n\n## 审批流程集成\n\nMCP 工具调用支持 `require_approval` 配置选项，实现人机协作审批流程。\n\n### 审批设置类型\n\n| 设置值 | 说明 |\n|--------|------|\n| `\"always\"` | 每次工具调用都需要人工审批 |\n| `\"never\"` | 不需要审批，自动执行 |\n| `Callable` | 自定义审批逻辑函数 |\n\n### 审批逻辑处理\n\n```python\n# 来自 server.py 的审批逻辑签名\n@staticmethod\ndef _normalize_needs_approval(\n *,\n require_approval: RequireApprovalSetting,\n) -> (\n bool\n | dict[str, bool]\n | Callable[[RunContextWrapper[Any], AgentBase, MCPTool], MaybeAwaitable[bool]]\n)\n```\n\n开发者可以传入布尔值、字典或可调用对象来自定义审批行为。当设置为 `\"always\"` 时，框架会自动进入 HITL（Human-In-The-Loop）流程，等待人工确认后继续执行。\n\n## 资源管理\n\nMCP 服务器可以暴露两种类型的资源访问接口：\n\n### 资源列表\n\n`list_resources` 方法返回服务器上可用的资源列表，支持分页：\n\n```python\nasync def list_resources(self, cursor: str | None = None) -> ListResourcesResult:\n \"\"\"\n Args:\n cursor: 分页游标，用于获取下一页结果\n \"\"\"\n```\n\n返回结果包含 `nextCursor` 字段用于后续分页请求。\n\n### 资源模板\n\n`list_resource_templates` 方法列出资源模板，模板支持参数化资源访问：\n\n```python\nasync def list_resource_templates(\n self, cursor: str | None = None\n) -> ListResourceTemplatesResult:\n \"\"\"\n 支持的参数化资源模板查询\n \"\"\"\n```\n\n### 资源读取\n\n`read_resource` 方法根据 URI 读取具体资源内容：\n\n```python\nasync def read_resource(self, uri: str) -> ReadResourceResult:\n \"\"\"\n Args:\n uri: 资源的 URI 地址\n \"\"\"\n```\n\n## 连接示例\n\n### 本地 MCP 服务器\n\n通过 `npx` 启动本地文件系统 MCP 服务器：\n\n```bash\nnpx -y @modelcontextprotocol/server-filesystem /path/to/directory\n```\n\n在代码中配置：\n\n```python\nfrom agents import Agent, MCPServer\nfrom agents.mcp import StreamableHTTPServer\n\nserver = StreamableHTTPServer(\n name=\"filesystem\",\n command=\"npx\",\n args=[\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/directory\"]\n)\n\nagent = Agent(mcp_servers=[server])\n```\n\n### 远程 MCP 服务器\n\n通过 Streamable HTTP 协议连接远程 MCP 服务器：\n\n```python\nfrom agents.mcp import StreamableHTTPServer\n\nserver = StreamableHTTPServer(\n name=\"deepwiki\",\n url=\"https://mcp.deepwiki.com/mcp\",\n auth_token=\"your-auth-token\" # 可选\n)\n\nagent = Agent(mcp_servers=[server])\n```\n\n## 错误处理\n\n框架为 MCP 操作定义了专门的异常类型：\n\n| 异常类型 | 触发场景 |\n|----------|----------|\n| `NotImplementedError` | 服务器不支持特定功能（如资源读取） |\n| `ExecNonZeroError` | 命令执行返回非零退出码 |\n| `InvalidManifestPathError` | manifest 路径无效（exit_code=111） |\n| `WorkspaceArchiveWriteError` | 工作空间归档写入失败 |\n\n## 应用场景\n\n### 1. 文件系统访问\n\n使用官方 MCP 文件系统服务器，为 Agent 添加读写本地文件的能力。\n\n### 2. 外部 API 集成\n\n通过 MCP 协议连接第三方服务（如 DeepWiki），扩展 Agent 的知识获取能力。\n\n### 3. 数据库操作\n\n部署自定义 MCP 服务器，实现结构化数据查询和操作。\n\n### 4. 开发工具集成\n\n集成开发相关的 MCP 工具，如代码搜索、版本控制、持续集成等。\n\n## 配置选项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `timeout` | `float` | 60.0 | 工具调用超时时间（秒） |\n| `require_approval` | `str\\|Callable` | `\"never\"` | 工具调用审批设置 |\n| `tool_filter` | `ToolFilter` | `None` | 工具过滤规则 |\n| `env_vars` | `dict` | `{}` | 传递给服务器的环境变量 |\n\n## 相关资源\n\n- 官方 MCP 服务器列表：[Model Context Protocol Servers](https://github.com/modelcontextprotocol/servers)\n- MCP 协议规范：[MCP Protocol Specification](https://modelcontextprotocol.io/specification)\n\n---\n\n\n\n## Agent 转交机制\n\n### 相关页面\n\n相关主题：[Agent 核心框架](#agent-core), [核心概念](#core-concepts)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/handoffs/__init__.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/handoffs/__init__.py)\n- [src/agents/handoffs/history.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/handoffs/history.py)\n- [src/agents/extensions/handoff_filters.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/extensions/handoff_filters.py)\n- [src/agents/extensions/handoff_prompt.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/extensions/handoff_prompt.py)\n- [examples/handoffs/message_filter.py](https://github.com/openai/openai-agents-python/blob/main/examples/handoffs/message_filter.py)\n \n\n# Agent 转交机制\n\n## 概述\n\nAgent 转交（Handoff）机制是 openai-agents-python 框架中实现多代理协作的核心功能。该机制允许一个 Agent 在执行过程中将控制权转移给另一个 Agent，同时支持传递上下文信息、过滤输入内容、以及管理对话历史。\n\n转交机制在以下场景中发挥关键作用：\n\n- 将复杂任务分解为多个专门化的子任务\n- 实现代理之间的专业分工（如数据分析代理、写作代理、审核代理）\n- 支持条件分支和动态路由\n- 管理用户请求与专门代理之间的映射关系\n\n## 核心组件\n\n### Handoff 类\n\n`Handoff` 类是转交机制的核心数据模型，封装了转交的所有配置信息。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `name` | `str` | 转交工具的名称 |\n| `tool_description` | `str` | 转交工具的描述，供 LLM 理解何时触发转交 |\n| `input_json_schema` | `dict[str, Any]` | 转交工具调用参数的 JSON Schema |\n| `on_invoke_handoff` | `Callable[[RunContextWrapper[Any], str], Awaitable[TAgent]]` | 执行转交的回调函数，接收运行上下文和 JSON 参数字符串，返回目标 Agent |\n| `agent_name` | `str` | 目标 Agent 的名称 |\n| `input_filter` | `HandoffInputFilter \\| None` | 过滤传递给下一 Agent 的输入历史 |\n| `on_handoff` | `Callable \\| None` | 转交触发时执行的副作用函数 |\n| `input_type` | `type \\| None` | 转交参数的 Pydantic 类型定义 |\n| `nest_handoff_history` | `bool \\| None` | 是否嵌套转交历史摘要 |\n| `is_enabled` | `bool \\| Callable[[RunContextWrapper[Any], AgentBase, MCPTool], bool]` | 转交是否启用，支持动态判断 |\n\n资料来源：[src/agents/handoffs/__init__.py]()\n\n### HandoffInputFilter 过滤器\n\n`HandoffInputFilter` 是一个函数类型，用于在转交发生时过滤和转换传递给下一 Agent 的输入历史。\n\n```python\nHandoffInputFilter = Callable[\n [list[RunItem], HandoffInputData], tuple[list[RunItem], list[TResponseInputItem]]\n]\n```\n\n该函数接收：\n- 转交前的完整运行项列表\n- `HandoffInputData` 对象\n\n返回经过过滤和修改后的运行项列表以及新的输入项列表。\n\n资料来源：[src/agents/handoffs/history.py]()\n\n### HandoffInputData 数据结构\n\n```python\nclass HandoffInputData:\n input_history: list[RunItem]\n pre_handoff_items: list[RunItem]\n```\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `input_history` | `list[RunItem]` | 整个对话历史 |\n| `pre_handoff_items` | `list[RunItem]` | 转交触发前的运行项集合 |\n\n资料来源：[src/agents/handoffs/history.py]()\n\n## 转交工作流程\n\n```mermaid\ngraph TD\n A[Agent A 执行中] --> B{触发转交条件}\n B -->|检测到转交工具调用| C[调用 on_handoff 回调]\n C --> D{存在 input_filter?}\n D -->|是| E[执行输入过滤]\n D -->|否| F[使用默认历史]\n E --> G[nest_handoff_history 启用?]\n F --> G\n G -->|是| H[生成历史摘要]\n G -->|否| I[直接传递原始历史]\n H --> J[调用 on_invoke_handoff]\n I --> J\n J --> K[Agent B 开始执行]\n```\n\n## 历史管理机制\n\n### 嵌套历史摘要\n\n当 `nest_handoff_history` 设置为 `True` 时，系统会对转交前的对话历史进行压缩摘要处理，以避免上下文窗口溢出。\n\n```python\ndef nest_handoff_history(\n handoff_input_data: HandoffInputData,\n *,\n history_mapper: HandoffHistoryMapper | None = None,\n) -> HandoffInputData:\n \"\"\"Summarize the previous transcript for the next agent.\"\"\"\n```\n\n处理流程：\n\n1. **规范化历史** - 调用 `_normalize_input_history()` 标准化输入格式\n2. **扁平化嵌套** - 调用 `_flatten_nested_history_messages()` 处理嵌套结构\n3. **转换格式** - 将 `RunItem` 转换为 `TResponseInputItem`\n4. **过滤项目** - 跳过 `ToolApprovalItem` 等特定类型\n5. **生成摘要** - 使用 LLM 生成压缩后的历史摘要\n\n资料来源：[src/agents/handoffs/history.py]()\n\n### 历史包装器\n\n系统使用标记符号包围嵌套的历史摘要：\n\n```python\n_DEFAULT_CONVERSATION_HISTORY_START = \"\"\n_DEFAULT_CONVERSATION_HISTORY_END = \"\"\n```\n\n可通过以下函数自定义：\n\n```python\nset_conversation_history_wrappers(start=\"\", end=\"\")\nreset_conversation_history_wrappers()\nget_conversation_history_wrappers() -> tuple[str, str]\n```\n\n资料来源：[src/agents/handoffs/history.py]()\n\n## 输入过滤详解\n\n### 过滤执行流程\n\n```mermaid\ngraph LR\n A[原始输入历史] --> B[HandoffInputFilter]\n B --> C[过滤后的历史]\n B --> D[新增输入项]\n C --> E[传递给目标 Agent]\n D --> E\n```\n\n### 内置过滤器\n\n框架在 `src/agents/extensions/handoff_filters.py` 中提供了常用的过滤器实现：\n\n| 过滤器 | 功能描述 |\n|--------|----------|\n| `filter_tool_messages` | 移除历史中的工具调用消息 |\n| `filter_non_agent_messages` | 仅保留 Agent 生成的消息 |\n| `filter_by_role` | 按角色过滤消息 |\n| `truncate_history` | 截断过长的历史记录 |\n\n资料来源：[src/agents/extensions/handoff_filters.py]()\n\n### 自定义过滤器示例\n\n```python\ndef my_input_filter(\n items: list[RunItem], \n data: HandoffInputData\n) -> tuple[list[RunItem], list[TResponseInputItem]]:\n # 只保留最近10条消息\n recent_items = items[-10:]\n new_items = [create_summary_item(data)]\n return recent_items, new_items\n\nhandoff = Handoff(\n name=\"transfer_to_analyst\",\n agent_name=\"analyst\",\n on_invoke_handoff=invoke_analyst,\n input_filter=my_input_filter,\n)\n```\n\n## 转交提示词\n\n### 提示词模板\n\n系统在 `src/agents/extensions/handoff_prompt.py` 中定义了转交相关的提示词模板，用于指导 LLM 理解何时以及如何触发转交。\n\n主要提示词组件包括：\n\n| 组件 | 用途 |\n|------|------|\n| `handoff_trigger_prompt` | 指导 LLM 判断触发转交的时机 |\n| `handoff_args_prompt` | 指导 LLM 生成转交参数 |\n| `handoff_summary_prompt` | 用于生成历史摘要 |\n\n资料来源：[src/agents/extensions/handoff_prompt.py]()\n\n## 高级配置\n\n### 条件启用转交\n\n```python\ndef dynamic_enabled(\n context: RunContextWrapper[Any], \n agent: AgentBase, \n tool: MCPTool\n) -> bool:\n # 根据上下文条件判断是否启用\n return context.metadata.get(\"user_tier\") == \"premium\"\n\nhandoff = Handoff(\n name=\"transfer_to_expert\",\n agent_name=\"expert\",\n on_invoke_handoff=invoke_expert,\n is_enabled=dynamic_enabled,\n)\n```\n\n### 带参数的转交\n\n```python\nfrom pydantic import BaseModel\n\nclass TransferArgs(BaseModel):\n reason: str\n priority: str = \"normal\"\n\ndef handle_handoff(context: RunContextWrapper, args: TransferArgs):\n logger.info(f\"Transferring to expert: {args.reason}\")\n return expert_agent\n\nhandoff = Handoff(\n name=\"transfer_to_expert\",\n agent_name=\"expert\",\n on_invoke_handoff=handle_handoff,\n input_type=TransferArgs,\n on_handoff=lambda ctx, args: print(f\"Transfer: {args}\"),\n)\n```\n\n### 禁用转交\n\n```python\n# 完全禁用\nhandoff = Handoff(\n name=\"transfer_to_debug\",\n agent_name=\"debugger\",\n on_invoke_handoff=invoke_debugger,\n is_enabled=False, # 对 LLM 隐藏此转交\n)\n```\n\n## 使用示例\n\n### 基本转交模式\n\n```python\nfrom agents import Agent, Runner, handoff\n\n# 定义两个 Agent\ngeneral_agent = Agent(\n name=\"general\",\n instructions=\"你是一个通用助手。\",\n handoffs=[\n handoff(\n agent=analytics_agent,\n on_handoff=lambda ctx, input: print(\"转移到分析代理\")\n )\n ]\n)\n\nanalytics_agent = Agent(\n name=\"analytics\",\n instructions=\"你是一个数据分析专家。\"\n)\n\n# 执行转交\nresult = await Runner.run(general_agent, \"分析本月的销售数据\")\n```\n\n### 带输入过滤的转交\n\n```python\nfrom agents.handoffs import HandoffInputFilter\n\ndef clean_history_filter(\n items: list[RunItem], \n data: HandoffInputData\n) -> tuple[list[RunItem], list[TResponseInputItem]]:\n # 移除所有工具调用记录\n clean_items = [i for i in items if not isinstance(i, ToolCallItem)]\n return clean_items, []\n\nhandoff = Handoff(\n name=\"escalate\",\n agent_name=\"supervisor\",\n on_invoke_handoff=invoke_supervisor,\n input_filter=clean_history_filter,\n)\n```\n\n资料来源：[examples/handoffs/message_filter.py]()\n\n## 错误处理\n\n### 常见错误场景\n\n| 错误类型 | 触发条件 | 处理建议 |\n|----------|----------|----------|\n| `UserError` | 提供了 `input_type` 但未提供 `on_handoff` | 确保两者同时配置 |\n| `UserError` | `on_handoff` 参数数量不为 2 | 回调必须接收 `context` 和 `input` 两个参数 |\n| `NotImplementedError` | MCP 服务器不支持特定资源操作 | 检查服务器能力 |\n\n资料来源：[src/agents/handoffs/__init__.py](), [src/agents/mcp/server.py]()\n\n## 架构总结\n\n```mermaid\ngraph TD\n subgraph \"转交发起方\"\n A[Agent A] --> B[Handoff 配置]\n B --> C[工具调用]\n end\n \n subgraph \"转交处理\"\n C --> D[on_handoff 回调]\n D --> E[input_filter 处理]\n E --> F[历史摘要生成]\n F --> G[on_invoke_handoff]\n end\n \n subgraph \"转交接收方\"\n G --> H[Agent B]\n H --> I[处理任务]\n end\n```\n\nAgent 转交机制通过解耦转交配置、转交执行、输入处理和历史管理四个关键环节，实现了灵活且可扩展的多代理协作模式。开发者可以通过组合不同的过滤器、回调函数和配置选项，构建复杂的代理工作流程。\n\n---\n\n\n\n## Guardrails 安全机制\n\n### 相关页面\n\n相关主题：[Agent 核心框架](#agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/guardrail.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/guardrail.py)\n- [src/agents/tool_guardrails.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool_guardrails.py)\n- [src/agents/run_internal/guardrails.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/guardrails.py)\n- [examples/agent_patterns/input_guardrails.py](https://github.com/openai/openai-agents-python/blob/main/examples/agent_patterns/input_guardrails.py)\n- [examples/agent_patterns/output_guardrails.py](https://github.com/openai/openai-agents-python/blob/main/examples/agent_patterns/output_guardrails.py)\n \n\n# Guardrails 安全机制\n\n## 概述\n\nGuardrails（安全护栏）机制是 openai-agents-python 框架中用于验证和过滤输入输出内容的关键安全组件。该机制在整个 Agent 运行周期中提供多层次的防护，确保模型行为符合预期规范，防止敏感信息泄露和危险操作执行。\n\nGuardrails 系统主要解决以下安全问题：\n\n- **输入验证**：在用户输入到达 Agent 之前进行安全检查\n- **输出过滤**：对模型生成的内容进行合规性验证\n- **工具调用保护**：在工具输入和输出阶段进行安全校验\n- **追踪审计**：记录安全检查的触发和执行情况\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户输入] --> B[输入 Guardrails 检查]\n B --> C{检查结果}\n C -->|通过| D[Agent 处理]\n C -->|触发| E[拒绝/拦截]\n D --> F[模型响应]\n F --> G[输出 Guardrails 检查]\n G --> H{检查结果}\n H -->|通过| I[返回结果]\n H -->|触发| J[内容过滤/拒绝]\n D --> K[工具调用]\n K --> L[工具输入 Guardrails]\n K --> M[工具执行]\n M --> N[工具输出 Guardrails]\n```\n\n### 组件层次\n\nGuardrails 机制由以下核心组件构成：\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| `Guardrail` | `src/agents/guardrail.py` | 基础 Guardrail 抽象类定义 |\n| `ToolInputGuardrail` | `src/agents/tool_guardrails.py` | 工具输入验证 |\n| `ToolOutputGuardrail` | `src/agents/tool_guardrails.py` | 工具输出验证 |\n| `InputGuardrailFunction` | `examples/agent_patterns/input_guardrails.py` | 输入检查函数示例 |\n| `OutputGuardrailFunction` | `examples/agent_patterns/output_guardrails.py` | 输出检查函数示例 |\n\n## 核心类型定义\n\n### GuardrailSpanData\n\n在追踪系统中，Guardrail 的执行状态通过 `GuardrailSpanData` 进行封装：\n\n```python\nclass GuardrailSpanData:\n name: str # Guardrail 名称标识\n triggered: bool # 是否被触发\n```\n\n### Guardrail 函数签名\n\n```python\nasync def guardrail_function(\n ctx: RunContext,\n agent: Agent,\n input: str | list[Message]\n) -> GuardrailResult:\n \"\"\"\n Args:\n ctx: 运行上下文\n agent: 当前 Agent 实例\n input: 待验证的输入内容\n Returns:\n GuardrailResult: 包含触发状态和输出信息\n \"\"\"\n```\n\n## 输入 Guardrails\n\n### 功能描述\n\n输入 Guardrails 在用户输入进入 Agent 处理流程之前进行安全检查。资料来源：[examples/agent_patterns/input_guardrails.py:1-50]()\n\n### 配置方式\n\n```python\nfrom agents import Agent, InputGuardrail, InputGuardrailFunction\n\nasync def check_sensitive_input(ctx, agent, input) -> GuardrailResult:\n \"\"\"检查输入是否包含敏感内容\"\"\"\n if contains_problematic_content(input):\n return GuardrailResult(\n triggerred=True,\n message=\"输入包含敏感内容，已被拦截\"\n )\n return GuardrailResult(triggerred=False)\n\nagent = Agent(\n name=\"安全助手\",\n instructions=\"你是一个有帮助的助手\",\n input_guardrails=[\n InputGuardrail(function=check_sensitive_input)\n ]\n)\n```\n\n### 执行流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户输入\n participant IG as 输入 Guardrail\n participant A as Agent\n participant T as 追踪系统\n\n U->>IG: 原始输入内容\n IG->>T: guardrail_span(name=\"input_check\")\n IG->>IG: 执行检查逻辑\n alt 检查通过\n IG->>A: 传递输入\n A-->>U: 正常响应\n else 检查触发\n IG-->>U: 返回错误信息\n end\n```\n\n## 输出 Guardrails\n\n### 功能描述\n\n输出 Guardrails 负责在模型生成响应后、返回给用户之前进行内容验证和过滤。资料来源：[examples/agent_patterns/output_guardrails.py:1-50]()\n\n### 配置方式\n\n```python\nfrom agents import Agent, OutputGuardrail, OutputGuardrailFunction\n\nasync def check_output_content(ctx, agent, output) -> GuardrailResult:\n \"\"\"检查输出内容的安全性\"\"\"\n if contains_harmful_content(output.content):\n return GuardrailResult(\n triggerred=True,\n message=\"输出内容包含不当信息\"\n )\n return GuardrailResult(triggerred=False)\n\nagent = Agent(\n name=\"内容审核助手\",\n instructions=\"生成安全的内容\",\n output_guardrails=[\n OutputGuardrail(function=check_output_content)\n ]\n)\n```\n\n## 工具级 Guardrails\n\n### 工具输入检查\n\nToolInputGuardrail 在工具执行前验证传入参数的安全性：\n\n```python\nclass ToolInputGuardrail(Guardrail):\n \"\"\"工具输入安全检查\"\"\"\n \n async def check(\n self,\n ctx: RunContext,\n agent: Agent,\n tool: Tool,\n input_data: dict\n ) -> GuardrailResult:\n # 验证输入参数是否符合预期格式和范围\n pass\n```\n\n### 工具输出检查\n\nToolOutputGuardrail 在工具执行后验证返回结果：\n\n```python\nclass ToolOutputGuardrail(Guardrail):\n \"\"\"工具输出安全检查\"\"\"\n \n async def check(\n self,\n ctx: RunContext,\n agent: Agent,\n tool: Tool,\n output: Any\n ) -> GuardrailResult:\n # 验证输出是否包含敏感信息\n pass\n```\n\n### 执行上下文\n\n工具级 Guardrails 的检查结果通过 `tool_input_guardrail_results` 和 `tool_output_guardrail_results` 参数在执行流程中传递。资料来源：[src/agents/run_internal/turn_resolution.py:50-80]()\n\n## 追踪与监控\n\n### Guardrail Span 创建\n\n每个 Guardrail 检查都会生成对应的追踪 Span：\n\n```python\ndef guardrail_span(\n name: str,\n triggered: bool = False,\n span_id: str | None = None,\n parent: Trace | Span[Any] | None = None,\n disabled: bool = False,\n) -> Span[GuardrailSpanData]:\n \"\"\"创建 Guardrail 追踪 Span\"\"\"\n```\n\n资料来源：[src/agents/tracing/create.py:40-60]()\n\n### 追踪数据结构\n\n```mermaid\nclassDiagram\n class GuardrailSpanData {\n +str name\n +bool triggered\n }\n \n class Span {\n +start()\n +finish()\n +set_status()\n }\n \n class Trace {\n +create_span()\n +get_spans()\n }\n \n Span --> GuardrailSpanData\n Trace ..> Span : creates\n```\n\n## Agent 配置集成\n\n### 完整配置示例\n\n```python\nfrom agents import Agent, RunContext\n\nagent = Agent(\n name=\"安全问答助手\",\n instructions=\"提供安全、准确的信息\",\n input_guardrails=[\n InputGuardrail(function=validate_user_input),\n ],\n output_guardrails=[\n OutputGuardrail(function=validate_model_output),\n ],\n tool_input_guardrails=[\n ToolInputGuardrail(function=validate_tool_params),\n ],\n tool_output_guardrails=[\n ToolOutputGuardrail(function=validate_tool_result),\n ],\n)\n```\n\n### 配置参数说明\n\n| 参数 | 类型 | 说明 | 必填 |\n|------|------|------|------|\n| `input_guardrails` | `list[InputGuardrail]` | 输入检查列表 | 否 |\n| `output_guardrails` | `list[OutputGuardrail]` | 输出检查列表 | 否 |\n| `tool_input_guardrails` | `list[ToolInputGuardrail]` | 工具输入检查 | 否 |\n| `tool_output_guardrails` | `list[ToolOutputGuardrail]` | 工具输出检查 | 否 |\n\n## 执行流程详解\n\n### 单轮对话中的 Guardrails 执行\n\n```mermaid\ngraph LR\n subgraph 输入阶段\n A1[用户消息] --> A2[Input Guardrails]\n A2 --> A3{触发?}\n end\n \n subgraph 处理阶段\n A3 -->|否| B1[Agent 处理]\n B1 --> B2[工具调用]\n end\n \n subgraph 工具阶段\n B2 --> C1[Tool Input Guardrails]\n C1 --> C2{触发?}\n C2 -->|是| C4[拦截]\n C2 -->|否| B3[执行工具]\n B3 --> C3[Tool Output Guardrails]\n C3 --> C5{触发?}\n C5 -->|是| C4\n end\n \n subgraph 输出阶段\n C5 -->|否| D1[Agent 响应生成]\n D1 --> D2[Output Guardrails]\n D2 --> D3{触发?}\n D3 -->|否| D4[返回结果]\n D3 -->|是| D5[返回错误]\n end\n```\n\n### 检查结果处理\n\n当 Guardrail 被触发时，系统会中断当前执行流程：\n\n1. **输入检查触发**：返回验证错误，拒绝处理请求\n2. **输出检查触发**：过滤或拒绝返回内容\n3. **工具检查触发**：阻止工具执行或过滤返回数据\n\n资料来源：[src/agents/run_internal/guardrails.py:1-100]()\n\n## 最佳实践\n\n### 1. 分层检查策略\n\n建议采用多层防护策略：\n\n```python\n# 基础层：快速检查\nasync def basic_check(ctx, agent, input):\n # 使用正则或关键词快速匹配\n pass\n\n# 深度层：复杂分析\nasync def deep_check(ctx, agent, input):\n # 使用模型或更复杂的逻辑\n pass\n\nagent = Agent(\n input_guardrails=[\n InputGuardrail(function=basic_check, timeout=1.0),\n InputGuardrail(function=deep_check, timeout=10.0),\n ]\n)\n```\n\n### 2. 性能优化\n\n- 将简单快速的检查放在前面\n- 使用缓存避免重复检查\n- 设置合理的超时时间\n\n### 3. 错误处理\n\n```python\nasync def safe_guardrail(ctx, agent, input):\n try:\n return await perform_check(input)\n except CheckError as e:\n # 保守策略：检查失败时拒绝\n return GuardrailResult(triggerred=True, message=str(e))\n```\n\n## 与其他系统的协作\n\n### 与 Tracing 系统集成\n\nGuardrails 的执行状态会自动记录到追踪系统中，便于审计和问题排查。\n\n### 与 Handoff 系统协作\n\n在 Agent 间交接时，Guardrail 配置会随 Agent 定义一起传递，但历史对话内容不重复检查。资料来源：[src/agents/handoffs/history.py:1-50]()\n\n## 总结\n\nGuardrails 安全机制为 openai-agents-python 提供了完整的多层次安全防护能力，覆盖从用户输入到模型输出再到工具调用的完整流程。通过灵活的接口设计，开发者可以轻松实现自定义的安全检查逻辑，同时追踪系统提供了完整的审计能力。\n\n---\n\n\n\n## 沙箱 Agent 概述\n\n### 相关页面\n\n相关主题：[沙箱会话管理](#sandbox-session)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/sandbox/sandbox_agent.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/sandbox_agent.py)\n- [src/agents/sandbox/runtime.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/runtime.py)\n- [src/agents/sandbox/manifest.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/manifest.py)\n- [src/agents/sandbox/capabilities/capabilities.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/capabilities/capabilities.py)\n- [examples/sandbox/basic.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/basic.py)\n- [examples/sandbox/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/README.md)\n- [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)\n- [src/agents/sandbox/util/tar_utils.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/util/tar_utils.py)\n- [examples/sandbox/tutorials/dataroom_metric_extract/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tutorials/dataroom_metric_extract/README.md)\n- [examples/sandbox/tutorials/repo_code_review/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tutorials/repo_code_review/README.md)\n \n\n# 沙箱 Agent 概述\n\n## 简介\n\n沙箱 Agent（Sandbox Agent）是 openai-agents-python 框架中用于在隔离环境中执行 AI 代理任务的组件。沙箱提供了安全的运行时环境，代理可以在其中执行文件操作、运行命令、安装依赖等操作，而不会影响宿主机系统。\n\n沙箱 Agent 的核心价值在于：\n\n- **隔离性**：代理在独立的虚拟工作空间中运行，与宿主环境完全隔离\n- **安全性**：通过路径验证和权限控制防止恶意操作\n- **可重现性**：支持快照（Snapshot）和持久化工作区，便于恢复和复用\n- **多后端支持**：支持多种沙箱提供商，包括 E2B、Modal、Cloudflare、Blaxel、Vercel、Daytona 等\n\n资料来源：[examples/sandbox/README.md:1-15]()\n\n## 核心组件\n\n### 组件架构图\n\n```mermaid\ngraph TD\n A[用户代码] --> B[SandboxAgent]\n B --> C[SandboxRuntime]\n C --> D[Manifest]\n C --> E[Capabilities]\n D --> F[Workspace]\n E --> G[Shell工具]\n E --> H[File工具]\n E --> I[其他工具]\n F --> J[E2B后端]\n F --> K[Modal后端]\n F --> L[Cloudflare后端]\n F --> M[其他后端]\n```\n\n### SandboxAgent\n\n`SandboxAgent` 是沙箱代理的核心类，继承自 `AgentBase`。它负责在沙箱环境中执行代理任务。\n\n**主要职责：**\n\n- 创建和管理沙箱会话\n- 配置工作区清单（Manifest）\n- 应用沙箱能力（Capabilities）\n- 处理代理与沙箱之间的交互\n\n资料来源：[src/agents/sandbox/sandbox_agent.py]()\n\n### SandboxRuntime\n\n`SandboxRuntime` 是沙箱的运行时环境，负责实际执行命令和文件操作。\n\n**主要职责：**\n\n- 初始化沙箱会话\n- 执行 shell 命令\n- 管理文件系统操作\n- 处理工作区持久化\n\n资料来源：[src/agents/sandbox/runtime.py]()\n\n### Manifest\n\nManifest 定义了沙箱工作区的初始状态和配置。它描述了需要注入到沙箱中的文件、目录和环境变量。\n\n**Manifest 核心配置项：**\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `name` | str | Manifest 名称 |\n| `description` | str | 描述信息 |\n| `image` | str | 容器镜像（可选） |\n| `env_vars` | dict | 环境变量 |\n| `files` | list | 要注入的文件列表 |\n| `setup` | list | 初始化命令列表 |\n| `index_url` | str | Python 包索引 URL |\n\n资料来源：[src/agents/sandbox/manifest.py]()\n\n### Capabilities\n\nCapabilities 定义了沙箱代理可以使用的工具集。这些能力通过 `SandboxToolset` 提供给代理使用。\n\n**内置能力：**\n\n| 能力名称 | 说明 |\n|----------|------|\n| `bash` | 执行 bash 命令 |\n| `read` | 读取文件内容 |\n| `write` | 写入文件内容 |\n| `edit` | 编辑文件 |\n| `glob` | 文件模式匹配 |\n| `grep` | 文本搜索 |\n| `web_search` | 网络搜索 |\n\n资料来源：[src/agents/sandbox/capabilities/capabilities.py]()\n\n## 快速开始\n\n### 基础使用示例\n\n以下示例展示了如何创建和运行一个基本的沙箱 Agent：\n\n```python\nfrom agents import SandboxAgent, Runner\nfrom agents.sandbox import Sandbox\n\nasync def main():\n sandbox = Sandbox()\n \n agent = SandboxAgent(\n name=\"文件分析助手\",\n instructions=\"分析工作区中的文件并提供摘要\",\n sandbox=sandbox,\n )\n \n result = await Runner.run(agent, \"查看当前目录下的所有 Python 文件\")\n print(result.final_output)\n```\n\n资料来源：[examples/sandbox/basic.py:1-30]()\n\n### 带 Manifest 的配置\n\n```python\nfrom agents import SandboxAgent, Runner\nfrom agents.sandbox import Sandbox, Manifest\n\nasync def main():\n manifest = Manifest(\n name=\"数据分析环境\",\n description=\"用于数据分析的 Python 环境\",\n files=[\n {\"path\": \"data.csv\", \"content\": \"...\"},\n ],\n setup=[\n \"pip install pandas numpy\",\n ],\n )\n \n sandbox = Sandbox(manifest=manifest)\n agent = SandboxAgent(\n name=\"数据分析师\",\n instructions=\"使用 Python 分析数据文件\",\n sandbox=sandbox,\n )\n```\n\n## 工作流程\n\n### 执行流程图\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as SandboxAgent\n participant Runtime as SandboxRuntime\n participant Sandbox as Sandbox Backend\n participant Workspace as Workspace\n\n User->>Agent: 启动代理\n Agent->>Runtime: 初始化沙箱\n Runtime->>Sandbox: 创建会话\n Sandbox->>Workspace: 注入 Manifest\n Workspace-->>Sandbox: 工作区就绪\n Sandbox-->>Runtime: 会话建立\n Runtime-->>Agent: 沙箱就绪\n Agent->>Runtime: 执行任务\n Runtime->>Workspace: 文件操作\n Runtime->>Sandbox: Shell 命令\n Workspace-->>Runtime: 结果\n Sandbox-->>Runtime: 输出\n Runtime-->>Agent: 任务结果\n Agent-->>User: 最终输出\n```\n\n### Manifest 处理流程\n\n1. **Manifest 验证**：检查 Manifest 配置的有效性\n2. **文件注入**：将 Manifest 中定义的文件注入到工作区\n3. **环境设置**：配置环境变量和初始化命令\n4. **路径解析**：验证所有路径都在工作区根目录内\n\n资料来源：[src/agents/sandbox/util/tar_utils.py:1-50]()\n\n## 多后端支持\n\n框架支持多种沙箱后端实现，开发者可以根据需求选择合适的后端。\n\n### 支持的后端\n\n| 后端 | 说明 | 特点 |\n|------|------|------|\n| E2B | 云端沙箱服务 | 成熟稳定，支持 PTY |\n| Modal | Modal 平台沙箱 | 支持持久化工作区 |\n| Cloudflare | Cloudflare 沙箱 | 支持云存储挂载 |\n| Blaxel | Blaxel 平台 | 支持 Drive 挂载 |\n| Vercel | Vercel 平台 | 支持 Node.js 运行时 |\n| Daytona | Daytona 沙箱 | 轻量级方案 |\n\n资料来源：[examples/sandbox/extensions/README.md:1-100]()\n\n### 后端选择示例\n\n```python\n# 使用 E2B 后端\nsandbox = Sandbox(backend=\"e2b\")\n\n# 使用 Modal 后端\nsandbox = Sandbox(backend=\"modal\")\n\n# 使用自定义后端\nfrom agents.sandbox.backends.modal import ModalSandbox\nsandbox = ModalSandbox(\n app_name=\"my-sandbox\",\n workspace_persistence=\"snapshot\"\n)\n```\n\n## 工具集成\n\n### 沙箱代理与工具的结合\n\n沙箱 Agent 可以与其他框架工具结合使用，实现更复杂的功能。\n\n```python\nfrom agents import SandboxAgent, Runner, function_tool\n\n@function_tool\ndef get_external_data(query: str) -> str:\n \"\"\"获取外部数据源\"\"\"\n return f\"External data for: {query}\"\n\nasync def main():\n sandbox = Sandbox()\n \n agent = SandboxAgent(\n name=\"研究助手\",\n instructions=\"结合外部数据和沙箱内文件完成研究任务\",\n sandbox=sandbox,\n tools=[get_external_data],\n )\n \n result = await Runner.run(\n agent, \n \"分析沙箱中的数据并结合外部信息源给出建议\"\n )\n```\n\n资料来源：[examples/sandbox/sandbox_agent_with_tools.py]()\n\n### 工作区能力\n\n沙箱 Agent 可以配置工作区能力（Workspace Capabilities），以更精细地控制代理的操作范围。\n\n```python\nfrom agents.sandbox.capabilities import (\n WorkspaceCapabilities,\n BashCapability,\n FileReadCapability,\n)\n\ncapabilities = WorkspaceCapabilities(\n tools=[\n BashCapability(timeout=30),\n FileReadCapability(allowed_paths=[\"/workspace/data\"]),\n ],\n)\n\nsandbox = Sandbox(capabilities=capabilities)\n```\n\n资料来源：[src/agents/sandbox/capabilities/capabilities.py]()\n\n## 安全机制\n\n### 路径安全\n\n框架实现了多层路径安全检查，防止路径遍历攻击：\n\n1. **根目录限制**：所有文件操作必须在工作区根目录下\n2. **符号链接检查**：禁止通过符号链接访问工作区外的路径\n3. **符号链接验证**：检查 tar 包中的符号链接是否安全\n\n```python\ndef validate_tarfile(\n tar: tarfile.TarFile,\n *,\n reject_symlink_rel_paths: Iterable[str | Path] = (),\n skip_rel_paths: Iterable[str | Path] = (),\n root_name: str | None = None,\n allow_symlinks: bool = True,\n allow_external_symlink_targets: bool = True,\n) -> None:\n # 检查路径是否逃逸根目录\n # 验证符号链接安全性\n```\n\n资料来源：[src/agents/sandbox/util/tar_utils.py:50-100]()\n\n### 执行权限控制\n\n- **命令白名单**：可以配置允许执行的命令列表\n- **超时控制**：防止无限循环或长时间运行\n- **资源限制**：限制 CPU、内存使用\n\n## 持久化与快照\n\n### 工作区持久化\n\n沙箱支持多种工作区持久化策略：\n\n| 策略 | 说明 | 适用场景 |\n|------|------|----------|\n| `tar` | 打包保存为 tar 文件 | 完整保存和传输 |\n| `snapshot` | 创建快照 | 快速恢复 |\n| `snapshot_filesystem` | 文件系统快照 | 大型工作区 |\n| `snapshot_directory` | 目录快照 | 简单场景 |\n\n```python\nsandbox = Sandbox(\n workspace_persistence=\"tar\",\n workspace_persistence_path=\"/path/to/save\"\n)\n```\n\n### 远程快照\n\n支持从远程快照启动沙箱：\n\n```python\nsandbox = Sandbox(\n snapshot_url=\"https://storage.example.com/snapshots/snapshot-001.tar\"\n)\n```\n\n资料来源：[examples/sandbox/sandbox_agent_with_remote_snapshot.py]()\n\n## 应用场景\n\n### 数据分析\n\n沙箱可以用于安全地分析敏感数据：\n\n```mermaid\ngraph LR\n A[敏感数据] --> B[沙箱环境]\n B --> C[数据处理]\n C --> D[分析结果]\n D --> E[报告输出]\n```\n\n**示例流程：**\n\n1. 将数据文件注入沙箱 Manifest\n2. 在隔离环境中执行数据分析代码\n3. 导出分析结果而不暴露原始数据\n\n资料来源：[examples/sandbox/tutorials/dataroom_metric_extract/README.md:1-30]()\n\n### 代码审查\n\n沙箱可用于自动化的代码审查任务：\n\n```mermaid\ngraph TD\n A[代码仓库] --> B[沙箱环境]\n B --> C[克隆代码]\n C --> D[运行审查工具]\n D --> E[生成报告]\n E --> F[修复建议]\n```\n\n资料来源：[examples/sandbox/tutorials/repo_code_review/README.md:1-25]()\n\n### 自动化测试\n\n沙箱提供隔离环境用于执行测试：\n\n- 隔离测试环境，避免污染宿主系统\n- 支持多种编程语言和测试框架\n- 自动收集测试结果和覆盖率报告\n\n## 配置选项\n\n### Sandbox 构造函数参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `backend` | str | \"e2b\" | 沙箱后端类型 |\n| `manifest` | Manifest | None | 工作区清单 |\n| `capabilities` | Capabilities | None | 能力配置 |\n| `timeout` | int | 300 | 超时时间（秒） |\n| `workspace_persistence` | str | None | 持久化策略 |\n| `workspace_persistence_path` | str | None | 持久化路径 |\n\n### 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥（必需） |\n| `E2B_API_KEY` | E2B 服务密钥 |\n| `MODAL_TOKEN_ID` | Modal Token ID |\n| `MODAL_TOKEN_SECRET` | Modal Token Secret |\n| `CLOUDFLARE_SANDBOX_API_KEY` | Cloudflare API 密钥 |\n\n## 最佳实践\n\n### 1. Manifest 优化\n\n- 仅注入必要的文件，减少启动时间\n- 使用 `.dockerignore` 类似规则排除不相关文件\n- 合理设置初始化命令，避免重复安装\n\n### 2. 安全性考虑\n\n- 始终设置合理的超时时间\n- 使用路径白名单限制文件访问\n- 避免在 Manifest 中包含敏感信息\n\n### 3. 性能优化\n\n- 对于重复任务，使用快照恢复而非重新初始化\n- 合理配置并发沙箱数量\n- 使用轻量级后端（如 Daytona）处理简单任务\n\n### 4. 调试技巧\n\n```python\n# 启用详细日志\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\n# 使用暂停模式检查状态\nsandbox = Sandbox(pause_on_exit=True)\n\n# 查看沙箱输出\nresult = await Runner.run(agent, \"ls -la\", stream=True)\n```\n\n## 扩展开发\n\n### 自定义后端\n\n开发者可以实现 `SandboxBackend` 接口来添加新的沙箱后端：\n\n```python\nfrom agents.sandbox.backends.base import SandboxBackend\n\nclass MyCustomSandbox(SandboxBackend):\n async def create_session(self, manifest: Manifest) -> SandboxSession:\n # 实现自定义会话创建逻辑\n pass\n \n async def execute(self, command: str) -> ExecutionResult:\n # 实现命令执行逻辑\n pass\n```\n\n### 自定义能力\n\n扩展沙箱能力以支持特定工具：\n\n```python\nfrom agents.sandbox.capabilities import BaseCapability\n\nclass CustomCapability(BaseCapability):\n name = \"custom_tool\"\n description = \"自定义工具\"\n \n def get_tools(self) -> list[FunctionTool]:\n return [self.custom_function_tool]\n```\n\n## 相关资源\n\n- [沙箱基础示例](examples/sandbox/basic.py)\n- [沙箱扩展后端](examples/sandbox/extensions/README.md)\n- [沙箱教程 - 数据提取](examples/sandbox/tutorials/dataroom_metric_extract/README.md)\n- [沙箱教程 - 代码审查](examples/sandbox/tutorials/repo_code_review/README.md)\n- [沙箱教程 - 视觉网站克隆](examples/sandbox/tutorials/vision_website_clone/README.md)\n\n---\n\n\n\n## 沙箱会话管理\n\n### 相关页面\n\n相关主题：[沙箱 Agent 概述](#sandbox-agent)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agents/sandbox/session/sandbox_session.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/session/sandbox_session.py)\n- [src/agents/sandbox/session/base_sandbox_session.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/session/base_sandbox_session.py)\n- [src/agents/sandbox/session/manager.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/session/manager.py)\n- [src/agents/sandbox/snapshot.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/snapshot.py)\n- [src/agents/sandbox/files.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/files.py)\n- [src/agents/sandbox/entries/artifacts.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/sandbox/entries/artifacts.py)\n \n\n# 沙箱会话管理\n\n## 概述\n\n沙箱会话管理是 openai-agents-python 框架中用于隔离执行 AI Agent 操作的核心子系统。它为每个 Agent 提供独立的虚拟工作空间，支持文件操作、命令执行、状态持久化以及工作区快照功能。沙箱机制确保 Agent 的操作不会影响主机系统安全，同时提供灵活的资源管理和跨后端支持。\n\n## 核心架构\n\n### 组件层次结构\n\n沙箱会话管理系统由以下核心组件构成：\n\n```mermaid\ngraph TD\n A[沙箱管理器 SessionManager] --> B[基础会话 BaseSandboxSession]\n B --> C[沙箱会话 SandboxSession]\n B --> D[工作区管理 FilesManager]\n B --> E[快照管理 SnapshotManager]\n C --> F[工件管理 ArtifactsManager]\n B --> G[后端实现 UnixLocal Cloudflare E2B Modal Vercel Daytona]\n```\n\n### 核心组件说明\n\n| 组件 | 文件位置 | 职责 |\n|------|---------|------|\n| `SessionManager` | `src/agents/sandbox/session/manager.py` | 管理多个沙箱会话的生命周期、创建和销毁 |\n| `BaseSandboxSession` | `src/agents/sandbox/session/base_sandbox_session.py` | 定义所有沙箱后端的抽象接口 |\n| `SandboxSession` | `src/agents/sandbox/session/sandbox_session.py` | 提供具体的工作区操作实现 |\n| `FilesManager` | `src/agents/sandbox/files.py` | 处理工作区的文件读写操作 |\n| `SnapshotManager` | `src/agents/sandbox/snapshot.py` | 管理工作区的快照保存和恢复 |\n\n## 会话生命周期管理\n\n### 创建流程\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant SessionManager\n participant BaseSandboxSession\n participant 后端实现\n participant Workspace\n\n 用户->>SessionManager: 创建会话请求\n SessionManager->>BaseSandboxSession: 初始化沙箱后端\n BaseSandboxSession->>后端实现: 创建沙箱实例\n 后端实现->>Workspace: 准备工作区\n Workspace-->>BaseSandboxSession: 工作区就绪\n BaseSandboxSession-->>SessionManager: 返回会话对象\n SessionManager-->>用户: 会话可用\n```\n\n### 核心方法\n\n沙箱会话提供以下核心生命周期方法：\n\n| 方法 | 功能 | 资料来源 |\n|------|------|---------|\n| `create()` | 创建新的沙箱会话实例 | `manager.py:1-50` |\n| `close()` | 关闭并清理沙箱资源 | `manager.py:50-80` |\n| `persist_workspace()` | 持久化当前工作区状态 | `base_sandbox_session.py:100-150` |\n| `hydrate_workspace()` | 从归档恢复工作区 | `unix_local.py:200-250` |\n\n## 工作区管理\n\n### 工作区文件系统\n\n沙箱工作区采用分层目录结构：\n\n```mermaid\ngraph TD\n Workspace[\"工作区根目录\"]\n Workspace --> Manifest[\"Manifest 定义\"]\n Workspace --> Scratch[\"临时文件目录\"]\n Workspace --> Output[\"输出产物目录\"]\n \n Manifest --> Binaries[\"二进制文件\"]\n Manifest --> SourceFiles[\"源码文件\"]\n Manifest --> ConfigFiles[\"配置文件\"]\n```\n\n### 文件操作接口\n\n`FilesManager` 类提供统一的工作区文件操作接口，资料来源：`src/agents/sandbox/files.py`\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `write()` | `path`, `content` | `None` | 写入文件内容 |\n| `read()` | `path` | `str` | 读取文件内容 |\n| `list()` | `path` | `list[Path]` | 列出目录内容 |\n| `delete()` | `path` | `None` | 删除文件或目录 |\n| `exists()` | `path` | `bool` | 检查路径是否存在 |\n\n### 安全机制\n\n系统实现了多层安全防护来防止路径遍历攻击：\n\n- **符号链接检查**：验证归档中的符号链接不会指向工作区外部 资料来源：`src/agents/sandbox/util/tar_utils.py:50-80`\n- **相对路径验证**：所有操作路径必须相对于工作区根目录\n- **根目录隔离**：确保文件操作被限制在工作区范围内\n\n```python\n# 安全路径验证示例\ndef validate_path_safety(dest: Path, root: Path) -> None:\n root_resolved = root.resolve()\n dest_resolved = dest.resolve()\n if not dest_resolved.is_relative_to(root_resolved):\n raise UnsafeTarMemberError(...)\n```\n\n## 快照管理系统\n\n### 快照类型\n\n快照系统支持两种主要模式：\n\n| 快照类型 | 用途 | 持久化方式 |\n|---------|------|-----------|\n| `SnapshotBase` | 完整工作区镜像 | 文件系统或远程存储 |\n| `SnapshotSpec` | 工作区配置规范 | 仅元数据 |\n\n### 快照操作流程\n\n```mermaid\ngraph LR\n A[创建快照] --> B[序列化工作区]\n B --> C[压缩为Tarball]\n C --> D[存储快照]\n D --> E[返回快照ID]\n \n F[恢复快照] --> G[获取快照数据]\n G --> H[解压到工作区]\n H --> I[验证完整性]\n I --> J[会话恢复]\n```\n\n资料来源：`src/agents/sandbox/snapshot.py`\n\n### 快照恢复机制\n\n```python\nasync def hydrate_workspace(self, data: io.IOBase) -> None:\n root = Path(self.state.manifest.root)\n root.mkdir(parents=True, exist_ok=True)\n with tarfile.open(fileobj=data, mode=\"r:*\") as tar:\n safe_extract_tarfile(tar, root=root, ...)\n```\n\n## 工件管理系统\n\n### 工件类型\n\n`ArtifactsManager` 负责管理沙箱会话生成的可交付产物，资料来源：`src/agents/sandbox/entries/artifacts.py`\n\n| 类型 | 描述 | 典型用途 |\n|------|------|---------|\n| `FileArtifact` | 单个文件产物 | 生成的代码、文档 |\n| `DirectoryArtifact` | 目录结构 | 项目输出、构建产物 |\n| `ArtifactBatch` | 批量产物 | 多文件导出 |\n\n### 工件生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 生成中: Agent 执行操作\n 生成中 --> 验证中: 写入完成\n 验证中 --> 已确认: 通过验证\n 验证中 --> 失败: 验证失败\n 已确认 --> [*]: 会话结束\n 失败 --> [*]: 错误报告\n```\n\n## 错误处理\n\n### 错误类层次结构\n\n```mermaid\ngraph TD\n SandboxError --> SandboxRuntimeError\n SandboxRuntimeError --> WorkspaceIOError\n SandboxRuntimeError --> ApplyPatchError\n SandboxError --> PTYSessionNotFoundError\n SandboxError --> UnsafeTarMemberError\n```\n\n### 核心错误类\n\n| 错误类 | 错误码 | 说明 |\n|-------|--------|------|\n| `WorkspaceArchiveWriteError` | `WORKSPACE_ARCHIVE_WRITE_ERROR` | 工作区归档写入失败 |\n| `ApplyPatchPathError` | `APPLY_PATCH_INVALID_PATH` | 路径验证失败 |\n| `UnsafeTarMemberError` | `UNSAFE_TAR_MEMBER` | Tar 归档包含不安全成员 |\n| `PTYSessionNotFoundError` | `PTY_SESSION_NOT_FOUND` | PTY 会话不存在 |\n\n资料来源：`src/agents/sandbox/errors.py:1-100`\n\n## 多后端支持\n\n### 后端实现矩阵\n\n| 后端 | 后端ID | 特点 | 部署方式 |\n|------|--------|------|---------|\n| UnixLocal | `unix_local` | 本地进程隔离 | 本地开发 |\n| E2B | `e2b` | 云端沙箱 | 远程服务 |\n| Cloudflare | `cloudflare` | 边缘计算 | 云端 Workers |\n| Modal | `modal` | Serverless 函数 | 按需计算 |\n| Vercel | `vercel` | 边缘部署 | Edge Runtime |\n| Daytona | `daytona` | 容器化隔离 | 容器环境 |\n\n### 后端统一接口\n\n所有后端必须实现以下核心方法：\n\n```python\nclass BaseSandboxClient(Generic[TSandboxClientOptions]):\n backend_id: str\n supports_default_options: bool\n \n async def create(\n self,\n *,\n snapshot: SnapshotSpec | SnapshotBase | None = None,\n manifest: Manifest | None = None,\n options: TSandboxClientOptions | None = None,\n ) -> SandboxSession: ...\n```\n\n资料来源：`src/agents/sandbox/sandboxes/unix_local.py:100-150`\n\n## 配置选项\n\n### 沙箱会话选项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `timeout` | `int` | `300` | 执行超时时间(秒) |\n| `memory` | `int` | `1024` | 内存限制(MB) |\n| `cpu` | `float` | `1.0` | CPU 核心数 |\n| `image` | `str` | `None` | 容器镜像名称 |\n| `region` | `str` | `None` | 部署区域 |\n\n### 环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| `OPENAI_API_KEY` | 是 | OpenAI API 密钥 |\n| `E2B_API_KEY` | E2B后端 | E2B 服务密钥 |\n| `CLOUDFLARE_SANDBOX_API_KEY` | Cloudflare后端 | Cloudflare 服务密钥 |\n\n## 最佳实践\n\n### 会话管理建议\n\n1. **生命周期控制**：始终使用上下文管理器或显式调用 `close()` 确保资源释放\n2. **超时设置**：根据 Agent 任务复杂度合理设置 timeout 参数\n3. **状态持久化**：长时间任务应定期调用 `persist_workspace()` 保存进度\n4. **错误处理**：捕获 `SandboxRuntimeError` 并实现重试逻辑\n\n### 性能优化\n\n- **批量操作**：合并多个文件写入操作减少 I/O 开销\n- **快照策略**：仅在必要时创建完整快照，使用增量更新\n- **资源清理**：会话结束后及时清理临时文件和符号链接\n\n## 相关文档\n\n- [沙箱示例](../examples/sandbox/README.md)\n- [云端沙箱扩展](../examples/sandbox/extensions/README.md)\n- [医疗支持示例](../examples/sandbox/healthcare_support/README.md)\n- [视觉网站克隆教程](../examples/sandbox/tutorials/vision_website_clone/README.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：openai/openai-agents-python\n\n摘要：发现 24 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `openai-agents-python` 与安装入口 `openai-agents` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install openai-agents`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:946380199 | https://github.com/openai/openai-agents-python | repo=openai-agents-python; install=openai-agents\n\n## 2. 配置坑 · 来源证据：AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the base table\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the base table\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d867c75f80af49c9968398851ff8bf6a | https://github.com/openai/openai-agents-python/issues/3346 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：Clarify whether retry-after delays should respect retry max_delay\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Clarify whether retry-after delays should respect retry max_delay\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f486d2247bf24df8bbc7a2bd6fddbd65 | https://github.com/openai/openai-agents-python/issues/3266 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：OpenAIConversationsSession persists empty reasoning item {\"type\":\"reasoning\",\"summary\":[]} and Conversations API reject…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenAIConversationsSession persists empty reasoning item {\"type\":\"reasoning\",\"summary\":[]} and Conversations API rejects it as invalid\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d6bad5c23bf3457eb546c22a1636cc26 | https://github.com/openai/openai-agents-python/issues/3268 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Tracing shutdown cannot interrupt exporter retry backoff\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Tracing shutdown cannot interrupt exporter retry backoff\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e1ceae098cf84c8aafae7082b13c5345 | https://github.com/openai/openai-agents-python/issues/3354 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 来源证据：v0.15.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.15.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b73472b5ae90447199984775aacdca67 | https://github.com/openai/openai-agents-python/releases/tag/v0.15.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 来源证据：v0.15.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.15.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7e05a382001a4d07b74eda1e1316320b | https://github.com/openai/openai-agents-python/releases/tag/v0.15.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：v0.16.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.16.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_44335088ff52486e9f2f41f72a274c35 | https://github.com/openai/openai-agents-python/releases/tag/v0.16.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 来源证据：v0.17.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.17.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_86b81f310a6e45feadc65196a057b23b | https://github.com/openai/openai-agents-python/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 来源证据：v0.15.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.15.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4c70d563ac704aeaa14b8e2c49976bc5 | https://github.com/openai/openai-agents-python/releases/tag/v0.15.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 能力坑 · 能力判断依赖假设\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:946380199 | https://github.com/openai/openai-agents-python | README/documentation is current enough for a first validation pass.\n\n## 12. 运行坑 · 来源证据：v0.14.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.14.8\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a31947cfee3a4299923f7714bfb54f42 | https://github.com/openai/openai-agents-python/releases/tag/v0.14.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 维护坑 · 来源证据：AdvancedSQLiteSession.add_items can report success after structure metadata failure\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：AdvancedSQLiteSession.add_items can report success after structure metadata failure\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0fed2dd63d55400d9e0d9adaf08570e5 | https://github.com/openai/openai-agents-python/issues/3348 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 来源证据：Chat Completions converter can send empty tool output for non-text results\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Chat Completions converter can send empty tool output for non-text results\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_34a35e920a01467e957cdd59b4179cc1 | https://github.com/openai/openai-agents-python/issues/3310 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. 维护坑 · 来源证据：v0.15.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.15.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_33cd0193aea84f9b82b15a02098d85cd | https://github.com/openai/openai-agents-python/releases/tag/v0.15.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:946380199 | https://github.com/openai/openai-agents-python | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:946380199 | https://github.com/openai/openai-agents-python | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在安全注意事项\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:946380199 | https://github.com/openai/openai-agents-python | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 19. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:946380199 | https://github.com/openai/openai-agents-python | no_demo; severity=medium\n\n## 20. 安全/权限坑 · 来源证据：Proposal: per-run BudgetGuard for token / request / cost limits (follow-up to #2848)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Proposal: per-run BudgetGuard for token / request / cost limits (follow-up to #2848)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_00884163bb274aecb62eeff18df12634 | https://github.com/openai/openai-agents-python/issues/3353 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：v0.16.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.16.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a9d11d6b8fd24b22882ee03998b45d63 | https://github.com/openai/openai-agents-python/releases/tag/v0.16.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 22. 安全/权限坑 · 来源证据：v0.17.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.17.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d47be3955c747baadea812c5f4c6487 | https://github.com/openai/openai-agents-python/releases/tag/v0.17.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 23. 维护坑 · 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:946380199 | https://github.com/openai/openai-agents-python | issue_or_pr_quality=unknown\n\n## 24. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:946380199 | https://github.com/openai/openai-agents-python | 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项目：openai/openai-agents-python\n\n摘要：发现 24 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `openai-agents-python` 与安装入口 `openai-agents` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install openai-agents`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:946380199 | https://github.com/openai/openai-agents-python | repo=openai-agents-python; install=openai-agents\n\n## 2. 配置坑 · 来源证据：AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the base table\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AdvancedSQLiteSession.delete_branch() leaves branch-only messages in the base table\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d867c75f80af49c9968398851ff8bf6a | https://github.com/openai/openai-agents-python/issues/3346 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：Clarify whether retry-after delays should respect retry max_delay\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Clarify whether retry-after delays should respect retry max_delay\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f486d2247bf24df8bbc7a2bd6fddbd65 | https://github.com/openai/openai-agents-python/issues/3266 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 来源证据：OpenAIConversationsSession persists empty reasoning item {\"type\":\"reasoning\",\"summary\":[]} and Conversations API reject…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenAIConversationsSession persists empty reasoning item {\"type\":\"reasoning\",\"summary\":[]} and Conversations API rejects it as invalid\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d6bad5c23bf3457eb546c22a1636cc26 | https://github.com/openai/openai-agents-python/issues/3268 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Tracing shutdown cannot interrupt exporter retry backoff\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Tracing shutdown cannot interrupt exporter retry backoff\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e1ceae098cf84c8aafae7082b13c5345 | https://github.com/openai/openai-agents-python/issues/3354 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 来源证据：v0.15.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.15.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b73472b5ae90447199984775aacdca67 | https://github.com/openai/openai-agents-python/releases/tag/v0.15.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 来源证据：v0.15.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.15.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7e05a382001a4d07b74eda1e1316320b | https://github.com/openai/openai-agents-python/releases/tag/v0.15.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：v0.16.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.16.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_44335088ff52486e9f2f41f72a274c35 | https://github.com/openai/openai-agents-python/releases/tag/v0.16.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 来源证据：v0.17.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.17.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_86b81f310a6e45feadc65196a057b23b | https://github.com/openai/openai-agents-python/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 来源证据：v0.15.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.15.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4c70d563ac704aeaa14b8e2c49976bc5 | https://github.com/openai/openai-agents-python/releases/tag/v0.15.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 能力坑 · 能力判断依赖假设\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:946380199 | https://github.com/openai/openai-agents-python | README/documentation is current enough for a first validation pass.\n\n## 12. 运行坑 · 来源证据：v0.14.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.14.8\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a31947cfee3a4299923f7714bfb54f42 | https://github.com/openai/openai-agents-python/releases/tag/v0.14.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 维护坑 · 来源证据：AdvancedSQLiteSession.add_items can report success after structure metadata failure\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：AdvancedSQLiteSession.add_items can report success after structure metadata failure\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0fed2dd63d55400d9e0d9adaf08570e5 | https://github.com/openai/openai-agents-python/issues/3348 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 来源证据：Chat Completions converter can send empty tool output for non-text results\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Chat Completions converter can send empty tool output for non-text results\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_34a35e920a01467e957cdd59b4179cc1 | https://github.com/openai/openai-agents-python/issues/3310 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 15. 维护坑 · 来源证据：v0.15.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.15.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_33cd0193aea84f9b82b15a02098d85cd | https://github.com/openai/openai-agents-python/releases/tag/v0.15.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:946380199 | https://github.com/openai/openai-agents-python | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:946380199 | https://github.com/openai/openai-agents-python | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在安全注意事项\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:946380199 | https://github.com/openai/openai-agents-python | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 19. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:946380199 | https://github.com/openai/openai-agents-python | no_demo; severity=medium\n\n## 20. 安全/权限坑 · 来源证据：Proposal: per-run BudgetGuard for token / request / cost limits (follow-up to #2848)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Proposal: per-run BudgetGuard for token / request / cost limits (follow-up to #2848)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_00884163bb274aecb62eeff18df12634 | https://github.com/openai/openai-agents-python/issues/3353 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：v0.16.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.16.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a9d11d6b8fd24b22882ee03998b45d63 | https://github.com/openai/openai-agents-python/releases/tag/v0.16.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 22. 安全/权限坑 · 来源证据：v0.17.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.17.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d47be3955c747baadea812c5f4c6487 | https://github.com/openai/openai-agents-python/releases/tag/v0.17.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 23. 维护坑 · 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:946380199 | https://github.com/openai/openai-agents-python | issue_or_pr_quality=unknown\n\n## 24. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:946380199 | https://github.com/openai/openai-agents-python | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# openai-agents-python - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 openai-agents-python 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的流程自动化任务。\n我常用的宿主 AI：chatgpt\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. overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. quickstart：快速开始指南。围绕“快速开始指南”模拟一次用户任务，不展示安装或运行结果。\n3. core-concepts：核心概念。围绕“核心概念”模拟一次用户任务，不展示安装或运行结果。\n4. agent-core：Agent 核心框架。围绕“Agent 核心框架”模拟一次用户任务，不展示安装或运行结果。\n5. tools：工具系统。围绕“工具系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quickstart\n输入：用户提供的“快速开始指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. core-concepts\n输入：用户提供的“核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. agent-core\n输入：用户提供的“Agent 核心框架”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. tools\n输入：用户提供的“工具系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / quickstart：Step 2 必须围绕“快速开始指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / core-concepts：Step 3 必须围绕“核心概念”形成一个小中间产物，并等待用户确认。\n- Step 4 / agent-core：Step 4 必须围绕“Agent 核心框架”形成一个小中间产物，并等待用户确认。\n- Step 5 / tools：Step 5 必须围绕“工具系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/openai/openai-agents-python\n- https://github.com/openai/openai-agents-python#readme\n- .agents/skills/code-change-verification/SKILL.md\n- .agents/skills/docs-sync/SKILL.md\n- .agents/skills/examples-auto-run/SKILL.md\n- .agents/skills/final-release-review/SKILL.md\n- .agents/skills/implementation-strategy/SKILL.md\n- .agents/skills/openai-knowledge/SKILL.md\n- .agents/skills/pr-draft-summary/SKILL.md\n- .agents/skills/runtime-behavior-probe/SKILL.md\n- .agents/skills/test-coverage-improver/SKILL.md\n- examples/sandbox/docs/skills/credit-note-fixer/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 openai-agents-python 的核心服务。\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项目：openai/openai-agents-python\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install openai-agents\n```\n\n来源：https://github.com/openai/openai-agents-python#readme\n\n## 来源\n\n- repo: https://github.com/openai/openai-agents-python\n- docs: https://github.com/openai/openai-agents-python#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_a44f7347bf66437e874a64a265e0fceb"
}