Computer-Use Agents API

io.github.hcompaiPublished by GitHub account hcompaiv1.0.0Updated Nov 9, 2026

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

VerifiedStreamable HTTPWeb executableBrowser AutomationAI & ML

Overview

AI-generated overview

Runs and manages H Company's hosted Computer-Use Agents, letting an assistant start tasks, follow sessions, steer them and read results.

What you can do
  • List the agents available to the caller, including public ones, and start a run on a named agent or a specific revision.
  • Poll a session for its answer or current snapshot, and send follow-up messages to a running session.
  • Cancel a session, or make it publicly readable and get a share link.
  • List, read and write files on a browser session's machine, such as downloads.
When to use it
Use it when you want an assistant to delegate web or desktop tasks to a hosted agent that has its own browser, and to collect, steer or share the results. Suited to one-shot research tasks as well as longer sessions you follow and redirect.
Requirements
Remote endpoint at agp.hcompany.ai over streamable HTTP. Requires an H Company API key sent as a bearer token in the Authorization header. The key is obtained from the provider's platform; the README also describes a Python SDK and CLI that read the key from an environment variable or a local config file.
Before you install
The API key is a billable credential for a hosted service, so treat it as a secret and expect usage costs. Sessions run on remote machines with their own browser and can read and write files there, and share_session makes a session publicly readable to anyone with the link. Follow-up messages and cancellation change a running session's behavior.

Installation

In SourceWeft

  1. Open Computer-Use Agents API in the dashboard and add it to a workspace.
  2. Connect Authorization token credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.hcompai%2Fhai-agents/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "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

Source: README.md at commit b7e682c

Tools

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.

Parameterstaskrequiredagentrequiredmax_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.

Parameterswaitsession_idrequired

list_agents

List Agents

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

Parameterspagesize

send_message

Send Message

Send a follow-up message to a running session.

Parametersmessagerequiredsession_idrequired

cancel_session

Cancel Session

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

Parameterssession_idrequired

share_session

Share Session

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

Parameterssession_idrequired

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.

Parameterspathname_aftersession_idrequiredmax_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.

Parameterspathrequiredsession_idrequired

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.

Parameterspathrequiredsession_idrequiredcontent_base64required

Version history

1
  1. v1.0.0LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts