翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

アセットの管理

AWS DevOps Agent は、エージェントスペースの設定とリファレンスマテリアルをアセットとして保存します。これは、エージェントが知っている内容と動作を形作るカスタマー管理のリソースです。スキル、AGENTS.md ファイル、添付ファイルはすべてアセットであり、Asset API を使用してプログラムで作成、読み取り、更新、削除できます。

このトピックでは、アセットモデル、必要な IAM アクセス許可、各アセットタイプが期待するメタデータ、および AWS CLI と AWS SDK for Python (Boto3) を使用してアセットをend-to-endで管理する方法について説明します。スキル自体の概念的な概要については、「」を参照してくださいDevOps エージェントスキル。自分で作成しないエージェント生成のナレッジについては、「」を参照してください学習したスキル。

アセット API を使用するタイミング

Operator Web App は、単一のスキルを作成したり、AGENTS.md ファイルをインタラクティブにアップロードしたりする最も速い方法です。アセット API は、スクリプトとオートメーションがウェブアプリを経由せずにアセットを管理できるように、同じオペレーションをプログラムで公開します。アセット API を直接呼び出す一般的な理由は次のとおりです。

アセット API のすべてのオペレーションは、CLI AWS を介して として公開aws devops-agent <operation>され、 AWS SDKsを介してdevops-agentクライアントとして公開されます。

アセット API オペレーション

アセット API は次のオペレーションを公開します。各行には、 オペレーションを呼び出すために付与する必要がある IAM アクションと、アクションが適用されるリソースが一覧表示されます。すべてのアクションはaidevops:名前空間に存在し、 を除きListAssetTypes、 形式のエージェントスペースリソースに適用されますarn:aws:aidevops:<region>:<account-id>:agentspace/<agentSpaceId>。アクセスaidevops:許可のより広範な背景については、「」を参照してくださいDevOps エージェント IAM アクセス許可。

IAM ポリシーの例

次のポリシーは、単一のエージェントスペース内のアセットへのフル管理アクセスを許可します。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aidevops:CreateAsset",
        "aidevops:GetAsset",
        "aidevops:UpdateAsset",
        "aidevops:DeleteAsset",
        "aidevops:ListAssets",
        "aidevops:ListAssetVersions",
        "aidevops:GetAssetContent",
        "aidevops:CreateAssetFile",
        "aidevops:GetAssetFile",
        "aidevops:UpdateAssetFile",
        "aidevops:DeleteAssetFile",
        "aidevops:ListAssetFiles"
      ],
      "Resource": "arn:aws:aidevops:us-east-1:111122223333:agentspace/8f6187a7-0388-4926-8217-3a0fe32f757c"
    },
    {
      "Effect": "Allow",
      "Action": "aidevops:ListAssetTypes",
      "Resource": "*"
    }
  ]
}

次のポリシーは、単一のエージェントスペース内のアセットへの読み取り専用アクセスを許可します。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aidevops:GetAsset",
        "aidevops:ListAssets",
        "aidevops:ListAssetVersions",
        "aidevops:GetAssetContent",
        "aidevops:GetAssetFile",
        "aidevops:ListAssetFiles"
      ],
      "Resource": "arn:aws:aidevops:us-east-1:111122223333:agentspace/8f6187a7-0388-4926-8217-3a0fe32f757c"
    },
    {
      "Effect": "Allow",
      "Action": "aidevops:ListAssetTypes",
      "Resource": "*"
    }
  ]
}

アセットタイプ

すべてのアセットには、リソースの種類を識別するassetType文字列があります。アセット API では、、skill、agents_md、attachment、custom_agent、 test_profileの 6 つのアセットタイプを作成できますfeedback。以降のセクションでは、各タイプについて説明します。を呼び出しListAssetTypesて、実行時にタイプ識別子を取得することもできます。

各アセットには、リソースを記述する自由形式の metadata JSON オブジェクトがあります。内のキーは snake_case metadataを使用します (例: agent_types、skill_type)。リクエスト本文の最上位にある 外部のキーはmetadata、 camelCase を使用します (例: agentSpaceId、assetType、clientToken)。必須キーとオプションmetadataキーは、以下のセクションで説明するように、アセットタイプによって異なります。

UpdateAsset または を呼び出すとUpdateAssetFile、サービスは PATCH セマンティクスを に適用しますmetadata。含めたキーは置き換えられ、省略したキーは保存された値を保持します。アセットの作成assetType後にアセットを変更することはできません。

skill

skill アセットは、必要に応じてエージェントがロードする指示書と参考資料をパッケージ化します。シンプルなスキルは 1 つのSKILL.mdファイルです。複雑なスキルは、SKILL.mdファイルとオプションの references/または assets/ ディレクトリを含む zip バンドルです。

必要なmetadataプロパティ:

オプションのmetadataプロパティ:

例metadata:

{
  "name": "rds-performance-investigation",
  "description": "Investigation procedures for RDS performance issues including connection exhaustion, slow queries, replication lag, and storage capacity. Use this skill when investigating database latency, connection errors, or read/write performance degradation.",
  "agent_types": ["GENERIC"]
}

制限: Zip アップロードは 6 MB を超えることはできません。エージェントスペースには、ユーザーが作成したスキルを最大 200 個含めることができます。

agents_md

agents_md アセットは、特定のエージェントタイプのスタンディングエージェント指示を含むマークダウンファイルです。エージェントは、すべてのタスクの開始時に一致する AGENTS.md をロードします。エージェントの手順の詳細については、「」を参照してくださいエージェントの指示。

必要なmetadataプロパティ:

例metadata:

{
  "agent_type": "INCIDENT_TRIAGE"
}

制限: 各エージェントスペースには、 ごとに最大 1 つの AGENTS.md を含めることができますagent_type。ファイルの内容はマークダウン (text/markdown) でなければならず、25 KB を超えることはできません。

添付

attachment アセットには、エージェントが調査中に参照できるバイナリファイルまたはテキストファイルが保存されます。たとえば、アーキテクチャ図、ランブック PDF、サンプルログファイルなどです。

必要なmetadataプロパティ:

例metadata:

{
  "filename": "topology.png",
  "extension": "png",
  "size": 184320
}

制限: エージェントスペース内のすべてのアタッチメントの合計サイズは 10 GB を超えることはできません。

custom_agent

custom_agent アセットは、厳選された一連のツールとスキルを使用して、特殊なエージェント設定を定義します。カスタムエージェントを使用して、エージェントを特定のワークフローまたは一連の機能にスコープします。

必要なmetadataプロパティ:

オプションのmetadataプロパティ:

例metadata:

{
  "name": "rds-firefighter",
  "tools": ["cloudwatch:GetMetricData", "rds:DescribeDBInstances"],
  "skills": ["rds-performance-investigation"]
}

test_profile

test_profile アセットは、実行するテストの種類やターゲットエンドポイントなど、リリーステストの実行の再利用可能な設定を保存します。

必要なmetadataプロパティ:

オプションのmetadataプロパティ:

例metadata:

{
  "name": "checkout-api-tests",
  "description": "Release API tests for the checkout service.",
  "test_agent_type": "releaseApiTesting",
  "target_url": "https://api.example.com",
  "test_personas": ["guest", "authenticated"],
  "api_spec": "openapi: 3.0.0",
  "credentials_secret_arn": "arn:aws:secretsmanager:us-east-1:111122223333:secret:checkout-creds"
}

フィードバック

feedback アセットは、単一のエージェント実行に関するお客様から提供されたフィードバックを記録します。フィードバックアセットを使用して、ダウンストリーム評価パイプラインが集約できる判定とメモをキャプチャします。

必要なmetadataプロパティ:

オプションのmetadataプロパティ:

例metadata:

{
  "execution_id": "b2c3d4e5-6789-01ab-cdef-example22222",
  "agent_types": ["INCIDENT_TRIAGE"]
}

アセットコンテンツ: file または zip

すべてのCreateAssetリクエストには、アセットが保存するバイトを保持するcontentオブジェクトが含まれます。の形状は、1 つのファイルをアップロードするか zip バンドルをアップロードするかcontentによって異なります。

json { "content": { "file": { "path": "SKILL.md", "body": { "text": "# Skill\n\nInstructions go here." } } } }

json { "content": { "file": { "path": "topology.png", "body": { "bytes": "<base64-encoded bytes>" } } } }

json { "content": { "zip": { "zipFile": "<base64-encoded zip bytes>" } } }

バンドル全体を再アップロードせずに既存のアセット内の個々のファイルを追加、置換、または削除するには、、CreateAssetFileUpdateAssetFile、および を使用しますDeleteAssetFile。

スキルend-to-endの管理

以下のチュートリアルでは、3 つの異なる方法 (1 つのテキストファイル、バイナリファイル、zip バンドルから) でスキルを作成し、読み取り、更新、削除オペレーションを実行します。をエージェントスペース ID 8f6187a7-0388-4926-8217-3a0fe32f757cに置き換えます。

単一のテキストファイルからスキルを作成する

これは最もシンプルなパスです。インラインでアップロードされた 1 つのSKILL.mdファイルです。アップロードには 1 つのテキストファイルのみが含まれているため、 descriptionで nameと を指定する必要がありますmetadata。

AWS CLI:

aws devops-agent create-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-type skill \
  --metadata '{
    "name": "rds-performance-investigation",
    "description": "Investigation procedures for RDS performance issues. Use when investigating database latency, connection errors, or query timeouts.",
    "agent_types": ["GENERIC"]
  }' \
  --content '{
    "file": {
      "path": "SKILL.md",
      "body": {
        "text": "# RDS Performance Investigation\n\nUse this skill when customers report database latency, connection errors, query timeouts, or read/write performance degradation."
      }
    }
  }'

Python (Boto3):

import boto3

client = boto3.client("devops-agent")

response = client.create_asset(
    agentSpaceId="8f6187a7-0388-4926-8217-3a0fe32f757c",
    assetType="skill",
    metadata={
        "name": "rds-performance-investigation",
        "description": (
            "Investigation procedures for RDS performance issues. "
            "Use when investigating database latency, connection errors, "
            "or query timeouts."
        ),
        "agent_types": ["GENERIC"],
    },
    content={
        "file": {
            "path": "SKILL.md",
            "body": {
                "text": (
                    "# RDS Performance Investigation\n\n"
                    "Use this skill when customers report database latency, "
                    "connection errors, query timeouts, or read/write "
                    "performance degradation."
                )
            },
        }
    },
)

asset_id = response["asset"]["assetId"]

バイナリファイルからスキルを作成する

スキルコンテンツが UTF-8 テキストでない場合は、バイナリアップロードを使用します。以下の例では、事前にレンダリングされた PDF をスキル本文としてアップロードします。リクエスト本文には、contentユニオン内にネストされた base64 でエンコードされた BLOB が含まれているため、 で JSON ファイルからのリクエストを指定--cli-input-jsonし、BLOB を base64 でエンコードします。

以下の-w 0フラグは、エンコードされた BLOB を 1 行に出力base64するように GNU に指示します。これがない場合、デフォルトの 76 文字のラインラップは、BLOB が heredoc に補間されたときに無効な JSON を生成する改行を挿入します。macOS では、 を使用します base64 -i ops-runbook.pdf (デフォルトでは BSD base64はラップされません）。

リクエスト本文を構築します。

base64 -w 0 ops-runbook.pdf > ops-runbook.b64
cat > create-skill.json <<EOF
{
  "agentSpaceId": "8f6187a7-0388-4926-8217-3a0fe32f757c",
  "assetType": "skill",
  "metadata": {
    "name": "ops-runbook",
    "description": "Operations runbook covering on-call escalation paths.",
    "agent_types": ["GENERIC"]
  },
  "content": {
    "file": {
      "path": "SKILL.pdf",
      "body": { "bytes": "$(cat ops-runbook.b64)" }
    }
  }
}
EOF

AWS CLI:

aws devops-agent create-asset --cli-input-json file://create-skill.json

Python (Boto3):

with open("ops-runbook.pdf", "rb") as f:
    body_bytes = f.read()

response = client.create_asset(
    agentSpaceId="8f6187a7-0388-4926-8217-3a0fe32f757c",
    assetType="skill",
    metadata={
        "name": "ops-runbook",
        "description": "Operations runbook covering on-call escalation paths.",
        "agent_types": ["GENERIC"],
    },
    content={
        "file": {
            "path": "SKILL.pdf",
            "body": {"bytes": body_bytes},
        }
    },
)

zip バンドルからスキルを作成する

スキルに複数のファイルが含まれている場合は、zip アップロードを使用します。たとえば、SKILL.mdプラスのリファレンスマテリアルやアセットなどです。zip アップロードの場合、サービスはSKILL.mdフロントマターdescriptionから nameと を読み取るため、 に含めないでくださいmetadata。

zip レイアウトは次のようになります。

rds-performance-investigation.zip
├── SKILL.md
├── references/
│   └── rds-metrics-reference.md
└── assets/
    └── rds-investigation-flowchart.png

SKILL.md サービスが名前と説明を抽出できるように、 にはフロントマターを含める必要があります。

---
name: rds-performance-investigation
description: Investigation procedures for RDS performance issues including
  connection exhaustion, slow queries, replication lag, and storage capacity.
  Use this skill when investigating database latency, connection errors, or
  read/write performance degradation.
---

# RDS Performance Investigation
...

リクエスト本文を構築します。

base64 -w 0 rds-performance-investigation.zip > skill.zip.b64
cat > create-skill.json <<EOF
{
  "agentSpaceId": "8f6187a7-0388-4926-8217-3a0fe32f757c",
  "assetType": "skill",
  "metadata": { "agent_types": ["GENERIC"] },
  "content": {
    "zip": { "zipFile": "$(cat skill.zip.b64)" }
  }
}
EOF

AWS CLI:

aws devops-agent create-asset --cli-input-json file://create-skill.json

Python (Boto3):

with open("rds-performance-investigation.zip", "rb") as f:
    zip_bytes = f.read()

response = client.create_asset(
    agentSpaceId="8f6187a7-0388-4926-8217-3a0fe32f757c",
    assetType="skill",
    metadata={"agent_types": ["GENERIC"]},
    content={"zip": {"zipFile": zip_bytes}},
)

リポジトリからスキルをインポートする

GitHub リポジトリディレクトリから直接インポートしてスキルを作成できます。 AWS DevOps Agent はスキルコンテンツを取得し、SKILL.md フロントマターから名前と説明を抽出して、エージェントスペースにスキルを作成します。これにより、バージョン管理のスキルを管理し、プログラムでインポートまたは同期できます。

前提条件:

AWS CLI:

aws devops-agent create-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-type skill \
  --metadata '{ "agent_types": ["GENERIC"] }' \
  --content '{"sourceUrl": {"url": "https://github.com/my-org/my-repo/tree/main/skills/rds-investigation"}}'

Python (Boto3):

response = client.create_asset(
    agentSpaceId="8f6187a7-0388-4926-8217-3a0fe32f757c",
    assetType="skill",
    metadata={"agent_types": ["GENERIC"]},
    content={
        "sourceUrl": {
            "url": "https://github.com/my-org/my-repo/tree/main/skills/rds-investigation"
        }
    },
)

asset_id = response["asset"]["assetId"]

サービスはディレクトリの内容を取得し、 nameと の SKILL.md フロントマターを読み取りdescription、すべてのファイルをインポートします。name または を description に含めないでくださいmetadata。前面から自動的に抽出されます。

インポートしたスキルの同期:

リポジトリから最新の変更を取得するには、 UpdateAssetで を呼び出しますcontent.sourceUrl。

aws devops-agent update-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-id <assetId> \
  --content '{"sourceUrl": {"url": "https://github.com/my-org/my-repo/tree/main/skills/rds-investigation"}}'

response = client.update_asset(
    agentSpaceId="8f6187a7-0388-4926-8217-3a0fe32f757c",
    assetId="<assetId>",
    content={
        "sourceUrl": {
            "url": "https://github.com/my-org/my-repo/tree/main/skills/rds-investigation"
        }
    },
)

同期すると、スキルコンテンツ全体がリポジトリディレクトリの現在の状態に置き換えられます。編集可能なフィールド (ステータス、エージェントタイプ) は保持されます。

インポートソースの表示:

GetAsset は、リポジトリにインポートされたスキルmetadata.sourceのソース情報を に返します。

{
  "metadata": {
    "name": "rds-performance-investigation",
    "description": "Investigation procedures for RDS performance issues...",
    "source": {
      "url": "https://github.com/my-org/my-repo/tree/main/skills/rds-investigation",
      "lastSyncedAt": 1718467200
    },
    "agent_types": ["GENERIC"],
    "skill_type": "USER",
    "status": "ACTIVE"
  }
}

制約:

の取得、一覧表示、更新、削除

GetAsset を使用して ID で単一のアセットを取得します。

aws devops-agent get-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-id <assetId>

を使用してListAssets、エージェントスペース内のすべてのアセットをページスルーします。

aws devops-agent list-assets \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --max-results 50

aws devops-agent list-assets \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --max-results 50 \
  --next-token <token>

を使用してUpdateAsset、コンテンツを再アップロードせずに 1 つ以上のmetadataフィールドを変更します。省略したキーは、既存の値を保持します。

aws devops-agent update-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-id <assetId> \
  --metadata '{ "agent_types": ["INCIDENT_TRIAGE", "INCIDENT_RCA"] }'

ListAssetVersions を使用して、アセットのバージョン履歴を検査します。成功した UpdateAssetまたは UpdateAssetFileの呼び出しごとに、アセットのバージョン番号が進められます。

aws devops-agent list-asset-versions \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-id <assetId>

DeleteAsset を使用して、アセットとそのすべてのファイルを削除します。

aws devops-agent delete-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-id <assetId>

既存のスキルに 1 つのファイルを追加する

zip バンドルからスキルを作成済みで、新しい参照ファイルを 1 つ追加する場合は、バンドル全体を再アップロードする必要はありません。を使用するCreateAssetFile:

aws devops-agent create-asset-file \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-id <assetId> \
  --path references/troubleshooting.md \
  --content '{ "text": "# Troubleshooting\n\nAdditional notes." }'

所定のファイルを置き換えるには、同じ引数update-asset-fileで を使用します。削除するには、 を使用しますdelete-asset-file。

スキルのアクティブ化と非アクティブ化

スキルは でアクティベーション状態になりますmetadata.status。新しいスキルはACTIVEデフォルトで、調査とチャット中にエージェントによってロードされます。スキルを無効にすると、例えば、予期しない結果を生成している理由を調査したり、後で再アクティブ化したりする間など、ローテーションを削除せずに無効にすることができます。

CreateAsset リクエストmetadata.statusに を含めることで、作成時の初期状態を設定します。

aws devops-agent create-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-type skill \
  --metadata '{
    "name": "rds-performance-investigation",
    "description": "Investigation procedures for RDS performance issues.",
    "agent_types": ["GENERIC"],
    "status": "INACTIVE"
  }' \
  --content '{
    "file": {
      "path": "SKILL.md",
      "body": { "text": "# RDS Performance Investigation" }
    }
  }'

で既存のスキルを非アクティブ化しますUpdateAsset。metadata は部分的な更新として適用されるため、送信しても他のすべてのフィールドはそのままstatus残ります。

aws devops-agent update-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-id <assetId> \
  --metadata '{ "status": "INACTIVE" }'

を使用して、同じ方法で再アクティブ化します"status": "ACTIVE"。

aws devops-agent update-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-id <assetId> \
  --metadata '{ "status": "ACTIVE" }'

GetAsset と ListAssetsは常にスキルアセットmetadataの statusに現在の を含めるため、ライブアクティベーションの状態をいつでも読み取ることができます。

[status] フィールドでは、大文字と小文字が区別されます。ACTIVE と INACTIVE (大文字) のみが受け入れられます。他の値は で失敗しますValidationException。アクティベーションはスキルにのみ適用されます。他のアセットタイプmetadata.statusで を設定しても効果はなく、 フィールドはレスポンスから削除されます。

他のアセットタイプの例

上記のスキルウォークスルーは、他のすべてのアセットタイプに適用されます。唯一の違いは、 metadataブロックと、添付ファイルの場合はバイナリコンテンツの選択です。以下の最小限のCreateAsset呼び出しは、各タイプを示しています。

AGENTS.md を作成します。

aws devops-agent create-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-type agents_md \
  --metadata '{ "agent_type": "INCIDENT_TRIAGE" }' \
  --content '{
    "file": {
      "path": "AGENTS.md",
      "body": { "text": "# Triage Instructions\n\nFollow these steps for new incidents." }
    }
  }'

添付ファイルを作成する (バイナリコンテンツ。「バイナリファイルからスキルを作成する」に示すように、JSON ファイルからリクエストを作成します）。

base64 -w 0 topology.png > topology.png.b64
cat > create-attachment.json <<EOF
{
  "agentSpaceId": "8f6187a7-0388-4926-8217-3a0fe32f757c",
  "assetType": "attachment",
  "metadata": {
    "filename": "topology.png",
    "extension": "png",
    "size": 184320
  },
  "content": {
    "file": {
      "path": "topology.png",
      "body": { "bytes": "$(cat topology.png.b64)" }
    }
  }
}
EOF
aws devops-agent create-asset --cli-input-json file://create-attachment.json

カスタムエージェントを作成します。

aws devops-agent create-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-type custom_agent \
  --metadata '{
    "name": "rds-firefighter",
    "tools": ["cloudwatch:GetMetricData", "rds:DescribeDBInstances"],
    "skills": ["rds-performance-investigation"]
  }' \
  --content '{
    "file": {
      "path": "AGENT.md",
      "body": { "text": "# RDS Firefighter\n\nCustom agent for RDS incidents." }
    }
  }'

テストプロファイルを作成します。

aws devops-agent create-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-type test_profile \
  --metadata '{
    "name": "checkout-api-tests",
    "test_agent_type": "releaseApiTesting",
    "target_url": "https://api.example.com",
    "test_personas": ["guest", "authenticated"]
  }' \
  --content '{
    "file": {
      "path": "PROFILE.md",
      "body": { "text": "# Checkout API test profile" }
    }
  }'

フィードバックアセットを作成します。

aws devops-agent create-asset \
  --agent-space-id 8f6187a7-0388-4926-8217-3a0fe32f757c \
  --asset-type feedback \
  --metadata '{
    "execution_id": "b2c3d4e5-6789-01ab-cdef-example22222",
    "agent_types": ["INCIDENT_TRIAGE"]
  }' \
  --content '{
    "file": {
      "path": "FEEDBACK.md",
      "body": { "text": "{\"verdict\":\"correct\"}" }
    }
  }'

サポートされているアセットタイプを一覧表示します。

aws devops-agent list-asset-types