examples/showcases/strands-file-analyzer/README.md
AI-powered document analysis demo built with CopilotKit, Strands Agents, and Amazon Bedrock.
What This Is:
What This Is NOT:
Use this to:
npm install
cd agent && uv sync && cd ..
Create agent/.env:
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=us-west-1
npm run dev
This starts:
Multi-File PDF Support:
Real-Time UI Updates:
Conversational Interface:
useCoAgent - State SynchronizationKeeps frontend and Python agent in sync automatically:
const { state, setState } = useCoAgent({
name: "file_investigator",
initialState: INITIAL_STATE,
});
When you upload files on the frontend, they're instantly available to the Python agent. When the agent updates findings, the UI updates immediately.
Why this matters: No manual API calls or state management - CopilotKit handles the bidirectional sync via AG-UI Protocol.
CopilotChat - Conversational UIProvides the chat interface with built-in tool call rendering:
<CopilotChat
labels={{
title: "File Investigator",
initial: "Upload a PDF to begin..."
}}
/>
Why this matters: You get a production-quality chat UI out of the box, with streaming responses and tool call visualization.
useDefaultTool - Custom Tool UIRenders custom components when the agent calls tools:
const defaultTools = [
useDefaultTool({
toolKey: "update_findings",
Component: () => <FindingsCard findings={state.findings} />
})
];
Why this matters: Instead of generic JSON displays, you control exactly how tool outputs appear in the chat.
Strands is a Python framework for building AI agents. It handles the tool-calling loop, state management, and LLM integration.
ag_ui_strands bridges Strands with CopilotKit. It:
from strands import Agent
from ag_ui_strands import StrandsAgent
# Create your Strands agent
strands_agent = Agent(
system="You are the File Investigator...",
model="anthropic/claude-haiku-4-5-20251001"
)
# Add tools
strands_agent.add_tool(update_findings)
strands_agent.add_tool(update_summary)
# Wrap with ag_ui_strands
app = StrandsAgent(
agent=strands_agent,
name="file_investigator",
description="AI document analyst"
).mount(FastAPI())
Why this matters: You write standard Strands tools in Python, and ag_ui_strands automatically makes them work with CopilotKit's frontend.
When you attach a state_from_args callback to a tool, the frontend UI updates automatically:
def update_findings(findings: dict, context) -> str:
"""Agent calls this to update findings panel."""
return "Updated findings"
# This callback syncs state to frontend
update_findings.state_from_args = lambda args, context: {
**get_current_state(context),
"findings": args.get("findings", [])
}
Why this matters: One tool call updates both the agent's logic and the user's UI - no separate API calls needed.
AWS Bedrock has limits:
But users want to upload large files and multiple files together.
Intelligent processing based on file size:
The agent sees all files and analyzes them together, regardless of how they were processed.
┌─────────────────────────────────────────────────────────────┐
│ Next.js Frontend │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ File Upload │ │ Dashboard │ │ CopilotKit Chat │ │
│ │ (multi) │ │ Panels │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
│ │ │
│ useCoAgent (state sync) │
└───────────────────────────┬─────────────────────────────────┘
│ AG-UI Protocol (HTTP + SSE)
┌───────────────────────────┴─────────────────────────────────┐
│ Python Agent │
│ │
│ Strands + ag_ui_strands + FastAPI │
│ │ │
│ Tools: update_findings, update_redacted, │
│ update_tweets, update_summary │
│ │ │
│ Amazon Bedrock │
│ (Claude Haiku) │
└─────────────────────────────────────────────────────────────┘
useCoAgentupdate_findings, update_tweets, etc.├── src/
│ ├── app/
│ │ ├── page.tsx # Main page with useCoAgent + CopilotChat
│ │ ├── layout.tsx # CopilotKit provider
│ │ └── api/copilotkit/route.ts # Runtime configuration
│ ├── components/
│ │ ├── dashboard-panels.tsx # Dashboard UI components
│ │ ├── file-upload.tsx # Multi-file upload
│ │ └── tool-cards.tsx # Tool UI renderers
│ └── types/
│ └── investigator.ts # TypeScript interfaces
├── agent/
│ ├── main.py # Strands agent + ag_ui_strands
│ ├── pdf_utils.py # PDF text extraction
│ └── pyproject.toml # Python dependencies
└── package.json
agent/.env)| Variable | Description |
|---|---|
AWS_ACCESS_KEY_ID | AWS access key for Bedrock |
AWS_SECRET_ACCESS_KEY | AWS secret key |
AWS_REGION | AWS region (default: us-west-1) |
| Variable | Description |
|---|---|
AGENT_URL | Agent URL (default: http://localhost:8000) |
Frontend:
Backend:
| Command | Description |
|---|---|
npm run dev | Start both frontend and agent |
npm run dev:ui | Start frontend only |
npm run dev:agent | Start agent only |
npm run build | Build for production |
npm run lint | Run ESLint |
Agent not connecting:
agent/.envPDF not processing:
State not syncing:
CopilotKit:
Strands Agents:
AWS Bedrock:
MIT
Built by Mark Morgan