> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snorbe.deskrex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# エージェント CRUD

> API キーで Agent を作成・取得・更新・削除します

# エージェント CRUD

API キーに紐づくワークスペース内で Agent を作成・取得・更新・削除します。

<Note>
  `workspaceId` や `userId` はリクエストで渡しません。API キーのスコープが自動的に適用されます。
</Note>

## 共通ヘッダー

| ヘッダー            | 必須              | 説明                             |
| --------------- | --------------- | ------------------------------ |
| `Authorization` | はい              | `Bearer snorbe_...` 形式の API キー |
| `Content-Type`  | POST / PATCH のみ | `application/json`             |

## GET /api/v1/agent/{agentId}

Agent の詳細を 1 件取得します。

### レスポンス

```json theme={null}
{
  "id": "clxxx123456",
  "name": "Research Agent",
  "identityMarkdown": "# Identity\nB2B SaaS の市場調査が得意です。",
  "userMarkdown": "ユーザーは新規事業責任者。",
  "soulMarkdown": "仮説を明示し、根拠を分けて話す。",
  "memoryMarkdown": "- 競合調査の粒度を高める依頼が多い",
  "isDefault": true,
  "createdAt": "2026-04-19T00:00:00.000Z",
  "updatedAt": "2026-04-19T02:30:00.000Z"
}
```

## POST /api/v1/agent

Agent を新規作成します。

### リクエストボディ

```json theme={null}
{
  "name": "Patent Analyst",
  "identityMarkdown": "# Identity\n特許調査を担当します",
  "userMarkdown": "",
  "soulMarkdown": "",
  "memoryMarkdown": "",
  "isDefault": false
}
```

### フィールド

| フィールド              | 型         | 必須  | 説明                                |
| ------------------ | --------- | --- | --------------------------------- |
| `name`             | `string`  | はい  | Agent 名。最大 100 文字                 |
| `identityMarkdown` | `string`  | いいえ | 自己紹介。最大 300 文字                    |
| `userMarkdown`     | `string`  | いいえ | ユーザー理解。最大 600 文字                  |
| `soulMarkdown`     | `string`  | いいえ | Persona / SOUL。最大 800 文字          |
| `memoryMarkdown`   | `string`  | いいえ | 長期記憶。最大 2000 文字                   |
| `isDefault`        | `boolean` | いいえ | `true` の場合、その Agent を default に設定 |

### default の挙動

* 1 体目の Agent は自動で `isDefault: true` になります
* `isDefault: true` で作成すると、同じワークスペース内の既存 default は解除されます

## PATCH /api/v1/agent/{agentId}

Agent を部分更新します。送ったフィールドのみ更新されます。

### リクエストボディ

```json theme={null}
{
  "identityMarkdown": "# Identity\n知財・論文の横断調査を担当します",
  "isDefault": true
}
```

### 注意

* `isDefault: true` を送ると、その Agent が default になります
* 現在の default Agent に `isDefault: false` を直接送ることはできません。別 Agent を default にしてください

## DELETE /api/v1/agent/{agentId}

Agent を削除します。関連する `AgentRun` は cascade で削除されます。

### default 削除時の挙動

* 他の Agent が残っていれば、最新更新の Agent が新しい default に昇格します
* 残りが 0 件なら default Agent は不在になります

## レスポンスフィールド

POST / GET / PATCH / DELETE はすべて同じ Agent オブジェクトを返します。

| フィールド              | 型         | 説明                 |
| ------------------ | --------- | ------------------ |
| `id`               | `string`  | Agent ID           |
| `name`             | `string`  | Agent 名            |
| `identityMarkdown` | `string`  | 自己紹介               |
| `userMarkdown`     | `string`  | ユーザー理解             |
| `soulMarkdown`     | `string`  | Persona / SOUL     |
| `memoryMarkdown`   | `string`  | 長期記憶               |
| `isDefault`        | `boolean` | default Agent かどうか |
| `createdAt`        | `string`  | 作成日時（ISO 8601）     |
| `updatedAt`        | `string`  | 更新日時（ISO 8601）     |

## 使用例

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://app.snorbe.deskrex.ai/api/v1/agent/clxxx123456" \
    -H "Authorization: Bearer snorbe_your_api_key_here"

  curl -X POST "https://app.snorbe.deskrex.ai/api/v1/agent" \
    -H "Authorization: Bearer snorbe_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Patent Analyst",
      "identityMarkdown": "# Identity\n特許調査を担当します"
    }'

  curl -X PATCH "https://app.snorbe.deskrex.ai/api/v1/agent/clxxx123456" \
    -H "Authorization: Bearer snorbe_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "isDefault": true
    }'

  curl -X DELETE "https://app.snorbe.deskrex.ai/api/v1/agent/clxxx123456" \
    -H "Authorization: Bearer snorbe_your_api_key_here"
  ```

  ```typescript TypeScript theme={null}
  const headers = {
    Authorization: "Bearer snorbe_your_api_key_here",
    "Content-Type": "application/json",
  };

  const created = await fetch("https://app.snorbe.deskrex.ai/api/v1/agent", {
    method: "POST",
    headers,
    body: JSON.stringify({
      name: "Patent Analyst",
      identityMarkdown: "# Identity\n特許調査を担当します",
    }),
  }).then((resp) => resp.json());

  await fetch(`https://app.snorbe.deskrex.ai/api/v1/agent/${created.id}`, {
    method: "PATCH",
    headers,
    body: JSON.stringify({ isDefault: true }),
  });
  ```
</CodeGroup>

## エラーレスポンス

| HTTP ステータス | コード                 | 説明                              |
| ---------- | ------------------- | ------------------------------- |
| 400        | `BAD_REQUEST`       | default の解除方法が不正、または入力値が不正      |
| 401        | `UNAUTHORIZED`      | API キーが無効、期限切れ、または未指定           |
| 404        | `NOT_FOUND`         | 指定した Agent が API キーのスコープ内に存在しない |
| 429        | `TOO_MANY_REQUESTS` | レート制限超過                         |