How aws-samples/sample-strands-agent-with-agentcore works
1. Repository shape
- This is a monorepo for an agentic chatbot system, not a single app.
- The main product lives in chatbot-app/, while agent-blueprint/ contains deployable AWS infrastructure samples for AgentCore runtimes and tool backends.
- mobile-app/ is a separate client with the same backend concepts, and scripts/ plus docs/ support testing and operational workflows.
2. Primary user-facing clients
- chatbot-app/frontend is the main web UI, built with Next.js and organized as a chat workspace with canvas/artifact panels, session history, settings, and streaming execution views.
- mobile-app is an Expo/React Native front end that mirrors the same core interactions: chat, artifacts, sessions, tool events, and auth.
- Both clients consume the same logical backend capabilities rather than embedding agent logic themselves.
3. Web app boundary: Next.js as BFF
- The frontend is not just presentation; it acts as a backend-for-frontend through many app/api/* routes.
- Those routes handle session management, streaming chat, tool registry sync, model configuration, OAuth completion, browser live view, S3 proxying, document downloads, voice start/end, and health checks.
- This layer is where UI state, auth/session handling, and remote service calls are assembled into a browser-friendly API.
4. Agent execution service
- chatbot-app/agentcore is the Python agent runtime service.
- Its structure is centered around agents/, routers/, workflows/, session/, streaming/, skill/, builtin_tools/, local_tools/, and workspace/.
- This is the orchestration boundary: it receives user requests, chooses an agent/workflow, invokes tools, streams intermediate events, and manages session state.
5. Agent orchestration model
- The runtime supports multiple agent styles: chat, skill-aware chat, swarm/multi-agent coordination, and workflow-driven composition.
- workflows/composer_workflow.py and the agents/ package indicate a supervisor/orchestrator pattern rather than a single monolithic prompt loop.
- Hook modules in agent/hooks/ add policy and approval boundaries for sensitive actions like email, GitHub, and research execution.
6. Skill system as a tool abstraction
- The repo uses a progressive disclosure “skills” model stored under chatbot-app/agentcore/skills.
- Skills package tool instructions and usage context separately from execution, so the system prompt stays small and only the needed skill details are loaded on demand.
- This is a key architectural boundary between intent selection, instructions, and actual tool execution.
7. Tooling layers and execution protocols
- Tools are split into several integration types:
- Local Python tools for web search, URL fetch, visualization, workspace operations.
- Built-in tools for code interpretation, diagrams, spreadsheets, PowerPoint, Word, and browser automation.
- Gateway tools accessed through MCP with SigV4 authentication.
- Private API tools using MCP plus 3LO OAuth for Gmail, Calendar, Notion, GitHub.
- A2A tools for remote agent collaboration.
- This separation is important for architecture diagrams because each tool class has a different trust and runtime boundary.
8. AWS AgentCore infrastructure
- agent-blueprint/ contains multiple CDK stacks for deployment:
- agentcore-runtime-stack for the main runtime.
- agentcore-gateway-stack for MCP gateway tools.
- agentcore-runtime-a2a-stack for remote agent runtimes.
- agentcore-runtime-mcp-stack for MCP-based services.
- chatbot-deployment for the integrated chatbot deployment and auth stack.
- The infrastructure is container- and Lambda-oriented, with TypeScript CDK defining the cloud topology.
9. External services and trust boundaries
- The architecture explicitly depends on Amazon Bedrock AgentCore capabilities: runtime, memory, gateway, browser, code interpreter, identity, and observability.
- MCP tools are authenticated with SigV4; user-delegated integrations use OAuth 2.0; some deployments include Cognito-based auth.
- This means the system spans browser/client auth, AWS service auth, and third-party API authorization.
10. Memory, sessions, and long-context handling
- Conversation state is managed as both live session context and summarized long-term memory.
- The frontend has session APIs and local/session-store utilities; the Python agent side has compacting session managers and message stores.
- The design is explicitly optimized for long-running conversations by summarizing and compacting rather than retaining everything in a single prompt.
11. Artifacts and structured outputs
- The system produces more than text: charts, documents, browser screenshots/live views, code outputs, and research artifacts.
- The frontend has canvas components and artifact viewers for charts, images, markdown, office files, and browser sessions.
- This indicates a dual-channel architecture: conversational output plus rendered artifacts/files.
12. Multi-agent and remote agent collaboration
- The repo supports agent-to-agent collaboration through A2A, including remote research and browser-use agents.
- The README also calls out a remote Claude Agent SDK/Claude Code style coding agent on AgentCore Runtime, with S3-backed workspace persistence.
- In a diagram, this should be shown as a supervisor agent delegating specialized tasks to remote runtimes rather than directly doing everything itself.
13. Operational tooling and verification
- There are explicit deployment scripts, destroy scripts, and test suites for both Python and TypeScript/React layers.
- The scripts/ directory includes end-to-end checks for gateway, browser, code interpreter, compaction, swarm, memory, and config behavior.
- This repo is built to validate the architecture across boundaries, not just compile code locally.
14. Practical diagram takeaway
- The clearest architectural picture is: UI clients at the edge, Next.js BFF/API layer in front, Python agent runtime as the orchestration core, and multiple execution backends behind it (AgentCore tools, MCP gateway tools, OAuth APIs, and remote A2A agents), all tied together with session/memory persistence and streamed events back to the UI.
Main entry points: main.py Agent Core · api API Routes · agent-blueprint CDK Deployments · gateway MCP Gateway
Components 18
Clients
User-facing interfaces and their shared UX layer
- Web UI · Primary browser client with chat workspace, canvas, artifacts, session history, and live execution views
chatbot-app/frontend - Mobile App · React Native client mirroring chat, artifacts, sessions, tool events, and auth flows
mobile-app
Web BFF
Next.js frontend acting as browser-facing backend and UI shell
- API Routes · Browser-facing API layer for sessions, streaming, tools, model config, OAuth, browser live view, S3, documents, voice, and health
chatbot-app/frontend/src/app/api - Canvas UX · Chat, canvas, sidebar, approvals, and artifact renderers for charts, images, documents, and browser views
chatbot-app/frontend/src/components - Web State · Session store, auth helpers, API clients, streaming hooks, and tool configuration used by the web app
chatbot-app/frontend/src/lib
Agent Runtime
Python orchestration core for chat, skills, tools, and streaming
- Agent Core · Main orchestration service receiving requests, selecting agents, invoking tools, and streaming results
chatbot-app/agentcore/src/main.py - Agent Styles · Chat, skill-aware chat, swarm coordination, and workflow-driven agent implementations
chatbot-app/agentcore/src/agents - Composer Workflow · Supervisor/composer flow for multi-step composition and delegated execution
chatbot-app/agentcore/src/workflows/composer_workflow.py - Skill System · Progressive-disclosure skills that package instructions and context separately from execution
chatbot-app/agentcore/src/skill - Sessions · Compacting session managers, message stores, and long-context memory handling
chatbot-app/agentcore/src/agent/session - Event Stream · Execution registry and AGUI event formatting for streaming intermediate events back to clients
chatbot-app/agentcore/src/streaming - Local Tools · Workspace, web search, URL fetch, visualization, and Excalidraw-style local tool integrations
chatbot-app/agentcore/src/local_tools - Built-in Tools · Code interpreter, diagrams, spreadsheets, PowerPoint, Word, and browser automation tools
chatbot-app/agentcore/src/builtin_tools - MCP Gateway · Gateway tool access layer using MCP and SigV4-authenticated requests
chatbot-app/agentcore/src/agent/gateway
Execution Backends
External services, remote runtimes, and AWS deployment surfaces
- OAuth Tools · Gmail, Calendar, Notion, and GitHub MCP-backed tools with 3LO user authorization
agent-blueprint/agentcore-runtime-mcp-stack/src - Remote Agents · Remote browser-use, code, and research agent runtimes for delegated collaboration
agent-blueprint/agentcore-runtime-a2a-stack - AgentCore Cloud · Bedrock AgentCore runtime, memory, gateway, browser, code interpreter, identity, and observability services
agent-blueprint - CDK Deployments · TypeScript CDK stacks for runtime, gateway, A2A, MCP, and integrated chatbot deployment
agent-blueprint
Connections 27
- Web UI → API Routes: browser calls · The web app uses route handlers as its browser-facing backend
- Web UI → Canvas UX: renders · Chat UI and artifact panels present results and interactive views
- Web UI → Web State: uses · Client-side state, auth, and streaming helpers drive the experience
- Mobile App → API Routes: shared backend · Mobile client consumes the same logical backend capabilities
- API Routes → Agent Core: invokes · API routes forward chat, session, tool, and voice requests to the runtime
- API Routes → Sessions: manages · Session APIs create, compact, truncate, and update conversation state
- API Routes → Event Stream: streams · Browser SSE and execution state are assembled for live updates
- API Routes → MCP Gateway: syncs tools · Route layer exposes gateway tool discovery and registry synchronization
- API Routes → OAuth Tools: completes auth · OAuth completion and private API integrations are handled through the BFF
- API Routes → Remote Agents: proxies · Remote agent interactions and browser-live workflows are surfaced to clients
- Agent Core → Agent Styles: selects · The runtime dispatches to the appropriate agent style
- Agent Core → Composer Workflow: orchestrates · Composer workflow coordinates multi-step and delegated execution
- Agent Core → Skill System: loads skills · Only relevant skill instructions and context are attached on demand
- Agent Core → Local Tools: executes · Local Python tools handle search, fetch, visualization, and workspace operations
- Agent Core → Built-in Tools: executes · Built-in tools provide code, office, diagram, and browser capabilities
- Agent Core → MCP Gateway: calls · Runtime reaches MCP gateway tools through a signed client boundary
- Agent Core → OAuth Tools: delegates · Private user-authorized integrations are accessed through MCP/OAuth services
- Agent Core → Remote Agents: delegates · Specialized tasks can be sent to remote agent runtimes
- Agent Core → Sessions: persists · Conversation context is compacted and stored across turns
- Agent Core → Event Stream: emits · Intermediate tool and reasoning events are formatted for streaming
- MCP Gateway → AgentCore Cloud: uses · Gateway tools depend on AgentCore runtime and gateway capabilities
- OAuth Tools → AgentCore Cloud: depends on · OAuth-backed integrations run within AgentCore-managed services
- Remote Agents → AgentCore Cloud: runs on · Remote agents execute as separate AgentCore runtimes
- CDK Deployments → AgentCore Cloud: provisions · CDK stacks define the cloud topology for runtimes and auth
- CDK Deployments → MCP Gateway: provisions · Gateway stack deploys MCP tool infrastructure
- CDK Deployments → Remote Agents: provisions · A2A stack deploys specialized remote runtimes
- CDK Deployments → OAuth Tools: provisions · Runtime MCP stack deploys OAuth-enabled tool services