← Sandbox SDK / sandbox / tutorials
Vytvořte AI kódovacího agenta pomocí OpenAI Agents SDK
OpenAI Agents SDK ↗ je odlehčený Python framework pro vytváření multiagentních workflow. Integrace Cloudflare Sandbox je součástí instalace a zajišťuje, že SDK obsahuje plnohodnotný backend Cloudflare, který vašim agentům poskytuje izolované kontejnery pro spouštění kódu, instalaci balíčků a správu souborů.
V tomto tutoriálu nasadíte sandbox bridge Worker a vytvoříte agenta v Pythonu, který přijme úlohu na programování, provede ji uvnitř Cloudflare Sandboxu a zkopíruje výstupní soubory do vašeho místního počítače.
Doba dokončení: 20 minut
Předpoklady
- Zaregistrujte si účet Cloudflare ↗ se zapnutou beta verzí Containers / Sandbox.
- Nainstalujte Python 3.12+ ↗ a uv ↗.
- Získejte OpenAI API key ↗.
1. Nasaďte sandbox bridge
sandbox bridge je Cloudflare Worker, který zpřístupňuje Sandbox API přes HTTP, takže klienti mimo Worker, například Python skript používající OpenAI Agents SDK, mohou vytvářet sandboxy a řídit je.
Prostředí Sandbox je přednastavené pro vývoj v Node.js a Pythonu, takže vaši agenti mohou okamžitě začít psát a spouštět kód.
Nasaďte propojovací vrstvu do svého účtu Cloudflare:
Tlačítko nasadí Worker a vygeneruje SANDBOX_API_KEY secret pro ověřování. Po dokončení nasazení si poznamenejte URL adresu svého Workeru a API klíč, budete je potřebovat v dalším kroku.
Ruční nasazení
Pokud dáváte přednost nasazení po krocích:
-
Vytvořte základní strukturu projektu bridge:
npm create cloudflare sandbox-bridge --template=cloudflare/sandbox-sdk/bridge/worker cd sandbox-bridge -
Ověřte se u Cloudflare:
npx wrangler login -
Nastavte tajný klíč API:
openssl rand -hex 32 | tee /dev/stderr | npx wrangler secret put SANDBOX_API_KEYKlíč se vypíše do vašeho terminálu a rourou odešle do Wrangleru. Uložte si ho, budete ho potřebovat k autentizaci požadavků API.
-
Nasaďte Worker:
npx wrangler deploy -
Ověřte nasazení:
curl https://cloudflare-sandbox-bridge.<your-subdomain>.workers.dev/healthMěli byste vidět
{"ok":true}.
2. Nastavte projekt v Pythonu
Vytvořte nový adresář pro agenta:
mkdir openai-sandbox-agent && cd openai-sandbox-agentVytvořte .env soubor s vašimi přihlašovacími údaji:
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. Sestavte agenta
Vytvořit main.py s následujícím obsahem. Vložená metadata skriptu sdělují uv které závislosti se mají instalovat, takže vše je obsaženo v jediném souboru:
# /// 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")))Následuje přehled toho, co dělají jednotlivé klíčové části:
| Komponenta | Účel |
|---|---|
SandboxAgent |
Agent podtřídu, která přijímá konfiguraci specifickou pro sandbox, včetně capabilities. |
Shell() |
Funkce, která zpřístupňuje LLM nástroj shellu a umožňuje mu spouštět příkazy uvnitř sandboxu. |
CloudflareSandboxClient |
Vytváří a spravuje relace sandboxu prostřednictvím propojovacího Workeru. Čte CLOUDFLARE_SANDBOX_API_KEY z prostředí pro ověřování. |
CloudflareSandboxClientOptions |
Nasměruje klienta na URL adresu vašeho přemosťujícího Workeru. |
Runner.run_streamed() |
Spustí agenta a postupně vrací streamované události pro volání nástrojů a textový výstup. |
SandboxRunConfig |
Připojí k běhu aktivní relaci sandboxu, díky čemuž se nástroje agenta spouštějí uvnitř kontejneru. |
4. Spusťte agenta
uv run --env-file .env main.py "Create a hello world HTTP server using Bun.serve"Měli byste vidět volání nástrojů a výstup streamovaný do konzole:
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.tsAgent napsal kód, otestoval ho v sandboxu a výsledek zkopíroval do vašeho lokálního počítače.
Co jste vytvořili
Vytvořili jste agenta pro psaní kódu v Pythonu, který:
- Přijímá programátorský úkol zadaný přirozeným jazykem
- Spouští kód v izolovaném kontejneru Cloudflare Sandbox
- Instaluje balíčky, spouští testy a iteruje, dokud není úloha dokončena
- Zkopíruje výsledné soubory zpět do vašeho lokálního počítače
Worker bridge má Dockerfile lze plně přizpůsobit vašim potřebám: nainstalujte si další jazyky, systémové balíčky nebo nástroje podle svého případu použití.
Cloudflare Sandbox nabízí další možnosti, které můžete integrovat do svých agentů:
- Relace PTY : Otevírejte interaktivní terminálové relace do sandboxů přes WebSocket pro I/O v reálném čase.
- Připojení bucketů : Připojte buckety R2 nebo kompatibilní s S3 jako lokální adresáře uvnitř sandboxu pro trvalá data.
- Zálohování a obnovení pracovního prostoru : Ukládejte stav pracovního prostoru pomocí
persist_workspace()ahydrate_workspace()k obnovení práce napříč životními cykly sandboxu. - Operace se soubory : Programově čtěte, zapisujte a spravujte soubory uvnitř sandboxu.
Další kroky
- Příklad chatu v pracovním prostoru ↗ : Full-stack chatovací aplikace s postranním panelem pro procházení souborů, vytvořená pomocí OpenAI Agents SDK a Cloudflare Sandbox.
- dokumentace OpenAI Agents SDK ↗ : Přečtěte si o multi-agent handoffs, guardrails, tracing a dalších tématech.
- Sandbox bridge : Přehled bridge Worker, ukázky použití a konfigurace.
- Referenční dokumentace HTTP API : Úplná referenční dokumentace tras pro bridge API.
- Návody k sandboxu : Další návody zaměřené na spouštění kódu, analýzu dat a CI/CD pipeline.