{
"canonical_name": "openai/openai-agents-js",
"compilation_id": "pack_5c56606bb2d84ea7a00e86c816c371b5",
"created_at": "2026-05-19T07:24:50.774088+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 `npm 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": "npm install @openai/agents",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_fd8d2bee09b748119edad6c045dbf9f0"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_60fdd071c559b644c3d053afcbc973ac",
"canonical_name": "openai/openai-agents-js",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/openai/openai-agents-js",
"slug": "openai-agents-js",
"source_packet_id": "phit_594733dbd6b2480fb8abe5f2c1a7d7cd",
"source_validation_id": "dval_536af9c378e94ca28f7c1cd57210eead"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 chatgpt的用户",
"github_forks": 767,
"github_stars": 3047,
"one_liner_en": "A lightweight, powerful framework for multi-agent workflows and voice agents",
"one_liner_zh": "A lightweight, powerful framework for multi-agent workflows and voice agents",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "semantic truth gate rework constraint"
},
"target_user": "使用 chatgpt 等宿主 AI 的用户",
"title_en": "openai-agents-js",
"title_zh": "openai-agents-js 能力包",
"visible_tags": [
{
"label_en": "AI Agent Framework",
"label_zh": "AI Agent 框架",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-ai-agent-framework",
"type": "product_domain"
},
{
"label_en": "Agent SDK",
"label_zh": "Agent SDK",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-agent-sdk",
"type": "user_job"
},
{
"label_en": "Tool Calling",
"label_zh": "工具调用",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-tool-calling",
"type": "core_capability"
},
{
"label_en": "Handoffs",
"label_zh": "Handoff",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-handoffs",
"type": "workflow_pattern"
},
{
"label_en": "Guardrails and Tracing",
"label_zh": "Guardrail 与 Tracing",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-guardrails-and-tracing",
"type": "selection_signal"
}
]
},
"packet_id": "phit_594733dbd6b2480fb8abe5f2c1a7d7cd",
"page_model": {
"artifacts": {
"artifact_slug": "openai-agents-js",
"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": "npm install @openai/agents",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/openai/openai-agents-js#readme",
"verified": true
}
],
"display_tags": [
"AI Agent 框架",
"Agent SDK",
"工具调用",
"Handoff",
"Guardrail 与 Tracing"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 chatgpt的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "A lightweight, powerful framework for multi-agent workflows and voice agents"
},
{
"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-js` 与安装入口 `@openai/agents` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:993521808 | https://github.com/openai/openai-agents-js | repo=openai-agents-js; install=@openai/agents"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "Developers should check this installation risk before relying on the project: v0.10.0",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_0017083f7c144b8b8068b1aa812f1798 | https://github.com/openai/openai-agents-js/releases/tag/v0.10.0 | v0.10.0"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v0.10.0. Context: Observed when using node, python",
"title": "失败模式：installation: v0.10.0",
"user_impact": "Upgrade or migration may change expected behavior: v0.10.0"
},
{
"body": "Developers should check this installation risk before relying on the project: v0.11.2",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_cbb13be7191292a101a93f89e2c40ad3 | https://github.com/openai/openai-agents-js/releases/tag/v0.11.2 | v0.11.2"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v0.11.2. Context: Observed when using node, python",
"title": "失败模式：installation: v0.11.2",
"user_impact": "Upgrade or migration may change expected behavior: v0.11.2"
},
{
"body": "Developers should check this configuration risk before relying on the project: v0.9.0",
"category": "配置坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_742498adc1555b1770e9377463c11ff4 | https://github.com/openai/openai-agents-js/releases/tag/v0.9.0 | v0.9.0"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v0.9.0. Context: Observed when using docker",
"title": "失败模式：configuration: v0.9.0",
"user_impact": "Upgrade or migration may change expected behavior: v0.9.0"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:993521808 | https://github.com/openai/openai-agents-js | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "Developers should check this runtime risk before relying on the project: Large realtime audio buffers can crash during base64 encoding",
"category": "运行坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_aaf4394591e72954462f8a949be29aee | https://github.com/openai/openai-agents-js/issues/1333 | Large realtime audio buffers can crash during base64 encoding",
"failure_mode_cluster:github_issue | fmev_dfcff51166e62ba4cc81679f3c9c2f18 | https://github.com/openai/openai-agents-js/issues/1333 | Large realtime audio buffers can crash during base64 encoding"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Large realtime audio buffers can crash during base64 encoding. Context: Observed when using node",
"title": "失败模式：runtime: Large realtime audio buffers can crash during base64 encoding",
"user_impact": "Developers may hit a documented source-backed failure mode: Large realtime audio buffers can crash during base64 encoding"
},
{
"body": "Developers should check this runtime risk before relying on the project: v0.11.4",
"category": "运行坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_73a57d6e6bb4c1e93cea0e78313774b1 | https://github.com/openai/openai-agents-js/releases/tag/v0.11.4 | v0.11.4"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v0.11.4. Context: Source discussion did not expose a precise runtime context.",
"title": "失败模式：runtime: v0.11.4",
"user_impact": "Upgrade or migration may change expected behavior: v0.11.4"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Large realtime audio buffers can crash during base64 encoding",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_1f01240eec894a519476aebd4a7590db | https://github.com/openai/openai-agents-js/issues/1333 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Large realtime audio buffers can crash during base64 encoding",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "Developers should check this migration risk before relying on the project: v0.9.1",
"category": "维护坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_e351743729d2a86ad6987f1baefae665 | https://github.com/openai/openai-agents-js/releases/tag/v0.9.1 | v0.9.1"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v0.9.1. Context: Observed during version upgrade or migration.",
"title": "失败模式：migration: v0.9.1",
"user_impact": "Upgrade or migration may change expected behavior: v0.9.1"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:993521808 | https://github.com/openai/openai-agents-js | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:993521808 | https://github.com/openai/openai-agents-js | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:993521808 | https://github.com/openai/openai-agents-js | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:993521808 | https://github.com/openai/openai-agents-js | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:993521808 | https://github.com/openai/openai-agents-js | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
},
{
"body": "Developers should check this maintenance risk before relying on the project: v0.10.1",
"category": "维护坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_21fc49454e8260a68f620eef5031497f | https://github.com/openai/openai-agents-js/releases/tag/v0.10.1 | v0.10.1"
],
"severity": "low",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v0.10.1. Context: Source discussion did not expose a precise runtime context.",
"title": "失败模式：maintenance: v0.10.1",
"user_impact": "Upgrade or migration may change expected behavior: v0.10.1"
},
{
"body": "Developers should check this maintenance risk before relying on the project: v0.11.0",
"category": "维护坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_46b242251b25a22b32eeb2d3e132ab09 | https://github.com/openai/openai-agents-js/releases/tag/v0.11.0 | v0.11.0"
],
"severity": "low",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v0.11.0. Context: Observed when using node",
"title": "失败模式：maintenance: v0.11.0",
"user_impact": "Upgrade or migration may change expected behavior: v0.11.0"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 89,
"forks": 767,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 3047
},
"source_url": "https://github.com/openai/openai-agents-js",
"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 and voice agents",
"title": "openai-agents-js 能力包",
"trial_prompt": "# openai-agents-js - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 openai-agents-js 的“安装前体验版”。\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. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-agents：Agent 核心机制。围绕“Agent 核心机制”模拟一次用户任务，不展示安装或运行结果。\n4. page-tools：工具系统。围绕“工具系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-sandbox-agents：沙箱 Agent。围绕“沙箱 Agent”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-agents\n输入：用户提供的“Agent 核心机制”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-tools\n输入：用户提供的“工具系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-sandbox-agents\n输入：用户提供的“沙箱 Agent”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-agents：Step 3 必须围绕“Agent 核心机制”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-tools：Step 4 必须围绕“工具系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-sandbox-agents：Step 5 必须围绕“沙箱 Agent”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/openai/openai-agents-js\n- https://github.com/openai/openai-agents-js#readme\n- .agents/skills/changeset-validation/SKILL.md\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/integration-tests/SKILL.md\n- .agents/skills/openai-knowledge/SKILL.md\n- .agents/skills/pnpm-upgrade/SKILL.md\n- .agents/skills/pr-draft-summary/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 openai-agents-js 的核心服务。\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: Large realtime audio buffers can crash during base64 encoding（https://github.com/openai/openai-agents-js/issues/1333）；github/github_issue: Large realtime audio buffers can crash during base64 encoding（https://github.com/openai/openai-agents-js/issues/1333）；github/github_release: v0.11.4（https://github.com/openai/openai-agents-js/releases/tag/v0.11.4）；github/github_release: v0.11.3（https://github.com/openai/openai-agents-js/releases/tag/v0.11.3）；github/github_release: v0.11.2（https://github.com/openai/openai-agents-js/releases/tag/v0.11.2）；github/github_release: v0.11.1（https://github.com/openai/openai-agents-js/releases/tag/v0.11.1）；github/github_release: v0.11.0（https://github.com/openai/openai-agents-js/releases/tag/v0.11.0）；github/github_release: v0.10.1（https://github.com/openai/openai-agents-js/releases/tag/v0.10.1）；github/github_release: v0.10.0（https://github.com/openai/openai-agents-js/releases/tag/v0.10.0）；github/github_release: v0.9.1（https://github.com/openai/openai-agents-js/releases/tag/v0.9.1）；github/github_release: v0.9.0（https://github.com/openai/openai-agents-js/releases/tag/v0.9.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Large realtime audio buffers can crash during base64 encoding",
"url": "https://github.com/openai/openai-agents-js/issues/1333"
},
{
"kind": "github_issue",
"source": "github",
"title": "Large realtime audio buffers can crash during base64 encoding",
"url": "https://github.com/openai/openai-agents-js/issues/1333"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.11.4",
"url": "https://github.com/openai/openai-agents-js/releases/tag/v0.11.4"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.11.3",
"url": "https://github.com/openai/openai-agents-js/releases/tag/v0.11.3"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.11.2",
"url": "https://github.com/openai/openai-agents-js/releases/tag/v0.11.2"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.11.1",
"url": "https://github.com/openai/openai-agents-js/releases/tag/v0.11.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.11.0",
"url": "https://github.com/openai/openai-agents-js/releases/tag/v0.11.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.10.1",
"url": "https://github.com/openai/openai-agents-js/releases/tag/v0.10.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.10.0",
"url": "https://github.com/openai/openai-agents-js/releases/tag/v0.10.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.9.1",
"url": "https://github.com/openai/openai-agents-js/releases/tag/v0.9.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.9.0",
"url": "https://github.com/openai/openai-agents-js/releases/tag/v0.9.0"
}
],
"status": "已收录 11 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "A lightweight, powerful framework for multi-agent workflows and voice agents",
"effort": "安装已验证",
"forks": 767,
"icon": "code",
"name": "openai-agents-js 能力包",
"risk": "可发布",
"slug": "openai-agents-js",
"stars": 3047,
"tags": [
"AI Agent 框架",
"Agent SDK",
"工具调用",
"Handoff",
"Guardrail 与 Tracing"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/openai/openai-agents-js 项目说明书\n\n生成时间：2026-05-17 12:58:06 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [系统架构](#page-architecture)\n- [Agent 核心机制](#page-agents)\n- [工具系统](#page-tools)\n- [Handoffs 与 Agent 委托](#page-handoffs)\n- [Guardrails 安全防护](#page-guardrails)\n- [沙箱 Agent](#page-sandbox-agents)\n- [沙箱运行时与容器](#page-sandbox-runtime)\n- [实时语音 Agent](#page-realtime-agents)\n- [传输层与集成](#page-transport-layer)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/openai/openai-agents-js/blob/main/README.md)\n- [examples/basic/README.md](https://github.com/openai/openai-agents-js/blob/main/examples/basic/README.md)\n- [examples/agent-patterns/README.md](https://github.com/openai/openai-agents-js/blob/main/examples/agent-patterns/README.md)\n- [examples/tools/README.md](https://github.com/openai/openai-agents-js/blob/main/examples/tools/README.md)\n- [examples/ai-sdk-ui/README.md](https://github.com/openai/openai-agents-js/blob/main/examples/ai-sdk-ui/README.md)\n- [packages/agents-extensions/README.md](https://github.com/openai/openai-agents-js/blob/main/packages/agents-extensions/README.md)\n- [packages/agents-core/src/agent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/agent.ts)\n- [packages/agents-core/src/tool.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/tool.ts)\n- [packages/agents-realtime/src/realtimeAgent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-realtime/src/realtimeAgent.ts)\n- [packages/agents-core/src/model.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/model.ts)\n \n\n# 项目介绍\n\n## 概述\n\nOpenAI Agents SDK（JavaScript/TypeScript 版本）是一个用于构建 AI Agent 的开发工具包，旨在帮助开发者快速构建、部署和管理智能代理应用。该 SDK 提供了完整的 Agent 生命周期管理、工具集成、流式输出、人类在环（Human-in-the-Loop）控制等功能。资料来源：[examples/basic/README.md:1]()\n\n## 核心架构\n\nOpenAI Agents SDK 采用模块化设计，由多个独立的功能包组成，每个包负责特定的功能领域。\n\n### 包结构\n\n| 包名 | 功能说明 |\n|------|----------|\n| `@openai/agents-core` | 核心包，提供 Agent、工具、运行器等基础功能 |\n| `@openai/agents-extensions` | 扩展包，提供 AI SDK UI 集成、沙箱环境等扩展功能 |\n| `@openai/agents-realtime` | 实时包，支持构建实时语音代理应用 |\n| `@openai/agents-openai` | OpenAI 特定实现，处理 OpenAI API 集成 |\n\n资料来源：[packages/agents-extensions/README.md:1]()\n\n### 技术架构图\n\n```mermaid\ngraph TD\n A[开发者应用] --> B[@openai/agents]\n B --> C[agents-core 核心包]\n B --> D[agents-extensions 扩展包]\n B --> E[agents-realtime 实时包]\n C --> F[Agent 代理]\n C --> G[Tools 工具集]\n C --> H[Runner 运行器]\n F --> I[Handoffs 交接]\n F --> J[Guardrails 防护栏]\n G --> K[FunctionTool]\n G --> L[ComputerTool]\n G --> M[ShellTool]\n G --> N[FileSearchTool]\n G --> O[WebSearchTool]\n```\n\n## 核心概念\n\n### Agent（代理）\n\nAgent 是 SDK 的核心组件，代表一个配置了指令、工具、防护栏和交接功能的 AI 代理实例。开发者通过创建 Agent 实例并定义其行为来实现各种智能应用场景。资料来源：[packages/agents-core/src/agent.ts:1]()\n\n```typescript\nimport { Agent } from '@openai/agents';\n\nconst agent = new Agent({\n name: 'Assistant',\n instructions: 'Reply with a short answer.',\n});\n```\n\n资料来源：[examples/ai-sdk-ui/README.md:1]()\n\n### 工具系统\n\nSDK 提供了丰富的内置工具，支持开发者扩展 Agent 的能力边界。\n\n| 工具类型 | 描述 | 使用场景 |\n|----------|------|----------|\n| FunctionTool | 函数工具，允许调用任意 JavaScript 函数 | 业务逻辑集成 |\n| ComputerTool | 计算机工具，支持浏览器自动化操作 | 网页抓取、表单填写 |\n| ShellTool | Shell 工具，在沙箱环境中执行命令 | 代码执行、系统操作 |\n| FileSearchTool | 文件搜索工具，集成向量搜索能力 | 文档检索、知识库问答 |\n| WebSearchTool | 网络搜索工具 | 实时信息查询 |\n| CodeInterpreterTool | 代码解释器 | 代码执行、数据分析 |\n\n资料来源：[examples/tools/README.md:1-30]()\n\n### 工具延迟加载机制\n\n工具支持 `deferLoading` 属性，允许在 Responses API 中延迟加载顶层函数工具定义，直到工具搜索阶段才加载。资料来源：[packages/agents-core/src/tool.ts:1]()\n\n### 工具命名空间\n\n多个相关工具可以组织在同一个命名空间下，便于管理和调用：\n\n```mermaid\ngraph LR\n A[Namespace: data] --> B[fileSearch]\n A --> C[documentParser]\n A --> D[textAnalyzer]\n E[Namespace: compute] --> F[calculator]\n E --> G[converter]\n```\n\n## 主要功能特性\n\n### 流式输出\n\nSDK 支持多种流式输出模式，便于构建实时交互应用。\n\n| 示例名称 | 功能说明 | 运行命令 |\n|----------|----------|----------|\n| stream-text | 流式纯文本响应 | `pnpm -F basic start:stream-text` |\n| stream-items | 流式事件包括工具调用 | `pnpm -F basic start:stream-items` |\n| stream-ws | WebSocket 流式响应 | `pnpm -F basic start:stream-ws` |\n| human-in-the-loop-stream | 人类审批流式版本 | `pnpm examples:streamed:human-in-the-loop` |\n\n资料来源：[examples/basic/README.md:1-20]()\n\n### 生命周期管理\n\nSDK 提供了完整的生命周期钩子，允许开发者在 Agent 运行的不同阶段注入自定义逻辑。\n\n| 生命周期事件 | 触发时机 |\n|--------------|----------|\n| onAgentStart | Agent 开始执行时 |\n| onAgentEnd | Agent 完成执行时 |\n| onToolStart | 工具开始调用时 |\n| onToolEnd | 工具完成调用时 |\n| onHandoff | 交接发生时 |\n| onGuardrail | 防护栏检查时 |\n\n资料来源：[examples/basic/README.md:1]()\n\n### 人类在环（Human-in-the-Loop）\n\n支持在工具执行前进行人工审批，确保关键操作经过人工确认。\n\n```mermaid\ngraph TD\n A[Agent 调用工具] --> B{需要人工审批?}\n B -->|是| C[暂停等待审批]\n C --> D[用户批准/拒绝]\n D -->|批准| E[继续执行]\n D -->|拒绝| F[终止执行]\n B -->|否| E\n```\n\n资料来源：[examples/agent-patterns/README.md:1]()\n\n### 防护栏（Guardrails）\n\nSDK 提供了输入和输出防护栏功能，用于过滤和验证用户输入与模型输出。\n\n| 防护栏类型 | 功能 |\n|------------|------|\n| InputGuardrail | 拒绝不需要的请求 |\n| OutputGuardrail | 阻止不安全的输出 |\n\n资料来源：[examples/agent-patterns/README.md:1]()\n\n### 交接（Handoffs）\n\nAgent 之间支持交接功能，允许构建多代理协作系统。一个 Agent 可以将对话控制权转移给另一个 Agent。\n\n```typescript\nconst agentA = new Agent({ name: 'Agent A', handoffs: [agentB] });\nconst agentB = new Agent({ name: 'Agent B' });\n```\n\n资料来源：[packages/agents-core/src/agent.ts:1]()\n\n## Agent 模式示例\n\n### 基础模式\n\n| 示例名称 | 功能描述 |\n|----------|----------|\n| hello-world | 基本 Agent 回复俳句 |\n| chat | 交互式 CLI 聊天 |\n| dynamic-system-prompt | 动态系统提示 |\n\n资料来源：[examples/basic/README.md:1-15]()\n\n### 高级模式\n\n| 示例名称 | 功能描述 |\n|----------|----------|\n| agents-as-tools | 将代理作为工具使用，实现翻译器编排 |\n| agents-as-tools-structured | 使用 `Agent.asTool()` 实现结构化工具输入 |\n| deterministic | 固定代理流程与质量检查 |\n| forcing-tool-use | 要求特定工具使用后才输出最终结果 |\n| llm-as-a-judge | 使用 LLM 评估故事大纲 |\n\n资料来源：[examples/agent-patterns/README.md:1-25]()\n\n## 实时语音代理\n\n`agents-realtime` 包专门用于构建实时语音代理应用，支持语音交互和代理交接功能。\n\n```typescript\nimport { RealtimeAgent } from '@openai/agents-realtime';\n\nconst voiceAgent = new RealtimeAgent({\n name: 'Voice Assistant',\n voice: 'alloy',\n handoffs: [anotherAgent],\n});\n```\n\n资料来源：[packages/agents-realtime/src/realtimeAgent.ts:1-20]()\n\n### 实时代理配置选项\n\n| 配置项 | 类型 | 描述 |\n|--------|------|------|\n| name | string | 实时代理名称 |\n| voice | string | 使用的语音 |\n| handoffs | RealtimeAgent[] | 可交接的代理列表 |\n| instructions | string | 系统指令 |\n\n## 模型配置\n\nSDK 支持详细的模型配置选项，包括推理能力设置。\n\n### 推理模型配置\n\n| 配置项 | 可选值 | 描述 |\n|--------|--------|------|\n| effort | none, minimal, low, medium, high, xhigh | 推理工作量的约束 |\n| summary | auto, concise, detailed | 推理摘要的详细程度 |\n\n资料来源：[packages/agents-core/src/model.ts:1-25]()\n\n### 文本配置\n\n| 配置项 | 可选值 | 描述 |\n|--------|--------|------|\n| verbosity | low, medium, high | 模型响应的详细程度约束 |\n\n## 错误处理\n\nSDK 提供了完善的错误处理机制，支持自定义错误处理器。\n\n| 错误类型 | 说明 |\n|----------|------|\n| MaxTurnsExceededError | 超出最大轮次限制 |\n| ModelRefusalError | 模型拒绝执行 |\n\n资料来源：[packages/agents-core/src/runner/errorHandlers.ts:1-20]()\n\n## 安装和使用\n\n### 基础安装\n\n```bash\nnpm install @openai/agents @openai/agents-extensions\n```\n\n资料来源：[packages/agents-extensions/README.md:1]()\n\n### 运行示例\n\n项目使用 `pnpm` 作为包管理器，运行命令格式如下：\n\n```bash\n# 运行基础示例\npnpm -F basic start:\n\n# 运行代理模式示例\npnpm examples:\n\n# 运行工具示例\npnpm examples:tools-\n```\n\n资料来源：[examples/basic/README.md:1](), [examples/tools/README.md:1]()\n\n## 工具搜索与加载\n\n### 客户端工具搜索执行器\n\nSDK 支持自定义客户端工具搜索逻辑，通过实现 `ClientToolSearchExecutor` 接口来实现动态工具加载：\n\n```typescript\ntype ClientToolSearchExecutor = (\n args: ClientToolSearchExecutorArgs,\n) => Tool | Tool[] | null | undefined;\n```\n\n资料来源：[packages/agents-core/src/tool.ts:1]()\n\n### 工具启用条件\n\n工具可以配置动态启用条件，通过 `ToolEnabledPredicate` 类型定义：\n\n```typescript\ntype ToolEnabledPredicate = (args: {\n runContext: RunContext;\n agent: Agent;\n}) => boolean | Promise;\n```\n\n## 序列化支持\n\nSDK 提供了工具序列化功能，支持在 Agent 运行前预先序列化和存储工具配置：\n\n| 工具类型 | 序列化字段 |\n|----------|-----------|\n| function | name, description, parameters, strict, deferLoading, namespace |\n| computer | name, environment, dimensions |\n| shell | name, environment |\n| apply_patch | name |\n\n资料来源：[packages/agents-core/src/utils/serialize.ts:1-40]()\n\n## 适用场景\n\n| 场景类型 | 推荐使用方式 |\n|----------|--------------|\n| 对话系统 | 使用基础 Agent + 工具集成 |\n| 自动化流程 | 使用 Human-in-the-Loop + 防护栏 |\n| 多代理协作 | 使用 Handoffs + 工具代理模式 |\n| 实时语音交互 | 使用 RealtimeAgent |\n| 代码执行与数据分析 | 使用 CodeInterpreterTool |\n| 网页自动化 | 使用 ComputerTool + Playwright |\n\n## 技术特点\n\n- **TypeScript 原生支持**：完整的类型定义，良好的开发体验\n- **模块化设计**：按需引入，减小包体积\n- **流式支持**：多种流式输出模式\n- **可扩展架构**：支持自定义工具、执行器和处理器\n- **安全防护**：内置输入输出防护栏\n- **生命周期钩子**：完整的运行时代码注入能力\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [Agent 核心机制](#page-agents), [工具系统](#page-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents-core/src/agent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/agent.ts)\n- [packages/agents-core/src/tool.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/tool.ts)\n- [packages/agents-core/src/runner/errorHandlers.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/runner/errorHandlers.ts)\n- [packages/agents-core/src/utils/serialize.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/utils/serialize.ts)\n- [packages/agents-openai/src/openaiResponsesModel.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-openai/src/openaiResponsesModel.ts)\n- [packages/agents-realtime/src/realtimeAgent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-realtime/src/realtimeAgent.ts)\n- [packages/agents-extensions/README.md](https://github.com/openai/openai-agents-js/blob/main/packages/agents-extensions/README.md)\n- [pnpm-workspace.yaml](https://github.com/openai/openai-agents-js/blob/main/pnpm-workspace.yaml)\n \n\n# 系统架构\n\n## 概述\n\nOpenAI Agents SDK（openai-agents-js）是一个用于构建 AI Agent 应用的 TypeScript/JavaScript SDK，采用 monorepo 结构管理多个功能包。该 SDK 提供了创建 Agent、定义工具、处理错误、实现安全防护等核心能力，支持与 OpenAI 模型及多种扩展功能集成。\n\n资料来源：[pnpm-workspace.yaml]()\n\n## 整体架构\n\n```mermaid\ngraph TB\n subgraph \"主包层\"\n A[\"@openai/agents\"]\n A --> B[\"agents-core\"]\n A --> C[\"agents-openai\"]\n end\n \n subgraph \"核心层 packages/agents-core\"\n D[\"Agent 类\"]\n E[\"Tool 系统\"]\n F[\"Runner 执行器\"]\n G[\"Guardrails 防护\"]\n H[\"Handoffs 交接\"]\n I[\"Error Handlers\"]\n end\n \n subgraph \"扩展层\"\n J[\"agents-extensions
扩展包\"]\n K[\"agents-realtime
实时语音\"]\n end\n \n subgraph \"示例\"\n L[\"examples/basic
基础示例\"]\n M[\"examples/agent-patterns
模式示例\"]\n N[\"examples/tools
工具集成\"]\n end\n \n C --> D\n C --> E\n J --> B\n K --> B\n```\n\n## 包结构\n\n| 包名 | 描述 | 依赖关系 |\n|------|------|----------|\n| `@openai/agents` | 主入口包，聚合所有功能 | agents-core, agents-openai |\n| `@openai/agents-core` | 核心功能实现 | 无外部依赖 |\n| `@openai/agents-openai` | OpenAI 模型适配器 | agents-core |\n| `@openai/agents-extensions` | 扩展功能（沙箱等） | agents-core |\n| `@openai/agents-realtime` | 实时语音 Agent | agents-core |\n\n资料来源：[packages/agents-extensions/README.md]()\n\n## 核心组件\n\n### Agent 类\n\n`Agent` 是 SDK 的核心类，泛型设计支持灵活的类型系统：\n\n```typescript\nexport class Agent<\n TContext = UnknownContext,\n TOutput extends AgentOutputType = TextOutput,\n>\n```\n\n**泛型参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `TContext` | `UnknownContext` | Agent 执行的上下文对象，可跨工具、交接、防护传递状态 |\n| `TOutput` | `AgentOutputType` | 输出类型，默认为 `TextOutput` |\n\n**静态工厂方法 `create`：**\n\n```typescript\nstatic create<\n TOutput extends AgentOutputType = TextOutput,\n Handoffs extends readonly (Agent | Handoff)[] = [],\n>(config: AgentConfigWithHandoffs...)\n```\n\n资料来源：[packages/agents-core/src/agent.ts:1-50]()\n\n### Tool 系统\n\n#### 工具类型体系\n\n```mermaid\nclassDiagram\n class Tool {\n <>\n type: 'function' | 'hosted_tool'\n }\n \n class FunctionTool {\n name: string\n description: string\n parameters: JsonObjectSchema\n strict: boolean\n deferLoading?: boolean\n invoke()\n needsApproval?: boolean\n }\n \n class HostedTool {\n name: string\n providerData?: Record\n }\n \n Tool <|-- FunctionTool\n Tool <|-- HostedTool\n```\n\n#### FunctionTool 核心属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `name` | `string` | 工具名称 |\n| `description` | `string` | 工具描述，帮助模型理解何时使用 |\n| `parameters` | `JsonObjectSchema` | JSON Schema 参数定义 |\n| `strict` | `boolean` | 是否严格遵循 schema |\n| `deferLoading` | `boolean` | 延迟加载（Responses API 专用） |\n| `invoke` | `Function` | 工具执行函数 |\n\n资料来源：[packages/agents-core/src/tool.ts:1-80]()\n\n#### 工具命名空间\n\n工具支持通过 `namespace` 属性进行分组管理：\n\n```typescript\nconst namespaceName = typeof tool.namespace === 'string' \n ? tool.namespace.trim() \n : '';\n```\n\n同一命名空间下的所有工具必须共享相同的 `namespaceDescription`。\n\n资料来源：[packages/agents-openai/src/openaiResponsesModel.ts:1-50]()\n\n### Handoffs 交接系统\n\nHandoff 允许 Agent 之间进行交接，传递执行上下文：\n\n```typescript\nexport type RealtimeAgentConfiguration = {\n name: string;\n handoffs?: (RealtimeAgent | Handoff, TextOutput>)[];\n voice?: string;\n};\n```\n\n资料来源：[packages/agents-realtime/src/realtimeAgent.ts:1-30]()\n\n### Guardrails 防护系统\n\n#### 输入防护（Input Guardrails）\n\n在 Agent 处理输入前进行验证和过滤。\n\n#### 输出防护（Output Guardrails）\n\n在 Agent 生成最终输出后进行验证：\n\n```typescript\nexport type RunErrorHandlerResult> = {\n /**\n * 返回的最终输出\n */\n finalOutput: ResolvedAgentOutput;\n /**\n * 是否将合成输出追加到历史记录\n */\n includeInHistory?: boolean;\n};\n```\n\n资料来源：[packages/agents-core/src/runner/errorHandlers.ts:1-50]()\n\n### Error Handlers 错误处理\n\n```mermaid\ngraph LR\n A[\"RunError\"] --> B[\"RunErrorHandlers\"]\n B --> C[\"MaxTurnsExceededError\"]\n B --> D[\"ModelRefusalError\"]\n B --> E[\"default handler\"]\n \n F[\"TryHandleRunErrorArgs\"] --> G[\"buildRunData\"]\n G --> H[\"RunErrorData\"]\n```\n\n**错误处理器类型：**\n\n```typescript\nexport type RunErrorHandlers<\n TContext,\n TAgent extends Agent,\n> = Partial>> & {\n default?: RunErrorHandler;\n};\n```\n\n资料来源：[packages/agents-core/src/runner/errorHandlers.ts:50-100]()\n\n## 工具流处理\n\n### 工具执行结果\n\n```mermaid\nstateDiagram-v2\n [*] --> ToolCall\n ToolCall --> ToolExecution\n ToolExecution --> isFinalOutput: true\n ToolExecution --> isInterrupted: true\n isInterrupted --> RunToolApprovalItem\n RunToolApprovalItem --> [*]\n isFinalOutput --> [*]\n```\n\n**ToolsToFinalOutputResult 类型：**\n\n| 状态 | 字段 | 说明 |\n|------|------|------|\n| 非最终输出 | `isFinalOutput: false` | LLM 将再次运行并接收工具调用输出 |\n| 等待审批 | `isInterrupted: true` | 需要人工审批，`interruptions` 包含审批项 |\n| 最终输出 | `isFinalOutput: true` | 工具执行完成，返回最终结果 |\n\n资料来源：[packages/agents-core/src/agent.ts:150-200]()\n\n## 序列化系统\n\n工具支持序列化以支持跨进程传输：\n\n```typescript\nexport function serializeTool(tool: Tool): SerializedTool {\n if (tool.type === 'function') {\n const namespace = getExplicitFunctionToolNamespace(tool);\n return {\n type: 'function',\n name: tool.name,\n description: tool.description,\n parameters: tool.parameters as JsonObjectSchema,\n strict: tool.strict,\n deferLoading: tool.deferLoading,\n ...(namespace ? { namespace } : {}),\n };\n }\n}\n```\n\n**支持序列化的工具类型：**\n\n| 工具类型 | 可序列化字段 |\n|----------|--------------|\n| `function` | name, description, parameters, strict, deferLoading, namespace |\n| `computer` | name, environment, dimensions |\n| `shell` | name, environment |\n| `apply_patch` | name |\n\n资料来源：[packages/agents-core/src/utils/serialize.ts:1-60]()\n\n## 实时语音架构\n\n`RealtimeAgent` 是专为实时语音场景设计的 Agent 类型：\n\n```typescript\nexport type RealtimeAgentConfiguration = \n Partial, TextOutput>,\n 'model' | 'handoffs' | 'modelSettings' | 'outputType' | \n 'toolUseBehavior' | 'resetToolChoice' | 'outputGuardrails' | 'inputGuardrails'\n >>;\n```\n\n**不支持的配置项：**\n\n- `model`：同一 RealtimeSession 内的所有 RealtimeAgent 使用相同模型\n- `modelSettings`：不支持\n- 其他模型相关配置\n\n资料来源：[packages/agents-realtime/src/realtimeAgent.ts:1-50]()\n\n## 执行流程\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant R as Runner\n participant A as Agent\n participant T as Tool\n participant M as Model\n \n U->>R: Runner.run(agent, input)\n R->>A: 创建 Agent 实例\n A->>M: 发送初始请求\n M-->>A: 返回响应\n A->>T: 调用工具\n T-->>A: 工具执行结果\n A->>M: 发送工具结果\n M-->>A: 返回最终输出\n A-->>R: 返回结果\n R-->>U: 完成执行\n```\n\n## 扩展机制\n\n### Client Tool Search Executor\n\n允许自定义工具搜索和加载逻辑：\n\n```typescript\nexport type ClientToolSearchExecutor = (\n args: ClientToolSearchExecutorArgs,\n) => Tool | Tool[] | null | undefined;\n\nexport const CLIENT_TOOL_SEARCH_EXECUTOR = Symbol('clientToolSearchExecutor');\n```\n\n资料来源：[packages/agents-core/src/tool.ts:150-200]()\n\n## 命名空间隔离\n\n工具执行时的路径操作通过 `shellQuote` 进行安全转义：\n\n```bash\nresolved_root=$(realpath -m -- \"$root\")\nparent=$(dirname -- \"$path\")\nbase=$(basename -- \"$path\")\nresolved_parent=$(realpath -m -- \"$parent\")\ncase \"$resolved_parent\" in \"$resolved_root\"|\"$resolved_root\"/*) ;; \n*) printf \"workspace escape: %s\\\\n\" \"$resolved_parent\" >&2; exit 111 ;; esac\n```\n\n这确保了沙箱环境中的工作区隔离，防止目录遍历攻击。\n\n资料来源：[packages/agents-extensions/src/sandbox/daytona/sandbox.ts:1-50]()\n\n## 总结\n\nOpenAI Agents SDK 采用分层架构设计：\n\n1. **核心层**（agents-core）：提供 Agent、Tool、Guardrail、Handoff 等核心抽象\n2. **适配层**（agents-openai）：实现与 OpenAI 模型的集成\n3. **扩展层**（agents-extensions、agents-realtime）：提供沙箱、实时语音等高级功能\n4. **入口层**（agents）：统一导出所有功能\n\n泛型设计贯穿整个系统，支持 `TContext` 跨组件传递状态，`TOutput` 定义输出类型约束，实现高度可扩展的 Agent 系统。\n\n---\n\n\n\n## Agent 核心机制\n\n### 相关页面\n\n相关主题：[工具系统](#page-tools), [Handoffs 与 Agent 委托](#page-handoffs), [Guardrails 安全防护](#page-guardrails)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents-core/src/agent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/agent.ts)\n- [packages/agents-core/src/runner/errorHandlers.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/runner/errorHandlers.ts)\n- [packages/agents-core/src/tool.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/tool.ts)\n- [packages/agents-core/src/handoff.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/handoff.ts)\n- [packages/agents-realtime/src/realtimeAgent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-realtime/src/realtimeAgent.ts)\n \n\n# Agent 核心机制\n\n## 概述\n\nAgent（智能体）是 OpenAI Agents SDK 的核心抽象单元，代表一个配置了指令、工具、护栏和交接逻辑的 AI 代理实例。Agent 继承自 `AgentHooks` 并实现 `AgentConfiguration` 接口，提供了一套完整的生命周期管理、工具调用、错误处理和状态追踪机制。\n\n**核心职责：**\n- 解析用户输入并生成模型响应\n- 管理工具调用和工具输出处理\n- 处理 Agent 之间的交接（handoff）\n- 支持输入/输出护栏（Guardrails）\n- 提供完整的运行生命周期钩子\n\n资料来源：[packages/agents-core/src/agent.ts:85-100]()\n\n## Agent 类架构\n\n### 继承层次\n\n```mermaid\ngraph TD\n A[Agent<TContext, TOutput>] --> B[AgentHooks<TContext, TOutput>]\n B --> C[实现 AgentConfiguration<TContext, TOutput>]\n```\n\n`Agent` 类是一个泛型类，接受两个类型参数：\n- `TContext`：上下文类型，用于在工具函数、护栏、交接之间共享状态\n- `TOutput`：输出类型，默认为 `TextOutput`\n\n资料来源：[packages/agents-core/src/agent.ts:82-100]()\n\n### 静态工厂方法\n\nAgent 提供了静态方法用于创建实例，支持类型推断：\n\n```typescript\nstatic create<\n TOutput extends AgentOutputType = TextOutput,\n Handoffs extends readonly (Agent | Handoff)[] = [],\n>(\n config: AgentConfigWithHandoffs\n): Agent\n```\n\n资料来源：[packages/agents-core/src/agent.ts:95-110]()\n\n## 核心配置项\n\n### AgentConfiguration 接口\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `name` | `string` | Agent 的唯一标识名称 |\n| `instructions` | `string \\| function` | 系统提示或动态指令生成函数 |\n| `model` | `Model` | 使用的语言模型 |\n| `tools` | `Tool[]` | 可用工具列表 |\n| `toolOptions` | `AgentToolOptions` | 工具行为配置 |\n| `handoffs` | `Handoff[]` | 可交接的 Agent 列表 |\n| `inputGuardrails` | `InputGuardrail[]` | 输入护栏 |\n| `outputGuardrails` | `OutputGuardrail[]` | 输出护栏 |\n| `outputType` | `AgentOutputType` | 输出格式类型 |\n\n资料来源：[packages/agents-core/src/agent.ts:1-100]()\n\n### 工具选项配置\n\n`AgentToolOptions` 提供了细粒度的工具行为控制：\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `toolName` | `string` | 工具名称，覆盖默认的 Agent 名称 |\n| `toolDescription` | `string` | 工具描述，说明工具用途 |\n| `customOutputExtractor` | `function` | 自定义输出提取函数 |\n| `needsApproval` | `boolean \\| function` | 是否需要人工批准 |\n| `parameters` | `TParameters` | 参数 Schema 定义 |\n| `inputBuilder` | `AgentToolInputBuilder` | 构建嵌套 Agent 输入的函数 |\n| `includeInputSchema` | `boolean` | 是否包含完整 JSON Schema |\n| `runConfig` | `RunConfig` | 内部 Runner 初始化配置 |\n\n资料来源：[packages/agents-core/src/agent.ts:20-65]()\n\n## 工具系统\n\n### 工具类型层次\n\n```mermaid\ngraph TD\n A[Tool<Context>] --> B[FunctionTool]\n A --> C[HostedTool]\n A --> D[AgentTool]\n \n B --> E[type: 'function']\n B --> F[name, description]\n B --> G[parameters: JsonObjectSchema]\n B --> H[strict: boolean]\n B --> I[invoke: function]\n B --> J[needsApproval?: boolean]\n B --> K[deferLoading?: boolean]\n```\n\n### FunctionTool 定义\n\n`FunctionTool` 是将普通函数暴露给 Agent 作为工具的核心类型：\n\n```typescript\ntype FunctionTool<\n Context = UnknownContext,\n TParameters extends ToolInputParameters = undefined,\n Result = unknown,\n> = {\n type: 'function';\n name: string;\n description: string;\n parameters: JsonObjectSchema;\n strict: boolean;\n deferLoading?: boolean;\n invoke: (\n runContext: RunContext,\n input: string,\n details?: ToolCallDetails,\n ) => Promise;\n needsApproval?: boolean | ToolApprovalFunction;\n};\n```\n\n**关键属性说明：**\n\n| 属性 | 必填 | 说明 |\n|------|------|------|\n| `type` | 是 | 固定为 `'function'` |\n| `name` | 是 | 工具唯一名称 |\n| `description` | 是 | 帮助模型理解何时调用 |\n| `parameters` | 是 | JSON Schema 参数定义 |\n| `strict` | 是 | 是否严格遵循 Schema |\n| `invoke` | 是 | 实际执行逻辑 |\n| `deferLoading` | 否 | 延迟加载（用于 Responses API） |\n| `needsApproval` | 否 | 需要人工批准 |\n\n资料来源：[packages/agents-core/src/tool.ts:20-60]()\n\n### 托管工具 (HostedTool)\n\n托管工具用于包装 API 级别的工具调用：\n\n```typescript\ntype HostedTool = {\n type: 'hosted_tool';\n name: string;\n providerData?: Record;\n};\n```\n\n资料来源：[packages/agents-core/src/tool.ts:100-115]()\n\n## 交接机制 (Handoff)\n\n### Handoff 概念\n\nHandoff 允许一个 Agent 将控制权转移给另一个 Agent，同时可以传递上下文数据。\n\n### Handoff 类\n\n```typescript\nexport class Handoff<\n TContext = UnknownContext,\n TOutput extends AgentOutputType = TextOutput,\n> {\n public agentName: string;\n public toolName: string;\n public toolDescription: string;\n public onHandoff?: OnHandoffCallback;\n public inputSchema: JsonSchema;\n public isEnabled: HandoffEnabledFunction;\n public agent: Agent;\n}\n```\n\n资料来源：[packages/agents-core/src/handoff.ts:40-75]()\n\n### Handoff 配置选项\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `toolNameOverride` | `string` | 自定义工具名称 |\n| `toolDescriptionOverride` | `string` | 自定义工具描述 |\n| `onHandoff` | `OnHandoffCallback` | 交接时执行的回调 |\n| `inputType` | `ToolInputParameters` | 交接输入的 Schema |\n\n资料来源：[packages/agents-core/src/handoff.ts:80-100]()\n\n### Handoff 回调签名\n\n```typescript\ntype OnHandoffCallback = (\n context: RunContext,\n input?: ResolveParsedToolParameters,\n) => Promise | void;\n```\n\n资料来源：[packages/agents-core/src/handoff.ts:55-60]()\n\n## 错误处理系统\n\n### RunErrorHandler 类型\n\n错误处理器用于捕获运行时的特定错误并生成最终输出：\n\n```typescript\ntype RunErrorHandler<\n TContext,\n TAgent extends Agent,\n> = (input: RunErrorHandlerInput) =>\n | RunErrorHandlerResult\n | void\n | Promise | void>;\n```\n\n资料来源：[packages/agents-core/src/runner/errorHandlers.ts:30-40]()\n\n### 错误处理输入\n\n```typescript\ntype RunErrorHandlerInput> = {\n error: MaxTurnsExceededError | ModelRefusalError;\n context: RunContext;\n runData: RunErrorData;\n};\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `error` | `MaxTurnsExceededError \\| ModelRefusalError` | 捕获的错误类型 |\n| `context` | `RunContext` | 运行上下文 |\n| `runData` | `RunErrorData` | 运行数据快照 |\n\n资料来源：[packages/agents-core/src/runner/errorHandlers.ts:10-25]()\n\n### 错误处理结果\n\n```typescript\ntype RunErrorHandlerResult> = {\n finalOutput: ResolvedAgentOutput;\n includeInHistory?: boolean;\n};\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `finalOutput` | 泛型 | 最终返回的输出 |\n| `includeInHistory` | `boolean` | 是否将输出追加到历史记录 |\n\n资料来源：[packages/agents-core/src/runner/errorHandlers.ts:25-35]()\n\n### 错误处理器集合\n\n```typescript\ntype RunErrorHandlers<\n TContext,\n TAgent extends Agent,\n> = Partial>> & {\n default?: RunErrorHandler;\n};\n```\n\n支持按错误类型注册特定处理器，同时提供 `default` 作为兜底处理器。\n\n## 工具使用行为\n\n### ToolUseBehaviorFlags\n\n```typescript\nexport type ToolUseBehaviorFlags = 'run_llm_again' | 'stop_on_first_tool';\n```\n\n| 值 | 行为 |\n|---|------|\n| `run_llm_again` | LLM 在工具调用后再次运行 |\n| `stop_on_first_tool` | 遇到第一个工具调用就停止 |\n\n资料来源：[packages/agents-core/src/agent.ts:140-145]()\n\n### ToolsToFinalOutputResult 联合类型\n\n```typescript\ntype ToolsToFinalOutputResult =\n | { isFinalOutput: false; isInterrupted: undefined }\n | { isFinalOutput: false; isInterrupted: true; interruptions: RunToolApprovalItem[] }\n | { isFinalOutput: true; ... }\n```\n\n表示工具调用结果的多种可能状态：\n- 正常工具调用（非最终输出）\n- 被中断等待批准\n- 最终输出\n\n## 实时 Agent\n\n`RealtimeAgent` 是专用于语音交互场景的特殊 Agent 类型：\n\n```typescript\nexport type RealtimeAgentConfiguration = Partial<\n Omit<\n AgentConfiguration, TextOutput>,\n | 'model'\n | 'handoffs'\n | 'modelSettings'\n | 'outputType'\n | 'toolUseBehavior'\n | 'resetToolChoice'\n | 'outputGuardrails'\n | 'inputGuardrails'\n >\n> & {\n name: string;\n handoffs?: (RealtimeAgent | Handoff<...>)[];\n voice?: string;\n};\n```\n\n**不支持的配置项：**\n- `model`：由 Session 统一管理\n- `modelSettings`：由 Session 统一管理\n- 其他模型相关配置\n\n资料来源：[packages/agents-realtime/src/realtimeAgent.ts:1-40]()\n\n## 工具搜索执行器\n\n### ClientToolSearchExecutor\n\n用于自定义工具加载逻辑：\n\n```typescript\ntype ClientToolSearchExecutor = (\n args: ClientToolSearchExecutorArgs,\n) => Tool | Tool[] | null | undefined;\n```\n\n**执行参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `agent` | `Agent` | 当前 Agent |\n| `availableTools` | `Tool[]` | 已加载工具 |\n| `loadDefault` | `function` | 加载默认工具的函数 |\n| `runContext` | `RunContext` | 运行上下文 |\n| `toolCall` | `protocol.ToolSearchCallItem` | 工具搜索调用项 |\n\n资料来源：[packages/agents-core/src/tool.ts:130-160]()\n\n## Agent 执行流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户输入\n participant Runner as Runner\n participant Agent as Agent\n participant Model as 语言模型\n participant Tools as 工具系统\n \n User->>Runner: 启动运行\n Runner->>Agent: 初始化 Agent\n Agent->>Model: 发送指令和工具定义\n Model->>Agent: 返回响应/工具调用\n alt 工具调用\n Agent->>Tools: 执行工具\n Tools-->>Agent: 返回工具结果\n Agent->>Model: 发送工具结果\n Model->>Agent: 继续响应\n end\n alt Handoff\n Agent->>Agent: 切换到目标 Agent\n Note over Agent: 传递上下文\n end\n alt 错误处理\n Agent->>Runner: 捕获错误\n Runner->>Runner: 调用错误处理器\n end\n Agent-->>Runner: 返回最终输出\n Runner-->>User: 返回结果\n```\n\n## 类型层次总结\n\n```\nAgentOutputType\n├── TextOutput\n└── CustomOutput (泛型)\n\nTool\n├── FunctionTool\n├── HostedTool\n└── AgentTool\n\nAgentConfiguration\n├── name: string\n├── instructions: string | InstructionsFunction\n├── model: Model\n├── tools: Tool[]\n├── handoffs: Handoff[]\n├── inputGuardrails: InputGuardrail[]\n├── outputGuardrails: OutputGuardrail[]\n└── outputType: TOutput\n```\n\n## 最佳实践\n\n### 1. 明确的 Agent 命名\n\n使用描述性的名称便于调试和交接：\n\n```typescript\nconst agent = Agent.create({\n name: 'research-assistant', // 使用 kebab-case\n instructions: 'You are a helpful research assistant...',\n});\n```\n\n### 2. 工具描述编写规范\n\n工具描述应清晰说明用途和参数：\n\n```typescript\nconst searchTool = createTool({\n name: 'web_search',\n description: 'Search the web for information. Use for factual queries.',\n parameters: { query: z.string() },\n // ...\n});\n```\n\n### 3. Handoff 回调使用场景\n\n- 在交接时记录审计日志\n- 清理或准备共享上下文\n- 触发通知或监控事件\n\n```typescript\nconst handoff = new Handoff(agent, async (context, input) => {\n context.logger.info(`Handoff to ${agent.name} at ${new Date()}`);\n});\n```\n\n### 4. 错误处理器配置\n\n为常见错误提供友好的兜底输出：\n\n```typescript\nconst errorHandlers: RunErrorHandlers = {\n [RunErrorKind.MaxTurnsExceeded]: async ({ runData }) => ({\n finalOutput: 'Reached maximum turns. Please try a more specific query.',\n includeInHistory: true,\n }),\n default: async ({ error }) => ({\n finalOutput: `An error occurred: ${error.message}`,\n }),\n};\n```\n\n## 相关文档\n\n- [工具系统详解](./tools.md)\n- [交接机制](./handoffs.md)\n- [错误处理](./error-handling.md)\n- [实时语音 Agent](./realtime-agents.md)\n- [SDK 快速入门](../getting-started.md)\n\n---\n\n\n\n## 工具系统\n\n### 相关页面\n\n相关主题：[Agent 核心机制](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents-core/src/tool.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/tool.ts)\n- [packages/agents-core/src/agent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/agent.ts)\n- [packages/agents-core/src/runner/toolSearch.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/runner/toolSearch.ts)\n- [packages/agents-core/src/runner/errorHandlers.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/runner/errorHandlers.ts)\n \n\n# 工具系统\n\n## 概述\n\nOpenAI Agents SDK 的**工具系统（Tool System）**是框架的核心组成部分之一，它使 AI Agent 能够与外部系统交互、执行具体操作并获取实时信息。工具系统提供了标准化的接口定义、类型安全的工具配置、以及完整的工具生命周期管理机制。\n\n工具系统在整体架构中扮演以下关键角色：\n\n- **能力扩展**：通过工具为 Agent 提供 API 调用、文件操作、代码执行等能力\n- **结构化输入输出**：支持 JSON Schema 验证的工具参数和返回值\n- **生命周期管理**：提供工具启动、结束、错误处理等完整的生命周期钩子\n- **运行时集成**：与 Runner、Agent 等核心组件无缝集成\n\n资料来源：[packages/agents-core/src/tool.ts:1-50]()\n\n## 工具类型体系\n\nSDK 中定义了多种工具类型，每种类型针对不同的使用场景进行优化。\n\n### 函数工具（FunctionTool）\n\n函数工具是最常用的工具类型，用于将普通函数暴露给 AI Agent 调用。\n\n```typescript\nexport type FunctionTool<\n Context = UnknownContext,\n TParameters extends ToolInputParameters = undefined,\n Result = unknown,\n> = {\n type: 'function';\n name: string;\n description: string;\n parameters: JsonObjectSchema;\n strict: boolean;\n deferLoading?: boolean;\n invoke: (\n runContext: RunContext,\n input: string,\n details?: ToolCallDetails,\n ) => Promise;\n needsApproval?: boolean | ToolApprovalFunction;\n};\n```\n\n资料来源：[packages/agents-core/src/tool.ts:40-80]()\n\n| 属性 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `type` | `'function'` | 是 | 工具类型标识 |\n| `name` | `string` | 是 | 工具名称，用于 Agent 识别和调用 |\n| `description` | `string` | 是 | 工具描述，帮助模型理解何时使用该工具 |\n| `parameters` | `JsonObjectSchema` | 是 | JSON Schema 描述工具参数 |\n| `strict` | `boolean` | 是 | 是否严格遵循 Schema |\n| `deferLoading` | `boolean` | 否 | 延迟加载标志，用于工具搜索场景 |\n| `invoke` | `Function` | 是 | 工具实际执行逻辑 |\n| `needsApproval` | `boolean \\| Function` | 否 | 是否需要人工审批 |\n\n### 托管工具（HostedTool）\n\n托管工具由 SDK 内置或第三方服务提供，代表外部能力。\n\n```typescript\nexport type HostedTool = {\n type: 'hosted_tool';\n name: string;\n providerData?: Record;\n};\n```\n\n资料来源：[packages/agents-core/src/tool.ts:100-110]()\n\n| 属性 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `type` | `'hosted_tool'` | 是 | 工具类型标识 |\n| `name` | `string` | 是 | 工具唯一名称 |\n| `providerData` | `Record` | 否 | 传递给工具的额外配置数据 |\n\n### 客户端工具搜索执行器\n\n客户端工具搜索执行器允许在运行时动态解析和加载工具。\n\n```typescript\nexport type ClientToolSearchExecutor = (\n args: ClientToolSearchExecutorArgs,\n) =>\n | Tool\n | Tool[]\n | null\n | undefined\n | Promise>;\n```\n\n资料来源：[packages/agents-core/src/tool.ts:130-145]()\n\n## 工具创建与配置\n\n### 基础工具创建\n\n使用 `functionTool` 辅助函数创建标准工具：\n\n```typescript\nimport { functionTool } from '@openai/agents-core';\n\nconst calculator = functionTool({\n name: 'calculator',\n description: 'Perform mathematical calculations',\n parameters: {\n type: 'object',\n properties: {\n expression: { type: 'string', description: 'Math expression' }\n },\n required: ['expression']\n },\n strict: true,\n execute: async (runContext, input) => {\n // 实现计算逻辑\n return result;\n }\n});\n```\n\n### Agent 作为工具\n\nAgent 可以被包装为工具供其他 Agent 调用，实现多 Agent 协作：\n\n```typescript\nexport type AgentToolOptions<\n TContext,\n TAgent extends Agent,\n TParameters extends AgentToolInputParameters,\n> = {\n toolName?: string;\n toolDescription?: string;\n customOutputExtractor?: (output: CompletedAgentToolInvocationRunResult) => string | Promise;\n needsApproval?: boolean | ToolApprovalFunction;\n parameters?: TParameters;\n inputBuilder?: AgentToolInputBuilder;\n includeInputSchema?: boolean;\n};\n```\n\n资料来源：[packages/agents-core/src/agent.ts:1-50]()\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `toolName` | `string` | 工具名称，默认使用 Agent 名称 |\n| `toolDescription` | `string` | 工具描述 |\n| `customOutputExtractor` | `Function` | 自定义输出提取器 |\n| `needsApproval` | `boolean \\| Function` | 是否需要人工审批 |\n| `parameters` | `AgentToolInputParameters` | 工具输入参数 Schema |\n| `inputBuilder` | `AgentToolInputBuilder` | 嵌套 Agent 输入构建器 |\n| `includeInputSchema` | `boolean` | 是否包含完整 JSON Schema |\n\n### 工具启用条件\n\n可以使用条件表达式动态控制工具是否可用：\n\n```typescript\ntype ToolEnabledPredicate = (args: {\n runContext: RunContext;\n agent: Agent;\n}) => boolean | Promise;\n\ntype ToolEnabledOption =\n | boolean\n | ToolEnabledPredicate;\n```\n\n## 工具执行流程\n\n```mermaid\ngraph TD\n A[Agent 决策] --> B{工具调用请求}\n B -->|FunctionTool| C[invoke 函数]\n B -->|HostedTool| D[托管服务调用]\n B -->|MCP Tool| E[MCP 协议通信]\n C --> F[参数验证]\n F --> G{验证通过?}\n G -->|是| H[执行业务逻辑]\n G -->|否| I[返回错误]\n H --> J[结果序列化]\n J --> K[返回给 Agent]\n D --> K\n E --> K\n I --> K\n```\n\n### 工具调用结果处理\n\nSDK 定义了 `ToolsToFinalOutputResult` 类型来描述工具执行后的状态：\n\n```typescript\nexport type ToolsToFinalOutputResult =\n | {\n isFinalOutput: false;\n isInterrupted: undefined;\n }\n | {\n isFinalOutput: false;\n isInterrupted: true;\n interruptions: RunToolApprovalItem[];\n }\n | {\n isFinalOutput: false;\n // ... 其他状态\n };\n```\n\n资料来源：[packages/agents-core/src/agent.ts:80-110]()\n\n## 错误处理机制\n\nSDK 提供了完整的工具执行错误处理框架：\n\n```typescript\nexport type RunErrorHandler> = (\n input: RunErrorHandlerInput,\n) =>\n | RunErrorHandlerResult\n | void\n | Promise | void>;\n\nexport type RunErrorHandlers<\n TContext,\n TAgent extends Agent,\n> = Partial>> & {\n default?: RunErrorHandler;\n};\n```\n\n资料来源：[packages/agents-core/src/runner/errorHandlers.ts:1-60]()\n\n| 错误处理类型 | 说明 |\n|-------------|------|\n| `MaxTurnsExceededError` | 最大轮次超限错误处理 |\n| `ModelRefusalError` | 模型拒绝执行错误处理 |\n| `default` | 通用错误默认处理 |\n\n## 工具搜索与延迟加载\n\n工具系统支持延迟加载机制，允许按需加载工具定义：\n\n### 延迟加载函数工具\n\n```typescript\nfunction isTopLevelDeferredFunctionTool(tool: Tool): boolean {\n return tool.type === 'function' && tool.deferLoading === true;\n}\n\nfunction getDeferredFunctionToolsByName(\n tools: Tool[],\n): Map> {\n return new Map(\n tools\n .filter(isTopLevelDeferredFunctionTool)\n .map((tool) => [tool.name, tool] as const),\n );\n}\n```\n\n资料来源：[packages/agents-core/src/runner/toolSearch.ts:1-30]()\n\n### 延迟加载命名空间工具\n\nSDK 支持命名空间分组管理延迟加载的工具：\n\n```typescript\nfunction getDeferredNamespaceToolsByName(\n tools: Tool[],\n): Map {\n const namespaces = new Map();\n\n for (const tool of tools) {\n if (!isDeferredFunctionTool(tool)) {\n continue;\n }\n\n const namespace = getExplicitFunctionToolNamespace(tool);\n if (!namespace) {\n continue;\n }\n // ... 命名空间处理逻辑\n }\n return namespaces;\n}\n```\n\n资料来源：[packages/agents-core/src/runner/toolSearch.ts:50-80]()\n\n## 工具序列化\n\n工具配置可以被序列化用于传输或持久化：\n\n```typescript\nexport function serializeTool(tool: Tool): SerializedTool {\n if (tool.type === 'function') {\n const namespace = getExplicitFunctionToolNamespace(tool);\n return {\n type: 'function',\n name: tool.name,\n description: tool.description,\n parameters: tool.parameters as JsonObjectSchema,\n strict: tool.strict,\n deferLoading: tool.deferLoading,\n ...(namespace ? { namespace } : {}),\n };\n }\n // ... 其他工具类型序列化\n}\n```\n\n资料来源：[packages/agents-core/src/utils/serialize.ts:1-50]()\n\n## 工具使用示例\n\n### 基础工具示例\n\n```typescript\nimport { Agent, functionTool } from '@openai/agents-core';\n\nconst fetchWeather = functionTool({\n name: 'fetch_weather',\n description: 'Get current weather for a location',\n parameters: {\n type: 'object',\n properties: {\n location: {\n type: 'string',\n description: 'City name'\n }\n },\n required: ['location']\n },\n strict: true,\n execute: async (runContext, input) => {\n const { location } = JSON.parse(input);\n // 调用天气 API\n return JSON.stringify({ location, temperature: 22 });\n }\n});\n```\n\n### Agent 作为工具\n\n```typescript\nconst translator = Agent.from({\n name: 'translator',\n instructions: 'Translate text to target language',\n outputType: TextOutput\n});\n\nconst mainAgent = Agent.from({\n name: 'main',\n instructions: 'You can use the translator tool to translate content',\n tools: [\n translator.asTool({\n toolName: 'translate',\n toolDescription: 'Translate text between languages',\n parameters: translateParamsSchema\n })\n ]\n});\n```\n\n## 架构总览\n\n```mermaid\ngraph TD\n subgraph 核心层\n A[Agent]\n B[Runner]\n C[Tool System]\n end\n \n subgraph 工具类型\n D[FunctionTool]\n E[HostedTool]\n F[ComputerTool]\n G[ShellTool]\n H[MCPTool]\n end\n \n subgraph 工具生命周期\n I[工具注册]\n J[工具搜索]\n K[工具执行]\n L[结果处理]\n end\n \n C --> D\n C --> E\n C --> F\n C --> G\n C --> H\n \n A --> C\n B --> C\n I --> J\n J --> K\n K --> L\n```\n\n## 最佳实践\n\n1. **参数 Schema 定义**：使用精确的 JSON Schema 定义工具参数，包含描述和类型约束\n2. **严格模式**：启用 `strict: true` 确保模型严格遵循参数规范\n3. **人工审批**：对于敏感操作设置 `needsApproval: true`\n4. **延迟加载**：大量工具场景下使用 `deferLoading` 优化初始化性能\n5. **命名空间管理**：相关工具使用命名空间分组，便于管理和搜索\n\n---\n\n\n\n## Handoffs 与 Agent 委托\n\n### 相关页面\n\n相关主题：[Agent 核心机制](#page-agents), [Guardrails 安全防护](#page-guardrails)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents-core/src/handoff.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/handoff.ts)\n- [packages/agents-core/src/agent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/agent.ts)\n- [packages/agents-core/src/realtimeAgent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/realtimeAgent.ts)\n- [packages/agents-core/src/runner/modelOutputs.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/runner/modelOutputs.ts)\n- [examples/handoffs/README.md](https://github.com/openai/openai-agents-js/blob/main/examples/handoffs/README.md)\n- [examples/agent-patterns/README.md](https://github.com/openai/openai-agents-js/blob/main/examples/agent-patterns/README.md)\n \n\n# Handoffs 与 Agent 委托\n\n## 概述\n\nHandoffs（交接）是 OpenAI Agents SDK 中实现多代理协作的核心机制。当一个 Agent 需要将对话控制权转移给另一个 Agent 时，Handoff 机制会完整地传递对话历史，使目标 Agent 能够无缝继续对话流程。资料来源：[packages/agents-core/src/agent.ts:1-100]()\n\n与 Handoff 不同的是 **Agent 委托（Agent as Tool）**，它将一个 Agent 作为工具使用，目标 Agent 接收的是生成的输入而非完整对话历史，并且对话由原始 Agent 继续控制。资料来源：[packages/agents-core/src/agent.ts:60-80]()\n\n## 核心概念对比\n\n| 特性 | Handoff | Agent as Tool |\n|------|---------|---------------|\n| 对话历史传递 | 完整历史转移 | 不传递，需通过 inputBuilder 构建输入 |\n| 控制权 | 完全转移给新 Agent | 原始 Agent 继续控制对话 |\n| 使用场景 | 多角色切换、任务委派 | 工具化调用、嵌套推理 |\n| 输入来源 | 历史消息 | 生成的参数 |\n\n## 架构设计\n\n```mermaid\ngraph TD\n A[User Input] --> B[Primary Agent]\n B --> C{Handoff Trigger?}\n C -->|Yes| D[Handoff Tool Call]\n D --> E[目标 Agent 接收完整历史]\n C -->|No| F[继续当前 Agent]\n E --> G[对话由目标 Agent 控制]\n F --> H[执行工具或生成响应]\n \n B --> I{asTool 调用?}\n I -->|Yes| J[AgentTool Invocation]\n J --> K[目标 Agent 作为工具执行]\n K --> L[结果返回给原始 Agent]\n L --> B\n```\n\n## Handoff 组件详解\n\n### Handoff 类\n\n`Handoff` 类是交接机制的核心实现，封装了源 Agent 到目标 Agent 的转换逻辑。资料来源：[packages/agents-core/src/handoff.ts:50-80]()\n\n```typescript\nexport class Handoff<\n TContext = UnknownContext,\n TOutput extends AgentOutputType = TextOutput,\n> {\n public agentName: string;\n public onInvokeHandoff: (\n context: RunContext,\n args: string,\n ) => Promise> | Agent;\n public toolName: string;\n public toolDescription: string;\n public agent: Agent;\n public isEnabled: HandoffEnabledFunction = async () => true;\n \n constructor(\n agent: Agent,\n onInvokeHandoff: (context: RunContext, args: string) => Promise> | Agent,\n ) {\n this.agentName = agent.name;\n this.onInvokeHandoff = onInvokeHandoff;\n this.toolName = defaultHandoffToolName(agent);\n this.toolDescription = defaultHandoffToolDescription(agent);\n this.agent = agent;\n }\n}\n```\n\n### HandoffConfig 配置选项\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `toolNameOverride` | `string` | 自定义 Handoff 工具名称 |\n| `toolDescriptionOverride` | `string` | 自定义 Handoff 工具描述 |\n| `onHandoff` | `OnHandoffCallback` | 交接触发时的回调函数 |\n| `inputType` | `TInputType extends ToolInputParameters` | 输入参数类型，支持 Zod Schema |\n\n资料来源：[packages/agents-core/src/handoff.ts:80-120]()\n\n### OnHandoffCallback 回调\n\n```typescript\nexport type OnHandoffCallback = (\n context: RunContext,\n input?: ResolveParsedToolParameters,\n) => Promise | void;\n```\n\n回调函数在 Handoff 被触发时执行，可用于日志记录、数据收集或状态更新。资料来源：[packages/agents-core/src/handoff.ts:70-75]()\n\n### HandoffEnabledFunction 条件启用\n\n```typescript\ntype HandoffEnabledFunction = (\n context: RunContext,\n args?: string,\n) => boolean | Promise;\n```\n\n通过此函数可以实现基于上下文的条件性 Handoff，例如根据用户偏好或功能开关控制交接是否可用。资料来源：[examples/handoffs/README.md]()\n\n## Agent 类的 Handoff 支持\n\n### handoffs 属性\n\n```typescript\nexport class Agent<\n TContext = UnknownContext,\n TOutput extends AgentOutputType = TextOutput,\n> extends AgentHooks\n implements AgentConfiguration\n{\n handoffs: (Agent | Handoff)[];\n // ... 其他属性\n}\n```\n\nAgent 的 `handoffs` 数组包含该 Agent 可以交接到的所有目标 Agent 或 Handoff 实例。资料来源：[packages/agents-core/src/agent.ts:120-130]()\n\n### HandoffsOutputUnion 类型推导\n\n```typescript\ntype ExtractAgentOutput = T extends Agent ? O : never;\ntype ExtractHandoffOutput = T extends Handoff ? O : never;\n\nexport type HandoffsOutputUnion<\n Handoffs extends readonly (Agent | Handoff)[],\n> =\n | ExtractAgentOutput\n | ExtractHandoffOutput;\n```\n\n此类型工具自动从 Handoff 列表中提取输出类型的联合类型，确保类型安全。资料来源：[packages/agents-core/src/agent.ts:160-175]()\n\n### Agent.create 静态工厂方法\n\n```typescript\nstatic create<\n TOutput extends AgentOutputType = TextOutput,\n Handoffs extends readonly (Agent | Handoff)[] = [],\n>(\n config: AgentConfigWithHandoffs,\n): Agent> {\n return new Agent>({\n ...config,\n handoffs: config.handoffs as any,\n outputType: config.outputType,\n handoffOutputTypeWarningEnabled: false,\n });\n}\n```\n\n`Agent.create()` 方法自动推断 Handoff 输出的联合类型，是创建带 Handoff 的 Agent 的推荐方式。资料来源：[packages/agents-core/src/agent.ts:85-100]()\n\n## Agent as Tool（委托）\n\n### asTool 方法重载\n\n```typescript\nexport class Agent<...> {\n asTool = Agent>(\n this: TAgent,\n options: AgentToolOptionsWithDefault,\n ): AgentTool;\n \n asTool<\n TAgent extends Agent = Agent,\n TParameters extends AgentToolInputParameters = typeof AgentAsToolInputSchema,\n >(\n this: TAgent,\n options: AgentToolOptionsWithParameters,\n ): AgentTool;\n}\n```\n\n`asTool()` 方法将 Agent 转换为可被其他 Agent 调用的工具。与 Handoff 的关键区别在于：资料来源：[packages/agents-core/src/agent.ts:60-90]()\n\n1. **对话历史不传递**：新 Agent 接收的是生成的输入，而非完整对话历史\n2. **控制权不转移**：对话由原始 Agent 继续控制\n3. **结果返回**：被委托 Agent 的结果作为工具输出返回给调用者\n\n### AgentToolOptions 配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `toolName` | `string` | 工具名称，默认为 Agent 名称 |\n| `toolDescription` | `string` | 工具描述，说明工具用途 |\n| `customOutputExtractor` | `function` | 自定义输出提取器 |\n| `needsApproval` | `boolean \\| ToolApprovalFunction` | 调用前是否需要审批 |\n| `parameters` | `TParameters` | 输入参数 Schema |\n| `inputBuilder` | `AgentToolInputBuilder` | 构建嵌套 Agent 输入 |\n| `includeInputSchema` | `boolean` | 是否包含完整 JSON Schema |\n\n资料来源：[packages/agents-core/src/agent.ts:130-180]()\n\n## RealtimeAgent 中的 Handoff\n\n```typescript\nexport type RealtimeAgentConfiguration = Partial<\n Omit<\n AgentConfiguration, TextOutput>,\n 'model' | 'handoffs' | 'modelSettings' | 'outputType' | 'toolUseBehavior'\n >\n> & {\n name: string;\n handoffs?: (\n | RealtimeAgent\n | Handoff, TextOutput>\n )[];\n voice?: string;\n};\n```\n\nRealtimeAgent 支持 Handoff，但不支持 `model`、`modelSettings` 等配置，因为所有 RealtimeAgent 在同一个 RealtimeSession 中由相同模型处理。资料来源：[packages/agents-core/src/realtimeAgent.ts:1-40]()\n\n## Handoff 解析与执行\n\n### modelOutputs.ts 中的解析逻辑\n\n```typescript\nexport function resolveToolCall(\n toolCall: FunctionToolCall,\n agent: Agent,\n tools: Tool[],\n handoffs: (Agent | Handoff)[],\n priorItems: RunItem[],\n): { type: 'handoff'; handoff: Handoff } | { type: 'function'; tool: FunctionTool } {\n const resolvedToolName = resolveFunctionToolCallName(toolCall, functionMap) ?? toolCall.name;\n \n if (functionTool && handoff && resolvedToolName.includes('.')) {\n throw new ModelBehaviorError(\n `Ambiguous dotted tool call ${resolvedToolName} in agent ${agent.name}: it matches both a namespaced function tool and a handoff.`\n );\n }\n \n if (handoff) {\n return { type: 'handoff', handoff };\n }\n \n // ...\n}\n```\n\n系统会解析工具调用名称，如果同时匹配函数工具和 Handoff，会抛出歧义错误。资料来源：[packages/agents-core/src/runner/modelOutputs.ts:1-60]()\n\n### handoffMap 和 functionMap 初始化\n\n```typescript\nconst handoffMap = new Map(handoffs.map((h) => [h.toolName, h]));\nconst functionMap = new Map(\n tools\n .filter((t): t is FunctionTool => t.type === 'function')\n .map((t) => [getFunctionToolQualifiedName(t) ?? t.name, t]),\n);\n```\n\n通过 Map 数据结构实现 O(1) 时间复杂度的工具查找。资料来源：[packages/agents-core/src/runner/modelOutputs.ts:80-100]()\n\n## 使用示例\n\n### 基础 Handoff 用法\n\n```typescript\nimport { Agent, Handoff } from '@openai/agents-core';\n\nconst spanishAgent = Agent.create({\n name: 'Spanish Agent',\n instructions: 'You only speak Spanish.',\n handoffDescription: 'For Spanish language requests',\n});\n\nconst triageAgent = Agent.create({\n name: 'Triage Agent',\n instructions: 'Route requests to the appropriate agent.',\n handoffs: [spanishAgent],\n});\n```\n\n### 带条件的 Handoff\n\n```typescript\nconst spanishHandoff = new Handoff(spanishAgent, {\n inputType: z.object({ reason: z.string() }),\n isEnabled: async (context) => {\n const userPrefs = context.context.userPreferences;\n return userPrefs.language === 'es';\n },\n onHandoff: async (context) => {\n console.log(`Handoff to Spanish agent triggered`);\n },\n});\n```\n\n### Agent as Tool 用法\n\n```typescript\nconst translatorAgent = Agent.create({\n name: 'Translator',\n instructions: 'Translate the following text to Spanish.',\n});\n\nconst mainAgent = Agent.create({\n name: 'Main Agent',\n instructions: 'Use the translator when needed.',\n tools: [translatorAgent.asTool({\n toolName: 'translate_to_spanish',\n toolDescription: 'Translate English text to Spanish',\n })],\n});\n```\n\n资料来源：[examples/agent-patterns/README.md]()\n\n## 生命周期事件\n\n```typescript\nexport type AgentHookEvents = {\n agent_handoff: [\n context: RunContext,\n nextAgent: Agent,\n ];\n agent_tool_start: [\n context: RunContext,\n tool: Tool,\n details: { toolCall: protocol.ToolCallItem },\n ];\n agent_tool_end: [\n context: RunContext,\n tool: Tool,\n result: string,\n details: { toolCall: protocol.ToolCallItem },\n ];\n};\n```\n\n`agent_handoff` 事件在 Handoff 发生时触发，可用于监控和日志记录。资料来源：[packages/agents-core/src/lifecycle.ts:1-50]()\n\n## 最佳实践\n\n| 场景 | 推荐方案 |\n|------|----------|\n| 多角色对话 | 使用 Handoff |\n| 工具化调用 | 使用 asTool |\n| 需要条件判断 | 实现 HandoffEnabledFunction |\n| 状态同步 | 使用 OnHandoffCallback |\n| 类型安全 | 使用 Agent.create() 工厂方法 |\n| 避免歧义 | 不要让 Handoff 工具名与函数工具名冲突 |\n\n## 总结\n\nHandoffs 与 Agent 委托是实现多代理协作的两种互补机制：\n\n- **Handoff**：适合角色切换、任务委派场景，完整传递对话历史，控制权完全转移\n- **Agent as Tool**：适合工具化调用、子任务执行场景，通过参数传递输入，控制权保持在调用者\n\n合理选择和组合这两种机制，可以构建出复杂而灵活的多代理系统架构。\n\n---\n\n\n\n## Guardrails 安全防护\n\n### 相关页面\n\n相关主题：[Agent 核心机制](#page-agents), [工具系统](#page-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents-core/src/guardrail.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/guardrail.ts)\n- [packages/agents-core/src/toolGuardrail.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/toolGuardrail.ts)\n- [packages/agents-core/src/runner/guardrails.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/runner/guardrails.ts)\n- [packages/agents-core/src/runner/errorHandlers.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/runner/errorHandlers.ts)\n- [packages/agents-core/src/agent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/agent.ts)\n \n\n# Guardrails 安全防护\n\n## 概述\n\nGuardrails（安全防护）是 openai-agents-js 框架中用于在 Agent 运行过程中对输入、输出和工具调用进行安全检查和质量控制的机制。Guardrails 允许开发者在 AI 模型生成响应之前（输入阶段）或之后（输出阶段）插入自定义验证逻辑，从而实现：\n\n- 过滤有害或不安全的用户输入\n- 阻止包含敏感信息的模型输出\n- 验证工具调用的安全性\n- 实现业务规则合规检查\n\n资料来源：[packages/agents-core/src/guardrail.ts:1-50]()\n\n## Guardrails 类型体系\n\n框架支持两种主要的 Guardrail 类型，分别用于不同的检查阶段：\n\n| Guardrail 类型 | 作用阶段 | 检查内容 | 命名空间 |\n|---------------|---------|---------|---------|\n| InputGuardrail | 模型调用前 | 用户输入、对话历史 | `inputGuardrails` |\n| OutputGuardrail | 模型调用后 | 模型生成的文本、结构化输出 | `outputGuardrails` |\n| ToolOutputGuardrail | 工具执行后 | 工具返回的结果内容 | `toolOutputGuardrails` |\n\n资料来源：[packages/agents-core/src/guardrail.ts:10-60]()\n\n## 输出防护（Output Guardrail）\n\n### 核心接口定义\n\n```typescript\nexport interface OutputGuardrail<\n TOutput extends AgentOutputType = TextOutput,\n TContext = UnknownContext,\n> {\n name: string;\n execute: OutputGuardrailFunction;\n}\n```\n\n资料来源：[packages/agents-core/src/guardrail.ts:30-40]()\n\nOutputGuardrail 接口包含两个必需属性：\n\n- **name**: 防护规则的唯一标识名称\n- **execute**: 执行检查的异步函数\n\n### 定义函数\n\n开发者使用 `defineOutputGuardrail` 工厂函数创建 OutputGuardrail 实例：\n\n```typescript\nexport function defineOutputGuardrail<\n TOutput extends AgentOutputType = TextOutput,\n TContext = UnknownContext,\n>({\n name,\n execute,\n}: DefineOutputGuardrailArgs): OutputGuardrailDefinition\n```\n\n资料来源：[packages/agents-core/src/guardrail.ts:70-85]()\n\n### 元数据定义\n\n```typescript\nexport interface OutputGuardrailMetadata {\n type: 'output';\n name: string;\n}\n\nexport interface OutputGuardrailDefinition<\n TMeta = OutputGuardrailMetadata,\n TOutput extends AgentOutputType = TextOutput,\n TContext = UnknownContext,\n> extends OutputGuardrailMetadata {\n guardrailFunction: OutputGuardrailFunction;\n run(args: OutputGuardrailFunctionArgs): Promise;\n}\n```\n\n资料来源：[packages/agents-core/src/guardrail.ts:42-55]()\n\n## 工具输出防护（Tool Output Guardrail）\n\nToolOutputGuardrail 专门用于检查工具执行后的返回结果，防止工具泄露敏感信息或返回不符合预期的内容。\n\n### 工具输出防护初始化\n\n```typescript\nexport type ToolOutputGuardrailInit = {\n name: string;\n run: (\n context: RunContext,\n result: ToolResult,\n ) => Promise;\n};\n```\n\n资料来源：[packages/agents-core/src/toolGuardrail.ts:1-20]()\n\n### 工具输出防护工厂函数\n\n```typescript\nexport function defineToolOutputGuardrail(\n guardrail: ToolOutputGuardrailInit\n): ToolOutputGuardrailDefinition\n```\n\n资料来源：[packages/agents-core/src/toolGuardrail.ts:22-35]()\n\n### 防护注册转换\n\n`guardrailsFromInit` 函数负责将初始化配置转换为完整的防护定义：\n\n```typescript\nexport function guardrailsFromInit(\n guardrails: ToolOutputGuardrailInit[]\n): ToolOutputGuardrailDefinition[] {\n if (!guardrails) {\n return [];\n }\n return guardrails.map((gr) =>\n 'type' in gr && gr.type === 'tool_output'\n ? (gr as ToolOutputGuardrailDefinition)\n : defineToolOutputGuardrail(gr as { name: string; run: any }),\n );\n}\n```\n\n资料来源：[packages/agents-core/src/toolGuardrail.ts:38-52]()\n\n## 错误处理与防护联动\n\n框架将错误处理与 Guardrail 系统紧密集成，通过 `RunErrorHandlers` 类型支持对特定错误类型执行防护检查。\n\n### 错误处理器类型\n\n```typescript\nexport type RunErrorHandler> = (\n input: RunErrorHandlerInput,\n) => RunErrorHandlerResult | void | Promise | void>;\n```\n\n资料来源：[packages/agents-core/src/runner/errorHandlers.ts:60-65]()\n\n### 错误处理器结果\n\n```typescript\nexport type RunErrorHandlerResult> = {\n finalOutput: ResolvedAgentOutput;\n includeInHistory?: boolean;\n};\n```\n\n资料来源：[packages/agents-core/src/runner/errorHandlers.ts:48-55]()\n\n### 错误处理注册表\n\n```typescript\nexport type RunErrorHandlers> = \n Partial>> & {\n default?: RunErrorHandler;\n };\n```\n\n资料来源：[packages/agents-core/src/runner/errorHandlers.ts:67-73]()\n\n## Agent 配置中的 Guardrails\n\n在创建 Agent 实例时，通过配置对象传入 Guardrails：\n\n```typescript\nexport class Agent<\n TContext = UnknownContext,\n TOutput extends AgentOutputType = TextOutput,\n> extends AgentHooks\n implements AgentConfiguration\n```\n\n资料来源：[packages/agents-core/src/agent.ts:45-60]()\n\nAgent 支持在配置中定义 `inputGuardrails` 和 `outputGuardrails` 数组，这些防护规则会在相应的生命周期阶段被自动调用。\n\n## 架构流程图\n\n```mermaid\ngraph TD\n A[用户输入] --> B{Input Guardrails}\n B -->|通过| C[Agent 推理]\n B -->|拒绝| Z[返回错误]\n C --> D[工具调用]\n D --> E{Tool Output Guardrails}\n E -->|通过| F[Agent 输出]\n E -->|拒绝| Z\n F --> G{Output Guardrails}\n G -->|通过| H[返回结果]\n G -->|拒绝| Z\n \n style Z fill:#ff6b6b\n style H fill:#51cf66\n```\n\n## 使用示例\n\n### 创建输出防护\n\n```typescript\nimport { defineOutputGuardrail } from '@openai/agents';\n\nconst contentFilter = defineOutputGuardrail({\n name: 'content-filter',\n execute: async ({ context, response }) => {\n const flagged = await checkForHarmfulContent(response.content);\n return {\n decision: flagged ? 'flagged' : 'pass',\n reason: flagged ? 'Content violates safety policy' : undefined,\n };\n },\n});\n```\n\n### 创建工具输出防护\n\n```typescript\nimport { defineToolOutputGuardrail } from '@openai/agents';\n\nconst fileSystemGuard = defineToolOutputGuardrail({\n name: 'file-system-filter',\n run: async (context, result) => {\n const sensitivePaths = ['/etc/passwd', '/root/.ssh'];\n if (sensitivePaths.some(p => result.output.includes(p))) {\n return { decision: 'flagged', reason: 'Access to sensitive path denied' };\n }\n return { decision: 'pass' };\n },\n});\n```\n\n## 防护决策类型\n\n| 决策值 | 含义 | 后续动作 |\n|-------|------|---------|\n| `pass` | 检查通过 | 继续执行 |\n| `flagged` | 检查发现问题 | 返回错误或拒绝输出 |\n| `neutral` | 无法判断 | 根据配置决定放行或拒绝 |\n\n## 总结\n\nGuardrails 安全防护系统为 openai-agents-js 提供了多层安全检查机制：\n\n1. **输入层防护** (`Input Guardrails`): 在模型处理前过滤有害输入\n2. **工具层防护** (`Tool Output Guardrails`): 验证工具返回内容的安全性\n3. **输出层防护** (`Output Guardrails`): 检查最终响应的合规性\n\n该系统采用声明式配置方式，通过统一的 `defineXxxGuardrail` 工厂函数创建防护实例，并支持异步执行和上下文感知检查，适配企业级应用的复杂安全需求。\n\n---\n\n\n\n## 沙箱 Agent\n\n### 相关页面\n\n相关主题：[沙箱运行时与容器](#page-sandbox-runtime), [Agent 核心机制](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents-core/src/sandbox/agent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/sandbox/agent.ts)\n- [packages/agents-core/src/sandbox/manifest.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/sandbox/manifest.ts)\n- [packages/agents-core/src/sandbox/local.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/sandbox/local.ts)\n- [packages/agents-core/src/sandbox/memory/prompts.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/sandbox/memory/prompts.ts)\n- [packages/agents-core/src/sandbox/capabilities/skills.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/sandbox/capabilities/skills.ts)\n \n\n# 沙箱 Agent\n\n## 概述\n\n沙箱 Agent（Sandbox Agent）是 OpenAI Agents SDK 中的一种专用 Agent 类型，它继承自基础 `Agent` 类并在运行时环境中提供了安全的代码执行能力。沙箱 Agent 允许 AI Agent 在隔离的运行时环境中执行代码、访问文件系统并运行各种工具，同时保持安全边界以防止对主机系统的未授权访问。\n\n沙箱 Agent 的核心职责包括：\n\n- 在隔离环境中执行 Agent 生成的代码\n- 管理文件系统的读写操作权限\n- 提供可配置的运行时 Manifest 定义允许的操作范围\n- 支持以指定用户身份运行以实现权限隔离\n\n资料来源：[agent.ts:1-50]()\n\n## 架构设计\n\n### 继承关系\n\n沙箱 Agent 继承自标准的 `Agent` 类，并扩展了沙箱特定的功能。这种设计允许沙箱 Agent 复用 Agent 的所有核心功能，包括工具调用、handoffs、guardrails 和生命周期钩子。\n\n```mermaid\ngraph TD\n A[Agent<TContext, TOutput>] -->|extends| B[AgentHooks]\n B --> C[Agent]\n C -->|extends| D[SandboxAgent<TContext, TOutput>]\n \n E[AgentConfiguration] -->|提供配置接口| C\n F[SandboxAgentOptions] -->|扩展配置| E\n```\n\n资料来源：[agent.ts:50-80]()\n\n### 核心组件\n\n| 组件 | 类型 | 说明 |\n|------|------|------|\n| `defaultManifest` | `Manifest \\| undefined` | 默认的沙箱 Manifest，定义允许的操作范围 |\n| `baseInstructions` | `SandboxBaseInstructions` | 基础指令，传递给沙箱运行的代码 |\n| `capabilities` | `Capability[]` | 沙箱能力数组，控制可用功能 |\n| `runAs` | `string \\| SandboxUser` | 以特定用户身份运行的配置 |\n| `runtimeManifest` | `Manifest` | 运行时 Manifest，可动态更新 |\n\n资料来源：[agent.ts:35-45]()\n\n## SandboxAgent 类\n\n### 类定义\n\n```typescript\nexport class SandboxAgent<\n TContext = UnknownContext,\n TOutput extends AgentOutputType = TextOutput,\n> extends Agent\n implements SandboxAgentOptions\n{\n // ... 实现代码\n}\n```\n\n沙箱 Agent 是一个泛型类，接受两个类型参数：\n\n- `TContext`：运行上下文类型，默认为 `UnknownContext`\n- `TOutput`：输出类型，默认为 `TextOutput`\n\n资料来源：[agent.ts:50-60]()\n\n### 构造函数\n\n构造函数接收 `SandboxAgentOptions` 配置对象，并对配置进行验证：\n\n```typescript\nconstructor(config: SandboxAgentOptions) {\n super(config);\n \n // 验证 baseInstructions 类型\n if (\n config.baseInstructions !== undefined &&\n typeof config.baseInstructions !== 'string' &&\n typeof config.baseInstructions !== 'function'\n ) {\n throw new TypeError(\n 'SandboxAgent baseInstructions must be a string or function.',\n );\n }\n \n // 初始化沙箱配置\n this.defaultManifest = config.defaultManifest\n ? cloneManifest(config.defaultManifest)\n : undefined;\n this.baseInstructions = config.baseInstructions;\n this.capabilities = config.capabilities ?? Capabilities.default();\n this.runAs = normalizeRunAs(config.runAs);\n this.runtimeManifest = this.defaultManifest ?? new Manifest();\n}\n```\n\n**关键验证规则**：\n\n- `baseInstructions` 必须为 `string` 类型或 `function` 类型，否则抛出 `TypeError`\n\n资料来源：[agent.ts:55-85]()\n\n### clone 方法\n\n沙箱 Agent 支持通过 `clone` 方法创建新的实例，允许部分覆盖配置：\n\n```typescript\noverride clone(\n config: Partial>,\n): SandboxAgent {\n return new SandboxAgent({\n name: config.name ?? this.name,\n instructions: config.instructions ?? this.instructions,\n prompt: config.prompt ?? this.prompt,\n handoffDescription: config.handoffDescription ?? this.handoffDescription,\n handoffs: config.handoffs ?? this.handoffs,\n model: config.model ?? this.model,\n modelSettings: config.modelSettings ?? this.modelSettings,\n tools: config.tools ?? this.tools,\n mcpServers: config.mcpServers ?? this.mcpServers,\n mcpConfig: config.mcpConfig ?? this.mcpConfig,\n inputGuardrails: config.inputGuardrails ?? this.inputGuardrails,\n // ... 其他配置项\n });\n}\n```\n\n该方法采用**浅拷贝策略**：对于非对象配置项使用 `??` 操作符合并，对于数组和对象配置项直接复用原实例引用。\n\n资料来源：[agent.ts:90-110]()\n\n## 配置选项详解\n\n### SandboxAgentOptions\n\n| 选项 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `name` | `string` | 是 | - | Agent 名称 |\n| `instructions` | `string \\| function` | 否 | - | 系统提示词 |\n| `tools` | `Tool[]` | 否 | `[]` | 可用工具列表 |\n| `model` | `string \\| Model` | 否 | 默认模型 | 使用的 AI 模型 |\n| `modelSettings` | `ModelSettings` | 否 | - | 模型设置 |\n| `defaultManifest` | `Manifest` | 否 | `undefined` | 默认 Manifest |\n| `baseInstructions` | `string \\| function` | 否 | - | 基础执行指令 |\n| `capabilities` | `Capability[]` | 否 | `Capabilities.default()` | 沙箱能力列表 |\n| `runAs` | `string \\| SandboxUser` | 否 | - | 运行用户身份 |\n| `mcpServers` | `MCPServer[]` | 否 | - | MCP 服务器配置 |\n| `mcpConfig` | `Record` | 否 | - | MCP 额外配置 |\n\n资料来源：[agent.ts:30-48]()\n\n### Manifest 配置\n\nManifest 定义了沙箱运行时允许的操作范围，包括文件路径白名单、允许的命令等。每个沙箱 Agent 维护两个 Manifest 实例：\n\n1. **`defaultManifest`**：静态配置的默认 Manifest\n2. **`runtimeManifest`**：运行时动态更新的 Manifest\n\nManifest 克隆使用专用的 `cloneManifest` 函数确保不可变性。\n\n资料来源：[manifest.ts](), [agent.ts:75-80]()\n\n### Capabilities 能力系统\n\nCapabilities 定义了沙箱可执行的具体功能。默认能力集通过 `Capabilities.default()` 获取，可通过覆盖 `capabilities` 选项进行定制。\n\n资料来源：[capabilities/skills.ts]()\n\n## 沙箱与本地执行环境\n\n### 本地沙箱执行\n\n沙箱 Agent 支持本地执行模式，通过 `local.ts` 模块提供。执行时序如下：\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant SandboxAgent\n participant Manifest\n participant 本地沙箱\n participant 文件系统\n \n 用户->>SandboxAgent: 调用 run()\n SandboxAgent->>Manifest: 验证 runtimeManifest\n Manifest->>本地沙箱: 授权操作\n 本地沙箱->>文件系统: 读写文件\n 文件系统-->>本地沙箱: 操作结果\n 本地沙箱-->>Manifest: 执行完成\n Manifest-->>SandboxAgent: 输出结果\n SandboxAgent-->>用户: 返回最终结果\n```\n\n资料来源：[local.ts](), [agent.ts:1-100]()\n\n### 文件系统安全\n\n沙箱 Agent 通过以下机制确保文件系统安全：\n\n1. **路径解析验证**：使用 `realpath -m` 解析绝对路径，防止符号链接绕过\n2. **目录边界检查**：确保操作不会超出 `workspace root` 范围\n3. **文件名限制**：禁止创建目录类型的目标文件\n\n关键实现逻辑示例：\n\n```bash\nresolved_root=$(realpath -m -- \"$root\")\nparent=$(dirname -- \"$path\")\nresolved_parent=$(realpath -m -- \"$parent\")\n\n# 验证路径在允许范围内\ncase \"$resolved_parent\" in \n \"$resolved_root\"|\"$resolved_root\"/*) ;; \n *) printf \"workspace escape: %s\\\\n\" \"$resolved_parent\" >&2; exit 111 ;; \nesac\n```\n\n资料来源：[sandbox.ts (agents-extensions)](), [memory/prompts.ts]()\n\n## 使用模式\n\n### 基本用法\n\n```typescript\nimport { SandboxAgent } from '@openai/agents-core';\n\nconst sandboxAgent = new SandboxAgent({\n name: 'code-executor',\n instructions: '你是一个代码执行助手',\n tools: [/* 工具列表 */],\n baseInstructions: '在沙箱中执行代码时，请确保安全',\n capabilities: Capabilities.default(),\n});\n```\n\n### 带 Manifest 的配置\n\n```typescript\nimport { Manifest } from '@openai/agents-core';\n\nconst manifest = new Manifest({\n root: '/workspace/project',\n allowedPaths: ['/workspace/project/src'],\n});\n\nconst agent = new SandboxAgent({\n name: 'secure-coder',\n instructions: '在受限环境中编写代码',\n defaultManifest: manifest,\n});\n```\n\n### Agent as Tool 模式\n\n沙箱 Agent 可以作为工具被其他 Agent 调用，通过 `Agent.asTool()` 方法暴露：\n\n```typescript\nconst executorTool = executorAgent.asTool({\n toolName: 'code-executor',\n toolDescription: '在沙箱中安全执行代码',\n});\n```\n\n资料来源：[agent.ts (Agent.asTool)](), [examples/agent-patterns/README.md]()\n\n## 与标准 Agent 的区别\n\n| 特性 | 标准 Agent | 沙箱 Agent |\n|------|------------|------------|\n| 代码执行 | 依赖外部环境 | 内置沙箱隔离 |\n| 权限控制 | 无内置机制 | Manifest + Capabilities |\n| 用户身份 | 不支持 | `runAs` 选项 |\n| 文件系统 | 无限制 | 路径白名单验证 |\n| 适用场景 | 通用对话 | 安全代码执行 |\n\n资料来源：[agent.ts:1-120](), [agent.ts:agent-class]()\n\n## 最佳实践\n\n### 安全配置\n\n1. **最小权限原则**：仅启用必要的 Capabilities\n2. **Manifest 边界**：设置狭窄的 `workspace root` 和 `allowedPaths`\n3. **用户隔离**：使用 `runAs` 指定非特权用户运行\n\n### 性能优化\n\n1. **Manifest 缓存**：避免重复创建相同的 Manifest 实例\n2. **clone 复用**：对于配置相似的 Agent，使用 `clone` 方法而非重新创建\n3. **能力精简**：移除未使用的工具以减少 Agent 初始化开销\n\n### 错误处理\n\n沙箱 Agent 的错误处理通过 `RunErrorHandler` 机制实现，支持的错误类型包括：\n\n- `MaxTurnsExceededError`：超出最大轮次限制\n- `ModelRefusalError`：模型拒绝执行\n\n```typescript\nconst agent = new SandboxAgent({\n name: 'robust-executor',\n instructions: instructions,\n errorHandlers: {\n maxTurnsExceeded: async (input) => {\n return {\n finalOutput: generateTimeoutResponse(),\n includeInHistory: true,\n };\n },\n },\n});\n```\n\n资料来源：[errorHandlers.ts]()\n\n## 总结\n\n沙箱 Agent 是 OpenAI Agents SDK 中专为安全代码执行设计的 Agent 类型。通过继承标准 Agent 的全部功能并扩展沙箱特定能力，开发者可以在保持 Agent 框架一致性的同时，获得可靠的隔离执行环境。Manifest 系统和 Capabilities 机制共同提供了细粒度的权限控制，而 `runAs` 选项则支持以不同用户身份运行的场景。\n\n---\n\n\n\n## 沙箱运行时与容器\n\n### 相关页面\n\n相关主题：[沙箱 Agent](#page-sandbox-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents-core/src/sandbox/sandboxes/docker.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/sandbox/sandboxes/docker.ts)\n- [packages/agents-core/src/sandbox/sandboxes/unixLocal.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/sandbox/sandboxes/unixLocal.ts)\n- [packages/agents-core/src/sandbox/runtime/manager.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/sandbox/runtime/manager.ts)\n- [packages/agents-core/src/sandbox/sandboxes/shared/pty.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/sandbox/sandboxes/shared/pty.ts)\n- [packages/agents-core/src/sandbox/agent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/sandbox/agent.ts)\n- [packages/agents-core/src/tool.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/tool.ts)\n- [packages/agents-core/src/sandbox/capabilities/memory.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/sandbox/capabilities/memory.ts)\n- [packages/agents-extensions/src/sandbox/daytona/sandbox.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-extensions/src/sandbox/daytona/sandbox.ts)\n \n\n# 沙箱运行时与容器\n\n## 概述\n\n沙箱运行时与容器是 OpenAI Agents SDK 中提供安全隔离执行环境的核心子系统。该系统允许 AI Agent 在受限的文件系统和 Shell 环境中执行操作，同时保持与主机环境的适当隔离。沙箱机制支持多种后端实现，包括本地 Unix 环境、Docker 容器以及第三方云沙箱服务。\n\n沙箱的核心职责包括：\n\n- **进程隔离**：在受限环境中执行 Shell 命令\n- **文件系统安全**：限制 Agent 对特定目录树的访问\n- **资源控制**：管理内存限制、网络策略等\n- **路径翻译**：透明处理工作区与主机之间的路径映射\n- **生命周期管理**：创建、暂停、恢复和销毁沙箱会话\n\n## 核心架构\n\n### 沙箱类型体系\n\nSDK 支持三种主要的沙箱环境类型：\n\n| 类型 | 标识符 | 适用场景 | 配置要求 |\n|------|--------|----------|----------|\n| 本地沙箱 | `local` | 开发调试、直接进程执行 | 只需提供 Shell 实现 |\n| 自动容器 | `container_auto` | 按需创建临时容器 | 需要 Docker 等容器运行时 |\n| 容器引用 | `container_reference` | 复用已有容器 | 必须提供 `containerId` |\n\n资料来源：[packages/agents-core/src/tool.ts:1-50]()\n\n### 沙箱环境配置接口\n\n```typescript\ninterface ShellToolEnvironment {\n type: 'local' | 'container_auto' | 'container_reference';\n fileIds?: string[];\n memoryLimit?: string;\n networkPolicy?: ShellToolContainerNetworkPolicy;\n skills?: ShellToolContainerSkill[];\n containerId?: string;\n}\n```\n\n环境规范化函数 `normalizeShellToolEnvironment` 负责验证配置完整性：\n\n```typescript\nexport function normalizeShellToolEnvironment(\n environment: ShellToolEnvironment | undefined,\n): NormalizedShellToolEnvironment {\n if (!environment || environment.type === 'local') {\n return environment ?? { type: 'local' };\n }\n\n if (environment.type === 'container_auto') {\n return {\n type: 'container_auto',\n fileIds: environment.fileIds,\n memoryLimit: environment.memoryLimit,\n networkPolicy: normalizeShellToolContainerNetworkPolicy(\n environment.networkPolicy,\n ),\n skills: environment.skills?.map(normalizeShellToolContainerSkill),\n };\n }\n\n const containerId = environment.containerId;\n if (!containerId) {\n throw new UserError(\n 'shellTool with container_reference environment requires a containerId.',\n );\n }\n\n return { type: 'container_reference', containerId };\n}\n```\n\n资料来源：[packages/agents-core/src/tool.ts]()\n\n## 本地沙箱实现\n\n### UnixLocalSandbox 类\n\n`UnixLocalSandbox` 是本地沙箱的核心实现类，负责在本地文件系统上创建隔离的 Shell 执行环境。\n\n```typescript\nexport class UnixLocalSandbox implements SandboxLike {\n private shell: Shell;\n private state: SandboxState;\n \n private buildEnv(args: SandboxEnvironmentArgs): Record {\n return {\n HOME: this.state.manifest.root,\n PATH: process.env.PATH ?? '/usr/local/bin:/usr/bin:/bin',\n LANG: 'en_US.UTF-8',\n SHELL: args.shellPath,\n TMPDIR: '/tmp',\n ...args.environment,\n PWD: args.pwd,\n };\n }\n}\n```\n\n资料来源：[packages/agents-core/src/sandbox/sandboxes/unixLocal.ts]()\n\n### Shell 工具创建\n\n本地沙箱通过 `shellTool` 工厂函数创建，其签名如下：\n\n```typescript\nexport function shellTool(options: LocalShellToolOptions): NormalizedLocalShellTool;\nexport function shellTool(options: HostedShellToolOptions): HostedShellTool;\nexport function shellTool(\n options: LocalShellToolOptions | HostedShellToolOptions,\n): NormalizedLocalShellTool | HostedShellTool\n```\n\n关键验证逻辑确保本地环境配置完整：\n\n```typescript\nif (environment.type === 'local') {\n const localShell = options.shell;\n if (!localShell) {\n throw new UserError(\n 'shellTool with local environment requires a shell implementation.',\n );\n }\n // ... 创建本地 Shell 工具\n}\n```\n\n资料来源：[packages/agents-core/src/tool.ts]()\n\n## 路径翻译机制\n\n路径翻译是沙箱安全性的核心保障，确保 Agent 无法通过路径遍历访问受限目录。\n\n### 命令输入路径翻译\n\n系统提供两种路径翻译策略：\n\n#### 绝对路径翻译\n\n将绝对路径转换为工作区根目录的相对路径：\n\n```typescript\nfunction translateRootManifestCommandInput(\n command: string,\n workspaceRootPath: string,\n): string {\n return command.replace(\n /(^|[\\s\"'=<>])\\/([^\\s\"'|&;<>(){}]*)/g,\n (_match, prefix: string, pathSuffix: string) =>\n `${prefix}${workspaceRootPath}/${pathSuffix}`,\n );\n}\n```\n\n#### Manifest 根目录翻译\n\n将引用 Manifest 根目录的路径替换为工作区根目录：\n\n```typescript\nfunction translateManifestRootCommandInput(\n command: string,\n manifestRoot: string,\n workspaceRootPath: string,\n): string {\n const escapedManifestRoot = escapeRegExp(manifestRoot);\n const pathPrefix = String.raw`(^|[\\s\"'=<>])`;\n const pathSuffix = String.raw`(?=$|[\\/\\s\"'|&;<>(){}])`;\n return command.replace(\n new RegExp(`${pathPrefix}${escapedManifestRoot}${pathSuffix}`, 'g'),\n (_match, prefix: string) => `${prefix}${workspaceRootPath}`,\n );\n}\n```\n\n资料来源：[packages/agents-core/src/sandbox/sandboxes/unixLocal.ts]()\n\n### 命令输出路径翻译\n\n输出路径翻译将工作区路径反向映射回 Manifest 根目录：\n\n```typescript\nfunction translateRootManifestCommandOutput(\n output: string,\n workspaceRootPath: string,\n): string {\n return translateWorkspaceRootCommandOutput(output, '/', workspaceRootPath);\n}\n\nfunction translateManifestRootCommandOutput(\n output: string,\n manifestRoot: string,\n workspaceRootPath: string,\n): string {\n return translateWorkspaceRootCommandOutput(\n output,\n manifestRoot,\n workspaceRootPath,\n );\n}\n```\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[创建 ShellTool] --> B{environment.type}\n B -->|local| C[使用 UnixLocalSandbox]\n B -->|container_auto| D[创建新容器]\n B -->|container_reference| E[连接已有容器]\n \n C --> F[构建 Shell 环境变量]\n D --> G[初始化容器]\n E --> H[挂载容器]\n \n F --> I[执行命令]\n G --> I\n H --> I\n \n I --> J{路径翻译}\n J --> K[输入翻译]\n J --> L[输出翻译]\n \n K --> M[安全检查]\n L --> N[格式化输出]\n \n M --> O[执行 Shell 命令]\n O --> P[返回结果]\n```\n\n## SandboxAgent 核心组件\n\n### SandboxAgent 类定义\n\n`SandboxAgent` 是专门用于沙箱环境的 Agent 基类：\n\n```typescript\nexport class SandboxAgent<\n TContext,\n TOutput extends AgentOutputTypes,\n> extends Agent {\n disabled?: boolean;\n defaultManifest?: Manifest;\n baseInstructions?: SandboxBaseInstructions;\n capabilities: Capability[];\n runAs?: string | SandboxUser;\n runtimeManifest: Manifest;\n\n constructor(config: SandboxAgentOptions) {\n super(config);\n // 验证 baseInstructions 类型\n if (\n config.baseInstructions !== undefined &&\n typeof config.baseInstructions !== 'string' &&\n typeof config.baseInstructions !== 'function'\n ) {\n throw new TypeError(\n 'SandboxAgent baseInstructions must be a string or function.',\n );\n }\n // 初始化 Manifest 和配置\n this.defaultManifest = config.defaultManifest\n ? cloneManifest(config.defaultManifest)\n : undefined;\n this.baseInstructions = config.baseInstructions;\n this.capabilities = config.capabilities ?? Capabilities.default();\n this.runAs = normalizeRunAs(config.runAs);\n this.runtimeManifest = this.defaultManifest ?? new Manifest();\n }\n}\n```\n\n资料来源：[packages/agents-core/src/sandbox/agent.ts]()\n\n### 克隆与配置\n\n`SandboxAgent` 支持通过 `clone` 方法创建配置变体：\n\n```typescript\noverride clone(\n config: Partial>,\n): SandboxAgent {\n return new SandboxAgent({\n name: config.name ?? this.name,\n instructions: config.instructions ?? this.instructions,\n prompt: config.prompt ?? this.prompt,\n handoffDescription: config.handoffDescription ?? this.handoffDescription,\n handoffs: config.handoffs ?? this.handoffs,\n model: config.model ?? this.model,\n modelSettings: config.modelSettings ?? this.modelSettings,\n tools: config.tools ?? this.tools,\n mcpServers: config.mcpServers ?? this.mcpServers,\n mcpConfig: config.mcpConfig ?? this.mcpConfig,\n inputGuardrails: config.inputGuardrails ?? this.inputGuardrails,\n // ... 其他配置项\n });\n}\n```\n\n资料来源：[packages/agents-core/src/sandbox/agent.ts]()\n\n## 能力系统\n\n### 能力检测\n\n沙箱系统通过 `requiredCapabilityTypes()` 方法检测运行时所需能力：\n\n```typescript\noverride requiredCapabilityTypes(): Set {\n if (this.read === null) {\n return new Set();\n }\n if (this.read.liveUpdate) {\n return new Set(['filesystem', 'shell']);\n }\n return new Set(['shell']);\n}\n```\n\n对于内存功能，当启用实时更新时需要文件系统和 Shell 两种能力，否则仅需 Shell 能力。\n\n资料来源：[packages/agents-core/src/sandbox/capabilities/memory.ts]()\n\n### Manifest 处理\n\n`processManifest` 方法确保所需目录结构已创建：\n\n```typescript\noverride processManifest(manifest: Manifest): Manifest {\n if (this.read?.liveUpdate || this.generate !== null) {\n ensureDirectoryEntry(manifest, this.layout.memoriesDir);\n }\n if (this.generate !== null) {\n ensureDirectoryEntry(manifest, this.layout.sessionsDir);\n }\n return manifest;\n}\n```\n\n## 云沙箱扩展\n\n### Daytona 沙箱实现\n\nDaytona 云沙箱提供了企业级的沙箱执行环境：\n\n```typescript\nprivate async deleteEditorPath(path: string): Promise {\n const absolutePath = this.resolveEditorPath(path, { forWrite: true });\n await this.runEditorFileCommand([\n 'set -eu',\n `root=${shellQuote(this.state.manifest.root)}`,\n `path=${shellQuote(absolutePath)}`,\n 'resolved_root=$(realpath -m -- \"$root\")',\n 'parent=$(dirname -- \"$path\")',\n 'base=$(basename -- \"$path\")',\n 'resolved_parent=$(realpath -m -- \"$parent\")',\n 'case \"$resolved_parent\" in \"$resolved_root\"|\"$resolved_root\"/*) ;; *) printf \"workspace escape: %s\\\\n\" \"$resolved_parent\" >&2; exit 111 ;; esac',\n 'target=\"$resolved_parent/$base\"',\n 'if [ -d \"$target\" ]; then printf \"directory target: %s\\\\n\" \"$target\" >&2; exit 112; fi',\n 'tmp=$(mktemp \"$resolved_parent/.openai-agents-write.XXXXXX\")',\n 'cleanup() { rm -f -- \"$tmp\"; }',\n 'trap cleanup EXIT HUP INT TERM',\n 'base64 -d > \"$tmp\" <<\\'OPENAI_AGENTS_CONTENT\\'',\n encoded,\n 'OPENAI_AGENTS_CONTENT',\n 'chmod 644 \"$tmp\"',\n 'mv -f -- \"$tmp\" \"$target\"',\n 'trap - EXIT',\n ].join('\\n'));\n}\n```\n\n资料来源：[packages/agents-extensions/src/sandbox/daytona/sandbox.ts]()\n\n### 安全防护机制\n\nDaytona 实现包含多层安全检查：\n\n| 错误码 | 含义 | 触发条件 |\n|--------|------|----------|\n| `111` | 工作区逃逸 | 目标路径不在允许的根目录树内 |\n| `112` | 目录目标 | 写入操作目标是目录而非文件 |\n\n## 沙箱运行时管理器\n\n### 管理器职责\n\n运行时管理器 (`SandboxRuntimeManager`) 负责协调沙箱的生命周期：\n\n- 创建和初始化沙箱实例\n- 管理多个并发沙箱会话\n- 处理沙箱间的资源分配\n- 提供统一的错误处理和恢复机制\n\n### 会话管理\n\n```mermaid\ngraph LR\n A[创建 Manifest] --> B[初始化沙箱]\n B --> C[执行任务]\n C --> D{任务类型}\n D -->|读取| E[文件系统操作]\n D -->|执行| F[Shell 命令]\n D -->|记忆| G[内存读写]\n E --> H[清理资源]\n F --> H\n G --> H\n H --> I[保存快照]\n I --> J[会话结束]\n```\n\n## 工具类型与沙箱集成\n\n### 函数工具\n\n函数工具是沙箱中使用最广泛的工具类型：\n\n```typescript\nexport type FunctionTool<\n Context = UnknownContext,\n TParameters extends ToolInputParameters = undefined,\n Result = unknown,\n> = {\n type: 'function';\n name: string;\n description: string;\n parameters: JsonObjectSchema;\n strict: boolean;\n deferLoading?: boolean;\n invoke: (\n runContext: RunContext,\n input: string,\n details?: ToolCallDetails,\n ) => Promise;\n needsApproval?: boolean | ToolApprovalFunction;\n};\n```\n\n### 托管工具\n\n托管工具通过客户端执行器扩展沙箱功能：\n\n```typescript\nexport type ClientToolSearchExecutor = (\n args: ClientToolSearchExecutorArgs,\n) =>\n | Tool\n | Tool[]\n | null\n | undefined;\n```\n\n工具搜索执行器允许在运行时动态加载和执行工具，实现按需扩展。\n\n资料来源：[packages/agents-core/src/tool.ts]()\n\n## 错误处理\n\n### 错误处理器接口\n\n沙箱系统定义了专门的错误处理接口：\n\n```typescript\nexport type RunErrorHandler> = (\n input: RunErrorHandlerInput,\n) =>\n | RunErrorHandlerResult\n | void\n | Promise | void>;\n\nexport type RunErrorHandlers<\n TContext,\n TAgent extends Agent,\n> = Partial>> & {\n default?: RunErrorHandler;\n};\n```\n\n### 运行错误数据结构\n\n```typescript\nexport type RunErrorData> = {\n input: unknown;\n newItems: GenerationItem[];\n history: TurnInput;\n output: TurnInput;\n rawResponses: Response[];\n lastAgent?: TAgent;\n state?: RunState;\n};\n\nexport type RunErrorHandlerInput> = {\n error: MaxTurnsExceededError | ModelRefusalError;\n context: RunContext;\n runData: RunErrorData;\n};\n```\n\n资料来源：[packages/agents-core/src/runner/errorHandlers.ts]()\n\n## 使用示例\n\n### 基本沙箱配置\n\n```typescript\nimport { shellTool, SandboxAgent } from '@openai/agents';\n\nconst sandboxTool = shellTool({\n environment: {\n type: 'local',\n },\n shell: {\n async run(command, args) {\n return { output: 'result' };\n },\n },\n});\n\nconst agent = new SandboxAgent({\n name: 'sandbox-agent',\n instructions: '在沙箱中执行文件操作',\n tools: [sandboxTool],\n});\n```\n\n### Docker 容器沙箱\n\n```typescript\nimport { shellTool } from '@openai/agents';\n\nconst containerTool = shellTool({\n environment: {\n type: 'container_auto',\n memoryLimit: '2g',\n networkPolicy: 'deny',\n skills: ['javascript', 'bash'],\n },\n});\n```\n\n## 总结\n\n沙箱运行时与容器系统为 OpenAI Agents SDK 提供了强大的安全隔离执行能力。通过清晰的分层架构，系统支持本地开发、临时容器和持久容器引用等多种运行模式。路径翻译、安全检查和能力检测等机制确保了沙箱环境的安全性和可靠性。\n\n---\n\n\n\n## 实时语音 Agent\n\n### 相关页面\n\n相关主题：[传输层与集成](#page-transport-layer), [Agent 核心机制](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents-realtime/src/realtimeAgent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-realtime/src/realtimeAgent.ts)\n- [packages/agents-realtime/src/realtimeSession.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-realtime/src/realtimeSession.ts)\n- [packages/agents-realtime/src/openaiRealtimeWebsocket.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-realtime/src/openaiRealtimeWebsocket.ts)\n- [packages/agents-realtime/src/clientMessages.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-realtime/src/clientMessages.ts)\n- [packages/agents-core/src/agent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/agent.ts)\n- [packages/agents-core/src/lifecycle.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts)\n \n\n# 实时语音 Agent\n\n## 概述\n\n实时语音 Agent（RealtimeAgent）是 OpenAI Agents SDK 中专门用于构建语音交互应用的组件。它基于 `Agent` 基类进行扩展，集成了实时语音通信能力，支持通过 WebRTC 或 WebSocket 传输层与 OpenAI Realtime API 进行双向音频交互。\n\nRealtimeAgent 的核心设计理念是简化语音应用的开发流程，使开发者无需关注底层传输细节，只需配置指令和工具即可快速构建语音助手、客服机器人等应用。\n\n资料来源：[packages/agents-realtime/src/realtimeAgent.ts:42-58]()\n\n## 核心架构\n\n### 类继承关系\n\nRealtimeAgent 继承自 Agent 基类，泛型参数分别为上下文数据类型和输出类型：\n\n```typescript\nexport class RealtimeAgent extends Agent<\n RealtimeContextData,\n TextOutput\n>\n```\n\n| 基类属性 | RealtimeAgent 中的值 | 说明 |\n|---------|---------------------|------|\n| TContext | RealtimeContextData | 实时会话上下文 |\n| TOutput | TextOutput | 输出类型为纯文本 |\n\n资料来源：[packages/agents-realtime/src/realtimeAgent.ts:85-89]()\n\n### 组件交互流程\n\n```mermaid\ngraph TD\n A[用户] -->|语音输入| B[RealtimeSession]\n B -->|音频流| C[Transport Layer]\n C -->|WebSocket/WebRTC| D[OpenAI Realtime API]\n D -->|音频响应| C\n C -->|音频流| B\n B -->|语音输出| A\n \n E[RealtimeAgent] -->|指令/工具| B\n F[RealtimeContext] -->|上下文| B\n```\n\n## RealtimeAgent 配置\n\n### RealtimeAgentConfiguration 接口\n\nRealtimeAgent 的配置通过 `RealtimeAgentConfiguration` 接口定义，相比标准 Agent 移除了部分不适用的配置项：\n\n| 配置项 | 类型 | 必需 | 说明 |\n|-------|------|------|------|\n| name | string | 是 | 实时语音 Agent 的名称 |\n| instructions | string | 否 | 系统指令，定义 Agent 行为 |\n| handoffs | RealtimeAgent[] 或 Handoff[] | 否 | 可转交给其他 Agent 的列表 |\n| voice | string | 否 | 使用的语音名称 |\n\n**不支持的配置项**（由 RealtimeSession 统一管理）：\n\n- `model`：所有 RealtimeAgent 共享同一模型\n- `modelSettings`：模型设置由会话级别统一配置\n- `outputType`：不支持结构化输出\n- `toolUseBehavior`：工具使用行为由会话统一管理\n\n资料来源：[packages/agents-realtime/src/realtimeAgent.ts:4-36]()\n\n### 配置示例\n\n```typescript\nconst agent = new RealtimeAgent({\n name: 'voice-assistant',\n instructions: '你是一个乐于助人的语音助手，可以回答问题和协助完成任务。',\n handoffs: [specializedAgent],\n voice: 'alloy',\n});\n```\n\n## RealtimeSession 会话管理\n\n### 会话初始化\n\nRealtimeSession 是实时语音交互的核心管理器，负责：\n\n1. 管理传输层连接（WebRTC/WebSocket）\n2. 维护对话历史和上下文\n3. 处理 Agent 之间的转交（handoff）\n4. 应用输出 Guardrails\n\n```typescript\nexport class RealtimeSession {\n constructor(\n public readonly initialAgent: RealtimeAgent,\n public readonly options: Partial> = {},\n ) {\n // 初始化传输层\n if (options.transport === 'webrtc' || !options.transport) {\n this.#transport = new OpenAIRealtimeWebRTC();\n } else if (options.transport === 'websocket') {\n this.#transport = new OpenAIRealtimeWebSocket();\n } else {\n this.#transport = options.transport;\n }\n }\n}\n```\n\n资料来源：[packages/agents-realtime/src/realtimeSession.ts:1-50]()\n\n### 传输层架构\n\nRealtimeSession 支持多种传输层实现：\n\n| 传输类型 | 类 | 说明 |\n|---------|-----|------|\n| WebRTC | OpenAIRealtimeWebRTC | 适用于浏览器环境，支持媒体流 |\n| WebSocket | OpenAIRealtimeWebSocket | 适用于 Node.js 环境或其他支持 WebSocket 的平台 |\n| 自定义 | 自定义实现 | 实现 RealtimeTransport 接口 |\n\n传输层选择逻辑：\n\n```typescript\nif (\n (typeof options.transport === 'undefined' && hasWebRTCSupport()) ||\n options.transport === 'webrtc'\n) {\n this.#transport = new OpenAIRealtimeWebRTC();\n} else if (\n options.transport === 'websocket' ||\n typeof options.transport === 'undefined'\n) {\n this.#transport = new OpenAIRealtimeWebSocket();\n}\n```\n\n资料来源：[packages/agents-realtime/src/realtimeSession.ts:30-44]()\n\n### 会话上下文\n\nRealtimeSession 创建一个包含历史记录的运行上下文：\n\n```typescript\nthis.#context = new RunContext>({\n ...(options.context ?? {}),\n history: this.#history,\n} as RealtimeContextData);\n```\n\n## 会话配置\n\n### 配置结构\n\n会话配置（RealtimeSessionConfig）定义了与 OpenAI Realtime API 交互的各种参数：\n\n| 配置类别 | 包含项 | 说明 |\n|---------|-------|------|\n| audio.input | format, noiseReduction, transcription, turnDetection | 输入音频配置 |\n| audio.output | format, voice | 输出音频配置 |\n| tools | 工具列表 | Agent 可调用的工具 |\n| tool高层次 | 工具使用策略 | 工具调用行为控制 |\n| turnDetection | 启用的检测类型 | 语音触发检测设置 |\n\n### 废弃配置兼容\n\n系统支持旧的配置格式向新格式的自动转换：\n\n```typescript\nfunction isDeprecatedConfig(\n config: Partial,\n): config is Partial {\n return (\n isDefined('modalities', config) ||\n isDefined('inputAudioFormat', config) ||\n isDefined('outputAudioFormat', config) ||\n isDefined('inputAudioTranscription', config) ||\n isDefined('turnDetection', config) ||\n isDefined('inputAudioNoiseReduction', config) ||\n isDefined('speed', config)\n );\n}\n```\n\n资料来源：[packages/agents-realtime/src/clientMessages.ts:1-30]()\n\n## 语音与转交（HandOff）\n\n### 语音配置\n\nRealtimeAgent 支持为每个 Agent 配置不同的语音：\n\n```typescript\nexport class RealtimeAgent {\n /**\n * The voice intended to be used by the agent.\n * If another agent already spoke during the RealtimeSession,\n * changing the voice during a handoff will fail.\n */\n readonly voice?: string;\n}\n```\n\n**重要约束**：如果在一个 RealtimeSession 中已有其他 Agent 发音，语音转交将失败。\n\n资料来源：[packages/agents-realtime/src/realtimeAgent.ts:90-96]()\n\n### Agent 转交\n\nRealtimeAgent 支持将对话转交给其他专门的 Agent：\n\n```typescript\nexport type RealtimeAgentConfiguration = Partial<\n Omit, ...>\n> & {\n /**\n * Any other `RealtimeAgent` instances the agent is able to hand off to.\n */\n handoffs?: (\n | RealtimeAgent\n | Handoff, TextOutput>\n )[];\n};\n```\n\n转交时，目标 Agent 会被作为工具暴露给模型调用，实现多 Agent 协作。\n\n## 事件与生命周期\n\n### 运行钩子\n\nRealtimeSession 继承自 LifecycleMixin，支持丰富的生命周期事件：\n\n| 事件名 | 触发时机 | 参数 |\n|-------|---------|------|\n| agent_start | Agent 开始执行 | context, agent, turnInput |\n| agent_end | Agent 完成执行 | context, agent, output |\n| agent_handoff | Agent 转交给其他 Agent | context, fromAgent, toAgent |\n| agent_tool_start | 工具开始调用 | context, agent, tool, details |\n\n资料来源：[packages/agents-core/src/lifecycle.ts:20-55]()\n\n## 使用示例\n\n### 基础语音助手\n\n```typescript\nimport { RealtimeAgent, RealtimeSession } from '@openai/agents-realtime';\n\nconst agent = new RealtimeAgent({\n name: 'my-voice-assistant',\n instructions: '你是一个友好的语音助手。',\n voice: 'alloy',\n});\n\nconst session = new RealtimeSession(agent, {\n transport: 'websocket', // 或 'webrtc' 用于浏览器\n});\n\nawait session.connect({ apiKey: process.env.OPENAI_API_KEY });\n```\n\n### 带工具的语音助手\n\n```typescript\nconst agent = new RealtimeAgent({\n name: 'weather-assistant',\n instructions: '你是一个天气助手，可以查询天气预报。',\n handoffs: [],\n});\n\n// 在 RealtimeSession 层面配置工具\nconst session = new RealtimeSession(agent, {\n tools: [weatherTool],\n audio: {\n input: { turnDetection: { type: 'server_vad' } },\n output: { voice: 'nova' },\n },\n});\n```\n\n### WebSocket 手动发送事件\n\n```typescript\n// 手动发送客户端事件\nsession.transport.sendEvent({\n type: 'response.create',\n response: {\n modalities: ['audio', 'text'],\n },\n});\n\n// 取消正在进行的响应\nsession.transport.sendEvent({\n type: 'response.cancel',\n});\n```\n\n资料来源：[packages/agents-realtime/src/openaiRealtimeWebsocket.ts:40-70]()\n\n## 注意事项与限制\n\n### 功能限制\n\n1. **不支持结构化输出**：RealtimeAgent 只能输出纯文本\n2. **统一模型配置**：同一会话中的所有 Agent 共享相同模型\n3. **语音转交限制**：首次发音后无法更改语音\n4. **不支持输入 Guardrails**：仅支持输出 Guardrails\n\n### 传输层选择建议\n\n| 环境 | 推荐传输 | 原因 |\n|-----|---------|------|\n| 浏览器 | WebRTC | 原生支持音视频流 |\n| Node.js | WebSocket | 更稳定，依赖更少 |\n| 移动端 | WebRTC | 低延迟音频传输 |\n\n## 相关文件索引\n\n| 文件路径 | 用途 |\n|---------|------|\n| `packages/agents-realtime/src/realtimeAgent.ts` | RealtimeAgent 类定义 |\n| `packages/agents-realtime/src/realtimeSession.ts` | RealtimeSession 会话管理 |\n| `packages/agents-realtime/src/openaiRealtimeWebsocket.ts` | WebSocket 传输实现 |\n| `packages/agents-realtime/src/clientMessages.ts` | 客户端消息处理与配置转换 |\n| `packages/agents-core/src/agent.ts` | Agent 基类定义 |\n| `packages/agents-core/src/lifecycle.ts` | 生命周期与事件系统 |\n\n---\n\n\n\n## 传输层与集成\n\n### 相关页面\n\n相关主题：[实时语音 Agent](#page-realtime-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/agents-realtime/src/realtimeSession.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-realtime/src/realtimeSession.ts)\n- [packages/agents-realtime/src/openaiRealtimeWebsocket.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-realtime/src/openaiRealtimeWebsocket.ts)\n- [packages/agents-realtime/src/openaiRealtimeBase.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-realtime/src/openaiRealtimeBase.ts)\n- [packages/agents-realtime/src/realtimeAgent.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-realtime/src/realtimeAgent.ts)\n- [packages/agents-realtime/src/clientMessages.ts](https://github.com/openai/openai-agents-js/blob/main/packages/agents-realtime/src/clientMessages.ts)\n \n\n# 传输层与集成\n\n## 概述\n\n传输层（Transport Layer）是 OpenAI Agents SDK 中处理实时会话通信的核心组件。它负责在客户端与 OpenAI Realtime API 之间建立、维护和管理双向通信连接。SDK 支持多种传输协议，包括 WebSocket 和 WebRTC，使得开发者能够灵活选择适合不同应用场景的通信方式。\n\nRealtimeSession 类是传输层的核心入口点，它封装了底层的传输实现，提供了统一的 API 接口。开发者可以根据网络环境、性能需求和功能特性选择合适的传输方式。\n\n## 架构设计\n\n### 传输层层次结构\n\n```\n┌─────────────────────────────────────────────┐\n│ RealtimeSession │\n│ (高级会话管理层，事件处理，用户交互) │\n├─────────────────────────────────────────────┤\n│ RealtimeTransport (接口) │\n│ (统一抽象层，事件分发，消息序列化) │\n├──────────────────┬──────────────────────────┤\n│ OpenAIRealtime │ OpenAIRealtime │\n│ WebSocket │ WebRTC │\n│ │ │\n│ (默认传输方式) │ (浏览器原生支持) │\n├──────────────────┴──────────────────────────┤\n│ OpenAI Realtime API │\n│ (wss://api.openai.com/v1/realtime) │\n└─────────────────────────────────────────────┘\n```\n\n### 传输类型枚举\n\n| 传输类型 | 说明 | 使用场景 |\n|---------|------|---------|\n| `webrtc` | WebRTC 传输协议 | 浏览器环境，NAT穿透需求 |\n| `websocket` | WebSocket 传输协议 | Node.js 环境，默认选项 |\n| `custom` | 自定义传输实现 | 第三方服务集成（Twilio、Cloudflare） |\n\n## 传输选择机制\n\nRealtimeSession 构造函数根据传入的 `options.transport` 参数和运行时环境自动选择合适的传输层实现。\n\n```mermaid\ngraph TD\n A[RealtimeSession 初始化] --> B{options.transport?}\n B -->|undefined| C{hasWebRTCSupport?}\n B -->|webrtc| D[使用 OpenAIRealtimeWebRTC]\n B -->|websocket| E[使用 OpenAIRealtimeWebSocket]\n B -->|自定义对象| F[使用 options.transport]\n C -->|true| D\n C -->|false| E\n D --> G[建立连接]\n E --> G\n F --> G\n```\n\n**传输选择逻辑源码：**\n\n```typescript\nif (\n (typeof options.transport === 'undefined' && hasWebRTCSupport()) ||\n options.transport === 'webrtc'\n) {\n this.#transport = new OpenAIRealtimeWebRTC();\n} else if (\n options.transport === 'websocket' ||\n typeof options.transport === 'undefined'\n) {\n this.#transport = new OpenAIRealtimeWebSocket();\n} else {\n this.#transport = options.transport;\n}\n```\n\n资料来源：[packages/agents-realtime/src/realtimeSession.ts:40-58]()\n\n## WebSocket 传输实现\n\n### 核心功能\n\nOpenAIRealtimeWebSocket 是默认的传输层实现，提供与 OpenAI Realtime API 的稳定连接。它处理消息的发送、接收、序列化和反序列化，并维护会话配置状态。\n\n### 连接初始化流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant WebSocket as OpenAIRealtimeWebSocket\n participant API as OpenAI Realtime API\n \n Client->>WebSocket: connect(options)\n WebSocket->>WebSocket: 构建 URL (model, call_id)\n WebSocket->>API: 建立 WebSocket 连接\n API-->>WebSocket: 连接成功\n WebSocket->>WebSocket: setupWebSocket()\n WebSocket->>API: 发送 session.update 配置\n API-->>WebSocket: session.created 事件\n WebSocket-->>Client: 触发 connected 事件\n```\n\n### 消息发送机制\n\n```typescript\nsendEvent(event: RealtimeClientMessage): void {\n this.#assertConnected();\n \n if (event.type === 'response.create') {\n this.#responseCreateSequencer.requestResponseCreate(event, {\n manual: true,\n });\n return;\n }\n\n if (event.type === 'response.cancel') {\n this.#responseCreateSequencer.beginCancelResponse();\n }\n\n this.#sendEventNow(event);\n}\n```\n\n资料来源：[packages/agents-realtime/src/openaiRealtimeWebsocket.ts:115-135]()\n\n### 事件类型处理\n\n| 事件类型 | 说明 | 处理逻辑 |\n|---------|------|---------|\n| `response.create` | 创建新响应 | 请求响应创建，遵循序列器规则 |\n| `response.cancel` | 取消响应 | 开始取消流程 |\n| 其他事件 | 通用消息 | 直接发送到服务器 |\n\n## 会话配置管理\n\n### 配置合并策略\n\n传输层使用 `_getMergedSessionConfig` 方法合并默认配置与用户自定义配置：\n\n```typescript\n_getMergedSessionConfig(\n config: Partial,\n): RealtimeSessionPayload {\n return this._getMergedSessionConfig(config);\n}\n```\n\n资料来源：[packages/agents-realtime/src/openaiRealtimeBase.ts:1-10]()\n\n### 配置参数表格\n\n| 参数类别 | 子参数 | 说明 | 默认值 |\n|---------|-------|------|-------|\n| `audio.input` | `format` | 输入音频格式 | `pcm16` |\n| `audio.input` | `noiseReduction` | 噪音消除配置 | `null` |\n| `audio.input` | `transcription` | 输入转录设置 | `undefined` |\n| `audio.input` | `turnDetection` | 语音检测配置 | `undefined` |\n| `audio.output` | `voice` | 输出语音名称 | `undefined` |\n| `audio.output` | `format` | 输出音频格式 | `pcm16` |\n| `model` | - | 使用的模型标识 | 必填 |\n\n### 语音配置参数\n\n```typescript\nconst outputConfig =\n audioOutput || typeof requestedOutputVoice !== 'undefined'\n ? {\n format: normalizeAudioFormat(audioOutput?.format),\n voice: requestedOutputVoice ?? undefined,\n }\n : undefined;\n```\n\n资料来源：[packages/agents-realtime/src/clientMessages.ts:80-95]()\n\n## 响应序列器\n\n### 响应创建流程\n\n响应序列器（Response Create Sequencer）管理响应的创建、排队和取消，确保多个响应请求按正确顺序处理。\n\n```mermaid\ngraph LR\n A[response.create 请求] --> B{是否手动触发?}\n B -->|是| C[添加到序列]\n B -->|否| D[自动处理]\n C --> E{有进行中的响应?}\n D --> E\n E -->|是| F[等待当前响应完成]\n E -->|否| G[立即执行]\n F --> G\n```\n\n### 响应取消机制\n\n```typescript\nrequestResponse(response?: Record): void {\n this.#assertConnected();\n this.#responseCreateSequencer.requestResponseCreate(\n {\n type: 'response.create',\n ...(response ? { response } : {}),\n },\n { manual: response !== undefined }\n );\n}\n```\n\n资料来源：[packages/agents-realtime/src/openaiRealtimeWebsocket.ts:137-150]()\n\n## 事件系统\n\n### 会话事件类型\n\n| 事件名称 | 触发时机 | 事件数据 |\n|---------|---------|---------|\n| `guardrail_tripped` | Guardrail 被触发 | `OutputGuardrailTripwireTriggered` |\n| `history_updated` | 历史记录更新 | 完整对话历史 |\n| `history_added` | 新项添加到历史 | 单个历史项 |\n| `error` | 发生错误 | `RealtimeSessionError` |\n| `tool_approval_requested` | 请求工具审批 | `RealtimeToolApprovalRequest` |\n| `mcp_tool_call_completed` | MCP 工具调用完成 | `RealtimeMcpCallItem` |\n| `mcp_tools_changed` | MCP 工具集变更 | 工具列表 |\n\n资料来源：[packages/agents-realtime/src/realtimeSessionEvents.ts:1-50]()\n\n### 错误处理流程\n\n```mermaid\ngraph TD\n A[发生错误] --> B{错误类型}\n B -->|MaxTurnsExceededError| C[调用 maxTurnsExceeded 处理器]\n B -->|ModelRefusalError| D[调用 modelRefusal 处理器]\n B -->|其他错误| E[调用 default 处理器]\n C --> F{处理器返回结果?}\n D --> F\n E --> F\n F -->|有结果| G[返回最终输出]\n F -->|无结果| H[抛出错误]\n```\n\n## 实时代理配置\n\n### RealtimeAgentConfiguration 接口\n\n```typescript\nexport type RealtimeAgentConfiguration = Partial<\n Omit<\n AgentConfiguration, TextOutput>,\n | 'model'\n | 'handoffs'\n | 'modelSettings'\n | 'outputType'\n | 'toolUseBehavior'\n | 'resetToolChoice'\n | 'outputGuardrails'\n | 'inputGuardrails'\n | 'model'\n >\n> & {\n name: string;\n handoffs?: (RealtimeAgent | Handoff<...>)[];\n voice?: string;\n};\n```\n\n资料来源：[packages/agents-realtime/src/realtimeAgent.ts:1-30]()\n\n### 配置限制说明\n\n与标准 Agent 不同，RealtimeAgent 在 RealtimeSession 环境中运行时存在以下限制：\n\n| 配置项 | 不支持原因 |\n|-------|-----------|\n| `model` | 所有 RealtimeAgent 共享同一模型 |\n| `modelSettings` | 模型设置由会话统一管理 |\n| `toolUseBehavior` | 工具行为由传输层控制 |\n\n## 第三方传输集成\n\n### 集成架构\n\n```\n┌──────────────────┐ ┌──────────────────┐\n│ Twilio 集成 │ │ Cloudflare 集成 │\n│ (agents-extensions) │ (agents-extensions) │\n└────────┬─────────┘ └────────┬─────────┘\n │ │\n └───────────┬────────────┘\n ▼\n ┌───────────────────────┐\n │ RealtimeTransport │\n │ (统一接口) │\n └───────────────────────┘\n```\n\n### 自定义传输实现\n\n开发者可以通过实现 `RealtimeTransport` 接口来创建自定义传输层：\n\n1. 实现消息发送方法\n2. 实现连接管理方法\n3. 实现事件订阅机制\n4. 实现配置更新方法\n\n```typescript\n// 自定义传输使用示例\nconst customTransport = new CustomRealtimeTransport();\nconst session = new RealtimeSession(agent, {\n transport: customTransport\n});\n```\n\n## 性能考虑\n\n### 连接生命周期\n\n```mermaid\ngraph LR\n A[初始化] --> B[连接建立]\n B --> C[会话配置]\n C --> D[消息交换]\n D --> E{保持连接?}\n E -->|是| D\n E -->|否| F[断开连接]\n F --> G[清理资源]\n```\n\n### 最佳实践\n\n| 场景 | 推荐传输 | 原因 |\n|-----|---------|------|\n| 浏览器实时对话 | WebRTC | 更低的延迟，更好的 NAT 穿透 |\n| Node.js 服务 | WebSocket | 稳定性更好 |\n| 企业网络 | WebSocket | 防火墙友好 |\n| 移动端应用 | WebRTC | 适应网络变化 |\n\n## 总结\n\n传输层与集成系统为 OpenAI Agents SDK 提供了灵活、高效的实时通信能力。通过抽象化的接口设计，开发者可以无缝切换不同的传输协议，同时支持 Twilio、Cloudflare 等第三方服务的深度集成。这种架构确保了 SDK 在各种运行环境下的适用性，同时保持了代码的简洁性和可维护性。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：openai/openai-agents-js\n\n摘要：发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `openai-agents-js` 与安装入口 `@openai/agents` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @openai/agents`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:993521808 | https://github.com/openai/openai-agents-js | repo=openai-agents-js; install=@openai/agents\n\n## 2. 安装坑 · 失败模式：installation: v0.10.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v0.10.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.10.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.10.0. Context: Observed when using node, python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_0017083f7c144b8b8068b1aa812f1798 | https://github.com/openai/openai-agents-js/releases/tag/v0.10.0 | v0.10.0\n\n## 3. 安装坑 · 失败模式：installation: v0.11.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v0.11.2\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.11.2\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.11.2. Context: Observed when using node, python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_cbb13be7191292a101a93f89e2c40ad3 | https://github.com/openai/openai-agents-js/releases/tag/v0.11.2 | v0.11.2\n\n## 4. 配置坑 · 失败模式：configuration: v0.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v0.9.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.9.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.9.0. Context: Observed when using docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_742498adc1555b1770e9377463c11ff4 | https://github.com/openai/openai-agents-js/releases/tag/v0.9.0 | v0.9.0\n\n## 5. 能力坑 · 能力判断依赖假设\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:993521808 | https://github.com/openai/openai-agents-js | README/documentation is current enough for a first validation pass.\n\n## 6. 运行坑 · 失败模式：runtime: Large realtime audio buffers can crash during base64 encoding\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: Large realtime audio buffers can crash during base64 encoding\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Large realtime audio buffers can crash during base64 encoding\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Large realtime audio buffers can crash during base64 encoding. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_aaf4394591e72954462f8a949be29aee | https://github.com/openai/openai-agents-js/issues/1333 | Large realtime audio buffers can crash during base64 encoding, failure_mode_cluster:github_issue | fmev_dfcff51166e62ba4cc81679f3c9c2f18 | https://github.com/openai/openai-agents-js/issues/1333 | Large realtime audio buffers can crash during base64 encoding\n\n## 7. 运行坑 · 失败模式：runtime: v0.11.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: v0.11.4\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.11.4\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.11.4. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_73a57d6e6bb4c1e93cea0e78313774b1 | https://github.com/openai/openai-agents-js/releases/tag/v0.11.4 | v0.11.4\n\n## 8. 运行坑 · 来源证据：Large realtime audio buffers can crash during base64 encoding\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Large realtime audio buffers can crash during base64 encoding\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1f01240eec894a519476aebd4a7590db | https://github.com/openai/openai-agents-js/issues/1333 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 维护坑 · 失败模式：migration: v0.9.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: v0.9.1\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.9.1\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.9.1. Context: Observed during version upgrade or migration.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_e351743729d2a86ad6987f1baefae665 | https://github.com/openai/openai-agents-js/releases/tag/v0.9.1 | v0.9.1\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:993521808 | https://github.com/openai/openai-agents-js | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:993521808 | https://github.com/openai/openai-agents-js | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:993521808 | https://github.com/openai/openai-agents-js | no_demo; severity=medium\n\n## 13. 维护坑 · 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:993521808 | https://github.com/openai/openai-agents-js | issue_or_pr_quality=unknown\n\n## 14. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:993521808 | https://github.com/openai/openai-agents-js | release_recency=unknown\n\n## 15. 维护坑 · 失败模式：maintenance: v0.10.1\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.10.1\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.10.1\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.10.1. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_21fc49454e8260a68f620eef5031497f | https://github.com/openai/openai-agents-js/releases/tag/v0.10.1 | v0.10.1\n\n## 16. 维护坑 · 失败模式：maintenance: v0.11.0\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.11.0\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.11.0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.11.0. Context: Observed when using node\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_46b242251b25a22b32eeb2d3e132ab09 | https://github.com/openai/openai-agents-js/releases/tag/v0.11.0 | v0.11.0\n\n## 17. 维护坑 · 失败模式：maintenance: v0.11.1\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.11.1\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.11.1\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.11.1. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_4770e6d325b06442bfbac2c7a9228b8b | https://github.com/openai/openai-agents-js/releases/tag/v0.11.1 | v0.11.1\n\n## 18. 维护坑 · 失败模式：maintenance: v0.11.3\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.11.3\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.11.3\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.11.3. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_0b2d37ec4d2e0354b33ecb8cc520f142 | https://github.com/openai/openai-agents-js/releases/tag/v0.11.3 | v0.11.3\n\n\n",
"markdown_key": "openai-agents-js",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:993521808",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/openai/openai-agents-js"
},
{
"evidence_id": "art_0e97ee656a1347e792406bb5b516f59f",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/openai/openai-agents-js#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "openai-agents-js 说明书",
"toc": [
"https://github.com/openai/openai-agents-js 项目说明书",
"目录",
"项目介绍",
"概述",
"核心架构",
"核心概念",
"主要功能特性",
"Agent 模式示例",
"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": "629d35af99e1ba80fc968b0d062c070caed0683d",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"package.json",
"README.md",
"docs/tsconfig.scripts.json",
"docs/package.json",
"docs/README.md",
"docs/tsconfig.json",
"docs/src/content.config.ts",
"docs/src/plugins/typedoc-frontmatter.js",
"docs/src/scripts/translate.ts",
"docs/src/content/docs/index.mdx",
"docs/src/content/docs/ja/index.mdx",
"docs/src/content/docs/guides/multi-agent.md",
"docs/src/content/docs/guides/config.mdx",
"docs/src/content/docs/guides/troubleshooting.mdx",
"docs/src/content/docs/guides/context.mdx",
"docs/src/content/docs/guides/models.mdx",
"docs/src/content/docs/guides/handoffs.mdx",
"docs/src/content/docs/guides/sandbox-agents.mdx",
"docs/src/content/docs/guides/human-in-the-loop.mdx",
"docs/src/content/docs/guides/mcp.mdx",
"docs/src/content/docs/guides/results.mdx",
"docs/src/content/docs/guides/tracing.mdx",
"docs/src/content/docs/guides/running-agents.mdx",
"docs/src/content/docs/guides/quickstart.mdx",
"docs/src/content/docs/guides/release.mdx",
"docs/src/content/docs/guides/tools.mdx",
"docs/src/content/docs/guides/agents.mdx",
"docs/src/content/docs/guides/sessions.mdx",
"docs/src/content/docs/guides/guardrails.mdx",
"docs/src/content/docs/guides/streaming.mdx",
"docs/src/content/docs/guides/voice-agents.mdx",
"docs/src/content/docs/extensions/cloudflare.mdx",
"docs/src/content/docs/extensions/ai-sdk.mdx",
"docs/src/content/docs/extensions/twilio.mdx",
"docs/src/content/docs/zh/index.mdx",
"docs/src/content/docs/ko/index.mdx",
"docs/src/content/docs/ja/guides/multi-agent.md",
"docs/src/content/docs/ja/guides/config.mdx",
"docs/src/content/docs/ja/guides/troubleshooting.mdx"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# openai-agents-js - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 openai-agents-js 编译的 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/changeset-validation/SKILL.md`, `.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.agents/skills/changeset-validation/SKILL.md`, `.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `packages/agents-core/README.md`, `packages/agents-extensions/README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npm install @openai/agents zod` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npm install @openai/agents` 证据：`packages/agents-core/README.md` Claim：`clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86\n- `npm install @openai/agents @openai/agents-extensions` 证据：`packages/agents-extensions/README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.agents/skills/changeset-validation/SKILL.md`, `.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.agents/skills/changeset-validation/SKILL.md`, `.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `packages/agents-core/README.md`, `packages/agents-extensions/README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：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/changeset-validation/SKILL.md`, `.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `packages/agents-core/README.md`, `packages/agents-extensions/README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.agents/skills/changeset-validation/SKILL.md`, `.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `packages/agents-core/README.md`, `packages/agents-extensions/README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `packages/agents-core/README.md`, `packages/agents-extensions/README.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/changeset-validation/SKILL.md`, `.agents/skills/code-change-verification/SKILL.md`, `.agents/skills/docs-sync/SKILL.md`, `.agents/skills/examples-auto-run/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `packages/agents-core/README.md`, `packages/agents-extensions/README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：1210\n- 重要文件覆盖：40/1210\n- 证据索引条目：86\n- 角色 / Skill 条目：15\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-js 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 openai-agents-js 当作安装前体验资产，而不是已安装工具或真实运行环境。\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-js 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 15 个角色 / Skill / 项目文档条目。\n\n- **changeset-validation**（skill）：Validate changesets in openai-agents-js using LLM judgment against git diffs including uncommitted local changes . Use when packages/ or .changeset/ are modified, or when verifying PR changeset compliance and bump level. 激活提示：当用户任务与“changeset-validation”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/changeset-validation/SKILL.md`\n- **code-change-verification**（skill）：Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo. 激活提示：当用户任务与“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 docs/src/content/docs/ and never touch translated docs under docs/src/content/docs/ja, ko, or 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 examples:start-all in auto mode with parallel execution, per-script logs, and start/stop helpers. 激活提示：当用户任务与“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-js. 激活提示：当用户任务与“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-js before editing code. Use when a task changes exported APIs, runtime behavior, schemas, 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- **integration-tests**（skill）：Run the integration-tests pipeline that depends on a local npm registry Verdaccio . Use when asked to execute integration tests or local publish workflows in this repo. 激活提示：当用户任务与“integration-tests”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/integration-tests/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- **pnpm-upgrade**（skill）：Keep pnpm current: run pnpm self-update/corepack prepare, align packageManager in package.json, and bump pnpm/action-setup + pinned pnpm versions in .github/workflows to the latest release. Use this when refreshing the pnpm toolchain manually or in automation. 激活提示：当用户任务与“pnpm-upgrade”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/pnpm-upgrade/SKILL.md`\n- **pr-draft-summary**（skill）：Create the required PR-ready summary block, branch suggestion, title, and draft description for openai-agents-js. 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 PR dr… 激活提示：当用户任务与“pr-draft-summary”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/pr-draft-summary/SKILL.md`\n- **runtime-behavior-probe**（skill）：Plan and execute runtime-behavior investigations with temporary TypeScript 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 a… 激活提示：当用户任务与“runtime-behavior-probe”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/runtime-behavior-probe/SKILL.md`\n- **test-coverage-improver**（skill）：Improve test coverage in the OpenAI Agents JS monorepo: run pnpm test:coverage , inspect coverage artifacts, identify low-coverage files and branches, propose high-impact tests, and confirm with the user before writing tests. 激活提示：当用户任务与“test-coverage-improver”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/test-coverage-improver/SKILL.md`\n- **invoice-total-fixer**（skill）：Use when fixing invoice total calculations in the sandbox quickstart repository. 激活提示：当用户任务与“invoice-total-fixer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`examples/docs/sandbox-agents/skills/invoice-total-fixer/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/data/coding-task/skills/credit-note-fixer/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- 共索引 86 条证据。\n\n- **Docs**（documentation）：The documentation is generated using Astro Starlight. 证据：`docs/README.md`\n- **Documentation Snippets**（documentation）：This directory contains small scripts used throughout the documentation. Run them with pnpm using the commands shown below. 证据：`examples/docs/README.md`\n- **Invoice Total Fixer**（skill_instruction）：Inspect the implementation and test before editing. The total should apply tax as a percentage of the subtotal, so the expected formula is subtotal + subtotal taxRate . 证据：`examples/docs/sandbox-agents/skills/invoice-total-fixer/SKILL.md`\n- **Changesets**（documentation）：Hello and welcome! This folder has been automatically generated by @changesets/cli , a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it in our repository https://github.com/changesets/changesets 证据：`.changeset/README.md`\n- **Contributor Guide**（documentation）：This guide helps new contributors get started with the OpenAI Agents JS monorepo. It covers repo structure, how to test your work, available utilities, file locations, and guidelines for commits and PRs. 证据：`AGENTS.md`\n- **OpenAI Agents SDK JavaScript/TypeScript**（documentation）：OpenAI Agents SDK JavaScript/TypeScript 证据：`README.md`\n- **Integration tests**（documentation）：This project hosts packages to test the different environments that the Agents SDK works in. 证据：`integration-tests/README.md`\n- **Agent Pattern Examples**（documentation）：This directory contains small scripts that demonstrate different agent patterns. Run them with pnpm using the commands shown below. 证据：`examples/agent-patterns/README.md`\n- **AI SDK UI Stream Example**（documentation）：This example shows how to convert an Agents SDK streaming run into responses that are compatible with the AI SDK UI data stream and text stream protocols. 证据：`examples/ai-sdk-ui/README.md`\n- **AI SDK Example**（documentation）：This example shows how to run the Agents SDK with a model provided by the AI SDK https://www.npmjs.com/package/@ai-sdk/openai . 证据：`examples/ai-sdk-v1/README.md`\n- **AI SDK Examples**（documentation）：These examples show how to wrap models from the AI SDK https://www.npmjs.com/package/@ai-sdk/openai and compatible providers with the aisdk helper from @openai/agents-extensions/ai-sdk , then run them inside the Agents runtime. 证据：`examples/ai-sdk/README.md`\n- **Basic Examples**（documentation）：This directory contains small scripts that demonstrate features of the Agents SDK. Run them with pnpm using the commands shown below. 证据：`examples/basic/README.md`\n- **Customer Service Agent**（documentation）：This example demonstrates a multi-agent customer service workflow for an airline. The index.ts script sets up a triage agent that can delegate to specialized FAQ and seat booking agents. Tools are used to look up common questions and to update a passenger's seat. Interaction occurs through a simple CLI loop, showing how agents can hand off between each other and call tools. 证据：`examples/customer-service/README.md`\n- **Financial Research Agent**（documentation）：This example demonstrates a multi-agent workflow that produces a short financial analysis report. 证据：`examples/financial-research-agent/README.md`\n- **Agent Handoffs**（documentation）：This example shows how one agent can transfer control to another. The index.ts script sets up two English speaking assistants and a Spanish assistant. The second agent is configured with a handoff so that if the user requests Spanish replies it hands off to the Spanish agent. A message filter strips out tool messages and the first two history items before the handoff occurs. Run it with: 证据：`examples/handoffs/README.md`\n- **Model Context Protocol Example**（documentation）：This example demonstrates how to use the Model Context Protocol https://modelcontextprotocol.io/ with the OpenAI Agents SDK. 证据：`examples/mcp/README.md`\n- **Model Providers Examples**（documentation）：This directory contains small scripts showing how to integrate custom model providers. Run them with pnpm using the commands shown below. 证据：`examples/model-providers/README.md`\n- **Next.js Demo**（documentation）：This example shows a basic example of how to use human-in-the-loop in a Next.js application. 证据：`examples/nextjs/README.md`\n- **Realtime Demo**（documentation）：This example is a small Vite https://vitejs.dev/ application showcasing the realtime agent API. 证据：`examples/realtime-demo/README.md`\n- **Realtime Next.js Demo**（documentation）：This example shows how to combine Next.js with the OpenAI Agents SDK to create a realtime voice agent. 证据：`examples/realtime-next/README.md`\n- **Twilio SIP Realtime Example**（documentation）：This example shows how to handle OpenAI Realtime SIP calls with the Agents JS 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- **Realtime Twilio Integration**（documentation）：This example demonstrates how to connect the OpenAI Realtime API to a phone call using Twilio's Media Streams. The script in index.ts starts a Fastify server that serves TwiML for incoming calls and creates a WebSocket endpoint for streaming audio. When a call connects, the audio stream is forwarded through a TwilioRealtimeTransportLayer to a RealtimeSession so the RealtimeAgent can respond in real time. 证据：`examples/realtime-twilio/README.md`\n- **Research Bot**（documentation）：This example shows how to orchestrate several agents to produce a detailed research report. 证据：`examples/research-bot/README.md`\n- **Sandbox Examples**（documentation）：These examples show the JavaScript sandbox APIs that are implemented in this branch: Manifest , SandboxAgent , local and Docker sandbox clients, filesystem and shell capabilities, lazy skills, host tools, handoffs, local and remote snapshots, external memory stores, and SDK conversation sessions. 证据：`examples/sandbox/README.md`\n- **Credit Note Example Repo**（documentation）：This tiny repo exists to support examples/sandbox/coding-task.ts . 证据：`examples/sandbox/data/coding-task/repo/README.md`\n- **Cloud Sandbox Extension Examples**（documentation）：These examples mirror the Python sandbox extension runners and keep the same environment-variable names and flag shapes where that makes sense. 证据：`examples/sandbox/extensions/README.md`\n- **Tool Integrations**（documentation）：These examples demonstrate the hosted tools provided by the Agents SDK. 证据：`examples/tools/README.md`\n- **OpenAI Agents SDK**（documentation）：The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. 证据：`packages/agents-core/README.md`\n- **OpenAI Agents SDK Extensions**（documentation）：This package contains a collection of extension features for the OpenAI Agents SDK and is intended to be used alongside it. 证据：`packages/agents-extensions/README.md`\n- **OpenAI Agents SDK**（documentation）：The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. 证据：`packages/agents-openai/README.md`\n- **OpenAI Agents SDK**（documentation）：The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. 证据：`packages/agents-realtime/README.md`\n- **OpenAI Agents SDK JavaScript/TypeScript**（documentation）：OpenAI Agents SDK JavaScript/TypeScript 证据：`packages/agents/README.md`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"docs\", \"type\": \"module\", \"scripts\": { \"dev\": \"astro dev\", \"start\": \"astro dev\", \"build\": \"astro build\", \"preview\": \"astro preview\", \"astro\": \"astro\", \"translate\": \"tsx src/scripts/translate.ts\" }, \"dependencies\": { \"@astrojs/starlight\": \"^0.38.4\", \"@astrojs/starlight-tailwind\": \"^5.0.0\", \"@openai/agents\": \"workspace: \", \"@tailwindcss/vite\": \"^4.2.4\", \"astro\": \"^6.1.10\", \"sharp\": \"^0.34.5\", \"starlight-llms-txt\": \"^0.8.1\", \"starlight-typedoc\": \"^0.21.5\", \"typedoc\": \"^0.28.19\", \"typedoc-plugin-markdown\": \"^4.11.0\" }, \"devDependencies\": { \"tailwindcss\": \"^4.2.4\", \"tsx\": \"^4.21.0\", \"typedoc-plugin-frontmatter\": \"^1.3.1\", \"typedoc-plugin-zod\": \"^1.4.3\" } } 证据：`docs/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"openai-agents-js\", \"version\": \"0.0.1\", \"scripts\": { \"clean\": \"node scripts/clean-package-dists.mjs && tsc-multi --clean\", \"prebuild\": \"pnpm -F @openai/ -r prebuild\", \"build\": \"pnpm clean && tsc-multi\", \"build:ci\": \"pnpm run prebuild && pnpm clean && tsc-multi --maxWorkers 1 && pnpm run postbuild\", \"postbuild\": \"pnpm -r -F @openai/ bundle\", \"packages:dev\": \"tsc-multi --watch\", \"docs:dev\": \"pnpm -F docs dev\", \"docs:translate\": \"pnpm -F docs translate\", \"docs:build\": \"pnpm -F docs build\", \"docs:scripts:check\": \"pnpm exec tsc --pretty false --project docs/tsconfig.scripts.json\", \"test\": \"CI=1 NODE ENV=test vitest\", \"test:coverage\": \"NODE ENV=test vitest run --coverag… 证据：`package.json`\n- **Contributing to OpenAI Agents SDK**（documentation）：Thank you for your interest in contributing to the OpenAI Agents SDK. This document outlines the process for reporting issues, proposing changes, and submitting pull requests. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"agent-patterns\", \"dependencies\": { \"@openai/agents\": \"workspace: \", \"chalk\": \"^5.4.1\", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start:agents-as-tools\": \"tsx agents-as-tools.ts\", \"start:agents-as-tools-conditional\": \"tsx agents-as-tools-conditional.ts\", \"start:agents-as-tools-structured\": \"tsx agents-as-tools-structured.ts\", \"start:agents-as-tools-streaming\": \"tsx agents-as-tools-streaming.ts\", \"start:deterministic\": \"tsx deterministic.ts\", \"start:forcing-tool-use\": \"tsx forcing-tool-use.ts -t default\", \"start:human-in-the-loop-stream\": \"tsx human-in-the-loop-stream.ts\", \"start:human-in-the-loop\": \"tsx human-in-the-loop.ts\", \"start:input-gua… 证据：`examples/agent-patterns/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"ai-sdk-ui\", \"dependencies\": { \"@ai-sdk/react\": \"^3.0.44\", \"@openai/agents\": \"workspace: \", \"@openai/agents-extensions\": \"workspace: \", \"@openai/agents-openai\": \"workspace: \", \"ai\": \"^6.0.42\", \"next\": \"16.2.3\", \"react\": \"^19.2.3\", \"react-dom\": \"^19.2.3\", \"react-markdown\": \"^9.0.3\", \"rehype-sanitize\": \"^6.0.0\", \"remark-gfm\": \"^4.0.0\", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"dev\": \"next dev --turbopack\", \"build\": \"next build\", \"start\": \"next start\", \"lint\": \"next lint\", \"start:script-simple\": \"tsx scripts/simple.ts\", \"start:script-ai-sdk\": \"tsx scripts/ai-sdk.ts\" }, \"devDependencies\": { \"@ai-sdk/openai\": \"^3.0.14\", \"@types/node\": \"^20\", \"@typ… 证据：`examples/ai-sdk-ui/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"ai-sdk-v1\", \"dependencies\": { \"@ai-sdk/openai\": \"1\", \"@ai-sdk/provider\": \"1.1.3\", \"@openai/agents\": \"0.3.9\", \"@openai/agents-extensions\": \"0.3.9\", \"hono\": \"^4.12.16\", \"zod\": \"^3.23.8\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start\": \"tsx index.ts\", \"start:stream\": \"tsx stream.ts\" } } 证据：`examples/ai-sdk-v1/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"ai-sdk\", \"dependencies\": { \"@ai-sdk/anthropic\": \"^3.0.9\", \"@ai-sdk/google\": \"^3.0.6\", \"@ai-sdk/openai\": \"^3.0.7\", \"@openai/agents\": \"workspace: \", \"@openai/agents-extensions\": \"workspace: \", \"@openrouter/ai-sdk-provider\": \"^2.9.0\", \"zod\": \"4.3.5\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start\": \"tsx index.ts\", \"start:gpt-5\": \"tsx gpt-5.ts\", \"start:retry\": \"tsx retry.ts\", \"start:stream\": \"tsx stream.ts\", \"start:image-tool-output\": \"tsx image-tool-output.ts\" }, \"devDependencies\": { \"ai\": \"^6.0.3\" } } 证据：`examples/ai-sdk/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"basic\", \"dependencies\": { \"@openai/agents\": \"workspace: \", \"openai\": \"^6.35.0\", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start\": \"tsx index.ts\", \"start:agent-lifecycle-example\": \"tsx agent-lifecycle-example.ts\", \"start:chat\": \"tsx chat.ts\", \"start:dynamic-system-prompt\": \"tsx dynamic-system-prompt.ts\", \"start:hello-world\": \"tsx hello-world.ts\", \"start:hello-world-gpt-5\": \"tsx hello-world-gpt-5.ts\", \"start:hello-world-gpt-oss\": \"tsx hello-world-gpt-oss.ts\", \"start:lifecycle-example\": \"tsx lifecycle-example.ts\", \"start:local-image\": \"tsx local-image.ts\", \"start:image-tool-output\": \"tsx image-tool-output.ts\", \"start:file-tool-output\": \"tsx fil… 证据：`examples/basic/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"connectors\", \"dependencies\": { \"@openai/agents\": \"workspace: \" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start\": \"tsx index.ts\" } } 证据：`examples/connectors/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"customer-service\", \"dependencies\": { \"@openai/agents\": \"workspace: \", \"@openai/agents-core\": \"workspace: \", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start\": \"tsx index.ts\" } } 证据：`examples/customer-service/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"docs-code\", \"dependencies\": { \"@ai-sdk/openai\": \"^2.0.15\", \"@modelcontextprotocol/server-filesystem\": \"^2026.1.14\", \"@openai/agents\": \"workspace: \", \"@openai/agents-core\": \"workspace: \", \"@openai/agents-extensions\": \"workspace: \", \"@openai/agents-realtime\": \"workspace: \", \"openai\": \"^6.35.0\", \"server-only\": \"^0.0.1\", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\" }, \"devDependencies\": { \"typedoc-plugin-zod\": \"^1.4.1\" } } 证据：`examples/docs/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"type\": \"module\", \"scripts\": { \"test\": \"node --test\" } } 证据：`examples/docs/sandbox-agents/repo/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"financial-research-agent\", \"dependencies\": { \"@openai/agents\": \"workspace: \", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start\": \"tsx main.ts\" } } 证据：`examples/financial-research-agent/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"handoffs\", \"dependencies\": { \"@openai/agents\": \"workspace: \", \"@openai/agents-core\": \"workspace: \", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start\": \"tsx index.ts\", \"start:types\": \"tsx types.ts\", \"start:is-enabled\": \"tsx is-enabled.ts\" } } 证据：`examples/handoffs/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"mcp\", \"dependencies\": { \"@modelcontextprotocol/sdk\": \"^1.26.0\", \"@modelcontextprotocol/server-filesystem\": \"^2026.1.14\", \"@openai/agents\": \"workspace: \" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start:stdio\": \"tsx filesystem-example.ts\", \"start:streamable-http\": \"tsx streamable-http-example.ts\", \"start:hosted-mcp-on-approval\": \"tsx hosted-mcp-on-approval.ts\", \"start:hosted-mcp-human-in-the-loop\": \"tsx hosted-mcp-human-in-the-loop.ts\", \"start:hosted-mcp-simple\": \"tsx hosted-mcp-simple.ts\", \"start:tool-filter\": \"tsx tool-filter-example.ts\", \"start:sse\": \"tsx sse-example.ts\", \"start:get-all-tools\": \"tsx get-all-mcp-tools-example.ts\", \"start:mcp-servers\": \"tsx… 证据：`examples/mcp/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"memory\", \"dependencies\": { \"@openai/agents\": \"workspace: \", \"@prisma/client\": \"^6.18.0\", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start:memory\": \"tsx memory.ts\", \"start:memory-hitl\": \"tsx memory-hitl.ts\", \"start:hitl-session-scenario\": \"tsx hitl-session-scenario.ts\", \"start:oai\": \"tsx oai.ts\", \"start:oai-hitl\": \"tsx oai-hitl.ts\", \"start:oai-compact\": \"tsx oai-compact.ts\", \"start:oai-compact-stateless\": \"tsx oai-compact-stateless.ts\", \"start:file\": \"tsx file.ts\", \"start:file-hitl\": \"tsx file-hitl.ts\", \"start:prisma\": \"tsx start-prisma.ts\" }, \"devDependencies\": { \"prisma\": \"^6.18.0\" } } 证据：`examples/memory/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"model-providers\", \"dependencies\": { \"@openai/agents\": \"workspace: \", \"openai\": \"^6.35.0\", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start:custom-example-agent\": \"tsx custom-example-agent.ts\", \"start:custom-example-global\": \"tsx custom-example-global.ts\", \"start:custom-example-provider\": \"tsx custom-example-provider.ts\" } } 证据：`examples/model-providers/package.json`\n- **Package**（package_manifest）：{ \"name\": \"nextjs\", \"private\": true, \"scripts\": { \"dev\": \"next dev --turbopack\", \"build\": \"next build\", \"start\": \"next start\", \"lint\": \"next lint\", \"build-check\": \"tsc --noEmit\" }, \"dependencies\": { \"@openai/agents\": \"workspace: \", \"@radix-ui/react-dialog\": \"^1.1.14\", \"@radix-ui/react-slot\": \"^1.2.3\", \"@tanstack/react-query\": \"^5.80.7\", \"class-variance-authority\": \"^0.7.1\", \"clsx\": \"^2.1.1\", \"lucide-react\": \"^0.515.0\", \"next\": \"16.2.3\", \"react\": \"^19.0.0\", \"react-dom\": \"^19.0.0\", \"tailwind-merge\": \"^3.3.1\", \"wavtools\": \"^0.1.5\", \"zod\": \"^4.0.0\" }, \"devDependencies\": { \"@tailwindcss/postcss\": \"^4\", \"@types/node\": \"^20\", \"@types/react\": \"^19\", \"@types/react-dom\": \"^19\", \"tailwindcss\": \"^4\", \"… 证据：`examples/nextjs/package.json`\n- **Package**（package_manifest）：{ \"name\": \"realtime-demo\", \"private\": true, \"type\": \"module\", \"scripts\": { \"dev\": \"vite\", \"build-check\": \"tsc --noEmit\", \"build\": \"tsc && vite build\", \"preview\": \"vite preview\", \"generate-token\": \"tsx token.ts\" }, \"devDependencies\": { \"typescript\": \"~5.8.3\", \"vite\": \"^6.4.2\" }, \"dependencies\": { \"@openai/agents-realtime\": \"workspace: \", \"@tailwindcss/vite\": \"^4.1.7\", \"openai\": \"^6.35.0\", \"tailwindcss\": \"^4.1.7\", \"zod\": \"^4.0.0\" } } 证据：`examples/realtime-demo/package.json`\n- **Package**（package_manifest）：{ \"name\": \"realtime-next\", \"private\": true, \"scripts\": { \"dev\": \"next dev --turbopack\", \"build\": \"next build\", \"start\": \"next start\", \"lint\": \"next lint\", \"build-check\": \"tsc --noEmit\" }, \"dependencies\": { \"@openai/agents\": \"workspace: \", \"@radix-ui/react-slot\": \"^1.2.3\", \"class-variance-authority\": \"^0.7.1\", \"clsx\": \"^2.1.1\", \"next\": \"16.2.3\", \"react\": \"^19.0.0\", \"react-dom\": \"^19.0.0\", \"tailwind-merge\": \"^3.3.0\", \"wavtools\": \"^0.1.5\", \"zod\": \"^4.0.0\" }, \"devDependencies\": { \"@tailwindcss/postcss\": \"^4\", \"@types/node\": \"^20\", \"@types/react\": \"^19\", \"@types/react-dom\": \"^19\", \"tailwindcss\": \"^4\", \"typescript\": \"^5\" } } 证据：`examples/realtime-next/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"realtime-twilio-sip\", \"dependencies\": { \"@openai/agents\": \"workspace: \", \"@openai/agents-core\": \"workspace: \", \"@openai/agents-realtime\": \"workspace: \", \"dotenv\": \"^16.5.0\", \"fastify\": \"^5.8.5\", \"fastify-raw-body\": \"^5.0.0\", \"openai\": \"^6.35.0\", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start\": \"tsx server.ts\" } } 证据：`examples/realtime-twilio-sip/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"realtime-twilio\", \"dependencies\": { \"@fastify/formbody\": \"^8.0.2\", \"@fastify/websocket\": \"^11.1.0\", \"@openai/agents\": \"workspace: \", \"@openai/agents-extensions\": \"workspace: \", \"dotenv\": \"^16.5.0\", \"fastify\": \"^5.8.5\", \"ws\": \"^8.18.1\", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start\": \"tsx index.ts\" } } 证据：`examples/realtime-twilio/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"research-bot\", \"dependencies\": { \"@openai/agents\": \"workspace: \", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start\": \"tsx main.ts\" } } 证据：`examples/research-bot/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"sandbox\", \"type\": \"module\", \"dependencies\": { \"@openai/agents\": \"workspace: \", \"@openai/agents-extensions\": \"workspace: \", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start:basic\": \"tsx basic.ts\", \"start:handoffs\": \"tsx handoffs.ts\", \"start:coding-task\": \"tsx coding-task.ts\", \"start:resume\": \"tsx resume.ts\", \"start:memory\": \"tsx memory.ts\", \"start:unix-local-pty\": \"tsx unix-local-pty.ts\", \"start:unix-local-runner\": \"tsx unix-local-runner.ts\", \"start:docker-runner\": \"tsx docker-runner.ts\", \"start:memory-generation\": \"tsx memory-generation.ts\", \"start:memory-multi-agent-multiturn\": \"tsx memory-multi-agent-multiturn.ts\", \"start:sandbox-agent-capa… 证据：`examples/sandbox/package.json`\n- **Package**（package_manifest）：{ \"private\": true, \"name\": \"tools\", \"type\": \"module\", \"dependencies\": { \"@openai/agents\": \"workspace: \", \"@openai/agents-core\": \"workspace: \", \"@openai/agents-extensions\": \"workspace: \", \"@openai/codex-sdk\": \"^0.86.0\", \"chalk\": \"^5.6.2\", \"openai\": \"^6.35.0\", \"playwright\": \"^1.55.1\", \"zod\": \"^4.0.0\" }, \"scripts\": { \"build-check\": \"tsc --noEmit\", \"start:codex\": \"tsx codex.ts\", \"start:codex-same-thread\": \"tsx codex-same-thread.ts\", \"start:computer-use\": \"tsx computer-use.ts\", \"start:computer-use-hitl\": \"tsx computer-use-hitl.ts\", \"start:file-search\": \"tsx file-search.ts\", \"start:tool-search\": \"tsx tool-search.ts\", \"start:web-search\": \"tsx web-search.ts\", \"start:web-search-filters\": \"tsx web-se… 证据：`examples/tools/package.json`\n- **Package**（package_manifest）：{ \"name\": \"bun\", \"module\": \"index.ts\", \"type\": \"module\", \"private\": true, \"scripts\": { \"start\": \"bun run index.ts\", \"start:aisdk\": \"bun run aisdk.ts\", \"start:zod\": \"bun run zod.ts\", \"start:sandbox:unix-local\": \"bun run sandbox-unix-local.ts\" }, \"devDependencies\": { \"@types/bun\": \"latest\" }, \"peerDependencies\": { \"typescript\": \"^5\" }, \"dependencies\": { \"@openai/agents\": \"latest\", \"@openai/agents-extensions\": \"latest\", \"zod\": \"^4\" } } 证据：`integration-tests/bun/package.json`\n- **Package**（package_manifest）：{ \"name\": \"worker\", \"version\": \"0.0.0\", \"private\": true, \"scripts\": { \"deploy\": \"wrangler deploy\", \"dev\": \"wrangler dev\", \"start\": \"wrangler dev\", \"test\": \"vitest\", \"cf-typegen\": \"wrangler types\", \"build\": \"wrangler deploy --dry-run --outdir dist\" }, \"dependencies\": { \"@openai/agents\": \"latest\", \"@openai/agents-extensions\": \"latest\" }, \"devDependencies\": { \"typescript\": \"^5.5.2\", \"wrangler\": \"^4.18.0\" } } 证据：`integration-tests/cloudflare-workers/worker/package.json`\n- **Package**（package_manifest）：{ \"name\": \"deno\", \"private\": true, \"scripts\": { \"start\": \"deno --allow-net --allow-env main.ts\" }, \"dependencies\": { \"@openai/agents\": \"latest\", \"@openai/agents-extensions\": \"latest\", \"zod\": \"^4\" } } 证据：`integration-tests/deno/package.json`\n- 其余 26 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `examples/docs/README.md`, `examples/docs/sandbox-agents/skills/invoice-total-fixer/SKILL.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `examples/docs/README.md`, `examples/docs/sandbox-agents/skills/invoice-total-fixer/SKILL.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, package.json, packages/agents/package.json\n- **系统架构**：importance `high`\n - source_paths: packages/agents-core/src/index.ts, packages/agents/src/index.ts, pnpm-workspace.yaml\n- **Agent 核心机制**：importance `high`\n - source_paths: packages/agents-core/src/agent.ts, packages/agents-core/src/lifecycle.ts, packages/agents-core/src/model.ts, packages/agents-core/src/runner/runLoop.ts\n- **工具系统**：importance `high`\n - source_paths: packages/agents-core/src/tool.ts, packages/agents-core/src/tooling.ts, packages/agents-core/src/runner/toolExecution.ts, packages/agents-core/src/mcp.ts\n- **Handoffs 与 Agent 委托**：importance `medium`\n - source_paths: packages/agents-core/src/handoff.ts, packages/agents-core/src/extensions/handoffPrompt.ts, packages/agents-core/src/extensions/handoffFilters.ts\n- **Guardrails 安全防护**：importance `medium`\n - source_paths: packages/agents-core/src/guardrail.ts, packages/agents-core/src/toolGuardrail.ts, packages/agents-core/src/runner/guardrails.ts\n- **沙箱 Agent**：importance `high`\n - source_paths: packages/agents-core/src/sandbox/agent.ts, packages/agents-core/src/sandbox/manifest.ts, packages/agents-core/src/sandbox/local.ts, packages/agents-core/src/sandbox/capabilities/skills.ts\n- **沙箱运行时与容器**：importance `medium`\n - source_paths: packages/agents-core/src/sandbox/sandboxes/docker.ts, packages/agents-core/src/sandbox/sandboxes/unixLocal.ts, packages/agents-core/src/sandbox/runtime/manager.ts, packages/agents-core/src/sandbox/sandboxes/shared/pty.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `629d35af99e1ba80fc968b0d062c070caed0683d`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `docs/tsconfig.scripts.json`, `docs/package.json`, `docs/README.md`, `docs/tsconfig.json`, `docs/src/content.config.ts`, `docs/src/plugins/typedoc-frontmatter.js`, `docs/src/scripts/translate.ts`, `docs/src/content/docs/index.mdx`, `docs/src/content/docs/ja/index.mdx`, `docs/src/content/docs/guides/multi-agent.md`, `docs/src/content/docs/guides/config.mdx`, `docs/src/content/docs/guides/troubleshooting.mdx`, `docs/src/content/docs/guides/context.mdx`, `docs/src/content/docs/guides/models.mdx`, `docs/src/content/docs/guides/handoffs.mdx`, `docs/src/content/docs/guides/sandbox-agents.mdx`, `docs/src/content/docs/guides/human-in-the-loop.mdx`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `openai-agents-js` 与安装入口 `@openai/agents` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:993521808 | https://github.com/openai/openai-agents-js | repo=openai-agents-js; install=@openai/agents\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 失败模式：installation: v0.10.0\n\n- Trigger: Developers should check this installation risk before relying on the project: v0.10.0\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.10.0. Context: Observed when using node, python\n- Why it matters: Upgrade or migration may change expected behavior: v0.10.0\n- Evidence: failure_mode_cluster:github_release | fmev_0017083f7c144b8b8068b1aa812f1798 | https://github.com/openai/openai-agents-js/releases/tag/v0.10.0 | v0.10.0\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 失败模式：installation: v0.11.2\n\n- Trigger: Developers should check this installation risk before relying on the project: v0.11.2\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.11.2. Context: Observed when using node, python\n- Why it matters: Upgrade or migration may change expected behavior: v0.11.2\n- Evidence: failure_mode_cluster:github_release | fmev_cbb13be7191292a101a93f89e2c40ad3 | https://github.com/openai/openai-agents-js/releases/tag/v0.11.2 | v0.11.2\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 失败模式：configuration: v0.9.0\n\n- Trigger: Developers should check this configuration risk before relying on the project: v0.9.0\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.9.0. Context: Observed when using docker\n- Why it matters: Upgrade or migration may change expected behavior: v0.9.0\n- Evidence: failure_mode_cluster:github_release | fmev_742498adc1555b1770e9377463c11ff4 | https://github.com/openai/openai-agents-js/releases/tag/v0.9.0 | v0.9.0\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:993521808 | https://github.com/openai/openai-agents-js | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 失败模式：runtime: Large realtime audio buffers can crash during base64 encoding\n\n- Trigger: Developers should check this runtime risk before relying on the project: Large realtime audio buffers can crash during base64 encoding\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Large realtime audio buffers can crash during base64 encoding. Context: Observed when using node\n- Why it matters: Developers may hit a documented source-backed failure mode: Large realtime audio buffers can crash during base64 encoding\n- Evidence: failure_mode_cluster:github_issue | fmev_aaf4394591e72954462f8a949be29aee | https://github.com/openai/openai-agents-js/issues/1333 | Large realtime audio buffers can crash during base64 encoding, failure_mode_cluster:github_issue | fmev_dfcff51166e62ba4cc81679f3c9c2f18 | https://github.com/openai/openai-agents-js/issues/1333 | Large realtime audio buffers can crash during base64 encoding\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 失败模式：runtime: v0.11.4\n\n- Trigger: Developers should check this runtime risk before relying on the project: v0.11.4\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.11.4. Context: Source discussion did not expose a precise runtime context.\n- Why it matters: Upgrade or migration may change expected behavior: v0.11.4\n- Evidence: failure_mode_cluster:github_release | fmev_73a57d6e6bb4c1e93cea0e78313774b1 | https://github.com/openai/openai-agents-js/releases/tag/v0.11.4 | v0.11.4\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Large realtime audio buffers can crash during base64 encoding\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Large realtime audio buffers can crash during base64 encoding\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_1f01240eec894a519476aebd4a7590db | https://github.com/openai/openai-agents-js/issues/1333 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 失败模式：migration: v0.9.1\n\n- Trigger: Developers should check this migration risk before relying on the project: v0.9.1\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.9.1. Context: Observed during version upgrade or migration.\n- Why it matters: Upgrade or migration may change expected behavior: v0.9.1\n- Evidence: failure_mode_cluster:github_release | fmev_e351743729d2a86ad6987f1baefae665 | https://github.com/openai/openai-agents-js/releases/tag/v0.9.1 | v0.9.1\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:993521808 | https://github.com/openai/openai-agents-js | last_activity_observed missing\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-js\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- 失败模式：installation: v0.10.0（medium）：Upgrade or migration may change expected behavior: v0.10.0 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.10.0. Context: Observed when using node, python\n- 失败模式：installation: v0.11.2（medium）：Upgrade or migration may change expected behavior: v0.11.2 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.11.2. Context: Observed when using node, python\n- 失败模式：configuration: v0.9.0（medium）：Upgrade or migration may change expected behavior: v0.9.0 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.9.0. Context: Observed when using docker\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/openai/openai-agents-js 项目说明书\n\n生成时间：2026-05-17 12:58:06 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [系统架构](#page-architecture)\n- [Agent 核心机制](#page-agents)\n- [工具系统](#page-tools)\n- [Handoffs 与 Agent 委托](#page-handoffs)\n- [Guardrails 安全防护](#page-guardrails)\n- [沙箱 Agent](#page-sandbox-agents)\n- [沙箱运行时与容器](#page-sandbox-runtime)\n- [实时语音 Agent](#page-realtime-agents)\n- [传输层与集成](#page-transport-layer)\n\n