Client tool

自分のアプリの中で実行する Tool。

ユーザーが見ているフォームの読み取り、表の行のハイライト、Agent が話題にしているページを開く操作など、アプリの中でしか実行できない Tool があります。こうした Tool を提供するのが Client です。Client は Session に登録してこれらの Tool を宣言し、Agent からの呼び出しに応答します。ブラウザーのタブも、バックエンドのワーカーも Client になれます。

モデルには Client の Tool が client__<name>__<tool> という名前で見えます。コンソールの会話では、その呼び出しは該当する Client によるものとして表示されます。

登録する

POST /v1/sessions/{session_id}/clients

{
  "name": "web",
  "lifetime": { "type": "ttl", "data": { "seconds": 60 } },
  "tools": [
    {
      "name": "highlight_row",
      "description": "Highlight a row in the table the user is looking at.",
      "parameters": {
        "type": "object",
        "properties": { "row_id": { "type": "string" } },
        "required": ["row_id"]
      }
    }
  ]
}

フィールド
`name`	英小文字、数字、`-` からなる 1~32 文字。その Session ですでに使われた名前の場合は末尾に番号が付くので、実際に割り当てられた名前はレスポンスで確認してください。
`lifetime`	`{"type": "never"}` の場合、登録は Client が退出したときにだけ終わります。`{"type": "ttl", "data": {"seconds": N}}` (5~3600) の場合は最後の ping から N 秒後に終わるので、閉じたタブが応答できない Tool を提供し続けることはありません。
`tools`	任意。64 個まで。各 Tool に `name` (`A`–`Z`、`a`–`z`、`0`–`9`、`_`、`-` からなる 1~64 文字)、4,096 文字までの `description`、`parameters` を表す JSON Schema オブジェクトを指定します。

レスポンスには Client の id、割り当てられた name、有効期限が含まれます。1 つの Session で同時に有効な Client は 32 個までです。これらのルートは、その Session の Session token か、Session › 管理の権限を持つ API key で呼び出せます。

登録を維持する

タブでは TTL を設定し、タブが開いている間、毎回新しい Idempotency-Key を付けて ping を送り続けます。ping が止まると登録は失効します。

POST /v1/sessions/{session_id}/clients/{client_id}/ping

ping に 404 が返った場合は登録が失効しているので、登録し直してください。

Session と同じ期間動き続けるワーカーは、never を使って ping を省略できます。ワーカーは自分から退出を伝えたときに退出します。そのとき名前は解放され、まだ応答していない呼び出しは失敗になります。

DELETE /v1/sessions/{session_id}/clients/{client_id}

呼び出しに応答する

ストリームで client_tool_dispatched を待ちます。この Event には、自分の client_id、call_id、自分が 宣言したとおりの Tool、引数が含まれます。

受け取りを通知する

ack は、Client がその呼び出しに取りかかったことを伝えます。呼び出しには 60 秒以内に ack し、ack してから 5 分以内に応答してください。

POST /v1/sessions/{session_id}/clients/{client_id}/calls/{call_id}/ack

結果を送る

POST /v1/sessions/{session_id}/clients/{client_id}/calls/{call_id}/result

{ "text": "Row 42 is highlighted.", "is_error": false }

text は 65,536 文字までです。is_error は、その結果がモデルに伝えるべき失敗であることを示します。

Client がいなくなったり期限を過ぎたりすると、呼び出しは理由 (client_gone、ack_timeout、result_timeout、run_gone) 付きの client_tool_failed で確定し、モデルにはエラーの結果が渡されます。そのため、Run が止まったままになることはありません。

提供する Tool を変える

Client が宣言した一覧は、それまでの一覧を置き換えます。一覧から外した Tool は提供されなくなります:

PUT /v1/sessions/{session_id}/clients/{client_id}/tools

画面遷移のあるページでは、この方法で Tool を画面の実態に合わせます。画面が変わるたびに、遷移を起こした呼び出しに応答する前に一覧を置き換えれば、モデルにはその画面で使える Tool だけが提供されます。

TypeScript SDK の @subako-ai/tools には、フォームの入力と送信、ページ遷移など、ページを操作する既製の Client tool が含まれています。