Computer-Use Agents API

H Company の Agents API 用 Python SDK です。

ドキュメント  ·  API キーを取得  ·  PyPI  ·  TypeScript SDK  ·  H Company

インストール

pip install hai-agents

cli エクストラを指定して、オプションのコマンドラインツールを追加します。

pip install "hai-agents[cli]"

Python 3.10 以降が必要です。platform.hcompany.ai/settings/api-keys で API キーを取得し、環境変数に設定します。

export HAI_API_KEY=hk-...

代わりに cli エクストラを使うと、hai login でキーを一度保存でき、Client() がそのキーを読み込みます。

クイックスタート

独自のブラウザーが付属する組み込みエージェント h/web-surfer-pro を起動し、タスクを自然言語で説明します。run_session はエージェントが完了するまでポーリングし、最終回答を返します。

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 を読み込みます。環境変数が設定されていない場合は、hai login で ~/.config/hai/.env に保存したキーを読み込みます。

result は SessionRunResult です。id、status、answer、蓄積された events、および final_changes が含まれます。

ローカルエージェント

Client.local() と await AsyncClient.local() は、オンデマンドで起動するか 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）。

このマシンのデスクトップを操作できるエージェントは一度に1つだけです。2つ目のプロセスが desktop または workstation ブリッジを要求すると、マウスを共有せず、すぐに失敗します。hai local stop はマシン上のすべてのローカル実行を停止します。また、hai_agents_local.killswitch.arm_esc_listener() を有効にすると、Esc キーを2回押しても停止できます（macOS、Windows、X11 の Linux）。

セッションの仕組み

セッションとは、タスクに対してエージェントを1回実行することです。状態は pending、running の順に進み、その後 completed、idle、failed、timed_out、interrupted などの確定状態になります。

セッションの操作方法は2通りあります。run_session はセッションを作成し、確定するまでブロックするため、単発のタスクに適しています。start_session はセッションを作成してすぐにハンドルを返すため、エージェントの作業中に状況を確認したり、指示を与えたりできます。

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 にバインドされたハンドルから、ライフサイクル全体を操作できます。エージェントの進行状況を、詳細度の異なる 3 つのレベルで確認できます。

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

status() は、状態、ステップ数、トークン使用量を含む軽量なスナップショットを返します。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 は次のステップでエージェントの動作を変更し、idle 状態のセッションを再開します。pause は状態を保持したまま一時停止し、resume するまで停止します。force_answer はエージェントに探索をやめ、手元にある情報で回答するよう指示します。cancel はセッションを interrupted 状態で終了します。

マルチターンセッション

デフォルトでは、エージェントが回答するとすぐにセッションは終了します。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 として渡すと、エージェントの最終回答が検証済みインスタンスとして返されます。モデルの JSON スキーマはエージェントの回答形式として送信されます。ワイヤー上の生の値は 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)

スキーマに一致しない完了済みの回答では、.raw に生のペイロードを含む AnswerValidationError が発生します。完了せずに終了したセッションでは、生の回答がそのまま返されます。

カスタムツール

独自の Python 関数をエージェントに公開できます。関数を run_session に渡すと、ポーリングループはエージェントからの呼び出しに応じて各関数を実行し、結果を返してセッションを続行します。型付きパラメーターと docstring を持つ関数であれば使用できます。入力スキーマはシグネチャから導出されます。

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

ツールで例外が発生すると、実行がクラッシュするのではなく、ツールエラーとしてエージェントに通知されます。AsyncClient では、ツールを async def で定義できます。

組み込み：ワンタイムパスワード（2FA）

hai_agents_tools には、すぐに使えるツールが含まれています。otp_tool を使うと、ログインまたは登録の手順で必要な場合に、エージェントがワンタイムパスワード、確認コード、または確認リンクを要求できます。ハンドラーを指定しない場合は 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 認証情報がお使いのマシンの外に出ることはなく、エージェントが受け取るのは抽出された単一のコードまたはリンクのみで、メールボックスの内容は渡されません。

ブラウザープロファイルと Vault

ユーザーの情報がすでに保存されているブラウザーでセッションを開始できます。ブラウザープロファイル は以前のセッションから保存済みの Cookie とストレージを復元し、Vault を使うと、コンテキストに入ることのないシークレットを使ってエージェントがサイトにサインインできます。両方を実行ごとのオーバーライドでバインドします。

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

セッションの確認と共有

過去のセッションを一覧表示し、公開リプレイリンクを作成します。

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 リージョンを使用します。US リージョンを使うには environment を渡します。

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)

コマンドライン

cli extra をインストールすると、ターミナルからエージェントを操作するための hai コマンドがインストールされます。

hai login
hai run "What's the top story on Hacker News?"
hai sessions list
hai sessions watch <session-id>
hai mcp install

hai login はブラウザーで Google にサインインするか、platform.hcompany.ai/settings/api-keys からコピーしたキーを受け取り、~/.config/hai/.env に保存します。ターミナルでほかのコマンドを初めて実行したときも同じ処理が行われるため、hai login は省略できます。スクリプトや --json を指定した実行ではプロンプトが表示されません。キーを hai login --key にパイプするか、HAI_API_KEY を設定してください。hai mcp install は、hai-agents MCP サーバーを Cursor、VS Code、Claude Code などの MCP クライアントに追加します。認証情報は、--api-key、HAI_API_KEY、~/.config/hai/.env の順に参照されます。すべてのコマンドについては、hai --help を実行してください。

ドキュメント

ガイド、基本概念、API リファレンスの完全版は、hub.hcompany.ai/agents-api にあります。

ライセンス

MIT