Home / Bedrock Agents / Agents
Note

Agents

매니지드 에이전트로 고객센터 봇 빠르게 구축

⏱ 35분 76 / 189

Bedrock Agents

매니지드 에이전트로 고객센터 봇 빠르게 구축

완전관리형 에이전트 오케스트레이션

코드 없이 에이전트를 구축·배포·운영하는 관리형 서비스

개요와 포지셔닝

3요소 구성 · ReAct 오케스트레이션 · AgentCore 비교

PART 1 · 개요와 포지셔닝

Bedrock Agents 3요소

코드 없이 선언만으로 에이전트를 구성하는 관리형 서비스

Action Group

Lambda 또는 Return Control로 외부 시스템 연동. API 스키마 기반 도구 정의

Knowledge Base

RAG 파이프라인 자동 연결. 검색→증강→생성을 선언만으로 구성

프롬프트 4단계

Pre/Orchestration/Knowledge Base/Post — 각 단계를 독립 오버라이드하여 행동 제어

takeaway

행동은 Action Group, 지식은 Knowledge Base, 통제는 프롬프트 4단계가 맡습니다 — 이 3요소 선언이 에이전트의 전부입니다.

PART 1 · 개요와 포지셔닝

ReAct 오케스트레이션 흐름

입력 검증 → ReAct 루프 → 응답 후처리로 이어지는 3단계 파이프라인

  1. 1
    Pre-processing

    사용자 입력 검증 · 카테고리 분류 · 안전성 판단

  2. 2
    Orchestration

    모델이 Action Group 또는 Knowledge Base를 선택하여 실행 (ReAct 루프)

  3. 3
    Post-processing

    최종 응답 포맷팅 · 필터링 · Citation 추가

takeaway

가운데 Orchestration이 ReAct 루프의 본체입니다 — 도구 선택과 반복 판단이 모두 이 단계에서 일어납니다.

PART 1 · 개요와 포지셔닝

Classic vs AgentCore

Bedrock Agents Classic은 유지보수 모드 — 새 프로젝트는 AgentCore

Bedrock Agents Classic

  • 콘솔/API로 선언적 구성
  • Action Group + Knowledge Base 기반
  • 코드 작성 불필요
  • 2026-07-30부터 신규 고객 차단

기존 서비스를 유지보수할 때. 신규 기능 추가 없음.

AgentCore Harness

  • Classic의 1:1 대체 (GA)
  • CreateHarness + InvokeHarness 2 API
  • 모델·도구·메모리·가드레일 선언적
  • agentcore export → Strands 코드 전환

새 프로젝트에 권장. 모든 AgentCore GA 리전에서 사용 가능.

takeaway

2026-07-30부터 Classic은 신규 고객이 차단됩니다 — 새 프로젝트는 AgentCore Harness로 시작합니다.

Action Group

Lambda · Return Control · 스키마 설계 · description 패턴

PART 2 · Action Group

Action Group

에이전트가 외부 시스템과 연결되는 통로

세 가지 선택으로 완성된다

어디서 실행할지, 어떤 스키마로 정의할지, 설명을 어떻게 쓸지 — Action Group 설계의 전부입니다.

  • 실행 유형 — Lambda vs Return Control
  • 스키마 — Function Detail vs OpenAPI
  • description — 언제 · 무엇을 · 무엇이
takeaway

에이전트의 행동 반경은 Action Group이 결정합니다 — 실행 위치와 스키마를 먼저 선택하고, 설명 문장으로 라우팅 품질을 끌어올립니다.

PART 2 · Action Group

실행 유형 2가지

서버에서 실행할지, 클라이언트로 제어를 반환할지 선택

Lambda 실행

  • 에이전트가 Lambda를 직접 호출
  • IAM 역할로 격리
  • 서버사이드 처리 — 백엔드 API/DB에 적합
  • 약간의 콜드스타트 지연

Bedrock이 연결된 Lambda를 자동 호출하고 결과를 컨텍스트에 통합합니다.

Return Control

  • 에이전트는 "결정"만, "실행"은 앱이
  • invocationInputs를 호출 앱에 전달
  • 클라이언트 SDK/UI 액션에 적합
  • 앱이 결과를 returnControlResults로 반환

에이전트의 판단력은 쓰되, 실행 권한은 앱이 유지합니다.

takeaway

기준은 실행 권한의 위치입니다 — 백엔드 API·DB 처리는 Lambda, 앱이 실행을 쥐어야 하면 Return Control을 선택합니다.

PART 2 · Action Group

스키마 2종 선택

Function Detail(단순) vs OpenAPI(대규모) — 규모에 따른 선택 기준

기준Function DetailOpenAPI Schema
형식Bedrock 전용 (name/desc/params)업계 표준 Swagger
편집✓ 콘솔에서 직접JSON/YAML 파일 업로드
규모소규모 도구 (1~5개)✓ 대규모 REST API
API GW 연동별도 구현✓ API Gateway 직접 매핑
takeaway

도구 1~5개의 소규모는 Function Detail로 충분하고, 대규모 REST API는 OpenAPI Schema로 관리합니다.

PART 2 · Action Group

좋은 description 패턴

description 품질이 도구 라우팅 정확도를 결정 — 3요소 명시

필수 3요소

정의

  • 언제 — 이 도구를 호출해야 하는 조건
  • 무엇을 — 입력 파라미터가 뭔지
  • 무엇이 — 반환되는 결과가 뭔지

예시로 대응해 보기

get_order_status

  • 언제 — "사용자의 주문 상태를 조회합니다"
  • 무엇을 — "주문번호(order_id)가 주어지면"
  • 무엇이 — "배송 상태·예상 도착일·현재 위치를 반환"
json
{
  "name": "get_order_status",
  "description": "사용자의 주문 상태를 조회합니다. 주문번호(order_id)가 주어지면 배송 상태, 예상 도착일, 현재 위치를 반환합니다."
}

Knowledge Bases와 프롬프트

GENERATE · RETRIEVE · 4단계 프롬프트 · 역할 정의

PART 3 · Knowledge Bases와 프롬프트

Knowledge Base와 프롬프트

지식은 선언으로 연결하고, 행동은 프롬프트로 제어

연결은 선언, 제어는 프롬프트

Knowledge Base를 연결하면 RAG 파이프라인이 자동으로 동작하고, 세밀한 행동은 4단계 프롬프트 오버라이드로 다듬습니다.

  • Knowledge Base 모드 — GENERATE vs RETRIEVE
  • 자동 RAG — 쿼리 생성 → 검색 → 답변
  • 프롬프트 4단계 — Pre · Orchestration · Knowledge Base · Post
takeaway

Knowledge Base 연결은 선언 한 번으로 끝나고, 에이전트의 역할·규칙·톤은 4단계 프롬프트에서 정의합니다.

PART 3 · Knowledge Bases와 프롬프트

Knowledge Base 연동 모드 2가지

답변을 생성할지, 원문만 반환할지 — 후처리 방식에 따라 선택

GENERATE (기본)

  • Knowledge Base 검색 → LLM이 답변 생성
  • 사용자에게 자연어 답변 전달
  • Citation 자동 포함
  • 일반적인 Q&A에 적합

에이전트가 Knowledge Base를 검색하고 답변까지 완성합니다.

RETRIEVE

  • Knowledge Base 검색 결과만 반환 (원문)
  • LLM 생성 없음
  • 앱이 직접 결과 가공
  • 커스텀 후처리에 적합

앱이 검색 결과를 직접 가공하거나 다른 시스템에 전달할 때.

takeaway

답변까지 맡기려면 GENERATE, 검색 결과를 앱이 직접 가공하려면 RETRIEVE를 선택합니다.

PART 3 · Knowledge Bases와 프롬프트

Knowledge Base 연동 시 자동 RAG 구성

Knowledge Base를 연결하면 쿼리 생성→벡터 검색→답변 생성이 자동으로 동작

  1. 1
    사용자 질문

    에이전트가 Knowledge Base 호출 필요 여부 판단

  2. 2
    쿼리 생성

    대화 맥락에서 검색 쿼리 자동 생성 (원문 그대로 검색하지 않음)

  3. 3
    벡터 검색

    Knowledge Base의 벡터 스토어에서 관련 청크 검색

  4. 4
    답변 생성

    검색 결과 + 시스템 프롬프트로 최종 답변 (Citation 포함)

takeaway

검색 쿼리는 원문 그대로가 아니라 대화 맥락에서 자동 생성됩니다 — 선언만으로 검색·증강·생성 파이프라인이 완성됩니다.

PART 3 · Knowledge Bases와 프롬프트

4단계 프롬프트 오버라이드

각 단계를 개별적으로 커스터마이징하여 에이전트 행동 제어

  1. 1
    Pre-processing

    입력 분류·안전 검사. "이 질문이 범위 안인가?" — 커스텀 분류 로직 삽입

  2. 2
    Orchestration

    도구 선택·실행 판단. 역할·페르소나·규칙·도구 우선순위 정의 — ReAct 루프의 핵심

  3. 3
    Knowledge Base

    Knowledge Base 검색 시 사용. 검색 쿼리 스타일과 답변 톤 제어

  4. 4
    Post-processing

    최종 응답 포맷팅·필터링·요약 — 출력 형식 강제

takeaway

역할·페르소나·도구 우선순위는 Orchestration 프롬프트에서 정의합니다 — ReAct 루프를 움직이는 핵심 단계입니다.

세션과 Trace 디버깅

sessionId · Attributes · Trace 주요 4종 · 오류 진단

PART 4 · 세션과 Trace 디버깅

세션과 Trace

대화는 세션으로 잇고, 판단 과정은 Trace로 열어보기

"왜 이 도구를 선택했나"에 Trace가 답한다

sessionId가 멀티턴 대화를 유지하고, Trace가 에이전트 실행의 각 단계를 보여줍니다.

  • sessionId — 멀티턴 컨텍스트 유지
  • sessionAttributes — 턴 간 상태 전달
  • Trace 주요 4종 — Pre · Orchestration · Post · Failure
takeaway

도구 선택의 이유는 추측하지 않습니다 — OrchestrationTrace의 modelInvocationInput에서 모델에 전달된 실제 프롬프트를 확인합니다.

PART 4 · 세션과 Trace 디버깅

세션 기반 대화 관리

sessionId로 멀티턴 컨텍스트를 유지하고, Attributes로 상태를 전달

sessionId

동일 ID = 동일 대화. 새 ID = 새 대화. TTL 기반 자동 만료

sessionAttributes

키-값 상태를 세션에 저장 — 프롬프트 템플릿에서 참조 가능, 턴 간 유지

한계와 대안

세션 내 단기 기억에 한정 — 세션 간 장기 기억은 AgentCore Memory로 해결

takeaway

멀티턴은 sessionId 재사용으로, 턴 간 상태는 sessionAttributes로 유지합니다 — 세션을 넘는 장기 기억은 AgentCore Memory의 영역입니다.

PART 4 · 세션과 Trace 디버깅

Trace 주요 4종

에이전트 실행 단계를 추적하는 트레이스 — "왜 이 도구를 선택했는지" 확인





콘솔 Test 창 · Show trace — OrchestrationTrace 페이로드



{"trace": {"orchestrationTrace": {

  "rationale": {"text": "재고 확인이 먼저 필요하므로 check_inventory를 호출한다"},

  "invocationInput": {"actionGroupInvocationInput": {

    "actionGroupName": "inventory-actions",

    "function": "check_inventory",

    "parameters": [{"name": "item", "value": "A4 용지"}]}}}}}



읽는 법

rationale — 모델이 이 도구를 고른 이유가 문장으로 기록

invocationInput — 실제 호출된 Action Group·함수·파라미터

같은 스트림에 modelInvocationInput(모델에 전달된 전체 프롬프트)도 포함




  1. 1
    PreProcessingTrace

    입력 분류 결과 · 안전 판단 · 카테고리 태그

  2. 2
    OrchestrationTrace

    모델 추론 · 도구 선택 이유 · 실행 결과 · modelInvocationInput

  3. 3
    PostProcessingTrace

    최종 응답 가공 과정 · 필터링 결과

  4. 4
    FailureTrace

    오류 발생 시 원인 · 위치 · 에러 메시지

takeaway

디버깅의 중심은 OrchestrationTrace입니다 — 모델 추론과 도구 선택 이유가 전부 이 단계에 기록됩니다. Guardrails 연결 시 guardrailTrace 같은 추가 유형도 반환됩니다.

PART 4 · 세션과 Trace 디버깅

도구 선택 오류 진단

OrchestrationTrace의 modelInvocationInput으로 실제 프롬프트를 확인하여 진단

증상원인해결
엉뚱한 도구 호출description이 비슷함차별화된 설명 작성 ("언제" 조건 명시)
도구 미호출description에 트리거 키워드 부재사용자 의도 키워드 추가
파라미터 누락required 미설정필수 파라미터에 required: true 명시
무한 루프종료 조건 없음프롬프트에 종료 조건 명시 + Trace로 반복 감시
takeaway

네 가지 증상 중 셋의 해결책이 스키마 설명 개선입니다 — 도구 오류의 대부분은 description에서 시작됩니다.

멀티에이전트와 마이그레이션

Supervisor · 네이티브 한계 · Alias · AgentCore 전환

PART 5 · 멀티에이전트와 마이그레이션

멀티에이전트와 마이그레이션

협업의 가능성과 한계, 그리고 AgentCore 전환 경로

Supervisor에서 AgentCore까지

Supervisor 모드로 협업을 구성하되 한계를 확인하고, Alias 배포를 거쳐 AgentCore Harness 전환으로 마무리합니다.

  • Supervisor 모드 — 하위 에이전트 위임
  • Alias · Versioning — 안전 배포와 롤백
  • agentcore export — Strands 코드 전환
takeaway

Classic은 유지보수 모드입니다 — 복잡한 멀티에이전트와 새 프로젝트는 AgentCore Harness가 다음 단계입니다.

PART 5 · 멀티에이전트와 마이그레이션

Supervisor 모드

상위 에이전트가 하위 협력 에이전트에 태스크를 위임

takeaway

Supervisor가 태스크를 분해·위임·통합합니다 — 하위 협력 에이전트는 사전 등록이 필요합니다.

PART 5 · 멀티에이전트와 마이그레이션

네이티브 멀티에이전트 한계

복잡한 멀티에이전트는 AgentCore Runtime + Strands Graph/Swarm 권장

항목지원한계
Supervisor 모드✓고정된 위임 구조 — 유연한 토폴로지 불가
협력 에이전트✓ 사전 등록동적 추가 불가
복잡한 오케스트레이션△조건 분기·루프 등 세밀한 제어 어려움
에이전트 간 상태 공유✗sessionAttributes로 우회
신규 기능 업데이트✗Classic은 신규 고객 차단 — 투자 중단
takeaway

유연한 토폴로지·동적 구성·상태 공유가 필요하면 AgentCore Runtime + Strands Graph/Swarm으로 넘어갑니다.

PART 5 · 멀티에이전트와 마이그레이션

배포와 마이그레이션

Alias·Versioning으로 안전 배포, AgentCore Harness로 전환

  1. 1
    Draft 편집

    에이전트 설정 변경 (프롬프트, Action Group)

  2. 2
    Version 생성

    현재 Draft를 스냅샷으로 고정

  3. 3
    Alias 연결

    프로덕션 Alias가 특정 Version을 가리킴 — 롤백 가능

  4. 4
    AgentCore 전환

    agentcore export → Strands 코드. Harness가 1:1 대체

takeaway

Draft → Version → Alias로 롤백 가능한 배포를 유지하고, 전환은 agentcore export 한 번으로 Strands 코드를 얻습니다.

PART 5 · 멀티에이전트와 마이그레이션

Classic에서 AgentCore로

선언적 구조는 그대로 — 새 프로젝트는 AgentCore Harness 시작

Classic을 이해하면, AgentCore 전환이 명확해진다

Action Group + Knowledge Base + 프롬프트 4단계 — 선언적 에이전트의 구조는 그대로, 새 프로젝트는 AgentCore Harness로 시작합니다.

  • 3요소 선언 구성
  • Trace로 디버깅
  • agentcore export → Strands 전환

기존 Bedrock Agent 분석과 AgentCore 전환

⏱ 60분

기존 Classic 에이전트 구성을 분석하고 AgentCore로 전환합니다 (신규 구축은 AgentCore 사용)

학습 목표

  • 기존 에이전트의 Action Group·Knowledge Base 구성 분석
  • Trace로 오케스트레이션 과정 이해
  • agentcore export로 Strands 코드 전환
  • Harness로 배포해 동일 동작 확인
Bedrock Agents Classic을 이해하면, AgentCore로의 전환이 명확해집니다.

Action Group + Knowledge Base + 프롬프트 = 선언적 에이전트. 다음 단계는 AgentCore Harness.