multica-creating-agents

Multica エージェントの作成

これは Multica のエージェント作成経路に関するコントラクトです。作成エントリポイントが何を受け付けるか、サーバーが何を検証して拒否するか、各フィールドがどのように永続化されるか、そしてデーモンがクレーム時に実際にどのフィールドを読み取るかを示します。これはパラメータのマニュアルではありません。ソースを追跡した事実を述べるものであり、すべての主張は references/creating-agents-source-map.md の file:line によって裏付けられています。

クイックスタート（読み取り専用の検査）

これらのコマンドは状態を読み取るだけで、副作用はありません:

multica agent get <agent-id> --output json      # full persisted agent record
multica agent skills list <agent-id> --output json   # current skill bindings
multica agent env get <agent-id> --output json  # plaintext env (agent owner or ws owner/admin; agents denied)

エージェントは未バインドにもなり得ます。runtime_id が NULL（"" として提供され、runtime_bound: false）になるのは、そのランタイムが削除された後です。この場合、エージェントは削除されずに未バインドになります（MUL-5559）。未バインドのエージェントは、所有するすべてを保持し、編集可能なままですが、agent update <id> --runtime-id <runtime-id> で再度バインドされるまで、どのトリガー経路もそれを実行しません — それらはすべて agent_runtime_required で拒否します。未バインドはアーカイブ済みとは直交する概念です。

agent get は、runtime_id、model、thinking_level、service_tier、custom_args、has_custom_env、custom_env_key_count、skills を含む、永続化されたエージェントを返します。平文の custom_env は決して返しません。

コアモデル

エージェントはワークスペーススコープの行（テーブル agent）です。作成は単一の POST /api/agents（multica agent create）です。タスクのクレーム時に、デーモンはエージェント行を再読み取りし、ランタイムペイロードを組み立てます — つまり、エージェントが実行するのは作成時の出力ではなく、永続化されたフィールドです。

しばしば混同される、2 つの異なるテキストフィールド:

• description はカタログの概要です。保存され、一覧に表示されますが、デーモンはこれをエージェントのランタイムプロンプトに注入しません。人間向けのメタデータとしてのみ扱ってください。最大 255 Unicode コードポイントです。
• instructions はランタイムの動作コントラクトです。デーモンはクレーム時にこれを読み取り、エージェントの永続的な instructions としてプロバイダーに出荷します。ペルソナ、責務、境界、出力およびエスカレーションのルールはここに記載し、description には記載しません。

CLI / API エントリポイント

最小の作成呼び出し（--name と --runtime-id はどちらも必須）:

multica agent create --name <name> --runtime-id <runtime-id> \
  --description "<short catalog summary>" \
  --instructions "<runtime behavior contract>" \
  --output json

runAgentCreate は JSON ボディを構築し、/api/agents にポストします。フラグが提供された場合にのみキーを追加します — description/instructions は空でない値の場合に、残り（runtime-config、custom-args、model、thinking-level、service-tier、visibility、…）はフラグが Changed の場合に — そのため省略されたフラグは空文字列を送信するのではなく、サーバーのデフォルトにフォールスルーします。--max-concurrent-tasks はリクエストが送信される前に 1〜50 として検証されます。

HTTP ボディ（CreateAgentRequest）は次を受け付けます: name、description、instructions、conversation_starters、avatar_url、runtime_id、runtime_config、custom_env、custom_args、model、thinking_level、service_tier、visibility、max_concurrent_tasks、mcp_config、skill_ids。

ボディは CLI が公開するよりも多くを受け付けます。conversation_starters には agent create / agent update フラグがありません — CLI は agent copy をまたぐ場合にのみこれを運ぶことができます。新しいエージェントにこれを設定するには、/api/agents を直接呼び出すか、人間に Web UI を使うよう伝えるかのいずれかです。それがどこにあるかは以下を参照してください。

エージェントのコピー

multica agent copy <source-agent-id> は、既存のエージェントのポータブルな 設定をまったく新しいエージェントにフォークし、ソースには手を加えません。これは Web の「複製」アクションに相当する CLI／ヘッドレスの機能です。専用のサーバー API は関与しません。runAgentCopy は GET /api/agents/<id> でソースを読み取り、次に CreateAgentRequest を POST します。このときソースのスキル ID を skill_ids で 渡すため、バインディングは同じ作成トランザクション内で関連付けられます（何も バインドしない agent create とは異なります）。したがって、この変更は単一の アトミックな作成操作です。

multica agent copy <source-agent-id> --name "My Agent (copy)"   # same runtime
multica agent copy <source-agent-id> --runtime-id <target> --model <model>  # cross-runtime fork

• 専用のオーバーライドフラグなしでデフォルトでコピーされます: conversation_starters。
• デフォルトでコピーされ、それぞれ対応するフラグでオーバーライドできます: name（" (copy)" が付加されます）、description、instructions、アバター、custom_args、 max_concurrent_tasks、呼び出し権限（permission_mode + 許可リスト）、および割り当てられたワークスペーススキル。
• コピーされた max_concurrent_tasks は、ソースの値が 1～50 の範囲内にある場合にのみ含まれます。履歴上の範囲外の値は省略されるため、 新しいエージェントはサーバーのデフォルト（6）を受け取ります。明示的な範囲外の --max-concurrent-tasks オーバーライドは、API リクエストの前に拒否されます。
• ランタイム固有のフィールド（model、thinking_level、service_tier）は、 ターゲットのランタイムが変更されていない場合にのみコピーされます。異なる ランタイムを選択する --runtime-id はこれらを破棄し、--model を必須とします （ターゲットランタイムのデフォルトを受け入れるには --model "" を渡します）。 これは、ランタイム切り替え時に Web の複製がモデルをクリアする動作を反映しています。
• コピーされないもの: custom_env、mcp_config、runtime_config（シークレット／ マシンローカルであり、いずれにせよ読み取り時に秘匿化またはマスクされます）。 これらには agent create と同じシークレットセーフなフラグ（--custom-env*、--mcp-config*、 --runtime-config）で新しい値を指定するか、コピー作成後に agent env set で指定します。
• --no-skills はソースのスキルバインディングのコピーをスキップします。

フィールド契約

フィールド	永続化される名前	検証?	利用者
name	agent.name	必須、空の場合は 400	リスティング、ランタイムペイロード
description	agent.description	255 コードポイントを超える場合は 400	カタログ/リスティングのみ — ランタイムプロンプトには使用されません
instructions	agent.instructions	なし	デーモン → クレーム時にプロバイダー
conversation_starters	agent.conversation_starters (JSON 配列)	最大 3 項目。各項目にはラベル (≤80 コードポイント) とプロンプト (≤4000 コードポイント) が必要	人間向けの Chat の空状態のみ。1 つ選択するとコンポーザーに事前入力されるだけで、実行は開始されません
avatar_url	agent.avatar_url	なし。明示的な空でない値は保持され、省略または空の場合はランダムな emoji:<glyph> アバターが作成されます	カタログ/リスティング UI のみ — ランタイムプロンプトには使用されません
runtime_id	agent.runtime_id (nullable)	作成時に必須 (400) + このワークスペース内のランタイムに解決できる必要があります	ランタイム/プロバイダーを選択します。NULL は未バインドを意味します — 以下を参照
model	agent.model (nullable)	ランタイムのサポート範囲を超える検証はなし	デーモンが読み取ります。空 = ランタイムのデフォルト
thinking_level	agent.thinking_level (nullable)	プロバイダーレベルの enum/安全トークンゲート。不明なリテラル → 400。Pi は `off	minimal
service_tier	agent.service_tier (nullable)	Codex 専用の安全トークン。他のプロバイダーは拒否します。デーモンは明示的な standard 機能または正確なモデル/カタログ階層のペアのいずれかをチェックします	デーモン → Codex app-server。空 = ローカルの Codex 設定、default = 明示的な Standard、priority などのカタログ階層 = 明示的な Fast
custom_args	agent.custom_args (JSON 配列)	JSON の形状は CLI 側でチェックされます。サーバーはそのまま保存します	デーモン (追加の CLI スイッチ)。デフォルトは []
runtime_config	agent.runtime_config (JSON)	JSON の形状は CLI 側でチェックされます。サーバーはそのまま保存します	ランタイム固有の設定。デフォルトは {}
custom_env	agent.custom_env (JSON オブジェクト)	—	デーモン (プロセス環境変数)。Env & secrets を参照
mcp_config	agent.mcp_config (生の JSON)	CLI は JSON オブジェクトまたは null であることをチェックします。サーバーはそのまま保存します。作成時、リテラルの null は破棄されます (no-op)。更新時、null はカラムをクリアします	デーモン → プロバイダー (プロバイダー固有の MCP 処理)。読み取り時にマスクされます
visibility	agent.visibility	—	アクセス制御。デフォルトは private。プライベートエージェント (例: プライベートなスクワッドリーダー) を読み取り/ルーティングできるユーザーを制限します — ランタイムプロンプトには使用されません
max_concurrent_tasks	agent.max_concurrent_tasks	1 から 50 までの整数。範囲外の値は 400 を返します	スケジューラのタスク上限。デフォルトは 6
省略時または明示的に null を指定した場合のデフォルト値: max_concurrent_tasks → 6。
省略時のその他のデフォルト値: runtime_config → {}、custom_env → {}、
custom_args → []、avatar_url → ランダムな emoji:<glyph>、visibility →
private
(すべて挿入前にサーバー側で実体化されます)。custom_args/runtime_config
は型が []string/any であり、そのままマーシャリングされます — JSON 形状の拒否は
CLI で行われ、作成ハンドラーでは行われません。

1〜50 の同時実行数の範囲は、作成と更新の両方に一貫して適用されます。作成時には、 省略されたフィールドは 6 にデフォルト設定される一方、明示的に指定された 0 は 拒否されます。更新時には、省略すると現在の値が保持されます。CLI は、作成または更新 リクエストを送信する前に、同じ範囲チェックを実行します。

thinking_level はプロバイダーレベルでのみ検証されます。固定語彙の プロバイダーは認識されないリテラルを拒否し、Codex/OpenCode のような動的語彙の プロバイダーは構文的に安全なトークンを受け入れます。Pi のプロバイダーレベルの 語彙は固定です(off|minimal|low|medium|high|xhigh|max)。ただし、その正確な サポート対象サブセットはモデル固有であり、ローカルの Pi RPC モデル カタログから検出されます。選択したモデルでサポートされていない値は、ここでは 拒否されません — デーモンは実行時にローカルのモデルカタログを確認し、警告を ログに記録して、互換性のないオーバーライドを省略します。

CLI からは agent create および agent update で --thinking-level を 指定して設定します。これは --model と同様です。このフラグはトップレベルの thinking_level フィールドへの薄いパススルーであり、更新時に空文字列 (--thinking-level "")を指定するとランタイムのデフォルトにクリアされます。 CLI は有効なレベルを意図的に列挙しません — それらはランタイム/モデル固有です (Claude は現在 low|medium|high|xhigh|max を使用し、Pi は off|minimal|low|medium|high|xhigh|max を使用し、Codex の値はランタイムの モデルカタログから検出されます)。CLI はトークンを転送し、サーバーは プロバイダーの固定 enum または安全トークンゲートを適用し、デーモンが正確な モデル/レベルのチェックを実行します。プロバイダーに thinking の概念がない ランタイムは、空でない値を 400 で拒否します。

service_tier は、対応する Codex の第一級の速度制御です。これには 3 つの 異なる状態があります:

• 空はローカルの Codex 設定を継承することを意味します。
• default は明示的に Standard ルーティングを使用することを意味します。
• priority のようなランタイムカタログのティアは、明示的に Fast を 使用することを意味します。

作成/更新時に --service-tier <value> で設定します。更新時に --service-tier "" を使用するとクリアされます。ピッカーが default を 提供するのは、デーモンがインストールされている Codex CLI がリクエスト専用の 明示的 Standard センチネル(Codex 0.133.0 以降)をサポートしていると報告した 場合のみです。古いデーモンからの機能の欠如は、サポートされていないものとして 扱われます。ランタイムモデルカタログが、代替ティアの可用性と表示文言を 管理します。サーバーは安全な将来の Codex 値を受け入れますが、デーモンは 実行前に明示的 Standard 機能または正確なモデル/カタログティアのペアを検証し、 古い互換性のないオーバーライドを省略します。明示的なモデルを持たない エージェントでの代替カタログティアは、有効な config.toml のモデルが不明で あるため、依然としてフェイルクローズします。default は、ランタイム機能が 判明していればモデルに依存しません。

conversation_starters

この機能は製品上 Conversation starters（中文：对话开场建议）と呼ばれます。 人と話すときはこの名前を使ってください。ワイヤーフィールド conversation_starters は実装の詳細であり、ユーザーが目にすることはありません。ユーザーはエージェントの Instructions タブでこれらを設定します。ディープリンクは /<workspace>/agents/<id>?view=instructions&focus=conversation_starters です。

これらは、誰かがこのエージェントとの新しい Chat を開いたときに、コンポーザーの上に 表示される最大 3 つのラベル + プロンプトのペアです。1 つを選択すると コンポーザーに入力されるだけで、実行は開始されません。つまりこれらは提案であり、 アクションではありません。作成時にこのフィールドを省略すると [] がデフォルトになり、 更新時に省略すると保存済みの値が維持され、明示的に [] を指定するとクリアされます。 何も設定されていないエージェントでも、その空の状態では 3 つの組み込みの汎用デフォルトが 表示されるため、「Chat に提案が表示される」ことは、そのエージェントが独自の提案を 持っていることを意味しません。

model vs custom_args

model はデーモンが直接読み取る、ファーストクラスの永続化カラムです。 custom_args は通常、プロバイダー CLI の生の引数です。CLI のヘルプには、一部の プロバイダー（codex app-server、openclaw）が custom_args 内の --model を拒否すると 記載されていますが、それは CLI のドキュメント上のガイダンスであり、サーバーが強制する 不変条件ではありません。create ハンドラー内で custom_args に model フラグがないか 検査するものは何もありません。プロバイダーのバックエンドは、起動前にプロトコルの セレクターを消費することがあります。

• Pi は --thinking をフィルタリングします。これはファーストクラスの thinking_level フィールドがそのフラグを所有しており、その唯一のソースでなければ ならないためです。
• ZeroClaw は --agent <alias> / --agent-alias <alias>（=value 形式を含む）を消費し、 その値を ACP の session/new.agentAlias パラメーターとして送信します。 zeroclaw acp にはそのような CLI フラグはありません。ZeroClaw に複数のエージェントが あり、[acp].default_agent がない場合は、これらのカスタム引数のいずれかを設定して ください。エージェントが 1 つだけの構成では省略して、ZeroClaw がそのエージェントを 自動選択できるようにしてください。

認証情報やその他のシークレットを custom_args に入れないでください。デーモンの コマンドログは引数の値を伏せ字にしますが、バックエンドが消費しない値は依然として プロバイダープロセスの argv に残り、ps や /proc を通じて他のローカルプロセスから 見える可能性があります。プロバイダーの認証情報は代わりに custom_env に入れ、 可能であればその stdin または 0600 のファイル入力を使用してください。

Env & secrets

custom_env はシークレット素材です。CLI は 3 つの入力チャネルを提供しており、 そのうち 2 つはシークレットをシェル履歴やプロセスリストから遠ざけます。

multica agent create --name <name> --runtime-id <runtime-id> --custom-env-stdin --output json
multica agent create --name <name> --runtime-id <runtime-id> --custom-env-file <0600-json> --output json

--custom-env-stdin は stdin から JSON オブジェクトを読み取ります。 --custom-env-file はファイルから読み取ります（推奨モード 0600）。3 つ目のチャネル --custom-env <json> は値をコマンドライン上に置くため、シェル履歴や ps から 見えてしまいます。実際のシークレットには避けてください。

読み取り側の事実（避けるべき誤った想定）:

• エージェントのリソースが平文の custom_env を公開することは決してありません。 agent list/get/create/update および WS イベントは、has_custom_env（bool）と custom_env_key_count（int）のみを返します。
• 平文の値を読み取るには、専用の GET /api/agents/{id}/env エンドポイント （multica agent env get）が必要です。これはエージェント自身の人間のオーナー、 またはワークスペースのオーナー/管理者に制限されており、背後にあるメンバーの ロールに関係なく、エージェントアクターは拒否されます。実行中のエージェントは、 自分の人間が所有するものであっても、別のエージェントのシークレットを読み取ることは できません。
• 作成後に値を書き込む場合、agent update を経由しません。汎用の update ハンドラーは custom_env フィールドをすべて 400 で拒否します（「use PUT /api/agents/{id}/env」）。 平文の env の書き込みは PUT /api/agents/{id}/env（multica agent env set）で 処理され、同じゲートを備え、監査行を書き込みます。

mcp_config

mcp_config はエージェントの MCP サーバー設定です（{"mcpServers": {…}} のような JSON オブジェクト）。これはシークレット情報でもあり — MCP のエントリには API トークンが日常的に埋め込まれます — custom_env と同じ 3 つの入力チャネルを、agent create と agent update の両方で提供します:

multica agent create --name <name> --runtime-id <runtime-id> --mcp-config-file <0600-json> --output json
multica agent update <agent-id> --mcp-config-stdin --output json
multica agent update <agent-id> --mcp-config 'null'   # clears the config

--mcp-config-stdin / --mcp-config-file は値をシェル履歴や ps から守りますが、インラインの --mcp-config <json> は守りません。CLI は JSON のオブジェクトまたはリテラルの null を要求します。トップレベルの配列やプリミティブはクライアント側で拒否され、空の stdin/ファイル入力は暗黙にクリアするのではなくエラーになります。

mcp_config が custom_env と異なる 2 つの点:

• agent update で設定可能です。 custom_env と違い、mcp_config には専用の監査済みエンドポイントがありません — 汎用の PUT /api/agents/{id} がこれを受け付けます。生のリクエストボディに応じた三態: フィールド省略 → 変更なし、null → クリア、オブジェクト → 置換。
• 読み取り時にはシリアライズされますが、秘匿化されます。 agent get/list は、エージェントのシークレットを閲覧する権限を持つ呼び出し元にのみ mcp_config を返します。それ以外の場合、フィールドは null となり、mcp_config_redacted が true になります。エージェントアクターは決してこれを目にしませんし、ワークスペースが全員に対して秘匿化を強制することもあります。

プロバイダーのサポートは一律ではありません。Qwen Code は、--mcp-config で渡されるデーモン所有の 0600 の一時 JSON ファイルを通じて管理された mcp_config を受け付けます。これは実行終了時に削除されます。Qwen Code ネイティブの設定を継承するには、フィールドを未設定（null）のままにしてください。

ワークスペースの MCP サーバー

ワークスペースは MCP サーバーのライブラリを保持します（ワークスペースの Settings → MCP、または multica workspace mcp list|add|update|remove）。そこで追加しても、どのエージェントにも付与されません — ワークスペーススキルと同じ形です。誰かが割り当てたときにのみエージェントに届きます:

multica workspace mcp list --output table        # find the server id
multica agent mcp add <agent-id> <server-id>     # give it to one agent
multica agent mcp disable <agent-id> <server-id> # stop sending it, keep the assignment
multica agent mcp remove <agent-id> <server-id>  # take it away

クレーム時に有効なセットは次のとおりです:

レイヤー	エージェントに届く条件
ランタイムローカルのサーバー	常に（デーモンがランタイム自身のファイルをマージします）
ワークスペースのサーバー	このエージェントに割り当てられ、有効のままになっている場合
エージェント自身の mcp_config	常に。名前が衝突した場合はこちらが優先されます

エージェントの設定を書く前に知っておく価値のある 2 つの帰結: 共有サーバーを割り当てても mcp_config に再掲する必要はありません（マージされます）。そして mcp_config は今やそのエージェントに固有のサーバーに関するものだけです — 管理された空の {} はもはやワークスペースレイヤーについて何も意味しません。そもそも何も継承されないからです。

保存されたエントリは書き込み専用です — 読み取りはサーバーの名前とトランスポートを返すだけで、どのロールに対しても url、コマンド、ヘッダー、env を決して返しません。

スキルのバインド

エージェントの作成はどのワークスペーススキルもバインドしません — バインドはエージェントが存在した後の別の呼び出しです。2 つの異なる動詞:

• add は追加的です — 指定された id を既存のバインドにマージします（POST /api/agents/{id}/skills/add）。
• set は全置換です — バインドリスト全体を指定された id だけに上書きします（PUT /api/agents/{id}/skills）。--skill-ids '' はすべてをクリアします。

multica agent skills add <agent-id> --skill-ids <skill-id> --output json
multica agent skills list <agent-id> --output json

クレーム時にデーモンはエージェントのスキルを、まずワークスペースにバインドされたスキルとして組み立て、次にプラットフォーム組み込みのスキルを追加します。LoadAgentSkills はバインドされた各スキルの内容とそのサポートファイルを読み込みます。組み込みスキルはコンパイル時に埋め込まれ、SKILL.md とその兄弟ファイルから読み込まれます。どちらもスキルコンテンツとしてプロバイダーに届きます — だからこそケイパビリティは instructions に貼り付けるのではなく、バインドされたスキルに属するのです。

承認が必要な副作用

読み取り専用（安全）: agent get、agent skills list、agent env get。

状態を変更するもの（明示的な指示が必要 — 推測で実行しないでください）:

• multica agent create — 新しいエージェント行を挿入します。
• multica agent copy — 新しいエージェント行を挿入します（既存エージェントのフォーク）。ソースはそのまま残されます。
• multica agent skills add / set — バインドを変更します（set は破壊的です: 新しいリストにないバインドを破棄します）。
• multica agent env set — custom_env マップ全体を上書きし、監査行を書き込みます。

よくある誤った前提

• 「description がプロンプトである」いいえ、そうではありません。ランタイムに到達するのは instructions だけです。空の instructions に詳細な description を付けても、動作契約のない名前付きシェルが得られるだけです。
• 「Create はエージェントのスキルをバインドする」いいえ、しません。後で明示的にバインドしてください。
• 「agent update は env をローテーションできる」いいえ、できません。custom_env に対して 400 を返します。env エンドポイントを使用してください。
• 「mcp_config は更新時に custom_env と同じように動作する」いいえ、そうではありません。mcp_config は agent update（--mcp-config）で設定可能であり、--mcp-config null でクリアできます。専用の env エンドポイントの背後で制限されているのは custom_env のみです。
• 「agent get は env の値を表示する」いいえ、表示するのは has_custom_env と custom_env_key_count だけです。
• 「受け入れられるすべてのボディフィールドには CLI フラグがある」conversation_starters にはありません。agent create/agent update では設定できず、agent copy は既存の値を引き継ぐだけです。
• 「無効な thinking_level/model の組み合わせは作成時に検出される」検出されるのは不明なプロバイダーレベルのリテラルのみです。モデル固有の不整合は実行時に失敗します。
• 「set と add はスキルに対して互換である」set はすべてのバインディングを置き換えます。add のつもりで set を使うと、能力が黙って削除されます。

参照

references/creating-agents-source-map.md は、上記のすべての契約を現在のツリー上の file:line、ランタイムへの影響、および安全な読み取り専用の検証コマンドにマッピングしています。