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

# 管理資產
<a name="about-aws-devops-agent-managing-assets"></a>

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

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

## 何時使用資產 API
<a name="when-to-use-the-asset-api"></a>

Operator Web 應用程式是編寫單一技能或以互動方式上傳 AGENTS.md 檔案的最快方法。資產 API 會以程式設計方式公開相同的操作，以便指令碼和自動化可以管理資產，而無需透過 Web 應用程式。直接呼叫資產 API 的常見原因包括：
+ 從指令碼、終端機或筆記本撰寫或更新資產，而非 Web 應用程式。
+ 將一組入門技能或 AGENTS.md 檔案大量載入新的客服人員空間。
+ 讀取資產的內容以備份或比較版本。

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

## 資產 API 操作
<a name="asset-api-operations"></a>

資產 API 會公開下列操作。每一列都會列出您必須授予才能呼叫 操作的 IAM 動作，以及動作適用的資源。每個動作都存在於 `aidevops:` 命名空間中，除了 之外`ListAssetTypes`， 適用於表單 的 Agent Space 資源`arn:aws:aidevops:<region>:<account-id>:agentspace/<agentSpaceId>`。如需`aidevops:`許可的更廣泛背景，請參閱 [DevOps 代理程式 IAM 許可](aws-devops-agent-security-devops-agent-iam-permissions.md)。


| 作業 | 說明 | IAM 動作 | 資源 | 
| --- | --- | --- | --- | 
| ListAssetTypes | 列出 AWS DevOps Agent 支援的資產類型。 | aidevops:ListAssetTypes | \* | 
| CreateAsset | 在客服人員空間中建立新的資產 （技能、https：//AGENTS.md、附件、自訂客服人員、測試設定檔或意見回饋）。 | aidevops:CreateAsset | 客服人員空間 | 
| GetAsset | 擷取資產的中繼資料和版本資訊。 | aidevops:GetAsset | 客服人員空間 | 
| UpdateAsset | 更新現有資產的中繼資料或內容。 | aidevops:UpdateAsset | 客服人員空間 | 
| DeleteAsset | 從 代理程式空間刪除資產及其所有檔案。 | aidevops:DeleteAsset | 客服人員空間 | 
| ListAssets | 列出 代理程式空間中的資產，並依資產類型進行選用篩選。 | aidevops:ListAssets | 客服人員空間 | 
| ListAssetVersions | 列出資產的歷史版本。 | aidevops:ListAssetVersions | 客服人員空間 | 
| GetAssetContent | 下載資產的完整內容做為 zip 套件。 | aidevops:GetAssetContent | 客服人員空間 | 
| CreateAssetFile | 將新檔案新增至現有資產。 | aidevops:CreateAssetFile | 客服人員空間 | 
| GetAssetFile | 依其路徑從資產擷取單一檔案。 | aidevops:GetAssetFile | 客服人員空間 | 
| UpdateAssetFile | 取代資產中現有檔案的內容或中繼資料。 | aidevops:UpdateAssetFile | 客服人員空間 | 
| DeleteAssetFile | 從資產移除單一檔案。 | aidevops:DeleteAssetFile | 客服人員空間 | 
| ListAssetFiles | 列出資產中的檔案。 | aidevops:ListAssetFiles | 客服人員空間 | 

### 範例 IAM 政策
<a name="example-iam-policies"></a>

下列政策授予單一代理程式空間中資產的完整管理存取權：

```
{
  "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": "*"
    }
  ]
}
```

## 資產類型
<a name="asset-types"></a>

每個資產都有可識別其資源類型的`assetType`字串。可以透過資產 API 建立六個資產類型：`skill`、`agents_md`、`attachment`、`test_profile`、 `custom_agent`和 `feedback`。以下各節說明每種類型。您也可以在執行時間呼叫 `ListAssetTypes` 來擷取類型識別符。

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

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

### 技能
<a name="skill"></a>

`skill` 資產套件指示和參考資料，代理程式會在相關時載入。簡單技能是單一`SKILL.md`檔案；複雜技能是包含`SKILL.md`檔案加上選用 `references/` 或 `assets/` 目錄的 zip 套件。

**必要`metadata`屬性：**
+ **name** （字串） – 技能的唯一識別符。僅限小寫字母、數字和連字號，1-64 個字元。不得以連字號開頭或結尾。僅適用於簡單技能。對於 zip 上傳，系統會`name`忽略從`SKILL.md`前端讀取的服務，並忽略此處提供的任何值。
+ **description** （字串） – 客服人員何時應使用技能的 1-1024 字元說明。僅適用於簡單技能。對於 zip 上傳，系統會`description`忽略從`SKILL.md`前端讀取的服務，並忽略此處提供的任何值。
+ **agent\_types** （字串陣列） – 此技能適用的一個或多個代理程式類型。使用 `["GENERIC"]` 讓所有客服人員類型都能使用技能。其他值包括 `CHAT`、`INCIDENT_TRIAGE`、`INCIDENT_RCA`、`INCIDENT_MITIGATION`、`PREVENTION`、`CHANGE_REVIEW``CHANGE_RELEASE`、`QUALITY_ASSURANCE_TESTING`、`RELEASE_SHEPHERD`、`RELEASE_READINESS_REVIEW`、 和 `RELEASE_TESTING`。該`GENERIC`值不能與其他值結合。

**選用`metadata`屬性：**
+ **skill\_type** （字串） – 預設為 `USER`。資產 API 僅允許客戶建立的技能，因此唯一接受的值為 `USER`。服務會拒絕`skill_type`設定為 的請求`LEARNED`，該請求會保留給客服人員本身產生的技能。
+ **狀態** （字串） – 技能的啟用狀態。接受的值為 `ACTIVE`和 `INACTIVE`（僅限大寫）。預設為 `ACTIVE`。非作用中技能會保留在客服人員空間中，但客服人員在調查或聊天期間不會載入。使用 `UpdateAsset`搭配 `metadata.status`來停用或重新啟用技能，而不將其刪除。Skills 是唯一支援啟用的資產類型；每隔一種資產類型都會忽略 `status` 欄位。如需工作範例，請參閱[啟用和停用技能](#activating-and-deactivating-skills)。
+ **enable\_tools** （字串陣列） – 代理程式載入此技能時可呼叫的工具識別符清單。

**範例`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
<a name="agents-md"></a>

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

**必要`metadata`屬性：**
+ **agent\_type** （字串） – 適用於 AGENTS.md 檔案的代理程式類型。有效值為：`GENERIC`、`CHAT`、`INCIDENT_TRIAGE`、`INCIDENT_RCA`、`INCIDENT_MITIGATION`、`PREVENTION`、`CHANGE_REVIEW`、`CHANGE_RELEASE`、`QUALITY_ASSURANCE_TESTING`、`RELEASE_SHEPHERD`、`RELEASE_READINESS_REVIEW` 和 `RELEASE_TESTING`。

**範例`metadata`：**

```
{
  "agent_type": "INCIDENT_TRIAGE"
}
```

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

### attachment
<a name="attachment"></a>

`attachment` 資產會存放代理程式可在調查期間參考的二進位或文字檔案，例如架構圖表、 Runbook PDF 或範例日誌檔案。

**必要`metadata`屬性：**
+ **filename** (string) – 原始檔案名稱，包括基本名稱和任何副檔名 （例如 `topology.png`)。
+ **extension** （字串） – 沒有前置點的副檔名 `png`（例如，、`pdf`、`csv`)。
+ **size** (number) – 以位元組為單位的檔案大小。

**範例`metadata`：**

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

**限制：**代理程式空間中所有附件的總大小不得超過 10 GB。

### custom\_agent
<a name="custom-agent"></a>

`custom_agent` 資產使用一組精選的工具和技能來定義專門的代理程式組態。使用自訂代理程式，將代理程式範圍限定在特定工作流程或一組功能。

**必要`metadata`屬性：**
+ **name** （字串） – 自訂代理程式的唯一識別符。僅限小寫字母、數字和連字號，1-64 個字元。不得以連字號開頭或結尾。

**選用`metadata`屬性：**
+ **工具** （字串陣列） – 允許自訂代理程式使用的工具識別符。省略時預設為空白清單。
+ **skills** （字串陣列） – 自訂代理程式載入的技能識別符。省略時預設為空白清單。

**範例`metadata`：**

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

### test\_profile
<a name="test-profile"></a>

`test_profile` 資產會存放可重複使用的發行測試執行組態，包括要執行的測試類型和目標端點。

**必要`metadata`屬性：**
+ **test\_agent\_type** （字串） – 此設定檔執行的測試類型。有效值為 `releaseUiTesting` 和 `releaseApiTesting`。
+ **target\_url** （字串） – 測試執行目標的 URL。

**選用`metadata`屬性：**
+ **name** （字串） – 測試設定檔的人類可讀取識別符。僅限小寫字母、數字和連字號，1-128 個字元。不得以連字號開頭或結尾。
+ **description** （字串） – 測試描述檔涵蓋內容的 1–1024 字元描述。
+ **test\_personas** （字串陣列） – 在測試執行期間要練習的角色。有效值為 `guest` 和 `authenticated`。
+ **api\_spec** （字串） – 測試執行的 API 規格。與 相關`releaseApiTesting`。
+ **credentials\_secret\_arn** （字串） – AWS Secrets Manager 秘密的 ARN，存放測試執行的登入資料。

**範例`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
<a name="feedback"></a>

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

**必要`metadata`屬性：**
+ **agent\_types** （字串陣列） – 產生執行的代理程式類型。必須至少包含一個值 （例如 `INCIDENT_TRIAGE`)。

**選用`metadata`屬性：**
+ **execution\_id** （字串） – 此回饋相關聯的執行。在 上設定此項目`CreateAsset`；無法由 變更`UpdateAsset`。

**範例`metadata`：**

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

## 資產內容：檔案或 zip
<a name="asset-content-file-or-zip"></a>

每個`CreateAsset`請求都包含一個物件，該`content`物件會保留資產存放區的位元組。的形狀`content`取決於您是上傳單一檔案還是 zip bundle：
+ **單一文字檔案** – `content.file.body.text`最多 1.5 MB 的 UTF-8 文字。將此用於簡單的技能和 AGENTS.md 檔案。

```json { "content": { "file": { "path": "SKILL.md", "body": { "text": "# Skill\n\nInstructions go here." } } } } ```
+ **單一二進位檔案 – **`content.file.body.bytes`承載最多 6 MB 的 base64 編碼二進位內容。將此用於連接，例如影像或 PDFs。由於 Blob 在`content`聯集內部巢狀，因此 base64 會預先編碼檔案，並使用 提交請求 `--cli-input-json`（請參閱[從二進位檔案建立技能](#create-a-skill-from-a-binary-file)以取得工作範例）。

```json { "content": { "file": { "path": "topology.png", "body": { "bytes": "<base64-encoded bytes>" } } } } ```
+ **壓縮套件** – `content.zip.zipFile`攜帶最多 6 MB 的 base64 編碼壓縮封存。將此用於在 `references/`或 `assets/`目錄中包含`SKILL.md`加其他檔案的技能。

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

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

## end-to-end管理技能
<a name="managing-a-skill-end-to-end"></a>

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

### 從單一文字檔案建立技能
<a name="create-a-skill-from-a-single-text-file"></a>

這是最簡單的路徑：內嵌上傳的單一`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"]
```

### 從二進位檔案建立技能
<a name="create-a-skill-from-a-binary-file"></a>

當技能內容不是 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 套件建立技能
<a name="create-a-skill-from-a-zip-bundle"></a>

當技能包含多個檔案時，請使用 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}},
)
```

### 從儲存庫匯入技能
<a name="import-a-skill-from-a-repository"></a>

您可以透過直接從 GitHub 儲存庫目錄匯入技能來建立技能。 AWS DevOps 代理程式會擷取技能內容、從 SKILL.md 前端擷取名稱和描述，並在您的代理程式空間中建立技能。這可讓您管理版本控制中的技能，並以程式設計方式匯入或同步這些技能。

**先決條件：**
+ 您的客服人員空間必須關聯 GitHub 帳戶。請參閱 [連接 GitHub](connecting-to-cicd-pipelines-connecting-github.md)。
+ 儲存庫目錄必須包含具有前端的有效 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"
  }
}
```

**限制條件**：
+ 僅接受 GitHub URLs。您可以指向包含 SKILL.md 的目錄 （例如 `https://github.com/org/repo/tree/main/skills/my-skill`)，該目錄會匯入整個目錄，包括參考檔案。如果 SKILL.md 位於儲存庫的根目錄，您也可以直接連結至 檔案 （例如 `https://github.com/org/repo/blob/main/SKILL.md`)，該檔案只會匯入 SKILL.md。
+ 目錄必須包含具有有效前端的 SKILL.md。
+ 目錄大小總計不得超過 6 MB，最多不得超過 100 個檔案。
+ `content.sourceUrl` 與 `content.file`和 互斥`content.zip`，您無法在相同的請求中合併它們。
+ 僅限中繼資料的更新 （不含 `content`) 會保留現有的匯入來源，而不會從儲存庫重新擷取。

### 取得、列出、更新和刪除
<a name="get-list-update-and-delete"></a>

使用 `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>
```

### 將單一檔案新增至現有技能
<a name="add-a-single-file-to-an-existing-skill"></a>

如果您已從 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`。

### 啟用和停用技能
<a name="activating-and-deactivating-skills"></a>

技能在 中具有啟用狀態`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`在任何其他資產類型的設定沒有效果，且 欄位會從回應中捨棄。

## 其他資產類型的範例
<a name="examples-for-the-other-asset-types"></a>

上述技能演練適用於所有其他資產類型。唯一的差別是 `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 檔案建置請求，如[從二進位檔案建立技能](#create-a-skill-from-a-binary-file)所示）：

```
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
```