Browser, Terminal und VSCode in einer Sandbox für LLMs ausführen
Als ich zum ersten Mal einen Stack für einen autonomen KI-Agenten zusammenstellte, wurde alles schnell zum Albtraum eines Dutzends verschiedener Dienste. Der Browser lief in einem isolierten Container, der Python-Interpreter in einem anderen, und Dateien mussten über S3 oder improvisierte Volume-Mounts zwischen ihnen hin- und hergeschoben werden. Infolgedessen konnte der Agent ein PDF im Browser herunterladen, es aber nicht in einer Bash-Sitzung öffnen, da die Dateisysteme voneinander isoliert waren.
Die Leute von agent-infra haben einen pragmatischen Ansatz gewählt. Sie haben das Projekt AIO Sandbox (All-in-One Agent Sandbox Environment) entwickelt, das alle Infrastrukturen, die ein Agent benötigt, in einem einzigen Docker-Container mit gemeinsamer Festplatte bündelt.
Was steckt in der Box
Das Konzept des Projekts ist einfach: LLMs Zugriff auf alle wichtigen Entwicklertools gewähren und gleichzeitig alles vom Host-System isolieren. Innerhalb eines einzigen Images erhalten Sie:
- Headless Chromium mit CDP-Protokoll-Unterstützung und Fernzugriff über VNC direkt im Browser
- VSCode Server (code-server) und interaktive Jupyter Notebooks zur Code-Ausführung
- WebSocket-Terminal zum Ausführen von Bash-Befehlen
- Integrierte MCP-Server (Model Context Protocol) für direkte Integration mit Claude, Cursor oder benutzerdefinierten Agents
- Proxy zur Vorschau von Ports und Web-Anwendungen
Der Hauptvorteil dieses Setups ist das vereinheitlichte Dateisystem. Wenn ein Agent einen Screenshot speichert oder eine CSV-Datei über Playwright herunterlädt, kann er diese Datei sofort mit einem Bash-Skript lesen, in Jupyter verarbeiten und das Ergebnis im Code-Editor öffnen. Keine komplexe Synchronisierung oder Netzwerk-Overhead erforderlich.
Schnellstart
Sie können den Container mit einem einzigen Befehl lokal starten:
docker run --security-opt seccomp=unconfined --rm -it \
-e SANDBOX_API_KEY=your-secret-key \
-p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:latest
Sobald er läuft, bietet Port 8080 Zugriff auf ein vollständiges Toolset:
- API-Dokumentation:
http://localhost:8080/v1/docs - Browser-Desktop-Streaming über VNC:
http://localhost:8080/vnc/index.html?autoconnect=true - Web-Version des VSCode-Editors:
http://localhost:8080/code-server/ - MCP-Endpunkte:
http://localhost:8080/mcp
Wenn Sie die Umgebung in der Produktion bereitstellen müssen, enthält das Repository fertige Manifeste für Docker Compose und Kubernetes. Bei der Bereitstellung in der Cloud sollte Port 8080 hinter einem Reverse Proxy mit Authentifizierung verborgen werden, da der Agent beliebigen Code im Container ausführt.
Wie man mit der Sandbox über Code arbeitet
Die Autoren bieten offizielle SDKs für Python, TypeScript und Go. Die Arbeit mit der API ist unkompliziert.
Python-Paket installieren:
pip install agent-sandbox
Basis-Shell- und Dateioperationen:
from agent_sandbox import Sandbox
client = Sandbox(base_url="http://localhost:8080")
home_dir = client.sandbox.get_context().home_dir
# Выполняем bash команду
result = client.shell.exec_command(command="ls -la")
print(result.data.output)
# Читаем конфигурационный файл
content = client.file.read_file(file=f"{home_dir}/.bashrc")
print(content.data.content)
# Делаем снимок экрана в браузере
screenshot = client.browser.screenshot()
Das TypeScript-SDK hat nahezu identische Signaturen:
import { Sandbox } from '@agent-infra/sandbox';
const sandbox = new Sandbox({ baseURL: 'http://localhost:8080' });
const result = await sandbox.shell.exec({ command: 'ls -la' });
console.log(result.output);
const content = await sandbox.file.read({ path: '/home/gem/.bashrc' });
console.log(content);
Vollständiges Szenario: Von der Webseite zum Markdown-Bericht
Hier ist ein Beispiel, das zeigt, wie die Komponenten zusammenarbeiten. Das Skript verbindet sich mit dem Sandbox-Browser über das Chrome DevTools Protocol, lädt eine Seite, macht einen Screenshot und übergibt dann den HTML-Code an den Jupyter-Kernel zur Konvertierung und speichert die endgültige Datei.
import asyncio
import base64
from playwright.async_api import async_playwright
from agent_sandbox import Sandbox
async def site_to_markdown():
c = Sandbox(base_url="http://localhost:8080")
home_dir = c.sandbox.get_context().home_dir
# 1. Браузер: заходим на сайт и забираем разметку
async with async_playwright() as p:
browser_info = c.browser.get_info().data
page = await (await p.chromium.connect_over_cdp(browser_info.cdp_url)).new_page()
await page.goto("https://example.com", wait_until="networkidle")
html = await page.content()
screenshot_b64 = base64.b64encode(await page.screenshot()).decode('utf-8')
# 2. Jupyter: выполняем скрипт конвертации внутри песочницы
c.jupyter.execute_code(code=f"""
from markdownify import markdownify
html = '''{html}'''
screenshot_b64 = "{screenshot_b64}"
md = f"{{markdownify(html)}}\\n\\n"
with open('{home_dir}/site.md', 'w') as f:
f.write(md)
print("Done!")
""")
# 3. Shell: проверяем созданные файлы
list_result = c.shell.exec_command(command=f"ls -lh {home_dir}")
print(f"Файлы в песочнице: {list_result.data.output}")
# 4. File API: забираем готовый markdown
return c.file.read_file(file=f"{home_dir}/site.md").data.content
if __name__ == "__main__":
result = asyncio.run(site_to_markdown())
print("Отчет успешно сохранен")
Integration mit fertigen Frameworks
Die Sandbox kann problemlos mit beliebten Bibliotheken wie LangChain, Browser Use oder der Standard-OpenAI-API integriert werden.
So sieht Function Calling in OpenAI Chat Completions für die Ausführung von Python- und Node.js-Code aus:
import json
from openai import OpenAI
from agent_sandbox import Sandbox
client = OpenAI(api_key="your_api_key")
sandbox = Sandbox(base_url="http://localhost:8080")
def run_code(code, lang="python"):
if lang == "python":
return sandbox.jupyter.execute_code(code=code).data
return sandbox.nodejs.execute_nodejs_code(code=code).data
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Посчитай факториал числа 12 на Python"}],
tools=[
{
"type": "function",
"function": {
"name": "run_code",
"parameters": {
"type": "object",
"properties": {
"code": {"type": "string"},
"lang": {"type": "string"},
},
},
},
}
],
)
if response.choices[0].message.tool_calls:
args = json.loads(response.choices[0].message.tool_calls[0].function.arguments)
result = run_code(**args)
print(result['outputs'][0]['text'])
Für wen ist dieses Projekt gedacht
Wenn Sie einen KI-Assistenten entwickeln, der mehr als eine einfache Textantwort benötigt, spart Ihnen dieses Projekt viel Zeit bei der Einrichtung der Umgebung. Es eignet sich hervorragend für autonomes Web-Scraping, Datenanalyse, Code-Generierung und -Debugging sowie für UI-Tests über VNC.
Ein offensichtlicher Nachteil: Das Container-Image ist aufgrund des installierten Chromium, Node.js, Python und Code-Servers ziemlich groß. Für leichte Aufgaben, bei denen der Agent nur Bash benötigt, kann dies überdimensioniert sein. Aber wenn Sie einen vollständigen Tool-Stack mit gemeinsamem Dateisystem benötigen, sieht AIO Sandbox nach einer der durchdachtesten Lösungen auf GitHub aus.
Ähnliche Projekte