Computer-Use Agents API

H Company 的 Agents API Python SDK。

文档  ·  获取 API 密钥  ·  PyPI  ·  TypeScript SDK  ·  H Company

目录

• 安装
• 快速入门：命令行
• 快速入门：Python
• 命令行
• Python SDK 指南
• 文档

安装

pip install "hai-agents[cli]"   # SDK and the holo command
pip install hai-agents          # SDK only

需要 Python 3.10 或更高版本。

快速入门：命令行

pip install "hai-agents[cli]"
holo login
holo "What's the top story on Hacker News?"

holo login 会在浏览器中使用 Google 登录，也可以通过 holo login --key 使用你粘贴的密钥，并将其存储在 ~/.config/hai/.env 中。在终端中首次使用时，任何命令都会执行相同的操作，因此这一步是可选的。随后，任务会在托管 Agent 上运行，该 Agent 配有自己的浏览器：执行步骤会实时显示在终端中，最终答案会在结束时输出。在终端中，你可以继续使用同一会话，也可以单独运行 holo 来启动交互式会话。

快速入门：Python

在 platform.hcompany.ai/settings/api-keys 获取 API 密钥并导出，或运行一次 holo login：

export HAI_API_KEY=hk-...

启动内置的 h/web-surfer-pro Agent，它自带浏览器，然后用日常语言描述任务。run_session 会持续轮询，直到 Agent 完成任务并返回最终答案。

from hai_agents import Client

client = Client()

result = client.run_session(
    agent="h/web-surfer-pro",
    messages="What are the top 3 stories on Hacker News right now?",
)

print(result.status)
print(result.answer)

Client() 会从环境中读取 HAI_API_KEY；如果不存在，则读取 holo login 存储在 ~/.config/hai/.env 中的密钥。

result 是一个 SessionRunResult：包含 id、status、answer、累积的 events 和 final_changes。

命令行

cli 附加组件会安装 holo 命令，该命令也可以通过 hai 使用。

holo "What's the top story on Hacker News?"      # run one task
holo                                            # interactive session
holo -a h/web-surfer-pro "Compare 3 laptops"    # pick an agent for one run
holo agents use h/web-surfer-pro                # change the default agent
holo -a h/holo-desktop "Open Calculator"        # drive this machine's desktop
holo --local "Summarize news.ycombinator.com"   # run the agent loop on this machine
holo sessions watch <session-id>                # follow a running session
holo mcp install                                # add the MCP server to your editor

除非传入 --agent 或使用 holo agents use 设置默认值，否则任务会在 h/web-surfer-flash 上运行。运行 holo --help 或 holo <command> --help 查看所有选项。

~/.holo/agents.md 会合并到 holo 运行的每个 Agent 的指令中，~/.holo/skills/<name>/SKILL.md 会合并到其技能中。

交互式会话

在终端中运行 holo，即可开启一个可用日常语言交流的会话。在开始新会话之前，每条消息都会继续使用同一会话及其浏览器和上下文；输入 /new 可开启新会话。

按键	操作
输入内容后按回车	在 Agent 工作时向其发送消息
esc	暂停 Agent；再次按 esc 可恢复
/answer	要求 Agent 立即作答
/	列出命令：/new、/retry、/resume、/agent、/live、/share、/status、/copy
?	查看所有快捷键
ctrl+c	取消当前轮次；按两次退出

像 h/holo-desktop 这样操控此桌面的 Agent 会使用你的鼠标和键盘，因此输入内容会发送到你的应用中；在任何应用中连续按两次 esc 即可停止它。

命令

命令	功能
holo run <task>	运行一项任务；等同于 holo <task>
holo chat	开始交互式会话
holo sessions	list、status、watch、events、send、cancel、share 会话
holo agents	list Agent、get 一个 Agent、use 一个 Agent 作为默认 Agent
holo skills	浏览可用技能
holo mcp install	允许 Cursor、Claude Code、Codex 和其他 MCP 客户端通过 holo mcp 运行 Agent；--remote 则会添加托管服务
holo local	在本机为从其他位置启动的会话提供浏览器、桌面应用或工作站
holo login、logout、whoami、doctor	管理并检查凭据和设置

脚本和 CI

脚本不会提示输入内容。设置 HAI_API_KEY，或将密钥通过管道传给 holo login --key，然后使用 --json 获取机器可读输出，或使用 -q 仅输出答案：

holo --json run "What's the top story on Hacker News?" | jq -r .answer
holo run -q "What's the top story on Hacker News?" > answer.txt

--json 会输出 session_id、status、answer、outcome、error、error_code 和 agent_view_url。会话完成时退出代码为 0，否则为 1。

凭据按以下顺序解析：--api-key、HAI_API_KEY，然后是 ~/.config/hai/.env。

Python SDK 指南

会话的工作方式

会话是 Agent 针对一项任务的一次运行。它会经过一组有限的状态：pending、running，然后进入 completed、idle、failed、timed_out 或 interrupted 等终态。

你可以通过两种方式驱动会话。run_session 会创建会话并阻塞，直到会话进入终态，适用于一次性任务。start_session 会创建会话并立即返回句柄，让你在 Agent 工作时读取并引导它。

session = client.start_session(
    agent="h/web-surfer-pro",
    messages="Find the top story on Hacker News",
)

print(session.id)
result = session.wait_for_completion()
print(result.status, result.answer)

监视并引导正在运行的会话

绑定到会话 id 的句柄会提供完整的生命周期信息。你可以通过三个详细级别读取 Agent 的进度：

session.status()
session.changes(from_index=0)
session.get()

status() 会以较低开销返回快照，其中包含状态、步骤数和 Token 用量。changes(from_index=0) 会长轮询新事件和最终答案。get() 会返回完整的 Session 资源。

只要会话尚未进入终态，你就可以进行干预：

session.send_message({"type": "user_message", "message": "Only consider the last 24 hours"})
session.pause()
session.resume()
session.force_answer()
session.cancel()

send_message 会在 Agent 执行下一步时引导它，并唤醒处于 idle 状态的会话。pause 会暂停会话并保留状态，直到调用 resume。force_answer 会让 Agent 停止探索并根据现有信息作答。cancel 会以 interrupted 状态结束会话。

多轮会话

默认情况下，Agent 作答后会话立即结束。设置 idle_timeout_s 可使会话保持开启：每次作答后，会话进入 idle 状态，并在等待你的下一条消息期间保留完整上下文和浏览器状态，等待时长由该参数决定。

session = client.start_session(
    agent="h/web-surfer-pro",
    idle_timeout_s=600,
    messages="Find the top story on Hacker News",
)
first = session.wait_for_completion()

session.send_message({"type": "user_message", "message": "Now summarize its comments"})
second = session.wait_for_completion()

结构化输出

将 pydantic 模型作为 answer_schema 传入，Agent 的最终答案就会以经过验证的实例形式返回。该模型的 JSON schema 会作为 Agent 的答案格式发送；原始线上的值仍保留在 result.final_changes.answer 中。

from pydantic import BaseModel
from hai_agents import Client

class Job(BaseModel):
    title: str
    company: str

class Jobs(BaseModel):
    jobs: list[Job]

client = Client()
result = client.run_session(
    agent="h/web-surfer-pro",
    messages="Find 3 open ML engineering roles in Paris.",
    answer_schema=Jobs,
)

for job in result.answer.jobs:
    print(job.title, "@", job.company)

如果已完成的答案不符合 schema，就会引发 AnswerValidationError，原始负载可通过 .raw 获取。未完成即结束的会话会原样返回原始答案。

自定义工具

向 Agent 暴露你自己的 Python 函数。将这些函数传给 run_session，轮询循环会在 Agent 调用函数时运行它们，然后回传结果，让会话继续进行。任何带有类型化参数和文档字符串的函数都可用；输入 schema 会根据函数签名生成。

from hai_agents import Client

def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"Sunny in {city}"

client = Client()

result = client.run_session(
    agent="h/web-surfer-pro",
    messages="What should I wear in Paris today?",
    tools=[get_weather],
)

使用 @tool 装饰器可覆盖名称或描述：

from hai_agents import tool

@tool(name="lookup_order", description="Look up an order by its id.")
def lookup(order_id: str) -> dict:
    return {"id": order_id, "status": "shipped"}

如果工具引发异常，系统会将其作为工具错误报告给 Agent，而不会导致运行崩溃。使用 AsyncClient 时，工具可以是 async def。

预构建：一次性密码（2FA）

hai_agents_tools 提供开箱即用的工具。otp_tool 可让 Agent 在登录或注册步骤需要一次性密码、验证码或确认链接时请求这些信息。若没有处理器，它会在 stdin 中提示；imap_otp_handler 则通过 IMAP 直接从邮箱读取验证码（Gmail 用户请使用应用专用密码）。

import os

from hai_agents import Client
from hai_agents_tools import imap_otp_handler, otp_tool

handler = imap_otp_handler(
    host="imap.gmail.com",
    username="[email protected]",
    password=os.environ["GMAIL_APP_PASSWORD"],
)

client = Client()
result = client.run_session(
    agent="h/web-surfer-pro",
    messages="Log in to example.com and check for new notifications",
    tools=[otp_tool(handler)],
)

与所有自定义工具一样，处理器完全在你的进程中运行：IMAP 凭据不会离开你的设备，Agent 也只会收到提取出的单个验证码或链接，而不会收到邮箱内容。

浏览器配置和保险库

在已了解用户信息的浏览器上启动会话。浏览器配置可恢复之前会话中保存的 Cookie 和存储数据，保险库则让 Agent 使用不会进入其上下文的密钥登录网站。通过每次运行的覆盖选项绑定两者：

result = client.run_session(
    agent="h/web-surfer-pro",
    messages="Open my dashboard and report any new alerts",
    overrides={
        "agent.environments[kind=web].browser_profile_id": "<profile-id>",
        "agent.environments[kind=web].vault_id": "<vault-id>",
    },
)

异步

AsyncClient 为 asyncio 提供与 Client 相对应的接口。所有会话方法都是协程。

import asyncio
from hai_agents import AsyncClient

async def main():
    client = AsyncClient()
    result = await client.run_session(
        agent="h/web-surfer-pro",
        messages="What are the top 3 stories on Hacker News right now?",
    )
    print(result.answer)

asyncio.run(main())

本地 Agent

Client.local() 和 await AsyncClient.local() 通过本地 Agent 运行时在此设备上运行 Agent。该运行时会按需启动，也可以通过 runtime=... 传入。每个环境都可以选择 host="user_device" 或 host="cloud"。 Client() 仍使用托管的 Agents API。关闭客户端时，它会停止由其启动的运行时；但如果其他客户端仍有活动会话，则不会停止该运行时。

from hai_agents import Client

with Client.local(local_options={"binary_path": "/path/to/hai-agent-runtime"}) as client:
    session = client.sessions.create_session(
        agent={
            "name": "local-example",
            "description": "Local workstation example",
            "instructions": "Answer the user's task using the workstation tools.",
            "environments": [
                {"id": "workstation", "kind": "workstation", "host": "user_device"}
            ],
        },
        messages=[{"type": "user_message", "message": "Print hello using the shell."}],
        max_steps=8,
        max_time_s=120,
    )
    # Poll or steer the session here, before leaving the client context.

除非传入 inference=Inference.self_hosted(url, model=...)（from hai_agents_local.runtime import Inference），否则推理仍由托管服务提供（HAI_API_KEY）。

同一时间只能有一个 Agent 操作此设备的桌面：第二个请求 desktop 或 workstation 桥接的进程会立即失败，而不会共享鼠标。holo local stop 会停止此设备上的所有本地运行；启用 hai_agents_local.killswitch.arm_esc_listener() 后，连续按两次 Esc 也会停止运行（适用于 macOS、Windows 和 X11 Linux）。

检查和分享会话

列出过往会话并创建公开回放链接：

page = client.sessions.list_sessions(size=10)
for summary in page.items:
    print(summary.id, summary.status)

link = client.sessions.share_session("<session-id>")
print(link.share_url)

区域和配置

客户端默认使用 EU 区域；传入 environment 即可改用 US 区域：

from hai_agents import Client, HaiAgentsEnvironment

client = Client(environment=HaiAgentsEnvironment.US)

Client 也接受自定义 base_url；如果不想使用环境变量，还可以传入 api_key：

client = Client(base_url="https://agp.hcompany.ai", api_key="hk-...")

错误

from hai_agents import AnswerValidationError, UnprocessableEntityError
from hai_agents.core import ApiError

ApiError 是 HTTP 错误的基类，包含 .status_code 和 .body。请求未通过验证时会引发 UnprocessableEntityError（422）。完成的回答与 answer_schema 不匹配时会引发 AnswerValidationError，未解析的值可通过 .raw 获取。

Webhook

在信任收到的 Webhook 之前，先验证其签名：

from hai_agents import verify_webhook, WebhookVerificationError

event = verify_webhook(request_body, signature, timestamp, secret)
print(event.type, event.data)

文档

指南、核心概念和完整 API 参考请参阅 hub.hcompany.ai/agents-api。

许可证

MIT