Financial Researcher 🔍📈

An AI-powered multi-agent system that researches any publicly traded company and delivers a polished financial analysis report — in minutes.

Built with CrewAI, it orchestrates two specialised AI agents that work in sequence: one scours the web for real-time data, the other synthesises those findings into a professional-grade Markdown report.

---

Table of Contents

• Demo
• How It Works
• CrewAI Concepts Explained
  • Agent
  • Task
  • Crew
  • Process — Sequential vs Hierarchical
  • Tools
• Project Structure
• Agents & Tasks in This Project
• Prerequisites
• Installation
• Configuration
• Running the Crew
• Sample Output
• Contributing
• License

---

Demo

$ crewai run

Enter the company to research: Apple

[Researcher Agent] Searching the web for Apple financial data...
[Analyst Agent] Synthesising research into a comprehensive report...

=== FINAL REPORT ===

# Comprehensive Report on Apple Inc.
As of 2026-03-24 ...

Report has been saved to output/report.md

---

How It Works

┌─────────────────────────────────────────────────────────────┐
│                        USER INPUT                           │
│                   "Enter company name"                      │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    CREW  (Sequential)                       │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  STEP 1 — Research Task                              │   │
│  │  Agent: Senior Financial Researcher                  │   │
│  │  Tool:  SerperDevTool (Google Search)                │   │
│  │  Output: Structured research document                │   │
│  └──────────────────────────┬───────────────────────────┘   │
│                             │  context passed downstream    │
│  ┌──────────────────────────▼───────────────────────────┐   │
│  │  STEP 2 — Analysis Task                              │   │
│  │  Agent: Market Analyst & Report Writer               │   │
│  │  Tool:  (none — works from research context)         │   │
│  │  Output: output/report.md                            │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

---

CrewAI Concepts Explained

🤖 Agent

An Agent is an autonomous AI entity with a specific role, goal, and backstory. Think of it as hiring a specialist for a job — you describe who they are, what they're trying to achieve, and the context that shapes their expertise. Each agent is backed by an LLM and can optionally be equipped with tools to interact with the outside world.

| Property | Purpose | |-------------|---------| | role | The agent's job title / persona (e.g., Senior Financial Researcher) | | goal | What the agent is trying to accomplish | | backstory | Background context that shapes the agent's reasoning style | | llm | The language model powering the agent | | tools | External capabilities the agent can invoke (search, code execution, APIs…) | | verbose | Prints the agent's chain-of-thought reasoning to the console |

# config/agents.yaml
researcher:
  role: Senior Financial Researcher for {company}
  goal: Research the company, news and potential for {company}
  backstory: You're a seasoned financial researcher...
  llm: openai/gpt-4o-mini

---

📋 Task

A Task is a specific piece of work assigned to an agent. It defines what needs to be done, what a successful result looks like, and which agent is responsible. Tasks can receive the output of previous tasks as context, enabling agents to build on each other's work.

| Property | Purpose | |-------------------|---------| | description | Detailed instructions for what to do | | expected_output | Describes what a complete, correct result looks like | | agent | Which agent is assigned to this task | | context | List of prior tasks whose output is fed into this task | | output_file | (Optional) Persist the result to a file |

# config/tasks.yaml
analysis_task:
  description: Analyze the research findings and create a comprehensive report...
  expected_output: A polished, professional report...
  agent: analyst
  context:
    - research_task          # ← analyst reads the researcher's full output
  output_file: output/report.md

---

🚢 Crew

A Crew is the team — it binds agents and tasks together under a shared process (execution strategy). The crew is responsible for scheduling tasks, routing context between them, and collecting the final result.

@crew
def crew(self) -> Crew:
    return Crew(
        agents=self.agents,   # [researcher, analyst]
        tasks=self.tasks,     # [research_task, analysis_task]
        process=Process.sequential,
        verbose=True,
    )

Kickoff the crew with dynamic inputs:

ResearchCrew().crew().kickoff(inputs={"company": "Apple", "date": "2026-03-24"})

---

⚙️ Process — Sequential vs Hierarchical

The Process controls how tasks are executed relative to each other.

Process.sequential (used in this project)

Tasks run one after another, in the order they are defined. The output of each task is automatically passed as context to the next. Simple, predictable, and great for linear pipelines.

Task 1 ──► Task 2 ──► Task 3 ──► Final Result

Process.hierarchical

A designated manager agent (or manager LLM) dynamically delegates tasks to the most suitable agent, decides the order of execution, and reviews outputs. Best for complex, open-ended workflows where the path isn't known upfront.

              Manager Agent
             /      |       \
        Task A   Task B   Task C   (assigned dynamically)
             \      |       /
              Final Result

| Feature | Sequential | Hierarchical | |----------------------|----------------------|----------------------------| | Execution order | Fixed, top-to-bottom | Dynamic delegation | | Manager agent needed | No | Yes | | Complexity | Low | High | | Best for | Linear pipelines | Complex, adaptive workflows |

---

🛠️ Tools

Tools extend an agent's capabilities beyond text generation. They allow agents to interact with the real world — search the web, read files, execute code, call APIs, query databases, and more.

How tools work

1. The agent decides it needs external information
2. It calls the appropriate tool with the required arguments
3. The tool returns results back to the agent
4. The agent incorporates the results into its reasoning

Tools used in this project

| Tool | Source | Purpose | |-----------------|----------------|---------| | SerperDevTool | crewai_tools | Executes real-time Google searches — gives the researcher access to current news, stock data, and filings |

Other popular CrewAI tools

| Tool | Purpose | |---------------------------|---------| | FileReadTool | Read local files | | WebsiteSearchTool | Scrape and search a specific website | | YoutubeVideoSearchTool | Search YouTube transcripts | | CodeInterpreterTool | Execute Python code | | ScrapeWebsiteTool | Extract full HTML content from a URL |

---

Project Structure

financial_researcher/
├── src/
│   └── financial_researcher/
│       ├── __init__.py
│       ├── crew.py          # Agent, Task, and Crew definitions
│       ├── main.py          # Entry point — prompts for company name, kicks off crew
│       └── config/
│           ├── agents.yaml  # Agent personas (role, goal, backstory, llm)
│           └── tasks.yaml   # Task definitions (description, expected output, agent)
├── output/
│   └── report.md            # Generated report (auto-created after each run)
├── pyproject.toml           # Project metadata and dependencies
├── .env                     # Your secret API keys (never commit this!)
├── .env.example             # Template — copy to .env and fill in your keys
└── README.md

---

Agents & Tasks in This Project

Agents

1. Senior Financial Researcher

• Role: Finds and organises raw information about the target company
• LLM: openai/gpt-4o-mini
• Tools: SerperDevTool — performs live Google searches
• Produces: A structured research document covering company health, history, challenges, recent news, and future outlook

2. Market Analyst & Report Writer

• Role: Transforms raw research into a polished, professional report
• LLM: openai/gpt-4o-mini
• Tools: None — works entirely from the researcher's context
• Produces: A well-formatted Markdown report with executive summary, sections, and conclusion

Tasks

| Task | Agent | Input | Output | |-----------------|------------|-----------------------------|-----------------------| | research_task | Researcher | Company name + date | Research document | | analysis_task | Analyst | Research document (context) | output/report.md |

---

Prerequisites

• Python >=3.10 and <3.13
• An OpenAI API key
• A Serper API key — free tier includes 2,500 searches/month

---

Installation

# 1. Clone the repository
git clone https://github.com/your-username/financial-researcher.git
cd financial-researcher/financial_researcher

# 2. Install uv (if not already installed)
pip install uv

# 3. Install project dependencies
crewai install

# 4. Copy the environment template and fill in your keys
copy .env.example .env    # Windows
cp .env.example .env      # macOS / Linux

---

Configuration

Open .env and add your API keys:

OPENAI_API_KEY=sk-...
SERPER_API_KEY=...

To swap the LLM model, edit src/financial_researcher/config/agents.yaml:

researcher:
  llm: openai/gpt-4o-mini   # or: openai/gpt-4o, anthropic/claude-3-5-sonnet, etc.

---

Running the Crew

# Activate the virtual environment
.venv\Scripts\activate          # Windows
source .venv/bin/activate       # macOS / Linux

# Run
crewai run

You will be prompted:

Enter the company to research: Tesla

The crew runs (typically 1–3 minutes) and saves the full report to output/report.md.

---

Sample Output

The output/ directory contains a real example report generated for Apple Inc. as of March 24, 2026.

Sections include:

• Executive Summary
• Current Company Status and Health
• Historical Performance
• Challenges & Opportunities
• Market Outlook
• Conclusion

---

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repo
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

---

License

This project is licensed under the MIT License.

---

Disclaimer: Reports generated by this tool are for informational and educational purposes only. They should not be used as the basis for any financial or investment decisions.