AI agent architektúra — a lokális agenttől az AWS Bedrock AgentCore platformig
Bevezetés
Ez a design dokumentum egy AI agent megoldás architekturális érési útját mutatja be két, egymásra épülő referencia-modellen keresztül. Az első egy lokális / on-premise futtatókörnyezet, amely egyetlen Docker hoston, minimális üzemeltetési teherrel ad működő agentet — ideális PoC-hez és belső, adat-szuverén kísérletekhez. A második egy teljesen menedzselt, szervermentes AWS Bedrock AgentCore architektúra, amely ugyanazt az agent-logikát identitás-, memória-, gateway- és observability-rétegekkel, vállalati szintű skálázhatósággal és izolációval egészíti ki.
A két modell nem egymás alternatívája, hanem egyetlen migrációs ív két végpontja. A lokális modell komponensei egy az egyben leképezhetők az AgentCore menedzselt szolgáltatásaira; a dokumentum végén ezt a megfeleltetést külön összegezzük. A leírás mindkét fejezetben a mellékelt architektúra-rajzokat követi.
1. Lokális agent egyetlen Docker hoston
A legegyszerűbb produktív elrendezésben az agent egyetlen Docker hoston fut, amely lehet a vállalati adatközpontban vagy egy dedikált VPC-ben. A futtató konténer maga az alkalmazás, amely egyszerre tölti be az MCP kliens és az agent szerepét: fogadja a triggert, megtervezi a lépéseket, hív eszközöket és vezényli az LLM-mel folytatott párbeszédet.
A folyamat egy felhasználói vagy belső eseménnyel indul (a rajzon szaggatott „trigger" nyíl). Ez lehet egy beérkező ticket, egy ütemezett job vagy egy API-hívás. Az agent ezután a kék hívási útvonalon (request/response) kommunikál az LLM API-val, amely mögött a tényleges nyelvi modell (LLM) áll. Ez az API lehet:
- saját modell-serving runtime
- privát Amazon Bedrock endpoint
- hálózati határon belül elérhető modellszolgáltatás
Az első opció a gyakorlatban azt jelenti, hogy ugyanazon a Docker hoston (vagy egy szomszédos konténerben) futtatsz egy model-serving runtime-ot, ami kiteszi az „LLM API" végpontot:
- Ollama — a legegyszerűbb,
ollama/ollamaimage, OpenAI-kompatibilis/v1végpont, GGUF modellek (Llama, Mistral, Qwen, stb.). - vLLM — nagy átbocsátású, produkciós kiszolgáló, OpenAI-kompatibilis API, jellemzően GPU-val.
- llama.cpp server / LM Studio / Text Generation Inference (TGI) — további alternatívák.
Ezzel a megoldással a modell-inferencia is a vállalati határon belül marad, vagyis egyetlen token sem hagyja el a hostot — ami pont a lokális/on-prem modell fő erőssége (adat-szuverenitás). Architekt szempontból egy dolgot érdemes kiemelni: ekkor a futtató host erőforrásigénye megnő (GPU/VRAM vagy erős CPU + RAM a modell méretétől függően), tehát a sizing és a skálázás kérdése a model-serving konténerre is kiterjed.
1.1 Eszközelérés három csatornán
Az agent háromféleképpen ér el képességeket, és ez a háromosztatúság a minta lényege:
- Lokális függvényhívások — közvetlen, alacsony késleltetésű kódhívások a konténeren belül (validáció, számítás, determinisztikus üzleti logika), amelyek nem igényelnek külön protokollt.
- Lokális MCP szerver — a Model Context Protocol-on keresztül elérhető, hoston belüli eszközszerver, amely például az adatbázist kérdezi le (a rajzon „query"). Így az adatelérés szabványos, auditálható eszköz-interfész mögé kerül, nem szóródik szét az agent kódjában.
- Távoli MCP szerver — a hoston kívüli, de szintén MCP-vel integrált eszközszerver, amely külső API-kat hív (a rajzon „fetch"). Ez a kontrollált kijárat a külvilág felé.
1.2 Architekturális olvasat
A diagram két vonaltípussal kódolja a felelősségeket: a folytonos kék a tényleges kérés/válasz hívásfolyam (agent ↔ LLM, agent → eszközök), a szaggatott szürke pedig a triggert és a továbbgyűrűző (downstream) adathozzáférést jelöli. Ez a megkülönböztetés architekt szemmel azért fontos, mert élesen elválasztja a vezérlési és az adat-/mellékhatás útvonalakat — a biztonsági kontrollokat (egress szabályok, secret-kezelés, naplózás) ezek mentén kell elhelyezni.
1.3 Mikor elég ez a modell?
A lokális Docker-agent erőssége az egyszerűség, az adat-szuverenitás és a költséghatékonyság: az egyetlen hálózati kijárat az LLM API és a távoli MCP szerver felé mutat, minden más a határon belül marad. Ideális PoC-hez, belső automatizációhoz és szabályozott (GDPR/NIS2) környezetben végzett kísérletekhez. Korlátai ugyanakkor hamar előjönnek éles, többfelhasználós terhelésnél: nincs beépített identitás- és jogosultságkezelés a felhasználó nevében, nincs perzisztens, megosztott memória, nincs horizontális skálázás és session-izoláció, és az observability is ad-hoc. Pontosan ezek a hiányosságok indokolják az elmozdulást egy menedzselt agent-platform felé.
2. Menedzselt agent platform: AWS Bedrock AgentCore
Az AWS Bedrock AgentCore ugyanazt az agent-mintát viszi tovább, de a futtatást és a körülötte lévő keresztmetszeti (cross-cutting) képességeket menedzselt, szervermentes building blockokká bontja. A rajz közepén az AgentCore Runtime áll a Host Agenttel; körülötte koncentrikusan helyezkednek el az identitás, a memória, a gateway, az eszközök és az observability rétegei. Az agent továbbra is MCP-kliensként viselkedik, de minden képesség mögött immár egy-egy menedzselt AWS szolgáltatás van.
2.1 AgentCore Runtime — a futtatómag
A Runtime adja a serverless végrehajtási környezetet: session-izoláció,
gyors hidegindítás, hosszú (akár 8 órás) futásidő és nagy csomagméret (~250 MB). A Host
Agent kap egy system promptot, és közvetlenül használja a Bedrock tools
képességeit — prompt management, Guardrails (felelős AI: tartalomszűrés,
tiltott témák, PII-maszkolás) és RAG. A Runtime endpoint
(bedrock-agent-runtime) az invokáció belépési pontja. Az agent maga az SDK-k egyikével készül —
Strands, LangGraph vagy CrewAI —, így a meglévő agent-kód
hordozható marad.
2.2 AgentCore Identity — zero-trust az agent körül
Az Identity réteg a platform biztonsági gerince. Bejövő oldalon (Inbound Auth) az Amazon Cognito / külső Identity Provider hitelesíti a felhasználót, kimenő oldalon (Outbound Auth) az agent OAuth2 authorizer és credential store segítségével szerez hozzáférést a célrendszerekhez. A modell elvei: Zero Trust, secure token vault, token caching és workload identity. Kulcs eleme a Workload Access Token: egy AWS-aláírt token, amely az agentet a felhasználó nevében hatalmazza fel, hordozva az agent- és user-identitást a hozzá tartozó scope-okkal és jogosultságokkal. Ez oldja meg azt, amit a lokális modell nem tudott: a delegált, auditálható hozzáférést.
2.3 AgentCore Memory — rövid és hosszú távú emlékezet
A Memory szolgáltatás titkosított, perzisztens tárolást ad rövid és hosszú távú kontextushoz. Támogatja a branchinget többágenses használathoz, valamint stratégiák és namespace-ek szerint különíti el a preferenciákat, a tényeket és az összefoglalókat. Ez a réteg váltja ki a lokális modell állapot-nélküliségét: az agent a futások között is „emlékszik", és a memória megosztható a sub-agentek között.
2.4 AgentCore Gateway — bármilyen API MCP-eszközzé alakítása
A Gateway a platform integrációs motorja: egy szervermentes MCP szerver,
amely a heterogén backendeket egységes MCP eszköz-felületté alakítja. Funkciói: tool listing,
szemantikus keresés, tool-kiválasztás, tool-hívás és
streamelhető HTTP. A célrendszerek (targets) háromfélék lehetnek:
Smithy, OpenAPI és AWS Lambda; hitelesítésük
IAM vagy API key / token alapú. Az eszközök elnevezése a
{target_name}__{tool_name} mintát követi, a Gateway pedig egy stabil URL-en
(https://{gateway_ID}.gateway.{region}.amazonaws.com/mcp) szolgálja ki a klienst. Ez a réteg a
lokális modell „lokális + távoli MCP szerver" párosának menedzselt, sokszorosan skálázható megfelelője.
2.5 AgentCore Tools és Sub-Agents
A Tools blokk a beépített, magasabb szintű képességeket fogja össze. A Sub-Agents orchesztrált al-agenteket tesz lehetővé (feladatfelosztás), a Custom tools egyedi vagy akár LLM által generált kódot futtat, a Code Interpreter izolált kódvégrehajtást, a Browser pedig felületi adatgyűjtést és űrlapkitöltést ad. Megjelennek olyan üzleti building blockok is, mint az Evaluation és a Payments.
2.6 Observability — átláthatóság és költségkontroll
Az Observability réteg Amazon CloudWatch metrikákra és OpenTelemetry nyomkövetésre épül, kiegészülve a Cost Explorer és a Security Hub nézeteivel. Ez adja az éles üzemhez nélkülözhetetlen end-to-end láthatóságot, a token-szintű költségbontást és a megfelelőségi állapotot — szintén olyasmi, amit a lokális modell csak ad-hoc módon tudott nyújtani.
2.7 Deployment pipeline és A2A
A telepítési lánc szabványos és reprodukálható: az agent kód (Strands / LangGraph / CrewAI SDK) Docker image-be kerül, onnan az Amazon ECR registrybe, és a CodeBuild építi/csomagolja a Runtime számára. A platform a több-agentes együttműködést is támogatja: az A2A (Agent-to-Agent) interfész egy másik agenttel (Agent 2) köt össze, discovery, feladatátadás (JSON), kontextus-megosztás és válasz mintákkal. A külső External Targets / Tools a Gateway targeteken keresztül, IAM vagy token alapú hitelesítéssel csatlakoznak.
3. A két modell megfeleltetése (migrációs ív)
A lokális Docker-agent nem zsákutca, hanem az AgentCore architektúra kicsinyített előképe. Az alábbi megfeleltetés mutatja, hogyan emelhető át minden komponens menedzselt szolgáltatásba — jellemzően az agent-logika (SDK) érintetlenül hagyásával:
| Lokális / on-prem modell | AWS Bedrock AgentCore megfelelő |
|---|---|
| Docker host (agent runner) | AgentCore Runtime (serverless, session-izoláció) |
| Application (MCP client / agent) | Host Agent + Bedrock tools (Strands / LangGraph / CrewAI) |
| Lokális függvényhívások | Custom tools / Code Interpreter |
| Lokális MCP szerver + Database | AgentCore Gateway target + AgentCore Memory / Storage |
| Távoli MCP szerver + Remote API-k | Gateway targets (OpenAPI / Smithy / Lambda) + Outbound Auth |
| LLM API → LLM | Bedrock Runtime endpoint + Foundation Models + Guardrails |
| (nincs) | AgentCore Identity — Workload Access Token, zero-trust |
| (ad-hoc naplózás) | Observability — CloudWatch, OpenTelemetry, Security Hub |
4. Architektúra-döntések és ajánlás
- Indulás: PoC és belső validáció lokális Docker-agenttel — gyors, olcsó, adat-szuverén.
- Skálázás: többfelhasználós, delegált hozzáférést igénylő éles terhelésnél váltás AgentCore-ra, az Identity és Memory rétegek miatt.
- Biztonság: a zero-trust, a Workload Access Token és a Guardrails együtt adják a vállalati (GDPR / NIS2) megfelelőséget.
- Integráció: a Gateway révén minden meglévő API (OpenAPI / Smithy / Lambda) egységes MCP eszközzé válik, hitelesítve.
- Üzemeltetés: reprodukálható Docker → ECR → CodeBuild pipeline, end-to-end observability és token-szintű költségkontroll.
Összegezve: a lokális modell a belépési pont, az AgentCore pedig az érett, skálázható célállapot. Mivel a két architektúra komponensei egy az egyben megfeleltethetők, a migráció kockázata alacsony, az agent-logika pedig végig hordozható marad.
Introduction
This design document presents the architectural maturity path of an AI agent solution through two reference models that build on each other. The first is a local / on-premise runtime that delivers a working agent on a single Docker host with minimal operational overhead — ideal for a PoC and for internal, data-sovereign experiments. The second is a fully managed, serverless AWS Bedrock AgentCore architecture that extends the same agent logic with identity, memory, gateway and observability layers, enterprise-grade scalability and isolation.
The two models are not alternatives but two endpoints of a single migration arc. The components of the local model map one-to-one onto AgentCore's managed services; we summarise this mapping at the end of the document. Both chapters follow the attached architecture diagrams.
1. A local agent on a single Docker host
In the simplest production layout the agent runs on a single Docker host, located either in the corporate data centre or in a dedicated VPC. The running container is the application itself, playing both the MCP client and agent roles: it receives the trigger, plans the steps, calls tools and orchestrates the conversation with the LLM.
The flow starts with a user or internal event (the dashed "trigger" arrow). This may be an incoming ticket, a scheduled job or an API call. The agent then communicates with the LLM API over the blue call path (request/response); behind the API sits the actual language model (LLM). This API can be:
- a self-hosted model-serving runtime
- a private Amazon Bedrock endpoint
- any model service reachable inside the network boundary
The first option in practice means running a model-serving runtime on the same Docker host (or in an adjacent container) that exposes the "LLM API" endpoint:
- Ollama — the simplest option,
ollama/ollamaimage, OpenAI-compatible/v1endpoint, GGUF models (Llama, Mistral, Qwen, etc.). - vLLM — high-throughput production serving, OpenAI-compatible API, typically with GPU.
- llama.cpp server / LM Studio / Text Generation Inference (TGI) — further alternatives.
With this approach model inference also stays inside the corporate boundary — no token leaves the host — which is the main strength of the local/on-prem model (data sovereignty). From an architect's perspective, one point matters: the host's resource requirements increase (GPU/VRAM or strong CPU + RAM depending on model size), so sizing and scaling must cover the model-serving container as well.
1.1 Tool access over three channels
The agent reaches capabilities in three ways, and this triad is the essence of the pattern:
- Local function calls — direct, low-latency code calls inside the container (validation, computation, deterministic business logic) that need no separate protocol.
- Local MCP server — an in-host tool server exposed over the Model Context Protocol, e.g. querying the database ("query" on the diagram). Data access thus sits behind a standard, auditable tool interface instead of being scattered across the agent code.
- Remote MCP server — an MCP-integrated tool server outside the host that calls remote APIs ("fetch"). This is the controlled exit toward the outside world.
1.2 Architectural reading
The diagram encodes responsibilities with two line types: solid blue is the actual request/response call flow (agent ↔ LLM, agent → tools), while dashed grey denotes the trigger and downstream data access. This distinction matters to an architect because it cleanly separates the control path from the data / side-effect path — security controls (egress rules, secret handling, logging) should be placed along these lines.
1.3 When is this model enough?
The local Docker agent's strength is simplicity, data sovereignty and cost efficiency: the only network exit points to the LLM API and the remote MCP server, everything else stays within the boundary. It is ideal for a PoC, internal automation and experiments in regulated (GDPR/NIS2) environments. Its limits, however, surface quickly under real, multi-user load: no built-in identity and authorization on behalf of the user, no persistent shared memory, no horizontal scaling and session isolation, and ad-hoc observability. These very gaps justify the move toward a managed agent platform.
2. Managed agent platform: AWS Bedrock AgentCore
AWS Bedrock AgentCore carries the same agent pattern forward but decomposes the runtime and the surrounding cross-cutting capabilities into managed, serverless building blocks. At the centre of the diagram sits the AgentCore Runtime with the Host Agent; around it are the concentric layers of identity, memory, gateway, tools and observability. The agent still behaves as an MCP client, but every capability is now backed by a managed AWS service.
2.1 AgentCore Runtime — the execution core
The Runtime provides the serverless execution environment: session isolation,
fast cold start, long (up to 8-hour) run time and a large package size (~250 MB). The Host
Agent receives a system prompt and directly uses the Bedrock tools —
prompt management, Guardrails (responsible AI: content filtering, denied
topics, PII masking) and RAG. The Runtime endpoint
(bedrock-agent-runtime) is the invocation entry point. The agent itself is built with one of the
SDKs — Strands, LangGraph or CrewAI — keeping existing agent
code portable.
2.2 AgentCore Identity — zero-trust around the agent
The Identity layer is the platform's security backbone. On the inbound side (Inbound Auth), Amazon Cognito / an external Identity Provider authenticates the user; on the outbound side (Outbound Auth) the agent obtains access to target systems via an OAuth2 authorizer and credential store. The model's principles: Zero Trust, secure token vault, token caching and workload identity. Its key element is the Workload Access Token: an AWS-signed token that authorises the agent on behalf of the user, carrying both agent and user identity with the associated scopes and permissions. This solves what the local model could not: delegated, auditable access.
2.3 AgentCore Memory — short- and long-term memory
The Memory service provides encrypted, persistent storage for short- and long-term context. It supports branching for multi-agent use and separates preferences, facts and summaries by strategy and namespace. This layer removes the statelessness of the local model: the agent "remembers" across runs and the memory can be shared among sub-agents.
2.4 AgentCore Gateway — turning any API into an MCP tool
The Gateway is the platform's integration engine: a serverless MCP server that
turns heterogeneous backends into a uniform MCP tool surface. Its functions: tool listing,
semantic search, tool selection, tool invocation and
streamable HTTP. Targets can be of three kinds: Smithy,
OpenAPI and AWS Lambda; authenticated via IAM or
API key / token. Tools are named following the {target_name}__{tool_name} pattern,
and the Gateway serves clients on a stable URL
(https://{gateway_ID}.gateway.{region}.amazonaws.com/mcp). This layer is the managed,
highly scalable equivalent of the local model's "local + remote MCP server" pair.
2.5 AgentCore Tools and Sub-Agents
The Tools block bundles the built-in, higher-level capabilities. Sub-Agents enable orchestrated child agents (task decomposition), Custom tools run bespoke or even LLM-generated code, the Code Interpreter offers isolated code execution, and the Browser provides UI data gathering and form filling. Business building blocks such as Evaluation and Payments also appear.
2.6 Observability — transparency and cost control
The Observability layer is built on Amazon CloudWatch metrics and OpenTelemetry tracing, complemented by Cost Explorer and Security Hub views. This delivers the end-to-end visibility, token-level cost breakdown and compliance posture indispensable for production — again something the local model could only offer ad hoc.
2.7 Deployment pipeline and A2A
The deployment chain is standard and reproducible: the agent code (Strands / LangGraph / CrewAI SDK) is packaged into a Docker image, pushed to Amazon ECR, and CodeBuild builds/packages it for the Runtime. The platform also supports multi-agent collaboration: the A2A (Agent-to-Agent) interface connects to another agent (Agent 2) with discovery, task handover (JSON), context sharing and reply patterns. External External Targets / Tools connect through Gateway targets with IAM or token-based authentication.
3. Mapping the two models (the migration arc)
The local Docker agent is not a dead end but a scaled-down preview of the AgentCore architecture. The mapping below shows how every component can be lifted into a managed service — typically leaving the agent logic (SDK) untouched:
| Local / on-prem model | AWS Bedrock AgentCore equivalent |
|---|---|
| Docker host (agent runner) | AgentCore Runtime (serverless, session isolation) |
| Application (MCP client / agent) | Host Agent + Bedrock tools (Strands / LangGraph / CrewAI) |
| Local function calls | Custom tools / Code Interpreter |
| Local MCP server + Database | AgentCore Gateway target + AgentCore Memory / Storage |
| Remote MCP server + Remote APIs | Gateway targets (OpenAPI / Smithy / Lambda) + Outbound Auth |
| LLM API → LLM | Bedrock Runtime endpoint + Foundation Models + Guardrails |
| (none) | AgentCore Identity — Workload Access Token, zero-trust |
| (ad-hoc logging) | Observability — CloudWatch, OpenTelemetry, Security Hub |
4. Architecture decisions and recommendation
- Start: PoC and internal validation with a local Docker agent — fast, cheap, data-sovereign.
- Scale: move to AgentCore for multi-user, delegated-access production load, for the Identity and Memory layers.
- Security: zero-trust, the Workload Access Token and Guardrails together provide enterprise (GDPR / NIS2) compliance.
- Integration: via the Gateway, every existing API (OpenAPI / Smithy / Lambda) becomes a uniform, authenticated MCP tool.
- Operations: reproducible Docker → ECR → CodeBuild pipeline, end-to-end observability and token-level cost control.
In summary: the local model is the entry point, AgentCore is the mature, scalable target state. Because the components of the two architectures map one-to-one, migration risk is low and the agent logic stays portable throughout.