AI Agent Service

Orchestrator architecture

flowchart LR
    subgraph API
        A[POST /api/chat]
    end
    subgraph GeneralController
        B[chat]
        C[_stream_events]
        D[_save_conversation]
    end
    subgraph GeneralAgent
        E[InMemorySessionService]
        F[getConversationsListTool<br/>MCP tools]
        G[LlmAgent orchestrator]
        H[MentalHealth LlmAgent]
        I[Orthopedic LlmAgent]
    end
    subgraph Runner
        J[run_async]
    end
    subgraph External
        K[MCP server]
        L[Conversation API<br/>save / summaries / semantic-search]
    end

    A --> B
    B --> E
    B --> G
    G --> F
    G --> H
    G --> I
    B --> J
    J --> G
    F --> K
    C --> J
    C --> D
    D --> L

Loading

Project Structure

├── main.py                  # Entry point
├── settings.py              # Configuration (reads from .env)
├── requirements.txt         # Python dependencies
├── app/
│   ├── server.py            # FastAPI app setup & route registration
│   ├── routes/              # API endpoints
│   │   ├── route.py
│   ├── agents/              # AI agent implementations
│   │   └── rule_review_agent/
│   │       ├── agent.py         # Core agent logic
│   │       ├── runner.py        # Execution wrapper
│   │       ├── executor.py      # A2A protocol handler
│   │       ├── request_handler.py # A2A app setup
│   │       ├── agent_card.py    # A2A agent metadata
│   │       └── knowledge/
│   │           └── prompts.py   # System prompts
│   ├── services/            # Business logic services
│   ├── controllers/         # Controller layer
│   ├── config/              # DB connections, configs
│   ├── middleware/          # Auth, response wrappers
│   ├── models/              # Data models
│   └── utils/               # Utilities
└── tests/                   # Test files

ADK Web UI (development)

To see and test the general orchestrator agent in the ADK web interface:

1. Install the ADK CLI (if not already): pip install google-adk
2. From the project root (this directory), run:

   adk web --port 8000

   If port 8000 is in use, use another port, e.g. adk web --port 8001.
3. Open http://127.0.0.1:8000 in your browser.
4. In the web UI, select the general_orchestrator agent from the dropdown (top left), then chat.

The agent is discovered from the general_orchestrator/ folder, which exposes root_agent for the ADK CLI. Your main app (FastAPI on port 7777) is unchanged and can still be used for production or custom frontends.

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

Create a .env file with your API keys:

GOOGLE_API_KEY=your_google_api_key
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key

3. Run the Server

python main.py

Or with uvicorn directly:

uvicorn app.server:app --reload

4. Access the API

• API Docs: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

Creating a New Agent

To create a new agent, follow this structure:

app/agents/my_new_agent/
├── __init__.py
├── agent.py               # Core agent logic
├── runner.py              # Execution wrapper
├── executor.py            # A2A executor (if A2A enabled)
├── request_handler.py     # A2A app setup (if A2A enabled)
├── agent_card.py          # A2A metadata (if A2A enabled)
└── knowledge/
    ├── __init__.py
    └── prompts.py         # System prompts

Agent Components

1. agent.py: Contains the core agent logic, LLM integration, and response processing
2. runner.py: Wraps the agent with timeout handling, error handling, and batch processing
3. executor.py: Handles A2A protocol messages and formats responses
4. request_handler.py: Sets up FastAPI endpoints for A2A communication
5. agent_card.py: Defines agent metadata for A2A discovery
6. knowledge/prompts.py: System prompts and templates

Running Tests

pytest tests/ -v

With coverage:

pytest tests/ --cov=app --cov-report=html

Configuration Options

Variable	Description	Default
HOST	Server host	0.0.0.0
PORT	Server port	8000
DEBUG	Debug mode	True
DEFAULT_MODEL	Default LLM model	gemini-2.0-flash
MAX_AGENT_ITERATIONS	Max agent iterations	10
AGENT_TIMEOUT	Agent timeout (seconds)	300
A2A_ENABLED	Enable A2A protocol	True

License

MIT

Project Structure

/
├── main.py                  # Entry point
├── settings.py              # Configuration (reads from .env)
├── requirements.txt         # Python dependencies
├── app/
│   ├── server.py            # FastAPI app setup & route registration
│   ├── routes/              # API endpoints
│   │   ├── route.py
│   ├── agents/              # AI agent implementations
│   │   └── rule_review_agent/
│   │       ├── agent.py         # Core agent logic
│   │       ├── runner.py        # Execution wrapper
│   │       ├── executor.py      # A2A protocol handler
│   │       ├── request_handler.py # A2A app setup
│   │       ├── agent_card.py    # A2A agent metadata
│   │       └── knowledge/
│   │           └── prompts.py   # System prompts
│   ├── services/            # Business logic services
│   ├── controllers/         # Controller layer
│   ├── config/              # DB connections, configs
│   ├── middleware/          # Auth, response wrappers
│   ├── models/              # Data models
│   └── utils/               # Utilities
└── tests/                   # Test files

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

Create a .env file with your API keys:

GOOGLE_API_KEY=your_google_api_key
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key

3. Run the Server

python main.py

Or with uvicorn directly:

uvicorn app.server:app --reload

4. Access the API

• API Docs: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

Creating a New Agent

To create a new agent, follow this structure:

app/agents/my_new_agent/
├── __init__.py
├── agent.py               # Core agent logic
├── runner.py              # Execution wrapper
├── executor.py            # A2A executor (if A2A enabled)
├── request_handler.py     # A2A app setup (if A2A enabled)
├── agent_card.py          # A2A metadata (if A2A enabled)
└── knowledge/
    ├── __init__.py
    └── prompts.py         # System prompts

Agent Components

1. agent.py: Contains the core agent logic, LLM integration, and response processing
2. runner.py: Wraps the agent with timeout handling, error handling, and batch processing
3. executor.py: Handles A2A protocol messages and formats responses
4. request_handler.py: Sets up FastAPI endpoints for A2A communication
5. agent_card.py: Defines agent metadata for A2A discovery
6. knowledge/prompts.py: System prompts and templates

Running Tests

pytest tests/ -v

With coverage:

pytest tests/ --cov=app --cov-report=html

Configuration Options

Variable	Description	Default
HOST	Server host	0.0.0.0
PORT	Server port	8000
DEBUG	Debug mode	True
DEFAULT_MODEL	Default LLM model	gemini-2.0-flash
MAX_AGENT_ITERATIONS	Max agent iterations	10
AGENT_TIMEOUT	Agent timeout (seconds)	300
A2A_ENABLED	Enable A2A protocol	True

Agent Evaluation Test

Run Tests

PYTHONPATH=. pytest evals/

License

MIT