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

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

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

## 登録する

```http
POST /v1/sessions/{session_id}/clients
```

```json
{
  "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"]
      }
    }
  ]
}
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | - | この client の tool がモデルから見える名前。その名前を session がすでに使っていた場合はカウンターが付きます — 割り当てられた名前は `client_registered` event で返り、意味を持つのはそちらです。 |
| `lifetime` | `never \| ttl` | - | `never` は明示的な離脱でのみ終わります。`ttl` は最後の ping から `seconds` 後に終わるので、閉じられたタブは自ら告げなくても tool の提供をやめます。 |
| `tools` | `ClientTool[]` | - | 各 tool は名前（1〜64 文字、`[A-Za-z0-9_-]`）、最大 4096 文字の説明、引数を表す JSON Schema オブジェクトを持ちます。 |

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

## Lifetime を選ぶ

**ブラウザのタブ**

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

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

**バックエンドの worker**

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

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

## Call に応答する

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

1. **ack する**

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

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

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

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

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

## 提供内容を変える

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

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

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

:::note
Call は、それがディスパッチされた登録に属するのであって、その登録が持っていた名前に属するわけではありません。解放された名前を引き継いだ後続の client が、未処理の仕事まで引き継ぐことはありません。
:::