# pawannagarwal/multi-agent-ai-system-for-web-search-and-financial-analysis architecture

> Architecture diagram of the GitHub repository pawannagarwal/multi-agent-ai-system-for-web-search-and-financial-analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pawannagarwal/multi-agent-ai-system-for-web-search-and-financial-analysis
- Repository: https://github.com/pawannagarwal/multi-agent-ai-system-for-web-search-and-financial-analysis

## Overview

1. **Repository shape**
   - This is a very small Python project centered around a single runtime script, `financial_agent.py`.
   - There is no separate frontend, backend service, database, or package hierarchy visible in the repository tree, so the architecture is essentially a **single-process agent orchestrator**.

2. **Core orchestration layer**
   - `financial_agent.py` is the main entrypoint and likely contains the agent definitions, tool wiring, and the execution flow for answering user queries.
   - The script appears to coordinate multiple AI agents rather than implement a traditional application server.

3. **Multi-agent boundary**
   - The system is organized around at least two conceptual agents:
     - a **Web Search Agent**
     - a **Financial Agent**
   - These are separate responsibilities with different toolsets, but they are combined under one orchestration layer to handle broader queries.

4. **Web search subsystem**
   - The web search side uses **DuckDuckGo** as the retrieval source.
   - Its role is to gather general web information and return results with sources, making it the external knowledge-retrieval path for non-financial questions or supporting evidence.

5. **Financial data subsystem**
   - The finance side uses **YFinanceTools** to retrieve stock-related data.
   - Based on the README, it can access:
     - stock prices
     - analyst recommendations
     - company fundamentals
     - company news
   - This is the structured-data path for finance-specific analysis.

6. **LLM / reasoning layer**
   - The project uses the **Phi framework** to build and manage the agents.
   - It also uses **Groq** as the model provider, which implies the reasoning and response generation happen through an external LLM API rather than a local model.

7. **Data flow**
   - A user query enters the Python script.
   - The orchestrator routes the request to the appropriate agent or agents.
   - Each agent calls its external tool(s) — DuckDuckGo or Yahoo Finance APIs via YFinanceTools.
   - Retrieved data is passed back to the LLM for synthesis into a final response.
   - The financial agent presents some outputs in **table format**, indicating a structured presentation step after retrieval.

8. **External service boundaries**
   - The important runtime dependencies are all outside the repo:
     - **Groq** for model inference
     - **DuckDuckGo** for web search
     - **Yahoo Finance** via YFinanceTools for market data
   - The architecture therefore depends on network access and the availability of third-party APIs/services.

9. **Configuration and secrets**
   - The presence of `.env` strongly suggests API keys and runtime configuration are injected via environment variables.
   - This means credentials and model/provider settings are not hardcoded into the script, but managed externally from the codebase.

10. **Packaging and dependencies**
   - `requirements.txt` defines the Python dependency boundary.
   - That file likely captures Phi, Groq client libraries, and the tool libraries needed for search and finance retrieval.
   - No containerization or deployment descriptors are visible, so the repo appears intended for local execution or lightweight scripting use.

11. **Likely architectural style**
   - The overall style is **tool-augmented LLM agents** rather than deterministic business logic.
   - The main computation is retrieval + reasoning + synthesis, with the LLM acting as the decision and response layer.

12. **What to draw in an architecture diagram**
   - A single Python application box containing:
     - agent orchestration
     - web search agent
     - financial agent
   - Outbound arrows from the agents to:
     - Groq LLM API
     - DuckDuckGo search
     - Yahoo Finance / YFinanceTools
   - A configuration arrow from `.env` into the Python app.
   - The final output should be shown as a synthesized natural-language answer, sometimes including tables and citations/sources.

Main entry points: [`financial_agent.py`](https://github.com/pawannagarwal/multi-agent-ai-system-for-web-search-and-financial-analysis/blob/main/financial_agent.py) (financial_agent.py), [`.env`](https://github.com/pawannagarwal/multi-agent-ai-system-for-web-search-and-financial-analysis/blob/main/.env) (.env)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Python app"]
  node_financial_agent_py["financial_agent.py<br/>entrypoint orchestrator<br/>[financial_agent.py]"]
end

subgraph group_agents["Agents"]
  node_web_search_agent(("Web search agent<br/>retrieval agent"))
  node_financial_analysis_agent(("Financial agent<br/>analysis agent"))
end

subgraph group_external["External services"]
  node_llm_reasoning["Phi + Groq<br/>LLM runtime"]
  node_duckduckgo["DuckDuckGo<br/>web search API"]
  node_yfinance_tools["YFinanceTools<br/>market data tools"]
  node_env_config[".env<br/>runtime config<br/>[.env]"]
end

node_user_query(("User query<br/>input"))
node_synthesized_answer["Final answer<br/>response"]

node_user_query -->|"submit request"| node_financial_agent_py
node_env_config -->|"configure"| node_financial_agent_py
node_financial_agent_py -->|"route web tasks"| node_web_search_agent
node_financial_agent_py -->|"route finance tasks"| node_financial_analysis_agent
node_web_search_agent -->|"search"| node_duckduckgo
node_financial_analysis_agent -->|"fetch market data"| node_yfinance_tools
node_web_search_agent -->|"reason over results"| node_llm_reasoning
node_financial_analysis_agent -->|"reason over data"| node_llm_reasoning
node_financial_agent_py -->|"coordinate"| node_llm_reasoning
node_llm_reasoning -->|"generate response"| node_synthesized_answer
node_financial_analysis_agent -.->|"format tables"| node_synthesized_answer

click node_financial_agent_py "https://github.com/pawannagarwal/multi-agent-ai-system-for-web-search-and-financial-analysis/blob/main/financial_agent.py"
click node_env_config "https://github.com/pawannagarwal/multi-agent-ai-system-for-web-search-and-financial-analysis/blob/main/.env"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_financial_agent_py toneBlue
class node_web_search_agent,node_financial_analysis_agent toneAmber
class node_llm_reasoning,node_duckduckgo,node_yfinance_tools,node_env_config toneMint
class node_user_query,node_synthesized_answer toneNeutral
```

## Components

### Python app

Single-process agent orchestrator and runtime entrypoint.

- [financial_agent.py](https://github.com/pawannagarwal/multi-agent-ai-system-for-web-search-and-financial-analysis/blob/main/financial_agent.py): entrypoint orchestrator · Main script that wires agents, tools, and response flow. · `financial_agent.py`

### Agents

Conceptual agents coordinated by the entrypoint.

- **Web search agent**: retrieval agent · Handles general web queries and source-backed retrieval.
- **Financial agent**: analysis agent · Handles market and company analysis using financial tools.

### External services

Third-party APIs and runtime dependencies used by the agents.

- **Phi + Groq**: LLM runtime · Framework and model provider used for agent reasoning and synthesis.
- **DuckDuckGo**: web search API · External search source for web retrieval and citations.
- **YFinanceTools**: market data tools · Retrieves stock prices, recommendations, fundamentals, and news.
- [.env](https://github.com/pawannagarwal/multi-agent-ai-system-for-web-search-and-financial-analysis/blob/main/.env): runtime config · Environment-based configuration and secrets for local execution. · `.env`

### Other components

- **User query**: input · Natural-language request entering the application.
- **Final answer**: response · LLM-synthesized response, sometimes formatted with tables and sources.

## Connections

- User query → financial_agent.py: submit request · A query enters the single-process Python app.
- .env → financial_agent.py: configure · Environment variables provide runtime settings and secrets.
- financial_agent.py → Web search agent: route web tasks · The orchestrator delegates general search-oriented requests.
- financial_agent.py → Financial agent: route finance tasks · The orchestrator delegates market-analysis requests.
- Web search agent → DuckDuckGo: search · Web retrieval is performed through DuckDuckGo.
- Financial agent → YFinanceTools: fetch market data · Finance analysis uses YFinanceTools to access Yahoo Finance data.
- Web search agent → Phi + Groq: reason over results · Retrieved web results are synthesized by the LLM layer.
- Financial agent → Phi + Groq: reason over data · Financial data is interpreted and summarized by the LLM layer.
- financial_agent.py → Phi + Groq: coordinate · The app uses Phi with Groq to manage agent execution and generation.
- Phi + Groq → Final answer: generate response · The reasoning layer produces the final user-facing answer.
- Financial agent → Final answer: format tables · Financial outputs may be presented in table form before delivery.