RESTful API 参考文档

Lybic GUI 智能体的 RESTful API 服务器，提供类似于 gRPC 服务功能的 HTTP/REST 接口。

安装可选的 RESTful API 依赖：

pip install lybic-guiagents[restful]

运行服务器

使用 CLI 命令：

lybic-guiagent-restful

使用 Python 模块：

python -m gui_agents.restful_app

通过环境变量配置：

# 服务器配置
export RESTFUL_HOST=0.0.0.0
export RESTFUL_PORT=8080
export LOG_LEVEL=INFO

# Lybic 认证（如果请求中未提供，则使用默认值）
export LYBIC_API_KEY=your_api_key
export LYBIC_ORG_ID=your_org_id
export LYBIC_API_ENDPOINT=https://api.lybic.cn/

# 任务配置
export TASK_MAX_TASKS=5
export LOG_DIR=runtime

# 可选：启用 Prometheus 指标
export ENABLE_PROMETHEUS=true
export PROMETHEUS_PORT=8000

lybic-guiagent-restful

使用 Docker：

docker build -t lybic-guiagent .
docker run -p 8080:8080 \
  -e LYBIC_API_KEY=your_api_key \
  -e LYBIC_ORG_ID=your_org_id \
  lybic-guiagent /app/.venv/bin/lybic-guiagent-restful

API 接口

1. 获取智能体信息

GET /api/agent/info

返回服务器信息，包括版本号、最大并发任务数、日志级别和域名。

响应：

{
  "version": "0.7.6",
  "max_concurrent_tasks": 5,
  "log_level": "INFO",
  "domain": "hostname"
}

2. 运行智能体（流式传输）

POST /api/agent/run

使用 Server-Sent Events (SSE) 流式传输运行 Agent 任务，以实现实时进度更新。

请求体：

{
  "instruction": "打开计算器并计算 123 + 456",
  "sandbox_id": "optional-existing-sandbox-id",
  "max_steps": 50,
  "mode": "fast",
  "platform": "Windows",
  "shape": "beijing-2c-4g-cpu",
  "destroy_sandbox": false,
  "continue_context": false,
  "task_id": "optional-previous-task-id",
  "authentication": {
    "api_key": "your_api_key",
    "org_id": "your_org_id",
    "api_endpoint": "https://api.lybic.cn/"
  },
  "stage_model_config": {
    "grounding_model": {
      "model_name": "gpt-4o",
      "provider": "openai",
      "api_key": "sk-your-openai-key"
    },
    "action_generator_model": {
      "model_name": "claude-3-5-sonnet-20241022",
      "provider": "anthropic",
      "api_key": "sk-ant-your-anthropic-key"
    },
    "embedding_model": {
      "model_name": "text-embedding-3-large",
      "provider": "openai"
    }
  }
}

请求参数：

instruction（必填）：自然语言任务指令
sandbox_id（可选）：使用现有的沙箱 ID
max_steps（可选，默认：50）：执行的最大步数
mode（可选，默认："fast"）：Agent 模式 - "normal" 或 "fast"
platform（可选，默认："Windows"）：平台 - "Windows"、"Ubuntu" 或 "Android"
shape（可选，默认："beijing-2c-4g-cpu"）：沙箱规格/大小
destroy_sandbox（可选，默认：false）：完成后销毁沙箱
continue_context（可选，默认：false）：从先前任务继续上下文
task_id（可选）：用于上下文继续的先前任务 ID
authentication（可选）：Lybic 认证（如果未提供，则使用环境变量）
stage_model_config（可选）：针对不同 Agent 组件的阶段模型配置. 参考文档Model Support & Configuration Reference

响应（SSE 流）：

event: starting
data: {"task_id": "uuid", "stage": "starting", "message": "任务开始", "timestamp": 1234567890}

event: running
data: {"task_id": "uuid", "stage": "running", "message": "第 1 步...", "timestamp": 1234567891}

event: finished
data: {"task_id": "uuid", "stage": "finished", "message": "任务成功完成", "timestamp": 1234567892}

3. 提交任务（异步）

POST /api/agent/submit

异步提交任务，并立即返回任务 ID 以供后续状态查询。

请求体： 与 /api/agent/run 相同

响应：

{
  "task_id": "task-uuid",
  "status": "pending"
}

4. 获取任务状态

GET /api/agent/status?task_id={task_id}

查询已提交任务的状态。

响应：

{
  "task_id": "task-uuid",
  "status": "completed",
  "message": "任务完成状态：completed",
  "result": null,
  "sandbox": {
    "id": "sandbox-id",
    "shape_name": "beijing-2c-4g-cpu"
  },
  "execution_statistics": {
    "steps": 15,
    "duration_seconds": 45.2,
    "input_tokens": 1234,
    "output_tokens": 567,
    "total_tokens": 1801,
    "cost": 0.05,
    "currency_symbol": "￥"
  }
}

状态值：

pending：任务排队中
running：任务正在执行
completed：任务成功完成
failed：任务遇到错误
cancelled：任务已被取消

5. 取消任务

POST /api/agent/cancel

取消正在运行的任务。

请求体：

{
  "task_id": "task-uuid"
}

响应：

{
  "task_id": "task-uuid",
  "success": true,
  "message": "任务已成功取消"
}

6. 列出任务

GET /api/agent/tasks?limit=100&offset=0

分页列出所有任务。

查询参数：

limit（可选，默认：100）：返回的最大任务数
offset（可选，默认：0）：跳过的任务数

响应：

{
  "tasks": [
    {
      "task_id": "task-uuid-1",
      "status": "completed",
      "instruction": "打开计算器",
      "created_at": 1234567890.123,
      "final_state": "completed"
    }
  ],
  "total": 150,
  "limit": 100,
  "offset": 0
}

7. 创建沙箱

POST /api/sandbox/create

创建新的沙箱环境。

请求体：

{
  "name": "my-sandbox",
  "maxLifeSeconds": 3600,
  "projectId": "optional-project-id",
  "shape": "beijing-2c-4g-cpu",
  "authentication": {
    "api_key": "your_api_key",
    "org_id": "your_org_id",
    "api_endpoint": "https://api.lybic.cn/"
  }
}

响应：

{
  "sandbox_id": "sandbox-uuid",
  "shape": "beijing-2c-4g-cpu",
  "status": "created"
}

使用 stage_model_config 进行模型配置

stage_model_config 参数允许为 Agent 的不同组件配置不同的 LLM 模型。这提供了与 gRPC 服务器的 StageModelConfig 相同的功能。

支持的模型配置

stage_model_config 允许为 Agent 执行管道中的不同组件配置不同的 LLM 模型。每个组件在 Agent 的执行流程中具有特定用途,更多内容请参考文档Model Support & Configuration Reference：

配置字段	工具名称	用途	Agent 模式	推荐模型
`web_search_engine`	websearch	网络搜索引擎	Normal	`exa`、`ark`
`context_fusion_model`	context_fusion	融合多个来源的上下文	Normal	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro
`subtask_planner_model`	subtask_planner	将任务分解为子任务	Normal	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro
`traj_reflector_model`	traj_reflector	对执行轨迹进行反思	Normal	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro
`memory_retrival_model`	memory_retrival	检索相关记忆	Normal	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro
`grounding_model`	grounding	在截图中定位 UI 元素	Normal/Fast	Qwen-VL-Max, Doubao-1.5-UI-Tars, GPT-4o
`task_evaluator_model`	evaluator	评估任务完成情况	Normal	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro
`action_generator_model`	action_generator	生成动作（Normal 模式）	Normal	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro, DeepSeek-R1
`action_generator_with_takeover_model`	action_generator_with_takeover	生成带接管动作	Normal	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro
`fast_action_generator_model`	fast_action_generator	生成动作（Fast 模式）	Fast	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro
`fast_action_generator_with_takeover_model`	fast_action_generator_with_takeover	生成带接管动作（Fast）	Fast	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro
`dag_translator_model`	dag_translator	将任务翻译为 DAG	Normal	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro
`embedding_model`	embedding	生成文本嵌入	Normal/Fast	text-embedding-3-large, Gemini-Embedding, Jina-v4
`query_formulator_model`	query_formulator	制定搜索查询	Normal	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro
`narrative_summarization_model`	narrative_summarization	总结任务叙述	Normal	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro
`text_span_model`	text_span	提取文本片段	Normal	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro
`episode_summarization_model`	episode_summarization	总结片段	Normal	GPT-4o, Claude-3.5-Sonnet, Gemini-2.5-Pro

注意：

如果未提供特定配置，action_generator_model 将作为所有 LLM 工具（除 grounding_model 外）的默认配置。
在 Fast 模式 中，仅使用 grounding_model、embedding_model 和 fast_action_generator_model。
在 Normal 模式 中，根据任务复杂性可能使用所有组件。
您必须根据所选模式至少指定 action_generator_model 或 fast_action_generator_model，以及 grounding_model。

支持的模型提供商

有关支持的模型和提供商的详细信息，请参阅 gui_agents/tools/model.md。主要提供商包括：

OpenAI：gpt-4o, gpt-4.1, o1, o3-mini, text-embedding-3-large
Anthropic：claude-opus-4, claude-sonnet-4, claude-3-7-sonnet, claude-3-5-sonnet-20241022
Google Gemini：gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash, text-embedding-004
Alibaba Qwen：qwen-max-latest, qwen-vl-max-latest（grounding）, text-embedding-v4
ByteDance Doubao：doubao-1-5-ui-tars-250428（grounding）, doubao-seed-1-6-flash
DeepSeek：deepseek-chat, deepseek-reasoner
Zhipu GLM：GLM-4-Plus, GLM-4-AirX（grounding）, Embedding-3
xAI Grok：grok-3-beta, grok-beta
代理平台：Monica, OpenRouter（支持多个提供商）

LLM 配置字段

每个模型配置支持：

model_name（必填）：模型名称（例如 "gpt-4o"、"claude-3-5-sonnet-20241022"、"gemini-2.5-pro"）
provider（可选）：提供商名称（例如 "openai"、"anthropic"、"gemini"、"doubao"）
api_key（可选）：该模型的 API 密钥
api_endpoint（可选）：自定义 API 端点（适用于代理服务或自托管模型）

优势

为不同组件使用不同模型
每个模型或每个任务使用不同的 API 密钥
覆盖环境变量中的默认配置
支持多租户场景下的每用户 API 密钥
通过为非关键组件使用更便宜的模型进行成本优化

示例

示例 1：为不同组件使用不同模型

curl -X POST http://localhost:8080/api/agent/run \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "打开计算器并计算 123 + 456",
    "stage_model_config": {
      "grounding_model": {
        "model_name": "gpt-4o",
        "provider": "openai",
        "api_key": "sk-your-openai-key"
      },
      "action_generator_model": {
        "model_name": "claude-3-5-sonnet-20241022",
        "provider": "anthropic",
        "api_key": "sk-ant-your-anthropic-key"
      },
      "embedding_model": {
        "model_name": "text-embedding-3-large",
        "provider": "openai"
      }
    },
    "authentication": {
      "api_key": "your_lybic_api_key",
      "org_id": "your_lybic_org_id"
    }
  }'

示例 2：使用自定义端点

curl -X POST http://localhost:8080/api/agent/run \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "搜索最新的 AI 新闻",
    "stage_model_config": {
      "action_generator_model": {
        "model_name": "deepseek-chat",
        "provider": "openai",
        "api_key": "your-deepseek-key",
        "api_endpoint": "https://api.deepseek.com/v1"
      }
    },
    "authentication": {
      "api_key": "your_lybic_api_key",
      "org_id": "your_lybic_org_id"
    }
  }'

交互式 API 文档

服务器运行后，您可以访问：

Swagger UI：http://localhost:8080/docs
ReDoc：http://localhost:8080/redoc
OpenAPI JSON：http://localhost:8080/openapi.json

示例用法

Python 客户端示例：

import requests
import json
import time

# 服务器 URL
BASE_URL = "http://localhost:8080"

# 认证
auth = {
    "api_key": "your_lybic_api_key",
    "org_id": "your_lybic_org_id"
}

# 异步提交任务
response = requests.post(
    f"{BASE_URL}/api/agent/submit",
    json={
        "instruction": "打开记事本并输入 'Hello World'",
        "mode": "fast",
        "max_steps": 30,
        "authentication": auth,
        "stage_model_config": {  # 可选
            "action_generator_model": {
                "model_name": "gpt-4o",
                "api_key": "your_llm_api_key"
            }
        }
    }
)
task_data = response.json()
task_id = task_data["task_id"]
print(f"任务已提交: {task_id}")

# 轮询任务状态
while True:
    response = requests.get(f"{BASE_URL}/api/agent/status?task_id={task_id}")
    status_data = response.json()
    print(f"状态: {status_data['status']}")

    if status_data["status"] in ["completed", "failed", "cancelled"]:
        print(f"最终状态: {status_data}")
        if status_data.get("execution_statistics"):
            stats = status_data["execution_statistics"]
            print(f"执行步数: {stats['steps']}, 用时: {stats['duration_seconds']}秒")
            print(f"令牌使用: {stats['total_tokens']}, 费用: {stats['cost']} {stats['currency_symbol']}")
        break

    time.sleep(2)

流式传输示例：

import requests
import json

# SSE 流式传输
def stream_task(instruction):
    url = "http://localhost:8080/api/agent/run"
    data = {
        "instruction": instruction,
        "authentication": {
            "api_key": "your_api_key",
            "org_id": "your_org_id"
        }
    }

    response = requests.post(url, json=data, stream=True)

    for line in response.iter_lines():
        if line:
            line = line.decode('utf-8')
            if line.startswith('data:'):
                data = json.loads(line[5:])
                print(f"[{data['stage']}] {data['message']}")

stream_task("打开计算器并计算 10 + 20")

cURL 示例：

# 获取服务器信息
curl http://localhost:8080/api/agent/info

# 提交任务
curl -X POST http://localhost:8080/api/agent/submit \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "打开计算器",
    "authentication": {
      "api_key": "your_api_key",
      "org_id": "your_org_id"
    }
  }'

# 检查任务状态
curl "http://localhost:8080/api/agent/status?task_id=YOUR_TASK_ID"

# 取消任务
curl -X POST http://localhost:8080/api/agent/cancel \
  -H "Content-Type: application/json" \
  -d '{"task_id": "YOUR_TASK_ID"}'

# 列出所有任务
curl "http://localhost:8080/api/agent/tasks?limit=10"

与 gRPC 服务的比较

RESTful API 使用 HTTP/REST 提供与 gRPC 服务（grpc_app.py）类似的功能：

功能	RESTful API	gRPC 服务
协议	HTTP/REST	gRPC
流式传输	SSE (Server-Sent Events)	gRPC 流式传输
任务提交	POST /api/agent/submit	RunAgentInstructionAsync
任务状态	GET /api/agent/status	QueryTaskStatus
任务取消	POST /api/agent/cancel	CancelTask
Agent 信息	GET /api/agent/info	GetAgentInfo
模型配置	stage_model_config 参数	StageModelConfig protobuf
认证	请求体中的 JSON	AuthorizationInfo protobuf

性能考虑

RESTful API 使用与 gRPC 服务相同的底层 Agent 基础设施
SSE 流式传输提供类似于 gRPC 流式传输的近实时更新
对于高吞吐量场景，建议使用 gRPC 服务
服务器强制执行最大并发任务限制（默认：5，可通过 TASK_MAX_TASKS 配置）

监控

如果启用 Prometheus 指标：

指标暴露在端口 8000（可通过 PROMETHEUS_PORT 配置）
指标包括任务计数、执行时间、令牌使用和系统资源
与 gRPC 服务的指标兼容

错误处理

API 返回标准 HTTP 状态码：

200：成功
400：请求无效（参数错误）
404：资源未找到（任务 ID 不存在）
500：内部服务器错误
503：服务不可用（达到最大并发任务数）

错误响应包含 detail 字段，提供更多信息：

{
  "detail": "已达到最大并发任务数 (5)"
}

安全注意事项

API 密钥和认证凭据应妥善保管
生产环境中使用 HTTPS
考虑实现速率限制和认证中间件
ark_apikey 参数允许为多租户场景指定每请求 API 密钥
API 密钥不会被记录或在响应中暴露

故障排除

服务器无法启动

检查端口 8080 是否已被占用
确认所有依赖已安装：pip install lybic-guiagents[restful]
检查环境变量是否正确设置

任务立即失败

验证 Lybic 认证凭据是否正确
检查指定的平台/规格是否可用
查看 runtime/ 目录中的日志

流式传输不工作

确保 HTTP 客户端支持 Server-Sent Events (SSE)
检查防火墙/代理是否阻塞 SSE 连接
尝试使用异步提交端点代替

许可证

此 RESTful API 是 Lybic GUI Agent 项目的一部分，采用 Apache-2.0 许可证。

Restful API 服务器参考

RESTful API 参考文档

运行服务器

使用 CLI 命令：

使用 Python 模块：

通过环境变量配置：

使用 Docker：

API 接口

1. 获取智能体信息

2. 运行智能体（流式传输）

3. 提交任务（异步）

4. 获取任务状态

5. 取消任务

6. 列出任务

7. 创建沙箱

使用 stage_model_config 进行模型配置

支持的模型配置

支持的模型提供商

LLM 配置字段

优势

示例

交互式 API 文档

示例用法

Python 客户端示例：

流式传输示例：

cURL 示例：

与 gRPC 服务的比较

性能考虑

监控

错误处理

安全注意事项

故障排除

服务器无法启动

任务立即失败

流式传输不工作

许可证

本页内容