Skip to content

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

BranchesTags

Repository files navigation

Strands Agent Chatbot with AgentCore

Production-ready multi-agent conversational AI system built with Bedrock AgentCore and Strands Agents. Supports RAG workflows, MCP-based tool integration, multimodal input/output, financial analysis tools, and deep research orchestration with prompt caching and multi-protocol tool execution.

Overview

Combines Strands Agent orchestration with AWS Bedrock AgentCore services:

  • Strands Agent: Multi-turn conversation orchestration with tool execution
  • AgentCore Runtime: Containerized agent deployment as managed AWS service
  • AgentCore Memory: Persistent conversation storage with user preference retrieval
  • AgentCore Gateway: MCP tool integration with SigV4 authentication
  • AgentCore Code Interpreter: Built-in code execution for data analysis, visualization, and chart generation
  • AgentCore Browser: Web automation via headless browser with live view streaming
  • Amazon Nova Act: Agentic foundation model for browser automation with visual reasoning

Architecture

Architecture Overview

Core Components

  1. Frontend + BFF (Next.js)

    • Server-side API routes as Backend-for-Frontend
    • Cognito authentication with JWT validation
    • SSE streaming from AgentCore Runtime
    • Session management and file upload handling

  2. AgentCore Runtime

    • Strands Agent with Bedrock Claude models
    • Turn-based session manager (optimized message buffering)
    • Uses AgentCore Memory for conversation persistence
    • Integrates with AgentCore Gateway via SigV4
    • Calls Built-in Tools via AWS API
    • Communicates with other agents via A2A protocol (Work in Progress)

  3. AgentCore Gateway

    • MCP tool endpoints with SigV4 authentication
    • Routes requests to 5 Lambda functions (12 tools total)
    • Lambda functions use MCP protocol
    • Tools: Wikipedia, ArXiv, Google Search, Tavily, Finance

  4. AgentCore Memory

    • Persistent conversation storage
    • Automatic history management across sessions

  5. Tool Ecosystem

    • Local Tools: Weather, visualization, web search, URL fetcher (embedded in Runtime)
    • Built-in Tools: AgentCore Code Interpreter for diagrams/charts, AgentCore Browser for automation (AWS SDK + WebSocket)
    • Gateway Tools: Research, search, and finance data (via AgentCore Gateway + MCP)
    • Runtime Tools (Work in Progress): Report Writer with A2A protocol

Key Features

  • Amazon Bedrock AgentCore Runtime
  • Strands Agent Orchestration
  • MCP Gateway Tools (Wikipedia, ArXiv, Google, Tavily)
  • A2A Agent-to-Agent Protocol
  • Financial research tools (stock data, market news)
  • Multimodal I/O (Vision, Charts, Documents, Screenshots)

Use Cases

  • Financial research agent with stock analysis & SEC ingestion
  • Technical research assistant using multi-agent architecture
  • Web automation agent via AgentCore Browser + Nova Act
  • RAG-enabled chatbot using AgentCore Memory
  • Multi-protocol research assistant (MCP, A2A, AWS SDK)

Key Technical Features

1. Full-stack Web-based Chatbot Application

  • Frontend: Next.js with React, TypeScript, Tailwind CSS, shadcn/ui
  • Backend (BFF): Next.js API routes for SSE streaming, authentication, session management
  • Agent Runtime: Strands Agent orchestration on AgentCore Runtime (containerized)
  • Persistence: AgentCore Memory for conversation history and user context
  • Authentication: AWS Cognito with JWT validation
  • Deployment: CloudFront → ALB → Fargate (Frontend+BFF) + AgentCore Runtime

2. Multi-Protocol Tool Architecture

Tools communicate via different protocols based on their characteristics:

Tool Type Protocol Count Examples Authentication
Local Tools Direct function calls 5 Weather, Web Search, Visualization N/A
Built-in Tools AWS SDK + WebSocket 4 AgentCore Code Interpreter, Browser (Nova Act) IAM
Gateway Tools MCP + SigV4 12 Wikipedia, ArXiv, Finance (Lambda) AWS SigV4
Runtime Tools A2A protocol 9 Report Writer AgentCore auth

Status: 21 tools ✅ / 9 tools 🚧. See Implementation Details for complete tool list.

3. Dynamic Tool Filtering

Users can enable/disable specific tools via UI sidebar, and the agent dynamically filters tool definitions before each invocation, sending only selected tools to the model to reduce prompt token count and optimize costs.

4. Token Optimization via Prompt Caching

Implements hooks-based caching strategy with system prompt caching and dynamic conversation history caching (last 2 messages), using rotating cache points (max 4 total) to significantly reduce input token costs across repeated API calls.

5. Multimodal Input/Output

Native support for visual and document content:

  • Input: Images (PNG, JPEG, GIF, WebP), Documents (PDF, CSV, DOCX, etc.)
  • Output: Charts from AgentCore Code Interpreter, screenshots from AgentCore Browser

6. Two-tier Memory System

Combines session-based conversation history (short-term) with namespaced user preferences and facts (long-term) stored in AgentCore Memory, enabling cross-session context retention with relevance-scored retrieval per user.

Demo

Implementation Details

Multi-Protocol Tool Architecture

See docs/TOOLS.md for detailed tool specifications.

Tool Name Protocol API Key Status Description
Local Tools
Calculator Direct call No ✅ Mathematical computations
Weather Lookup Direct call No ✅ Current weather by city
Visualization Creator Direct call No ✅ Interactive charts (Plotly)
Web Search Direct call No ✅ DuckDuckGo search
URL Fetcher Direct call No ✅ Web content extraction
Built-in Tools
Diagram Generator AWS SDK No ✅ Charts/diagrams via AgentCore Code Interpreter
Browser Automation (3 tools) AWS SDK + WebSocket Yes ✅ Navigate, action, extract via AgentCore Browser (Nova Act)
Gateway Tools
Wikipedia (2 tools) MCP + SigV4 No ✅ Article search and retrieval
ArXiv (2 tools) MCP + SigV4 No ✅ Scientific paper search
Google Search (2 tools) MCP + SigV4 Yes ✅ Web and image search
Tavily AI (2 tools) MCP + SigV4 Yes ✅ AI-powered search and extraction
Financial Market (4 tools) MCP + SigV4 No ✅ Stock quotes, history, news, analysis (Yahoo Finance)
Runtime Tools
Report Writer (9 tools) A2A No 🚧 Multi-section research reports with charts

Protocol Details:

  • Direct call: Python function with @tool decorator, executed in runtime container
  • AWS SDK: Bedrock client API calls (AgentCore Code Interpreter, AgentCore Browser)
  • WebSocket: Real-time bidirectional communication for browser automation
  • MCP + SigV4: Model Context Protocol with AWS SigV4 authentication
  • A2A: Agent-to-Agent protocol for runtime-to-runtime communication

Total: 30 tools (21 ✅ / 9 🚧)

Dynamic Tool Filtering

Implementation: agent.py:277-318

# User-selected tools from UI sidebar
enabled_tools = ["calculator", "gateway_wikipedia-search___wikipedia_search"]

# Filters applied before agent creation
agent = Agent(
    model=model,
    tools=get_filtered_tools(enabled_tools),  # Dynamic filtering
    session_manager=session_manager
)

Tool Filtering Flow

Flow:

  1. User Toggle: User selects tools via UI sidebar
  2. Enabled Tools: Frontend sends enabled tool list to AgentCore Runtime
  3. Tool Filtering: Strands Agent filters tools before model invocation
  4. Invoke: Model receives only enabled tool definitions
  5. ToolCall: Agent executes local or remote tools as needed

Benefits:

  • Reduced token usage (only selected tool definitions sent to model)
  • Per-user customization
  • Real-time tool updates without redeployment

Token Optimization: Prompt Caching

Implementation: agent.py:67-142

Two-level caching via Strands hooks:

  1. System Prompt Caching (static)

    system_content = [
    {"text": system_prompt},
    {"cachePoint": {"type": "default"}}  # Cache marker
]

  2. Conversation History Caching (dynamic)

    • ConversationCachingHook adds cache points to last 2 messages
    • Removes cache points from previous messages
    • Executes on BeforeModelCallEvent

Cache Strategy:

  • Max 4 cache points: system (1-2) + last 2 messages (2)
  • Cache points rotate as conversation progresses
  • Reduces input tokens for repeated content

Prompt Caching Strategy

Visual Explanation:

  • 🟧 Orange: Cache creation (new content cached)
  • 🟦 Blue: Cache read (reusing cached content)
  • Turn1 creates initial cache, Turn2+ reuses and extends cached context

Turn-based Session Manager

Implementation: turn_based_session_manager.py:15-188

Buffers messages within a turn to reduce AgentCore Memory API calls:

Without buffering:
User message     → API call 1
Assistant reply  → API call 2
Tool use         → API call 3
Tool result      → API call 4
Total: 4 API calls per turn

With buffering:
User → Assistant → Tool → Result  → Single merged API call
Total: 1 API call per turn (75% reduction)

Key Methods:

  • append_message(): Buffers messages instead of immediate persistence
  • _should_flush_turn(): Detects turn completion
  • flush(): Writes merged message to AgentCore Memory

Multimodal I/O

Input Processing (agent.py:483-549):

  • Converts uploaded files to ContentBlock format
  • Supports images (PNG, JPEG, GIF, WebP) and documents (PDF, CSV, DOCX, etc.)
  • Files sent as raw bytes in message content array

Output Rendering:

  • Tools return ToolResult with multimodal content
  • Images from AgentCore Code Interpreter and Browser rendered inline
  • Image bytes delivered as raw bytes (not base64)
  • Files downloadable from frontend

Example Tool Output:

return {
    "content": [
        {"text": "Chart generated successfully"},
        {"image": {"format": "png", "source": {"bytes": image_bytes}}}
    ],
    "status": "success"
}

Two-tier Memory System

Implementation: agent.py:223-235

AgentCoreMemoryConfig(
    memory_id=memory_id,
    session_id=session_id,
    actor_id=user_id,
    retrieval_config={
        # User preferences (coding style, language, etc.)
        f"/preferences/{user_id}": RetrievalConfig(top_k=5, relevance_score=0.7),

        # User-specific facts (learned information)
        f"/facts/{user_id}": RetrievalConfig(top_k=10, relevance_score=0.3),
    }
)

Memory Tiers:

  • Short-term: Session conversation history (automatic via session manager)
  • Long-term: Namespaced key-value storage with vector retrieval
  • Cross-session persistence via actor_id (user identifier)

Quick Start

Prerequisites

  • AWS Account with Bedrock access (Claude models)
  • AWS CLI configured with credentials
  • Docker installed and running
  • Node.js 18+ and Python 3.13+
  • AgentCore enabled in your AWS account region

Local Development

Run the application locally with Docker Compose:

# 1. Clone repository
git clone https://github.com/aws-samples/sample-strands-agent-with-agentcore.git
cd sample-strands-agent-with-agentcore

# 2. Setup dependencies
cd chatbot-app
./setup.sh

# 3. Configure AWS credentials
cd ../agent-blueprint
cp .env.example .env
# Edit .env with your AWS credentials and region

# 4. Start all services
cd ../chatbot-app
./start.sh

Services started:

What runs locally:

  • ✅ Frontend (Next.js)
  • ✅ AgentCore Runtime (Strands Agent)
  • ✅ Local Tools (5 tools)
  • ✅ Built-in Tools (Code Interpreter, Browser via AWS API)
  • ❌ AgentCore Gateway (requires cloud deployment)
  • ❌ AgentCore Memory (uses local file storage instead)

Cloud Deployment

Deploy the full-stack application to AWS:

# Navigate to deployment directory
cd agent-blueprint

# Full deployment (all components)
./deploy.sh

Deployment Components:

  1. Main Application Stack (chatbot-deployment/)

    • Frontend + BFF (Next.js on Fargate)
    • AgentCore Runtime (Strands Agent)
    • AgentCore Memory (conversation persistence)
    • CloudFront, ALB, Cognito
    • Deploy: cd chatbot-deployment/infrastructure && ./scripts/deploy.sh

  2. AgentCore Gateway Stack (agentcore-gateway-stack/)

    • MCP tool endpoints with SigV4 authentication
    • 5 Lambda functions (12 tools total)
    • Wikipedia, ArXiv, Google Search, Tavily, Finance
    • Deploy: cd agentcore-gateway-stack && ./scripts/deploy.sh

  3. Report Writer Runtime (Optional, agentcore-runtime-a2a-stack/)

    • A2A protocol-based agent collaboration
    • Multi-section research report generation
    • Deploy: cd agentcore-runtime-a2a-stack/report-writer && ./deploy.sh

Deployment Architecture

User → CloudFront → ALB → Frontend+BFF (Fargate)
                              ↓ HTTP
                         AgentCore Runtime
                         (Strands Agent container)
                              ↓
            ┌─────────────────┼─────────────────┐
            │                 │                 │
            ↓ SigV4           ↓ A2A             ↓ AWS SDK
     AgentCore Gateway   Report Writer     Built-in Tools
     (MCP endpoints)     Runtime 🚧        (Code Interpreter,
            ↓                               Browser + Nova Act)
     Lambda Functions (5x)
     └─ Wikipedia, ArXiv,
        Google, Tavily, Finance

     AgentCore Memory
     └─ Conversation history
        User preferences & facts

Technology Stack

Frontend & Backend:

  • Frontend: Next.js, React, TypeScript, Tailwind CSS, shadcn/ui
  • BFF: Next.js API Routes (SSE streaming, authentication, session management)
  • Deployment: AWS Fargate (containerized)

AI & Agent:

  • Orchestration: Strands Agents (Python)
  • Models: AWS Bedrock Claude (Haiku default, Sonnet available)
  • Runtime: AgentCore Runtime (containerized Strands Agent)

AgentCore Services:

  • Memory: Conversation history with user preferences/facts retrieval
  • Gateway: MCP tool endpoints with SigV4 authentication
  • Code Interpreter: Python code execution for diagrams/charts
  • Browser: Web automation with Nova Act AI model

Tools & Integration:

  • Local Tools: Direct Python function calls (5 tools)
  • Built-in Tools: AWS SDK + WebSocket (4 tools)
  • Gateway Tools: Lambda + MCP protocol (12 tools)
  • Runtime Tools: A2A protocol (9 tools, in progress)

Infrastructure:

  • IaC: AWS CDK (TypeScript)
  • Frontend CDN: CloudFront
  • Load Balancer: Application Load Balancer
  • Authentication: AWS Cognito
  • Compute: Fargate containers

Iframe Embedding

Embed the chatbot in external applications:

<iframe
  src="https://your-domain.com/embed"
  width="100%"
  height="600"
  frameborder="0">
</iframe>

Project Structure

sample-strands-agent-chatbot/
├── chatbot-app/
│   ├── frontend/              # Next.js (Frontend + BFF)
│   │   └── src/
│   │       ├── app/api/       # API routes (BFF layer)
│   │       ├── components/    # React components
│   │       └── config/        # Tool configuration
│   └── agentcore/             # AgentCore Runtime
│       └── src/
│           ├── agent/         # ChatbotAgent + session management
│           ├── local_tools/   # Weather, visualization, etc.
│           ├── builtin_tools/ # Code Interpreter tools
│           └── routers/       # FastAPI routes
│
└── agent-blueprint/
    ├── chatbot-deployment/    # Main app stack (Frontend+Runtime)
    ├── agentcore-gateway-stack/   # Gateway + 5 Lambda functions
    ├── agentcore-runtime-stack/   # Runtime deployment (shared)
    └── agentcore-runtime-a2a-stack/   # Report Writer (optional)

Documentation

Support

License

MIT License - see LICENSE file for details.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

46 stars

Watchers

1 watching

Forks

15 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 6

Languages