GenAI Chatdestiny

“Uncover the deeper pattern behind your choices and future through the combined wisdom of Tarot cards and numbers.”

Comment

🔮 Chat Destiny - AI-Powered Mystical Guidance System

Inspiration

As developers passionate about AI, we wanted to explore the full capabilities of AWS Bedrock AgentCore. We asked ourselves: "Can we build a production-ready multi-agent system using AgentCore Runtime, Memory, and Observability?" This question led us to create Chat Destiny - a mystical guidance platform that combines tarot readings with AWS AI technology.

We were inspired by the potential of Strands Agents framework working with AWS Bedrock AgentCore to create sophisticated multi-agent systems. Instead of a simple chatbot, we wanted to showcase how AgentCore's services work together in a real application.

What it does

Chat Destiny is a mystical guidance platform featuring:

  • Interactive Tarot Readings: 78 animated tarot cards with visual effects
  • 7 Specialized AI Agents: Built with Strands Agents framework, powered by Amazon Bedrock Nova Micro
  • Multi-Agent Collaboration: A 3-agent Tarot Swarm that works together intelligently
  • Persistent Memory: AgentCore Memory remembers conversations across sessions
  • FastAPI Backend: Async API server handling concurrent requests
  • Production Observability: AWS OpenTelemetry integration for monitoring

How we built it

Core Technology Stack

Backend:

  • Strands Agents (v1.10.0): Multi-agent orchestration with GraphBuilder and Swarm
  • FastAPI: Async API server
  • bedrock-agentcore (v0.1.7): AgentCore Memory client
  • aws-opentelemetry-distro (v0.12.1): Distributed tracing
  • Bedrock AgentCore Runtime: Containerized deployment

Frontend:

  • React + Vite: Modern frontend framework
  • Framer Motion: Card animations
  • Tailwind CSS: UI styling

1. Strands Agents Framework - Multi-Agent System

We built our system using Strands Agents with a graph-based architecture using GraphBuilder.

Agent Structure:

  • Router Agent: Entry point that analyzes user intent
  • Welcome Agent: Handles greetings
  • Numerology Agent: Performs calculations
  • Tarot Swarm: Three agents (Spread Reader, Card Interpreter, Life Advisor) working together

Swarm Configuration (from tarot_swarm.py):

  • Entry point: spread_reader
  • max_handoffs: 15
  • max_iterations: 15
  • execution_timeout: 120.0 seconds
  • node_timeout: 20.0 seconds
  • repetitive_handoff_detection_window: 6
  • repetitive_handoff_min_unique_agents: 2

2. FastAPI - Async Backend

We use FastAPI for the API server with async endpoints. The main endpoint is /invocations which:

  • Loads conversation history from AgentCore Memory
  • Converts events to Strands Messages format
  • Creates agent graph with history
  • Executes graph asynchronously with invoke_async()
  • Extracts response from nested results
  • Stores conversation back to memory

3. Bedrock AgentCore Runtime - Deployment

We deployed as a containerized AgentCore Runtime (from main.py):

  • Container stored in Amazon ECR
  • Runtime ID: chatdestiny-CpdlPd2w1j
  • Network mode: PUBLIC
  • Custom request headers for authentication
  • Environment variables for all prompt IDs and memory ID

4. Bedrock AgentCore Memory - Conversation Storage

We implemented AgentCore Memory using MemoryClient from bedrock-agentcore SDK (from memory.py):

Implementation:

  • MemoryClient connects to AWS region
  • Memory name: "StrandAgentShortTermMemory"
  • Checks config for existing MEMORY_ID first
  • Lists existing memories to find by name
  • Creates new memory only if none exists
  • Handles "already exists" errors gracefully

Usage:

  • create_event(): Stores conversation with actor_id and session_id
  • list_events(): Retrieves conversation history (we load last 10 events)
  • Events contain conversational payload with role and text

5. Bedrock Prompt Management - Version Control

All agents pull prompts from Bedrock Prompt Management (from prompt_manager.py):

Implementation:

  • Uses boto3 bedrock-agent client
  • Fetches prompts by identifier and version
  • Supports TEXT and CHAT template types
  • Caches versioned prompts (not DRAFT)
  • Extracts system prompt text and inference config

Prompt IDs (from config.py):

  • ROUTER_PROMPT_ID
  • WELCOME_PROMPT_ID
  • NUMEROLOGY_PROMPT_ID
  • CARD_INTERPRETER_PROMPT_ID
  • SPREAD_READER_PROMPT_ID
  • LIFE_ADVISOR_PROMPT_ID

6. AgentCore Observability - OpenTelemetry

We integrated AWS OpenTelemetry Distro (from requirements.txt and main.py):

  • aws-opentelemetry-distro~=0.12.1
  • Structured logging with timestamps and levels
  • Logs to stdout for CloudWatch integration
  • Distributed tracing across agents

7. Strands Tools - Custom Capabilities

We built a custom tool using Strands' @tool decorator (from tarot_tools.py):

  • draw_tarot_cards(num_cards): Draws 1-10 cards from 78-card deck
  • Returns formatted string: "CARDS: [Card Name 1, Card Name 2, ...]"
  • Used by Spread Reader agent during readings

8. Multi-Agent Graph with Conditional Routing

Our GraphBuilder implementation (from graph.py):

  • Adds all agents as nodes
  • Creates conditional edges based on router output
  • Routes to welcome, numerology, or tarot based on intent
  • Entry point: router agent
  • Execution timeout: 600 seconds (10 minutes)
  • Node timeout: 180 seconds (3 minutes)

Challenges we ran into

1. AgentCore Memory Resource Management

Challenge: Memory creation sometimes failed with "already exists" errors. The API for finding existing memories required careful handling.

Solution: Built initialization that checks config first, lists memories to find by name, creates only if none exists, and handles race conditions.

2. Strands Swarm Coordination

Challenge: Preventing infinite loops between 3 agents in the Tarot Swarm.

Solution: Configured Swarm with max_handoffs, repetitive_handoff_detection_window, and timeouts as shown in source code.

3. Response Extraction from Nested Results

Challenge: Extracting clean text from complex SwarmResult and NodeResult objects.

Solution: Built extraction logic that traverses node_history, finds last agent, extracts message content from nested dictionaries.

4. AgentCore Runtime Deployment

Challenge: Configuring containerized deployment with environment variables and network settings.

Solution: Used update_agent_runtime() to configure container URI, environment variables, network mode, and request headers.

5. Async Integration

Challenge: Ensuring smooth async execution between FastAPI and Strands Agents.

Solution: Used invoke_async() and proper async/await patterns throughout.

Accomplishments that we're proud of

Complete AgentCore Integration

  • ✅ AgentCore Runtime: Containerized deployment
  • ✅ AgentCore Memory: Persistent conversations with MemoryClient
  • ✅ AgentCore Observability: OpenTelemetry integration
  • ✅ Bedrock Prompt Management: Version-controlled prompts

Strands Agents Implementation

  • ✅ Multi-Agent Graph: GraphBuilder with conditional routing
  • ✅ Swarm Architecture: 3-agent Tarot Swarm
  • ✅ Custom Tools: Tarot card drawing tool
  • ✅ History Management: Conversation context across agents

Production-Ready Features

  • ✅ FastAPI async backend
  • ✅ Error handling throughout
  • ✅ Timeout protection at multiple levels
  • ✅ Memory resource management

User Experience

  • ✅ 78 animated tarot cards
  • ✅ Physics-based animations
  • ✅ Responsive design
  • ✅ Visual card effects

What we learned

1. Strands Agents Framework

We learned that Strands provides GraphBuilder for routing and Swarm for collaboration. The framework includes built-in loop prevention with repetitive handoff detection.

2. AgentCore Memory

We learned how to use MemoryClient to store and retrieve conversations. The memory system supports actor_id and session_id for organizing conversations. We load the last 10 events for context.

3. FastAPI + Strands Integration

We learned that FastAPI's async capabilities work well with Strands' invoke_async(). This allows handling multiple requests concurrently.

4. AgentCore Runtime Deployment

We learned how to deploy as a containerized runtime with environment variables, network configuration, and custom headers.

5. Prompt Management

We learned to fetch prompts from Bedrock Prompt Management using boto3. The system supports versioning and caching for performance.

6. Multi-Agent Patterns

We learned to build conditional routing with GraphBuilder and collaborative agents with Swarm. Proper timeout configuration prevents runaway executions.

7. Observability

We learned that AWS OpenTelemetry Distro provides distributed tracing. Structured logging helps with debugging multi-agent interactions.

8. Error Handling

We learned to handle various edge cases: memory already exists, nested result extraction, timeout errors, and API failures.

9. Tool Integration

We learned to create custom tools with Strands' @tool decorator. Tools integrate seamlessly with agents.

10. Production Considerations

We learned the importance of timeouts, error handling, and observability from the start. These features made deployment straightforward.

What's next for GenAI Chatdestiny

Immediate Enhancements

  • Additional agents for I Ching, runes, astrology
  • Voice integration with AWS Polly and Transcribe
  • Image generation with Bedrock
  • Multi-language support

Platform Expansion

  • Mobile applications
  • API service for third-party integration
  • Community features
  • Analytics dashboard

Advanced Features

  • Model fine-tuning for specialized agents
  • Lambda integration for serverless scaling
  • S3 and DynamoDB for data storage
  • Multi-region deployment

Why Chat Destiny Deserves Recognition

Complete AgentCore Demonstration

We integrated the full AgentCore stack: Runtime, Memory, Observability, and Prompt Management. This shows how these services work together in a real application.

Strands Agents Implementation

Our graph + swarm architecture demonstrates multi-agent patterns with Strands. We show conditional routing, collaborative agents, and loop prevention.

Production-Ready Architecture

We built with error handling, timeouts, and observability from the start. The application is deployment-ready.

Technical Learning

We mastered new technologies and documented our implementation. Our code shows practical patterns for AgentCore and Strands.

Real Application

This isn't just a demo - it's a functional application with 78 animated cards, persistent memory, and multi-agent intelligence.

Chat Destiny demonstrates what's possible with AWS Bedrock AgentCore and Strands Agents. We hope our implementation helps others build multi-agent systems.

Built with ❤️ and ✨ for the AWS Bedrock Hackathon

Powered by Strands Agents, FastAPI, and AWS Bedrock AgentCore

🔮 May the cards guide your path 🔮

Built With

Share this project:

Updates