INTEGRITY Документация

Создание ИИ-агента для написания кода с OpenAI Agents SDK

OpenAI Agents SDK ↗ это легковесный Python фреймворк для построения мультиагентных рабочих процессов. Интеграция с Cloudflare Sandbox предоставляется из коробки и обеспечивает то, что SDK включает полноценный бэкенд Cloudflare, предоставляющий вашим агентам изолированные контейнеры для запуска кода, установки пакетов и управления файлами.

В этом руководстве вы развернёте Worker-мост для песочницы и создадите агента на Python, который принимает задачу на написание кода, выполняет её внутри Cloudflare Sandbox и копирует выходные файлы на локальную машину.

Время выполнения: 20 минут

Предварительные требования

  1. Зарегистрируйтесь для получения Аккаунт Cloudflare ↗ с включённым Containers / Sandbox beta.
  2. Установка Python 3.12+ ↗ и uv ↗.
  3. Получите OpenAI API key ↗.

1. Разверните мост песочницы

мост песочницы представляет собой Cloudflare Worker, который предоставляет Sandbox API по HTTP, чтобы клиенты, не являющиеся Worker (например, Python скрипт, использующий OpenAI Agents SDK), могли создавать песочницы и управлять ими.

Среда Sandbox предварительно настроена для разработки на Node.js и Python, поэтому ваши агенты могут сразу начать писать и выполнять код.

Разверните bridge в своём аккаунте Cloudflare:

Deploy to Cloudflare

Кнопка разворачивает Worker и создаёт SANDBOX_API_KEY секрет для аутентификации. После завершения развертывания запишите URL Worker и API-ключ: они понадобятся вам на следующем шаге.

Ручное развёртывание

Если вы предпочитаете разворачивать поэтапно:

  1. Установка Node.js ↗ и Docker ↗.

  2. Создайте каркас проекта моста:

    npm create cloudflare sandbox-bridge --template=cloudflare/sandbox-sdk/bridge/worker
    cd sandbox-bridge
  3. Аутентификация в Cloudflare:

    npx wrangler login
  4. Задайте секрет с API-ключом:

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

    Ключ выводится в ваш терминал и передаётся через конвейер в Wrangler. Сохраните его: он понадобится для аутентификации запросов к API.

  5. Разверните Worker:

    npx wrangler deploy
  6. Проверьте развёртывание:

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

    Вы должны увидеть {"ok":true}.

2. Настройте проект Python

Создайте новый каталог для агента:

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

Создайте .env файл с вашими учётными данными:

.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. Постройте агента

Создайте main.py со следующим содержимым. Встроенные метаданные скрипта сообщают uv какие зависимости устанавливать, поэтому всё содержится в одном файле:

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")))

Вот что делает каждый из ключевых компонентов:

Компонент Назначение
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, который:

Worker'а моста Dockerfile можно полностью настраивать под свои задачи: устанавливать дополнительные языки, системные пакеты или инструменты, соответствующие вашему сценарию использования.

Cloudflare Sandbox предоставляет дополнительные возможности, которые можно интегрировать в ваших агентов:

Следующие шаги