chore: import upstream snapshot with attribution

2026-07-13 12:39:17 +08:00
commit 4ed4e9ff99
1368 changed files with 334957 additions and 0 deletions
@@ -0,0 +1,117 @@
+---
+search:
+  exclude: true
+---
+# 快速入门
+
+!!! warning "测试版功能"
+
+    沙箱智能体目前处于测试阶段。在正式发布之前，API 细节、默认值和支持的功能可能会发生变化，并且未来将逐步提供更高级的功能。
+
+现代智能体能够在文件系统中操作真实文件时，往往能发挥最佳效果。Agents SDK 中的**沙箱智能体**为模型提供持久化工作区，使其能够检索大型文档集、编辑文件、运行命令、生成产物，并从已保存的沙箱状态继续工作。
+
+SDK 为你提供这一执行框架，无需自行整合文件暂存、文件系统工具、shell 访问、沙箱生命周期、快照以及特定于提供商的适配代码。你可以继续使用常规的 `Agent` 和 `Runner` 流程，然后为工作区添加 `Manifest`，为沙箱原生工具添加 capabilities，并使用 `SandboxRunConfig` 指定工作运行的位置。
+
+## 前置条件
+
+- Python 3.10 或更高版本
+- 基本熟悉 OpenAI Agents SDK
+- 沙箱客户端。对于本地开发，请从 `UnixLocalSandboxClient` 开始。
+
+## 安装
+
+如果尚未安装 SDK：
+
+```bash
+pip install openai-agents
+```
+
+对于由 Docker 支持的沙箱：
+
+```bash
+pip install "openai-agents[docker]"
+```
+
+## 本地沙箱智能体的创建
+
+此代码示例将本地仓库存放到 `repo/` 下，延迟加载本地技能，并允许运行器为本次运行创建 Unix 本地沙箱会话。
+
+```python
+import asyncio
+from pathlib import Path
+
+from agents import Runner
+from agents.run import RunConfig
+from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
+from agents.sandbox.capabilities import Capabilities, LocalDirLazySkillSource, Skills
+from agents.sandbox.entries import LocalDir
+from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient
+
+EXAMPLE_DIR = Path(__file__).resolve().parent
+HOST_REPO_DIR = EXAMPLE_DIR / "repo"
+HOST_SKILLS_DIR = EXAMPLE_DIR / "skills"
+
+
+def build_agent(model: str) -> SandboxAgent[None]:
+    return SandboxAgent(
+        name="Sandbox engineer",
+        model=model,
+        instructions=(
+            "Read `repo/task.md` before editing files. Stay grounded in the repository, preserve "
+            "existing behavior, and mention the exact verification command you ran. "
+            "If you edit files with apply_patch, paths are relative to the sandbox workspace root."
+        ),
+        default_manifest=Manifest(
+            entries={
+                "repo": LocalDir(src=HOST_REPO_DIR),
+            }
+        ),
+        capabilities=Capabilities.default() + [
+            Skills(
+                lazy_from=LocalDirLazySkillSource(
+                    # This is a host path read by the SDK process.
+                    # Requested skills are copied into `skills_path` in the sandbox.
+                    source=LocalDir(src=HOST_SKILLS_DIR),
+                )
+            ),
+        ],
+    )
+
+
+async def main() -> None:
+    result = await Runner.run(
+        build_agent("gpt-5.6-sol"),
+        "Open `repo/task.md`, fix the issue, run the targeted test, and summarize the change.",
+        run_config=RunConfig(
+            sandbox=SandboxRunConfig(client=UnixLocalSandboxClient()),
+            workflow_name="Sandbox coding example",
+        ),
+    )
+    print(result.final_output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+请参阅 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用一个基于 shell 的小型仓库，因此可以在多次 Unix 本地运行中以确定性方式验证该代码示例。
+
+## 关键选项
+
+基本运行正常后，大多数人接下来会使用以下选项：
+
+- `default_manifest`：全新沙箱会话所使用的文件、仓库、目录和挂载项
+- `instructions`：应适用于所有提示词的简短工作流规则
+- `base_instructions`：用于替换 SDK 沙箱提示词的高级应急选项
+- `capabilities`：沙箱原生工具，例如文件系统编辑/图像检查、shell、技能、记忆和压缩
+- `run_as`：面向模型的工具所使用的沙箱用户身份
+- `SandboxRunConfig.client`：沙箱后端
+- `SandboxRunConfig.session`、`session_state` 或 `snapshot`：后续运行如何重新连接到先前的工作
+
+## 后续步骤
+
+- [概念](sandbox/guide.md)：了解清单、capabilities、权限、快照、运行配置和组合模式。
+- [沙箱客户端](sandbox/clients.md)：选择 Unix 本地、Docker、托管提供商和挂载策略。
+- [智能体记忆](sandbox/memory.md)：保留并复用以往沙箱运行中获得的经验。
+
+如果 shell 访问只是偶尔使用的工具，请先从[工具指南](tools.md)中的托管 shell 开始。如果工作区隔离、沙箱客户端选择或沙箱会话恢复行为属于设计的一部分，请使用沙箱智能体。