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

# Agents

> BRICKS Buttress の設定で LLM エージェントを定義し、ローカル関数をツールとして与え、関数・HTTP・CLI から実行する

エージェントは、[BRICKS Buttress](/ja/buttress) サーバーの設定で宣言する LLM ループです。**サーバープロセス内**で動作し、[ローカル関数](/ja/buttress/functions)（および MCP サーバー）をツールとして使い、会話履歴をディスク上の session ファイルに保持します。

主な利用者は自動化処理です。ローカル関数や daemon が `context.agents.run(...)` を呼び出し、サーバーサイドのワークフローに多段階の推論を組み込みます。同じエージェントを操作・確認するための対話型 CLI も用意されています。

<Warning>
  Agents は実験的機能です。`[[agents]]` と `[agents_options]` の設定キー、`/agents` エンドポイント、SSE イベントの構造、`context.agents` API は、非推奨期間を挟まずにリリース間で変更される可能性があります。サーバーは起動時にこの注意を表示します。これを前提に開発する場合は `bricks-buttress` のバージョンを固定し、アップグレード後は本ページを読み直してください。
</Warning>

## エージェントを定義する

設定に `[[agents]]` テーブルが 1 つ以上宣言されるまで、agents は無効です。

```toml theme={null}
[[agents]]
name = "ops-assistant"                            # 一意であること。session のスコープキーも兼ねる
model = "buttress/ggml-org/gpt-oss-20b-GGUF"      # provider/model-id。「最初の」スラッシュで分割
system_prompt = "You are an ops automation agent. Use the provided tools."
# system_prompt_file = "./prompts/ops.md"         # またはファイル指定。両方は不可
tools = ["get-server-status", "restart-service"]  # ローカル関数名
max_turns = 30
# max_tokens_per_run = 200000
# temperature = 0.2                               # 認識されないキーは生成にそのまま渡される

[agents.mcp_servers.github]                       # 任意の MCP サーバー
url = "https://api.githubcopilot.com/mcp/"
# optional = true
```

| キー                            | 型         | デフォルト | 説明                                                                             |
| ----------------------------- | --------- | ----- | ------------------------------------------------------------------------------ |
| `name`                        | string    | —     | 必須。設定内で一意であり、そのエージェントの session のスコープキーになります。英数字・`-`・`_` が使え、最大 64 文字           |
| `model`                       | string    | —     | 必須。`provider/model-id` 形式で、**最初の**スラッシュで分割されます。[モデル](#モデル)を参照                  |
| `system_prompt`               | string    | —     | インラインのシステムプロンプト                                                                |
| `system_prompt_file`          | string    | —     | システムプロンプトのファイルパス。相対パスは設定ファイル基準で解決され、`~` はホームディレクトリに展開されます。`system_prompt` とは排他 |
| `tools`                       | string\[] | `[]`  | ローカル関数名を明示的に列挙します。ワイルドカードはありません。[ツール](#ツール)を参照                                 |
| `max_turns`                   | integer   | `30`  | 1 回の実行あたりのアシスタント↔ツールの往復回数                                                      |
| `max_tokens_per_run`          | integer   | 無制限   | 1 回の実行あたりのトークン予算                                                               |
| `[agents.mcp_servers.<name>]` | table     | `{}`  | ツールとして追加する MCP サーバー。[MCP サーバー](#mcp-サーバー)を参照                                   |

上表にないキーは生成にそのまま渡されるため、`temperature` や `top_p` はそのまま記述できます。

エージェント定義は初回実行時ではなく**起動時**に検証されます。未知の `buttress/` モデル、存在しないプロンプトファイル、不正なツール名、エージェント名の重複があると、そのエージェントを黙って無視するのではなく、サーバーがエラーで停止します。

### グローバルオプション

`[agents_options]` はすべてのエージェントに適用されます。

```toml theme={null}
[agents_options]
# sessions_dir = "./.buttress-agent/sessions"
# session_max_age = "30d"
# session_max_count = 500
# max_depth = 2
# allow_unauthenticated = false
```

| キー                      | 型                 | デフォルト                          | 説明                                                        |
| ----------------------- | ----------------- | ------------------------------ | --------------------------------------------------------- |
| `sessions_dir`          | string            | `"./.buttress-agent/sessions"` | session ファイルの保存先。相対パスは設定ファイル基準で解決され、`~` はホームディレクトリに展開されます |
| `session_max_age`       | number または string | `"30d"`                        | 経過時間による自動削除。ミリ秒数または期間文字列で指定し、`0` で無効                      |
| `session_max_count`     | integer           | `500`                          | 件数による自動削除（エージェントごと）。`0` で無効                               |
| `max_depth`             | integer           | `2`                            | エージェント呼び出しの連鎖の深さの上限 — 関数 → エージェント → 関数 → エージェント           |
| `allow_unauthenticated` | boolean           | `false`                        | **未バインド**のサーバーでも `/agents` を提供します。[セキュリティ](#セキュリティ)を参照    |

## モデル

`model` は `provider/model-id` 形式で、最初のスラッシュで分割されます。そのため model id 自体にスラッシュを含められます。

**`buttress/<repo_id>`** は、このサーバーがすでにホストしているモデルを指します。この id は設定済みの `ggml-llm` または `mlx-llm` [`[[generators]]`](/ja/buttress/configuration#generators) エントリの `repo_id` と一致する必要があり、サーバーが起動時に検証します。通信はプロセス内のループバック経由で generator に届きます — ソケットを介さず、追加設定も不要です。`[openai_compat]` を有効にする必要はありません。このキーは引き続き外部 HTTP ルートのみを制御します。

```toml theme={null}
[[generators]]
type = "ggml-llm"

[generators.model]
repo_id = "ggml-org/gpt-oss-20b-GGUF"

[[agents]]
name = "ops-assistant"
model = "buttress/ggml-org/gpt-oss-20b-GGUF"
```

**それ以外のプレフィックス**はホスト型プロバイダー（`anthropic/…`、`openai/…`、`google/…`）を指し、各プロバイダーの通常の環境変数（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY` など）で認証されます。`[env]` またはプロセス環境で設定してください。

```toml theme={null}
[env]
ANTHROPIC_API_KEY = "sk-ant-…"

[[agents]]
name = "reviewer"
model = "anthropic/claude-sonnet-5"
```

<Note>
  OAuth によるプロバイダーログインには対応していません。ホスト型プロバイダーを使う場合は、環境に API キーが必要です。
</Note>

## ツール

`tools` にはローカル関数名を明示的に列挙します。各ツール呼び出しは通常の関数エグゼキューターを経由するため、HTTP や MCP から呼び出したときと同じ遅延リロード、スクラッチディレクトリ、プロセス追跡、`meta.timeout` の期限が適用されます。またモデルが参照するのは、その関数の `meta.parameters` の JSON Schema です。

実行を中止すると、進行中のツール呼び出しと、その呼び出しが起動したプロセスも中止されます。

列挙された関数が存在しない場合、その実行は**エラーで失敗**します。無人の自動化処理が、欠けている機能を勝手に迂回することはありません。

### MCP サーバー

`[agents.mcp_servers.<name>]` で、ローカル関数に加えて MCP サーバーのツールを追加できます。各サーバーには `url`（Streamable HTTP）か `command`（stdio）のどちらか一方だけを指定します。

```toml theme={null}
[agents.mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
headers = { Authorization = "Bearer ghp_…" }

[agents.mcp_servers.local]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/srv/data"]
# env = { LOG_LEVEL = "debug" }
optional = true
```

MCP ツールはサーバー名で修飾された名前（`mcp__github__create_issue`）で公開されるため、ローカル関数名と衝突しません。サーバーは、それを必要とする最初の実行時に遅延接続します。接続できないサーバーがあると、`optional = true` が指定されていない限りその実行は**失敗**します。指定されている場合、エージェントはそのツールなしで実行を続けます。

## エージェントを実行する

### ローカル関数から

これが主要なインターフェースです。設定済みのエージェントはすべて `context.agents` から利用できます。

```ts theme={null}
export const meta = {
  description: 'Ask the ops agent to investigate a service.',
  timeout: '10m',
}

export default async ({ service }: { service: string }, context: ButtressFunctionContext) => {
  const result = await context.agents.run('ops-assistant', {
    prompt: `Investigate the '${service}' service and fix it if needed.`,
  })
  return { conclusion: result.content, sessionId: result.sessionId }
}
```

| メンバー                                | 機能                                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `agents.run(name, options)`         | プロンプトを最後まで実行 → [`AgentRunResult`](#実行結果)。オプションは `prompt`、`sessionId`、`fork`、`onEvent`、`onSession` |
| `agents.list()`                     | 設定済みのエージェント名                                                                                      |
| `agents.sessions(name, { limit? })` | 新しい順の [session サマリー](#sessions)                                                                   |

実行は呼び出し元の関数のライフタイムと期限を引き継ぎます。`context.signal` — 関数の `meta.timeout` の満了や呼び出し元の切断 — によって実行とそのツール呼び出しが中止されます。エージェントのループは通常の関数呼び出しよりはるかに時間がかかるため、`meta.timeout` を引き上げるか、期限のない **daemon** に処理を移してください。

エージェントの進捗は、関数自身の SSE ストリームに `agent` イベントとしてミラーされます。そのため*関数*の SSE 呼び出し元は、追加の配線なしにエージェントの動作を確認できます。

サーバーに `[[agents]]` が 1 つも設定されていない場合、これらのメソッドはすべて例外を投げます。

### HTTP 経由

| エンドポイント                                   | 用途                                                                        |
| ----------------------------------------- | ------------------------------------------------------------------------- |
| `GET /agents`                             | 設定済みのエージェント名 → `{ "agents": [...] }`                                      |
| `POST /agents/<name>/run`                 | プロンプトを実行します。ボディは `{ prompt, sessionId?, fork? }`、レスポンスは `{ "result": … }` |
| `POST /agents/<name>/run?stream=1`        | 同じ呼び出しを SSE で — `agent` 進捗イベントのあとに結果                                      |
| `GET /agents/<name>/sessions`             | 新しい順の session サマリー。`?limit=` で件数を制限                                       |
| `GET /agents/<name>/sessions/<id>`        | 完全なトランスクリプト → `{ "messages": [...] }`                                     |
| `POST /agents/<name>/sessions/<id>/abort` | その session で実行中の処理を中止 → `{ "aborted": true \| false }`                    |

```bash theme={null}
curl -X POST http://localhost:2080/agents/ops-assistant/run \
  -H 'Authorization: Bearer <workspace-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "Which services are unhealthy?"}'
```

実行が失敗すると `AGENT_RUN_FAILED` が `sessionId` 付きで返るため、トランスクリプトには引き続きアクセスできます。中止された実行は `499`、それ以外の失敗は `500` を返します。存在しないエージェントや session は `404 NOT_FOUND` を返します。

ストリーミングレスポンスが運ぶのは、スリム化されたエージェントイベントです。生成途中のアシスタントメッセージや完全なツール結果は、ストリームを圧迫するため含まれません。完全な記録が必要な場合は、sessions エンドポイントからトランスクリプトを取得してください。

### CLI から

`bricks-buttress agent` は、**実行中**のサーバー上のエージェントと対話するストリーミングチャットクライアントです。サーバーと同じ設定ファイルを指定すれば、ポートとローカルトークンを自動的に見つけます。

```sh theme={null}
bricks-buttress agent -c config.toml                                # エージェント一覧
bricks-buttress agent ops-assistant -c config.toml                  # チャット
bricks-buttress agent ops-assistant --sessions -c config.toml       # session 一覧
bricks-buttress agent ops-assistant --session <id> -c config.toml   # session を継続
bricks-buttress agent ops-assistant --fork <id> -c config.toml      # フォークしてその続きから
```

| オプション                 | 説明                                                       |
| --------------------- | -------------------------------------------------------- |
| `-c, --config <path>` | サーバーの設定ファイル — ポートとローカルのランタイムトークンの特定に使われます                |
| `--url <url>`         | サーバーのベース URL。デフォルトは設定ファイルの値、なければ `http://127.0.0.1:2080` |
| `--token <token>`     | アクセストークン。デフォルトは設定ファイルのランタイムトークンファイル                      |
| `--session <id>`      | 既存の session を継続します                                       |
| `--fork <id>`         | session をフォークし、そのフォークを継続します                              |
| `--sessions`          | そのエージェントの session を一覧表示して終了します                           |

チャットでは、テキスト・思考内容・ツール呼び出しがリアルタイムにストリーミングされます。チャット中は `/exit` で終了、`/new` で新しい session を開始、<kbd>Ctrl</kbd>+<kbd>C</kbd> で現在の実行を中止します（もう一度 <kbd>Ctrl</kbd>+<kbd>C</kbd> を押すと終了）。

### 実行結果

`context.agents.run` と `POST /agents/<name>/run` は、いずれも次の内容を返します。

| フィールド              | 説明                                                   |
| ------------------ | ---------------------------------------------------- |
| `sessionId`        | この実行が書き込んだ session。これを渡すと継続できます                      |
| `content`          | エージェントの最終的な回答                                        |
| `reasoningContent` | モデルが思考内容を生成した場合、そのテキスト                               |
| `usage`            | 実行全体を集計した `{ input, output, cacheRead, totalTurns }` |
| `stopReason`       | ループが終了した理由                                           |

`stopReason` は `end_turn`（エージェントが回答した）、`max_turns`、`token_budget`、`aborted`、`error` のいずれかです。`end_turn` 以外はすべて、回答が未完了だとみなしてください。

## Sessions

すべての実行はいずれかの session に属します。`sessionId` を省略すると新しい session が始まり、渡すと会話を継続します。あわせて `fork: true` を指定すると、元の session はそのままに、親を記録した新しい session に分岐します。

session は `sessions_dir` 配下の JSONL ファイルで、エージェント名でスコープが分かれ、実行のストリーミングと**同時に**書き込まれます。そのため、中止されたりタイムアウトした実行でも、継続可能なトランスクリプトが残ります。

同じ session への実行はキューに入って順番に処理され、異なる session は並列に実行されます。

自動削除処理が、経過時間（`session_max_age`）と件数（`session_max_count`、エージェントごと）に基づいて古い session を削除します。

<Note>
  session はエージェントの `name` でスコープが決まります。エージェント名を変更すると既存の session は孤立します — ファイルはディスク上に残りますが、名前を変更したエージェントからは一覧にも表示されず、継続もできません。
</Note>

## セキュリティ

`/agents` の認証は、公開された推論エンドポイントではなく、[ローカル関数のインターフェース](/ja/buttress/functions#セキュリティ)と同じ方式です。

* **バインド済み**のサーバーでは、workspace のアクセストークンが必要です。[ワークスペースへのバインド](/ja/buttress/workspace-binding)を参照してください。
* **未バインド**のサーバーは、`[agents_options] allow_unauthenticated = true` が設定されていない限り、リモートからの呼び出しをすべて拒否します。
* クロスサイトのブラウザーリクエストは常に拒否されます。

サーバーは起動時に、`sessions_dir` の隣に一時的な**ランタイムトークン**を `runtime-token` ファイル（パーミッション `0600`）として書き出します。同一ホスト上のツール（上記の CLI など）はこれを読み取り、バインドの有無にかかわらず自動的に認証します。

<Warning>
  `allow_unauthenticated = true` を設定すると、そのポートに到達できる誰もがすべてのエージェントを — ひいてはエージェントに与えたすべてのツールを — 実行できます。信頼できるネットワークでのみ使用してください。
</Warning>

エージェント定義は、設定ファイルや関数ファイルと同様に**信頼された入力**です。エージェントの安全性は、与えたローカル関数と MCP サーバーの安全性で決まります。いつ呼び出すかを決めるのはモデルであるため、エージェントには目的を果たすのに必要な最小限のツールだけを与えてください。

バインド済みのサーバーが自分自身のために workspace トークンを発行することはありません。`buttress/` モデルへのループバックは内部トークンで認可され、workspace の資格情報は一切使われません。

## サンプル

サーバーパッケージには `config/function-samples/run-agent.ts` が同梱されています。これは設定済みのエージェントを実行し、その結論・session id・ターン数・停止理由を返すローカル関数です。`config/sample.toml` にはコメントアウトされた `[[agents]]` ブロックが含まれています。その他のサンプルは[ローカル関数](/ja/buttress/functions#サンプル)を参照してください。

## 次のステップ

<CardGroup cols={2}>
  <Card title="ローカル関数" icon="code" href="/ja/buttress/functions">
    エージェントがツールとして使う関数を書きます。
  </Card>

  <Card title="設定" icon="gear" href="/ja/buttress/configuration">
    エージェントが動作する generator を含む、TOML の完全なリファレンス。
  </Card>
</CardGroup>