⬡ API & SDK/2026-04-10上級

Claude Managed Agents 本番アーキテクチャ設計ガイド — サンドボックス実行・永続メモリ・認証管理・コスト最適化の実装パターン

Claude Managed Agentsを本番環境で運用するための設計パターンを徹底解説。サンドボックス実行、永続メモリ、認証情報管理、マルチエージェント連携、コスト最適化まで網羅します。

managed-agents³ production⁸⁶ architecture¹¹ api⁵⁸ enterprise¹³ security¹²

✦ プレミアム記事

Claude Managed Agents を本番で使いこなすために

2026年4月にパブリックベータとして公開された Claude Managed Agents は、クラウドホスト型のエージェント基盤として大きな注目を集めています。サンドボックス実行、永続メモリ、認証情報管理、エンドツーエンドのトレース機能が組み込まれており、従来は数ヶ月かかっていたエージェント開発を数週間に短縮できるプラットフォームです。

しかし、プロトタイプから本番環境への移行には、設計上の重要な判断が数多く存在します。セキュリティ要件をどう満たすか、永続メモリをどう設計するか、複数エージェントの協調をどう実現するか、そしてランタイム課金をどう最適化するか——ここで扱うのはこれらの課題に対する実践的な設計パターンを体系的に解説します。

なお、Managed Agents の基本概念や導入手順については「Claude Managed Agents 完全ガイド」で解説していますので、そちらを先にご確認いただくとスムーズです。

サンドボックス実行環境の設計パターン

Managed Agents の実行環境は、各エージェントが完全に分離されたサンドボックス内で動作します。これにより、エージェントが外部システムに予期しない影響を与えるリスクを最小化しつつ、必要なツールやリソースへのアクセスを細かく制御できます。

実行環境の構成

サンドボックスには以下のコンポーネントが含まれます。

コード実行ランタイム: Python / Node.js / シェルスクリプトの実行が可能
ファイルシステム: エージェント固有の一時ストレージ（セッション終了時に自動消去）
ネットワークアクセス: 許可リストベースの外部API呼び出し
ツールバインディング: MCP サーバーやカスタムツールの動的接続

本番環境では、これらを明示的に制限するセキュリティポリシーの設定が必須です。

// エージェント作成時のサンドボックス設定例
import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const agent = await client.agents.create({
  name: "data-processor",
  model: "claude-sonnet-4-6",
  instructions: "データ処理専用エージェント。外部APIとの通信は許可リスト内のみ。",
  sandbox: {
    // ネットワークアクセスの許可リスト
    allowed_domains: [
      "api.internal.example.com",
      "storage.googleapis.com"
    ],
    // ファイルシステムの制限
    filesystem: {
      max_size_mb: 512,
      writable_paths: ["/workspace", "/tmp"],
      read_only_paths: ["/config"]
    },
    // 実行時間の上限（秒）
    max_runtime_seconds: 3600,
    // メモリ上限
    max_memory_mb: 2048
  },
  tools: [
    { type: "code_execution" },
    { type: "mcp", server_url: "https://mcp.internal.example.com/data" }
  ]
});
 
console.log(`Agent created: ${agent.id}`);
// 出力例: Agent created: agent_01JZ8K...

本番向けのセキュリティ階層

本番デプロイでは、以下の3階層でセキュリティを構成することを推奨します。

第1層 — エージェントレベルの制限として、上記コード例のようにサンドボックス設定でネットワーク・ファイル・ランタイムを制限します。第2層 — 認証スコープの最小化として、後述するクレデンシャル管理機能で各エージェントに必要最小限の権限のみを付与します。第3層 — 監視とアラートとして、OpenTelemetry トレースとログ連携により異常な動作を即座に検知します。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦Managed Agentsの本番デプロイで認証やメモリ設計に悩んでいた方が、セキュアで拡張性の高いアーキテクチャを即座に構築できるようになる

✦サンドボックス実行環境とチェックポイント機構の仕組みを理解し、障害時にも状態を失わないリカバリ可能なエージェントを実装できる

✦エージェントランタイム課金（$0.08/h）の仕組みを把握し、アイドルコスト削減・バッチ処理最適化で月額費用を40〜60%削減する具体的手法を習得できる

Stripe による安全な決済 · いつでもキャンセル可能

永続メモリの設計と実装

Managed Agents の最も強力な機能の一つが、セッションをまたいでコンテキストを保持する永続メモリです。エージェントが過去のやりとりや学習結果を記憶し、次回のインタラクションで活用できます。

メモリアーキテクチャの設計

永続メモリは3つの層で設計するのが実用的です。

// メモリ設計のアーキテクチャパターン
const agent = await client.agents.create({
  name: "customer-support-agent",
  model: "claude-sonnet-4-6",
  instructions: `
    あなたは顧客サポートエージェントです。
    過去の対話履歴を参照し、顧客の状態を把握した上で応答してください。
  `,
  memory: {
    // 短期メモリ: 現在のセッション内の対話コンテキスト
    short_term: {
      enabled: true,
      max_turns: 50
    },
    // 中期メモリ: ユーザー固有の状態（チケット、嗜好、対話パターン）
    medium_term: {
      enabled: true,
      storage: "per_user",
      ttl_days: 90,
      max_entries: 1000
    },
    // 長期メモリ: 組織レベルのナレッジ（FAQ、ポリシー、製品情報）
    long_term: {
      enabled: true,
      storage: "shared",
      source: "knowledge_base",
      refresh_interval_hours: 24
    }
  }
});

チェックポイントによる状態復元

長時間実行されるエージェントタスクでは、チェックポイント機構を活用して中断からの復元を可能にします。これは障害復旧だけでなく、コスト最適化にも直結します（後述のアイドルタイム削減で解説します）。

// チェックポイント付きのタスク実行
const session = await client.agents.sessions.create({
  agent_id: agent.id,
  checkpoint: {
    enabled: true,
    interval_seconds: 300, // 5分ごとにチェックポイント
    max_checkpoints: 10
  }
});
 
// タスクの実行
const result = await client.agents.sessions.run(session.id, {
  messages: [
    {
      role: "user",
      content: "過去30日間の売上データを分析し、レポートを生成してください"
    }
  ]
});
 
// 中断からの復元（障害発生時やタイムアウト後）
if (result.status === "interrupted") {
  const resumed = await client.agents.sessions.resume(session.id, {
    from_checkpoint: "latest"
  });
  console.log(`Resumed from checkpoint: ${resumed.checkpoint_id}`);
  // 出力例: Resumed from checkpoint: ckpt_01JZ9M...
}

メモリ設計のアンチパターン

本番運用で頻出する失敗パターンを共有します。

アンチパターン1: 無制限のメモリ蓄積。中期メモリの max_entries を設定せずに運用すると、コンテキストウィンドウのトークン消費が増大し、レスポンス遅延とコスト増加を招きます。必ずTTLとエントリ上限を設定してください。

アンチパターン2: 全データをメモリに格納。構造化データ（商品カタログ、在庫情報など）はメモリではなく外部データベースに保持し、MCP ツール経由で参照する設計にします。メモリには「このユーザーは前回〇〇を質問した」といったコンテキスト情報のみを格納します。

アンチパターン3: チェックポイント間隔の不適切な設定。間隔が短すぎるとI/Oオーバーヘッドが増加し、長すぎると障害時のデータロスが大きくなります。タスクの特性に応じて、5〜15分の範囲で調整するのが実用的です。

認証情報管理とスコープ付き権限

本番環境でエージェントを運用する際、最も慎重に設計すべきなのが認証情報の管理です。Managed Agents にはクレデンシャル管理機能が組み込まれており、APIキーやOAuthトークンをエージェントに安全に渡すことができます。

クレデンシャルの登録と使用

// シークレットの登録（管理者が事前に実行）
await client.agents.secrets.create({
  agent_id: agent.id,
  name: "GITHUB_TOKEN",
  value: process.env.GITHUB_PAT, // 環境変数から取得
  scope: "session", // セッション単位でのみアクセス可能
  permissions: ["read"] // 読み取り専用
});
 
await client.agents.secrets.create({
  agent_id: agent.id,
  name: "DATABASE_URL",
  value: process.env.DATABASE_URL,
  scope: "agent", // エージェント全体で共有
  permissions: ["read"]
});
 
// エージェント内でのシークレット使用（コード実行ツール内）
// エージェントは $GITHUB_TOKEN として環境変数でアクセスできる
// ただし、エージェントの応答テキストにシークレットが漏洩しないよう
// 自動フィルタリングが適用される

最小権限の原則を実装する

エンタープライズ環境では、エージェントごとにアクセスできるリソースを厳密に制限する「スコープ付き権限」が重要です。

// 権限設計の例: 営業レポートエージェント
const salesAgent = await client.agents.create({
  name: "sales-report-agent",
  model: "claude-sonnet-4-6",
  instructions: "月次営業レポートを生成するエージェント",
  permissions: {
    // データソースへのアクセス制御
    data_access: [
      {
        resource: "crm_api",
        operations: ["read"],
        filters: { department: "sales" }
      },
      {
        resource: "analytics_db",
        operations: ["read"],
        filters: { tables: ["revenue", "pipeline", "forecasts"] }
      }
    ],
    // 出力先の制御
    output_destinations: [
      { type: "file", path: "/reports/" },
      { type: "api", endpoint: "https://slack.internal/webhook" }
    ],
    // 他のエージェントとの通信制御
    agent_communication: {
      can_spawn: false, // サブエージェントの生成は不可
      can_message: ["analytics-agent"] // 分析エージェントとのみ通信可
    }
  }
});

マルチエージェント連携の設計パターン

Managed Agents の Research Preview 機能として、エージェントが他のエージェントを動的にスポーン（生成）する機能が提供されています。複雑なタスクを専門化されたサブエージェントに分割して処理させるパターンです。

オーケストレーターパターン

最も一般的な連携パターンは、1つのオーケストレーターエージェントが複数の専門エージェントを協調させる構成です。

// オーケストレーターエージェントの設計
const orchestrator = await client.agents.create({
  name: "project-orchestrator",
  model: "claude-sonnet-4-6",
  instructions: `
    あなたはプロジェクト管理のオーケストレーターです。
    ユーザーのリクエストを分析し、適切な専門エージェントに作業を委任してください。
    
    利用可能な専門エージェント:
    - code-reviewer: コードレビューと品質チェック
    - test-generator: テストコードの自動生成
    - doc-writer: ドキュメント・APIリファレンスの作成
    - security-auditor: セキュリティ脆弱性の検出
    
    各エージェントの結果を統合し、最終レポートを作成してください。
  `,
  sub_agents: {
    enabled: true,
    max_concurrent: 3,
    allowed_agents: [
      "code-reviewer",
      "test-generator",
      "doc-writer",
      "security-auditor"
    ],
    timeout_seconds: 600
  }
});
 
// オーケストレーターへのタスク投入
const result = await client.agents.sessions.run(
  orchestratorSession.id,
  {
    messages: [{
      role: "user",
      content: `
        以下のPRをレビューしてください: https://github.com/org/repo/pull/42
        コードレビュー、テスト生成、ドキュメント更新、セキュリティ監査を
        並行して実施し、統合レポートを作成してください。
      `
    }]
  }
);
 
// result.sub_agent_results で各エージェントの結果を確認可能

パイプラインパターン

データ処理のように、ステージを順次実行するパイプラインパターンも有効です。

// パイプライン型マルチエージェント
const pipeline = await client.agents.pipelines.create({
  name: "data-etl-pipeline",
  stages: [
    {
      agent: "data-extractor",
      input: "raw_data_url",
      output: "extracted_data",
      retry: { max_attempts: 3, backoff: "exponential" }
    },
    {
      agent: "data-transformer",
      input: "extracted_data",
      output: "transformed_data",
      checkpoint: true // ステージ間でチェックポイント保存
    },
    {
      agent: "data-validator",
      input: "transformed_data",
      output: "validated_data",
      on_failure: "pause" // バリデーション失敗時は停止
    },
    {
      agent: "report-generator",
      input: "validated_data",
      output: "final_report"
    }
  ]
});
 
// パイプラインの非同期実行
const run = await client.agents.pipelines.run(pipeline.id, {
  raw_data_url: "https://storage.example.com/sales-2026-q1.csv"
});
 
// 各ステージの進捗をポーリング
const status = await client.agents.pipelines.get_status(run.id);
console.log(`Current stage: ${status.current_stage}`);
console.log(`Progress: ${status.completed_stages}/${status.total_stages}`);
// 出力例: Current stage: data-transformer
// 出力例: Progress: 1/4

連携時のエラーハンドリング

マルチエージェント環境で最も重要なのは、部分的な障害に対する回復力（レジリエンス）です。

// エラーハンドリング付きオーケストレーション
const runWithRecovery = async (orchestratorSessionId, task) => {
  try {
    const result = await client.agents.sessions.run(
      orchestratorSessionId,
      { messages: [{ role: "user", content: task }] }
    );
    
    // サブエージェントの結果を個別にチェック
    for (const subResult of result.sub_agent_results || []) {
      if (subResult.status === "failed") {
        console.warn(
          `Sub-agent ${subResult.agent_name} failed: ${subResult.error}`
        );
        // 失敗したサブエージェントのタスクをリトライ
        await client.agents.sessions.retry_sub_agent(
          orchestratorSessionId,
          subResult.agent_name,
          { max_retries: 2 }
        );
      }
    }
    
    return result;
  } catch (error) {
    if (error.status === 429) {
      // レートリミット: エクスポネンシャルバックオフで待機
      const waitMs = Math.pow(2, retryCount) * 1000;
      await new Promise(r => setTimeout(r, waitMs));
      return runWithRecovery(orchestratorSessionId, task);
    }
    throw error;
  }
};

OpenTelemetry によるオブザーバビリティ

本番環境のエージェントシステムでは、動作の可視化が不可欠です。Managed Agents は OpenTelemetry との統合を標準でサポートしています。

トレースの設定

// OpenTelemetry トレース設定
const agent = await client.agents.create({
  name: "monitored-agent",
  model: "claude-sonnet-4-6",
  instructions: "本番監視付きエージェント",
  observability: {
    tracing: {
      enabled: true,
      exporter: {
        type: "otlp",
        endpoint: "https://otel-collector.internal:4317",
        headers: {
          "Authorization": "Bearer ${OTEL_TOKEN}"
        }
      },
      // トレース対象のイベント
      events: [
        "session.start",
        "session.end",
        "tool.call",
        "tool.result",
        "sub_agent.spawn",
        "sub_agent.complete",
        "checkpoint.save",
        "checkpoint.restore",
        "error"
      ],
      // サンプリングレート（本番では10〜20%を推奨）
      sampling_rate: 0.1
    },
    // メトリクスの収集
    metrics: {
      enabled: true,
      interval_seconds: 60,
      custom_metrics: [
        "tokens_used",
        "runtime_seconds",
        "tools_called",
        "sub_agents_spawned"
      ]
    }
  }
});

本番監視ダッシュボードの設計

エージェントシステムの監視では、以下のメトリクスを最優先で追跡します。

応答レイテンシ: P50 / P95 / P99 の分布。突然の増加はメモリ肥大化やツール障害の兆候
トークン消費量: セッションあたりの入力/出力トークン数。コスト予測と異常検知に直結
ランタイム時間: エージェントのアクティブ時間。課金に直接影響するため最重要
エラー率: ツール呼び出し失敗、タイムアウト、レートリミットの発生頻度
チェックポイント復元率: 障害からの自動復旧が正常に機能しているかの指標

コスト最適化の実践手法

Managed Agents の課金は「Claude モデル使用料 + エージェントランタイム $0.08/時間」の二重構造です。本番環境ではこの両方を最適化する必要があります。

ランタイムコストの削減

// コスト最適化パターン1: アイドルタイムの最小化
const session = await client.agents.sessions.create({
  agent_id: agent.id,
  lifecycle: {
    // アイドル検出: 指定時間無操作で自動サスペンド
    idle_timeout_seconds: 120,
    // サスペンド時はチェックポイントを保存して課金停止
    on_idle: "suspend_with_checkpoint",
    // 新しいメッセージが来たら自動復帰
    on_resume: "restore_from_checkpoint"
  }
});
 
// コスト最適化パターン2: バッチ処理でランタイムを集約
const batchRun = await client.agents.batch.create({
  agent_id: agent.id,
  tasks: [
    { id: "task-1", content: "レポートAを生成" },
    { id: "task-2", content: "レポートBを生成" },
    { id: "task-3", content: "レポートCを生成" }
  ],
  // 同一セッション内で逐次処理（セッション起動コストを1回に抑える）
  execution: "sequential_in_session",
  // 優先度を下げてコスト削減（50%オフの可能性）
  priority: "low"
});

トークンコストの削減

// コスト最適化パターン3: プロンプトキャッシュの活用
const agent = await client.agents.create({
  name: "cost-optimized-agent",
  model: "claude-sonnet-4-6",
  instructions: "コスト最適化されたエージェント",
  optimization: {
    // プロンプトキャッシュ: 共通のシステムプロンプトをキャッシュ
    prompt_caching: {
      enabled: true,
      // キャッシュTTL（5分以内の再利用で90%削減）
      ttl_seconds: 300
    },
    // コンテキスト圧縮: 長い対話履歴を自動要約
    context_compression: {
      enabled: true,
      trigger_tokens: 50000, // 50Kトークン超で圧縮開始
      target_tokens: 20000   // 20Kトークンに要約
    },
    // モデル選択の最適化
    model_routing: {
      // 簡単なタスクにはHaikuを使用
      simple_tasks: "claude-haiku-4-5",
      // 複雑なタスクにはSonnetを使用
      complex_tasks: "claude-sonnet-4-6",
      // 判断基準のしきい値
      complexity_threshold: 0.7
    }
  }
});

コスト試算の具体例

月間コストを試算してみましょう。営業レポートエージェントが1日10回起動し、各回平均15分稼働する場合を想定します。

ランタイム費用: 10回 × 0.25時間 × $0.08/h × 30日 = $6/月
モデル使用料（Sonnet 4.6、平均10Kトークン/回）: 10回 × $0.03 × 30日 = $9/月
合計: 約 $15/月

アイドルタイム最小化とバッチ処理を適用すると、ランタイムを約40%削減できます。さらに、簡単なタスクへの Haiku ルーティングでモデル使用料を約50%削減し、合計で $8〜9/月 まで圧縮可能です。

エンタープライズ統合パターン

Managed Agents をエンタープライズの既存システムに統合する際の実践パターンを解説します。

既存の認証基盤との統合

// OAuth 2.0 / SAML との統合例
const enterpriseAgent = await client.agents.create({
  name: "enterprise-assistant",
  model: "claude-sonnet-4-6",
  instructions: "社内アシスタントエージェント",
  auth: {
    // 企業のIdPと統合
    provider: "oauth2",
    issuer: "https://auth.example.com",
    audience: "managed-agents",
    // ユーザーのトークンをエージェントセッションに紐付け
    user_token_propagation: true,
    // RBAC: ユーザーのロールに基づいてエージェントの権限を制限
    role_mapping: {
      "admin": { data_access: "full", can_spawn_agents: true },
      "manager": { data_access: "department", can_spawn_agents: false },
      "member": { data_access: "own", can_spawn_agents: false }
    }
  }
});

ログ監査とコンプライアンス

金融・医療・行政など規制対象の業種では、エージェントの全アクションを監査ログとして保存する必要があります。

// 監査ログの設定
const complianceAgent = await client.agents.create({
  name: "compliance-agent",
  model: "claude-sonnet-4-6",
  instructions: "コンプライアンス準拠エージェント",
  audit: {
    enabled: true,
    // 全入出力を暗号化して保存
    log_messages: true,
    log_tool_calls: true,
    log_tool_results: true,
    // 保存先（S3互換ストレージ）
    destination: {
      type: "s3",
      bucket: "audit-logs-managed-agents",
      prefix: "compliance/",
      encryption: "AES-256"
    },
    // 保持期間（規制要件に合わせて設定）
    retention_days: 2555, // 7年
    // PII（個人情報）のマスキング
    pii_masking: {
      enabled: true,
      fields: ["email", "phone", "ssn", "credit_card"]
    }
  }
});