Amazon Bedrock AgentCore 웹 검색

Amazon Bedrock AgentCore 웹 검색 (Amazon Bedrock AgentCore Web Search)

AWS가 관리하는 웹 인덱스를 AgentCore Gateway의 MCP 도구로 노출하는 검색 제공자예요. 검색 트래픽이 AWS 안에 머무르고 제3자 검색 API 대신 AWS가 과금해요. 다른 검색 제공자와 달리 가입할 API 키가 없어요.

출처: 문서

본문

Amazon Bedrock AgentCore의 웹 검색은 AWS가 관리하는 웹 인덱스로, AgentCore Gateway의 MCP 도구로 노출되므로 검색 트래픽이 AWS 안에 머물고 제3자 검색 API 대신 AWS가 과금해요.

다른 검색 제공자와 달리 가입할 API 키가 없어요. web-search 커넥터 대상을 가진 게이트웨이를 만든 다음 LiteLLM을 그 MCP 엔드포인트에 연결하면 돼요.


제공자 ID	`agentcore`
게이트웨이 URL	`AGENTCORE_GATEWAY_URL` 또는 `api_base`
인증 (AWS_IAM gateway)	SigV4, 명시적 키 또는 표준 AWS 자격 증명 체인
인증 (CUSTOM_JWT gateway)	`AGENTCORE_GATEWAY_TOKEN` 또는 `api_key`
도구 이름 오버라이드	`AGENTCORE_SEARCH_TOOL_NAME` 또는 `tool_name`
MCP 프로토콜 버전 오버라이드	`AGENTCORE_MCP_PROTOCOL_VERSION`

게이트웨이 URL은 https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp처럼 생겼어요.

LiteLLM Python SDK

AgentCore Web Search

import os
from litellm import search

os.environ["AGENTCORE_GATEWAY_URL"] = "https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp"
os.environ["AWS_ACCESS_KEY_ID"] = "your-access-key"
os.environ["AWS_SECRET_ACCESS_KEY"] = "your-secret-key"

response = search(
    query="latest AI developments",
    search_provider="agentcore",
    max_results=5
)

for result in response.results:
    print(f"{result.title}: {result.url}")
    print(f"Snippet: {result.snippet}\n")

AWS 키를 생략하면 표준 자격 증명 체인(환경, 공유 프로필, IRSA, 인스턴스 역할)을 사용하고, 호출별로 aws_access_key_id, aws_secret_access_key, aws_session_token, aws_region_name으로 전달할 수도 있어요.

CUSTOM_JWT 게이트웨이의 경우 AWS 자격 증명 대신 OAuth2 bearer 토큰을 전달해요: AgentCore Web Search with a CUSTOM_JWT gateway

response = search(
    query="latest AI developments",
    search_provider="agentcore",
    api_key=os.environ["AGENTCORE_GATEWAY_TOKEN"]
)

LiteLLM AI Gateway

1. config.yaml 설정

config.yaml

search_tools:
  - search_tool_name: agentcore-search
    litellm_params:
      search_provider: agentcore
      api_base: https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp

2. 프록시 시작

litellm --config /path/to/config.yaml

# RUNNING on http://0.0.0.0:4000

3. 검색 엔드포인트 테스트

Test Request

curl http://0.0.0.0:4000/v1/search/agentcore-search \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI developments",
    "max_results": 5
  }'

Bedrock용 웹 검색 인터셉션

제공자가 제3자 키를 필요로 하지 않으므로, 검색 제공자에서 Anthropic 네이티브 web_search 도구(Claude Code가 사용하는)를 제공하는 웹 검색 인터셉션의 자연스러운 백엔드예요: config.yaml

model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: bedrock/us.anthropic.claude-sonnet-5
      aws_region_name: us-east-1

search_tools:
  - search_tool_name: agentcore-search
    litellm_params:
      search_provider: agentcore
      api_base: https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp

litellm_settings:
  callbacks: ["websearch_interception"]
  websearch_interception_params:
    enabled_providers: ["bedrock"]
    search_tool_name: agentcore-search

통합 파라미터

통합 사양 파라미터	AgentCore 파라미터로 매핑
`max_results`	`maxResults`
`search_domain_filter`	무시 (해당 없음)
`country`	무시 (해당 없음)
`max_tokens_per_page`	무시 (해당 없음)

AgentCore는 쿼리를 200자로 제한하므로, 더 긴 쿼리는 잘려요.

제공자별 파라미터

파라미터	타입	설명
`tool_name`	string	호출할 게이트웨이 도구. 기본값 `web-search-tool___WebSearch`로 AWS 설정 문서에 사용된 대상 이름과 일치해요. 커넥터 대상 이름이 다를 때만 설정하세요. `___WebSearch`로 끝나야 해요.

참고 사항

게이트웨이는 AWS가 직접 과금하므로, LiteLLM은 agentcore/search를 0 비용으로 추적해요.

SigV4 서명 지역은 게이트웨이 호스트네임에서 나와요. 게이트웨이 앞에 커스텀 호스트네임을 두면 aws_region_name(또는 AWS_REGION, 프로필 리전)을 게이트웨이의 리전으로 설정하세요.

AGENTCORE_GATEWAY_TOKEN은 요청이 AGENTCORE_GATEWAY_URL에 구성된 게이트웨이를 대상으로 할 때만 전송되므로, 호출자가 제공한 api_base가 그것을 유출할 수 없어요. 자격 증명은 https에서만 탑니다. 평문 http:// 게이트웨이 URL은 호스트가 localhost가 아니면 거부돼요.

LiteLLM은 모든 요청에 MCP-Protocol-Version: 2025-03-26을 보내는데, 이는 기본 protocolConfiguration을 가진 게이트웨이가 받아들이는 버전이에요. 게이트웨이가 supportedVersions를 다른 값으로 고정했다면 AGENTCORE_MCP_PROTOCOL_VERSION을 예: 2025-06-18과 같이 맞춰 설정하세요.

Amazon Bedrock AgentCore 웹 검색