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

# Conecte-se aos servidores remotos do DevOps Agent
<a name="accessing-devops-agent-connect-to-devops-agent-remote-servers"></a>

AWS DevOps O agente fornece servidores remotos dedicados para o protocolo Model Context Protocol (MCP) e Agent-to-Agent (A2A). Use esses servidores para conectar seu IDE, CLI ou integrações personalizadas de agentes a um Espaço do Agente.

## Protocolos compatíveis
<a name="supported-protocols"></a>
+ **MCP (Model Context Protocol)** — Conecte clientes IDE e CLI, como Kiro, Claude Code, Cursor e outras ferramentas. MCP-compatible 
+ **A2A (Agent-to-Agent) v1.0 —** Conecte agentes autônomos para comunicação entre agentes.

## Endpoints
<a name="endpoints"></a>

Os servidores remotos estão disponíveis em uma URL regional:

```
https://connect.aidevops.{region}.api.aws
```


| Protocolo | Path | Método | 
| --- | --- | --- | 
| MCP | /mcp | POST | 
| A2A | /a2a/\* | POST | 
| Cartão de agente A2A | /.well-known/agent-card.json | GET | 

Para ver a lista de regiões disponíveis, consulte[Regiões aceitas](about-aws-devops-agent-supported-regions.md).

## Autenticação
<a name="authentication"></a>

Dois métodos de autenticação estão disponíveis para endpoints MCP e A2A:
+ **Token de acesso (portador)** — Um único token com escopo limitado a um espaço de agente. Configuração mais simples para uso individual.
+ **AWS SigV4** — autenticação baseada em AWS credenciais. Oferece suporte a vários Agent Spaces e se integra à governança de AWS identidade existente. Processado automaticamente pelo [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws), um proxy local que assina solicitações usando suas credenciais. AWS 

## Crie um token de acesso
<a name="create-an-access-token"></a>

### Pré-requisitos
<a name="prerequisites"></a>
+ O recurso de tokens de acesso deve estar ativado no seu Espaço do Agente.
+ Você deve ter permissões do IAM para gerenciar tokens de acesso (`aidevops:CreateAccessToken`,`aidevops:RevokeAccessToken`,`aidevops:RotateAccessToken`). Para ver a lista completa, consulte [DevOps Permissões do Agent IAM](aws-devops-agent-security-devops-agent-iam-permissions.md).

### Ativar tokens de acesso
<a name="enable-access-tokens"></a>

1. Faça login no console AWS de gerenciamento e abra o console do AWS DevOps agente.

1. Escolha seu Espaço do Agente.

1. Escolha a guia **Configuração**.

1. Na seção **Tokens de acesso**, escolha **Ativar**.

1. Confirme a ação.

### Crie um token
<a name="create-a-token"></a>

1. Abra o aplicativo web do DevOps Agente para seu Espaço do Agente e, no menu de navegação, escolha **Configurações** e, em seguida, escolha **Tokens de acesso**.

1. Escolha **Gerar token**.

1. Insira um nome para o token.

1. Escolha um escopo:
   + `read`— Visualize investigações, recomendações, bate-papos e recursos do Agent Space.
   + `operate`— Acesso total. Inclui tudo`read`, além de enviar mensagens, criar bate-papos e gerenciar tarefas e recomendações da lista de pendências.

1. Escolha um tipo de cliente:
   + `human`— Para uso de IDE e CLI (Kiro, Claude Code, Cursor e outras ferramentas interativas).
   + `agent`— Para integrações A2A autônomas e agentes programáticos.

1. Defina uma expiração (1 a 60 dias).

1. Copie o valor do token e guarde-o em um local seguro, como o [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html). Você não pode recuperá-lo novamente.

Depois de criar um token, o aplicativo web exibe um exemplo de configuração que você pode copiar diretamente para o seu cliente.

## Conecte-se com Kiro
<a name="connect-with-kiro"></a>

Para usuários do [Kiro](https://kiro.dev/), um poder de **AWS DevOps agente** dedicado está disponível no IDE ou no mercado do [Kiro Powers](https://kiro.dev/powers/#aws-devops-agent).

**Etapa 1: instalar a alimentação**

Instale o poder do **aws-devops-agent do mercado Powers**.

**Etapa 2: definir variáveis de ambiente**

Defina as seguintes variáveis de ambiente para configurar a conexão:

```
DEVOPS_AGENT_TOKEN=<your-access-token>
DEVOPS_AGENT_REGION=<your-agent-space-region>
```

**Etapa 3: Aprovar as variáveis no Kiro**

Vá para **Configurações** > **MCP Approved Env Vars e aprove** e. `DEVOPS_AGENT_TOKEN` `DEVOPS_AGENT_REGION` O Kiro não passa variáveis de ambiente para os servidores MCP até que sejam aprovadas.

**Etapa 4: reinicie o Kiro**

Reinicie o Kiro para aplicar as alterações.

O poder do Kiro inclui `aws-mcp` um substituto, que fornece acesso direto à AWS API quando o endpoint do servidor remoto não está disponível.

## Conecte-se com Claude Code
<a name="connect-with-claude-code"></a>

Para usuários [do Claude Code](https://code.claude.com/docs/en/overview), o AWS DevOps Agent está disponível no plug-in **aws-agents-for-devsecops** Claude, que traz os recursos do Agente e do Security Agent para Claude. AWS DevOps AWS Instale-o a partir dos [plug-ins Claude](https://claude.com/plugins/aws-agents-for-devsecops) ou do [repositório de origem](https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-agents-for-devsecops).

1. Instale o plug-in **aws-agents-for-devsecops**.

1. Execute o `/aws-agents-for-devsecops:setup-devops-agent` comando para configurar sua conexão.

## Conecte-se com outros clientes MCP
<a name="connect-with-other-mcp-clients"></a>

Para qualquer MCP-compatible cliente, configure o servidor com:
+ **URL** — `https://connect.aidevops.{region}.api.aws/mcp`
+ **Cabeçalho de autorização** — `Bearer <your-token>`
+ **Tempo limite** — mínimo de 120 segundos (as respostas iniciais podem levar de 5 a 30 segundos; as sessões de bate-papo em andamento podem demorar mais)

Essa configuração também funciona com Kiro e Claude Code se você preferir configurar a conexão manualmente em vez de usar a alimentação ou o plug-in dedicados.

Exemplo de configuração MCP:

```
{
  "mcpServers": {
    "aws-devops-agent": {
      "url": "https://connect.aidevops.{region}.api.aws/mcp",
      "headers": {
        "Authorization": "Bearer <your-access-token>"
      }
    }
  }
}
```

`{region}`Substitua pela região do seu Espaço do Agente (por exemplo,`us-east-1`) e `<your-access-token>` pelo valor do token.

## Use a autenticação SigV4
<a name="use-sigv4-authentication"></a>

A autenticação SigV4 usa suas AWS credenciais em vez de um token de acesso. Os plug-ins Kiro power e Claude Code incluem suporte SigV4 integrado`mcp-proxy-for-aws`, que assina solicitações usando suas credenciais locais. AWS 

### Quando o SigV4 é usado
<a name="when-sigv4-is-used"></a>
+ Como **alternativa quando** o token de acesso não está configurado ou falha (expirado, inválido).
+ Como autenticação **primária** quando você tem vários Agent Spaces e precisa passar `agent_space_id` por chamada de ferramenta.
+ Como **opção do usuário**, no Claude Code, execute a habilidade de configuração para mudar do token do portador para a autenticação SigV4.

### Pré-requisitos
<a name="prerequisites"></a>
+ AWS credenciais disponíveis no ambiente (por meio de SSO, variáveis de ambiente ou arquivo de credenciais).
+ Suas credenciais devem ter permissão para invocar ações do AWS DevOps Agente. Para ver as permissões necessárias, consulte [DevOps Permissões do Agent IAM](aws-devops-agent-security-devops-agent-iam-permissions.md).
+ `uvx`instalado (o proxy é executado`uvx mcp-proxy-for-aws@latest`).

### Exemplo de configuração
<a name="example-configuration"></a>

Para configurar um cliente MCP para usar SigV4 em vez de um token de acesso, execute o servidor por meio de. `mcp-proxy-for-aws` `{region}`Substitua pela região do seu Espaço do Agente (por exemplo,`us-east-1`):

```
{
  "mcpServers": {
    "aws-devops-agent": {
      "command": "uvx",
      "timeout": 120000,
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://connect.aidevops.{region}.api.aws/mcp",
        "--service", "aidevops",
        "--region", "{region}"
      ]
    }
  }
}
```

O proxy assina cada solicitação com suas AWS credenciais locais, portanto, nenhum token de acesso é necessário.

### Multi-Agent-Space roteamento
<a name="multi-agent-space-routing"></a>

No modo SigV4, transmita `agent_space_id` cada chamada de ferramenta para especificar qual espaço do agente usar. Isso possibilita o roteamento entre vários Agent Spaces a partir de um único cliente.

## Integração A2A
<a name="a2a-integration"></a>

O endpoint A2A implementa a especificação A2A v1.0 usando a vinculação [HTTP\+JSON](https://a2a-protocol.org/latest/specification/).

### Descoberta do cartão do agente
<a name="agent-card-discovery"></a>

Recupere o cartão do agente em:

```
GET https://connect.aidevops.{region}.api.aws/.well-known/agent-card.json
```

### Operações compatíveis
<a name="supported-operations"></a>
+ `SendMessage`— Envie uma mensagem e receba uma resposta.
+ `SendStreamingMessage`— Transmita as respostas à medida que elas são geradas.
+ `GetTask`— Verifique o status de uma tarefa assíncrona.
+ `ListTasks`— Listar tarefas para um Agent Space.
+ `CancelTask`— Cancelar uma tarefa em execução.
+ `SubscribeToTask`— Inscreva-se para receber atualizações de tarefas por meio de eventos enviados pelo servidor.

### Habilidades
<a name="skills"></a>
+ **investigue** — Análise assíncrona profunda de problemas operacionais (5 a 8 minutos).
+ **chat** — Respostas instantâneas às perguntas operacionais.

## Considerações sobre segurança
<a name="security-considerations"></a>

### Escopo do token
<a name="token-scoping"></a>
+ Use o menor privilégio: escolha integrações somente `read` para leitura, `operate` somente quando o cliente precisar enviar mensagens ou gerenciar tarefas.
+ Gire os tokens periodicamente. Os tokens expiram após a duração configurada (máximo de 60 dias).
+ Armazene tokens em variáveis de ambiente ou gerenciadores de segredos. Não codifique tokens no código-fonte.
+ Não execute automaticamente as respostas do agente sem a revisão humana.

### Lista de permissões de IP
<a name="ip-allowlist"></a>

Ao criar um token de acesso, você pode, opcionalmente, especificar uma lista de permissões de IP. Quando configurado, o token só pode ser usado a partir dos endereços IP ou intervalos CIDR especificados. Solicitações de outros IPs são rejeitadas com um erro de acesso negado.

### Rotação e revogação de tokens
<a name="token-rotation-and-revocation"></a>
+ **Rotação** — gire um token para gerar um novo valor de token, preservando o nome, os escopos e a lista de permissões de IP do token. O token antigo é imediatamente invalidado. Atualize a configuração do seu cliente com o novo valor do token.
+ **Revogação** — Se um token for comprometido, revogue-o imediatamente. Os tokens revogados não podem ser usados e não podem ser restaurados.

#### Respondendo a um token comprometido
<a name="responding-to-a-compromised-token"></a>

Se você suspeitar que um token foi comprometido, siga estas etapas:

1. **Bloquear todo o AWS DevOps acesso ao token** — No console do agente, abra seu Espaço do agente, escolha a guia **Configuração** e escolha **Desativar** na seção Tokens de acesso. Isso bloqueia imediatamente todo o acesso baseado em tokens ao Espaço do Agente.

1. **Revogar tokens comprometidos** **— No aplicativo web, acesse **Configurações** > **Tokens de acesso**, escolha o token comprometido e escolha Revogar.** Você pode revogar tokens mesmo quando os tokens de acesso estão desativados.

1. **Re-enable tokens de acesso** — Depois de revogar os tokens comprometidos, reative os tokens de acesso na guia **Configuração** se você ainda precisar de acesso baseado em tokens.

#### Revogando tokens programaticamente
<a name="revoking-tokens-programmatically"></a>

Você também pode revogar tokens de forma programática usando. `awscurl` Os comandos a seguir usam a autenticação SigV4. Substitua a Região (`us-east-1`) pela Região em que seu Espaço do Agente foi criado.

**Nota:** A etapa 1 usa a AWS CLI. As etapas 2 e 3 usam [awscurl](https://github.com/okigan/awscurl), uma ferramenta de linha de comando que assina solicitações HTTP com SigV4, porque as operações de token de acesso ainda não têm comandos CLI dedicados. AWS 

**Etapa 1: Listar seus espaços de agente**

```
aws aidevops list-agent-spaces --region us-east-1
```

**Etapa 2: Listar tokens de acesso para um Espaço do Agente**

```
awscurl --service aidevops --region us-east-1 \
  -H "Accept: application/json" \
  "https://cp.aidevops.us-east-1.api.aws/v1/agentspaces/{agentSpaceId}/access-tokens"
```

**Etapa 3: revogar um token**

```
awscurl --service aidevops --region us-east-1 -X POST \
  -H "Accept: application/json" \
  "https://cp.aidevops.us-east-1.api.aws/v1/agentspaces/{agentSpaceId}/access-tokens/{accessTokenId}/revoke"
```

`{accessTokenId}`Substitua `{agentSpaceId}` e pelos valores das respostas anteriores.

### Rastreabilidade
<a name="traceability"></a>

Quando um token de acesso é usado, o AWS DevOps agente assume uma função em seu nome para realizar ações. Essa `AssumeRole` chamada é registrada AWS CloudTrail com tags de sessão que identificam o token e o chamador:
+ `AgentSpaceId`— Identificador do espaço do agente.
+ `UserId`— Identidade do criador do token.
+ `AccessTokenId`— Identificador exclusivo do token.
+ `TokenName`— Nome do token de acesso usado.
+ `ClientType`— O protocolo usado (MCP, A2A).
+ `SourceIp`— Endereço IP do cliente.
+ `UserAgent`— User-Agent Cadeia de caracteres do cliente (quando disponível).

As invocações diretas de endpoint MCP e A2A não estão registradas em nenhum dos métodos de autenticação. CloudTrail Cada invocação tem uma chamada de AWS API downstream correspondente registrada CloudTrail, com um nome de sessão de função identificável no formato. `token_{spaceId}_{timestamp}_{tokenName}`

### Limitação da política de VPC endpoint
<a name="vpc-endpoint-policy-limitation"></a>

Os endpoints do servidor remoto não oferecem suporte às políticas de endpoints de VPC. As chamadas usando tokens de acesso ou autenticação SigV4 não podem ser restringidas pelas políticas de endpoint da VPC.

### Desativando tokens de acesso
<a name="disabling-access-tokens"></a>

O recurso de tokens de acesso está desativado por padrão. Para desativá-lo após a ativação:

1. Abra a guia **Configuração** do seu Espaço do Agente.

1. Na seção **Tokens de acesso**, escolha **Desativar**.

A desativação bloqueia imediatamente todo o acesso baseado em token. Os tokens existentes não são excluídos, mas não podem ser usados até que o recurso seja reativado.

Para impedir que os usuários da sua organização habilitem tokens de acesso, crie uma Política de Controle de Serviços (SCP) que negue as ações da API do token de acesso e a `UpdateAgentSpace` ação (que controla a alternância dos tokens de acesso):

**Nota:** Negar `aidevops:UpdateAgentSpace` também impede outras atualizações do Agent Space (nome, descrição, localidade). Se isso for muito amplo, omita-o do SCP — as negações restantes ainda impedem a criação e o uso do token, mesmo que alguém habilite o recurso.

```
{
  "Version": "2012-10-17",		 	 	 		 	 	 
  "Statement": [
    {
      "Sid": "DenyAccessTokenOperations",
      "Effect": "Deny",
      "Action": [
        "aidevops:UpdateAgentSpace",
        "aidevops:CreateAccessToken",
        "aidevops:GetAccessToken",
        "aidevops:ListAccessTokens",
        "aidevops:RotateAccessToken",
        "aidevops:RevokeAccessToken"
      ],
      "Resource": "*"
    }
  ]
}
```

## Solução de problemas
<a name="troubleshooting"></a>


| Sintomas | Causa | Resolução | 
| --- | --- | --- | 
| HTTP 401 Não autorizado | O token é inválido ou expirou. | Crie um novo token ou gire o token existente no aplicativo web. | 
| HTTP 400 “A2A-Version cabeçalho obrigatório” | Falta o cabeçalho da versão do protocolo. Somente o A2A v1.0 é suportado. | Adicione A2A-Version: 1.0 cabeçalho às solicitações A2A. | 
| Tempo limite da solicitação | As respostas iniciais levam de 5 a 30 segundos. As investigações levam de 5 a 8 minutos. | Defina o tempo limite do cliente para pelo menos 120 segundos. | 
| Conexão recusada | URL ou região do endpoint incorretos. | Verifique o formato do URL: https://connect.aidevops.{region}.api.aws |