09 · 에이전트 테스트·문제 해결 — DRAFT·준비·추적·격리
한 문장 요약: 에이전트 테스트의 감각은 "규격 초안(DRAFT)을 고치면 반드시 준비(Prepare)부터 다시 하고, 추적으로 단계를 읽고, 작업 그룹·지식 기반을 하나씩 꺼며 원인을 격리하는 것"이며, 문서 첫머리는 Agents Classic이 신규 가입 불가(유지 관리 모드)이고 신규 구축은 AgentCore라는 중대 공지로 시작한다.
- 태스크: T-DOC-09 · 연계 주차: 3주차(에이전트)
- 원본: docs.aws.amazon.com/ko_kr/bedrock/latest/userguide/agents-test.html (2026-11-18 수집·본문 7,447자)
- 원문 사본:
downloads/07-에이전트테스트/agents-test.html
개요
에이전트를 만들면 규격 초안(DRAFT)이 생기고 변경할 때마다 갱신된다. 구성을 마치면 스냅샷인 버전과 이를 가리키는 별칭을 만들어 배포한다. 테스트는 콘솔의 테스트 창 또는 API(InvokeAgent)로 하며, 문제 해결은 추적(trace)과 구성 요소 격리로 진행한다.
핵심 메시지 3
1. Agents Classic은 더 이상 신규 가입 불가 — "Amazon Bedrock Agents(현재 Amazon Bedrock Agents Classic)에 더 이상 가입할 수 없습니다… Strands Agents SDK를 사용하여 코드 정의 에이전트를 빌드하는 방법은 Amazon Bedrock AgentCore 시작하기를 참조하세요." (원문) — 신규 에이전트 구축의 정답 방향은 AgentCore다.
2. 준비(Prepare) 없이는 테스트가 낡은 구성을 돌려준다 — 규격 초안을 업데이트할 때마다 PrepareAgent로 패키징해야 하며, "가장 좋은 방법은 마지막 준비 시간(preparedAt)을 확인"해 최신 구성으로 테스트하고 있는지 검증하는 것이다 (원문).
3. 격리가 문제 해결의 방법론이다 — 테스트 창에서 작업 그룹·지식 기반을 개별적으로 비활성화하면서 "어느 구성 요소가 문제를 일으키는지" 분리할 수 있다 (원문) — 3주차 "도구 오류 시 어느 단계 로그를 볼지" 훈련의 공식 버전.
주제별 심화
테스트 경로
| 경로 | 절차 |
|---|---|
| 콘솔 | 에이전트 선택 → 테스트 창 → 준비 → 별칭/버전 선택(기본 TestAlias: 규격 초안) → 메시지 실행 → 추적 표시 |
| API | PrepareAgent(빌드 타임 엔드포인트, agentId) → InvokeAgent(TSTALIASID로 DRAFT 호출). AWS CLI는 InvokeAgent 미지원 |
InvokeAgent 필수 필드: agentId·agentAliasId·sessionId(영숫자 2~100자)·inputText. 선택: enableTrace·endSession·sessionState·streamingConfigurations(streamFinalResponse=TRUE).
추적·응답 해석
- 추적은 오케스트레이션 각 단계의 프롬프트·추론 구성·작업 그룹·지식 기반 사용법을 실시간으로 보여준다(응답 반환 전에도 표시)
- KB를 간접 호출하면 응답에 각주(citations) — S3 객체 링크로 인용 확인
- 스트리밍 활성화 + 가드레일 구성 시 응답은 기본 50자 간격으로 생성됨 (원문)
- Lambda 없이 제어를 반환한 작업 그룹 →
returnControl필드로ReturnControlPayload반환:
```
{ "invocationId": "...",
"invocationInputs": [ ApiInvocationInput | FunctionInvocationInput ] }
```
ApiInvocationInput: actionGroup·apiPath·httpMethod·parameters·requestBody /FunctionInvocationInput: actionGroup·function·parameters — 사용자가 예제 출력값을 제공하고 제출하면 에이전트가 응답을 마저 생성
2025-03-31 이후 생성 에이전트 (원문 참고)
콘솔 생성 시 스트리밍 기본 활성화 · 실행 역할에 bedrock:InvokeModelWithResponseStream 권한 필요.
적용 체크리스트 (시험·실습 관점)
- ☐ DRAFT→버전→별칭 배포 모델과 "준비 재실행" 규칙을 가드레일(요약본 04)과 묶어 설명할 수 있는가
- ☐ "에이전트가 이상 동작 → 어디부터 보나"에 추적→작업 그룹/KB 격리 순서로 답할 수 있는가 (도메인 5)
- ☐ returnControl의 용도(클라이언트가 도구를 직접 수행)를 아는가 (도메인 2)
- ☐ "신규 에이전트는 AgentCore(Strands)" 방향 전환을 시험 답안에 반영할 수 있는가
최종 정리
이 문서의 3단 키워드 — 준비(Prepare)·추적(trace)·격리(disable) — 이 에이전트 문제 해결 문제의 뼈대다. Classic/AgentCore 전환 공지는 시험 출제 기준(가이드 범위)과 실무 방향 모두에 영향을 주는 시점 정보로, 덱 3주차 학습과 워크숍(요약본 10)의 AgentCore 경로와 일치한다.
Provenance: 원문 인용·구조는 2026-11-18 수집 본문 기준(Classic 유지관리 공지 포함). 기계 번역 한국어 문서로 원문 영어 우선 고지. 해석·체크리스트는 학습용 편집임.