Strona główna / Artykuły / Wskazówki praktyczne: wyszukiwanie semantyczne w narzędziach MCP za pomocą Amazon Bedrock AgentCore

agentsmcptoolssearchsemantic

Wskazówki praktyczne: wyszukiwanie semantyczne w narzędziach MCP za pomocą Amazon Bedrock AgentCore

Krok po kroku instrukcja obsługi Notatek praktycznych: wyszukiwanie semantyczne w narzędziach MCP przy użyciu Amazon Bedrock AgentCore – umowy, sprawdzenia oraz gotowe miejsca na kod dla zespołów wdrażających ten wzorzec.

903 słów

To przewodnik pokazuje, jak stworzyć cały proces od surowców aż do działającego systemu umożliwiającego: semantyczne wyszukiwanie w narzędziach MCP przy użyciu Amazon Bedrock AgentCore Gateway. Główny nacisk kładziony jest na konkretne kroki operacyjne, jasne sprawdzenia oraz kod, który można bez problemu wdrożyć do repozytorium, bez konieczności domyślania się intencji. Aby uzyskać ogólny obraz, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności domyślania się ukrytego stanu. Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć przypadkowe, częściowe ukończenie zadania.

To, co tworzysz

Gdy pracujesz nad projektem „What you build”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zapisz czas wykonywania oraz koszt tokena lub zapytania obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z wersji demonstracyjnej do środowisk współdzielonych. Zapisz nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdego wywołania. Bez takich informacji debugowanie może trwać godzinami.

Dlaczego wyszukiwanie semantyczne po stronie Gateway

Gdy pracujesz nad tematem „Dlaczego semantyczne wyszukiwanie po stronie Gateway”, najpierw zapisz specyfikację: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny haseł oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdej wywołania. Bez takich informacji debugowanie pętli agenta trwa godzinami.

Wymagania wstępne

Gdy pracujesz nad warunkami wstępnymi, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez ludzi oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdej wywołania. Bez takich informacji debugowanie trwa godzinami. Gdy pracujesz nad warunkami wstępnymi, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzucaj ciche, częściowe ukończenie zadań.

Przeprowadź wyszukiwanie semantyczne

Zastosowanie wyszukiwania semantycznego daje najlepsze wyniki, gdy traktuje się je jako coś mierzalnego. Zanim rozszerzy się zakres, należy odnotować jeden idealny przypadek użycia, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań. Obok wyników funkcjonalnych należy zapisywać czas trwania operacji oraz koszt tokenów lub zapytań. Wczesna widoczność kosztów zapobiega nieoczekiwanym rachunkom, gdy przechodzi się z środowiska demonstracyjnego do współdzielonych środowisk. Należy udostępniać narzędzia o wąskich schematach oraz z wyraźnymi etykietami opisującymi efekty uboczne. Hostowie muszą wiedzieć, które wywołania zmieniają stan systemu, zanim je automatycznie zatwierdzą.

Krok 1: Zadanie zapytania w narzędziu wyszukiwania

Krok 1: Zapytania do narzędzia wyszukiwawczego działają najlepiej, gdy traktuje się je jako mierzalną powierzchnię. Zapisz jeden udany przypadek, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Używaj narzędzi o wąskich schematach i wyraźnych etykietach efektów ubocznych. Hostowie muszą wiedzieć, które wywołania zmieniają stan, zanim automatycznie je zatwierdzą.

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)

Krok 2: Wykorzystaj wyniki do filtrowania listy narzędzi

Krok 2: Użyj wyników do filtrowania listy narzędzi – najlepiej postępować z nią jak z mierzalną powierzchnią. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian przed rozszerzeniem zakresu. Zdokumentuj zarówno prawidłowy przebieg działania, jak i ścieżkę przywracania do stanu poprzedniego. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później. Ujawnij narzędzia o wąskich schematach i wyraźnych etykietach efektów ubocznych. Hostowie muszą wiedzieć, które wywołania zmieniają stan, zanim automatycznie je zatwierdzą.

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]

Krok 3: Połącz to z agentem Strands

Krok 3: Połącz to z agentem Strands – najlepiej postępować z tym jak z mierzalną powierzchnią. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian przed rozszerzeniem zakresu. Wolno preferować małe, testowalne jednostki nad rozbudowanymi skryptami. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji.

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)

Dostosowywanie wyszukiwania

Odnośniki

Następne kroki

Lista kontrolna operacyjna

Powiązane materiały

Wszystkie artykułyWyślij brief