エージェントを定義する

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

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

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

エージェントを作成する

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

レスポンスは設定をエコーバックし、id、version、created_at、updated_at、およびarchived_atフィールドを追加します。versionは1から始まり、エージェントを更新するたびにインクリメントされます。

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-4-7",
    "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
}

エージェントを更新する

エージェントを更新すると、新しいバージョンが生成されます。既知の状態から更新していることを確認するために、現在のversionを渡します。

更新セマンティクス

• 省略されたフィールドは保持されます。 変更したいフィールドのみを含める必要があります。

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

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

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

バージョンをリスト

完全なバージョン履歴を取得して、エージェントが時間の経過に伴いどのように変更されたかを追跡します。

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

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

次のステップ

• ツールを設定して、エージェントが使用できる機能をカスタマイズします。
• スキルを添付して、ドメイン固有の専門知識を得ます。
• セッションを開始して、エージェントを参照します。

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