As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Gerenciando ativos

AWS DevOps O agente armazena a configuração e o material de referência de um Espaço do Agente como ativos, os recursos gerenciados pelo cliente que moldam o que o agente sabe e como ele se comporta. Habilidades, AGENTS.md arquivos e anexos são todos ativos, e você pode criá-los, lê-los, atualizá-los e excluí-los programaticamente por meio da API de ativos.

Este tópico explica o modelo de ativos, as permissões do IAM de que você precisa, os metadados que cada tipo de ativo espera e como gerenciar ativos de ponta a ponta com a AWS CLI e o AWS SDK for Python (Boto3). Para obter uma visão geral conceitual das habilidades em si, consulteDevOps Habilidades do agente. Para obter conhecimento gerado por agentes que você não cria sozinho, consulte. Habilidades aprendidas

Quando usar a API Asset

O Operator Web App é a maneira mais rápida de criar uma única habilidade ou carregar um AGENTS.md arquivo de forma interativa. A API de ativos expõe as mesmas operações programaticamente para que scripts e automação possam gerenciar ativos sem passar pelo aplicativo Web. Os motivos comuns para chamar diretamente a API Asset incluem:

Cada operação na API de ativos é exposta por meio da AWS CLI aws devops-agent <operation> e por meio dos AWS SDKs como cliente. devops-agent

Operações da API de ativos

A API Asset expõe as seguintes operações. Cada linha lista a ação do IAM que você deve conceder para chamar a operação e o recurso ao qual a ação se aplica. Cada ação reside no aidevops: namespace e, com exceção deListAssetTypes, se aplica a um recurso do Agent Space do formulário. arn:aws:aidevops:<region>:<account-id>:agentspace/<agentSpaceId> Para obter informações mais aidevops: amplas sobre permissões, consulteDevOps Permissões do Agent IAM.

Políticas de exemplo do IAM

A política a seguir concede acesso total de gerenciamento aos ativos em um único Espaço do Agente:

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

A política a seguir concede acesso somente para leitura aos ativos em um único Espaço do Agente:

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

Tipos de ativo

Cada ativo tem uma assetType string que identifica que tipo de recurso ele é. Seis tipos de ativos podem ser criados por meio da API de ativos: skill agents_mdattachment,custom_agent,test_profile,, feedback e. As seções a seguir descrevem cada tipo. Você também pode ligar ListAssetTypes para recuperar os identificadores de tipo em tempo de execução.

Cada ativo carrega um objeto metadata JSON de formato livre que descreve o recurso. As chaves internas metadata usam snake_case (por exemplo,,agent_types). skill_type As chaves externasmetadata, no nível superior do corpo da solicitação, usam CamelCase (por exemploagentSpaceId,,,assetType). clientToken As metadata chaves obrigatórias e opcionais dependem do tipo de ativo, conforme descrito nas seções a seguir.

Quando você chama UpdateAsset ouUpdateAssetFile, o serviço aplica a semântica PATCH ametadata: as chaves que você inclui são substituídas e as chaves que você omite mantêm seus valores armazenados. Você não pode alterar o ativo assetType depois que ele foi criado.

habilidade

Um skill ativo empacota instruções e material de referência que o agente carrega quando relevante. Uma habilidade simples é um único SKILL.md arquivo; uma habilidade complexa é um pacote zip que contém um SKILL.md arquivo e assets/ diretórios opcionaisreferences/.

metadataPropriedades necessárias:

metadataPropriedades opcionais:

Exemplometadata:

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

Limites: os uploads em Zip não devem exceder 6 MB. Um Espaço do Agente pode conter até 200 habilidades criadas pelo usuário.

agentes_md

Um agents_md ativo é um arquivo markdown contendo instruções permanentes do agente para um tipo específico de agente. O agente carrega a correspondência AGENTS.md no início de cada tarefa. Para obter mais informações sobre as instruções do agente, consulteInstruções do agente.

metadataPropriedades necessárias:

Exemplometadata:

{
  "agent_type": "INCIDENT_TRIAGE"
}

Limites: Cada Espaço do Agente pode conter no máximo um AGENTS.md poragent_type. O conteúdo do arquivo deve ser markdown (text/markdown) e não deve exceder 25 KB.

anexo

Um attachment ativo armazena um arquivo binário ou de texto que o agente pode referenciar durante as investigações, por exemplo, um diagrama de arquitetura, um PDF do runbook ou um arquivo de registro de amostra.

metadataPropriedades necessárias:

Exemplometadata:

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

Limites: O tamanho total de todos os anexos em um Espaço do Agente não pode exceder 10 GB.

agente personalizado

Um custom_agent ativo define uma configuração de agente especializado com um conjunto selecionado de ferramentas e habilidades. Use um agente personalizado para definir o escopo do agente para um fluxo de trabalho específico ou conjunto de recursos.

metadataPropriedades necessárias:

metadataPropriedades opcionais:

Exemplometadata:

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

perfil_teste

Um test_profile ativo armazena uma configuração reutilizável para uma execução de teste de versão, incluindo o tipo de teste a ser executado e o endpoint de destino.

metadataPropriedades necessárias:

metadataPropriedades opcionais:

Exemplometadata:

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

Um feedback ativo registra o feedback fornecido pelo cliente sobre a execução de um único agente. Use recursos de feedback para capturar veredictos e notas que os pipelines de avaliação posterior podem agregar.

metadataPropriedades necessárias:

metadataPropriedades opcionais:

Exemplometadata:

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

Conteúdo do ativo: arquivo ou zip

Cada CreateAsset solicitação inclui um content objeto que contém os bytes que o ativo armazena. O formato de content depende se você está carregando um único arquivo ou um pacote 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>" } } }

Para adicionar, substituir ou excluir arquivos individuais dentro de um ativo existente sem recarregar o pacote inteiroCreateAssetFile, use e. UpdateAssetFile DeleteAssetFile

Gerenciando uma habilidade de ponta a ponta

O passo a passo a seguir cria uma habilidade de três maneiras diferentes (a partir de um único arquivo de texto, de um arquivo binário e de um pacote zip) e, em seguida, exercita as operações de leitura, atualização e exclusão. 8f6187a7-0388-4926-8217-3a0fe32f757cSubstitua pelo seu ID do Agent Space.

Crie uma habilidade a partir de um único arquivo de texto

Esse é o caminho mais simples: um único SKILL.md arquivo carregado em linha. Como o upload contém exatamente um arquivo de texto, você deve fornecer name e description inserirmetadata.

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

Crie uma habilidade a partir de um arquivo binário

Use um upload binário quando o conteúdo da habilidade não for UTF-8 texto. O exemplo abaixo carrega um PDF pré-renderizado como corpo de habilidades. Como o corpo da solicitação contém um blob codificado em base64 aninhado dentro content da união, forneça a solicitação de um arquivo JSON --cli-input-json e codifique o blob com antecedência em base64.

O -w 0 sinalizador abaixo diz ao GNU base64 para emitir o blob codificado em uma única linha; sem ele, a quebra de linha padrão de 76 caracteres insere novas linhas que produzem JSON inválido quando o blob é interpolado no heredoc. No macOS, use base64 -i ops-runbook.pdf (o BSD base64 não empacota por padrão).

Crie o corpo da solicitação:

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

Crie uma habilidade a partir de um pacote zip

Use um upload zip quando a habilidade incluir mais de um arquivo, por exemplo, SKILL.md mais material de referência e ativos. Para uploads zip, o serviço lê name e sai description do SKILL.md frontmatter, portanto, não os inclua. metadata

O layout do zip se parece com:

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

SKILL.mddeve incluir frontmatter para que o serviço possa extrair o nome e a descrição:

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

Crie o corpo da solicitação:

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

Importar uma habilidade de um repositório

Você pode criar uma habilidade importando-a diretamente do diretório do GitHub repositório. AWS DevOps O agente busca o conteúdo da habilidade, extrai o nome e a descrição do SKILL.md frontmatter e cria a habilidade no seu Espaço do Agente. Isso permite gerenciar habilidades de controle de versão e importá-las ou sincronizá-las programaticamente.

Pré-requisitos:

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

O serviço busca o conteúdo do diretório, lê o SKILL.md frontmatter de name e e importa todos description os arquivos. Não inclua name ou description metadata entre — eles são extraídos automaticamente do frontmatter.

Sincronizando uma habilidade importada:

Para obter as alterações mais recentes do repositório, chame UpdateAsset comcontent.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"
        }
    },
)

A sincronização substitui totalmente o conteúdo da habilidade pelo estado atual do diretório do repositório. Os campos editáveis (status, tipos de agentes) são preservados.

Visualizando a fonte de importação:

GetAssetretorna as informações de origem metadata.source para habilidades importadas do repositório:

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

Restrições:

Obter, listar, atualizar e excluir

Use GetAsset para recuperar um único ativo por ID:

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

Use ListAssets para percorrer cada ativo em um Espaço do Agente:

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 para alterar um ou mais metadata campos sem recarregar o conteúdo. As chaves que você omite mantêm seus valores existentes:

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 para inspecionar o histórico de versões de um ativo. Cada UpdateAssetFile chamada UpdateAsset ou chamada bem-sucedida avança o número da versão do ativo:

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

Use DeleteAsset para remover o ativo e todos os seus arquivos:

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

Adicionar um único arquivo a uma habilidade existente

Se você já criou uma habilidade a partir de um pacote zip e deseja adicionar um novo arquivo de referência, não é necessário recarregar o pacote inteiro. UsoCreateAssetFile:

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

Para substituir o arquivo no local, use update-asset-file com os mesmos argumentos. Para removê-lo, usedelete-asset-file.

Ativando e desativando habilidades

As habilidades carregam um estado de ativação emmetadata.status. Por padrão, as novas habilidades são ACTIVE carregadas pelo agente durante as investigações e o bate-papo. Você pode desativar uma habilidade para tirá-la da rotação sem excluí-la, por exemplo, enquanto investiga por que ela está produzindo resultados inesperados e a reativa posteriormente.

Defina o estado inicial na criação incluindo metadata.status na CreateAsset solicitação:

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

Desative uma habilidade existente comUpdateAsset. Como metadata é aplicado como uma atualização parcial, o envio só status deixa todos os outros campos intactos:

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

Reative da mesma forma, com"status": "ACTIVE":

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

GetAssete ListAssets sempre inclua os dados atuais status dos ativos de habilidades, metadata para que você possa ler o estado de ativação ao vivo a qualquer momento.

O campo status diferencia maiúsculas de minúsculas. Somente ACTIVE e INACTIVE (maiúsculas) são aceitos. Qualquer outro valor falha com ValidationException a. A ativação se aplica somente às habilidades; a configuração metadata.status em qualquer outro tipo de ativo não tem efeito e o campo é removido da resposta.

Exemplos de outros tipos de ativos

O passo a passo de habilidades acima se aplica a todos os outros tipos de ativos. A única diferença é o metadata bloqueio e, para anexos, a escolha do conteúdo binário. As CreateAsset chamadas mínimas abaixo ilustram cada tipo.

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

Crie um anexo (conteúdo binário; crie a solicitação a partir de um arquivo JSON, conforme mostrado em Criar uma habilidade a partir de um arquivo binário):

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

Crie um agente personalizado:

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

Crie um perfil de teste:

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

Crie um ativo de feedback:

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

Liste os tipos de ativos compatíveis:

aws devops-agent list-asset-types