Introducing the Web Search API on Amazon Bedrock AgentCore

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

AWS는 Amazon Bedrock AgentCore에서 별도 리소스 생성 없이 기존 IAM 자격 증명과 단일 API 호출로 웹 검색 결과를 가져오는 Web Search API를 발표했다.

📌 핵심 요약

• Web Search API는 AWS SDK나 AWS CLI에서 InvokeWebSearch를 호출해 Amazon이 운영하는 웹 인덱스를 검색한다. 모든 결과에는 텍스트 발췌가 포함되며, 제목·URL·게시 시각은 인덱스에 해당 정보가 있을 때 제공된다. 검색어는 타사 검색 엔진으로 전송되지 않는다.
• AgentCore Gateway는 통합 MCP 엔드포인트, 인증, 의미 기반 도구 선택 등을 제공하므로 대부분의 에이전트 워크로드에 여전히 권장된다. Web Search API는 자체 오케스트레이션, 비에이전트 애플리케이션, 재시도·캐싱·오류 처리의 직접 관리가 필요한 경우를 보완한다.
• searchQuery는 최대 200자이며, maxResults는 1~25개로 설정할 수 있고 생략 시 최대 25개를 반환한다. 도메인 포함·제외 목록은 각각 최대 100개를 지원하고, 게시 시각은 UTC의 RFC 3339 형식으로 지정하며 양쪽 경계를 포함한다.
• 로컬 Python 개발에는 Boto3 1.43.127 이상이 안내되며, langchain-aws 1.9.3 이상과 AgentCore Python SDK 1.26.0 이상에서 Web Search API를 지원한다. AWS Lambda, Amazon ECS, Amazon EC2, Amazon EKS에서는 실행 역할이 자격 증명을 자동으로 제공한다.
• 접근은 IAM의 bedrock-agentcore:InvokeWebSearch 권한으로 제어한다. CloudTrail 데이터 이벤트 기록은 별도로 활성화해야 하며 검색어와 필터는 기록하지 않는다. AWS PrivateLink를 통한 비공개 연결을 지원하고, 기본 호출 한도는 계정·리전별 초당 10건이며 상향을 요청할 수 있다.

🧩 주요 포인트

1. Gateway와 직접 API가 동일한 검색 인프라를 사용하므로, 통합 도구 관리의 필요성과 호출 수명주기를 직접 제어할 필요성이 통합 경로 선택의 기준이 된다.
2. 도메인·게시 시각 필터와 결과 수 제한으로 검색 범위를 조절할 수 있지만, 제목·URL·게시 시각은 선택적으로 제공되므로 응답 처리에서 누락 가능성을 고려해야 한다.
3. 기존 IAM 체계와 AWS PrivateLink를 활용할 수 있어 접근·네트워크 통제를 적용하기 쉽지만, CloudTrail 기록 범위와 계정·리전별 호출 한도는 별도로 고려해야 한다.

🧠 상세 정리

1. 최신 정보 검색을 위한 직접 호출 API

최근 사건, 제품 출시, 가격, 규정에 답하는 AI 에이전트와 애플리케이션에는 모델 학습 데이터보다 새로운 정보가 필요하다. 기존 Amazon Bedrock AgentCore의 웹 검색은 AgentCore Gateway를 통해 제공됐으며, 게이트웨이와 웹 검색 대상을 생성한 뒤 MCP 클라이언트에서 도구를 호출해야 했다. 새 Web Search API는 별도 리소스를 먼저 만들지 않고 기존 AWS 자격 증명으로 인증한 다음, AWS SDK 또는 AWS CLI의 단일 API 호출로 검색 결과를 받을 수 있게 한다. 응답은 Amazon이 운영하는 웹 인덱스에서 순위를 매긴 결과이며, 각 결과에는 텍스트 발췌와 가용한 제목·URL·게시 시각이 포함된다. 원문은 이를 일반 애플리케이션, 개발자가 직접 작성한 에이전트 루프, 데이터 파이프라인에 사용할 수 있다고 설명하며, Alexa+, Kiro, Quick 등 Amazon 제품을 구동하는 검색 인프라와 동일한 품질 및 규정 준수 체계를 직접 API로 제공한다고 소개한다.

2. AgentCore Gateway와 직접 API의 역할

원문은 Web Search API를 발표하면서도 대부분의 에이전트 워크로드에는 AgentCore Gateway를 권장한다. Gateway는 웹 검색과 다른 도구를 하나의 보안 MCP 엔드포인트로 통합하고, 인바운드·아웃바운드 인증, 의미 기반 도구 선택, 선택적인 MCP 세션을 처리한다. 반면 자체 에이전트 루프를 만들거나 LangChain·LlamaIndex 같은 프레임워크를 쓰는 개발자는 검색을 자신의 오케스트레이션 로직 안에서 직접 호출하기를 원할 수 있다. 검색 기반 대시보드, 사실 확인 파이프라인, 콘텐츠 보강 워크플로, 모니터링 시스템처럼 에이전트 인프라가 필요하지 않은 용도도 직접 API의 대상이다. 재시도·캐싱·오류 처리를 직접 관리하거나 기존 애플리케이션의 API 계층에 웹 검색을 추가하려는 요구도 제시되며, 두 경로는 같은 검색 인프라를 사용하는 상호 보완적 선택지로 설명된다.

3. InvokeWebSearch의 인증과 요청 처리

Web Search API는 AgentCore Browser 같은 다른 도구도 사용하는 bedrock-agentcore 데이터 플레인의 InvokeWebSearch 작업으로 제공된다. AWS SDK와 AWS CLI는 표준 AWS 자격 증명을 사용해 요청에 AWS Signature Version 4인 SigV4 서명을 적용하므로, 별도 API 키나 비밀값을 관리할 필요가 없다. API는 호출자에게 AWS 관리형 웹 검색 도구에 대한 bedrock-agentcore:InvokeWebSearch 권한이 있는지 IAM으로 확인한 다음, 요청의 도메인 및 게시 시각 필터를 적용한다. 이후 Amazon이 운영하는 웹 인덱스를 검색하고 maxResults까지 순위가 매겨진 결과를 반환하며, 검색어는 AWS 안에서 처리되고 타사 검색 엔진으로 전달되지 않는다. 예시 정책의 리소스는 arn:aws:bedrock-agentcore:us-west-2:aws:tool/web-search.v1이며, Gateway 서비스 역할도 동일한 작업과 리소스를 사용하므로 하나의 정책으로 두 호출 경로를 포괄할 수 있다.

4. 검색 범위와 응답 형식의 제약

도메인 필터는 포함하거나 제외할 도메인을 지정해 검색 범위를 조절하며, 각 목록에는 최대 100개의 도메인 이름을 넣을 수 있고 루트 도메인은 하위 도메인에도 적용된다. 게시 시각 필터는 publishedAfter와 publishedBefore를 사용하며, 2026-01-01T00:00:00Z 같은 UTC의 RFC 3339 형식으로 지정하고 양쪽 경계를 모두 포함한다. 검색어인 searchQuery의 길이는 최대 200자이고, maxResults는 쿼리당 1~25개로 설정할 수 있으며 생략하면 최대 25개를 반환한다. 모든 결과에는 모델의 컨텍스트에 넣을 수 있는 텍스트 발췌가 포함되지만, 페이지 제목·URL·게시 시각은 인덱스가 해당 정보를 보유한 경우에만 제공된다. 따라서 원문의 Python 예시는 선택적인 필드를 get으로 읽으며, 검색 결과를 사용하는 코드가 이들 필드의 누락 가능성을 처리하도록 보여준다.

5. 첫 검색 예제와 실행 환경

첫 Python 예제는 AWS SDK for Python인 Boto3로 us-west-2의 bedrock-agentcore 클라이언트를 만들고 web-search.v1을 호출한다. 검색어는 multi-region EKS cluster deployment best practices이며, maxResults를 10으로 설정하고 aws.amazon.com과 kubernetes.io만 포함하도록 도메인 범위를 제한한다. 게시 시각 조건은 publishedAfter를 2026-01-01T00:00:00Z로 지정하며, 제시된 코드에는 publishedBefore 상한이 없다. 축약된 실제 호출 결과에는 Amazon EKS의 엣지 컨테이너 전략을 다룬 페이지의 제목·URL·텍스트 발췌와 2026-09-25T15:52:00Z라는 게시 시각이 제시된다. 코드가 AWS Lambda, Amazon ECS, Amazon EC2 또는 Amazon EKS에서 실행되면 실행 역할이 자격 증명을 자동으로 제공하므로, 해당 역할에 필요한 권한을 추가하면 같은 코드를 변경 없이 실행할 수 있다고 설명한다.

6. CloudShell과 로컬 개발의 시작 절차

원문은 첫 결과를 얻는 방법으로 브라우저의 AWS CloudShell과 로컬 개발 환경을 제시한다. CloudShell은 콘솔 세션의 자격 증명을 사용하며, 역할에는 앞서 제시한 정책이나 더 넓은 AWS 관리형 정책인 BedrockAgentCoreFullAccess를 통해 bedrock-agentcore:InvokeWebSearch 권한이 있어야 한다. CLI 예제는 aws bedrock-agentcore invoke-web-search에서 web-search.v1을 지정하고 latest EKS features를 검색해 최대 5개 결과를 요청한다. 로컬에서는 AWS CLI 또는 해당 언어의 AWS SDK를 설치하며, Python에는 Boto3 1.43.127 이상을 사용하도록 안내한다. 필요한 정책을 가진 IAM 역할을 만든 뒤 애플리케이션이나 AWS CLI 프로필에서 역할을 수임하거나 자격 증명 공급자를 통해 로그인해 호출하며, 두 방법 모두 별도의 검색 리소스나 API 키를 생성하지 않는다.

7. 에이전트 프레임워크와 SDK 통합

LangChain 에이전트는 langchain-aws 1.9.3 이상에서 제공하는 AgentCore 웹 검색 도구를 사용할 수 있으며, 예제는 create_web_search_toolkit으로 도구를 만들고 bedrock_converse:us.anthropic.claude-sonnet-5 모델과 연결한다. 예제의 시스템 프롬프트는 사용한 모든 사실의 URL을 인용하도록 요구하고, 검색 도구에는 제외 도메인·게시 시각 하한·검색 예산처럼 모델이 바꿀 수 없는 규칙을 둘 수 있다고 설명한다. 도구는 애플리케이션 코드가 검사할 수 있는 데이터로 결과를 반환하며, 소개된 daily dependency watch 샘플은 LangGraph로 세 패키지 생태계를 병렬 조사하고 보고 전에 각 발견 사항을 출처와 대조한다. 개발자가 직접 감싸는 방식을 선호하면 Boto3 호출을 일반 LangChain 도구로 정의하고 검색 결과를 JSON 문자열로 반환할 수도 있다. 프레임워크 없이 사용할 때는 AgentCore Python SDK의 WebSearchClient가 같은 호출을 감싸 날짜를 파싱한 결과를 제공하며, 해당 지원은 AgentCore Python SDK 1.26.0 이상에 추가됐다.

8. 기업 접근 통제와 감사 기록, 호출 한도

Web Search API는 표준 IAM 인증을 사용하므로 사용자·그룹·역할별로 bedrock-agentcore:InvokeWebSearch를 허용하거나 거부하고, 서비스 제어 정책인 SCP로 계정 전반의 제약을 적용할 수 있다. AWS CloudTrail은 InvokeWebSearch 요청을 데이터 이벤트로 기록하지만 기본적으로 활성화되지 않으므로, 트레일이나 이벤트 데이터 스토어에 AWS::BedrockAgentCore::WebSearch 리소스 유형의 이벤트 선택기를 추가해야 한다. 기록되는 정보에는 웹 검색 도구와 maxResults가 포함되며 검색어와 필터는 포함되지 않는다는 점이 명시된다. 원문은 규정 준수 프로그램의 구체적 적용 범위와 허용되는 사용 방식에 대해서는 각각 AgentCore 규정 준수 검증 문서와 Web Search API Acceptable Use 문서를 참조하도록 안내한다. 할당량은 계정별로 적용되고 기본적으로 각 리전에서 초당 최대 10건의 요청을 보낼 수 있으며, 필요한 경우 한도 상향을 요청할 수 있다.

9. AWS PrivateLink를 통한 비공개 연결

민감한 데이터를 처리하는 에이전트와 파이프라인은 인터넷 경로가 없는 프라이빗 서브넷에서 실행되는 경우가 있으며, 원문은 이를 위해 AWS PrivateLink 연결을 설명한다. 애플리케이션은 VPC 안의 인터페이스 VPC 엔드포인트를 통해 Web Search API를 호출하고, VPC와 API 사이의 트래픽은 AWS 네트워크에 머문다. 따라서 이 API에 접근하기 위해 인터넷 게이트웨이, NAT 게이트웨이 또는 프록시를 둘 필요가 없다고 설명한다. 제시된 흐름에서는 애플리케이션이 표준 리전 API 이름으로 InvokeWebSearch를 호출하면 프라이빗 DNS가 이를 서브넷의 인터페이스 엔드포인트로 해석하고, 엔드포인트 정책이 적용된 뒤 요청이 AWS 네트워크를 통해 API에 도달한다. 다만 제공된 source_body는 이어지는 IAM 확인 단계의 문장 중간에서 끝나므로, 그 이후의 설명이나 추가 설정 절차는 확인할 수 없다.

🧾 핵심 주장 / 시사점

• 직접 API의 핵심은 검색 호출을 기존 애플리케이션과 자체 오케스트레이션에 쉽게 넣는 데 있다. 공통 도구와 인증을 통합 관리해야 하는 경우에는 AgentCore Gateway의 역할이 유지된다.
• 도메인·게시 시각 필터는 검색 범위를 제한하지만, 제목·URL·게시 시각의 제공 여부까지 보장하지는 않는다. 원문이 소개하는 출처 대조와 코드 검사는 검색 결과를 활용하는 별도의 처리 단계다.
• IAM과 AWS PrivateLink는 접근 및 네트워크 통제를 제공하지만, CloudTrail 데이터 이벤트는 별도 활성화가 필요하고 검색어·필터를 기록하지 않으므로 감사 기록의 범위를 구분해 이해해야 한다.

✅ 액션 아이템

• 통합 도구·인증 관리와 재시도·캐싱·오류 처리의 직접 관리 필요성을 기준으로 AgentCore Gateway와 Web Search API의 적용 경로 검토.
• searchQuery 최대 200자, maxResults 1~25개, 도메인 목록별 최대 100개 및 게시 시각 조건을 반영한 검색 범위 설정.
• IAM 권한, CloudTrail 데이터 이벤트 활성화, AWS PrivateLink 적용 필요성과 계정·리전별 기본 초당 10건 한도 확인.

❓ 열린 질문

• 현재 애플리케이션에는 AgentCore Gateway의 통합 도구·인증 관리와 Web Search API의 직접 호출 중 어느 경로가 더 적합한가?
• 제목·URL·게시 시각이 제공되지 않는 검색 결과를 애플리케이션에서 어떻게 처리할 것인가?
• 계정·리전별 기본 초당 10건 한도가 예상 호출량에 충분하며, 검색어와 필터를 기록하지 않는 CloudTrail의 기록 범위가 필요한 감사 요건을 충족하는가?