기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 에이전트에게 WorkSpaces 애플리케이션에 대한 액세스 권한 제공 시작하기
AI 에이전트가 Amazon WorkSpaces 애플리케이션을 통해 데스크톱 애플리케이션을 운영할 수 있도록 하려면 에이전트에 대한 액세스가 활성화된 스택을 생성하고, 스트리밍 URL을 생성하고, 에이전트를 관리형 MCP 서비스에 연결합니다.
에이전트 액세스를 처음 설정하는 경우 첫 번째 에이전트 구축 빠른 시작 환경을 사용할 수 있습니다. 이 주제의 단계에 따라 에이전트 액세스를 수동으로 구성할 수도 있습니다. 빠른 시작 환경은 GitHub 리포지토리인 [sample-code-for-workspaces-agent-access](https://github.com/aws-samples/sample-code-for-workspaces-agent-access)에서 사용할 수 있습니다.
이 자습서를 완료하는 데 약 15분이 걸립니다.
**중요**
이 자습서에서 생성한 리소스로 인해 계정에 요금이 부과될 수 있습니다 AWS . 지속적인 요금이 부과되지 않도록 스택을 삭제하고 완료되면 플릿을 중지합니다.
이 자습서에서는 다음 작업을 완료합니다.
+ 1단계: 에이전트 액세스가 활성화된 스택 생성
+ 2단계: 스트리밍 URL 생성
+ 3단계: 에이전트를 MCP 서비스에 연결
+ 4단계: 에이전트 활동 확인
+ 5단계: 리소스 정리
## 사전 조건
시작하기 전에 다음 항목이 준비되었는지 확인합니다.
+ 활성 Amazon WorkSpaces 애플리케이션 플릿입니다. 아직 설정하지 않은 경우 섹션을 참조하세요[Amazon WorkSpaces 애플리케이션 시작하기: 샘플 애플리케이션으로 설정](getting-started.md).
+ AWS 다음 IAM 권한이 있는 자격 증명(환경 변수, AWS 프로파일, EC2 인스턴스 역할 또는 Lambda 실행 역할). 에이전트는 이러한 자격 증명을 직접 사용하여 MCP 서비스에 대한 요청에 서명합니다.
```
{
"Sid": "MCP",
"Effect": "Allow",
"Action": ["agentaccess-mcp:*"],
"Resource": "*"
},
{
"Sid": "AppStream",
"Effect": "Allow",
"Action": ["appstream:CreateStreamingURL", "appstream:DescribeFleets"],
"Resource": "*"
}
```
`agentaccess-mcp:*` 와일드카드에는 다음 작업이 포함됩니다.
+ `agentaccess-mcp:InvokeMcp` - 세션 초기화 및 도구 검색
+ `agentaccess-mcp:GetScreenshot` - 화면 상태 캡처
+ `agentaccess-mcp:LeftClick` - 왼쪽 마우스 클릭 수행
+ `agentaccess-mcp:DoubleClick` - 두 번 클릭 수행
+ `agentaccess-mcp:TripleClick` - 트리플 클릭 수행
+ `agentaccess-mcp:RightClick` - 마우스 오른쪽 버튼 클릭 수행
+ `agentaccess-mcp:MiddleClick` - 마우스 중간 클릭 수행
+ `agentaccess-mcp:TypeText` - 텍스트 문자열을 입력합니다.
+ `agentaccess-mcp:KeyPress` - 키 또는 키 조합을 누릅니다.
+ `agentaccess-mcp:HoldKey` - 지속 시간 동안 키 유지
+ `agentaccess-mcp:Scroll` - 좌표로 스크롤
+ `agentaccess-mcp:MovePointer` - 포인터를 좌표로 이동
+ `agentaccess-mcp:LeftClickDrag` - 왼쪽 클릭 드래그 수행
+ `agentaccess-mcp:LeftMouseDown` - 마우스 왼쪽 버튼을 길게 누릅니다.
+ `agentaccess-mcp:LeftMouseUp` - 마우스 왼쪽 버튼 해제
+ `agentaccess-mcp:CheckConnectionStatus` - 스트리밍 세션의 연결 상태 확인
+ `agentaccess-mcp:CallForwardedTool` - 원격 인스턴스에서 전달된 도구 호출
+ MCP 호환 에이전트 프레임워크입니다. 에이전트는 SigV4-signed 스트리밍 가능한 HTTP 요청을 MCP 엔드포인트에 수행할 수 있어야 합니다. [Strands Agents SDK](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/)는 기본 MCP 클라이언트 지원을 제공하거나 mcp-proxy-for-aws 전송과 함께 모든 프레임워크를 사용할 수 있습니다.
+ Python 3.10 이상. 특정 운영 체제는 필요하지 않습니다.
## 1단계: 에이전트 액세스가 활성화된 스택 생성
AI 에이전트가 데스크톱 애플리케이션과 상호 작용할 수 있도록 에이전트 액세스가 활성화된 WorkSpaces 애플리케이션 스택을 생성합니다.
### AWS 관리 콘솔 사용
**에이전트 액세스 권한이 있는 스택을 생성하려면**
1. [WorkSpaces 애플리케이션 콘솔](https://console.aws.amazon.com/appstream2/home)을 엽니다.
1. 왼쪽 탐색 창에서 **스택을** 선택한 다음 **스택 생성을** 선택합니다.
1. **스택 세부 정보** 페이지(4단계 중 1단계)의 **AI 에이전트 액세스**에서 **AI 에이전트 액세스 활성화**를 선택합니다. **다음**을 선택합니다.
1. **스토리지 활성화** 페이지(4단계 중 2단계)에서 선택적으로 **홈 폴더를** 활성화하여 에이전트가 AWS 계정의 Amazon S3 버킷에 파일을 저장할 수 있도록 합니다. 이 스택과 연결된 플릿은 인터넷 또는 Amazon S3용 Amazon VPC 엔드포인트를 통해 Amazon S3에 대한 액세스를 허용해야 합니다. **다음**을 선택합니다.
1. **에이전트 설정 편집** 페이지(4단계 중 3단계)에서 다음을 구성합니다.
+ **컴퓨터 입력 활성화** - 에이전트가 버튼을 선택하고 텍스트를 입력한 다음 데스크톱에서 스크롤할 수 있도록 허용합니다. 컴퓨터 입력을 활성화하는 경우 컴퓨터 비전도 활성화해야 합니다.
+ **컴퓨터 비전 활성화** - 에이전트가 데스크톱을 볼 수 있도록 허용합니다.
+ **스크린샷 스토리지** - 스트리밍 세션 중에 에이전트 스크린샷이 저장되는 위치를 구성합니다. 활성화된 경우 쓸 권한이 있는 Amazon S3 버킷을 제공합니다.
+ **화면 해상도** - 에이전트 스트리밍 환경(1280x720)의 디스플레이 해상도를 선택합니다.
+ **화면 이미지 유형** - 에이전트 화면 캡처(PNG 또는 JPEG)의 이미지 형식을 선택합니다.
+ **애플리케이션 설정 지속성** - 선택적으로 이를 활성화하여 세션 간에 에이전트의 애플리케이션 사용자 지정 및 Windows 설정을 저장합니다. 설정은 AWS 계정의 Amazon S3 버킷에 저장됩니다.
+ **MCP 도구 전달 활성화** - 에이전트가 컴퓨터 사용 도구를 사용하는 대신 직접 MCP 호출을 통해 애플리케이션 및 데스크톱 운영 체제와 상호 작용할 수 있습니다. 활성화하면 WorkSpaces 애플리케이션 세션에 구성된 MCP 도구가 에이전트에게 전달됩니다.
+ **사용자 제어 모드 활성화** - 사용자가 브라우저를 통해 실시간으로 에이전트 세션을 관찰할 수 있습니다. 관찰자는 에이전트가 작동하면서 데스크톱의 라이브 뷰를 볼 수 있습니다. VIEW\_STOP 모드에서 관찰자는 화면 상단의 버튼을 사용하여 에이전트를 중지할 수 있습니다. 중지되면 에이전트는 다시 시작하려면 새 세션을 시작해야 합니다.
**참고**
컴퓨터 입력 또는 컴퓨터 비전 중 하나 이상을 활성화해야 합니다.
**다음**을 선택합니다.
1. **검토 및 생성** 페이지(4/4단계)에서 설정을 검토하고 **스택 생성을** 선택합니다.
### 사용 AWS CLI
다음 명령을 실행하여 에이전트 액세스가 활성화된 스택을 생성합니다.
```
aws appstream create-stack \
--name {{your-stack-name}} \
--agent-access-config '{
"Settings": [
{"AgentAction": "COMPUTER_VISION", "Permission": "ENABLED"},
{"AgentAction": "COMPUTER_INPUT", "Permission": "ENABLED"},
{"AgentAction": "FORWARD_MCP_TOOLS", "Permission": "ENABLED"}
],
"ScreenResolution": "W_1280xH_720",
"ScreenImageFormat": "PNG"
}'
```
스크린샷 스토리지도 활성화하려면 `S3BucketArn` 및 `ScreenshotsUploadEnabled` 파라미터를 추가합니다.
```
aws appstream create-stack \
--name {{your-stack-name}} \
--agent-access-config '{
"Settings": [
{"AgentAction": "COMPUTER_VISION", "Permission": "ENABLED"},
{"AgentAction": "COMPUTER_INPUT", "Permission": "ENABLED"},
{"AgentAction": "FORWARD_MCP_TOOLS", "Permission": "ENABLED"}
],
"ScreenResolution": "W_1280xH_720",
"ScreenImageFormat": "PNG",
"S3BucketArn": "{{arn:aws:s3:::your-bucket-name}}",
"ScreenshotsUploadEnabled": true
}'
```
스택을 생성한 후 플릿과 연결합니다. 에이전트는 연결된 플릿이 없는 스택에 연결할 수 없습니다.
```
aws appstream associate-fleet \
--stack-name {{your-stack-name}} \
--fleet-name {{your-fleet-name}}
```
## 2단계: 스트리밍 URL 생성
표준 WorkSpaces 애플리케이션 `CreateStreamingURL` API를 사용하여 스트리밍 URL을 생성합니다. 에이전트별 파라미터는 필요하지 않습니다. 스택의 에이전트 액세스 구성에 따라 에이전트별 동작이 결정됩니다.
### AWS 관리 콘솔 사용
**콘솔을 사용하여 스트리밍 URL을 생성하려면**
1. [WorkSpaces 애플리케이션 콘솔](https://console.aws.amazon.com/appstream2/home)을 엽니다.
1. 왼쪽 탐색 창에서 **스택을** 선택한 다음 에이전트 액세스가 활성화된 상태에서 생성한 스택을 선택합니다.
1. **작업** 버튼을 선택하고 드롭다운에서 **스트리밍 URL 생성을** 선택합니다. 이 옵션을 사용하려면 스택을 선택해야 합니다.
1. **UserID** 섹션에서 사용자를 입력합니다. 테스트 중인 `TestUser` 경우를 입력할 수 있습니다.
1. **URL 만료** 섹션에서 URL이 유효할 시간을 선택합니다. 더 짧은 시간이 권장됩니다. 30분이 기본값이며 테스트에 권장됩니다.
1. **GetURL**을 선택하고 생성된 URL을 복사합니다.
### 사용 AWS CLI
다음 명령을 실행하여 스트리밍 URL을 생성합니다.
```
aws appstream create-streaming-url \
--stack-name {{your-stack-name}} \
--fleet-name {{your-fleet-name}} \
--user-id {{your-agent-id}} \
--validity 3600
```
응답에는 다음 단계에서 에이전트에 전달하는 `StreamingURL`이 포함됩니다. URL은 `--validity` 파라미터에 지정된 기간 동안 유효합니다.
## 3단계: 에이전트를 MCP 서비스에 연결
에이전트는 다음 고정 엔드포인트에서 관리형 MCP 서비스에 연결합니다.
`https://agentaccess-mcp.{{region}}.api.aws/mcp`
연결은 서비스 이름 로 SigV4 서명을 사용합니다`agentaccess-mcp`. 에이전트는 `agentaccess-mcp:*` 권한이 있는 사전 조건에 구성된 자격 증명을 사용하여 AWS 각 요청에 서명합니다. 2단계의 스트리밍 URL을 모든 MCP 요청의 헤더로 전달합니다.
다음 예제에서는 mcp-proxy-for-aws를 사용하여 연결을 설정하는 방법을 보여줍니다.
```
aws_iam_streamablehttp_client(
endpoint="https://agentaccess-mcp.{{region}}.api.aws/mcp",
aws_service="agentaccess-mcp",
aws_region="{{region}}",
headers={
"X-Amzn-AgentAccess-Streaming-Session-Url": streaming_url,
},
)
```
에이전트가 연결되면 MCP 도구를 사용하여 텍스트를 입력하고, 버튼을 선택하고, 데스크톱의 스크린샷을 캡처할 수 있습니다.
## 4단계: 에이전트 활동 확인
다음 AWS 서비스를 사용하여 에이전트 활동을 확인할 수 있습니다.
+ **AWS CloudTrail** - 에이전트 세션 이벤트를 AWS CloudTrail 로깅합니다. AWS CloudTrail 콘솔을 열어 에이전트 활동을 봅니다.
+ **CloudWatch** - CloudWatch는 에이전트 세션에 대한 운영 지표를 제공합니다. CloudWatch 콘솔을 열어 지표를 봅니다.
+ **Amazon S3** - 스크린샷 스토리지를 활성화한 경우 Amazon S3는 스택 구성 중에 지정한 버킷에 스크린샷을 저장합니다.
## 5단계: 리소스 정리
지속적인 요금을 방지하려면이 자습서에서 생성한 스택을 삭제합니다. 스택을 삭제하려면 먼저 플릿을 중지하고 스택에서 연결을 해제해야 합니다. 선택적으로 플릿을 삭제할 수도 있습니다.
### AWS 관리 콘솔 사용
**리소스를 정리하려면**
1. [WorkSpaces 애플리케이션 콘솔](https://console.aws.amazon.com/appstream2/home)을 엽니다.
1. 왼쪽 탐색 창에서 **플릿**을 선택합니다.
1. 스택과 연결된 플릿을 선택합니다. [**Actions**], [**Stop**]을 선택합니다. 플릿이 멈출 때까지 기다리세요.
1. 왼쪽 탐색 창에서 **스택**을 선택합니다.
1. 생성한 스택을 선택하고 **작업**, **플릿 연결 해제를** 선택합니다.
1. 스택을 선택한 상태에서 **작업**, **삭제**를 선택합니다.
1. (선택 사항) 플릿을 삭제하려면 왼쪽 탐색 창에서 **플릿**을 선택합니다. 플릿을 선택하고 **작업**, **삭제**를 선택합니다.
### 사용 AWS CLI
다음 명령을 실행하여 리소스를 정리합니다.
```
aws appstream stop-fleet \
--name {{your-fleet-name}}
aws appstream disassociate-fleet \
--stack-name {{your-stack-name}} \
--fleet-name {{your-fleet-name}}
aws appstream delete-stack \
--name {{your-stack-name}}
```
(선택 사항) 플릿이 중지된 후에도 플릿을 삭제하려면:
```
aws appstream delete-fleet \
--name {{your-fleet-name}}
```