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

# 连接到 DevOps Agent 远程服务器
<a name="accessing-devops-agent-connect-to-devops-agent-remote-servers"></a>

AWS DevOps 代理为模型上下文协议 (MCP) 和 Agent-to-Agent (A2A) 协议提供专用的远程服务器。使用这些服务器将 IDE、CLI 或定制代理集成连接到代理空间。

## 受支持的协议
<a name="supported-protocols"></a>
+ **MCP（模型上下文协议）**— 连接 IDE 和 CLI 客户端，例如 Kiro、Claude Code、Cursor 和其他工具。 MCP-compatible 
+ **A2A (Agent-to-Agent) v1.0 — C** onnect 自治代理进行代理与代理之间的通信。

## 端点
<a name="endpoints"></a>

远程服务器可通过区域 URL 获得：

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


| 协议 | 路径 | 方法 | 
| --- | --- | --- | 
| MCP | /mcp | POST | 
| A2A | /a2a/\* | POST | 
| A2A 特工卡 | /.well-known/agent-card.json | GET | 

有关可用区域的列表，请参阅[支持的区域：](about-aws-devops-agent-supported-regions.md)。

## 身份验证
<a name="authentication"></a>

MCP 和 A2A 端点都有两种身份验证方法可用：
+ **访问令牌（持有者）**— 限定为一个代理空间的单个令牌。最简单的设置，供个人使用。
+ **AWS Sigv4** — 基于 AWS 凭据的身份验证。支持多个代理空间，并与现有的 AWS 身份管理集成。由 [mcp-proxy-for-aw](https://github.com/aws/mcp-proxy-for-aws) s 自动处理，这是一种使用您的证书签署请求的本地代理。 AWS 

## 创建访问令牌
<a name="create-an-access-token"></a>

### 先决条件
<a name="prerequisites"></a>
+ 必须在 Agent Space 上启用访问令牌功能。
+ 您必须拥有 IAM 权限才能管理访问令牌（`aidevops:CreateAccessToken``aidevops:RevokeAccessToken`、、`aidevops:RotateAccessToken`）。完整列表请参阅 [DevOps 代理 IAM 权限](aws-devops-agent-security-devops-agent-iam-permissions.md)。

### 启用访问令牌
<a name="enable-access-tokens"></a>

1. 登录 AWS 管理控制台并打开 AWS DevOps 代理控制台。

1. 选择您的代理空间。

1. 选择**配置**选项卡。

1. 在**访问令牌**部分中，选择**启用**。

1. 确认该操作。

### 创建代币
<a name="create-a-token"></a>

1. 打开 A DevOps gent Space 的 Agent Web 应用程序，然后从导航菜单中选择**设置**，然后选择**访问令牌**。

1. 选择**生成令牌**。

1. 输入令牌的名称。

1. 选择一个范围：
   + `read`— 查看调查、推荐、聊天和 Agent Space 资源。
   + `operate`— 完全访问权限。包括其中的所有内容`read`，以及发送消息、创建聊天以及管理待办事项和推荐。

1. 选择客户机类型：
   + `human`— 用于 IDE 和 CLI 的使用（Kiro、Claude Code、Cursor 和其他交互式工具）。
   + `agent`— 用于自主 A2A 集成和编程代理。

1. 设置到期时间（1 到 60 天）。

1. 复制令牌值并将其存储在安全可靠的位置，例如 Secr [AWS ets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。您无法再次检索它。

创建令牌后，Web 应用程序会显示一个配置示例，您可以将其直接复制到客户端。

## Connect with Kiro
<a name="connect-with-kiro"></a>

对于 [Kiro](https://kiro.dev/) 用户，可以从 IDE 或 K [iro Powers 市场获得专用的**AWS DevOps 代理**权限](https://kiro.dev/powers/#aws-devops-agent)。

**第 1 步：安装电源**

安装来自 Powers **市场的 aws-devops-agent** power。

**步骤 2：设置环境变量**

设置以下环境变量来配置连接：

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

**第 3 步：批准 Kiro 中的变量**

前往 **“设置” > “****MCP 批准的环境变量”，然后**批准和。`DEVOPS_AGENT_TOKEN` `DEVOPS_AGENT_REGION`在环境变量获得批准之前，Kiro 不会将环境变量传递给 MCP 服务器。

**第 4 步：重启 Kiro**

重启 Kiro 以应用更改。

Kiro 的功能包括后备功能，`aws-mcp`当远程服务器端点不可用时，它可以直接访问 AWS API。

## Connect with Code
<a name="connect-with-claude-code"></a>

对于 [Claude 用户， AWS DevOps 代理可通过 aws-agents-for-devseco](https://code.claude.com/docs/en/overview) **ps Claude 插件获得，该插件为 Claude 带来了代理**和安全代理功能。 AWS DevOps AWS 从 [Claude 插件](https://claude.com/plugins/aws-agents-for-devsecops)或[源代码库](https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-agents-for-devsecops)中安装它。

1. 安装 **aws-agents-for-d** evsecops 插件。

1. 运行`/aws-agents-for-devsecops:setup-devops-agent`命令来配置您的连接。

## 连接其他 MCP 客户端
<a name="connect-with-other-mcp-clients"></a>

对于任何 MCP-compatible 客户端，请使用以下命令配置服务器：
+ **网址** — `https://connect.aidevops.{region}.api.aws/mcp`
+ **授权标题** — `Bearer <your-token>`
+ **超时**-最少 120 秒（初始响应可能需要 5-30 秒；正在进行的聊天会话可能需要更长的时间）

如果您更喜欢手动配置连接，而不是使用专用电源或插件，则此配置也适用于 Kiro 和 Claude Code。

MCP 配置示例：

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

`{region}`替换为您的 Agent Space 的区域（例如`us-east-1`）和`<your-access-token>`代币值。

## 使用 Sigv4 身份验证
<a name="use-sigv4-authentication"></a>

Sigv4 身份验证使用您的 AWS 凭证而不是访问令牌。Kiro power 和 Claude Code 插件包括内置的 SigV4 支持`mcp-proxy-for-aws`，它使用你的本地凭据对请求进行签名。 AWS 

### 当使用 sigv4 时
<a name="when-sigv4-is-used"></a>
+ 作为未配置访问令牌或访问令牌失败（已过期、无效）时的**备**用方法。
+ 当您有多个代理空间并且需要通过`agent_space_id`每个工具调用进行路由时，作为**主要**身份验证。
+ 作为**用户选择** — 在 Claude Code 中，运行设置技能从 Bearer token 切换到 Sigv4 身份验证。

### 先决条件
<a name="prerequisites"></a>
+ AWS 环境中可用的凭证（通过 SSO、环境变量或凭据文件）。
+ 您的凭证必须具有调用 AWS DevOps 代理操作的权限。有关所需的权限，请参阅[DevOps 代理 IAM 权限](aws-devops-agent-security-devops-agent-iam-permissions.md)。
+ `uvx`已安装（代理通过`uvx mcp-proxy-for-aws@latest`）。

### 示例配置
<a name="example-configuration"></a>

要将 MCP 客户端配置为使用 Sigv4 而不是访问令牌，请运行服务器。`mcp-proxy-for-aws``{region}`替换为代理空间的区域（例如，`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}"
      ]
    }
  }
}
```

代理使用您的本地 AWS 凭证对每个请求进行签名，因此不需要访问令牌。

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

在 Sigv4 模式下，传递`agent_space_id`每个工具调用以指定要使用的代理空间。这使得从单个客户端跨多个代理空间进行路由成为可能。

## A2A 集成
<a name="a2a-integration"></a>

A2A 端点使用 HTTP\+JSON 绑定实现 [A2A v1.0 规范](https://a2a-protocol.org/latest/specification/)。

### 代理卡发现
<a name="agent-card-discovery"></a>

在以下地址取回代理卡：

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

### 支持的操作
<a name="supported-operations"></a>
+ `SendMessage`— 发送消息并接收回复。
+ `SendStreamingMessage`— 在生成响应时进行流式传输。
+ `GetTask`— 检查异步任务的状态。
+ `ListTasks`— 列出代理空间的任务。
+ `CancelTask`— 取消正在运行的任务。
+ `SubscribeToTask`— 通过服务器发送的事件订阅任务更新。

### 技能
<a name="skills"></a>
+ **调查 — 对**操作问题进行深度异步分析（5—8 分钟）。
+ **聊天** — 即时回答操作问题。

## 安全注意事项
<a name="security-considerations"></a>

### 代币范围界定
<a name="token-scoping"></a>
+ 使用最低权限：仅当客户端需要发送消息或管理任务时，`operate`才选择`read`只读集成。
+ 定期轮换代币。令牌将在配置的持续时间（最长 60 天）后过期。
+ 将令牌存储在环境变量或机密管理器中。不要在源代码中对令牌进行硬编码。
+ 未经人工审查，请勿自动执行代理响应。

### IP 许可名单
<a name="ip-allowlist"></a>

创建访问令牌时，您可以选择指定 IP 许可名单。配置后，该令牌只能在指定的 IP 地址或 CIDR 范围内使用。来自其他 IP 的请求会被拒绝，并显示拒绝访问错误。

### 代币轮换和撤销
<a name="token-rotation-and-revocation"></a>
+ **轮换 — 轮换**令牌以生成新的令牌值，同时保留令牌的名称、范围和 IP 许可名单。旧令牌立即失效。使用新的令牌值更新您的客户端配置。
+ **撤销** — 如果令牌被盗用，请立即将其撤销。已撤销的代币无法使用，也无法恢复。

#### 回应被盗的代币
<a name="responding-to-a-compromised-token"></a>

如果您怀疑令牌已被盗用，请按照以下步骤操作：

1. **阻止所有令牌访问**-在 AWS DevOps 代理控制台中，打开您的代理空间，选择**配置**选项卡，然后在访问令牌部分中选择**禁用**。这将立即阻止对代理空间的所有基于令牌的访问。

1. **撤消已泄露的令牌** — 在 Web 应用程序中，前往 **“设置” > “****访问令牌**”，选择已泄露的令牌，然后选择 “**撤销**”。即使禁用了访问令牌，您也可以撤消令牌。

1. **Re-enable 访问令牌** — 撤销已泄露的令牌后，如果您仍需要基于令牌的访问权限，请从 “**配置**” 选项卡中重新启用访问令牌。

#### 以编程方式撤销代币
<a name="revoking-tokens-programmatically"></a>

您也可以使用以编程方式撤消令牌。`awscurl`以下命令使用 Sigv4 身份验证。将区域 (`us-east-1`) 替换为创建代理空间的区域。

**注意：**步骤 1 使用 AWS CLI。步骤 2 和 3 使用 [awscurl，这是一种使用 S](https://github.com/okigan/awscurl) igv4 签署 HTTP 请求的命令行工具，因为访问令牌操作还没有专用 CLI 命令。 AWS 

**第 1 步：列出您的代理空间**

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

**步骤 2：列出代理空间的访问令牌**

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

**第 3 步：撤销代币**

```
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}`用先前响应中的值替换`{agentSpaceId}`和。

### 追溯性
<a name="traceability"></a>

使用访问令牌时， AWS DevOps 代理会代表您扮演一个角色来执行操作。此`AssumeRole`呼叫 AWS CloudTrail 使用标识令牌和呼叫者的会话标签登录：
+ `AgentSpaceId`— 代理空间的标识符。
+ `UserId`— 代币创建者的身份。
+ `AccessTokenId`— 令牌的唯一标识符。
+ `TokenName`— 使用的访问令牌的名称。
+ `ClientType`— 使用的协议（MCP、A2A）。
+ `SourceIp`— 客户机的 IP 地址。
+ `UserAgent`— 客户端 User-Agent 字符串（如果可用）。

两种身份验证方法都不会登录直接 MCP 和 A2A 端点调用。 CloudTrail 每次调用都登录了相应的下游 AWS API 调用 CloudTrail，其格式`token_{spaceId}_{timestamp}_{tokenName}`为可识别的角色会话名称。

### VPC 终端节点策略限制
<a name="vpc-endpoint-policy-limitation"></a>

远程服务器终端节点不支持 VPC 终端节点策略。VPC 终端节点策略无法限制使用访问令牌或 Sigv4 身份验证的呼叫。

### 禁用访问令牌
<a name="disabling-access-tokens"></a>

默认情况下，访问令牌功能处于关闭状态。要在启用后将其禁用，请执行以下操作：

1. 打开 “代理空间” 的 “**配置**” 选项卡。

1. 在 “**访问令牌**” 部分中，选择 “**禁用**”。

禁用会立即阻止所有基于令牌的访问。现有令牌不会被删除，但在重新启用该功能之前无法使用。

要防止组织中的用户启用访问令牌，请创建拒绝访问令牌 API 操作和操作（控制访问令牌切换）的`UpdateAgentSpace`服务控制策略 (SCP)：

**注意：**拒绝`aidevops:UpdateAgentSpace`还会阻止其他 Agent Space 更新（名称、描述、区域设置）。如果这太宽泛，请将其从 SCP 中省略——即使有人启用了该功能，其余的拒绝仍会阻止令牌的创建和使用。

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

## 问题排查
<a name="troubleshooting"></a>


| 症状 | 原因 | 解决方案 | 
| --- | --- | --- | 
| HTTP 401 未经授权 | 令牌无效或已过期。 | 在 Web 应用程序中创建新令牌或轮换现有令牌。 | 
| HTTP 400 “需要A2A-Version 标头” | 缺少协议版本标头。仅支持 A2A v1.0。 | 在 A2A 请求中添加A2A-Version: 1.0标头。 | 
| 请求超时 | 初始响应需要 5-30 秒。调查需要 5-8 分钟。 | 将客户端超时设置为至少 120 秒。 | 
| 连接被拒绝 | 终端节点 URL 或区域不正确。 | 验证 URL 格式：https://connect.aidevops.{region}.api.aws |