本文档介绍 AgentFlow Sandbox 的 API 接口。

客户端 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	内部错误

快速参考

执行工具

# 异步
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()