Computer-Use Agents API

io.github.hcompai由 GitHub 账号 hcompai 发布v1.0.0更新于 Nov 9, 2026

Run and manage H Company's Computer-Use Agents from any MCP client.

已验证Streamable HTTP可网页运行浏览器自动化AI 与机器学习

概览

AI 生成的概览

运行并管理 H Company 托管的 Computer-Use Agents,让助手启动任务、跟踪会话、干预执行并获取结果。

可以做什么
  • 列出调用者可用的代理(含公开代理),并按名称或指定版本启动一次运行。
  • 轮询会话以获取答案或当前快照,并向运行中的会话发送后续消息。
  • 取消会话,或将会话设为公开可读并取得分享链接。
  • 列出、读取和写入浏览器会话机器上的文件,例如下载目录。
适用场景
适合把网页或桌面任务交给带自有浏览器的托管代理执行,并收集、干预或分享结果。既可用于一次性调研任务,也可用于需要持续跟进和调整的较长会话。
运行要求
通过 streamable HTTP 连接 agp.hcompany.ai 远程端点。需要 H Company API 密钥,以 bearer 形式放在 Authorization 请求头中。密钥需在提供方平台获取;README 还介绍了从环境变量或本地配置文件读取密钥的 Python SDK 与命令行工具。
安装前请注意
该 API 密钥是托管服务的计费凭据,应作为机密保管,并预期产生使用费用。会话在带浏览器的远程机器上运行,可读写其中的文件;share_session 会让会话对任何持有链接的人公开可读。发送后续消息和取消操作会改变运行中会话的行为。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Computer-Use Agents API,将其添加到工作区。
  2. 连接 Authorization token 凭据。它们会被私密存储,绝不会在公开页面上展示。
  3. 为需要使用其工具的对话启用该服务。

Web executable,通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体,或 SourceWeft 对话中。智能体会读取该服务器的安装指南,先向你展示发布者、端点和登录方式,经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.hcompai%2Fhai-agents/install.md,并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前,先告诉我它的发布者、端点和登录方式,等我确认。不要把 API 密钥写进命令或我会提交的文件;问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "mcpServers": {
    "computer-use-agents-api": {
      "type": "http",
      "url": "https://agp.hcompany.ai/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

README

[Agents API]

[PyPI] [Python versions] [License: MIT]

Python SDK for H Company's Agents API.

Documentation  ·  Get an API key  ·  PyPI  ·  TypeScript SDK  ·  H Company

Contents

Installation

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

Python 3.10 or newer is required.

Quickstart: command line

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

holo login signs you in with Google in the browser, or takes a key you paste with holo login --key, and stores it in ~/.config/hai/.env. Any command does the same on first use in a terminal, so this step is optional. The task then runs on a hosted agent with its own browser: its steps stream to your terminal, and its answer prints at the end. In a terminal you can follow up on the same session, or run holo alone to start an interactive session.

Quickstart: Python

Get an API key at platform.hcompany.ai/settings/api-keys and export it, or run holo login once:

bash
export HAI_API_KEY=hk-...

Launch the built-in h/web-surfer-pro agent, which ships with its own browser, and describe the task in plain language. run_session polls until the agent finishes and returns the final answer.

python
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() reads HAI_API_KEY from the environment, else the key holo login stored in ~/.config/hai/.env.

result is a SessionRunResult: id, status, answer, the accumulated events, and final_changes.

Command line

The cli extra installs the holo command, also available as hai.

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

Tasks run on h/web-surfer-flash unless you pass --agent or set a default with holo agents use. Run holo --help, or holo <command> --help, for every option.

~/.holo/agents.md joins the instructions of every agent holo runs, and ~/.holo/skills/<name>/SKILL.md joins its skills.

Interactive sessions

holo in a terminal opens a session you talk to in plain words. Each message continues the same session, with its browser and context, until you start fresh with /new.

KeyAction
type, then entermessage the agent while it works
escpause the agent; esc again resumes
/answerask the agent to answer now
/list commands: /new, /retry, /resume, /agent, /live, /share, /status, /copy
?all shortcuts
ctrl+ccancel the turn; twice to exit

An agent that drives this desktop, like h/holo-desktop, uses your mouse and keyboard, so typing goes to your apps instead: press esc twice, from any app, to stop it.

Commands

CommandWhat it does
holo run <task>run one task; same as holo <task>
holo chatstart an interactive session
holo sessionslist, status, watch, events, send, cancel, share sessions
holo agentslist agents, get one, use one as the default
holo skillsbrowse available skills
holo mcp installlet Cursor, Claude Code, Codex, and other MCP clients run agents through holo mcp; --remote adds the hosted server instead
holo localserve a browser or desktop on this machine for a session started elsewhere
holo login, logout, whoami, doctormanage and check your credentials and setup

Scripts and CI

Scripts never prompt. Set HAI_API_KEY, or pipe a key into holo login --key, then use --json for machine-readable output or -q for the answer alone:

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

--json prints session_id, status, answer, outcome, error, error_code, and agent_view_url. The exit code is 0 when the session completes and 1 otherwise.

Credentials resolve from --api-key, then HAI_API_KEY, then ~/.config/hai/.env.

Python SDK guides

How a session works

A session is one run of an agent against a task. It moves through a small set of states: pending, running, and then a settled state such as completed, idle, failed, timed_out, or interrupted.

You drive a session two ways. run_session creates it and blocks until it settles, which suits one-shot tasks. start_session creates it and returns a handle right away, so you can read and steer the agent while it works.

python
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)

Watch and steer a running session

A handle bound to the session id exposes the full lifecycle. Read the agent's progress at three levels of detail:

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

status() is a cheap snapshot with the state, step count, and token usage. changes(from_index=0) long-polls for new events and the final answer. get() returns the full Session resource.

While the session is not in a terminal state, you can intervene:

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

send_message redirects the agent on its next step and wakes an idle session. pause halts with state preserved until resume. force_answer makes the agent stop exploring and answer from what it has. cancel ends the session as interrupted.

Multi-turn sessions

By default a session ends as soon as the agent answers. Set idle_timeout_s to keep it open: after each answer the session goes idle and waits that long for your next message, carrying its full context and browser state across turns.

python
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()

Structured output

Pass a pydantic model as answer_schema and the agent's final answer comes back as a validated instance. The model's JSON schema is sent as the agent's answer format; the raw wire value stays at result.final_changes.answer.

python
from pydantic import BaseModelfrom 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)

A completed answer that does not match the schema raises AnswerValidationError, with the raw payload on .raw. Sessions that end without completing return their raw answer untouched.

Custom tools

Expose your own Python functions to the agent. Pass them to run_session and the polling loop runs each one when the agent calls it, then posts the result back so the session continues. Any function with typed parameters and a docstring works; the input schema is derived from the signature.

python
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],)

Use the @tool decorator to override the name or description:

python
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"}

A tool that raises is reported to the agent as a tool error rather than crashing the run. With AsyncClient, tools may be async def.

Prebuilt: one-time passwords (2FA)

hai_agents_tools ships ready-made tools. otp_tool lets the agent ask for a one-time password, verification code, or confirmation link when a login or signup step needs one. Without a handler it prompts on stdin; imap_otp_handler reads the code straight from a mailbox over IMAP (for Gmail, use an app password).

python
import os
from hai_agents import Clientfrom 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)],)

Like every custom tool, the handler runs entirely in your process: the IMAP credentials never leave your machine, and the agent only receives the single extracted code or link -- never mailbox contents.

Browser profiles and vaults

Start a session on a browser that already knows the user. A browser profile restores saved cookies and storage from an earlier session, and a vault lets the agent sign in to sites with secrets that never enter its context. Bind both through per-run overrides:

python
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>",    },)

Async

AsyncClient mirrors Client for asyncio. Every session method is a coroutine.

python
import asynciofrom 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())

Local agents

Client.local() and await AsyncClient.local() run the agent on this machine through a local agent runtime, started on demand or passed in with runtime=.... A desktop is this machine; a browser picks host="user_device" or host="cloud". Client() keeps using the hosted Agents API. Closing the client stops a runtime it started, unless other clients still have active sessions there.

python
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 desktop example",            "instructions": "Answer the user's task on this desktop.",            "environments": [{"id": "my-laptop", "kind": "desktop"}],        },        messages=[{"type": "user_message", "message": "Open the Calculator app."}],        max_steps=8,        max_time_s=120,    )    # Poll or steer the session here, before leaving the client context.

Inference stays hosted (HAI_API_KEY) unless you pass inference=Inference.self_hosted(url, model=...) (from hai_agents_local.runtime import Inference).

One agent drives this machine's desktop at a time: a second process asking for a desktop bridge fails fast instead of sharing the mouse. holo local stop stops every local turn on the machine; so does a double Esc once hai_agents_local.killswitch.arm_esc_listener() is armed (macOS, Windows, and X11 Linux).

Code on this machine

A desktop in shell mode gives the agent a shell on this machine. It runs commands, edits files and writes code in a folder, and drives the screen from the same shell when a result only shows in a window.

bash
pip install "hai-agents[cli,workstation]"
python
from hai_agents import Client
Client().agents.create_agent(    name="laptop-coder",    description="Runs commands and edits files on my machine.",    environments=[{"id": "my-laptop", "kind": "desktop", "mode": {"type": "shell", "command_approval": "required"}}],)
bash
cd ~/Projects/appHAI_SHELL_WORKSPACE=. holo -a laptop-coder "Run the tests and fix the one that fails"

Without HAI_SHELL_WORKSPACE the agent works in a folder of its own, ~/hai/<session id>. With command_approval: "required", holo asks before each command your allowlist does not cover: y runs it, a runs it and always allows it, n refuses. From code, read result.pending_approvals and answer with session.approve(call_id) or session.deny(call_id, message).

On macOS every command runs inside Anthropic's sandbox-runtime, downloaded on the first session: it writes in the workspace only, reaches the Python and npm registries, and cannot read your credentials. On Linux and Windows the sandbox is off until you install it. The guide covers both.

Inspect and share sessions

List past sessions and create a public replay link:

python
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)

Regions and configuration

The client targets the EU region by default; pass environment to use the US region instead:

python
from hai_agents import Client, HaiAgentsEnvironment
client = Client(environment=HaiAgentsEnvironment.US)

Client also accepts a custom base_url, and an api_key when you do not want to use the environment variable:

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

Errors

python
from hai_agents import AnswerValidationError, UnprocessableEntityErrorfrom hai_agents.core import ApiError

ApiError is the base for HTTP failures and carries .status_code and .body. UnprocessableEntityError is the 422 raised when a request fails validation. AnswerValidationError is raised when a completed answer does not match answer_schema, with the unparsed value on .raw.

Webhooks

Verify the signature on an incoming webhook before trusting it:

python
from hai_agents import verify_webhook, WebhookVerificationError
event = verify_webhook(request_body, signature, timestamp, secret)print(event.type, event.data)

Documentation

Guides, core concepts, and the full API reference live at hub.hcompany.ai/agents-api.

License

MIT

来源:README.md,提交 b7e682c

工具

9

run_agent

Run Agent

Start an agent on a task; return the answer or a session handle to wait on. ``agent`` is a name from list_agents, which runs its latest revision, or ``name:N`` to run revision N.

输入参数task必填agent必填max_stepsmax_time_sidempotency_key

wait_for_session

Wait For Session

Poll a session: with ``wait`` long-poll for the answer, else return the current snapshot.

输入参数waitsession_id必填

list_agents

List Agents

List agents the caller can run: their org's agents plus the public ``h/`` ones.

输入参数pagesize

send_message

Send Message

Send a follow-up message to a running session.

输入参数message必填session_id必填

cancel_session

Cancel Session

Cancel a session; a no-op if it does not exist or already finished.

输入参数session_id必填

share_session

Share Session

Make a session publicly readable and return its absolute share URL.

输入参数session_id必填

list_files

List Files

List files on a browser session's machine (e.g. downloads), newest first. ``session_id`` is the browser session id issued by env-manager when the session was created, not the id ``run_agent`` returns. When a listing is truncated, page on the last entry's modified_at (ISO-8601) and name, passed as modified_before and name_after. Send both: modification times are not unique, and a timestamp alone skips the rest of a tied group.

输入参数pathname_aftersession_id必填max_entriesmodified_before

read_file

Read File

Read a file from a browser session's machine; returns base64 content and metadata. ``session_id`` is the browser session id issued by env-manager when the session was created, not the id ``run_agent`` returns.

输入参数path必填session_id必填

write_file

Write File

Write base64-encoded content to a file on a browser session's machine. ``session_id`` is the browser session id issued by env-manager when the session was created, not the id ``run_agent`` returns.

输入参数path必填session_id必填content_base64必填

版本历史

1
  1. v1.0.0最新Sep 16, 2026

评分

已满足适用检查项的 100%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分
  • 已声明认证方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分