Managed AgentsのスケジュールデプロイをAWSのIAMロールで動かす

Claude Platform on AWSでスケジュールデプロイを作るなら、先にエージェント側へexecution_identityを設定します。これが無いエージェントでデプロイを作ると、400エラーが返ります。cron式やタイムゾーンを直しても解消しません。

スケジュールデプロイは2026年10月14日にClaude Platform on AWSへ対応しました。この記事は、その対応で増えたAWS側の準備を、IAMロールの作り方から手動実行での確認までたどります。cron式そのものの設計はManaged Agentsのスケジュールデプロイをcronで定期実行するにあります。

何が違うのか — 各実行はIAMロールとしてセッションを作る

Claude Platform on AWSでは、デプロイの各実行が、AWSアカウント内のIAMロールとしてセッションを作成します。誰のアカウントの、どのロールで動くのかを、実行のたびに決める必要があるわけです。

そのロールを指すのが、エージェントのexecution_identityです。

{
  "type": "aws_role",
  "role_arn": "arn:aws:iam::123456789012:role/example-role"
}

この値はデプロイではなくエージェントに置きます。デプロイの作成時にチェックされ、無ければ400になります。

準備は3つに分かれます。

手順1: アカウントでWeb ID連携を有効にする

ロールを作る前に、AWSアカウント側の前提を確認します。Claude Platform on AWSのゲートウェイは、サーバー側でsts:GetWebIdentityTokenを呼んでJWTを発行します。この機能はAWSアカウントごとに既定で無効です。

aws iam enable-outbound-web-identity-federation
aws iam get-outbound-web-identity-federation-info

有効化は1アカウントにつき1回です。すでに有効ならFeatureEnabledのエラーが返るので、そのまま次へ進めます。無効のままだと、最初のAPI呼び出しからOutbound web identity federation is disabled for your accountが返ります。公式はこれを最も多いセットアップエラーとしています。デプロイ固有の問題と取り違えやすいので、最初に潰しておく価値があります。

手順2: 実行用のIAMロールを作る

信頼ポリシーとロールの権限ポリシーを分けて書きます。次は、公式の記載事項をJSONにした例です。アカウントIDなどはダミーです。

信頼ポリシー(ロールを引き受けられる相手):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "aws-external-anthropic.amazonaws.com"
      },
      "Action": ["sts:AssumeRole", "sts:SetSourceIdentity"]
    }
  ]
}

権限ポリシー(ロールができること):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aws-external-anthropic:CreateSession",
        "sts:GetWebIdentityToken",
        "sts:TagGetWebIdentityToken"
      ],
      "Resource": "*"
    }
  ]
}

Resourceは例として"*"にしています。CreateSessionをワークスペースのARNで絞る書き方はIAMアクション一覧のページにありますが、この実行ロールでそう絞って動くかはデプロイの記載にありません。絞るなら、手順5の手動実行で通ることを確かめてからにします。

ここでAnthropicLimitedAccessのようなマネージドポリシーを付ければよいと考えがちです。ただ、このロールに必要なのは3つのアクションだけです。マネージドポリシーはResource: "*"で、推論やManaged Agentsの全操作まで含みます。実行ロールは、エージェントが動く間ずっと使われる権限なので、必要最小限の自前ポリシーにするほうが事故が小さくなります。マネージドポリシーの中身はClaude Platform on AWSのIAMアクション一覧と最小権限ポリシーで整理しています。

手順3: iam:PassRoleを設定者に付ける

見落としやすいのがiam:PassRoleです。公式は、エージェントにロールを設定するIAMプリンシパルが、そのロールに対してiam:PassRoleを持つことを求めています。さらに、どのマネージドポリシーもiam:PassRoleを付与しません。AnthropicFullAccessを付けていても足りません。

設定者側のポリシーは、次のような形になります(例)。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::123456789012:role/example-role"
    }
  ]
}

ResourceをロールのARNに固定しておくと、設定者が任意のロールを渡せる状態を避けられます。加えて、エージェントを作る・更新するルートはそれぞれCreateAgentとUpdateAgentのアクションが対応します。iam:PassRoleとあわせて、設定する人にはこの2つの扱いも決めておきます。

手順4: エージェントに設定してデプロイを作る

execution_identityは、エージェントの更新リクエスト(POST /v1/agents/{id})で渡します。新しく作るならPOST /v1/agentsの本文に同じフィールドを入れます。この2つの経路はIAMのアクションではUpdateAgentとCreateAgentに対応します。更新のときのversionは任意で、付けると競合時に409が返り、省くと後勝ちで上書きされます。

AWS上のAPI呼び出しは、AWS以外とは接続先・認証・ヘッダーが違います。接続先はaws-external-anthropic.{region}.api.aws、SigV4のサービス名はaws-external-anthropicで、リージョンはURLと署名の両方に同じ値を入れます。さらにanthropic-workspace-idヘッダー(wrkspc_で始まるワークスペースID)が、Managed Agentsのエンドポイントにも必須です。次はSigV4で署名したcURLの例です。

# us-west-2 は自分のリージョンに置き換える(URLと--aws-sigv4の両方)
# 長期のIAMユーザー認証情報なら x-amz-security-token は省く
curl --fail-with-body -sS \
  "https://aws-external-anthropic.us-west-2.api.aws/v1/agents/$AGENT_ID" \
  --aws-sigv4 "aws:amz:us-west-2:aws-external-anthropic" \
  -u "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  -H "x-amz-security-token: $AWS_SESSION_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "anthropic-workspace-id: $ANTHROPIC_AWS_WORKSPACE_ID" \
  -H "content-type: application/json" \
  -d '{
    "version": '"$AGENT_VERSION"',
    "execution_identity": {
      "type": "aws_role",
      "role_arn": "arn:aws:iam::123456789012:role/example-role"
    }
  }'

anthropic-betaは、AWS以外のManaged Agentsの例にあるヘッダーをそのまま残した形です。AWS側のページにこのヘッダーの扱いは書かれていないので、エラーになる場合は有無を切り替えて確かめます。設定できたら、デプロイを作ります。execution_identity以外の本文は、AWS以外と同じです。

curl --fail-with-body -sS \
  "https://aws-external-anthropic.us-west-2.api.aws/v1/deployments?beta=true" \
  --aws-sigv4 "aws:amz:us-west-2:aws-external-anthropic" \
  -u "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  -H "x-amz-security-token: $AWS_SESSION_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "anthropic-workspace-id: $ANTHROPIC_AWS_WORKSPACE_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "Weekly compliance scan",
    "agent": "'"$AGENT_ID"'",
    "environment_id": "'"$ENVIRONMENT_ID"'",
    "initial_events": [
      {"type": "user.message", "content": [{"type": "text", "text": "Run the weekly compliance scan."}]}
    ],
    "schedule": {
      "type": "cron",
      "expression": "0 20 * * 5",
      "timezone": "America/New_York"
    }
  }'

本文はスケジュールデプロイのcURL例そのままで、接続先と認証、ワークスペースIDのヘッダーだけをAWS版に替えています。APIキーで認証するなら、--aws-sigv4と-uの代わりにAWSコンソールで発行したキーを渡します。キーを使う主体には、IAMポリシー側でaws-external-anthropic:CallWithBearerTokenも必要です。

手順5: スケジュールを待たずに手動で1回走らせる

デプロイができても、権限の不足は実際に実行するまで分かりません。次の定期実行まで待たずに、runエンドポイントで手動実行します。公式も、スケジュールを確定する前のテストにこの手動実行を勧めています。

ant beta:deployments run --deployment-id "$DEPLOYMENT_ID"

手動実行はその場でセッションを作り、trigger_context.typeが"manual"の実行を記録します。ここで失敗したら、実行のerror.typeを確認します。失敗の扱いは、AWSでも通常のデプロイと同じです。セッション作成が回復不能な理由で失敗した場合は、実行が失敗として記録され、デプロイが自動で一時停止します。実行履歴の見方はcron版の記事で扱っています。

つまずいたときの切り分け

症状ごとに、疑う順番を決めておくと速くなります。

運用で知っておくこと

6時間の制限と関連する点があります。Claude Platform on AWSでは、ユーザーイベントなしで自律的に動けるセッションは最長6時間で、その後は再認証が必要です。再認証はユーザーロールのイベントをセッションへ送ることで行います。スケジュールデプロイのページにはこの上限への言及がありません。長時間かかる定期ジョブでも、1回の実行が6時間に収まれば再認証を挟まずに済みます。止め方と失敗の抑え方はManaged Agentsの定期自動化 — 失敗を防ぐ6つの設計ルールにまとめています。

もう一つは監査です。セッションの作成(CreateSession)は、CloudTrailではデータイベントに分類されます。データイベントは明示的にログ設定をしないと記録されず、設定すると追加料金がかかります。定期実行の履歴をCloudTrailで追いたいなら、先にデータイベントの設定を入れておきます。本番前の点検全体はManaged Agentsを本番に出す前のセキュリティ点検にあります。

まとめ

• AWS上のデプロイは、エージェントのexecution_identityが必須です。無いと400になります
• AWS側では、信頼ポリシー、ロールの3権限、設定者のiam:PassRoleの3点がそろって初めて動きます
• iam:PassRoleはマネージドポリシーに含まれないので、自前で付ける必要があります
• 確認はスケジュールを待たず、手動実行で1回通してから本番のcronに載せます