How pushkrjain/multi_agent_ai works
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 Super-agent server · parser.py Intent parser · client.py CLI caller · deploy_agents.sh LXC deployment
Components 18
RPC Surface
- CLI caller · Interactive request dispatcher.
client.py - Agent RPC contract
shared/protos/agent.proto - Generated gRPC bindings
agent_pb2_grpc.py - Super-agent server · Receives requests and returns task results.
server.py
Agent Runtime
- Intent parser
mid_agents/intent/parser.py - Intent errors
mid_agents/intent/errors/__init__.py - API validation
utils/api_validator.py - Shared errors
utils/errors.py - Weather agent · Uses weather providers with fallback behavior.
task_agents/weather.py - News agent · Uses news providers with fallback behavior.
task_agents/news.py - Translation agent · Uses DeepL for translation tasks.
task_agents/translation.py
Observability
- Error monitor · Tracks agent uptime and API errors.
mid_agents/monitoring/error_monitor.py - Prometheus · Scrapes metrics and stores local TSDB state.
prometheus.yml
Linux Control Plane
- eBPF monitor
agent_monitor.bpf - Kernel agent · Intended shared object is absent from the tree.
kagent.c
Deployment
- LXC deployment
deployment/deploy_agents.sh - Weather LXC profile
deployment/lxc_profiles/weather.conf
Other components
- External provider APIs · Credentialed weather, news, and translation services.
Connections 19
- 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