AI Agents

Overview

AI Agents with MCP and LangGraph is a multi-agent experimentation hub where each agent is designed around a specific real-world workflow. The project demonstrates how autonomous agents can reason, use tools, call APIs, retrieve data, generate content, and coordinate multiple workers through graph-based control flow.

The repository is being organized as an agent platform instead of only a collection of scripts. Experimental agents live inside projects/, while shared platform code lives inside src/ai_agents/.

This gives the project a cleaner path toward:

• a unified FastAPI backend
• a React dashboard for running agents
• shared request and response formats
• centralized configuration
• reusable tools and workflows
• easier testing and contribution

Key Features

• Multi-agent architecture: each agent is separated by responsibility and can evolve independently.
• Supervisor routing: the supervisor agent plans the task, selects only the needed workers, and sends work through ordered routes.
• Tool-aware worker nodes: worker agents can call tools through LangGraph ToolNode routing and then resume their own reasoning.
• Shared core layer: common schemas, base interface, registry, and configuration helpers.
• LangGraph workflows: graph-based control flow for reliable agentic systems.
• LangChain integration: LLM orchestration, tool calling, prompts, and chains.
• MCP tooling: Model Context Protocol support for connecting agents with external tools.
• Extensible structure: new agents can be added without rewriting the whole project.

Agent Overview

Supervisor Agent

The new projects/supervisor workflow demonstrates a proper supervisor-worker graph.

Flow:

User Input
   |
Supervisor
   |-- creates a plan
   |-- selects ordered worker routes
   v
Worker Agent
   |-- coding
   |-- research
   |-- weather
   v
Tool Routing
   |-- if the worker requests a tool, run ToolNode
   |-- return to the same worker after tool output
   v
Synthesizer
   |
Final Answer

Current worker nodes:

• coding: programming, debugging, architecture, and code explanations
• research: fact gathering, comparison, and general research-style reasoning
• weather: weather-related questions using the available weather tool

The supervisor returns a structured route list, for example:

routes = ["research", "coding"]

Each selected worker runs in order. If a worker calls a tool, tool_routing() sends the graph to ToolNode, then route_after_tool() returns the graph back to the worker that requested the tool. Once all selected workers finish, the synthesizer creates one final response.

Run it:

cd projects/supervisor
python app.py

Required environment variables:

OPENROUTER_API_KEY=replace_me
OPENROUTER_BASE_URL=replace_me

Project Structure

Ai_agents/
|-- src/
|   `-- ai_agents/
|       |-- core/
|       |   |-- base.py
|       |   |-- registry.py
|       |   `-- schemas.py
|       |-- config/
|       |   `-- settings.py
|       `-- cli.py
|-- projects/
|   |-- scraper/
|   |-- podcast/
|   |-- stock/
|   |-- github/
|   |-- notion/
|   |-- agentic_rag/
|   |-- orchestration_workers/
|   |-- supervisor/
|   |-- travel/
|   `-- deep_agent/
|-- public/
|-- projects/requirements.txt
|-- pyproject.toml
`-- README.md

src/ai_agents/

This is the shared platform layer. It contains common contracts, configuration helpers, and registry logic used by future production-ready agents.

projects/

This contains the experimental agents. These agents can be gradually migrated into the shared architecture without breaking the current code.

Core Architecture

The target platform flow is:

User Input
   |
AgentRequest
   |
Agent Registry
   |
Selected Agent
   |
Tools / APIs / LLM / MCP
   |
AgentResponse
   |
CLI / FastAPI / Frontend

Every mature agent should eventually follow this contract:

class MyAgent(BaseAgent):
    info = AgentInfo(
        name="My Agent",
        slug="my-agent",
        description="What this agent does",
        tools=["tool-a", "tool-b"],
    )

    def run(self, request: AgentRequest) -> AgentResponse:
        ...

Tech Stack

• Python: core programming language
• LangGraph: agent workflow orchestration
• LangChain: LLM application framework
• MCP SDK: tool integration using Model Context Protocol
• Pydantic: typed request and response schemas
• python-dotenv: local environment loading
• Streamlit: UI layer for selected agents
• External APIs: research, scraping, audio, finance, GitHub, Notion, and weather integrations

Installation

1. Clone the repository

git clone [email protected]:jenasuraj/Ai_agents.git

2. Move into the project

cd Ai_agents

3. Create a virtual environment

python -m venv venv

4. Activate the virtual environment

For Windows:

venv\Scripts\activate

For macOS/Linux:

source venv/bin/activate

5. Install dependencies

pip install -r projects/requirements.txt

For editable development:

pip install -e .

Environment Variables

Keep your real keys only in a local .env file. The repository ignores .env files by default.

Example pattern:

OPENAI_API_KEY=replace_me
OPENROUTER_API_KEY=replace_me
OPENROUTER_BASE_URL=replace_me
TAVILY_API_KEY=replace_me

Only add the keys required by the agent you are running.

Usage

Run an existing experimental agent:

cd projects/scraper
python main.py

Run the supervisor agent:

cd projects/supervisor
python app.py

Run the platform CLI:

python -m ai_agents.cli

Some agents may use Streamlit:

streamlit run app.py

Adding a New Agent

Recommended structure:

projects/my-new-agent/
|-- main.py
|-- tools.py
|-- prompts.py
|-- graph.py
`-- README.md

A good agent should have:

• a clear goal
• typed input and output
• well-defined tools
• proper error handling
• clean prompt design
• documentation explaining how to run it

For production-style agents, use the shared base classes inside src/ai_agents/core/.

Roadmap

• Migrate each existing agent to the shared BaseAgent interface
• Add a unified FastAPI backend for all agents
• Add a frontend dashboard for selecting and running agents
• Add per-agent README files
• Add tests for registry and core workflows
• Add Docker support
• Add tracing and logging
• Add deployment guide

Author

Suraj Jena

• LinkedIn: Suraj Jena
• X/Twitter: @jenasuraj_