Agent-S 安装使用教程

🚀 项目介绍

Agent-S 是由 Simular AI 开发的开源框架，让 AI 能够像人类一样操作电脑。它可以：

自动点击鼠标 - 识别屏幕元素并精准点击
自动敲键盘 - 输入文字、执行快捷键
自主思考决策 - 根据任务目标规划操作步骤
执行复杂任务 - 浏览网页、编辑文档、整理文件等

🏆

首个超越人类！Agent-S 在 OSWorld 基准测试中达到 72.60% 的成功率，首次超越人类水平。

项目信息	详情
GitHub 地址	github.com/simular-ai/Agent-S
支持平台	Windows / macOS / Linux
开源协议	Apache 2.0
Star 数量	9.4K+

📋 环境要求

在安装之前，请确保您的电脑满足以下条件：

要求	说明
操作系统	Windows 10+、macOS 10.15+、Ubuntu 20.04+
Python	3.8 或更高版本
Git	用于克隆代码仓库
API 密钥	OpenAI / Anthropic / Hugging Face（至少一个）

⚠️

Linux 用户注意：建议直接在系统环境下操作，避免使用 conda 环境，因为可能与 pyatspi 库产生冲突。

⚙️ 安装步骤

克隆代码仓库

打开终端（Windows 用户可使用 Git Bash 或 PowerShell），执行以下命令：

bash

git clone https://github.com/simular-ai/Agent-S.git
cd Agent-S

创建虚拟环境（推荐）

为了避免依赖冲突，建议创建独立的虚拟环境：

bash

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate

# macOS / Linux:
source venv/bin/activate

安装依赖包

使用 pip 安装项目所需的依赖：

bash

pip install -r requirements.txt

或者直接安装 gui-agents 包：

bash

pip install gui-agents

💡

提示：如果安装过程中遇到权限问题，可以在命令前添加 sudo（Linux/macOS）或以管理员身份运行终端（Windows）。

🔑 配置 API 密钥

Agent-S 需要调用大语言模型 API 来实现智能决策。您需要至少配置以下一个 API 密钥：

获取 API 密钥

服务商	获取地址	推荐模型
OpenAI	platform.openai.com	GPT-4o
Anthropic	console.anthropic.com	Claude 3.5 Sonnet
Hugging Face	huggingface.co	开源模型

设置环境变量

方法一：临时设置（当前终端有效）

PowerShell

$env:OPENAI_API_KEY="sk-your-api-key-here"
$env:ANTHROPIC_API_KEY="sk-ant-your-api-key-here"

方法二：永久设置

按 Win + X，选择「系统」
点击「高级系统设置」→「环境变量」
在「用户变量」中点击「新建」
添加 OPENAI_API_KEY 和对应的值

编辑 shell 配置文件：

bash

# 编辑配置文件（zsh 用户）
nano ~/.zshrc

# 在文件末尾添加：
export OPENAI_API_KEY="sk-your-api-key-here"
export ANTHROPIC_API_KEY="sk-ant-your-api-key-here"

# 保存后使配置生效
source ~/.zshrc

💻 命令行使用

安装完成后，您可以通过 gui-agents 命令来启动 Agent-S：

基本用法

bash

gui-agents --instruction "打开计算器，计算 123 乘以 456"

指定模型

bash

# 使用 GPT-4o
gui-agents --instruction "在浏览器中搜索今天的天气" --model "gpt-4o"

# 使用 Claude 3.5 Sonnet
gui-agents --instruction "帮我关闭 VS Code" --model "claude-3-5-sonnet-20240620"

任务示例

任务类型	示例指令
应用操作	`"打开记事本，写入 Hello World 并保存"`
网页浏览	`"打开浏览器，搜索 Python 教程"`
文件管理	`"创建一个名为 test 的文件夹"`
复杂任务	`"打开 Excel，创建一个包含姓名和年龄的表格"`

⚠️

安全提醒：Agent-S 会直接在您的电脑上执行操作。请确保在安全可控的环境下运行，并时刻监控其行为，避免执行危险操作。

🔧 SDK 开发集成

如果您希望将 Agent-S 集成到自己的应用中，可以使用 Python SDK：

python

import os
from gui_agents.s2 import AgentS2
from gui_agents.acis.os_world_aci import OSWorldACI

# 1. 定义模型参数
# 主智能体使用 GPT-4o
engine_params = {
    "provider": "openai",
    "model": "gpt-4o",
    "temperature": 0.0,
}

# 接地模型使用 Claude (用于将指令转换为代码)
grounding_params = {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-20240620",
    "temperature": 0.0,
}

# 2. 初始化智能体
agent = AgentS2(
    engine_params=engine_params,
    grounding_params=grounding_params,
    aci=OSWorldACI(),
)

# 3. 执行任务
instruction = "打开计算器，计算 123 乘以 456"
agent.run(instruction)

核心类说明

类名	说明
`AgentS2`	Agent-S 第二代智能体，支持更复杂的任务规划
`OSWorldACI`	操作系统交互接口，提供屏幕识别和操作能力
`engine_params`	主推理模型配置，负责任务规划和决策
`grounding_params`	接地模型配置，负责将指令转换为具体操作

❓ 常见问题

Q1: 安装时提示 pip 找不到包？

确保您使用的是 Python 3.8+ 版本，并且已激活正确的虚拟环境。可以使用 python --version 检查版本。

Q2: 运行时提示 API Key 未配置？

请检查环境变量是否正确设置。可以使用以下命令验证：

bash

# macOS / Linux
echo $OPENAI_API_KEY

# Windows PowerShell
echo $env:OPENAI_API_KEY

Q3: Linux 上运行报错 pyatspi 相关错误？

这通常是因为在 conda 环境中运行导致的。请退出 conda 环境，直接在系统 Python 环境中安装和运行。

Q4: Agent-S 操作速度很慢？

这可能是因为：

网络延迟导致 API 调用较慢
任务过于复杂，需要多步规划
可以尝试使用更快的模型（如 GPT-4o-mini）

🚀 项目介绍

📋 环境要求

⚙️ 安装步骤

克隆代码仓库

创建虚拟环境（推荐）

安装依赖包

🔑 配置 API 密钥

获取 API 密钥

设置环境变量

💻 命令行使用

基本用法

指定模型

任务示例

🔧 SDK 开发集成

核心类说明

❓ 常见问题

Q1: 安装时提示 pip 找不到包？

Q2: 运行时提示 API Key 未配置？

Q3: Linux 上运行报错 pyatspi 相关错误？

Q4: Agent-S 操作速度很慢？

Q5: 如何停止正在运行的任务？