← Sandbox SDK / sandbox / tutorials
Создание ИИ-агента для написания кода с OpenAI Agents SDK
OpenAI Agents SDK ↗ это легковесный Python фреймворк для построения мультиагентных рабочих процессов. Интеграция с Cloudflare Sandbox предоставляется из коробки и обеспечивает то, что SDK включает полноценный бэкенд Cloudflare, предоставляющий вашим агентам изолированные контейнеры для запуска кода, установки пакетов и управления файлами.
В этом руководстве вы развернёте Worker-мост для песочницы и создадите агента на Python, который принимает задачу на написание кода, выполняет её внутри Cloudflare Sandbox и копирует выходные файлы на локальную машину.
Время выполнения: 20 минут
Предварительные требования
- Зарегистрируйтесь для получения Аккаунт Cloudflare ↗ с включённым Containers / Sandbox beta.
- Установка Python 3.12+ ↗ и uv ↗.
- Получите OpenAI API key ↗.
1. Разверните мост песочницы
мост песочницы представляет собой Cloudflare Worker, который предоставляет Sandbox API по HTTP, чтобы клиенты, не являющиеся Worker (например, Python скрипт, использующий OpenAI Agents SDK), могли создавать песочницы и управлять ими.
Среда Sandbox предварительно настроена для разработки на Node.js и Python, поэтому ваши агенты могут сразу начать писать и выполнять код.
Разверните bridge в своём аккаунте Cloudflare:
Кнопка разворачивает Worker и создаёт SANDBOX_API_KEY секрет для аутентификации. После завершения развертывания запишите URL Worker и API-ключ: они понадобятся вам на следующем шаге.
Ручное развёртывание
Если вы предпочитаете разворачивать поэтапно:
-
Создайте каркас проекта моста:
npm create cloudflare sandbox-bridge --template=cloudflare/sandbox-sdk/bridge/worker cd sandbox-bridge -
Аутентификация в Cloudflare:
npx wrangler login -
Задайте секрет с API-ключом:
openssl rand -hex 32 | tee /dev/stderr | npx wrangler secret put SANDBOX_API_KEYКлюч выводится в ваш терминал и передаётся через конвейер в Wrangler. Сохраните его: он понадобится для аутентификации запросов к API.
-
Разверните Worker:
npx wrangler deploy -
Проверьте развёртывание:
curl https://cloudflare-sandbox-bridge.<your-subdomain>.workers.dev/healthВы должны увидеть
{"ok":true}.
2. Настройте проект Python
Создайте новый каталог для агента:
mkdir openai-sandbox-agent && cd openai-sandbox-agentСоздайте .env файл с вашими учётными данными:
OPENAI_API_KEY=sk-your-openai-key
CLOUDFLARE_SANDBOX_API_KEY=your-bridge-token
CLOUDFLARE_SANDBOX_WORKER_URL=https://cloudflare-sandbox-bridge.your-subdomain.workers.dev3. Постройте агента
Создайте main.py со следующим содержимым. Встроенные метаданные скрипта сообщают uv какие зависимости устанавливать, поэтому всё содержится в одном файле:
# /// script
# requires-python = ">=3.12"
# dependencies = ["openai-agents[cloudflare]"]
# ///
"""One-shot coding agent backed by a Cloudflare Sandbox."""
from __future__ import annotations
import asyncio
import os
import sys
from pathlib import Path
from agents import Runner
from agents.extensions.sandbox.cloudflare import (
CloudflareSandboxClient,
CloudflareSandboxClientOptions,
)
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from agents.sandbox.capabilities import Shell
MODEL = "gpt-5.4"
INSTRUCTIONS = """\
You are an expert developer working inside a sandbox.
The sandbox has bun, node, npm, and python available on the PATH.
Implement the user's task in /workspace, test it, then copy deliverable files to /workspace/output/.
""".strip()
async def copy_output(session, dest: Path) -> list[Path]:
"""Download files from /workspace/output/ in the sandbox to a local directory."""
dest.mkdir(parents=True, exist_ok=True)
ls = await session.exec("find", "/workspace/output", "-maxdepth", "1", "-type", "f", shell=False)
if not ls.ok():
return []
copied: list[Path] = []
for name in (l.strip() for l in ls.stdout.decode().splitlines() if l.strip()):
handle = await session.read(Path(name))
local = dest / Path(name).name
payload = handle.read(); handle.close()
local.write_bytes(payload if isinstance(payload, bytes) else payload.encode())
copied.append(local)
return copied
async def run(prompt: str, output_dir: Path) -> None:
worker_url = os.environ.get("CLOUDFLARE_SANDBOX_WORKER_URL", "")
if not worker_url:
sys.exit("Error: CLOUDFLARE_SANDBOX_WORKER_URL is not set.")
agent = SandboxAgent(
name="Developer",
model=MODEL,
instructions=INSTRUCTIONS,
capabilities=[Shell()],
)
client = CloudflareSandboxClient()
options = CloudflareSandboxClientOptions(worker_url=worker_url)
session = await client.create(manifest=agent.default_manifest, options=options)
try:
async with session:
run_config = RunConfig(
sandbox=SandboxRunConfig(session=session),
tracing_disabled=True,
)
# Stream tool calls so the user can follow progress.
result = Runner.run_streamed(agent, prompt, run_config=run_config)
async for ev in result.stream_events():
if ev.type == "run_item_stream_event" and ev.name == "tool_called":
print(f" [tool] {getattr(ev.item.raw_item, 'name', '')}")
elif ev.type == "run_item_stream_event" and ev.name == "tool_output":
print(f" [output] {str(getattr(ev.item, 'output', ''))[:200]}")
# Copy output files from the sandbox to the local machine.
copied = await copy_output(session, output_dir)
if copied:
print(f"\nCopied {len(copied)} file(s) to {output_dir}:")
for p in copied:
print(f" {p}")
else:
print("\nAgent did not produce any output files.")
finally:
await client.delete(session)
if __name__ == "__main__":
prompt = sys.argv[1] if len(sys.argv) > 1 else "Create a hello world HTTP server using Bun.serve"
asyncio.run(run(prompt, Path("output")))Вот что делает каждый из ключевых компонентов:
| Компонент | Назначение |
|---|---|
SandboxAgent |
Одна Agent подкласс, который принимает специфичную для sandbox конфигурацию, включая capabilities. |
Shell() |
Возможность, которая предоставляет LLM инструмент shell, позволяющий выполнять команды внутри песочницы. |
CloudflareSandboxClient |
Создаёт сессии песочницы и управляет ими через bridge Worker. Считывает CLOUDFLARE_SANDBOX_API_KEY из окружения для аутентификации. |
CloudflareSandboxClientOptions |
Направляет клиента на URL вашего Worker-моста. |
Runner.run_streamed() |
Запускает агента и выдаёт потоковые события для вызовов инструментов и текстового вывода. |
SandboxRunConfig |
Подключает к запуску активную сессию песочницы, благодаря чему инструменты агента выполняются внутри контейнера. |
4. Запустите агента
uv run --env-file .env main.py "Create a hello world HTTP server using Bun.serve"Вы должны увидеть вызовы инструментов и вывод, потоково поступающий в консоль:
Sending task to sandbox agent (gpt-5.4)...
[tool] exec_command
[output] exit_code=0 stdout: mkdir: created directory '/workspace/output'
[tool] exec_command
[output] exit_code=0 stdout: Listening on http://localhost:3000
Copied 1 file(s) to output:
output/server.tsАгент написал код, протестировал его в песочнице и скопировал результат на ваш локальный компьютер.
Что вы создали
Вы создали агент для написания кода на Python, который:
- Принимает задачу на написание кода, сформулированную на естественном языке
- Выполняет код в изолированном контейнере Cloudflare Sandbox
- Устанавливает пакеты, запускает тесты и повторяет цикл, пока задача не будет выполнена
- Копирует итоговые файлы обратно на ваш локальный компьютер
Worker'а моста Dockerfile можно полностью настраивать под свои задачи: устанавливать дополнительные языки, системные пакеты или инструменты, соответствующие вашему сценарию использования.
Cloudflare Sandbox предоставляет дополнительные возможности, которые можно интегрировать в ваших агентов:
- Сеансы PTY : открытие интерактивных терминальных сессий к песочницам через WebSocket для ввода и вывода в реальном времени.
- Монтирования бакетов : монтирование бакетов R2 или S3-совместимых хранилищ как локальных каталогов внутри песочницы для хранения постоянных данных.
- Резервное копирование и восстановление рабочей области : сохранение состояния рабочего пространства с помощью
persist_workspace()иhydrate_workspace()чтобы возобновлять работу между жизненными циклами песочницы. - Файловые операции : программное чтение, запись и управление файлами внутри песочницы.
Следующие шаги
- Пример чата рабочей области ↗ : full-stack чат-приложение с боковой панелью файлового браузера, созданное с помощью OpenAI Agents SDK и Cloudflare Sandbox.
- документация OpenAI Agents SDK ↗ : узнайте о передаче управления между агентами, guardrails, трассировке и других возможностях.
- Мост песочницы : обзор bridge Worker, примеры использования и настройка.
- Справочник по HTTP API : полный справочник по маршрутам bridge API.
- Руководства по Sandbox : больше руководств о выполнении кода, анализе данных и CI/CD-пайплайнах.