跳转至

快速入门

测试版功能

沙箱智能体目前处于测试阶段。在正式发布前，API 细节、默认设置和支持的能力可能会发生变化，未来还将陆续推出更多高级功能。

现代智能体只有能够操作文件系统中的真实文件时，才能发挥最佳效果。Agents SDK 中的沙箱智能体为模型提供持久工作区，使其能够检索大型文档集、编辑文件、运行命令、生成工件，并从保存的沙箱状态中恢复工作。

SDK 提供了这套执行框架，你无需自行串联文件暂存、文件系统工具、shell 访问、沙箱生命周期、快照以及特定于提供商的适配代码。你可以保留常规的 Agent 和 Runner 流程，然后添加用于工作区的 Manifest、沙箱原生工具的能力，以及用于指定工作运行位置的 SandboxRunConfig。

前提条件

  • Python 3.10 或更高版本
  • 对OpenAI Agents SDK有基本了解
  • 一个沙箱客户端。对于可信的本地开发，请从 UnixLocalSandboxClient 开始。

安装

如果尚未安装 SDK：

pip install openai-agents

对于由 Docker 支持的沙箱：

pip install "openai-agents[docker]"

本地沙箱智能体的创建

此示例会将本地代码仓库暂存到 repo/ 下，延迟加载本地技能，并让运行器为本次运行创建 Unix 本地沙箱会话。

本地命令使用主机权限

在 Linux 上，UnixLocalSandboxClient 不会对命令施加任何操作系统级别的限制。在 macOS 上，它会通过 sandbox-exec 应用文件系统限制，但不提供网络隔离。请仅将此示例用于可信的本地开发，或在外部隔离的环境中使用。对于不可信的命令，包括受不可信输入影响的命令，请选择经过适当配置的 Docker 沙箱或托管沙箱，或者提供外部隔离。请参阅 Unix 本地执行限制。

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。它使用一个基于 shell 的微型代码仓库，因此可以在不同的 Unix 本地运行中以确定性的方式验证此示例。

关键选择

基本运行正常后，大多数人接下来通常会使用以下选项：

  • default_manifest：新沙箱会话使用的文件、代码仓库、目录和挂载
  • instructions：应在不同提示词中统一应用的简短工作流规则
  • base_instructions：用于替换 SDK 沙箱提示词的高级备用机制
  • capabilities：沙箱原生工具，例如文件系统编辑/图像检查、shell、技能、记忆，以及 SDK 的压缩机制
  • run_as：面向模型的工具执行时所使用的沙箱用户账户
  • SandboxRunConfig.client：沙箱后端
  • SandboxRunConfig.session、session_state 或 snapshot：后续运行重新连接到先前工作的方式

后续步骤

  • 概念：了解清单、能力、权限、快照、运行配置和组合模式。
  • 沙箱客户端：选择 Unix 本地、Docker、托管提供商和挂载策略。
  • 智能体记忆：保留并复用以往沙箱运行中积累的经验。

如果 shell 访问只是你偶尔使用的工具之一，请从工具指南中的托管 shell 开始。当工作区隔离、沙箱客户端选择或沙箱会话恢复行为属于整体设计的一部分时，请使用沙箱智能体。