# nshkrdotcom/agent_experiments architecture

> Architecture diagram of the GitHub repository nshkrdotcom/agent_experiments, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nshkrdotcom/agent_experiments
- Repository: https://github.com/nshkrdotcom/agent_experiments

## Overview

##### Project type and purpose
- This is a collection of AI-agent experiments and tooling (“agent_experiments”) written in Python. It includes:
- agent2 and multi_tool_agent packages (core agent implementations)
- an MCP client (“mcp/mcp-client”) with command-line interface, engine, configuration, and services layers
- a sample microservice (“mcp/weather”) demonstrating an external tool the agent can call
- The purpose is to explore multi-agent patterns, external service adapters, and configurable workflows for AI agents.

##### File structure
- Top level:
– agent2/agent2.py (a standalone agent prototype)
– multi_tool_agent/agent.py (another standalone agent)
– mcp/
· mcp-client/ (a reusable client library & CLI for MCP-style agents)
· weather/ (a simple HTTP-style service module the client can query)
- mcp-client sub-structure follows a modular layout:
– cli.py (entrypoint for user commands)
– engine.py (orchestrator that drives agent workflows)
– services.py (abstraction layer for calling out to external systems or microservices)
– config.py + workflows.json + mcp_servers.json (configuration for endpoints & workflows)
– app_logger.py (logging framework)
- mcp/weather contains a main.py and weather.py, showing how an external service can be spun up or invoked.

##### README
- Confirms this is an experimental suite for “MCP, Google ADK, and related AI agent experiments.”

##### Detail
- Break out mcp-client into its submodules (cli, engine, services, config, logger)
- Sample workflows.json driving the engine
- Weather service as an example microservice block

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["CLI User"]:::cli

    %% CLI Layer
    subgraph "CLI Layer"
        CLI["mcp-client/cli.py"]:::cli
    end

    %% Agent Engine & Core Agents
    subgraph "Agent Engine & Core"
        Engine["mcp-client/engine.py"]:::core
        Agent2["agent2/agent2.py"]:::core
        MultiTool["multi_tool_agent/agent.py"]:::core
    end

    %% Service Adapters
    subgraph "Service Adapters"
        Services["mcp-client/services.py"]:::services
    end

    %% Configuration & Logging
    subgraph "Config & Logging"
        Config["mcp-client/config.py"]:::config
        Workflows["workflows.json"]:::config
        Servers["mcp_servers.json"]:::config
        Logger["app_logger.py"]:::config
    end

    %% External Systems
    subgraph "External Systems"
        MCPServers["MCP Servers"]:::external
        LLM["LLM APIs (Google ADK, Claude, Gemini)"]:::external
        subgraph "Weather Microservice"
            WeatherMain["mcp/weather/main.py"]:::external
            WeatherLogic["mcp/weather/weather.py"]:::external
        end
    end

    %% Connections
    User -->|invokes| CLI
    CLI -->|parses & reads config| Config
    CLI -->|hands off| Engine
    Engine -->|loads workflows| Workflows
    Engine -->|loads servers| Servers
    Engine -->|uses logger| Logger
    Engine -->|calls| Agent2
    Engine -->|calls| MultiTool
    Engine -->|calls adapters| Services
    Services -->|invokes| MCPServers
    Services -->|invokes| LLM
    Services -->|HTTP calls| WeatherMain
    WeatherMain -->|executes logic| WeatherLogic
    Services -->|responses| Engine
    Engine -->|returns results| CLI

    %% Click Events
    click Agent2 "https://github.com/nshkrdotcom/agent_experiments/blob/main/agent2/agent2.py"
    click MultiTool "https://github.com/nshkrdotcom/agent_experiments/blob/main/multi_tool_agent/agent.py"
    click CLI "https://github.com/nshkrdotcom/agent_experiments/blob/main/mcp/mcp-client/cli.py"
    click Engine "https://github.com/nshkrdotcom/agent_experiments/blob/main/mcp/mcp-client/engine.py"
    click Services "https://github.com/nshkrdotcom/agent_experiments/blob/main/mcp/mcp-client/services.py"
    click Config "https://github.com/nshkrdotcom/agent_experiments/blob/main/mcp/mcp-client/config.py"
    click Workflows "https://github.com/nshkrdotcom/agent_experiments/blob/main/mcp/mcp-client/workflows.json"
    click Servers "https://github.com/nshkrdotcom/agent_experiments/blob/main/mcp/mcp-client/mcp_servers.json"
    click Logger "https://github.com/nshkrdotcom/agent_experiments/blob/main/mcp/mcp-client/app_logger.py"
    click WeatherMain "https://github.com/nshkrdotcom/agent_experiments/blob/main/mcp/weather/main.py"
    click WeatherLogic "https://github.com/nshkrdotcom/agent_experiments/blob/main/mcp/weather/weather.py"

    %% Styles
    classDef cli fill:#e0ffe0,stroke:#333,stroke-width:1px
    classDef core fill:#e0f0ff,stroke:#333,stroke-width:1px
    classDef services fill:#d0e7ff,stroke:#333,stroke-width:1px
    classDef config fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef external fill:#ffe0b0,stroke:#333,stroke-width:1px
```
