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 分