자연어 쿼리를 사용하여 AgentCore 게이트웨이에서 도구 검색

게이트웨이를 생성할 때 시맨틱 검색을 활성화한 경우 x_amz_bedrock_agentcore_search 도구를 호출하여 자연어 쿼리를 사용하여 게이트웨이에서 도구를 검색할 수 있습니다. 시맨틱 검색은 도구가 많고 사용 사례에 가장 적합한 도구를 찾아야 하는 경우에 특히 유용합니다. 게이트웨이 생성 중에 의미 체계 검색을 활성화하는 방법을 알아보려면 Amazon Bedrock AgentCore 게이트웨이 생성을 참조하세요.

의미 체계 검색을 지원하는 AWS 리전

의미 체계 검색은 다음 AWS 리전에서 지원됩니다.

리전 이름	리전
미국 동부(버지니아 북부)	us-east-1
미국 동부(오하이오)	us-east-2
미국 서부(오리건)	us-west-2
아시아 태평양(하이데라바드)	ap-south-2
아시아 태평양(뭄바이)	ap-south-1
아시아 태평양(서울)	ap-northeast-2
아시아 태평양(싱가포르)	ap-southeast-1
아시아 태평양(시드니)	ap-southeast-2
아시아 태평양(도쿄)	ap-northeast-1
캐나다(중부)	ca-central-1
유럽(프랑크푸르트)	eu-central-1
유럽(아일랜드)	eu-west-1
유럽(런던)	eu-west-2
유럽(밀라노)	eu-south-1
유럽(파리)	eu-west-3
유럽(스페인)	eu-south-2
유럽(스톡홀름)	eu-north-1
남아메리카(상파울루)	sa-east-1

이 AgentCore 도구를 사용하여 도구를 검색하려면 게이트웨이의 MCP 엔드포인트에 tools/call 메서드를 사용하여 다음 POST 요청을 수행합니다.

예

참고

게이트웨이는 protocolConfiguration.mcp 구성의 supportedVersions 필드에 나열된 MCP 프로토콜 버전만 허용합니다. 버전를 사용하려면 게이트웨이에 버전이 supportedVersions 포함되어 있는지 2026-07-28확인합니다. UpdateGateway API를 사용하여 지원되는 버전을 변경할 수 있습니다.

다음 값을 교체합니다.

${GatewayEndpoint} - CreateGateway API의 응답에 제공된 게이트웨이의 URL입니다.
${Authorization header} - 인바운드 권한 부여를 설정할 때 자격 증명 공급자의 권한 부여 자격 증명입니다.
${McpProtocolVersion} -와 같은 요청에 대한 MCP 프로토콜 버전입니다2025-11-25. 버전은 게이트웨이가 지원하는 버전이어야 합니다.
${RequestName} - 요청의 이름입니다.
${Query} - 도구를 검색하기 위한 자연어 쿼리입니다.

응답은 쿼리와 관련된 도구 목록을 반환합니다.

도구 검색을 위한 코드 샘플

자연어 쿼리를 사용하여 게이트웨이에서 도구를 찾는 예를 보려면 다음 방법 중 하나를 선택합니다.

예

Python requests package (2025-11-25 and earlier)

MCP-Protocol-Version 헤더를 게이트웨이가 지원하는 버전으로 설정합니다.


import requests
import json

def search_tools(gateway_url, access_token, query):
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}",
        "MCP-Protocol-Version": "2025-11-25"
    }

    payload = {
        "jsonrpc": "2.0",
        "id": "search-tools-request",
        "method": "tools/call",
        "params": {
            "name": "x_amz_bedrock_agentcore_search",
            "arguments": {
                "query": query
            }
        }
    }

    response = requests.post(gateway_url, headers=headers, json=payload)
    return response.json()

# Example usage
gateway_url = "https://${GatewayEndpoint}/mcp" # Replace with your actual gateway endpoint
access_token = "${AccessToken}" # Replace with your actual access token
results = search_tools(gateway_url, access_token, "find order information")
print(json.dumps(results, indent=2))

Python requests package (2026-07-28)

버전 에서는 본문에 Mcp-Method 및 Mcp-Name 요청 메타데이터 헤더와 _meta 버전 필드를 2026-07-28포함합니다. MCP-Protocol-Version 헤더는와 일치해야 합니다_meta.io.modelcontextprotocol/protocolVersion. 게이트웨이의 에는가 포함되어야 supportedVersions 합니다2026-07-28.


import requests
import json

def search_tools(gateway_url, access_token, query):
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}",
        "MCP-Protocol-Version": "2026-07-28",
        "Mcp-Method": "tools/call",
        "Mcp-Name": "x_amz_bedrock_agentcore_search"
    }

    payload = {
        "jsonrpc": "2.0",
        "id": "search-tools-request",
        "method": "tools/call",
        "params": {
            "name": "x_amz_bedrock_agentcore_search",
            "arguments": {
                "query": query
            },
            "_meta": {
                "io.modelcontextprotocol/protocolVersion": "2026-07-28",
                "io.modelcontextprotocol/clientInfo": {"name": "my-agent", "version": "1.0.0"},
                "io.modelcontextprotocol/clientCapabilities": {}
            }
        }
    }

    response = requests.post(gateway_url, headers=headers, json=payload)
    return response.json()

# Example usage
gateway_url = "https://${GatewayEndpoint}/mcp" # Replace with your actual gateway endpoint
access_token = "${AccessToken}" # Replace with your actual access token
results = search_tools(gateway_url, access_token, "find order information")
print(json.dumps(results, indent=2))

MCP Client


from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
import asyncio

async def execute_mcp(
    url,
    token,
    tool_params,
    headers=None
):
    default_headers = {
        "Authorization": f"Bearer {token}"
    }
    headers = {**default_headers, **(headers or {})}

    async with streamablehttp_client(
       url=url,
       headers=headers,
    ) as (
        read_stream,
        write_stream,
        callA,
    ):
        async with ClientSession(read_stream, write_stream) as session:
            # 1. Perform initialization handshake
            print("Initializing MCP...")
            _init_response = await session.initialize()
            print(f"MCP Server Initialize successful! - {_init_response}")

            # 2. Call specific tool
            print(f"Calling tool: {tool_params['name']}")
            tool_response = await session.call_tool(
                name=tool_params['name'],
                arguments=tool_params['arguments']
            )
            print(f"Tool response: {tool_response}")
            return tool_response

async def main():
    url = "https://${GatewayEndpoint}/mcp"
    token = "your_bearer_token_here"
    tool_params = {
        "name": "x_amz_bedrock_agentcore_search",
        "arguments": {
            "query": "How do I find order details?"
        }
    }
    await execute_mcp(
        url=url,
        token=token,
        tool_params=tool_params
    )


if __name__ == "__main__":
    asyncio.run(main())

Strands MCP Client


from strands.tools.mcp.mcp_client import MCPClient
from mcp.client.streamable_http import streamablehttp_client

def create_streamable_http_transport(mcp_url: str, access_token: str):
    return streamablehttp_client(mcp_url, headers={"Authorization": f"Bearer {access_token}"})

def get_full_tools_list(client):
    """
    List tools w/ support for pagination
    """
    more_tools = True
    tools = []
    pagination_token = None
    while more_tools:
        tmp_tools = client.list_tools_sync(pagination_token=pagination_token)
        tools.extend(tmp_tools)
        if tmp_tools.pagination_token is None:
            more_tools = False
        else:
            more_tools = True
            pagination_token = tmp_tools.pagination_token
    return tools

def run_agent(mcp_url: str, access_token: str):
    mcp_client = MCPClient(lambda: create_streamable_http_transport(mcp_url, access_token))

    with mcp_client:
        tools = get_full_tools_list(mcp_client)
        print(f"Found the following tools: {[tool.tool_name for tool in tools]}")
        result = mcp_client.call_tool_sync(
            tool_use_id="tool-123",  # A unique ID for the tool call
            name="x_amz_bedrock_agentcore_search",  # The name of the tool to invoke
            arguments={"query": "find order information"}  # A dictionary of arguments for the tool
        )
        print(result)

url = {gatewayUrl}
token = {AccessToken}
run_agent(url, token)

LangGraph MCP Client


import asyncio

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

url = ""
headers = {}

def filter_search_tool(
):
    mcp_client = MultiServerMCPClient(
        {
            "agent": {
                "transport": "streamable_http",
                "url": url,
                "headers": headers,
            }
        }
    )
    tools = asyncio.run(mcp_client.get_tools())
    builtin_search_tool = []
    for tool in tools:
        if tool.name == "x_amz_bedrock_agentcore_search":
            builtin_search_tool.append(tool)
    return builtin_search_tool

def execute_agent(
    user_prompt,
    model_id,
    region,
    tools
):
    model = ChatBedrock(model_id=model_id, region_name=region)

    agent = create_react_agent(model, filter_search_tool())
    _response = asyncio.run(agent.ainvoke({
        "messages": user_prompt
    }))

    _response = _response.get('messages', {})[1].content
    print(
        f"Invoke Langchain Agents Response"
        f"Response - \n{_response}\n"
    )
    return _response

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

샘플링

에이전트 연결