Praktyczne zastosowanie Bedrock AgentCore: Terraform, LangGraph i stwierdzone pułapki

Zorganizowanie hostingu agenta AI na AWS ręcznie oznacza konieczność samodzielnego rozwiązania problemów z izolacją sesji, dostępem do narzędzi, pamięcią oraz autoryzacją. Amazon Bedrock AgentCore to zarządzana wersja tego samego rozwiązania, dostępna od października 2025 roku. Praktycznym sposobem na ocenę takiej platformy jest przestanie czytania o niej i stworzenie czegoś rzeczywistego – mały agent triażowy typu read-only do zadań DevOps spełniał w tym przypadku tę funkcję. Został zaimplementowany za pomocą Terraform zamiast wbudowanego w AWS interfejsu CLI, a napisany został przy użyciu LangGraph zamiast SDK Strands od AWS. Oba te wybory były celowe, ponieważ chodziło o to, aby dowiedzieć się, co działa w warunkach poza utartymi ścieżkami.

Czym jest AgentCore

AgentCore to zbiór zarządzanych komponentów, które obejmują nudne, kluczowe aspekty działania agenta w środowisku produkcyjnym, a także umożliwiają zachowanie istniejących frameworki agentów. Główną obietnicą jest kompatybilność z dowolnym frameworkiem, co w większości przypadków się sprawdza. Akceptowane są LangGraph, LangChain, CrewAI, Strands oraz zwykłe wywołania API.

Komponenty i ich funkcje:

• Runtime przechowuje kod agenta i zapewnia każdej sesji oddzielną mikroVM. Przy braku aktywności skaluje się do zera, a opłaty naliczane są sekundowo podczas pracy.
• Gateway przekształca istniejące funkcje Lambda lub API w narzędzia kompatybilne z MCP, które agent może wywoływać, dzięki czemu nie jest potrzebny ręcznie napisany serwer MCP.
• Memory przechowuje historię rozmów jako krótkoterminowe zdarzenia i opcjonalnie może wydobywać długoterminową wiedzę semantyczną pomiędzy sesjami.

Tożsamość obejmuje dwa kierunki autoryzacji: kto może dzwonić do agenta oraz co agent może robić w imieniu użytkownika, w tym korzystać z usług third-party takich jak Slack czy GitHub.

Możliwość obserwacji polega na wysyłaniu śladów OpenTelemetry do CloudWatch, dzięki czemu istnieje zapis tego, co agent wykonał i dlaczego.

Narzędzie przeglądarki oraz narzędzie interpretatora kodu służą agentom, które muszą działać w otwartej sieci lub uruchamiać dowolny kod.

Ogłoszenie z AWS Summit z czerwca 2026 roku wprowadziło warstwę Harness oraz wbudowaną wyszukiwarkę internetową. Obie są jeszcze na tak wczesnym etapie, że infrastruktura krytyczna nie powinna na nich jeszcze polegać.

Proces wdrożenia został już raz przebudowany. Oryginalne narzędzie Starter Toolkit CLI jest obecnie przestarzałe i zastąpione pakietem npm opartym na CDK o nazwie @aws/agentcore. Tutorial pokazujący konfigurację oraz uruchomienie agentcore jako odrębne kroki opisuje stary proces. Ten szczegół jest ważny, ponieważ wskazuje na tempo zmian: dziewięć miesięcy po ogólnej dostępności ścieżka rozpoczęcia pracy została już ponownie opracowana, więc wszystko, co zostało napisane o tym produkcie, ma określony czas ważności.

Projekt testowy

Agent odpowiada na pytania takie jak to, czy aktywne są jakiekolwiek alarmy CloudWatch, lub jaki jest stan określonej instancji EC2. Posiada dwa rzeczywiste, tylko do odczytu narzędzia, więc nic z tego, co może być użyte, nie jest w stanie zmieniać infrastruktury – jedynie ją obserwować. Pamięta rozmowę z poprzednich kroków, a każdy przejście między komponentami jest uwierzytelniane.

Wybrano LangGraph zamiast Strands, ponieważ Strands to własna platforma AWS i umożliwia najłatwiejsze przeprowadzenie każdego oficjalnego przykładu. Użycie czegoś innego stanowiło prawdziwą próbę twierdzenia o uniwersalności frameworków, a wybrany narzędzie pasowało do już dostępnych rozwiązań. Z podobnego powodu wybrano Terraform zamiast interfejsu CLI – asystent służy do szybkiego uruchomienia demonstracji, a celem było zobaczenie każdej relacji zaufania IAM oraz każdego połączenia między komponentami, a nie ich niewidzialne generowanie. Ta widoczność okazała się ważniejsza, niż się spodziewano.

Architektura opiera się na kontenerze Runtime uruchamiającym agenta LangGraph, który komunikuje się z bramką Gateway udostępniającą dwa narzędzia oparte na Lambda przez protokół MCP. AgentCore Memory przechowuje treść rozmowy, a Cognito wydaje tokeny typu machine-to-machine dla każdego kroku w procesie.

Kliknij, zanim napiszesz skrypt

Zanim napisano jakikolwiek kod Terraform, wersja konsolowa tego procesu została przetestowana raz, głównie po to, aby zobaczyć, co jest automatyzowane. Ten nawyk warto przyjąć, nawet gdy to Terraform zajmuje się faktyczną implementacją, ponieważ czytanie plików infrastruktury jest o wiele łatwiejsze po tym, jak już zobaczyło się formularze, które one wypełniają.

Rejestr kontenerów wymaga ręcznego przeprowadzenia procesu, niezależnie od narzędzia obsługującego resztę, ponieważ to jedyny krok, którego Terraform nie może wykonać. Tworzenie repozytorium odbywa się na jednym ekranie konsoli. Obraz musi jednak trafić w inny sposób, gdyż konsola nie posiada przycisku do tworzenia pliku Dockerfile. Dzieje się to w terminalu za pomocą polecenia docker buildx build dla platformy linux/arm64, a następnie następuje jego wysłanie. Kluczowe jest ręczne określenie platformy – jeśli tego nie zrobić, obraz zostanie utworzony bez problemów, ale potem zostanie cicho odrzucony podczas próby uruchomienia go przez Runtime, ponieważ ten działa wyłącznie na procesorach Graviton.

Gdy obraz zostanie dostarczony, konsola pokazuje jego dokładny URI. To właśnie ta wartość musi zostać przeniesiona z ręcznie wykonywanych działań do informacji znanych Terraformowi, czy to do pliku tfvars, czy do pola z obrazem kontenerowym w Runtime dla osób korzystających z konsoli.

Elementy AgentCore dotyczące pamięci, bramy i czasu wykonywania znajdują się w osobnych sekcjach konsoli Bedrock. Każdy z nich to formularz z tymi samymi polami, które ustawia Terraform, co ma sens, ponieważ Terraform korzysta z tej samej podstawowej API.

• W formularzu dotyczącym pamięci wymagane jest podanie nazwy oraz okresu przechowywania krótkoterminowych zdarzeń.
• Formularz bramy wymaga podania protokołu, roli wykonywania oraz metody autoryzacji osób dzwoniących. Problem związany z rozróżnieniem audience versus client-id w Cognito, opisany poniżej, pojawia się właśnie tutaj w postaci listy rozwijanej, która wymusza wybór.
• Formularz czasu wykonywania wymaga podania URI rejestru, roli oraz tej samej konfiguracji autoryzatora co w przypadku bramy.

Wszystko to nie stanowi trudności, gdy formularze są przed oczami. Terraform nadal pozostaje lepszym wyborem dla zadań, które mają trwać, ponieważ przechodzenie przez siedem formularzy w trzech sekcjach konsoli nie jest procesem implementacji, który ktokolwiek chciałby powtarzać lub przekazywać koleżeńsko.

Miejsce ukąszenia

Zdjęcia muszą być w formacie ARM64

Bieg aplikacji jest możliwy wyłącznie na platformie Graviton, bez żadnych wyjątków. Zwykłe tworzenie obrazu Docker na większości laptopów daje obraz w formacie amd64, który jest cicho odrzucany podczas implementacji. Każde tworzenie obrazu wymaga użycia polecenia buildx z flagą platformy arm64. Komentarz umieszczony bezpośrednio nad linijką FROM w pliku Dockerfile stanowi prosty mechanizm zabezpieczający, ponieważ w przeciwnym razie zostanie zapomniany.

Umowa Lambda Gateway

Kilka postów na blogu pokazuje zdarzenie Lambda umieszczone w „kopercie” zawierającej toolName oraz parametry. Rzeczywistym zdarzeniem są właściwości wejściowe narzędzia w postaci prostego słownika. Prawdziwa nazwa narzędzia pojawia się w elemencie context.client_context.custom pod kluczem bedrockAgentCoreToolName, poprzedzona nazwą celu bramy oraz delimitatorem w postaci trzech podkreśleń. Różnica ta ujawniła się dopiero po bezpośrednim przeczytaniu dokumentacji AWS dotyczącej celu Lambda, zamiast polegania na podsumowaniach pochodzących od innych źródeł. Duża część informacji krążących na temat tego produktu pochodzi z okresu przeglądowego lub jest po prostu błędna.

Tokeny Cognito nie zawierają pola aud

Trzeba było sporo czasu, aby to rozgryźć. Gdy używa się Cognito do autoryzacji między maszynami poprzez mechanizm client_credentials bez konieczności logowania przez człowieka, Cognito wydaje token dostępu, a nie token identyfikacyjny. Tokeny dostępu nigdy nie zawierają pola aud. Tylko tokeny identyfikacyjne je mają, a w przypadku przepływu M2M nie ma tokena identyfikacyjnego, ponieważ nie ma użytkownika, któremu można by go wydać. Należy skonfigurować autoryzator JWT w AgentCore tak, aby sprawdzał pole allowed_audience w takim tokenie – w rezultacie pojawia się błąd 403 bez oczywistego powodu. Rozwiązaniem jest użycie opcji allowed_clients, która sprawdza pole client_id, które rzeczywiście jest zawarte w tokenach dostępu Cognito.

boto3 nie może wywołać środowiska Runtime chronionego JWT

To było największe zaskoczenie – nie jest to rozwiązanie tymczasowe, lecz zdanie w własnym dokumencie referencyjnym API AWS. Jeśli agent używa autoryzacji przychodzącej w stylu OAuth, funkcja InvokeAgentRuntime w ogóle nie może być wywoływana za pośrednictwem AWS SDK. Zamiast tego jest to surowy żądanie HTTPS z tokenem nośnym w nagłówku Authorization, wysyłane do adresu URL stworzonego ręcznie, przy czym ARN środowiska jest percent-kodowane i włączane do ścieżki. Wszystkie przykłady z boto3 zakładają domyślną ścieżkę IAM i SigV4. Gdy tylko konfiguruje się custom_jwt_authorizer, co jest konieczne w przypadku wszystkiego, co nie jest wyłącznie wewnętrzne, cała ta kategoria przykładów przestaje być stosowalna.

Konflikt pakietów w Pythonie

Pakiet mcp w Pythonie wydał główną wersję 2.0.0, która zmienia nazwy wewnętrznych modułów, podczas gdy langchain-mcp-adapters nie nadążył za tymi zmianami. Deklaruje on zgodność z mcp wersji 1.24.0 lub nowszej, bez określenia górnego limitu, więc zwykłe polecenie pip install powoduje teraz nieprawidłowe połączenie. Przynajmniej powoduje to wyraźny błąd, w postaci błędu importu, a nie subtelnego problemu. Projekt testowy ustala wersję mcp na 1.29.0. Sprawdź, czy to ustalenie jest nadal konieczne, ponieważ ciche poprawki mogą przekształcić naprawę w zbędny bałagan.

Rozwój to coś więcej niż pojedyncze zastosowanie

Zasób Runtime wymaga obrazu kontenera już istniejącego w rejestrze, a Terraform nie może zbudować i wysłać obrazu w ramach własnego procesu apply. Prawidłowa sekwencja polega na stworzeniu jedynie repozytorium w rejestrze, zbudowaniu i wysłaniu obrazu poza Terraformem, a następnie zastosowaniu wszystkich pozostałych elementów. Inżynierowie pracujący z znacznie większymi stackami AgentCore integrowali CodeBuild z grafem Terraform za pomocą null_resource, aby zamknąć tę lukę. To rozsądny następny krok oraz oznaka tego, że ten problem jest powszechny, a nie błąd osobisty.

Stan rozmowy powinien znajdować się w jednym miejscu

To nie błąd, lecz decyzja strukturalna: agent celowo nie używa własnego checkpointera LangGraph do przechowywania stanu rozmowy, chociaż większość tutoriali LangGraph ustawia go jako domyślny. Sesje w czasie rzeczywistym mogą zostać zredukowane do zera i przekazać nową mikroVM pomiędzy wywołaniami, więc wszystko, co jest przechowywane tylko w pamięci procesu, znika. Pamięć AgentCore stanowi trwałą część tego rozwiązania. Uruchomienie lokalnego checkpointera obok Pamięci powoduje, że ta sama rozmowa ma dwa sprzeczne zapisy, które prędzej czy później będą się różnić co do tego, co zostało powiedziane. Należy wybrać jeden z nich. Pamięć jest rozsądnym wyborem, ponieważ przetrwa start z zimnego stanu.

Jakie to kosztuje

Ceny są ustalane według zużycia, bez minimalnej kwoty, co jest dobrym rozwiązaniem dla systemu, który większość czasu spędza w oczekiwaniu na odpowiedź LLM. Skutkiem tego jest fakt, że rachunek składa się z kilku małych pozycji pomiarowych, a nie z jednej liczby. Na chwilę pisania:

• Koszty działania wynoszą około 9 centów za każdą godzinę vCPU oraz około 1 centa za każdą godzinę GB, naliczane sekundowo z minimalną jednostką czasu wynoszącą jedną sekundę; więc pytanie trwające trzy sekundy kosztuje dokładnie trzy sekundy, a nie zaokrągloną do minuty kwotę.
• Koszt Gateway wynosi około pół centa za tysiąc wywołań MCP.
• Pamięć jest opłacana w wysokości 0,25 centa za 1000 przechowywanych zdarzeń oraz 0,5 centa za 1000 odzyskanych zdarzeń.
• Użycie tożsamości poprzez Runtime lub Gateway zamiast bezpośredniego wywołania nie wiąże się z żadnym kosztem, co dotyczy praktycznie całego układu.

W tym nie uwzględniono żadnych kosztów związanych z wywołaniami modeli, które przy czymkolwiek więcej niż tylko prostych testach stanowią największy element rachunku i na które AgentCore nie ma wpływu. To po prostu cena wybranego modelu ustalana przez Bedrock. Nowe konta otrzymują dwieście dolarów w kredytach AgentCore, co wystarcza na kilkukrotne stworzenie i zniszczenie takiego projektu. Przed przyjęciem jakichkolwiek danych należy sprawdzić oficjalną stronę z cenami, ponieważ ceny zmieniły się już kilkakrotnie od momentu ogólnej dostępności i prawdopodobnie zmienią się ponownie.

Platforma zarządzana czy samodzielne hostowanie

Konstrukcja agenta budowana ręcznie wraz z stosem hostingu stanowi przydatne porównanie, a uczciwy wniosek ma dwa aspekty. AgentCore zapewnia izolację sesji, zarządzany bramkarz MCP, trwałą pamięć oraz model autoryzacji, które są ze sobą połączone i działają skuteczniej niż ręczne projektowanie polityk zaufania IAM – właśnie nad tymi politykami spędzono tu wiele godzin. To ogromna ilość pracy związanej z infrastrukturą, która zostaje odciążona. Dla każdego, czy to osoby odpowiedzialnej za budowę agenta, czy też platformy hostingu pod nim, ta zamiana jest prawdopodobnie warta podejmowania decyzji.

To, czego platforma nie oferuje, to oceny dotyczące tego, co agent powinien mieć prawo robić, ile powinno to kosztować w rzeczywistych warunkach lub czy jakikolwiek framework oznacza automatycznie taki, który wykorzystuje najlepiej udokumentowaną metodę dostarczaną przez same AWS. Brakuje również stabilności. CLI zostało przebudowane raz, a wykryto co najmniej trzy przypadki, w których dokumentacja AWS różniła się od rzeczywistej API w drobnych, lecz istotnych aspektach. Nic z tego nie czyni produktu złym – po prostu opisuje młody usługę zarządzaną, która rozwija się szybko, a o której lepiej jest wiedzieć przed rozpoczęciem pracy, niż odkrywać jej zalety w trakcie implementacji.

Wszystko to zostało faktycznie zbudowane, a nie tylko opisane. Każdy zasób jest obsługiwany przez Terraform, agent jest kompletny, istnieją narzędzia Lambda, a zestaw testów nie wymaga uprawnień AWS – dlatego to, co można było zweryfikować, zostało sprawdzone najpierw. Przy podobnej konfiguracji najprawdopodobniej na te same problemy natrafi się przy użyciu flagi platformy ARM64 dla obrazu oraz parametru allowed_clients w konfiguracji autoryzatora Cognito.