API Overview
About 480 wordsAbout 2 min
2025-02-04
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()