기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# DevOps Agent 원격 서버에 연결
<a name="accessing-devops-agent-connect-to-devops-agent-remote-servers"></a>

AWS DevOps Agent는 모델 컨텍스트 프로토콜(MCP) 및 Agent-to-Agent(A2A) 프로토콜을 위한 전용 원격 서버를 제공합니다. 이러한 서버를 사용하여 IDE, CLI 또는 사용자 지정 에이전트 통합을 에이전트 스페이스에 연결합니다.

## 지원되는 프로토콜
<a name="supported-protocols"></a>
+ **MCP(모델 컨텍스트 프로토콜)** - Kiro, Claude Code, Cursor 및 기타 MCP 호환 도구와 같은 IDE 및 CLI 클라이언트를 연결합니다.
+ **A2A(Agent-to-Agent) v1.0 -** agent-to-agent 통신을 위해 자율 에이전트를 연결합니다.

## 엔드포인트
<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).

## Authentication
<a name="authentication"></a>

MCP 및 A2A 엔드포인트 모두에 대해 두 가지 인증 방법을 사용할 수 있습니다.
+ **액세스 토큰(베어러)** - 하나의 에이전트 공간으로 범위가 지정된 단일 토큰입니다. 개별 사용을 위한 가장 간단한 설정입니다.
+ **AWS SigV4** – AWS 자격 증명 기반 인증. 여러 에이전트 스페이스를 지원하고 기존 AWS 자격 증명 거버넌스와 통합됩니다. 자격 AWS 증명을 사용하여 요청에 서명하는 로컬 프록시인 [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws)에서 자동으로 처리합니다.

## 액세스 토큰 생성
<a name="create-an-access-token"></a>

### 사전 조건
<a name="prerequisites"></a>
+ 에이전트 스페이스에서 액세스 토큰 기능을 활성화해야 합니다.
+ 액세스 토큰(`aidevops:CreateAccessToken`, `aidevops:RevokeAccessToken`, )을 관리하려면 IAM 권한이 있어야 합니다`aidevops:RotateAccessToken`. 전체 목록은 [DevOps 에이전트 IAM 권한](aws-devops-agent-security-devops-agent-iam-permissions.md) 단원을 참조하십시오.

### 액세스 토큰 활성화
<a name="enable-access-tokens"></a>

1.  AWS Management Console에 로그인하고 AWS DevOps 에이전트 콘솔을 엽니다.

1. 에이전트 스페이스를 선택합니다.

1. **구성** 탭을 선택합니다.

1. **액세스 토큰** 섹션에서 **활성화**를 선택합니다.

1. 작업을 확인합니다.

### 토큰 생성
<a name="create-a-token"></a>

1. 에이전트 스페이스의 DevOps 에이전트 웹 앱을 열고 탐색 메뉴에서 **설정을** 선택한 다음 **토큰 액세스를** 선택합니다.

1. **토큰 생성**을 선택합니다.

1. 토큰 이름을 입력하세요.

1. 범위를 선택합니다.
   + `read` - 조사, 추천, 채팅 및 에이전트 스페이스 리소스를 봅니다.
   + `operate` - 전체 액세스. 의 모든 항목과 메시지 전송`read`, 채팅 생성, 백로그 작업 및 권장 사항 관리가 포함됩니다.

1. 클라이언트 유형을 선택합니다.
   + `human` - IDE 및 CLI 사용(Kiro, Claude Code, Cursor 및 기타 대화형 도구).
   + `agent` - 자율 A2A 통합 및 프로그래밍 에이전트용.

1. 만료(1\~60일)를 설정합니다.

1. 토큰 값을 복사하여 [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)와 같은 안전하고 안전한 위치에 저장합니다. 다시 검색할 수 없습니다.

토큰을 생성한 후 웹 앱에는 클라이언트에 직접 복사할 수 있는 구성 예제가 표시됩니다.

## Kiro와 연결
<a name="connect-with-kiro"></a>

[Kiro](https://kiro.dev/) 사용자의 경우 IDE 또는 [Kiro Powers 마켓플레이](https://kiro.dev/powers/#aws-devops-agent)스에서 전용 **AWS DevOps 에이전트** 전원을 사용할 수 있습니다.

**1단계: 전원 설치**

Powers Marketplace에서 **aws-devops-agent** 전원을 설치합니다.

**2단계: 환경 변수 설정**

다음 환경 변수를 설정하여 연결을 구성합니다.

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

**3단계: Kiro에서 변수 승인**

**설정** > **MCP 승인 Env Vars**로 이동하여 `DEVOPS_AGENT_TOKEN` 및를 승인합니다`DEVOPS_AGENT_REGION`. Kiro는 환경 변수가 승인될 때까지 MCP 서버에 환경 변수를 전달하지 않습니다.

**4단계: Kiro 다시 시작**

Kiro를 다시 시작하여 변경 사항을 적용합니다.

Kiro 전원은 원격 서버 엔드포인트를 사용할 수 없을 때 직접 AWS API 액세스를 제공하는 폴백`aws-mcp`으로를 포함합니다.

## Claude Code로 연결
<a name="connect-with-claude-code"></a>

[Claude 코드](https://code.claude.com/docs/en/overview) 사용자의 경우 AWS DevOps 에이전트는 **aws-agents-for-devsecops** Claude 플러그인에서 사용할 수 있으며,이 플러그인은 AWS DevOps 에이전트 및 AWS 보안 에이전트 기능을 모두 Claude로 가져옵니다. [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-devsecops** 플러그인을 설치합니다.

1. `/aws-agents-for-devsecops:setup-devops-agent` 명령을 실행하여 연결을 구성합니다.

## 다른 MCP 클라이언트와 연결
<a name="connect-with-other-mcp-clients"></a>

MCP 호환 클라이언트의 경우 다음을 사용하여 서버를 구성합니다.
+ **URL** - `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}`를 에이전트 스페이스의 리전(예: `us-east-1`)`<your-access-token>`으로 바꾸고를 토큰 값으로 바꿉니다.

## SigV4 인증 사용
<a name="use-sigv4-authentication"></a>

SigV4 인증은 액세스 토큰 대신 자격 AWS 증명을 사용합니다. Kiro power 및 Claude Code 플러그인에는 로컬 AWS 자격 증명을 사용하여 요청에 서명`mcp-proxy-for-aws`하는를 통한 기본 제공 SigV4 지원이 포함되어 있습니다.

### SigV4를 사용하는 경우
<a name="when-sigv4-is-used"></a>
+ 액세스 토큰이 구성되지 않았거나 실패(만료됨, 유효하지 않음)할 때 **폴백**으로 사용됩니다.
+ 여러 에이전트 스페이스가 있고 도구 호출`agent_space_id`당 로 라우팅해야 하는 경우의 **기본** 인증입니다.
+ **사용자 선택** - Claude Code에서 설정 스킬을 실행하여 베어러 토큰에서 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>

액세스 토큰 대신 SigV4를 사용하도록 MCP 클라이언트를 구성하려면를 통해 서버를 실행합니다`mcp-proxy-for-aws`. 를 에이전트 스페이스의 리전(예: `us-east-1`)`{region}`으로 바꿉니다.

```
{
  "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` - 서버 전송 이벤트를 통해 작업 업데이트를 구독합니다.

### Skills
<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 범위에서만 사용할 수 있습니다. 다른 IPs의 요청은 액세스 거부 오류와 함께 거부됩니다.

### 토큰 교체 및 취소
<a name="token-rotation-and-revocation"></a>
+ **교체** - 토큰의 이름, 범위 및 IP 허용 목록을 유지하면서 토큰을 교체하여 새 토큰 값을 생성합니다. 이전 토큰은 즉시 무효화됩니다. 새 토큰 값으로 클라이언트 구성을 업데이트합니다.
+ **취소** - 토큰이 손상된 경우 즉시 취소합니다. 취소된 토큰은 사용할 수 없으며 복원할 수 없습니다.

#### 손상된 토큰에 대한 대응
<a name="responding-to-a-compromised-token"></a>

토큰이 손상되었다고 의심되는 경우 다음 단계를 따르세요.

1. **모든 토큰 액세스 차단** - AWS DevOps 에이전트 콘솔에서 에이전트 스페이스를 열고 **구성** 탭을 선택한 다음 액세스 토큰 섹션에서 **비활성화**를 선택합니다. 이렇게 하면 에이전트 스페이스에 대한 모든 토큰 기반 액세스가 즉시 차단됩니다.

1. **손상된 토큰 취소** - 웹 앱에서 **설정** > **액세스 토큰**으로 이동하여 손상된 토큰을 선택하고 **취소**를 선택합니다. 액세스 토큰이 비활성화된 상태에서도 토큰을 취소할 수 있습니다.

1. **액세스 토큰 다시 활성화 **- 손상된 토큰을 취소한 후 토큰 기반 액세스가 필요한 경우 **구성** 탭에서 액세스 토큰을 다시 활성화합니다.

#### 프로그래밍 방식으로 토큰 취소
<a name="revoking-tokens-programmatically"></a>

를 사용하여 프로그래밍 방식으로 토큰을 취소할 수도 있습니다`awscurl`. 다음 명령은 SigV4 인증을 사용합니다. 리전(`us-east-1`)을 에이전트 스페이스가 생성된 리전으로 바꿉니다.

**참고:** 1단계에서는 AWS CLI를 사용합니다. 액세스 토큰 작업에는 전용 AWS CLI 명령이 아직 없기 때문에 2단계와 3단계에서는 SigV4로 HTTP 요청에 서명하는 명령줄 도구인 [awscurl](https://github.com/okigan/awscurl)을 사용합니다.

**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"
```

`{agentSpaceId}` 및를 이전 응답의 값으로 `{accessTokenId}` 바꿉니다.

### 추적성
<a name="traceability"></a>

액세스 토큰이 사용되는 경우 AWS DevOps Agent는 사용자를 대신하여 작업을 수행하는 역할을 수임합니다. 이 `AssumeRole` 호출은 토큰과 호출자를 식별하는 세션 태그와 함께 AWS CloudTrail에 로깅됩니다.
+ `AgentSpaceId` - 에이전트 공간의 식별자입니다.
+ `UserId` - 토큰 생성자의 자격 증명입니다.
+ `AccessTokenId` - 토큰의 고유 식별자입니다.
+ `TokenName` - 사용된 액세스 토큰의 이름입니다.
+ `ClientType` - 사용된 프로토콜(MCP, A2A).
+ `SourceIp` - 클라이언트의 IP 주소입니다.
+ `UserAgent` - 클라이언트 사용자-에이전트 문자열(사용 가능한 경우).

직접 MCP 및 A2A 엔드포인트 호출은 두 인증 방법에 대해 CloudTrail에 로깅되지 않습니다. 각 호출에는 CloudTrail에 로깅된 해당 다운스트림 AWS API 호출이 있으며 식별 가능한 역할 세션 이름은 형식입니다`token_{spaceId}_{timestamp}_{tokenName}`.

### VPC 엔드포인트 정책 제한
<a name="vpc-endpoint-policy-limitation"></a>

원격 서버 엔드포인트는 VPC 엔드포인트 정책을 지원하지 않습니다. 액세스 토큰 또는 SigV4 인증을 사용하는 호출은 VPC 엔드포인트 정책에 의해 제한될 수 없습니다.

### 액세스 토큰 비활성화
<a name="disabling-access-tokens"></a>

액세스 토큰 기능은 기본적으로 꺼져 있습니다. 활성화 후 비활성화하려면:

1. 에이전트 스페이스의 **구성** 탭을 엽니다.

1. **액세스 토큰** 섹션에서 **비활성화**를 선택합니다.

를 즉시 비활성화하면 모든 토큰 기반 액세스가 차단됩니다. 기존 토큰은 삭제되지 않지만 기능이 다시 활성화될 때까지 사용할 수 없습니다.

조직의 사용자가 액세스 토큰을 활성화하지 못하도록 하려면 액세스 토큰 API 작업 및 `UpdateAgentSpace` 작업(액세스 토큰 토글을 제어하는)을 거부하는 서비스 제어 정책(SCP)을 생성합니다.

**참고:** 거부는 다른 에이전트 스페이스 업데이트(이름, 설명, 로캘)`aidevops:UpdateAgentSpace`도 방지합니다. 너무 광범위한 경우 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 무단 | 토큰이 유효하지 않거나 만료되었습니다. | 웹 앱에서 새 토큰을 생성하거나 기존 토큰을 교체합니다. | 
| HTTP 400 "A2A 버전 헤더 필요" | 프로토콜 버전 헤더가 누락되었습니다. A2A v1.0만 지원됩니다. | A2A 요청에 A2A-Version: 1.0 헤더를 추가합니다. | 
| 요청 제한 시간 | 초기 응답에는 5\~30초가 걸립니다. 조사에는 5\~8분이 소요됩니다. | 클라이언트 제한 시간을 최소 120초로 설정합니다. | 
| 연결이 거부됨 | 엔드포인트 URL 또는 리전이 잘못되었습니다. | URL 형식을 확인합니다. https://connect.aidevops.{region}.api.aws  |