Connect Amazon Bedrock AgentCore to cross-account knowledge bases

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Amazon Bedrock AgentCore는 최소 권한의 교차 계정 IAM 역할을 통해 원본 데이터 복사 없이 다른 계정의 지식 기반에서 답변을 생성하며, 사용자 정의가 필요한 정도에 따라 Strands 에이전트와 선언형 AgentCore harness를 선택할 수 있다.

📌 핵심 요약

• Amazon Bedrock Knowledge Bases 리소스 정책은 교차 계정 Retrieve와 GetDocumentContent를 지원하지만 RetrieveAndGenerate는 지원하지 않으므로, 답변 생성 도구가 AWS STS로 지식 기반 계정의 IAM 역할을 맡아 호출한다.
• 두 구현 모두 Amazon Redshift Serverless 기반 지식 기반을 사용한다. Amazon Nova Pro가 query_knowledge_base 도구 호출을 결정하고, 도구는 RetrieveAndGenerate와 Claude Haiku 4.5를 통해 생성한 답변과 인용을 반환한다.
• 코드 기반 Strands 에이전트는 AgentCore runtime에서 Python 에이전트 루프와 로컬 MCP 도구를 실행하며, 선언형 AgentCore harness는 관리형 루프에서 AgentCore Gateway를 거쳐 AWS Lambda 도구를 호출한다.
• 검색된 콘텐츠만 필요하면 교차 계정 Retrieve를 검토하고, 도구 선택·다단계 추론·대화 상태 없이 매번 답변 하나만 필요하면 RetrieveAndGenerate를 직접 호출한다. 모델이 도구 사용을 판단해야 할 때 에이전트를 사용한다.
• 두 구현 비교에는 동일한 질문·지식 기반 ID·모델·검색 결과 수와 새 세션을 사용한다. 행 단위 질문은 행 수·날짜 범위·정렬 순서를 제한하고, 업무 사실은 직접 도구 응답과 원본 구조화 데이터로 검증한다.

🧩 주요 포인트

1. RetrieveAndGenerate의 교차 계정 리소스 정책 지원 제약 → 지식 기반 계정의 최소 권한 IAM 역할이 두 구현의 공통 데이터 접근 경계가 된다.
2. Strands는 사용자 코드가 루프를 소유하고 AgentCore harness는 관리형 루프를 사용 → 선택 기준은 교차 계정 연결 자체보다 사용자 정의 제어와 운영 책임의 범위다.
3. RetrieveAndGenerate는 생성형으로 동작하고 무제한 SQL 결과는 처리 한도를 넘을 수 있음 → 동일 조건 비교, 행 수·날짜 범위·정렬 순서 제한, 원본 구조화 데이터 검증이 필요하다.

🧠 상세 정리

1. 계정 분리를 유지하면서 답변을 생성하는 과제

조직은 Amazon Bedrock AgentCore로 에이전트를 운영하면서, 거버넌스가 적용된 지식 기반과 구조화 데이터를 별도의 AWS 계정에 둘 수 있다. 이러한 분리는 에이전트 워크로드와 데이터 워크로드의 경계를 명확하게 유지하지만, 다른 계정의 데이터를 이용해 자연어 답변을 생성하는 연결 과정에는 추가 구성이 필요하다. 원문은 Amazon Redshift Serverless에 연결된 Amazon Bedrock Knowledge Bases를 대상으로, 원본 데이터를 에이전트 계정에 복사하지 않는 접근 방식을 설명한다. 핵심 목표는 자연어 답변 생성, 계정 경계 유지, 데이터 복사 방지, 전용 IAM 역할을 통한 최소 권한 접근을 함께 충족하는 것이다.

2. API 지원 제약과 공통 보안 경계

Amazon Bedrock Knowledge Bases의 리소스 정책은 교차 계정 작업으로 Retrieve와 GetDocumentContent를 지원하지만, RetrieveAndGenerate는 지원 대상에 포함하지 않는다. 따라서 이 솔루션은 생성된 답변을 받기 위해 도구가 AWS STS를 사용하여 지식 기반 계정의 bedrock_kb_access_role을 맡도록 구성한다. 이후 역할을 맡은 세션에서 RetrieveAndGenerate를 호출하고, 생성된 답변과 인용을 오케스트레이션 계층에 반환한다. 코드 기반 방식과 선언형 방식 모두 이 데이터 접근 경계를 공유하므로, 구현 방식을 바꾸더라도 교차 계정 접근 원리는 동일하다. 접근 역할은 필요한 지식 기반과 모델 리소스로 범위를 제한하며, 장시간 실행되는 런타임과 재사용되는 AWS Lambda 실행 환경에서는 갱신 가능한 STS 자격 증명을 사용하도록 권고한다.

3. 질문에서 구조화 데이터 조회와 답변까지

사용자는 Streamlit UI 또는 AgentCore API를 통해 자연어 질문을 제출하고, Amazon Nova Pro는 query_knowledge_base 도구를 호출할지 결정한다. 코드 기반 구현에서는 AgentCore runtime에 패키징된 로컬 MCP 하위 프로세스에서 도구가 실행되며, 선언형 구현에서는 AgentCore harness가 AgentCore Gateway를 통해 AWS Lambda 도구를 호출한다. 도구는 지식 기반 계정의 접근 역할을 맡은 뒤 Claude Haiku 4.5를 사용하는 RetrieveAndGenerate 요청을 보낸다. 지식 기반은 질문을 Amazon Redshift Serverless에 대한 구조화 쿼리로 변환하며, 생성된 답변은 선택한 오케스트레이션 경로를 거쳐 사용자에게 돌아온다. 이 흐름에서 도구 호출을 판단하는 모델과 지식 기반 답변 생성에 사용하는 모델은 각각 다른 역할을 담당한다.

4. 에이전트가 필요한지 먼저 판단

원문은 두 AgentCore 구현 중 하나를 고르기 전에, 해당 워크로드에 에이전트가 실제로 필요한지 먼저 판단하도록 제안한다. 애플리케이션이 검색된 콘텐츠만 필요로 한다면 지식 기반 리소스 정책을 사용하는 기본 교차 계정 Retrieve 방식을 검토할 수 있다. 모든 요청이 정해진 흐름에 따라 생성 답변 하나만 요구한다면, 도구 선택과 다단계 추론 및 대화 상태가 필요하지 않은지 먼저 확인한다. 이러한 기능이 필요 없다면 애플리케이션이나 AWS Lambda 함수가 지식 기반 계정의 역할을 맡아 RetrieveAndGenerate를 직접 호출하면 된다. 더 넓은 대화나 도구 사용 흐름에서 모델이 지식 기반을 언제 또는 어떻게 조회할지 판단해야 하는 경우에 에이전트를 사용하며, 필요한 동작에 맞춰 설계 복잡도를 결정한다.

5. Strands와 선언형 harness의 선택 기준

코드 기반 Strands 에이전트는 Python 코드와 Strands Agents SDK로 루프를 실행하므로, 사용자 정의 오케스트레이션·훅·미들웨어·재시도·계측이나 도구 및 스트리밍의 직접 제어가 필요한 팀에 적합하다. 이 방식에서는 agent.py, 의존성, MCP 서버, 도구 로직, 런타임 설정을 유지하며 InvokeAgentRuntime으로 호출한다. 선언형 AgentCore harness는 정의된 설정에 따라 AgentCore가 루프를 실행하므로, 관리형 루프가 요구사항에 맞고 설정 중심의 운영을 선호하는 팀에 적합하다. 이 방식에서도 harness 설정, 시스템 프롬프트, AWS Lambda 도구, IAM, 애플리케이션 동작은 유지해야 하며 호출 API는 InvokeHarness다. 교차 계정 역할을 맡는 주체는 각각 AgentCore runtime 실행 역할과 Gateway 뒤의 AWS Lambda 실행 역할이며, 두 방식의 선택을 가르는 기준은 사용자 정의 제어와 관리형 오케스트레이션이다.

6. 배포 전제와 구현 자료

실행에는 에이전트 계정과 지식 기반 계정의 두 AWS 계정, 양쪽 계정의 자격 증명, AWS CLI v2.24.22 이상, Python 3.10 이상, jq가 필요하다. Amazon Redshift Serverless에 연결된 구조화 지식 기반과 함께, 미국 서부 오리건 리전에서 에이전트 계정의 Amazon Nova Pro 및 지식 기반 계정의 Claude Haiku 4.5 모델 접근 권한도 준비해야 한다. 선언형 방식에는 코드 기반 방식의 Python bedrock-agentcore CLI 외에 최신 @aws/agentcore Node.js CLI가 추가로 필요하다. 예제는 us-west-2와 agent 및 agent-kb 프로필 별칭을 사용하지만, 실제 환경에서는 구성된 프로필로 바꾸고 계정 ID를 조회하도록 안내한다. 세부 배포 절차는 공개 GitHub 샘플에서 관리하며, 지식 기반·교차 계정 IAM 역할·AgentCore memory 준비와 각 구현의 실행 방법, Local·AgentCore·Harness 모드를 지원하는 Streamlit 클라이언트를 제공한다.

7. 비교 검증과 생성형 조회의 한계

두 구현을 비교할 때는 질문, 지식 기반 ID, 모델, 검색 결과 수를 동일하게 맞추고 각각 새 세션을 사용해야 한다. 프롬프트 계약은 사용자 질문을 그대로 도구에 전달하도록 정하지만, RetrieveAndGenerate 자체는 생성형으로 동작하므로 업무 사실은 직접 도구 응답과 원본 구조화 데이터로 확인해야 한다. 행 단위 질문에는 행 수, 날짜 범위, 정렬 순서를 명시해야 하며, 제한 없는 생성 SQL은 결과 처리 한도를 초과할 수 있다. Streamlit에서는 호출 모드를 먼저 선택하고 AgentCore 또는 Harness 모드의 배포 리소스 ARN이 채워져 있는지 확인한 뒤, 독립적인 사실 비교마다 새 대화를 시작한다. 원문은 TPC-H 데이터에 대해 사우디아라비아 상위 고객 5명이나 1997년 10월부터 12월까지의 1-URGENT 주문 중 금액 상위 100건처럼 조회 대상을 구체화한 질문을 제시한다.

8. 운영 권고와 리소스 정리

운영 시에는 정확한 도구 질의, 지식 기반 ID, 모델 ID, 검색 결과 수를 기록하고, 파생 업무 지표는 승인된 정제 SQL과 열 설명으로 정의하도록 권고한다. 두 구현 모두 시스템 프롬프트, 도구 설명, IAM, 애플리케이션 동작을 시험하며, Amazon Bedrock Guardrails로 사용자 질문과 생성 답변의 유해 콘텐츠·금지 주제·민감 정보를 평가한다. Guardrails는 최소 권한 접근, 원본 데이터 거버넌스, 인용 기반 검증, 중대한 결정에 대한 사람의 검토를 보완하며 이를 대체하지 않는다. 두 구현을 모두 배포했다면 harness를 먼저 정리하여 공유 지식 기반 접근 역할에서 AWS Lambda 실행 역할에 대한 신뢰 권한을 제거한 다음, 코드 기반 런타임과 공유 IAM 리소스를 삭제한다. 정리 스크립트는 프로젝트에서 관리하는 AgentCore memory, 지식 기반, Redshift Serverless 리소스를 삭제하지 않으므로, 더 이상 필요하지 않을 때 별도로 삭제해야 한다.

🧾 핵심 주장 / 시사점

• 두 구현은 동일한 교차 계정 데이터 접근 경계를 공유하므로, 데이터 접근 권한 설계와 에이전트 루프 운영 방식은 구분하여 판단할 수 있다.
• 생성 답변이 필요하다는 조건만으로 에이전트가 필요한 것은 아니며, 모델의 도구 선택이나 대화 오케스트레이션 필요성이 도입 판단의 기준이다.
• 질문을 도구에 그대로 전달해도 RetrieveAndGenerate의 생성형 동작은 남으므로, 비교 조건 통일과 원본 데이터 검증이 함께 필요하다.

✅ 액션 아이템

• 도구 선택·다단계 추론·대화 상태 필요성에 따라 교차 계정 Retrieve, RetrieveAndGenerate 직접 호출, 에이전트 사용의 적합성 검토.
• 최소 권한 IAM 역할을 공통 데이터 접근 경계로 두고, 사용자 정의 제어와 운영 책임의 범위에 따라 Strands 또는 AgentCore harness 선택.
• 동일한 질문·지식 기반 ID·모델·검색 결과 수와 새 세션으로 비교하고, 행 수·날짜 범위·정렬 순서를 제한하여 원본 구조화 데이터와 대조.

❓ 열린 질문

• 현재 요청에는 도구 선택·다단계 추론·대화 상태가 필요한가, 아니면 RetrieveAndGenerate 직접 호출로 충족할 수 있는가?
• 필요한 사용자 정의 제어와 운영 책임의 범위에는 Strands와 AgentCore harness 중 어느 방식이 더 적합한가?
• 행 단위 질문의 행 수·날짜 범위·정렬 순서는 어떻게 정하고, 답변의 업무 사실은 원본 구조화 데이터와 어떻게 대조할 것인가?