本文档介绍 AgentFlow 的 API 接口，涵盖三大核心模块：Sandbox、Rollout 和 Synthesis。

Synthesis API

synthesize()

一站式数据合成入口。

from synthesis import synthesize

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

load_config() / load_seeds()

分步加载配置和种子数据。

from synthesis import load_config, load_seeds

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

主要函数:

函数	说明
synthesize(config_path, seeds)	运行完整合成流水线
load_config(config_path)	加载 SynthesisConfig 配置
load_seeds(seeds_or_path)	加载种子数据（支持文件路径、字符串列表、字典列表）

Rollout API

rollout()

一站式推理评测入口。

from rollout import rollout

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

quick_rollout()

无需配置文件的单问题快速推理。

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

分步加载配置和任务数据。

from rollout import load_config, load_tasks

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

主要函数:

函数	说明
rollout(config_path, ...)	运行推理和评测流水线
quick_rollout(question, ...)	单问题快速推理
load_config(config_path)	加载 RolloutConfig 配置
load_tasks(tasks_or_path)	加载 Benchmark 任务数据

Sandbox 客户端 API

Sandbox 类

Sandbox 是用户交互的主要入口类。

from sandbox import Sandbox

# 创建实例
sandbox = Sandbox(
    server_url="http://127.0.0.1:18890",
    worker_id="my_worker",
    auto_start_server=True
)

主要方法:

方法	说明
start()	启动连接
close()	关闭连接
warmup(resources)	预热后端
create_session(resource, config)	创建 Session
destroy_session(resource)	销毁 Session
execute(action, params)	执行工具
list_sessions()	列出 Session
get_status()	获取状态

HTTPServiceClient 类

底层 HTTP 客户端，用于高级用法。

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)

服务端 API

HTTP 端点

端点	方法	说明
/execute	POST	执行工具
/execute/batch	POST	批量执行
/session/create	POST	创建 Session
/session/destroy	POST	销毁 Session
/session/list	POST	列出 Session
/session/refresh	POST	刷新 Session
/tools	GET	列出工具
/health	GET	健康检查
/warmup	POST	预热后端
/warmup/status	GET	预热状态
/shutdown	POST	关闭服务器

响应格式

标准响应格式：

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

错误码

错误码	说明
0	成功
1001	工具未找到
1002	参数错误
1003	Session 错误
2001	后端错误
2002	超时
5000	内部错误

快速参考

数据合成

from synthesis import synthesize

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

推理评测

from rollout import rollout

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

执行工具

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

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

Session 管理

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

# 销毁
await sandbox.destroy_session("vm")

# 列出
sessions = await sandbox.list_sessions()

预热

# 预热指定后端
await sandbox.warmup(["rag", "vm"])

# 获取预热状态
status = await sandbox.get_warmup_status()