Agent config
Agent config の全フィールド。
Agent のバージョンは 1 つの JSON ドキュメントです。コンソールの バージョンの編集画面 はこのドキュメントを編集するフォームで、subako agent publish はこれをファイルから読み込みます。API では POST /v1/agents/{agent_id}/versions がこのドキュメントを受け取り、Model Provider はドキュメントと並べて model_provider_id で指定します。
{
"system_prompt": "You triage support tickets for Acme.",
"model": { "format": "openai_responses", "model": "hawk", "max_tokens": 8192, "context_window": 128000 },
"mcp": [{ "name": "orders", "url": "https://mcp.acme.example/orders", "default_policy": "require_approval" }],
"skills": [{ "name": "refund-policy", "skill_id": "<skill-id>", "version": { "type": "latest" } }],
"functions": [{ "name": "files", "source": { "type": "platform", "package": "files" }, "default_policy": "allow" }],
"volume": { "data": { "type": "enabled" } },
"builtin": { "session_display_name": { "when": "empty" }, "ask_user": { "widgets": [{ "type": "select" }] } }
}subako agent config-example --format <format> は、公開できる最小のドキュメントを出力します。サーバーが知らないキーはエラーにならず無視されるので、公開後にバージョンのページで内容を確認してください。
トップレベル
| フィールド | ||
|---|---|---|
system_prompt |
文字列 | 毎回の会話の前にモデルに与える指示です。省略すると何も指示しません。 |
model |
オブジェクト、必須 | モデルとその設定です。 |
mcp |
配列 | MCP サーバーの Grant です。 |
skills |
配列 | Skill の Grant です。 |
sandboxes |
配列 | Sandbox の Grant です。 |
functions |
配列 | Function package の Grant です。 |
volume |
オブジェクト | Session Volume の領域です。 |
builtin |
オブジェクト | Subako 自身が提供する Tool です。 |
Model Provider はドキュメントに含めません。編集画面の Model Provider、CLI の --model-provider、API の model_provider_id で指定するので、同じファイルを同じ形式のどの Model Provider にも公開できます。CORS の Origin はバージョンではなく Agent に設定します。詳しくは API から Session を使う を参照してください。
model
format で種類を区別します。値は Model Provider の形式と一致させてください。
| フィールド | ||
|---|---|---|
model |
文字列、必須 | モデルの ID です。Platform の Model Provider では価格が設定されているモデルでなければならず、公開時に確認されます。自分の Model Provider のモデルは、Session が最初に呼び出したときに確認されます。 |
max_tokens |
整数、必須 | モデルが 1 ステップで書けるトークン数の上限です。 |
context_window |
整数、必須 | モデルが一度に読み込めるトークン数です。 |
image_input |
supported | unsupported |
モデルに画像を渡すかどうかです。既定は supported です。 |
reasoning_effort |
none | minimal | low | medium | high | xhigh |
省略するとモデルの既定値を使います。 |
| フィールド | ||
|---|---|---|
model |
文字列、必須 | モデルの ID です (例: claude-sonnet-5)。 |
max_tokens |
整数、必須 | モデルが 1 ステップで書けるトークン数の上限です。Thinking の分も含みます。 |
context_window |
整数、必須 | モデルが一度に読み込めるトークン数です。 |
image_input |
supported | unsupported |
モデルに画像を渡すかどうかです。既定は supported です。 |
thinking |
オブジェクト | {"type": "adaptive"}、{"type": "disabled"}、{"type": "between_tools"}、{"type": "enabled", "budget_tokens": N} のいずれかです。N は 1,024 以上、max_tokens 未満にします。省略するとモデルの既定値を使います。モデルによっては使えないモードもあります。 |
effort |
low | medium | high | xhigh | max |
省略するとモデルの既定値を使います。 |
Grant
Grant にはどれも name を付けます。英小文字、数字、- からなる 1~32 文字で、同じ配列の中で一意にします。parent は使えません。Grant の Tool は、モデルには <kind>__<name>__<tool> という名前で見えます。詳しくは Tool を参照してください。
MCP サーバー、Sandbox、Function の Grant には Policy も指定します。
| フィールド | ||
|---|---|---|
default_policy |
allow | require_approval | deny、必須 |
どの Tool rule にも指定されていない Tool すべてに適用されます。後から追加された Tool も含みます。 |
tools |
[{"name", "policy"}] |
Tool 名の完全一致で指定する Tool rule です。 |
mcp
{ "name": "orders", "url": "https://mcp.acme.example/orders", "default_policy": "allow", "tools": [{ "name": "refund", "policy": "require_approval" }] }url はサーバーの URL で、そのサーバー用の Vault の Credential に指定した URL と完全に一致させます。リソースを提供するサーバーには、list_resources と read_resource の Tool も追加されます。
skills
{ "name": "refund-policy", "skill_id": "<skill-id>", "version": { "type": "pinned", "number": 2 } }version は {"type": "latest"} (各 Session の作成時に解決されます) か {"type": "pinned", "number": N} です。同じ Skill を付与できるのは一度だけです。
sandboxes
{ "name": "build", "environment": { "type": "platform", "release": "2026" }, "network": { "type": "unrestricted" }, "default_policy": "allow" }| フィールド | ||
|---|---|---|
environment |
{"type": "platform", "release": "2026"}、必須 |
起動する Platform image の系列です。 |
network |
{"type": "unrestricted"} | {"type": "none"} |
インターネットに接続するか、どこにも接続しないかです。既定は unrestricted です。 |
Sandbox の Tool は exec の 1 つだけです。
functions
{
"name": "billing",
"source": { "type": "workspace", "function_id": "<function-id>", "version": { "type": "latest" } },
"default_policy": "allow",
"timeout_secs": 120,
"network": { "type": "allowlist", "hosts": ["billing.acme.example"] },
"http_credentials": ["https://billing.acme.example"]
}| フィールド | ||
|---|---|---|
source |
必須 | {"type": "platform", "package": "files" | "http"}、または {"type": "workspace", "function_id", "version"} です。version の書き方は Skill と同じです。 |
timeout_secs |
1~300 | 既定は 60 秒です。 |
network |
{"type": "none"} (既定)、{"type": "unrestricted"}、{"type": "allowlist", "hosts": [...]} のいずれかです。hosts には api.example.com や *.example.com のような Host を 1~64 個指定します。 |
|
http_credentials |
最大 16 個 | Vault の Credential をリクエストに付ける Origin (https://host[:port]) です。どの Origin も network で接続できる必要があります。 |
詳しくは Function の付与 を参照してください。
volume
{ "data": { "type": "enabled" } }既定は {"type": "disabled"} です。有効にすると、Function は常に使える /volume/tmp に加えて、Session を削除するまで残る /volume/data を使えます。
builtin
session_display_name
{"when": "never" | "empty" | "until_user_edits"} で指定し、既定は never です。never 以外にすると、Agent が自分の Session に名前を付けられます。empty では名前がない間だけ付けられ、until_user_edits では、人が名前を変えるまで自分で付けた名前を直すこともできます。人が付けた名前が上書きされることはありません。
ask_user
{"widgets": [...]} で、Widget を 1~32 個、それぞれ一度ずつ指定します。省略すると、Agent は人に質問できません。
| Widget | |
|---|---|
{"type": "select"} |
選択肢から選ぶ |
{"type": "text"} |
自由入力のテキスト |
{"type": "confirm"} |
はい・いいえ |
{"type": "custom", "id", "description", "props", "answer"} |
アプリが描画する Widget です。id (a–z、0–9、_、- からなる 1~64 文字)、モデルがこの Widget を選ぶときに読む description、Agent が埋める内容 (props) と回答の内容 (answer) を表す JSON Schema を指定します |
詳しくは 承認とフォーム を参照してください。
公開したバージョンを読み出す
GET /v1/agents/{agent_id}/versions は、各バージョンの config を Subako が保存している形で返します。この形は公開時のものと少し異なり、モデルの設定は model.config の下にまとめられ、既定値も省略されずに書かれます。TypeScript SDK の readAgentConfig を使うと、公開時の形に戻せます。