Notes pratiques : Recherche sémantique parmi les outils MCP grâce à Amazon Bedrock AgentCore

Ce guide reconstruit le parcours allant des matières premières à un système fonctionnel pour : la recherche sémantique entre les outils MCP via Amazon Bedrock AgentCore Gateway. L’accent est mis sur des étapes opérationnelles, des vérifications explicites, ainsi que du code que vous pouvez intégrer directement dans un dépôt sans devoir deviner l’intention. Pour une vue d’ensemble, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans avoir à deviner l’état caché. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Nommez les artefacts, définissez des vérifications de succès, et refusez toute complétion partielle silencieuse.

Ce que vous construisez

Lorsque vous travaillez sur « What you build », notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût en tokens ou en requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés. Journalisez le nom outil, l’hash des arguments, la latence et le résultat de chaque appel. Sans ce suivi, les boucles d’analyse des erreurs perdent des heures précieuses.

Pourquoi une recherche sémantique du côté du Gateway

Lorsque vous travaillez sur le sujet de la recherche sémantique du côté Gateway, notez d’abord les exigences : entrées requises, signal de succès et comportement en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les administrateurs peuvent auditer sans devoir lire l’ensemble du système. Enregistrez le nom outil, le hash des arguments, la latence et le résultat de chaque appel. Sans ces traces, le débogage des boucles d’agent prend des heures inutilement.

Prérequis

Lors de l’étude des Prérequis, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non traités font partie intégrante du produit, et non d’améliorations ultérieures. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans cette trace, les boucles d’analyse débogage gaspillent des heures. Lors de l’étude des Prérequis, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès et refusez les terminations partielles silencieuses.

Exécuter une recherche sémantique

Mettre en œuvre une recherche sémantique donne de meilleurs résultats lorsqu’elle est considérée comme un ensemble mesurable. Capturez un exemple réussi, un cas d’échec ainsi que la note de réversion avant d’élargir le champ d’application. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le système passe d’un environnement de démonstration à des environnements partagés. Fournissez des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les administrateurs doivent savoir quels appels modifient l’état du système avant d’approuver automatiquement ces requêtes.

Étape 1 : Interroger l’outil de recherche

Étape 1 : Il est préférable de considérer l’outil de recherche comme une surface mesurable pour effectuer des requêtes. Recueillez un exemple réussi, un cas d’échec ainsi que la note de réversion avant d’élargir le champ d’application. Conservez les paramètres de configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les administrateurs peuvent auditer sans devoir lire l’ensemble du système. Exposez des outils dotés de schémas restreints et de labels indiquant clairement leurs effets secondaires. Les hôtes doivent savoir quels appels modifient l’état du système avant de les valider automatiquement.

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)

Étape 2 : Utilisez les résultats pour filtrer la liste des outils

Étape 2 : Utilisez les résultats pour filtrer la liste d’outils. Cela fonctionne le mieux lorsque cela est traité comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Documentez ensemble le parcours réussi et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie du produit, et non d’une mise en forme ultérieure. Exposez les outils ayant des schémas restreints et des étiquettes explicites indiquant leurs effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant de valider automatiquement.

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]

Étape 3 : L’intégrer dans un agent Strands

Étape 3 : L’intégrer dans un agent Strands fonctionne le mieux lorsque cela est traité comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’échec doit pointer vers une seule responsabilité plutôt que vers un processus embrouillé.

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)

Ajustement de la recherche

Référence

Ce qui vient ensuite

Liste de contrôle opérationnelle