context.agents.run(...) を呼び出し、サーバーサイドのワークフローに多段階の推論を組み込みます。同じエージェントを操作・確認するための対話型 CLI も用意されています。
エージェントを定義する
設定に[[agents]] テーブルが 1 つ以上宣言されるまで、agents は無効です。
上表にないキーは生成にそのまま渡されるため、
temperature や top_p はそのまま記述できます。
エージェント定義は初回実行時ではなく起動時に検証されます。未知の buttress/ モデル、存在しないプロンプトファイル、不正なツール名、エージェント名の重複があると、そのエージェントを黙って無視するのではなく、サーバーがエラーで停止します。
グローバルオプション
[agents_options] はすべてのエージェントに適用されます。
モデル
model は provider/model-id 形式で、最初のスラッシュで分割されます。そのため model id 自体にスラッシュを含められます。
buttress/<repo_id> は、このサーバーがすでにホストしているモデルを指します。この id は設定済みの ggml-llm または mlx-llm [[generators]] エントリの repo_id と一致する必要があり、サーバーが起動時に検証します。通信はプロセス内のループバック経由で generator に届きます — ソケットを介さず、追加設定も不要です。[openai_compat] を有効にする必要はありません。このキーは引き続き外部 HTTP ルートのみを制御します。
anthropic/…、openai/…、google/…）を指し、各プロバイダーの通常の環境変数（ANTHROPIC_API_KEY、OPENAI_API_KEY など）で認証されます。[env] またはプロセス環境で設定してください。
OAuth によるプロバイダーログインには対応していません。ホスト型プロバイダーを使う場合は、環境に API キーが必要です。
ツール
tools にはローカル関数名を明示的に列挙します。各ツール呼び出しは通常の関数エグゼキューターを経由するため、HTTP や MCP から呼び出したときと同じ遅延リロード、スクラッチディレクトリ、プロセス追跡、meta.timeout の期限が適用されます。またモデルが参照するのは、その関数の meta.parameters の JSON Schema です。
実行を中止すると、進行中のツール呼び出しと、その呼び出しが起動したプロセスも中止されます。
列挙された関数が存在しない場合、その実行はエラーで失敗します。無人の自動化処理が、欠けている機能を勝手に迂回することはありません。
MCP サーバー
[agents.mcp_servers.<name>] で、ローカル関数に加えて MCP サーバーのツールを追加できます。各サーバーには url（Streamable HTTP）か command（stdio）のどちらか一方だけを指定します。
mcp__github__create_issue）で公開されるため、ローカル関数名と衝突しません。サーバーは、それを必要とする最初の実行時に遅延接続します。接続できないサーバーがあると、optional = true が指定されていない限りその実行は失敗します。指定されている場合、エージェントはそのツールなしで実行を続けます。
エージェントを実行する
ローカル関数から
これが主要なインターフェースです。設定済みのエージェントはすべてcontext.agents から利用できます。
実行は呼び出し元の関数のライフタイムと期限を引き継ぎます。
context.signal — 関数の meta.timeout の満了や呼び出し元の切断 — によって実行とそのツール呼び出しが中止されます。エージェントのループは通常の関数呼び出しよりはるかに時間がかかるため、meta.timeout を引き上げるか、期限のない daemon に処理を移してください。
エージェントの進捗は、関数自身の SSE ストリームに agent イベントとしてミラーされます。そのため関数の SSE 呼び出し元は、追加の配線なしにエージェントの動作を確認できます。
サーバーに [[agents]] が 1 つも設定されていない場合、これらのメソッドはすべて例外を投げます。
HTTP 経由
AGENT_RUN_FAILED が sessionId 付きで返るため、トランスクリプトには引き続きアクセスできます。中止された実行は 499、それ以外の失敗は 500 を返します。存在しないエージェントや session は 404 NOT_FOUND を返します。
ストリーミングレスポンスが運ぶのは、スリム化されたエージェントイベントです。生成途中のアシスタントメッセージや完全なツール結果は、ストリームを圧迫するため含まれません。完全な記録が必要な場合は、sessions エンドポイントからトランスクリプトを取得してください。
CLI から
bricks-buttress agent は、実行中のサーバー上のエージェントと対話するストリーミングチャットクライアントです。サーバーと同じ設定ファイルを指定すれば、ポートとローカルトークンを自動的に見つけます。
チャットでは、テキスト・思考内容・ツール呼び出しがリアルタイムにストリーミングされます。チャット中は
/exit で終了、/new で新しい session を開始、Ctrl+C で現在の実行を中止します（もう一度 Ctrl+C を押すと終了）。
実行結果
context.agents.run と POST /agents/<name>/run は、いずれも次の内容を返します。
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 を削除します。
session はエージェントの
name でスコープが決まります。エージェント名を変更すると既存の session は孤立します — ファイルはディスク上に残りますが、名前を変更したエージェントからは一覧にも表示されず、継続もできません。セキュリティ
/agents の認証は、公開された推論エンドポイントではなく、ローカル関数のインターフェースと同じ方式です。
- バインド済みのサーバーでは、workspace のアクセストークンが必要です。ワークスペースへのバインドを参照してください。
- 未バインドのサーバーは、
[agents_options] allow_unauthenticated = trueが設定されていない限り、リモートからの呼び出しをすべて拒否します。 - クロスサイトのブラウザーリクエストは常に拒否されます。
sessions_dir の隣に一時的なランタイムトークンを runtime-token ファイル（パーミッション 0600）として書き出します。同一ホスト上のツール（上記の CLI など）はこれを読み取り、バインドの有無にかかわらず自動的に認証します。
エージェント定義は、設定ファイルや関数ファイルと同様に信頼された入力です。エージェントの安全性は、与えたローカル関数と MCP サーバーの安全性で決まります。いつ呼び出すかを決めるのはモデルであるため、エージェントには目的を果たすのに必要な最小限のツールだけを与えてください。
バインド済みのサーバーが自分自身のために workspace トークンを発行することはありません。buttress/ モデルへのループバックは内部トークンで認可され、workspace の資格情報は一切使われません。
サンプル
サーバーパッケージにはconfig/function-samples/run-agent.ts が同梱されています。これは設定済みのエージェントを実行し、その結論・session id・ターン数・停止理由を返すローカル関数です。config/sample.toml にはコメントアウトされた [[agents]] ブロックが含まれています。その他のサンプルはローカル関数を参照してください。
次のステップ
ローカル関数
エージェントがツールとして使う関数を書きます。
設定
エージェントが動作する generator を含む、TOML の完全なリファレンス。