This document introduces the API interfaces of AgentFlow, covering all three core modules: Sandbox, Rollout, and Synthesis.

Synthesis API

synthesize()

One-stop data synthesis entry point.

from synthesis import synthesize

synthesize(config_path="configs/synthesis/web_config.json")

load_config() / load_seeds()

Step-by-step loading of configuration and seed data.

from synthesis import load_config, load_seeds

config = load_config("configs/synthesis/web_config.json")
seeds = load_seeds("seeds/web/seeds.jsonl")

Main Functions:

Function	Description
synthesize(config_path, seeds)	Run the full synthesis pipeline
load_config(config_path)	Load SynthesisConfig configuration
load_seeds(seeds_or_path)	Load seed data (supports file path, string list, dict list)

Rollout API

rollout()

One-stop inference and evaluation entry point.

from rollout import rollout

result = rollout(config_path="configs/infer/web_infer.json")

quick_rollout()

Quick single-question inference without a config file.

from rollout import quick_rollout

result = quick_rollout(
    "What is the capital of France?",
    tools=["web-search", "web-visit"],
    model_name="gpt-4.1-2025-04-14",
    api_key="your-key",
    base_url="https://api.openai.com/v1",
)

load_config() / load_tasks()

Step-by-step loading of configuration and task data.

from rollout import load_config, load_tasks

config = load_config("configs/infer/web_infer.json")
tasks = load_tasks("benchmark/web_bench.jsonl")

Main Functions:

Function	Description
rollout(config_path, ...)	Run the inference and evaluation pipeline
quick_rollout(question, ...)	Quick single-question inference
load_config(config_path)	Load RolloutConfig configuration
load_tasks(tasks_or_path)	Load benchmark task data

Sandbox Client API

Sandbox Class

Sandbox is the main entry class for user interaction.

from sandbox import Sandbox

# Create instance
sandbox = Sandbox(
    server_url="http://127.0.0.1:18890",
    worker_id="my_worker",
    auto_start_server=True
)

Main Methods:

Method	Description
start()	Start connection
close()	Close connection
warmup(resources)	Warmup backends
create_session(resource, config)	Create Session
destroy_session(resource)	Destroy Session
execute(action, params)	Execute tool
list_sessions()	List Sessions
get_status()	Get status

HTTPServiceClient Class

Low-level HTTP client for advanced usage.

from sandbox.client import HTTPServiceClient, HTTPClientConfig

config = HTTPClientConfig(
    base_url="http://127.0.0.1:18890",
    timeout=60.0,
    max_retries=3
)
client = HTTPServiceClient(config=config)

Server API

HTTP Endpoints

Endpoint	Method	Description
/execute	POST	Execute tool
/execute/batch	POST	Batch execute
/session/create	POST	Create Session
/session/destroy	POST	Destroy Session
/session/list	POST	List Sessions
/session/refresh	POST	Refresh Session
/tools	GET	List tools
/health	GET	Health check
/warmup	POST	Warmup backends
/warmup/status	GET	Warmup status
/shutdown	POST	Shutdown server

Response Format

Standard response format:

{
  "code": 0,
  "message": "success",
  "data": {...},
  "meta": {
    "execution_time_ms": 150,
    "tool": "screenshot",
    "resource_type": "vm",
    "session_id": "xxx"
  }
}

Error Codes

Code	Description
0	Success
1001	Tool not found
1002	Parameter error
1003	Session error
2001	Backend error
2002	Timeout
5000	Internal error

Quick Reference

Data Synthesis

from synthesis import synthesize

synthesize(config_path="configs/synthesis/web_config.json")

Inference & Evaluation

from rollout import rollout

result = rollout(config_path="configs/infer/web_infer.json")
print(f"Accuracy: {result['accuracy']}")

Execute Tool

# Async
result = await sandbox.execute("vm:screenshot", {})

# Sync
result = sandbox.execute_sync("vm:screenshot", {})

Session Management

# Create
await sandbox.create_session("vm", {"screen_size": [1920, 1080]})

# Destroy
await sandbox.destroy_session("vm")

# List
sessions = await sandbox.list_sessions()

Warmup

# Warmup specific backends
await sandbox.warmup(["rag", "vm"])

# Get warmup status
status = await sandbox.get_warmup_status()