AWS Agent Toolkit: AI 에이전트의 API 환각 현상 방지

당신의 AI 프로그래밍 에이전트는 과거에 고정된 학습 데이터로 추측하기 때문에 AWS API를 환각(Hallucination)합니다.

Agent Toolkit for AWS는 진실의 원천(Source of Truth)을 바로잡습니다. MCP(Model Context Protocol)와 호환되는 모든 에이전트에 실시간 AWS 문서, 검증된 기술(Skills), 그리고 가드레일(Guardrails)을 제공합니다. 여기 전후 비교와 한 줄의 명령어로 설치하는 방법이 있습니다.

프로그래밍 에이전트에게 "합리적인 보안 설정을 갖춘 S3 버킷을 구성해줘"라고 요청했을 때 어떤 일이 발생하는지 살펴보세요.

에이전트는 기억에 의존하여 정책을 작성합니다. 이 정책은 두 번의 릴리스(Release) 전 이름이 변경된 API 파라미터를 사용합니다. 배포는 실패합니다. 에이전트는 변형된 방식으로 재시도합니다. 이 또한 실패합니다. 세 번의 반복 끝에 당신은 기술적으로는 존재하지만, 퍼블릭 액세스 차단은 불완전하며, 그 과정에서 수천 개의 토큰을 낭비한 트랜스크립트를 얻게 됩니다.

AI 프로그래밍 에이전트는 AWS를 다룰 때 요란하게 실패하지 않습니다. 그럴듯하게 실패합니다. 코드는 멀쩡해 보이고, 서비스 이름도 실제 존재하며, 오류는 배포 시점이나 더 최악의 경우 보안 검토 단계에서야 나타납니다.

왜 AI 프로그래밍 어시스턴트는 AWS 코드를 작성할 때 환각을 일으키나요?

모델이 과거에 고정된 학습 데이터로 추측하기 때문입니다. AWS는 해당 데이터 컷오프(Cutoff) 이후에 새로운 서비스를 출시하고 API 인터페이스를 변경했습니다. 따라서 에이전트는 오늘날의 사실이 아니라 기억하는 것에 의존합니다. 에이전트는 자신이 무엇을 모르는지 모르며, 작성하기 전에 이를 확인할 방법이 없습니다.

Agent Toolkit for AWS란 무엇인가요?

El Agent Toolkit for AWS는 AWS가 지원하는 공식 툴킷으로, AI 프로그래밍 에이전트에게 AWS에서 애플리케이션을 구축, 배포 및 운영하는 데 필요한 도구, 지식, 가드레일(guardrails)을 제공합니다. 하위의 AWS MCP Server는 2026년 5월 6일에 일반 사용 가능(general availability)해졌습니다. 이는 오픈 소스(Apache-2.0)입니다.

이 툴킷은 네 가지 구성 요소로 이루어져 있습니다:

AWS MCP Server: Model Context Protocol의 관리형 서버입니다. 하나의 엔드포인트에서 AWS의 15,000개 이상의 API 작업에 접근할 수 있으며(사용자의 IAM 자격 증명을 통해 call_aws 도구 사용), 샌드박스 내 Python 스크립트 실행 및 인증이 필요 없는 문서 검색 기능을 제공합니다.
Agent skills: 에이전트가 필요에 따라 로드하는, 선별된 지침(instructions), 스크립트 및 참고 자료 패키지입니다. 에이전트는 현재 작업과 관련된 내용만 검색하므로 컨텍스트를 낭비하지 않습니다. 이는 일반적인 추측이 아니라 'X 설정에 대한 검증된 절차'와 같습니다.
Plugins: Claude Code 및 Codex용 단일 설치 패키지로, MCP Server의 구성과 선별된 skills 세트를 그룹화합니다. 시작하는 데 사용되는 것은 aws-core입니다.
Rules files: 프로젝트 수준의 설정 파일로, 에이전트에게 프로젝트에서 어떻게 작업해야 하는지 알려줍니다. 행동하기 전에 MCP Server를 사용하고, skills를 검색하며, 문서에서 찾아보도록 지시합니다.

에이전트가 AWS에 직접 호출하도록 두면 안 되는 이유?

'직접'이라는 것은 '메모리로부터'라는 의미입니다. MCP Server는 진실의 출처(source of truth)를 변경합니다: 모델의 훈련 데이터에서 실시간 AWS 문서 및 API로 바꿉니다.

여기서 중요한 두 가지가 있습니다:

문서 검색에는 자격 증명(Credentials)이 필요하지 않습니다. 에이전트는 코드 한 줄을 작성하기 전에 무언가를 수행하는 최신 방법을 조회할 수 있습니다. 이 부분에는 AWS 계정이 필요하지 않습니다.
스크립트 실행은 샌드박스(Sandbox) 내에서 이루어집니다. 에이전트가 AWS를 대상으로 Python을 실행할 때, 사용자의 파일 시스템 및 로컬 네트워크와 격리된 상태에서 실행되며, 모든 호출은 CloudWatch 메트릭과 함께 CloudTrail에 기록됩니다.

두 번째 포인트는 팀들이 흔히 간과하는 부분입니다. MCP Server는 각 요청에 aws:ViaAWSMCPService 및 aws:CalledViaAWSMCP라는 두 가지 조건 키(Condition keys)를 추가하여, 사용자의 IAM 정책이 에이전트의 작업과 인간의 작업을 구분할 수 있게 합니다. 기본 역할(Role)이 쓰기 권한을 허용하더라도 에이전트를 읽기 전용으로 유지할 수 있습니다. 에이전트는 능력을 얻고, 사용자는 통제권을 유지합니다.

전과 후

동일한 프롬프트, 동일한 모델. 유일한 변수는 Toolkit입니다.

	에이전트 단독	에이전트 + Toolkit
진실의 원천 (Source of truth)	훈련 데이터 (고정됨)	실시간 AWS 문서 및 API
...

AWS는 그 이점을 "더 적은 오류, 더 낮은 토큰 비용, 그리고 엔터프라이즈급 보안 제어 기능을 갖춘 에이전트"로 설명합니다. 그 이면의 메커니즘은 위의 표와 같습니다. 에이전트는 구식 메모리에 의존해 즉흥적으로 행동하는 것을 멈추고, 최신 문서와 검증된 절차를 바탕으로 행동하기 시작합니다.

에이전트에 적용하기

uv가 설치되어 있어야 하며(아래의 uvx 명령어를 사용하기 위함), 실제로 AWS를 호출하는 모든 작업에 대해서는 로컬 AWS 자격 증명이 필요합니다. 문서 검색 및 스킬 탐색(Skill discovery)은 자격 증명 없이 작동합니다.

Claude Code. claude-plugins-official 마켓플레이스가 기본적으로 제공되므로, 단 하나의 명령어로 설치할 수 있습니다:

plugin install aws-core

만약 "Plugin not found"라는 메시지가 뜨면, 먼저 /plugin marketplace update claude-plugins-official로 마켓플레이스를 업데이트한 다음, aws-core@claude-plugins-official라는 명시적인 이름으로 설치하십시오.

알아둘 만한 가치가 있는 두 가지 플러그인이 더 있습니다: aws-agents (Bedrock 및 AgentCore를 사용하여 에이전트 구축)와 aws-data-analytics (S3 Tables, Glue, Athena)입니다. 우선 aws-core로 시작하십시오.

Codex:

codex plugin marketplace add aws/agent-toolkit-for-aws

그 다음 Codex를 열고 /plugins를 실행하여 aws-core를 설치하십시오.

Kiro (또는 MCP 호환 에이전트). .kiro/settings/mcp.json에 서버를 추가하십시오. 재현성과 공급망 보안을 위해 버전을 고정하십시오:

{
  "mcpServers": {
    "aws": {
...

그리고 스킬 (skills)을 추가합니다:

npx skills add aws/agent-toolkit-for-aws/skills

Cursor: Settings > Plugins > Team Marketplaces > Add Marketplace > Import from Repo를 선택하고 aws/agent-toolkit-for-aws를 지정하십시오.

이 툴킷은 MCP 호환 에이전트라면 무엇이든 작동하며, 만약 Strands, LangChain 또는 Bedrock AgentCore와 같은 프레임워크로 자율 에이전트 (autonomous agents)를 구축하고 있다면, 동일한 MCP 서버가 해당 프레임워크 하단에서 작동하는 AWS 인터페이스가 됩니다.

버킷 프롬프트를 다시 테스트하기

aws-core를 설치하고 정확히 동일한 프롬프트를 다시 실행했습니다. 이번에 에이전트는 최신 문서를 검색하고, 스킬 (skill)에서 검증된 절차를 추출했으며, 퍼블릭 액세스 차단 (public access block)이 첫 번째 시도에서 올바르게 구성되었습니다. 에이전트가 추측하는 것이 아니라 읽고 있었기 때문에, 더 이상 폐기된 (obsolete) 파라미터가 나타나지 않았습니다.

이것이 변화의 핵심입니다: AWS에서 에이전트가 추측하게 두지 말고, 읽게 만드십시오.

추가 비용 없이 사용할 수 있습니다. 실제로 사용하는 AWS 리소스에 대해서만 비용을 지불하면 됩니다.

이 튜토리얼은 Agent Toolkit for AWS를 사용하지만, 근본적인 아이디어(에이전트에게 고정된 학습 데이터 대신 실시간 소스 오브 트루스 (source of truth)와 검증된 절차를 제공하는 것)는 다른 클라우드 및 에이전트 프레임워크에도 적용되는 일반적인 에이전트 패턴입니다.

자주 묻는 질문 (FAQ)

Agent Toolkit for AWS에서 agent skills란 무엇인가요?
skills는 에이전트가 필요할 때 요청하여 가져오는 지침(instructions), 스크립트(scripts) 및 참조 자료(reference material)의 큐레이션된 패키지입니다. 에이전트가 절차를 추측하는 대신, 검증된 절차(예: S3 버킷을 보안하기 위해 검증된 단계)를 필요한 시점에 꺼내어 사용합니다.

사용하려면 AWS 계정이 필요한가요?
모든 경우에 필요한 것은 아닙니다. 문서 검색 및 skills 탐색은 자격 증명(credentials) 없이도 작동합니다. 에이전트가 실제 API 호출을 수행하거나 사용자의 계정을 대상으로 스크립트를 실행할 때만 로컬 AWS 자격 증명이 필요합니다.

어떤 프로그래밍 에이전트를 지원하나요?
Claude Code, Codex, Cursor는 플러그인을 직접 설치합니다. Kiro 및 MCP(Model Context Protocol)와 호환되는 기타 모든 에이전트는 설정을 통해 AWS MCP Server를 추가할 수 있습니다. Strands, LangChain 또는 Bedrock AgentCore와 같은 프레임워크를 사용하여 자율 에이전트를 구축하는 경우, 동일한 MCP Server가 하위의 AWS 인터페이스 역할을 합니다.

에이전트가 AWS CLI를 사용하도록 두는 것과 무엇이 다른가요?
CLI는 에이전트가 추측한 내용을 그대로 실행합니다. Toolkit은 먼저 '신뢰할 수 있는 원천(source of truth)'을 변경합니다. 에이전트는 행동하기 전에 실시간 문서와 검증된 skills를 조회하고, 샌드박스(sandbox)에서 스크립트를 실행하며, CloudWatch 메트릭과 함께 CloudTrail에 모든 호출을 기록합니다.

비용은 얼마인가요?
Toolkit은 추가 비용 없이 사용할 수 있습니다. 에이전트가 실제로 생성하거나 사용하는 AWS 리소스에 대한 비용만 지불하면 됩니다.

여러분의 프로그래밍 에이전트가 가장 자주 실수하는 AWS 워크플로우는 무엇인가요? 댓글로 알려주세요. Toolkit이 이를 해결할 수 있는지 확인해보고 싶습니다.

리소스

감사합니다!

🇻🇪🇨🇱 Dev.to Linkedin GitHub Twitter Instagram Youtube

](/elizabethfuentes12) ## Elizabeth Fuentes L팔로우

저는 실습 튜토리얼과 오픈 소스 프로젝트를 통해 개발자가 프로덕션 준비가 된 AI 애플리케이션을 구축하도록 돕습니다.