Client tool

あなたのアプリを session に client として登録し、提供する tool を宣言し、モデルからルーティングされた call に応答する。

あなたのアプリの中でしか動かせない tool があります。ユーザーがいま見ているフォームを読む、テーブルの行をハイライトする、日付を選んでもらう — agent はこれらを呼べるべきですが、サーバーサイドの連携では提供できません。

Client は、session に登録し、tool を宣言し、call に応答する参加者です。ブラウザのタブは client です。バックエンドの worker もそうです。

登録する

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

PropType

namestring

この client の tool がモデルから見える名前。その名前を session がすでに使っていた場合はカウンターが付きます — 割り当てられた名前は `client_registered` event で返り、意味を持つのはそちらです。

Typestring

lifetimenever | ttl

`never` は明示的な離脱でのみ終わります。`ttl` は最後の ping から `seconds` 後に終わるので、閉じられたタブは自ら告げなくても tool の提供をやめます。

Typenever | ttl

toolsClientTool[]

各 tool は名前（1〜64 文字、`[A-Za-z0-9_-]`）、最大 4096 文字の説明、引数を表す JSON Schema オブジェクトを持ちます。

TypeClientTool[]

これらのルートにはどちらの credential でも到達できます。Session 自身のトークンか、session.manage を持つ workspace の API key です。

Lifetime を選ぶ

タブは予告なく閉じられうるので、TTL を与えて開いている間 ping してください。ping が止まれば登録は失効し、応答する者のいない tool がモデルに提示されなくなります。

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

Session の寿命のあいだ起動し続けるサーバーサイドの client は never を使い、ping を一切省けます。離脱するのは、離脱すると告げたときです。

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

Call に応答する

Session のストリームで client_tool_dispatched を監視してください。そこにはあなたの client_id、call_id、あなたが 宣言したままの（名前空間の付かない）tool、そして引数が載っています。

ack する

ack は、call に取り組んでいる client と、そもそもそれを見ていない client を区別します。両者には異なる期限が設定されているので、ack すれば長いほうを得られます。

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

処理して、結果を投稿する

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

call の途中で client がいなくなった場合、その call は理由付きで client_tool_failed として確定し、モデルはエラーの tool 結果を受け取ります — 戻ってこない client を待って止まるのではなく、ターンが回復するということです。

提供内容を変える

Client は毎回リスト全体を宣言します。送ったリストが直前のものを置き換えるので、名前を挙げなくなった tool は、提供をやめた tool です。

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

画面を行き来する client が tool を正直に保つ方法がこれです — 画面が変わるたびにリストを PUT し直せば、モデルには実際にそこにあるものだけが提示されます。