👥 AI Analyst Crew

Multi-agent competitive analysis system powered by CrewAI — three specialized agents (Researcher, Analyst, Writer) collaborate sequentially to turn a company name into a polished report, with live progress streamed to the browser.

---

🎯 What It Does

This is the difference between an agent and a crew.

A single agent loops through think-act-observe by itself. A crew is multiple specialized agents, each with a distinct role, goal, and personality, handing work off to one another — the way a real team operates.

Input: a company name (+ optional focus area)

Research Analyst   → searches the web, gathers current facts
        ↓ (output becomes input)
Market Analyst      → turns research into a SWOT-style analysis
        ↓ (both outputs become input)
Senior Business Writer → writes the final polished report

Each agent only does its job. The framework handles passing one agent's completed work into the next agent's context automatically — that's CrewAI's core mechanism.

---

📸 Screenshots

Live agent progress — UI Real-time status board showing each agent transition from waiting → working → done as the crew executes.

Final report output — UI The completed report alongside expandable research notes and SWOT analysis from each intermediate agent.

Agent handoff — Terminal Verbose CrewAI execution log — Research Analyst completing its task and handing off to the Market Analyst in real time.

---

✨ Features

• True multi-agent collaboration — three agents with distinct roles, goals, and backstories, not one agent wearing different hats
• Sequential task handoff — CrewAI's context=[task] mechanism passes one agent's output directly into the next agent's prompt, no manual prompt-stitching
• Live progress streaming — SSE endpoint streams agent start/finish events to the browser in real time, not just a final blocking response
• Tool-using agent — the Research Analyst uses a live Tavily web search tool to ground its findings in current information
• Streamlit dashboard integration — a 4th tab in the broader integrated UI shows per-agent status badges updating live as the crew works
• Resilient to provider quirks — works around a confirmed upstream CrewAI/Groq compatibility bug (documented below)

---

📡 API Reference

POST /analysis/

Blocking endpoint — runs the full crew, returns the complete result at once.

{
  "company": "Anthropic",
  "focus": "AI safety and enterprise adoption"
}

{
  "company": "Anthropic",
  "research_notes": "...",
  "analysis": "...",
  "final_report": "..."
}

POST /analysis/stream

SSE endpoint — streams agent progress events as they happen, then a final result event.

data: {"event": "agent_start", "agent": "Research Analyst"}
data: {"event": "task_done", "agent": "Research Analyst", "preview": "..."}
data: {"event": "agent_start", "agent": "Market Analyst"}
data: {"event": "task_done", "agent": "Market Analyst", "preview": "..."}
data: {"event": "agent_start", "agent": "Senior Business Writer"}
data: {"event": "task_done", "agent": "Senior Business Writer", "preview": "..."}
data: {"event": "result", "research_notes": "...", "analysis": "...", "final_report": "..."}
data: [DONE]

This is what powers the live status board in the Streamlit UI — each event updates one agent's badge from waiting to working to done as it actually happens, not simulated.

---

🧠 How the Crew Works

Three agents, one process, sequential handoff.

The Research Analyst is given a goal — find current facts about the company — and one tool, a live Tavily web search. It's instructed to search at least twice with different queries before concluding.

The Market Analyst receives the Research Analyst's complete output as context (via CrewAI's context=[research_task] parameter) and turns it into a structured SWOT analysis. It has no web search tool — its job is reasoning over what was already found, not searching for new information.

The Senior Business Writer receives both previous outputs as context and produces the final polished report. It never touches raw research — only the already-analyzed material.

Process.sequential tells CrewAI to run these three tasks strictly in order, each one waiting for the previous to finish. CrewAI also supports Process.hierarchical, where a manager agent dynamically delegates work — a natural next step for this project.

---

🏗️ Architecture

Client (Streamlit or Swagger)
        │
        ▼
FastAPI Router (/analysis)
        │
        ├── /            → run_analysis()           — blocking
        └── /stream       → run_analysis_streaming() — SSE generator
                │
                ▼
        CrewAI Crew (Process.sequential)
                │
        ┌───────┼────────┐
        ▼       ▼        ▼
   Researcher Analyst  Writer
        │
        ▼
   Tavily Web Search (tool)
        │
        ▼
   Groq / LLaMA (shared LLM backend for all 3 agents)

Key design decisions:

• One shared LLM instance across all agents — keeps configuration (model, temperature, API key) centralized in one place rather than repeated per agent.
• Background thread + queue for streaming — CrewAI's kickoff() is a blocking call by design. To stream progress, the crew runs in a background thread while the main request thread polls an event queue and yields SSE events as they arrive.
• Task callbacks as the event source — CrewAI fires a callback automatically when each Task completes. Hooking into that callback is what drives the entire live progress system, no polling or guesswork involved.
• Tool access scoped to the role that needs it — only the Research Analyst has web search. This mirrors how real teams work and keeps each agent's responsibility narrow and predictable.

---

🗂️ Project Structure

ai-analyst-crew/
├── main.py                 # App entry, router registration
├── schemas/
│   ├── __init__.py
│   └── analysis.py          # AnalysisRequest, AnalysisResponse
├── services/
│   ├── __init__.py
│   ├── tools.py              # Tavily web search tool
│   └── crew.py                # Agents, Tasks, Crew, streaming generator
├── routers/
│   ├── __init__.py
│   └── analysis.py            # POST /analysis/ and /analysis/stream
├── .env.example
└── .gitignore

---

🧠 Technical Highlights

Three agents, three distinct roles

researcher = Agent(role="Research Analyst", goal="Find accurate, current information",
                    tools=[web_search], llm=llm)
analyst    = Agent(role="Market Analyst", goal="Analyze findings into SWOT", llm=llm)
writer     = Agent(role="Senior Business Writer", goal="Write the final report", llm=llm)

Output handoff — the core CrewAI mechanism

analysis_task = Task(
    description="Analyze the research notes into a SWOT analysis...",
    agent=analyst,
    context=[research_task]   # ← research_task's output is injected automatically
)

Live progress via task callbacks + background thread

research_task.callback = lambda output: event_queue.put(
    {"event": "task_done", "agent": "Research Analyst", "preview": output.raw[:200]}
)
# crew.kickoff() runs in a background thread; main thread streams the queue as SSE

Known upstream issue — documented and worked around

# CrewAI bug #5886: cache_breakpoint metadata injected into every message
# regardless of provider. Only Anthropic's adapter strips it — Groq rejects it.
import crewai.llms.cache as _crewai_cache
_crewai_cache.mark_cache_breakpoint = lambda msg: msg

---

🚀 Getting Started

Prerequisites

• Python 3.11+
• Groq API key — free
• Tavily API key — free, 1000 searches/month

Installation

git clone https://github.com/vyavahare-kishor/ai-analyst-crew
cd ai-analyst-crew

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
source .venv/bin/activate
uv install

Configuration

cp .env.example .env

# .env
GROQ_API_KEY=your_groq_api_key_here
TAVILY_API_KEY=your_tavily_api_key_here

Run

uvicorn main:app --reload --port 8002

Open http://localhost:8002/docs for the blocking endpoint, or connect the Streamlit dashboard for the live streaming view.

Quick test

curl -X POST http://localhost:8002/analysis/ \
  -H "Content-Type: application/json" \
  -d '{"company": "Anthropic", "focus": "enterprise AI adoption"}'

---

🗺️ Roadmap

• [ ] Process.hierarchical — add a manager agent that dynamically delegates instead of fixed sequential order
• [ ] More specialist agents — competitor benchmarking agent, financial data agent
• [ ] Persist reports — save completed analyses to PostgreSQL for history/reuse
• [ ] Agent observability — trace every agent decision with CrewAI's built-in tracing
• [ ] Docker + deployment

---

🔗 Related Projects

Part of an AI-native engineering portfolio — built while transitioning from Ruby on Rails to AI Engineering, deliberately covering different agent paradigms across projects:

| Project | Description | Agent paradigm | |---------|-------------|-----------------| | ai-research-agent | Autonomous single-agent web research | LangGraph ReAct — one agent, tool loop | | ai-analyst-crew (this) | Multi-agent competitive analysis | CrewAI — multiple roles, sequential handoff | | ai-customer-support-bot | RAG-grounded support answers | Retrieval pipeline, not agentic | | ai-document-analyser | Conversational PDF analysis | RAG + conversation memory | | ai-pr-reviewer | AI-powered GitHub PR review | Structured LLM output, no agent loop | | streamlit-ui-integrated-ai-prj | Unified frontend across all services | — |

---

👨‍💻 Author

Kishor Vyavahare Senior Software Engineer → AI Native Engineer

11+ years of backend engineering (Ruby on Rails, PostgreSQL, Redis, AWS, Kubernetes). Now building production AI systems — RAG pipelines, ReAct agents, multi-agent crews, and LLM-powered APIs.

---

📄 License

MIT License — use it, fork it, build on it.