# aws-samples/sample-strands-agent-with-agentcore architecture

> Architecture diagram of the GitHub repository aws-samples/sample-strands-agent-with-agentcore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/sample-strands-agent-with-agentcore
- Repository: https://github.com/aws-samples/sample-strands-agent-with-agentcore

## Overview

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: [`chatbot-app/agentcore/src/main.py`](https://github.com/aws-samples/sample-strands-agent-with-agentcore/blob/main/chatbot-app/agentcore/src/main.py) (Agent Core), [`chatbot-app/frontend/src/app/api`](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/frontend/src/app/api) (API Routes), [`agent-blueprint`](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/agent-blueprint) (CDK Deployments), [`chatbot-app/agentcore/src/agent/gateway`](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/agent/gateway) (MCP Gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_clients["Clients"]
  node_node_web_ui["Web UI<br/>Next.js chat app"]
  node_node_mobile_ui["Mobile App<br/>Expo client"]
end

subgraph group_group_web_bff["Web BFF"]
  node_node_web_api["API Routes<br/>BFF routes"]
  node_node_canvas["Canvas UX<br/>artifact UI"]
  node_node_web_state["Web State<br/>client state"]
end

subgraph group_group_agent_runtime["Agent Runtime"]
  node_node_agent_main["Agent Core<br/>Python runtime<br/>[main.py]"]
  node_node_agents["Agent Styles<br/>agent orchestration"]
  node_node_workflow["Composer Workflow<br/>workflow engine"]
  node_node_skill_system["Skill System<br/>skill registry"]
  node_node_session[("Sessions<br/>state + memory")]
  node_node_streaming["Event Stream<br/>streaming pipeline"]
  node_node_tools_local["Local Tools<br/>python tools"]
  node_node_tools_builtin["Built-in Tools<br/>embedded tools"]
  node_node_gateway["MCP Gateway<br/>sigv4 MCP client"]
end

subgraph group_group_backends["Execution Backends"]
  node_node_oauth_tools["OAuth Tools<br/>private integrations"]
  node_node_a2a["Remote Agents<br/>A2A runtimes"]
  node_node_agentcore_cloud["AgentCore Cloud<br/>aws services"]
  node_node_deploy["CDK Deployments<br/>infra stacks"]
end

node_node_web_ui -->|"browser calls"| node_node_web_api
node_node_web_ui -->|"renders"| node_node_canvas
node_node_web_ui -->|"uses"| node_node_web_state
node_node_mobile_ui -->|"shared backend"| node_node_web_api
node_node_web_api -->|"invokes"| node_node_agent_main
node_node_web_api -->|"manages"| node_node_session
node_node_web_api -->|"streams"| node_node_streaming
node_node_web_api -->|"syncs tools"| node_node_gateway
node_node_web_api -->|"completes auth"| node_node_oauth_tools
node_node_web_api -->|"proxies"| node_node_a2a
node_node_agent_main -->|"selects"| node_node_agents
node_node_agent_main -->|"orchestrates"| node_node_workflow
node_node_agent_main -->|"loads skills"| node_node_skill_system
node_node_agent_main -->|"executes"| node_node_tools_local
node_node_agent_main -->|"executes"| node_node_tools_builtin
node_node_agent_main -->|"calls"| node_node_gateway
node_node_agent_main -->|"delegates"| node_node_oauth_tools
node_node_agent_main -->|"delegates"| node_node_a2a
node_node_agent_main -->|"persists"| node_node_session
node_node_agent_main -->|"emits"| node_node_streaming
node_node_gateway -->|"uses"| node_node_agentcore_cloud
node_node_oauth_tools -->|"depends on"| node_node_agentcore_cloud
node_node_a2a -->|"runs on"| node_node_agentcore_cloud
node_node_deploy -->|"provisions"| node_node_agentcore_cloud
node_node_deploy -->|"provisions"| node_node_gateway
node_node_deploy -->|"provisions"| node_node_a2a
node_node_deploy -->|"provisions"| node_node_oauth_tools

click node_node_web_ui "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/frontend"
click node_node_mobile_ui "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/mobile-app"
click node_node_web_api "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/frontend/src/app/api"
click node_node_canvas "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/frontend/src/components"
click node_node_web_state "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/frontend/src/lib"
click node_node_agent_main "https://github.com/aws-samples/sample-strands-agent-with-agentcore/blob/main/chatbot-app/agentcore/src/main.py"
click node_node_agents "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/agents"
click node_node_workflow "https://github.com/aws-samples/sample-strands-agent-with-agentcore/blob/main/chatbot-app/agentcore/src/workflows/composer_workflow.py"
click node_node_skill_system "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/skill"
click node_node_session "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/agent/session"
click node_node_streaming "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/streaming"
click node_node_tools_local "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/local_tools"
click node_node_tools_builtin "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/builtin_tools"
click node_node_gateway "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/agent/gateway"
click node_node_oauth_tools "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/agent-blueprint/agentcore-runtime-mcp-stack/src"
click node_node_a2a "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/agent-blueprint/agentcore-runtime-a2a-stack"
click node_node_agentcore_cloud "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/agent-blueprint"
click node_node_deploy "https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/agent-blueprint"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_web_ui,node_node_mobile_ui toneBlue
class node_node_web_api,node_node_canvas,node_node_web_state toneAmber
class node_node_agent_main,node_node_agents,node_node_workflow,node_node_skill_system,node_node_session,node_node_streaming,node_node_tools_local,node_node_tools_builtin,node_node_gateway toneMint
class node_node_oauth_tools,node_node_a2a,node_node_agentcore_cloud,node_node_deploy toneRose
```

## Components

### Clients

User-facing interfaces and their shared UX layer

- [Web UI](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/frontend): Next.js chat app · Primary browser client with chat workspace, canvas, artifacts, session history, and live execution views · `chatbot-app/frontend`
- [Mobile App](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/mobile-app): Expo client · 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](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/frontend/src/app/api): BFF 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](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/frontend/src/components): artifact UI · Chat, canvas, sidebar, approvals, and artifact renderers for charts, images, documents, and browser views · `chatbot-app/frontend/src/components`
- [Web State](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/frontend/src/lib): client 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](https://github.com/aws-samples/sample-strands-agent-with-agentcore/blob/main/chatbot-app/agentcore/src/main.py): Python runtime · Main orchestration service receiving requests, selecting agents, invoking tools, and streaming results · `chatbot-app/agentcore/src/main.py`
- [Agent Styles](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/agents): agent orchestration · Chat, skill-aware chat, swarm coordination, and workflow-driven agent implementations · `chatbot-app/agentcore/src/agents`
- [Composer Workflow](https://github.com/aws-samples/sample-strands-agent-with-agentcore/blob/main/chatbot-app/agentcore/src/workflows/composer_workflow.py): workflow engine · Supervisor/composer flow for multi-step composition and delegated execution · `chatbot-app/agentcore/src/workflows/composer_workflow.py`
- [Skill System](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/skill): skill registry · Progressive-disclosure skills that package instructions and context separately from execution · `chatbot-app/agentcore/src/skill`
- [Sessions](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/agent/session): state + memory · Compacting session managers, message stores, and long-context memory handling · `chatbot-app/agentcore/src/agent/session`
- [Event Stream](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/streaming): streaming pipeline · Execution registry and AGUI event formatting for streaming intermediate events back to clients · `chatbot-app/agentcore/src/streaming`
- [Local Tools](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/local_tools): python tools · Workspace, web search, URL fetch, visualization, and Excalidraw-style local tool integrations · `chatbot-app/agentcore/src/local_tools`
- [Built-in Tools](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/builtin_tools): embedded tools · Code interpreter, diagrams, spreadsheets, PowerPoint, Word, and browser automation tools · `chatbot-app/agentcore/src/builtin_tools`
- [MCP Gateway](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/chatbot-app/agentcore/src/agent/gateway): sigv4 MCP client · 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](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/agent-blueprint/agentcore-runtime-mcp-stack/src): private integrations · Gmail, Calendar, Notion, and GitHub MCP-backed tools with 3LO user authorization · `agent-blueprint/agentcore-runtime-mcp-stack/src`
- [Remote Agents](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/agent-blueprint/agentcore-runtime-a2a-stack): A2A runtimes · Remote browser-use, code, and research agent runtimes for delegated collaboration · `agent-blueprint/agentcore-runtime-a2a-stack`
- [AgentCore Cloud](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/agent-blueprint): aws services · Bedrock AgentCore runtime, memory, gateway, browser, code interpreter, identity, and observability services · `agent-blueprint`
- [CDK Deployments](https://github.com/aws-samples/sample-strands-agent-with-agentcore/tree/main/agent-blueprint): infra stacks · TypeScript CDK stacks for runtime, gateway, A2A, MCP, and integrated chatbot deployment · `agent-blueprint`

## Connections

- 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
