指示文と説明

エージェントには、人が見る値と実行に使われる値が別々にある。

名前と説明は、一覧や詳細画面でエージェントを見分けるための値である。どちらもモデルには渡されない。エージェントの仕事の進め方は、リポジトリの AGENTS.md か CLAUDE.md に書く。

仕事の進め方はリポジトリのファイルに書く見出しのリンクをコピー

エージェントに仕事の進め方、答え方、守るべきルールを伝える方法はひとつである。セッションが作業するリポジトリのルートに AGENTS.md (なければ CLAUDE.md) を置く。カードには、そのような文章を入れる欄がない。

• ファイルはリポジトリにコミットする。セッションは開始時にコミットされた内容を読むので、ファイルを直すと新しいセッションから変わる。バージョンやリリースを作る必要はない。
• プロファイルが project_settings.claude_md: true のときだけ読む。オフならファイルがあってもモデルには渡されない。設定はプロファイル詳細の「リポジトリの CLAUDE.md を読む」でオンにする。ローカルプロファイル claude-coding-local ではオンになっている。
• セッションは開始したリポジトリのファイルを読むので、同じリポジトリのエージェントは同じファイルを共有する。

書き方見出しのリンクをコピー

エージェントの役割は作成者が決める。プラットフォームは役割や性格を決める文を入れず、プラットフォームだけが知る事実だけを伝える。その内容は現在モデルが読むものにある。

• 経験年数や誇張した修飾を書かない。「経験 30 年の最高のシニア開発者」のような言葉は、何を担当するのかを伝えない。
• 担当範囲は一行で書く。
• 許可する行動は具体的な動詞で書き、理由を添える。理由があれば、書いていない状況でも同じ基準で判断できる。

決済障害の分析を担当する。
ログを読んで原因を要約する。
変更は担当チームがレビューするので、コードは修正しない。

以前のカードの値見出しのリンクをコピー

以前のカードには「ロール」(role) と「指示事項」(instructions) の欄があり、その後に「エージェント指示文」(agent_instructions) の欄ができた。前の 2 つはモデルに渡されたことがなく、エージェント指示文の欄は廃止した。

• 新しく作るカードはこれらの値を送らない。すでに保存されたバージョンの値は残るが、画面には表示されず、実行にも使われない。
• 古いクライアントが agent_instructions を送っても、リクエストは拒否されない。そのキーは捨てられ、保存されない。
• エージェント指示文に書いていた内容を使い続けるには、リポジトリの AGENTS.md か CLAUDE.md に移す。

カードのフィールド見出しのリンクをコピー

名前 (1〜120 文字) と説明 (0〜2,000 文字) はカードではなくエージェントのフィールドである。POST /v1/agents と PATCH /v1/agents/{id} に name・description として送る。

Web コンソールでツールを選ぶ見出しのリンクをコピー

カードの編集 (新しいエージェントの「役割」ステップ、エージェント詳細の詳細設定の編集) の「使用できるツール」は、プロファイル 1 つのツールのチェックリストである。

• 「ツールを表示するプロファイル」: カードのモデルを実行するプロファイルからひとつ選ぶ。新しいエージェントの流れでは、リポジトリなしでリリースできるプロファイルを先に並べ、選んだプロファイルをリリースのステップで先に選んでおく。この値はカードに保存しない。
• 「リリース時にプロファイルがブロックしていないすべてのツール」がオンなら tools: null である。オフにすると、チェックしたツールが tools になる。チェックを外すことが禁止である。
• 保存するとき、チェックを外した組み込みツールの tool_policy.per_tool の項目を消す。リリースは実行しない組み込みツールのポリシーを拒否するためである。MCP ツールのポリシーは残る。
• tools にプロファイルにない名前があれば「プロファイルにないツール」としてチェックされたまま表示され、オフにすることだけができる。
• 一覧の下に、選んだツールをすべて許可するプロファイルの数が出る。0 なら保存できない。
• 既存のカードに forbidden があれば一覧で表示され、「禁止ツールを消す」で空にできる。空にするまでは、チェックリストのそのツールはオフのまま変更できない。

現在モデルが読むもの見出しのリンクをコピー

worker がモデルのシステムプロンプトに追加する指示は、この順序である。

1. リポジトリのないセッションでは、out/ がチェックポイントが成果物として集めるディレクトリであるという事実の 1 行。
2. リポジトリルートの AGENTS.md。なければ CLAUDE.md。プロファイルが project_settings.claude_md: true のとき、コミットされた内容を読む。CLAUDE.md が AGENTS.md へのリンクである場合や @AGENTS.md の 1 行だけの場合は、一度だけ読む。ローカルプロファイル claude-coding-local では有効になっている。

1 の文章は、ワークスペースのルートにも AGENTS.md として置かれ、CLAUDE.md はそのファイルへのリンクになる。どちらも .git/info/exclude に入るため、コミットには混ざらない。リポジトリがすでに AGENTS.md か CLAUDE.md を持っている場合は、上書きしない。その場合も、モデルは同じ文章をシステムプロンプトとして受け取る。

プラットフォームは、これ以外の段落をモデルに追加しない。役割や振る舞いを決める文はプラットフォームが書かず、事実だけを伝える。以前のビルドが追加していたプラットフォーム段落はなくなった。その段落で作ったチェックポイントのフィンガープリントは worker が引き続き認識するので、既存のセッションもそのまま再開される。

修正とバージョン見出しのリンクをコピー

カードを送ると、PATCH /v1/agents/{id} が新しいバージョンを追加する。名前や説明だけを変えるときは name・description だけを送る。このときバージョンは作られない。すでにあるバージョンと同じカードを送った場合は何も追加されない。作成の AID と WEB を引き続き使う。

curl -sS -X PATCH "$API/v1/agents/$AID" "${WEB[@]}" -d '{
  "description": "リポジトリを読んで質問に答える",
  "card": {
    "model": "claude-sonnet-5",
    "language": "en",
    "capabilities": { "tools": ["Read", "Grep", "Glob"], "mcp": null },
    "rules": [{ "id": "no-guess", "text": "Never invent a file path.", "source": "user" }]
  }
}' | jq -c '.versions[] | {version_no, language: .card.language}'

{"version_no":1,"language":"follow-user"}
{"version_no":2,"language":"en"}

新しいバージョンは有効なリリースを変更しない。使うには、そのバージョンでリリースを作成して有効化する (作成)。Web コンソールでは、詳細設定の「保存」が同じ処理を行い、2 つのバージョンの差分を表示する。

次のステップ見出しのリンクをコピー

• プロファイルを選ぶ: リリースとセッションが使うプロファイル
• 権限: ツール権限とエージェント管理者