AWS DevOps Agent の実行中のインシデント調査をキャンセルしてみた

AWS DevOps Agent の実行中のインシデント調査をキャンセルしてみた

実行中の調査は、AWS CLI と Web アプリのどちらからでもキャンセルできました。
2026.11.17

こんにちは、製造ビジネステクノロジー部 モビリティチーム の若槻です。

AWS DevOps Agent のインシデント調査(Investigation)は、開始すると完了するまでエージェントが自律的に調査を続けます。手動で誤って開始してしまった場合や、アラームなどをきっかけに自動で開始された調査がなかなか終わらない場合には、途中で止めたい場面があると思います。

そこで今回は、実行中の調査のキャンセルを試してみました。

先に結論

  • update-backlog-task --task-status CANCELED で実行中の調査を停止できた。タスクと実行(execution)の両方のステータスが CANCELED になり、以降は調査記録(journal)が追加されなかった
  • API から指定できるステータスは PENDING_START と CANCELED だけだった。API リファレンスには 11 種類の値が記載されているが、COMPLETED を指定するとエラーになった
  • キャンセルした調査は再開できなかった。PENDING_START に戻せるのは COMPLETED・LINKED・SKIPPED のタスクに限られる
  • 完了した調査はキャンセルできなかった。キャンセルできるのは PENDING_START と IN_PROGRESS のタスクに限られ、完了したタスクに指定すると ConflictException になった
  • Web アプリの調査画面にも「調査をキャンセル」ボタンがあった。ボタンでキャンセルした場合も、ステータスと canceledReason は AWS CLI の場合と同じだった

調査はバックログタスクとして管理される

DevOps Agent のインシデント調査は、API 上はバックログタスク(backlog task)の一種として扱われます。タスクの種類(taskType)が INVESTIGATION のタスクがインシデント調査です。

タスクのステータスは UpdateBacklogTask で更新でき、AWS CLI では aws devops-agent update-backlog-task コマンドに該当します。API リファレンスに記載されている taskStatus の値は次のとおりです。

PENDING_TRIAGE | LINKED | PENDING_START | IN_PROGRESS | PENDING_CUSTOMER_APPROVAL | COMPLETED | FAILED | TIMED_OUT | CANCELED | SKIPPED | WAITING

この中の CANCELED を指定すれば調査を止められると考え、実際に試してみました。

検証環境

Agent Space

Agent Space は AWS CDK で作成しています。Agent Space 本体と Web アプリ用のオペレーターロールに加えて、調査対象の AWS アカウント自身を監視対象(monitor)として関連付けています。実装の詳細は、以前の記事で紹介しています。

Agent Space のコード
lib/constructs/devops-agent/agent-space/index.ts
import * as devopsagent from "aws-cdk-lib/aws-devopsagent";
import { Construct } from "constructs";

import { commonParameter } from "../../../../bin/parameter";
import { OperatorRoleConstruct } from "./operator-role";

/**
 * Agent Space とオペレーターロールの実装
 * @see https://github.com/aws-samples/sample-aws-devops-agent-cdk/blob/main/lib/devops-agent-stack.ts
 */
export class AgentSpaceConstruct extends Construct {
  public readonly agentSpace: devopsagent.CfnAgentSpace;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    const { projectNamePascalCase } = commonParameter;

    const operatorRole = new OperatorRoleConstruct(this, "OperatorRole");

    this.agentSpace = new devopsagent.CfnAgentSpace(this, "Resource", {
      name: `${projectNamePascalCase}AgentSpace`,
      locale: "ja-JP", // エージェントの応答言語
      operatorApp: {
        iam: {
          operatorAppRoleArn: operatorRole.role.roleArn,
        },
      },
    });
  }
}
lib/constructs/devops-agent/agent-space/operator-role/index.ts
import * as cdk from "aws-cdk-lib";
import * as iam from "aws-cdk-lib/aws-iam";
import { Construct } from "constructs";

/**
 * オペレーター用ロール実装
 * @see https://github.com/aws-samples/sample-aws-devops-agent-cdk/blob/main/lib/devops-agent-stack.ts
 */
export class OperatorRoleConstruct extends Construct {
  public readonly role: iam.Role;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    const stack = cdk.Stack.of(this);
    const accountId = stack.account;

    /**
     * AIDevOps サービスプリンシパルの許可条件
     */
    const principalConditions = {
      StringEquals: {
        "aws:SourceAccount": accountId,
      },
      ArnLike: {
        "aws:SourceArn": stack.formatArn({
          service: "aidevops",
          resource: "agentspace",
          resourceName: "*", // 循環参照回避のためワイルドカードで指定
        }),
      },
    };

    /**
     * AIDevOps サービスプリンシパル
     */
    const servicePrincipal = new iam.ServicePrincipal(
      "aidevops.amazonaws.com",
      {
        conditions: principalConditions,
      },
    );

    this.role = new iam.Role(this, "Default", {
      assumedBy: servicePrincipal,
      managedPolicies: [
        /**
         * オペレーターアプリ用のアクセス許可を付与するマネージドポリシーをアタッチ
         * @see https://docs.aws.amazon.com/ja_jp/devopsagent/latest/userguide/configuring-capabilities-for-aws-devops-agent-migrating-from-public-preview-to-general-availability.html#new-managed-policies
         */
        iam.ManagedPolicy.fromAwsManagedPolicyName(
          "AIDevOpsOperatorAppAccessPolicy",
        ),
      ],
    });

    /**
     * sts:TagSession を許可するステートメントを追加
     * @see https://docs.aws.amazon.com/ja_jp/devopsagent/latest/userguide/configuring-capabilities-for-aws-devops-agent-migrating-from-public-preview-to-general-availability.html#step-2-update-the-operator-role-iam
     */
    this.role.assumeRolePolicy?.addStatements(
      new iam.PolicyStatement({
        actions: ["sts:TagSession"],
        principals: [servicePrincipal],
        conditions: principalConditions,
      }),
    );
  }
}
lib/constructs/devops-agent/aws-association/index.ts
import { Stack } from "aws-cdk-lib";
import * as devopsagent from "aws-cdk-lib/aws-devopsagent";
import { Construct } from "constructs";

import { AgentSpaceRoleConstruct } from "./agent-space-role";

interface AwsAssociationConstructProps {
  agentSpace: devopsagent.CfnAgentSpace;
}

/**
 * DevOps Agent と AWS リソースの関連付け実装
 */
export class AwsAssociationConstruct extends Construct {
  public readonly association: devopsagent.CfnAssociation;

  constructor(
    scope: Construct,
    id: string,
    props: AwsAssociationConstructProps,
  ) {
    super(scope, id);
    const accountId = Stack.of(this).account;

    const agentSpaceRole = new AgentSpaceRoleConstruct(this, "AgentSpaceRole");

    this.association = new devopsagent.CfnAssociation(this, "Default", {
      agentSpaceId: props.agentSpace.ref,
      serviceId: "aws",
      configuration: {
        aws: {
          assumableRoleArn: agentSpaceRole.role.roleArn,
          accountId,
          // 関連付け対象に応じて monitor / source を指定する。
          // このスタックでは DevOps Agent に監視させる対象 AWS アカウント自身を
          // 関連付けているため、monitor を指定する。
          accountType: "monitor",
        },
      },
    });
  }
}
lib/constructs/devops-agent/aws-association/agent-space-role/index.ts
import * as cdk from "aws-cdk-lib";
import * as iam from "aws-cdk-lib/aws-iam";
import { Construct } from "constructs";

/**
 * Agent Space 用の監視ロール実装
 * @see https://github.com/aws-samples/sample-aws-devops-agent-cdk/blob/main/lib/devops-agent-stack.ts
 * @see https://docs.aws.amazon.com/ja_jp/devopsagent/latest/userguide/configuring-capabilities-for-aws-devops-agent-migrating-from-public-preview-to-general-availability.html#step-1-update-monitoring-roles
 */
export class AgentSpaceRoleConstruct extends Construct {
  public readonly role: iam.Role;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    const stack = cdk.Stack.of(this);

    this.role = new iam.Role(this, "Default", {
      assumedBy: new iam.ServicePrincipal("aidevops.amazonaws.com", {
        conditions: {
          StringEquals: {
            "aws:SourceAccount": stack.account,
          },
          ArnLike: {
            "aws:SourceArn": stack.formatArn({
              service: "aidevops",
              resource: "agentspace",
              resourceName: "*", // 循環参照回避のためワイルドカードで指定
            }),
          },
        },
      }),
      managedPolicies: [
        /**
         * Agent Space 用のアクセス許可を付与するマネージドポリシーをアタッチ
         * @see https://docs.aws.amazon.com/ja_jp/devopsagent/latest/userguide/configuring-capabilities-for-aws-devops-agent-migrating-from-public-preview-to-general-availability.html#new-managed-policies
         */
        iam.ManagedPolicy.fromAwsManagedPolicyName("AIDevOpsAgentAccessPolicy"),
      ],
      inlinePolicies: {
        AllowCreateServiceLinkedRoles: new iam.PolicyDocument({
          statements: [
            /**
             * 以下を参考にサービスリンクロール作成権限を追加
             * @see https://docs.aws.amazon.com/ja_jp/devopsagent/latest/userguide/configuring-capabilities-for-aws-devops-agent-migrating-from-public-preview-to-general-availability.html#step-1-update-monitoring-roles
             */
            new iam.PolicyStatement({
              actions: ["iam:CreateServiceLinkedRole"],
              resources: [
                stack.formatArn({
                  service: "iam",
                  region: "",
                  resource: "role",
                  resourceName:
                    "aws-service-role/resource-explorer-2.amazonaws.com/AWSServiceRoleForResourceExplorer",
                }),
              ],
            }),
          ],
        }),
      },
    });
  }
}

障害を起こす Lambda 関数

調査の対象とする障害を起こすため、意図的にタイムアウトする Lambda 関数を AWS CDK で作成しました。

スタックは、Lambda 関数を作成するコンストラクトを呼び出すだけの構成です。

lib/devops-agent-cancel-verification-stack.ts
import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { AppParameter } from "../bin/parameter";
import { SlowTaskFunctionConstruct } from "./constructs/devops-agent-cancel-verification/slow-task-function";

/**
 * DevOps Agent の調査キャンセル検証用スタック
 *
 * 意図的にタイムアウトする Lambda 関数を作成し、DevOps Agent にその障害を調査させる。
 * 調査の実行中に UpdateBacklogTask でキャンセルできるかを検証する。
 * 検証が終わったら cdk destroy で削除する。
 */
export class DevOpsAgentCancelVerificationStack extends cdk.Stack {
  constructor(
    scope: Construct,
    id: string,
    props: AppParameter & cdk.StackProps,
  ) {
    super(scope, id, props);

    // 意図的にタイムアウトする Lambda 関数を作成
    new SlowTaskFunctionConstruct(this, "SlowTaskFunction");
  }
}

Lambda 関数のタイムアウト値を 3 秒にし、ハンドラーの処理時間(10 秒)より短くしています。

Lambda 関数のコード
lib/constructs/devops-agent-cancel-verification/slow-task-function/index.ts
import * as cdk from "aws-cdk-lib";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as nodejs from "aws-cdk-lib/aws-lambda-nodejs";
import * as logs from "aws-cdk-lib/aws-logs";
import { Construct } from "constructs";

/**
 * 検証用 Lambda 関数の実装
 *
 * ハンドラーの処理時間(10 秒)より短いタイムアウト値を設定することで、
 * 意図的に Task timed out を発生させる。DevOps Agent にこの障害を調査させ、
 * 実行中の調査をキャンセルするための検証用リソース。検証専用。
 */
export class SlowTaskFunctionConstruct extends Construct {
  public readonly function: nodejs.NodejsFunction;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    const logGroup = new logs.LogGroup(this, "LogGroup", {
      retention: logs.RetentionDays.ONE_WEEK,
      removalPolicy: cdk.RemovalPolicy.DESTROY, // 検証用のため、スタック削除時に削除する
    });

    this.function = new nodejs.NodejsFunction(this, "Default", {
      entry:
        "lib/constructs/devops-agent-cancel-verification/slow-task-function/function.ts",
      handler: "handler",
      runtime: lambda.Runtime.NODEJS_24_X,
      timeout: cdk.Duration.seconds(3), // 処理時間より短く、意図的にタイムアウトさせる
      logGroup,
    });
  }
}
lib/constructs/devops-agent-cancel-verification/slow-task-function/function.ts
const PROCESSING_SECONDS = 10;

const sleep = (milliseconds: number): Promise<void> =>
  new Promise((resolve) => setTimeout(resolve, milliseconds));

/**
 * 長時間処理を模した検証用ハンドラー
 *
 * 関数のタイムアウト値より長く動作させることで、意図的に Task timed out を発生させる。
 */
export const handler = async (): Promise<void> => {
  console.log(
    `Start processing. This task takes ${PROCESSING_SECONDS} seconds.`,
  );

  await sleep(PROCESSING_SECONDS * 1000);

  console.log("Finished processing.");
};

デプロイ後に Lambda 関数を 3 回実行し、Task timed out after 3.00 seconds で失敗することを確認しました。

AWS CLI からのキャンセル

調査を開始する

以降のコマンドでは、Agent Space の ID をシェル変数 AGENT_SPACE_ID に設定して使います。Agent Space の ID は名前とは異なる UUID 形式の値で、list-agent-spaces で名前から取得できます。

AGENT_SPACE_ID=$(aws devops-agent list-agent-spaces \
  --region ap-northeast-1 \
  --query "agentSpaces[?name=='SampleProjectAgentSpace'].agentSpaceId" \
  --output text)

create-backlog-task で、--task-type INVESTIGATION を指定してインシデント調査を開始しました。

aws devops-agent create-backlog-task \
  --region ap-northeast-1 \
  --agent-space-id $AGENT_SPACE_ID \
  --task-type INVESTIGATION \
  --priority HIGH \
  --title "検証用 Lambda 関数のタイムアウト" \
  --description "DevOpsAgentCancelVerification スタックの Lambda 関数 DevOpsAgentCancelVerifica-SlowTaskFunction5A03C8B3-h5Ln9rRCfrU5 が Task timed out after 3.00 seconds で失敗しています。原因を調査してください。"

作成直後のステータスは PENDING_START でした。

{
    "task": {
        "agentSpaceId": "<AGENT_SPACE_ID>",
        "taskId": "<TASK_ID>",
        "executionId": "<EXECUTION_ID>",
        "title": "検証用 Lambda 関数のタイムアウト",
        "description": "DevOpsAgentCancelVerification スタックの Lambda 関数 DevOpsAgentCancelVerifica-SlowTaskFunction5A03C8B3-h5Ln9rRCfrU5 が Task timed out after 3.00 seconds で失敗しています。原因を調査してください。",
        "taskType": "INVESTIGATION",
        "priority": "HIGH",
        "status": "PENDING_START",
        "createdAt": "2026-11-17T01:50:14.840000+00:00",
        "updatedAt": "2026-11-17T01:50:14.840000+00:00",
        "version": 1,
        "hasLinkedTasks": false
    }
}

以降のコマンドで調査を指定するため、作成した調査のタスク ID をシェル変数 TASK_ID に設定します。list-backlog-tasks で、同じタイトルの調査のうち作成日時が最も新しいものの ID を取得しています。

TASK_ID=$(aws devops-agent list-backlog-tasks \
  --region ap-northeast-1 \
  --agent-space-id $AGENT_SPACE_ID \
  --query "sort_by(tasks[?title=='検証用 Lambda 関数のタイムアウト'], &createdAt)[-1].taskId" \
  --output text)

get-backlog-task でステータスを 3 秒ごとに確認したところ、作成から約 20 秒後に IN_PROGRESS に変わりました。

aws devops-agent get-backlog-task \
  --region ap-northeast-1 \
  --agent-space-id $AGENT_SPACE_ID \
  --task-id $TASK_ID \
  --query task.status
"IN_PROGRESS"

調査をキャンセルする

調査が IN_PROGRESS の状態で、update-backlog-task に --task-status CANCELED を指定して実行しました。

aws devops-agent update-backlog-task \
  --region ap-northeast-1 \
  --agent-space-id $AGENT_SPACE_ID \
  --task-id $TASK_ID \
  --task-status CANCELED

ステータスが CANCELED になり、metadata.canceledReason に USER_CANCELED が記録されていますね。

{
    "task": {
        "agentSpaceId": "<AGENT_SPACE_ID>",
        "taskId": "<TASK_ID>",
        "executionId": "<EXECUTION_ID>",
        "title": "検証用 Lambda 関数のタイムアウト",
        "description": "DevOpsAgentCancelVerification スタックの Lambda 関数 DevOpsAgentCancelVerifica-SlowTaskFunction5A03C8B3-h5Ln9rRCfrU5 が Task timed out after 3.00 seconds で失敗しています。原因を調査してください。",
        "taskType": "INVESTIGATION",
        "priority": "HIGH",
        "status": "CANCELED",
        "createdAt": "2026-11-17T01:50:14.840000+00:00",
        "updatedAt": "2026-11-17T01:50:54.355000+00:00",
        "version": 3,
        "metadata": {
            "canceledReason": "USER_CANCELED"
        },
        "hasLinkedTasks": false
    }
}

調査が停止したことを確認する

タスクのステータスが変わっただけでなく、エージェントの実行も止まったかを確認しました。list-executions で調査の実行を確認したところ、executionStatus も CANCELED になっていました。

aws devops-agent list-executions \
  --region ap-northeast-1 \
  --agent-space-id $AGENT_SPACE_ID \
  --task-id $TASK_ID
{
    "executions": [
        {
            "agentSpaceId": "<AGENT_SPACE_ID>",
            "executionId": "<EXECUTION_ID>",
            "agentSubTask": "oncall",
            "createdAt": "2026-11-17T10:50:14.840000+09:00",
            "updatedAt": "2026-11-17T10:50:54.419000+09:00",
            "executionStatus": "CANCELED",
            "agentType": "ops1"
        }
    ]
}

また、list-journal-records で調査記録を確認しました。調査記録は 18 件で、最後の記録の時刻はキャンセルを実行した 10:50:54 より前の 10:50:52 でした。1 分後に再度確認しても件数は 18 件のまま変わらず、キャンセル後に調査記録は追加されていませんでした。

list-journal-records には調査の実行 ID を指定するため、get-backlog-task で取得してシェル変数 EXECUTION_ID に設定します。

EXECUTION_ID=$(aws devops-agent get-backlog-task \
  --region ap-northeast-1 \
  --agent-space-id $AGENT_SPACE_ID \
  --task-id $TASK_ID \
  --query task.executionId \
  --output text)
aws devops-agent list-journal-records \
  --region ap-northeast-1 \
  --agent-space-id $AGENT_SPACE_ID \
  --execution-id $EXECUTION_ID \
  --query 'length(records)'
18

Web アプリからのキャンセル

Operator Web App からもキャンセルできるかを確認するため、AWS CLI と同じ手順で調査をもう 1 件開始し、Web アプリの調査画面を開きました。調査の実行中は、画面上部の「調査中」の表示の横に「調査をキャンセル」ボタンが表示されていました。


実行中の調査の画面に表示される「調査をキャンセル」ボタン

ボタンをクリックすると、元に戻せない操作であることを示す確認ダイアログが表示されました。


キャンセルの確認ダイアログ

ダイアログで「調査をキャンセル」をクリックすると、画面上部に「調査がキャンセルされました: ユーザーによりキャンセルされました」と表示されました。


キャンセル後の調査の画面

get-backlog-task で確認したところ、AWS CLI でキャンセルした場合と同じく、ステータスは CANCELED、metadata.canceledReason は USER_CANCELED になっていました。インシデントレスポンスのダッシュボードでは、キャンセルした調査のステータスが「ユーザーがキャンセル」と表示されます。


インシデントレスポンスのダッシュボード

画面から 1 件ずつ止める場合は Web アプリ、スクリプトから止める場合や複数件をまとめて止める場合は AWS CLI と使い分けることができます。

できなかったこと

調査のキャンセルに関連して、ステータスの更新でできなかった操作を紹介します。いずれも、API のエラーメッセージから、更新できる条件が分かりました。

CANCELED 以外のステータスの指定

キャンセルを実行する前に、CANCELED 以外のステータスも指定できるかを確認していました。実行中の調査に COMPLETED を指定したところ、次のエラーになりました。

aws devops-agent update-backlog-task \
  --region ap-northeast-1 \
  --agent-space-id $AGENT_SPACE_ID \
  --task-id $TASK_ID \
  --task-status COMPLETED

aws: [ERROR]: An error occurred (ValidationException) when calling the UpdateBacklogTask operation: Only PENDING_START or CANCELED status is allowed for task updates

Additional error details:
fieldList: <complex value>
Use "--cli-error-format json" or another error format to see the full details.

API リファレンスには 11 種類の値が記載されていますが、ユーザーが指定できるのは PENDING_START と CANCELED の 2 種類だけでした。それ以外のステータスは、エージェントが調査を進める中で更新するものと考えられます。

キャンセルした調査の再開

キャンセルした調査を PENDING_START に戻して再開できるかも確認しました。

aws devops-agent update-backlog-task \
  --region ap-northeast-1 \
  --agent-space-id $AGENT_SPACE_ID \
  --task-id $TASK_ID \
  --task-status PENDING_START

aws: [ERROR]: An error occurred (ValidationException) when calling the UpdateBacklogTask operation: Cannot update task to PENDING_START from CANCELLED status. Only tasks in COMPLETED, LINKED, or SKIPPED status can be updated to PENDING_START

Additional error details:
fieldList: <complex value>
Use "--cli-error-format json" or another error format to see the full details.

PENDING_START に戻せるのは COMPLETED・LINKED・SKIPPED のタスクに限られ、キャンセルしたタスクは再開できませんでした。調査をやり直す場合は、新しいタスクを作成する必要があります。

完了した調査のキャンセル

調査が完了した後にキャンセルするとどうなるかも確認しました。別の調査で、キャンセルを実行する前に調査が完了してしまったため、完了した状態のタスクに CANCELED を指定したところ、次のエラーになりました。

aws devops-agent update-backlog-task \
  --region ap-northeast-1 \
  --agent-space-id $AGENT_SPACE_ID \
  --task-id $TASK_ID \
  --task-status CANCELED

aws: [ERROR]: An error occurred (ConflictException) when calling the UpdateBacklogTask operation: Cannot cancel task in COMPLETED status. Only tasks in PENDING_START or IN_PROGRESS status can be cancelled

キャンセルできるのは PENDING_START と IN_PROGRESS のタスクだけで、完了したタスクに指定すると ConflictException になりました。調査は数分で完了することもあるため、止めたい場合は早めにキャンセルする必要があります。

後片付け

検証用のスタックは cdk destroy で削除しました。

npx cdk destroy DevOpsAgentCancelVerification --context environment=dev

キャンセルの機能が提供された時期

キャンセルの機能がいつから提供されているかは、告知やドキュメントで確認できませんでした。ただ、Web アプリのキャンセルボタンは、プレビュー版の時点から存在していたようです。2025 年 12 月にプレビュー版を紹介した記事のスクリーンショットにも、実行中の調査画面の上部に「Cancel Investigation」ボタンが写っています。

また、AWS CLI でキャンセルに使う UpdateBacklogTask は、2026 年 3 月の一般提供の時点で、AWS SDK の API 定義に含まれていました。

おわりに

AWS DevOps Agent の実行中のインシデント調査を、AWS CLI の update-backlog-task と Web アプリのボタンの両方でキャンセルしてみました。どちらの方法でもステータスは CANCELED になり、結果は同じでした。API リファレンスにはステータスの値が 11 種類記載されていますが、ユーザーが指定できるのは PENDING_START と CANCELED だけで、キャンセルした調査は再開できないという点に気を付けましょう。

誤って開始した調査や、自動で開始されてなかなか終わらない調査を止めたいときの参考になれば幸いです。

参考

この記事をシェアする

関連記事