本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

管理资产

AWS DevOps 代理将座席空间的配置和参考资料存储为资产，这些资源是客户管理的资源，这些资源决定了代理所知道的内容和行为方式。技能、 AGENTS.md 文件和附件都是资产，您可以通过资产 API 以编程方式创建、读取、更新和删除它们。

本主题介绍资产模型、您需要的 IAM 权限、每种资产类型期望的元数据，以及如何使用适用于 Python 的 AWS CLI 和 AWS SDK (Boto3) 进行端到端的资产管理。有关技能本身的概念概述，请参阅DevOps 特工技能。有关不是您自己创建的代理生成的知识，请参阅。学到的技能

何时使用资产 API

Operator Web App 是创作单项技能或以交互方式上传 AGENTS.md 文件的最快方法。Asset API 以编程方式公开了相同的操作，因此脚本和自动化无需通过 Web 应用程序即可管理资产。直接调用资产 API 的常见原因包括：

资产 API 中的每个操作都通过 AWS CLI aws devops-agent <operation> 和作为devops-agent客户端的 AWS SDK 公开。

资产 API 操作

资产 API 公开了以下操作。每行都列出了您必须授权才能调用该操作的 IAM 操作以及该操作适用的资源。每个操作都存在于aidevops:命名空间中，除此之外都适用于形式为 Agent Space 的资源arn:aws:aidevops:<region>:<account-id>:agentspace/<agentSpaceId>。ListAssetTypes有关aidevops:权限的更广泛背景信息，请参阅DevOps 代理 IAM 权限。

示例 IAM policies

以下策略授予对单个代理空间中资产的完全管理权限：

{
  "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 可以创建六种资产类型：skillagents_md、attachment、custom_agent、test_profile、和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。一个特工空间最多可以包含 200 个用户创建的技能。

agents_md

agents_md资产是一个 markdown 文件，其中包含特定代理类型的常设代理指令。代理会在每个任务开始 AGENTS.md 时加载匹配项。有关代理说明的更多信息，请参阅代理说明。

必需的metadata属性：

示例metadata：

{
  "agent_type": "INCIDENT_TRIAGE"
}

限制：每个代理空间最多只能包含一个 AGENTS.md agent_type。文件内容必须为 markdown (text/markdown) 且不得超过 25 KB。

连接

attachment资产存储代理可以在调查期间参考的二进制文件或文本文件，例如架构图、runbook PDF 或示例日志文件。

必需的metadata属性：

示例metadata：

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

限制：座席空间中所有附件的总大小不能超过 10 GB。

自定义代理

custom_agent资产定义了具有精选工具和技能的专业代理配置。使用自定义代理将代理范围限定为特定的工作流程或一组功能。

必需的metadata属性：

可选metadata属性：

示例metadata：

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

测试配置文件

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

资产内容：文件或 zip

每个CreateAsset请求都包含一个content对象，用于保存资产存储的字节。的形状content取决于您上传的是单个文件还是 zip 包：

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。

端到端管理技能

接下来的演练以三种不同的方式创建技能（来自单个文本文件、二进制文件和 zip 包），然后练习读取、更新和删除操作。8f6187a7-0388-4926-8217-3a0fe32f757c替换为您的代理空间 ID。

从单个文本文件创建技能

这是最简单的路径：内联上传单个SKILL.md文件。由于上传内容仅包含一个文本文件，因此您必须提供name和descriptionmetadata。

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 作为技能主体。由于请求正文包含嵌套在并集内部的 base64 编码的 blob，因此请提前提供来自 JSON 文件的请求--cli-input-json并对 blob 进行 base64 编码。content

下面的-w 0标志告诉 GNU base64 在一行上发出编码的 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},
        }
    },
)

使用压缩包创建技能

当技能包含多个文件（例如，SKILL.md加号参考资料和资产）时，请使用 zip 上传。对于 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必须包含 frontmatter 这样服务才能提取名称和描述：

---
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 特工获取技能内容，从 f SKILL.md rontmatter 中提取名称和描述，然后在你的特工空间中创建技能。这使您可以管理版本控制中的技能，并以编程方式导入或同步这些技能。

先决条件：

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

该服务获取目录内容，读取和 SKILL.md 的前置内容description，name然后导入所有文件。不要包含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用于在不重新上传内容的情况下更改一个或多个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用于检查资产的版本历史记录。每次成功UpdateAssetFile调用UpdateAsset或调用都会提高资产的版本号：

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 捆绑包中创建了技能，并且想要添加一个新的参考文件，则无需重新上传整个捆绑包。使用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始终包含技能资产statusmetadata的当前值，这样您就可以随时读取实时激活状态。

该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