Zmead AI

A delivery-focused AI agent platform where users converse naturally and the agent produces tangible outputs — images, videos, documents, architecture diagrams, deployed web pages, and more.

Features

Agent Tools

Tool	Provider	Description
Code Execution	AgentCore Code Interpreter	Python, JS, Shell scripts, data analysis
Web Browsing	AgentCore Browser	Scraping, form filling, live view via DCV
Web Search	Nova 2 Lite Web Grounding	Research, fact-checking, source synthesis
Image Generation	Stability AI (SD3.5)	Visual content, graphics, illustrations
Video Generation	Luma AI (Ray v2)	Motion content, animations
File Operations	Built-in	Create, read, manage files on S3
Web Deployment	Built-in	Deploy static sites to S3 + CloudFront
Architecture Diagrams	Built-in	AWS Draw.io diagrams with official icons
AWS Pricing	Built-in	Real-time pricing lookups
Billing Analysis	Built-in	CSV/Excel billing analysis with anomaly detection
Competitor Mapping	Built-in	Cloud provider feature comparison
Content Review	Built-in	Document review and feedback
Knowledge Base	Built-in	Save, search, publish knowledge items
Task Manager	Built-in	Create, track, and manage tasks with reminders
Code Generation	Built-in	Generate and scaffold code projects

Agent Skills

Pre-built skill packs that guide the agent for specialized tasks:

AWS Architecture Review — Well-Architected Framework analysis
AWS Cost Optimization — RI/SP recommendations, cost reports
Client Weekly Report — Automated weekly status reports
Competitor Analysis — Multi-cloud competitive analysis
HTML Presentation — Slide deck generation
Solution Document — Technical solution authoring

Skills can be installed/uninstalled via the API, including from GitHub repositories. Per-user enable/disable is supported.

MCP Integration

Dynamic Model Context Protocol server management:

Add/remove/enable/disable MCP servers per user
OAuth discovery and credential management for MCP servers
List available tools from connected MCP servers

Platform Features

Library — Browse, preview, download all generated deliverables
Knowledge Base — Personal knowledge store with publish-to-web (docs.zmead.com)
Knowledge Portal — Public-facing article portal with categories, featured articles, and search
Tasks — Task tracking with due dates, priorities, and email reminders
Projects — Organize conversations and deliverables into projects with analytics
Analytics — Usage overview, trend data, tool usage distribution, error statistics
Templates — Reusable conversation starters
History — Full conversation history with search
Admin — User management, approval workflow
Settings — User preferences and configuration
Real-time Streaming — WebSocket-based progress updates during agent execution
Embedded Browser — Live browser preview with AgentCore Browser and DCV streaming
Smart Suggestions — Context-aware conversation starters
Multi-auth — Google OAuth, GitHub OAuth, Amazon Cognito

Tech Stack

Backend (Python 3.12+)

Component	Technology
Framework	FastAPI (async/await)
Database	MySQL 8.4 + SQLAlchemy async (aiomysql)
Cache	Redis 7.1
Storage	AWS S3
Auth	Google/GitHub OAuth + Cognito + JWT

AI / Agent

Purpose	Provider	Model
Conversational	Anthropic	Claude Opus 4.6 (1M context, 128K output)
Image Generation	Stability AI	SD3.5 Large
Video Generation	Luma AI	Ray v2
Multimodal	Amazon	Nova 2 Lite

Agent Framework: Strands Agents (@tool decorator)
Runtime: Amazon Bedrock AgentCore (optional, auto-scaling)
Memory: AgentCore Memory (conversation persistence)
Code Execution: AgentCore Code Interpreter (isolated sandboxes)
Browser: AgentCore Browser (headless browsing)

Frontend (TypeScript)

Component	Technology	Version
Framework	React	19
Build	Vite	7
Styling	Tailwind CSS	4
Routing	React Router	7
Markdown	react-markdown	+ remark-gfm

Architecture

CloudFront (zmead.com)      → S3 (Frontend SPA)
CloudFront (docs.zmead.com) → S3 (Published Knowledge Base)
ALB (api.zmead.com)         → ECS Fargate (FastAPI)
                                ├── RDS MySQL 8.4
                                ├── ElastiCache Redis 7.1
                                ├── S3 (Deliverables)
                                ├── Bedrock (AI Models)
                                ├── AgentCore Runtime (optional)
                                ├── AgentCore Code Interpreter
                                └── AgentCore Browser

Dual Execution Modes

Mode	Config	Use Case
Direct	`AGENTCORE_RUNTIME_ENABLED=false`	Development, single instance
AgentCore	`AGENTCORE_RUNTIME_ENABLED=true`	Production, auto-scaling

Direct Mode:

Frontend → FastAPI (WebSocket) → ZmeadAgent → Bedrock / Tools

AgentCore Runtime Mode:

Frontend → FastAPI (WebSocket) → AgentCore Runtime (SSE) → ZmeadAgent

Local Development

Prerequisites

Python 3.12+
Node.js 20+
MySQL 8.x running locally
Redis running locally

Backend

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # Edit with your credentials
uvicorn app.main:app --reload --port 8000

Optional — with AgentCore Runtime:

agentcore configure --entrypoint app/agent/agentcore_app.py --name zmead_agent
agentcore launch --local          # Terminal 1
# Set AGENTCORE_RUNTIME_ENABLED=true in .env
uvicorn app.main:app --reload     # Terminal 2

Frontend

cd frontend
npm install
npm run dev    # http://localhost:5173

Testing

cd backend
pytest                  # All tests
pytest --cov=app        # With coverage
pytest -k "test_name"   # Specific test

Deployment

Infrastructure is managed with AWS CDK in the infra/ directory:

ZmeadStack — Main infra (VPC, ECS, RDS, Redis, ALB, CloudFront, Cognito)

AgentCore Runtime is deployed separately via ./deploy.sh agent using the agentcore CLI.

Deploy

cd infra
npm install
./deploy.sh all          # Full deploy (infra + frontend)
./deploy.sh infra        # CDK infrastructure only
./deploy.sh frontend     # Frontend only (~1 min)
./deploy.sh backend      # ECS rolling update (~10s trigger)
./deploy.sh backend-full # Full CDK deploy with env var changes
./deploy.sh agent        # Deploy AgentCore Runtime agent
./deploy.sh status       # Show current endpoints

Deploy AgentCore Runtime

The agent can run on Amazon Bedrock AgentCore Runtime for auto-scaling. It uses direct_code_deploy via the agentcore CLI — no Docker/ECR needed.

cd infra
./deploy.sh agent              # Deploy agent to AgentCore Runtime
./deploy.sh agent --dry-run    # Preview without deploying

For local testing:

cd backend
agentcore configure --entrypoint app/agent/agentcore_app.py --name zmead_agent
agentcore launch --local   # Starts local runtime on port 8080

After deploying, update backend/.env (or ECS env vars):

AGENTCORE_RUNTIME_ENABLED=true
AGENTCORE_RUNTIME_ARN=arn:aws:bedrock-agentcore:us-west-2:ACCOUNT:runtime/zmead_agent-xxxxx
AGENTCORE_LOCAL_MODE=false

DNS Configuration

Record	Type	Target
`zmead.com`	CNAME	CloudFront distribution
`www.zmead.com`	CNAME	CloudFront distribution
`api.zmead.com`	CNAME	ALB domain
`docs.zmead.com`	CNAME	Docs CloudFront distribution

Environment Variables

Backend (`backend/.env`)

See backend/.env.example for the full list. Key variables:

# Database & Cache
DATABASE_URL=mysql+aiomysql://user:pass@localhost:3306/zmead
REDIS_URL=redis://localhost:6379/0

# AWS
AWS_REGION=us-west-2
S3_BUCKET_NAME=zmead-deliverables

# Auth (Google + GitHub + Cognito)
GOOGLE_CLIENT_ID=xxx
GOOGLE_CLIENT_SECRET=xxx
GITHUB_CLIENT_ID=xxx
GITHUB_CLIENT_SECRET=xxx
COGNITO_USER_POOL_ID=xxx
COGNITO_CLIENT_ID=xxx
JWT_SECRET_KEY=change-me

# AgentCore Runtime (optional)
AGENTCORE_RUNTIME_ENABLED=false
AGENTCORE_RUNTIME_URL=http://localhost:8080
AGENTCORE_LOCAL_MODE=true

# AgentCore Memory (optional)
AGENTCORE_MEMORY_ID=your-memory-id
AGENTCORE_MEMORY_REGION=us-west-2

# Knowledge Base Publishing
CLOUDFRONT_DISTRIBUTION_ID=           # Docs CloudFront ID
KNOWLEDGE_PUBLIC_DOMAIN=docs.zmead.com

Frontend (`frontend/.env`)

VITE_API_BASE_URL=http://localhost:8000/api
VITE_WS_BASE_URL=ws://localhost:8000/api/ws
VITE_GOOGLE_CLIENT_ID=xxx
VITE_GITHUB_CLIENT_ID=xxx

Project Structure

├── backend/
│   ├── app/
│   │   ├── agent/              # Strands Agent + tools + skills
│   │   │   ├── config.py       # Model IDs, system prompts
│   │   │   ├── zmead_agent.py  # Main agent class
│   │   │   ├── agentcore_app.py # AgentCore Runtime entry point
│   │   │   ├── memory.py       # AgentCore Memory integration
│   │   │   ├── tools/          # 15 agent tools (class-based, @tool)
│   │   │   └── skills/         # 6 installed skill packs (SKILL.md)
│   │   ├── core/               # Config, database, auth, redis, s3, email
│   │   ├── models/             # SQLAlchemy ORM models
│   │   ├── routers/            # FastAPI route handlers (16 routers)
│   │   ├── schemas/            # Pydantic request/response schemas
│   │   └── services/           # Business logic layer
│   ├── migrations/             # SQL migration files (001_, 002_, ...)
│   └── tests/                  # pytest test suite
├── frontend/
│   └── src/
│       ├── components/         # Reusable UI components (17+)
│       ├── contexts/           # React contexts (Auth)
│       ├── hooks/              # Custom hooks (useWebSocket)
│       ├── pages/              # Route pages (15 pages)
│       ├── services/           # API client
│       └── types/              # TypeScript definitions
└── infra/                      # AWS CDK infrastructure
    ├── deploy.sh               # Unified deployment script
    └── lib/
        └── zmead-stack.ts      # VPC, ECS, RDS, Redis, ALB, CloudFront, Cognito

API Routes

Prefix	Router	Description
`/api/auth`	auth	Google, GitHub, Cognito OAuth + JWT
`/api/conversations`	conversations	Chat sessions CRUD
`/api/ws`	websocket	Real-time agent streaming
`/api/library`	library	Deliverables management
`/api/templates`	templates	Conversation starters
`/api/knowledge`	knowledge	Knowledge base CRUD + publish
`/api/portal`	portal	Public knowledge portal
`/api/tasks`	tasks	Task management
`/api/projects`	projects	Project organization
`/api/analytics`	analytics	Usage metrics and trends
`/api/admin`	admin	User management
`/api/mcp`	mcp	MCP server management
`/api/skills`	skills	Agent skill management
`/api/upload`	upload	File uploads
`/api/presigned-url`	presigned_url	S3 presigned URLs

Estimated Costs

Service	Monthly
NAT Gateway	~$32
RDS t4g.micro	~$12
ElastiCache t4g.micro	~$12
ECS Fargate (512 CPU)	~$15
ALB	~$16
CloudFront (x2)	~$2
Total	~$89/month

AI model costs (Bedrock pay-per-use) are additional and depend on usage volume.

License

MIT

Name		Name	Last commit message	Last commit date
backend		backend
frontend		frontend
infra		infra
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
THIRD-PARTY-LICENSES		THIRD-PARTY-LICENSES
docker-compose.dev.yml		docker-compose.dev.yml
init_requrements.md		init_requrements.md

Navigation Menu

Uh oh!

Repository files navigation

Zmead AI

Features

Agent Tools

Agent Skills

MCP Integration

Platform Features

Tech Stack

Backend (Python 3.12+)

AI / Agent

Frontend (TypeScript)

Architecture

Dual Execution Modes

Local Development

Prerequisites

Backend

Frontend

Testing

Deployment

Deploy

Deploy AgentCore Runtime

DNS Configuration

Environment Variables

Backend (`backend/.env`)

Frontend (`frontend/.env`)

Project Structure

API Routes

Estimated Costs

License

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Zmead AI

Features

Agent Tools

Agent Skills

MCP Integration

Platform Features

Tech Stack

Backend (Python 3.12+)

AI / Agent

Frontend (TypeScript)

Architecture

Dual Execution Modes

Local Development

Prerequisites

Backend

Frontend

Testing

Deployment

Deploy

Deploy AgentCore Runtime

DNS Configuration

Environment Variables

Backend (backend/.env)

Frontend (frontend/.env)

Project Structure

API Routes

Estimated Costs

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Backend (`backend/.env`)

Frontend (`frontend/.env`)