Inicio / Artículos / Notas prácticas: Búsqueda semántica entre herramientas MCP con Amazon Bedrock AgentCore

agentsmcptoolssearchsemantic

Notas prácticas: Búsqueda semántica entre herramientas MCP con Amazon Bedrock AgentCore

Guía paso a paso práctica: Búsqueda semántica en herramientas MCP con Amazon Bedrock AgentCore: contratos, verificaciones y espacios para código listo para usar para los equipos que implementan este patrón.

903 palabras

Esta guía reconstruye el proceso desde las materias primas hasta un sistema funcional para: la búsqueda semántica en herramientas MCP mediante Amazon Bedrock AgentCore Gateway. El enfoque está en pasos operativos claros, verificaciones explícitas y código que se puede incorporar directamente a un repositorio sin necesidad de adivinar la intención. Para obtener una visión general, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y evite completaciones parciales silenciosas.

Qué se construye

Al trabajar en “What you build”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar bucles sin ese rastro desperdicia horas.

Por qué la búsqueda semántica en el lado del Gateway

Al trabajar en el tema de la búsqueda semántica del lado de Gateway, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestos los cambios posteriores en el código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar bucles de agentes sin ese registro desperdicia horas.

Requisitos previos

Al trabajar en los Requisitos previos, anote primero el contrato: las entradas necesarias, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente junto con ella el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar agentes en bucles sin esa huella desperdicia horas. Al trabajar en los Requisitos previos, anote primero el contrato: las entradas necesarias, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.

Ejecutar una búsqueda semántica

Ejecutar una búsqueda semántica funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo por token o consulta junto con los resultados funcionales. Tener visibilidad del costo desde temprano evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.

Paso 1: Consultar la herramienta de búsqueda

Paso 1: La consulta de la herramienta de búsqueda funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.

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

async with streamablehttp_client(gateway_url) as (r, w, _):
    async with ClientSession(r, w) as session:
        await session.initialize()        result = await session.call_tool(
            "x_amz_bedrock_agentcore_search",
            {"query": "find a customer by phone number"},
        )        for match in result.content:
            print(match.text)

Paso 2: Utilice los resultados para filtrar la lista de herramientas

Paso 2: Utilice los resultados para filtrar la lista de herramientas. Funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Exponga las herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.

async def smart_tool_selection(session, user_request: str, top_k: int = 5):
    search = await session.call_tool(
        "x_amz_bedrock_agentcore_search",
        {"query": user_request},
    )

    relevant_tool_names = [match.text for match in search.content[:top_k]]    all_tools = await session.list_tools()
    return [t for t in all_tools.tools if t.name in relevant_tool_names]

Paso 3: Conéctelo a un agente Strands

Paso 3: Conéctelo a un agente Strands funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado.

from strands import Agent
from strands.tools.mcp import MCPClient

async def run(user_message: str):
    async with MCPClient(gateway_url) as mcp:
        relevant_tools = await smart_tool_selection(mcp.session, user_message)        agent = Agent(
            model="anthropic.claude-opus-4-7-v1:0",
            tools=relevant_tools,
            system_prompt="Use only the provided tools to answer.",
        )
        return await agent.run_async(user_message)

Ajuste de la búsqueda

Referencia

Siguiente paso

Lista de verificación operativa

Lecturas relacionadas

Todos los artículosEnviar el brief