# pushkrjain/multi_agent_ai architecture

> Architecture diagram of the GitHub repository pushkrjain/multi_agent_ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pushkrjain/multi_agent_ai
- Repository: https://github.com/pushkrjain/multi_agent_ai

## Overview

#### Purpose and execution surface
This is a Python-based hierarchical agent system for routing natural-language requests to weather, news, or translation task agents. Its operational entry points are the gRPC server in `server.py` and CLI caller in `client.py`. The RPC contract is defined in `shared/protos/agent.proto` and materialized as `agent_pb2.py` / `agent_pb2_grpc.py`.

#### Request transport and service boundary
Clients send an `AgentMessage` containing caller identity, UTF-8 query payload, urgency, and optional audit trail through `AgentService.SendAgentMessage`. `client.py` is the interactive dispatch side; `server.py` hosts the gRPC service and returns a payload result. TLS certificates are present as `server.crt`; the README describes TLS deployment, although matching shared certificate paths are not in this tree.

#### Orchestration and intent routing
The server acts as the super-agent boundary: it receives a request, invokes intent classification/parsing, then delegates to a task-specific agent. Intent interpretation is centered in `mid_agents/intent/parser.py`, with intent-related errors under `mid_agents/intent/errors/__init__.py`. Validation and shared exception semantics are separated into `utils/api_validator.py` and `utils/errors.py`.

#### Task execution layer
Task agents encapsulate integrations and fallback behavior for their domains:
- Weather: `task_agents/weather.py`
- News: `task_agents/news.py`
- Translation: `task_agents/translation.py`

These agents are the external-service boundary and rely on environment-provided API credentials. Supported providers include WeatherAPI/OpenWeatherMap, NewsAPI/NewsData/CurrentsAPI, and DeepL. Results are returned upward as response text rather than exposing provider-specific protocols to the gRPC client.

#### Monitoring and operational feedback
Python-level availability/error tracking is implemented in `mid_agents/monitoring/error_monitor.py`. Prometheus scrape configuration is in `prometheus.yml`, and the checked-in `data/` WAL/chunk files indicate a local Prometheus TSDB runtime state. Monitoring exposes agent uptime and API-error metrics for Prometheus collection.

#### Kernel and eBPF control plane
The repository includes low-level Linux observability/control artifacts: `agent_monitor.c`, compiled/loadable `agent_monitor.bpf`, and `kagent.c`. The intended compiled kernel-agent shared object is `super_agent/kagent.so`, though it is absent from the tree. This layer targets Kali Linux/WSL2-compatible Linux hosts, requires BPF filesystem/kernel headers, and is operationally separate from Python RPC routing.

#### Deployment assumptions
The system runs as cooperating local processes: gRPC server, Prometheus, optional loaded eBPF program/kernel shared object, and CLI client. Container-oriented deployment support exists in `deployment/deploy_agents.sh` and `deployment/lxc_profiles/weather.conf`, indicating LXC may isolate or deploy agents. External APIs, Prometheus, Linux BPF facilities, and TLS material are the principal infrastructure dependencies.

Main entry points: [`server.py`](https://github.com/pushkrjain/multi_agent_ai/blob/main/server.py) (Super-agent server), [`mid_agents/intent/parser.py`](https://github.com/pushkrjain/multi_agent_ai/blob/main/mid_agents/intent/parser.py) (Intent parser), [`client.py`](https://github.com/pushkrjain/multi_agent_ai/blob/main/client.py) (CLI caller), [`deployment/deploy_agents.sh`](https://github.com/pushkrjain/multi_agent_ai/blob/main/deployment/deploy_agents.sh) (LXC deployment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rpc["RPC Surface"]
  node_cli["CLI caller<br/>Python CLI<br/>[client.py]"]
  node_proto["Agent RPC contract<br/>Protobuf<br/>[agent.proto]"]
  node_grpc_stubs["Generated gRPC bindings<br/>Python protobuf<br/>[agent_pb2_grpc.py]"]
  node_server["Super-agent server<br/>Python gRPC service<br/>[server.py]"]
end

subgraph group_agents["Agent Runtime"]
  node_intent_parser["Intent parser<br/>Routing logic<br/>[parser.py]"]
  node_intent_errors["Intent errors<br/>Exceptions<br/>[__init__.py]"]
  node_validation["API validation<br/>[api_validator.py]"]
  node_shared_errors["Shared errors<br/>Exceptions<br/>[errors.py]"]
  node_weather["Weather agent<br/>Task agent<br/>[weather.py]"]
  node_news["News agent<br/>Task agent<br/>[news.py]"]
  node_translation["Translation agent<br/>Task agent<br/>[translation.py]"]
end

subgraph group_observability["Observability"]
  node_error_monitor["Error monitor<br/>Python monitoring<br/>[error_monitor.py]"]
  node_prometheus[("Prometheus<br/>Metrics collector<br/>[prometheus.yml]")]
end

subgraph group_kernel["Linux Control Plane"]
  node_ebpf_program{{"eBPF monitor<br/>Linux BPF artifact<br/>[agent_monitor.bpf]"}}
  node_kernel_agent{{"Kernel agent<br/>Linux kernel component<br/>[kagent.c]"}}
end

subgraph group_deployment["Deployment"]
  node_lxc_deploy["LXC deployment<br/>Deployment automation<br/>[deploy_agents.sh]"]
  node_lxc_weather["Weather LXC profile<br/>[weather.conf]"]
end

node_external_apis{{"External provider APIs<br/>Infrastructure dependency"}}

node_cli -->|"uses"| node_grpc_stubs
node_grpc_stubs -->|"implements"| node_proto
node_cli -->|"SendAgentMessage"| node_server
node_server -->|"classifies request"| node_intent_parser
node_server -->|"validates message"| node_validation
node_intent_parser -.->|"raises"| node_intent_errors
node_server -.->|"uses"| node_shared_errors
node_intent_parser -->|"weather intent"| node_weather
node_intent_parser -->|"news intent"| node_news
node_intent_parser -->|"translation intent"| node_translation
node_weather -->|"weather APIs"| node_external_apis
node_news -->|"news APIs"| node_external_apis
node_translation -->|"DeepL"| node_external_apis
node_server -->|"reports availability/errors"| node_error_monitor
node_error_monitor -->|"exposes metrics"| node_prometheus
node_prometheus -.->|"scrapes"| node_server
node_ebpf_program -->|"Linux observability/control"| node_kernel_agent
node_lxc_deploy -->|"uses profile"| node_lxc_weather
node_lxc_deploy -.->|"deploys agents"| node_server

click node_cli "https://github.com/pushkrjain/multi_agent_ai/blob/main/client.py"
click node_proto "https://github.com/pushkrjain/multi_agent_ai/blob/main/shared/protos/agent.proto"
click node_grpc_stubs "https://github.com/pushkrjain/multi_agent_ai/blob/main/agent_pb2_grpc.py"
click node_server "https://github.com/pushkrjain/multi_agent_ai/blob/main/server.py"
click node_intent_parser "https://github.com/pushkrjain/multi_agent_ai/blob/main/mid_agents/intent/parser.py"
click node_intent_errors "https://github.com/pushkrjain/multi_agent_ai/blob/main/mid_agents/intent/errors/__init__.py"
click node_validation "https://github.com/pushkrjain/multi_agent_ai/blob/main/utils/api_validator.py"
click node_shared_errors "https://github.com/pushkrjain/multi_agent_ai/blob/main/utils/errors.py"
click node_weather "https://github.com/pushkrjain/multi_agent_ai/blob/main/task_agents/weather.py"
click node_news "https://github.com/pushkrjain/multi_agent_ai/blob/main/task_agents/news.py"
click node_translation "https://github.com/pushkrjain/multi_agent_ai/blob/main/task_agents/translation.py"
click node_error_monitor "https://github.com/pushkrjain/multi_agent_ai/blob/main/mid_agents/monitoring/error_monitor.py"
click node_prometheus "https://github.com/pushkrjain/multi_agent_ai/blob/main/prometheus.yml"
click node_ebpf_program "https://github.com/pushkrjain/multi_agent_ai/blob/main/agent_monitor.bpf"
click node_kernel_agent "https://github.com/pushkrjain/multi_agent_ai/blob/main/kagent.c"
click node_lxc_deploy "https://github.com/pushkrjain/multi_agent_ai/blob/main/deployment/deploy_agents.sh"
click node_lxc_weather "https://github.com/pushkrjain/multi_agent_ai/blob/main/deployment/lxc_profiles/weather.conf"

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_cli,node_proto,node_grpc_stubs,node_server toneBlue
class node_intent_parser,node_intent_errors,node_validation,node_shared_errors,node_weather,node_news,node_translation toneAmber
class node_error_monitor,node_prometheus toneMint
class node_ebpf_program,node_kernel_agent toneRose
class node_lxc_deploy,node_lxc_weather toneIndigo
class node_external_apis toneNeutral
```

## Components

### RPC Surface

- [CLI caller](https://github.com/pushkrjain/multi_agent_ai/blob/main/client.py): Python CLI · Interactive request dispatcher. · `client.py`
- [Agent RPC contract](https://github.com/pushkrjain/multi_agent_ai/blob/main/shared/protos/agent.proto): Protobuf · `shared/protos/agent.proto`
- [Generated gRPC bindings](https://github.com/pushkrjain/multi_agent_ai/blob/main/agent_pb2_grpc.py): Python protobuf · `agent_pb2_grpc.py`
- [Super-agent server](https://github.com/pushkrjain/multi_agent_ai/blob/main/server.py): Python gRPC service · Receives requests and returns task results. · `server.py`

### Agent Runtime

- [Intent parser](https://github.com/pushkrjain/multi_agent_ai/blob/main/mid_agents/intent/parser.py): Routing logic · `mid_agents/intent/parser.py`
- [Intent errors](https://github.com/pushkrjain/multi_agent_ai/blob/main/mid_agents/intent/errors/__init__.py): Exceptions · `mid_agents/intent/errors/__init__.py`
- [API validation](https://github.com/pushkrjain/multi_agent_ai/blob/main/utils/api_validator.py): Validation · `utils/api_validator.py`
- [Shared errors](https://github.com/pushkrjain/multi_agent_ai/blob/main/utils/errors.py): Exceptions · `utils/errors.py`
- [Weather agent](https://github.com/pushkrjain/multi_agent_ai/blob/main/task_agents/weather.py): Task agent · Uses weather providers with fallback behavior. · `task_agents/weather.py`
- [News agent](https://github.com/pushkrjain/multi_agent_ai/blob/main/task_agents/news.py): Task agent · Uses news providers with fallback behavior. · `task_agents/news.py`
- [Translation agent](https://github.com/pushkrjain/multi_agent_ai/blob/main/task_agents/translation.py): Task agent · Uses DeepL for translation tasks. · `task_agents/translation.py`

### Observability

- [Error monitor](https://github.com/pushkrjain/multi_agent_ai/blob/main/mid_agents/monitoring/error_monitor.py): Python monitoring · Tracks agent uptime and API errors. · `mid_agents/monitoring/error_monitor.py`
- [Prometheus](https://github.com/pushkrjain/multi_agent_ai/blob/main/prometheus.yml): Metrics collector · Scrapes metrics and stores local TSDB state. · `prometheus.yml`

### Linux Control Plane

- [eBPF monitor](https://github.com/pushkrjain/multi_agent_ai/blob/main/agent_monitor.bpf): Linux BPF artifact · `agent_monitor.bpf`
- [Kernel agent](https://github.com/pushkrjain/multi_agent_ai/blob/main/kagent.c): Linux kernel component · Intended shared object is absent from the tree. · `kagent.c`

### Deployment

- [LXC deployment](https://github.com/pushkrjain/multi_agent_ai/blob/main/deployment/deploy_agents.sh): Deployment automation · `deployment/deploy_agents.sh`
- [Weather LXC profile](https://github.com/pushkrjain/multi_agent_ai/blob/main/deployment/lxc_profiles/weather.conf): LXC profile · `deployment/lxc_profiles/weather.conf`

### Other components

- **External provider APIs**: Infrastructure dependency · Credentialed weather, news, and translation services.

## Connections

- CLI caller → Generated gRPC bindings: uses
- Generated gRPC bindings → Agent RPC contract: implements
- CLI caller → Super-agent server: SendAgentMessage
- Super-agent server → Intent parser: classifies request
- Super-agent server → API validation: validates message
- Intent parser → Intent errors: raises
- Super-agent server → Shared errors: uses
- Intent parser → Weather agent: weather intent
- Intent parser → News agent: news intent
- Intent parser → Translation agent: translation intent
- Weather agent → External provider APIs: weather APIs
- News agent → External provider APIs: news APIs
- Translation agent → External provider APIs: DeepL
- Super-agent server → Error monitor: reports availability/errors
- Error monitor → Prometheus: exposes metrics
- Prometheus → Super-agent server: scrapes
- eBPF monitor → Kernel agent: Linux observability/control
- LXC deployment → Weather LXC profile: uses profile
- LXC deployment → Super-agent server: deploys agents
