Managing Assets

AWS DevOps Agent stores the configuration and reference material for an Agent Space as assets, the customer-managed resources that shape what the agent knows and how it behaves. Skills, AGENTS.md files, and attachments are all assets, and you can create, read, update, and delete them programmatically through the Asset API.

This topic explains the asset model, the IAM permissions you need, the metadata each asset type expects, and how to manage assets end-to-end with the AWS CLI and AWS SDK for Python (Boto3). For the conceptual overview of skills themselves, see DevOps Agent Skills. For agent-generated knowledge that you do not create yourself, see Learned Skills.

When to use the Asset API

The Operator Web App is the fastest way to author a single skill or upload an AGENTS.md file interactively. The Asset API exposes the same operations programmatically so that scripts and automation can manage assets without going through the Web App. Common reasons to call the Asset API directly include:

Every operation in the Asset API is exposed through the AWS CLI as aws devops-agent <operation> and through the AWS SDKs as the devops-agent client.

Asset API operations

The Asset API exposes the following operations. Each row lists the IAM action you must grant to call the operation and the resource the action applies to. Every action lives in the aidevops: namespace and, except for ListAssetTypes, applies to an Agent Space resource of the form arn:aws:aidevops:<region>:<account-id>:agentspace/<agentSpaceId>. For broader background on aidevops: permissions, see DevOps Agent IAM permissions.

Example IAM policies

The following policy grants full management access to assets in a single Agent Space:

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

The following policy grants read-only access to assets in a single Agent Space:

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

Asset types

Every asset has an assetType string that identifies what kind of resource it is. Six asset types can be created through the Asset API: skill, agents_md, attachment, custom_agent, test_profile, and feedback. The sections that follow describe each type. You can also call ListAssetTypes to retrieve the type identifiers at runtime.

Each asset carries a free-form metadata JSON object that describes the resource. The keys inside metadata use snake_case (for example, agent_types, skill_type). The keys outside metadata, at the top level of the request body, use camelCase (for example, agentSpaceId, assetType, clientToken). The required and optional metadata keys depend on the asset type, as described in the sections that follow.

When you call UpdateAsset or UpdateAssetFile, the service applies PATCH semantics to metadata: keys that you include are replaced, and keys that you omit retain their stored values. You cannot change an asset's assetType after it has been created.

skill

A skill asset packages instructions and reference material that the agent loads when relevant. A simple skill is a single SKILL.md file; a complex skill is a zip bundle that contains a SKILL.md file plus optional references/ or assets/ directories.

Required metadata properties:

Optional metadata properties:

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

Limits: Zip uploads must not exceed 6 MB. An Agent Space can contain up to 200 user-created skills.

agents_md

An agents_md asset is a markdown file containing standing agent instructions for a specific agent type. The agent loads the matching AGENTS.md at the start of every task. For more information about agent instructions, see Agent instructions.

Required metadata properties:

Example metadata:

{
  "agent_type": "INCIDENT_TRIAGE"
}

Limits: Each Agent Space can contain at most one AGENTS.md per agent_type. The file content must be markdown (text/markdown) and must not exceed 25 KB.

attachment

An attachment asset stores a binary or text file that the agent can reference during investigations, for example, an architecture diagram, a runbook PDF, or a sample log file.

Required metadata properties:

Example metadata:

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

Limits: The total size of all attachments in an Agent Space cannot exceed 10 GB.

custom_agent

A custom_agent asset defines a specialized agent configuration with a curated set of tools and skills. Use a custom agent to scope the agent to a specific workflow or set of capabilities.

Required metadata properties:

Optional metadata properties:

Example metadata:

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

test_profile

A test_profile asset stores a reusable configuration for a release-testing run, including the kind of testing to perform and the target endpoint.

Required metadata properties:

Optional metadata properties:

Example 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 feedback asset records customer-provided feedback on a single agent execution. Use feedback assets to capture verdicts and notes that downstream evaluation pipelines can aggregate.

Required metadata properties:

Optional metadata properties:

Example metadata:

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

Asset content: file or zip

Every CreateAsset request includes a content object that holds the bytes the asset stores. The shape of content depends on whether you are uploading a single file or a 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>" } } }

To add, replace, or delete individual files inside an existing asset without re-uploading the whole bundle, use CreateAssetFile, UpdateAssetFile, and DeleteAssetFile.

Managing a skill end-to-end

The walkthrough that follows creates a skill three different ways (from a single text file, from a binary file, and from a zip bundle), and then exercises the read, update, and delete operations. Replace 8f6187a7-0388-4926-8217-3a0fe32f757c with your Agent Space ID.

Create a skill from a single text file

This is the simplest path: a single SKILL.md file uploaded inline. Because the upload contains exactly one text file, you must supply name and description in 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"]

Create a skill from a binary file

Use a binary upload when the skill content is not UTF-8 text. The example below uploads a pre-rendered PDF as the skill body. Because the request body contains a base64-encoded blob nested inside the content union, supply the request from a JSON file with --cli-input-json and base64-encode the blob ahead of time.

The -w 0 flag below tells GNU base64 to emit the encoded blob on a single line; without it the default 76-character line wrap inserts newlines that produce invalid JSON when the blob is interpolated into the heredoc. On macOS, use base64 -i ops-runbook.pdf (the BSD base64 does not wrap by default).

Build the request body:

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},
        }
    },
)

Create a skill from a zip bundle

Use a zip upload when the skill includes more than one file, for example, a SKILL.md plus reference material and assets. For zip uploads the service reads name and description from the SKILL.md frontmatter, so do not include them in metadata.

The zip layout looks like:

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

SKILL.md must include frontmatter so the service can extract the name and description:

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

Build the request body:

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}},
)

Get, list, update, and delete

Use GetAsset to retrieve a single asset by ID:

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

Use ListAssets to page through every asset in an Agent Space:

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>

Use UpdateAsset to change one or more metadata fields without re-uploading content. Keys that you omit keep their existing values:

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

Use ListAssetVersions to inspect the version history of an asset. Each successful UpdateAsset or UpdateAssetFile call advances the asset's version number:

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

Use DeleteAsset to remove the asset and all of its files:

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

Add a single file to an existing skill

If you already created a skill from a zip bundle and want to add one new reference file, you do not need to re-upload the whole bundle. Use 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." }'

To replace the file in place, use update-asset-file with the same arguments. To remove it, use delete-asset-file.

Activating and deactivating skills

Skills carry an activation state in metadata.status. New skills are ACTIVE by default and are loaded by the agent during investigations and chat. You can deactivate a skill to take it out of rotation without deleting it, for example while you investigate why it is producing unexpected results, and reactivate it later.

Set the initial state on create by including metadata.status in the CreateAsset request:

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

Deactivate an existing skill with UpdateAsset. Because metadata is applied as a partial update, sending only status leaves every other field intact:

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

Reactivate the same way, with "status": "ACTIVE":

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

GetAsset and ListAssets always include the current status in metadata for skill assets, so you can read the live activation state at any time.

The status field is case-sensitive. Only ACTIVE and INACTIVE (uppercase) are accepted. Any other value fails with a ValidationException. Activation applies only to skills; setting metadata.status on any other asset type has no effect and the field is dropped from the response.

Examples for the other asset types

The skill walkthrough above applies to every other asset type. The only difference is the metadata block and, for attachments, the choice of binary content. The minimal CreateAsset calls below illustrate each type.

Create an 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." }
    }
  }'

Create an attachment (binary content; build the request from a JSON file as shown in 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

Create a custom agent:

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

Create a test profile:

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

Create a feedback asset:

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

List supported asset types:

aws devops-agent list-asset-types