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 が指定されていない限りその実行は失敗します。指定されている場合、エージェントはそのツールなしで実行を続けます。
exposure でサーバーのツールをモデルにどう公開するかを選び、tool_exposure で個別のツールについて上書きします。キーには正確なツール名か * パターンを指定します。正確な名前はパターンより優先され、パターン同士では最初に一致したものが使われます。
codemode = true のないエージェントで codemode または deferred を指定すると、サーバーは起動時に停止します。
ローカルデバイス
local_devices = true を指定すると、LAN 上の BRICKS デバイスに接続するための組み込みツールが 2 つ、そのエージェントに追加されます。これらはローカル関数や MCP サーバーとは独立して動作し（[functions] を有効にする必要はありません）、明示的にオプトインするまでは無効です。
devices_scan や devtools を tools に追加しないでください。tools はローカル関数名のみを受け付けます。local_devices の変更は、サーバーの次回起動時に反映されます。
devices_scan は bricks devtools scan と同じ UDP および HTTP による探索を実行します。ただし対象は呼び出し元ではなく Buttress ホストのネットワークで、設定ディレクトリを基準としたローカルプロジェクトのプレビューも検出します。{} で呼び出すか、次の引数で絞り込めます。
devtools は Chrome DevTools Protocol 経由で 1 台のデバイスを操作します。各呼び出しには action と address（ポートを含まないホスト名または IP。IPv6 は角括弧で囲みます）、および port（デフォルトは 19851）を指定します。
まずスキャンし、その結果からデバイスを指定します。
passcode またはワークスペースの DevTools accessToken を渡します。指定しない場合、接続にはデバイスが Chrome Inspect 用に広告している資格情報が使われます。Buttress がホストの BRICKS CLI のログイン情報を読むことはなく、自ら token を発行することもありません。
各呼び出しは自身の CDP 接続を開いて閉じます。また、デバイスが同時に受け付ける inspector は 1 つだけです。そのため呼び出しは順番に実行し、エージェントの作業中は他の DevTools クライアントをそのデバイスに接続しないでください。実行を中止すると、開いている接続は閉じられます。すでに開始されたスキャンは、限定された範囲の探索を終えてから中止結果を返します。
Codemode
codemode = true は、1 つのエージェントに codemode ツールを追加します。有効にすると、モデルはエージェントの他のツール（ローカル関数、MCP ツール、ローカルデバイスのツール）を 1 つずつ呼び出す代わりに、それらを呼び出す短い JavaScript プログラムを書きます。呼び出しの並列実行、ある結果を次の呼び出しにつなぐ処理、大きな結果をコンテキストに届く前に絞り込む処理ができます。モデルに戻るのはスクリプトが出力した内容だけです。
exposure = "codemode"でモデルのツール一覧から除外した MCP ツールを検索して呼び出す。MCP サーバーを参照- エージェントのプロバイダー認証情報で分類器モデルを実行する
- 同じ session 内で、後のスクリプトのために小さな値を保持する
codemode の変更は次回のサーバー起動時に反映されます。
エージェントを実行する
ローカル関数から
これが主要なインターフェースです。設定済みのエージェントはすべて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 の完全なリファレンス。