GUI 智能体

Lybic GUI 智能体概述

Lybic 是一个开源框架和服务，用于创建电脑端使用和移动端使用智能体，这些智能体可以查看、推理并操作真实的 Windows、macOS、Linux 和 Android（沙箱）桌面。它集成了多个提供商 LLM 编排、视觉定位（UI-TARS）、动作规划、记忆、可观测性和可选的持久化。

核心能力：

跨平台 GUI 控制：本地后端（pyautogui*）或远程 Lybic 沙箱
通过可配置的工具编排图，接入多种模型提供方（OpenAI、Anthropic、Gemini、Doubao 等）
支持 Fast / Normal 执行模式、接管（Human-in-the-loop）、基准测试（OSWorld）以及 Prometheus 指标
提供 gRPC 服务模式，并可选使用 PostgreSQL 进行任务存储

安装

从 PyPI：

pip install lybic-guiagents

从源码（UV）：

git clone git@github.com:lybic/agent.git
cd agent
curl -LsSf https://astral.sh/uv/0.8.5/install.sh | sh
uv sync
source .venv/bin/activate
uv pip install -e .

如果 Windows 编码错误：在安装前设置 PYTHONUTF8=1。

pyproject.toml 可选依赖项说明

Agentic lybic 的默认依赖仅包含核心功能（Lybic 后端与交互式 CLI 智能体）。以下为可选依赖，用于启用额外的后端支持或特定功能：

[project.optional-dependencies]
dev=[]
all=[]
pyautogui=[]
vmware-and-evaluation=[]
restful=[]
mcp=[]
grpc=[]
prometheus=[]
postgres=[]

依赖项	说明
dev	本地开发和测试相关依赖项
pyautogui	(后端)启用本地桌面自动化后端
vmware-and-evaluation	(后端)启用 VMware 后端和 Osworld评估工具
restful	(服务)启用 agentic lybic RESTful API server 服务器支持
mcp	(服务)启用 agentic lybic Mcp(Model Context Protocol) server 服务器支持
grpc	(服务)启用 agentic lybic gRPC server服务器支持
prometheus	(特性)对于`Agent服务器`启用 Prometheus 指标支持
postgres	(特性)对于`Agent服务器`启用 PostgreSQL 记忆、持久化数据的存储支持

基本配置

模型凭证映射

您需要在 .env 中填写的API 密钥,取决于您的 tools_config.json 引用哪些模型提供方。

每个tool配置项都包含 provider 和 model_name；如果出现提供商（例如 doubao、gemini、anthropic、openai），则必须在 .env.example 中填写其对应的 API 密钥。
如果您切换到英文版工具配置（tools_config_en.json），请确按需提供对应提供商的密钥（例如 GEMINI_API_KEY、ARK_API_KEY、ANTHROPIC_API_KEY、OPENAI_API_KEY）。
中文配置（tools_config_cn.json）在所有工具使用 Doubao 的情况下，可能只需要 ARK_API_KEY。
未使用的提供商密钥可以留空或删除；只有在某个工具阶段被引用时才是必需的，否则不需要它们。请参考 gui_agents/tools/model.md 获取完整的提供商列表和支持的模型。编辑 tools_config.json 后，请确认其中所有 provider 都能在您的环境变量中找到对应的凭证。

复制env示例文件并添加所需的密钥：

cp gui_agents/.env.example gui_agents/.env
# 编辑 .env 并添加提供商密钥

选择工具配置（英文 vs 中文）：

cp gui_agents/tools/tools_config_en.json gui_agents/tools/tools_config.json
# 或
cp gui_agents/tools/tools_config_cn.json gui_agents/tools/tools_config.json

CLI 使用

交互式（Lybic 沙箱后端）：

python gui_agents/cli_app.py --backend lybic

本地快速模式：

python gui_agents/cli_app.py --backend pyautogui --mode fast

单次查询，限制 20 步：

python gui_agents/cli_app.py --backend pyautogui --query "Find the result of 8 × 7 on a calculator" --max-steps 20

重要选项：

--backend [lybic|lybic_mobile|pyautogui|pyautogui_vmware]
--max-steps N
--mode [normal|fast]
--enable-takeover
--disable-search

警告：pyautogui 后端将直接控制您的本地计算机。

Docker

docker run --rm -it --env-file gui_agents/.env agenticlybic/guiagent --backend lybic

沙箱变量

LYBIC_API_KEY=your_key
LYBIC_ORG_ID=your_org
LYBIC_MAX_LIFE_SECONDS=3600
# 可选预创建沙箱
LYBIC_PRECREATE_SID=SBX-XXXXXXXXXXXXXXX

Python 库快速开始

from gui_agents import AgentService
service = AgentService()
result = service.execute_task("Take a screenshot")
print(result.status)

核心组件：AgentService（高级）、AgentS2 / AgentSFast（实现）、HardwareInterface、ServiceConfig。

gRPC 服务器

对于完整文档和生产部署说明，请参阅 gRPC 服务器文档。

运行服务器（端口 50051）：

docker run --rm -it -p 50051:50051 --env-file gui_agents/.env agenticlybic/guiagent /app/.venv/bin/lybic-guiagent-grpc

启用 Prometheus 指标：

docker run --rm -it \
  -p 50051:50051 -p 8000:8000 \
  -e ENABLE_PROMETHEUS=true -e PROMETHEUS_PORT=8000 \
  --env-file gui_agents/.env \
  agenticlybic/guiagent /app/.venv/bin/lybic-guiagent-grpc

Python 异步客户端：

import asyncio, grpc
from gui_agents.proto.pb import agent_pb2, agent_pb2_grpc

async def main():
    async with grpc.aio.insecure_channel('localhost:50051') as channel:
        stub = agent_pb2_grpc.AgentStub(channel)
        req = agent_pb2.RunAgentInstructionRequest(instruction="Open a calculator and compute 1 + 1")
        async for resp in stub.RunAgentInstruction(req):
            print(f"[{resp.stage}] {resp.message}")

asyncio.run(main())

生成 protobuf 存根（如果在本地开发）：

python -m grpc_tools.protoc -Igui_agents/proto \
  --python_out=gui_agents/proto/pb \
  --grpc_python_out=gui_agents/proto/pb \
  --pyi_out=gui_agents/proto/pb gui_agents/proto/agent.proto

持久化（可选）

pip install lybic-guiagents[postgres]
# 或 uv pip install .[postgres]
TASK_STORAGE_BACKEND=postgres
POSTGRES_CONNECTION_STRING=postgresql://user:password@host:port/dbname

VMware 后端（可选）

设置 VMware，下载操作系统镜像，解压到 vmware_vm_data/Windows-x86 和 vmware_vm_data/Ubuntu-x86，然后：

USE_PRECREATE_VM=Ubuntu

故障排查要点

缺少 API 密钥：验证 .env 文件及环境变量是否正确配置。
编码错误（Windows）：设置 PYTHONUTF8=1。
定位（Grounding）缓慢：使用推荐的模型；或者尝试 --mode fast。
沙箱相关问题：检查 LYBIC_API_KEY/ORG_ID 和生命周期相关的环境变量。

下一步

尝试体验中心（仅限中国大陆）
将 GUI 智能体附加到 MCP 服务器会话
与 Lybic SDK 集成以实现自动化沙箱生命周期

本页内容