INTEGRITY Dokumentace

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

  1. Zaregistrujte si účet Cloudflare ↗ se zapnutou beta verzí Containers / Sandbox.
  2. Nainstalujte Python 3.12+ ↗ a uv ↗.
  3. 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:

Deploy to 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:

  1. Nainstalujte Node.js ↗ a Docker ↗.

  2. Vytvořte základní strukturu projektu bridge:

    npm create cloudflare sandbox-bridge --template=cloudflare/sandbox-sdk/bridge/worker
    cd sandbox-bridge
  3. Ověřte se u Cloudflare:

    npx wrangler login
  4. Nastavte tajný klíč API:

    openssl rand -hex 32 | tee /dev/stderr | npx wrangler secret put SANDBOX_API_KEY

    Klíč 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.

  5. Nasaďte Worker:

    npx wrangler deploy
  6. Ověřte nasazení:

    curl https://cloudflare-sandbox-bridge.<your-subdomain>.workers.dev/health

    Měli byste vidět {"ok":true}.

2. Nastavte projekt v Pythonu

Vytvořte nový adresář pro agenta:

mkdir openai-sandbox-agent && cd openai-sandbox-agent

Vytvořte .env soubor s vašimi přihlašovacími údaji:

.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.dev

3. 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:

main.py
# /// 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.ts

Agent 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ý:

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ů:

Další kroky