本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

管理資產

AWS DevOps Agent 會將 Agent Space 的組態和參考資料儲存為資產、客戶管理的資源，以塑造客服人員知道的內容及其行為。Skills、AGENTS.md 檔案和附件都是資產，您可以透過資產 API 以程式設計方式建立、讀取、更新和刪除它們。

本主題說明資產模型、您需要的 IAM 許可、每種資產類型預期的中繼資料，以及如何使用 CLI 和適用於 Python AWS 的 AWS SDK (Boto3) end-to-end管理資產。如需技能本身的概念概觀，請參閱 DevOps 代理程式技能。如需您不自行建立的客服人員產生知識，請參閱 學習的技能。

何時使用資產 API

Operator Web 應用程式是編寫單一技能或以互動方式上傳 AGENTS.md 檔案的最快方法。資產 API 會以程式設計方式公開相同的操作，以便指令碼和自動化可以管理資產，而無需透過 Web 應用程式。直接呼叫資產 API 的常見原因包括：

資產 API 中的每個操作都會透過 AWS CLI 公開為 aws devops-agent <operation> ，並透過 AWS SDKs公開為 devops-agent用戶端。

資產 API 操作

資產 API 會公開下列操作。每一列都會列出您必須授予才能呼叫 操作的 IAM 動作，以及動作適用的資源。每個動作都存在於 aidevops: 命名空間中，除了 之外ListAssetTypes， 適用於表單 的 Agent Space 資源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、test_profile、 custom_agent和 feedback。以下各節說明每種類型。您也可以在執行時間呼叫 ListAssetTypes 來擷取類型識別符。

每個資產都有描述資源的自由格式 metadata JSON 物件。內部的金鑰metadata使用 snake_case （例如，agent_types、skill_type)。外部的金鑰metadata，在請求內文的最上層，使用 camelCase （例如，、agentSpaceIdassetType、clientToken)。必要和選用的metadata金鑰取決於資產類型，如以下各節所述。

當您呼叫 UpdateAsset或 時UpdateAssetFile，服務會將 PATCH 語意套用至 metadata：您包含的金鑰會遭到取代，而您省略的金鑰會保留其儲存的值。您無法在建立資產assetType之後變更資產的 。

技能

skill 資產套件指示和參考資料，代理程式會在相關時載入。簡單技能是單一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。Agent Space 最多可包含 200 個使用者建立的技能。

agent_md

agents_md 資產是 Markdown 檔案，其中包含特定代理程式類型的常設代理程式指示。代理程式會在每個任務開始時載入相符的 AGENTS.md。如需客服人員指示的詳細資訊，請參閱 客服人員指示。

必要metadata屬性：

範例metadata：

{
  "agent_type": "INCIDENT_TRIAGE"
}

限制：每個客服人員空間每個 最多可包含一個 AGENTS.mdagent_type。檔案內容必須是 Markdown (text/markdown)，且不得超過 25 KB。

attachment

attachment 資產會存放代理程式可在調查期間參考的二進位或文字檔案，例如架構圖表、 Runbook 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

feedback 資產會記錄客戶針對單一客服人員執行所提供的意見回饋。使用意見回饋資產來擷取下游評估管道可以彙總的判斷和備註。

必要metadata屬性：

選用metadata屬性：

範例metadata：

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

資產內容：檔案或 zip

每個CreateAsset請求都包含一個物件，該content物件會保留資產存放區的位元組。的形狀content取決於您是上傳單一檔案還是 zip bundle：

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>" } } }

若要新增、取代或刪除現有資產中的個別檔案，而不重新上傳整個套件，請使用 CreateAssetFile、 UpdateAssetFile和 DeleteAssetFile。

end-to-end管理技能

接下來的演練會以三種不同的方式 （從單一文字檔案、二進位檔案和 zip 套件） 建立技能，然後執行讀取、更新和刪除操作。8f6187a7-0388-4926-8217-3a0fe32f757c 以您的客服人員空間 ID 取代 。

從單一文字檔案建立技能

這是最簡單的路徑：內嵌上傳的單一SKILL.md檔案。由於上傳只包含一個文字檔案，因此您必須在 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，請事先使用 --cli-input-json和 base64 編碼 Blob 提供來自 JSON 檔案的請求。

以下-w 0旗標base64會指示 GNU 在單行上發出編碼的 Blob；如果沒有預設的 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 上傳，服務description會從SKILL.md前端讀取 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 代理程式會擷取技能內容、從 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，以及匯入所有檔案。請勿在 description中包含 name或 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 變更一或多個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>

將單一檔案新增至現有技能

如果您已從 zip bundle 建立技能，並想要新增一個新的參考檔案，則不需要重新上傳整個 bundle。使用 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 根據預設，新技能由客服人員在調查和聊天期間載入。您可以停用技能使其停止輪換，而不將其刪除，例如當您調查產生意外結果的原因時，稍後再重新啟用。

透過在請求中包含 ，在建立時設定初始狀態： metadata.status CreateAsset

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一律在 status中包含技能資產metadata的目前 ，因此您可以隨時讀取即時啟用狀態。

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