Define your agent は「長いプロンプト」ではなく再利用できる設定資産を作る話

要点

要点まとめ

このページの本当の論点は、agent をその場の長文指示として扱うのをやめ、何度でも同じ形で使える設定として持てるようにしたことだ。
毎回チャットに似た説明を書き直す運用では、担当者ごとに少しずつ違う agent が増え、何が効いたかも何を変えたかも追いにくくなる。
公式は、使う model、system、tools、MCP servers、skills などをまとめた agent 定義を保存し、更新ごとに版を増やす構造を示している。
つまり managed agent の読みどころは人格づけではなく、再利用、比較、改版ができる実行設定を資産として持てるかどうかだ。

続けて読む

読み終えたら次へ

この1本で終わらせず、同じ目的・同じテーマ・近い原典へ進めます。

同じ目的で読む 作る前に確認したい

API や設定を試す前に、先に落とし穴を知りたい人向け。

同じテーマで読む AIエージェント

ツール利用、MCP、Agent SDK、長時間タスク、実行責任の設計。

次の記事 Safety checks は「危ない prompt を弾く」より先に危ない user を追えるようにせよと迫る

この guide の主題は、moderation のように 1 回ごとの入出力を見るだけではなく、繰り返し高リスク利用をしている end user を product 側で追えるようにすることだ。

読解

何が変わったのか

原典は agent を reusable, versioned configuration と定義しています。reusable は何度でも同じ形で呼び直せること、versioned は更新のたびに版を増やせること、configuration resource は会話ログとは別に保存される設定単位という意味です。中身も persona prompt だけでなく、`model`、`system`、`tools`、`mcp_servers`、`skills`、`multiagent`、`metadata` まで含みます。managed agent は prompt 断片ではなく、呼び出し可能な構成物として扱う前提へ寄っています。

日本の文脈

なぜ重要か

日本の小規模開発では、agent の定義が README、チャット履歴、口頭共有に散りやすいです。その状態では、うまくいった agent を別担当者が再利用できず、何を変えたら壊れたかも追いにくい。versioned resource として分離すると、少なくとも『何を固定し、何を変えたか』を比較できます。workflow packaging の観点でも、商品になるのは一発の prompt ではなく、再利用可能な設定と運用手順の組み合わせだと理解しやすくなります。

技術ポイント

技術的ポイント

agent は reusable, versioned configuration resource であり、persona だけでなく capabilities も含む設定単位である。
構成要素には `model`、`system`、`tools`、`mcp_servers`、`skills`、`multiagent`、`metadata` があり、会話中の依頼文と常設ルールを分離できる。
create 後の response には `id`、`version`、`created_at`、`updated_at`、`archived_at` が付き、どの版で動いた session かを追跡しやすい。
update semantics が重要で、scalar fields は置換、array fields は fully replaced、metadata は key 単位 merge、no-op なら新 version なし、という挙動になる。
multiagent の coordinator roster は subagent 更新へ自動追随しないことがあり、構成差分の見落としが運用事故につながる。

用語

英日キーワード

英語	日本語	補足
reusable resource	再利用可能な資産	session をまたいで同じ形で呼び出せる設定単位。一回限りの会話指示と分けて管理する。
versioned configuration	版管理された設定	更新のたびに版を増やし、どの構成で動いたか追跡できる設定。
system prompt	システムプロンプト	agent の常設ルールを置く指示。各 session の user message とは役割が違う。
MCP servers	MCPサーバー群	agent から接続する標準化された外部機能群。構成定義に含めると接続責任を追いやすい。
skills	スキル	領域固有の手順や文脈を与える再利用部品。agent 定義に含めると運用再現性が上がる。
update semantics	更新規則	どの項目が置換で、どの項目が併合かを決めるルール。managed agent の改版事故を減らす。

試す

試すなら

今使っている agent 的な長文指示を分解し、model、system、tools、MCP、skills のどれに属するか整理する。
使い回したい役割を 1 つ選び、session ごとの気分的プロンプトではなく versioned agent resource として定義する。
update 時は array fields が丸ごと置き換わる前提で差分確認し、『何を追加したつもりで何を落としたか』をレビューする。

注意

注意点

agent resource に切り出しても、done 条件や評価基準まで自動で整うわけではない。設定資産化と成果判定は別問題である。
version が増えるだけでは安全ではない。どの version をどの session や coordinator が参照しているか追えなければ、古い構成のまま動き続ける。

この記事は役に立ちましたか

公益的に続けるため、役に立った点や読みづらかった点だけを短く送れます。メールアドレスは不要です。