エージェントを定義する

エージェントは、ペルソナと機能を定義する、再利用可能でバージョン管理された設定です。モデル、システムプロンプト、ツール、MCPサーバー、スキルをまとめたもので、セッション中のClaudeの動作を形作ります。

エージェントを再利用可能なリソースとして一度作成し、セッションを開始するたびにIDで参照します。エージェントはバージョン管理されており、多数のセッションにわたって管理しやすくなっています。



エージェント設定フィールド

エージェントを変更せずに、単一のセッションに対してmodel、system、tools、mcp_servers、skillsをオーバーライドすることもできます。セッションのエージェント設定をオーバーライドするを参照してください。



エージェントを作成する

次の例では、事前構築済みエージェントツールセットにアクセスできるClaude Opus 4.8を使用するコーディングエージェントを定義します。このツールセットにより、エージェントはコードの記述、ファイルの読み取り、ウェブ検索などを実行できます。サポートされているツールの完全なリストについては、エージェントツールリファレンスを参照してください。

例ではcurl、ant CLI、またはいずれかのSDKを使用しています。まだセットアップしていない場合は、クイックスタートでインストールとクライアントのセットアップについて説明しています。

agent=$(ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-8}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}' \
  --format json)

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")

レスポンスには設定内容がそのまま返され、id、type、version、created_at、updated_at、archived_atフィールドが追加されます。versionは1から始まり、更新によってエージェントが変更されるたびにインクリメントされます。

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-4-8",
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "skills": [],
  "mcp_servers": [],
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

ツールセットのdefault_configには、デフォルトの権限ポリシーであるalways_allowが表示されます。これは、ポリシーを設定しない限り適用されます。



エージェントを更新する

エージェントを更新すると、設定が変更された場合に新しいバージョンが生成されます。versionフィールドは必須で、エージェントの現在のバージョンと一致する必要があるため、常に既知の状態から更新することになります。バージョンが一致しない場合は409が返され、アーカイブされたエージェントへの更新は拒否されます。

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --system "You are a helpful coding agent. Always write tests."



更新のセマンティクス

• 省略されたフィールドは保持されます。 変更したいフィールドのみを含めれば十分です。

• スカラーフィールド（model、system、name、description）は新しい値で置き換えられます。systemとdescriptionはnullを渡すことでクリアできます。modelとnameは必須であり、クリアできません。

• 配列フィールド（tools、mcp_servers、skills）は新しい配列で完全に置き換えられます。配列フィールドを完全にクリアするには、nullまたは空の配列を渡します。

• **multiagent**は、そのagentsロスターを含めて全体として置き換えられます。クリアするにはnullを渡します。

• メタデータはキーレベルでマージされます。指定したキーは追加または更新されます。省略したキーは保持されます。特定のキーを削除するには、その値をnullに設定します。

• 変更なしの検出。 更新が現在のバージョンに対して変更を生じない場合、新しいバージョンは作成されず、既存のバージョンが返されます。

• コーディネーターのロスターは更新されません。 multiagent.agentsロスターでこのエージェントを参照しているコーディネーターは、参照がversionを省略している場合でも、コーディネーターが作成または最後に更新されたときに固定されたバージョンを保持します。新しいバージョンに委任するには、コーディネーターを更新して、そのロスターが新しいバージョンを参照するようにします。



エージェントのライフサイクル



バージョンを一覧表示する

完全なバージョン履歴を取得して、エージェントが時間の経過とともにどのように変更されたかを追跡します。結果はページ分割されており、SDKの例ではすべてのページを自動的に取得します。

ant beta:agents:versions list --agent-id "$AGENT_ID"



エージェントをアーカイブする

アーカイブするとエージェントは読み取り専用になり、元に戻すことはできません。既存のセッションは引き続き実行されますが、新しいセッションはこのエージェントを参照できません。レスポンスではarchived_atにアーカイブのタイムスタンプが設定されます。

ant beta:agents archive --agent-id "$AGENT_ID"



次のステップ