Network Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
The Network Troubleshooting system acts as an automated "first responder" for your infrastructure, identifying why services are down or performance is degraded. It allows network engineers to describe a problem in plain English and receive a diagnostic report grounded in real-time device state and historical evidence.
The platform functions as a self-hosted AI Network Engineer that provides deep analysis across multi-vendor environments, including Cisco (IOS, IOS-XE, NX-OS), Juniper, Arista, Palo Alto, Fortinet, and F5. Every diagnostic step is visible, and all AI decisions are explained and audited to ensure transparency for the operations team.
Sources: CLAUDE.md:3-13, README.md:1-5, backend/app/agents/troubleshooting/agent.py:11-20
Overview
The Troubleshooting system is designed to solve complex operational issues by routing questions to specialized "team members" known as agents. For troubleshooting specifically, this means analyzing routing tables, BGP sessions, OSPF adjacencies, and Access Control Lists (ACLs) to find the root cause of a fault.
Key Capabilities
- Protocol Analysis: Deep inspection of BGP peer states, OSPF neighbor relationships, and routing table entries.
- Security Impact: Analyzing ACLs and firewall policies to determine if traffic is being blocked by a specific rule.
- Multi-Vendor Support: Standardized troubleshooting across Cisco, Juniper, Arista, and cloud environments like AWS and Azure.
- Human-Centric Design: Every diagnostic conclusion is explained with specific evidence citations.
Sources: CLAUDE.md:18-32, backend/app/agents/troubleshooting/agent.py:133-145, backend/app/llm/prompts/init.py:228-245
Design Philosophy
The platform adheres to a "local-first" and "secure by default" philosophy. It is self-hosted to ensure sensitive network data never leaves your infrastructure. Furthermore, while the Troubleshooting Agent is strictly read-only (meaning it cannot change device configurations), any remediations it suggests must be approved by a human before being executed by the Automation system.
Sources: CLAUDE.md:34-40, backend/app/agents/troubleshooting/agent.py:11-15
Platform Architecture
The platform consists of seven core components that work together to provide a seamless troubleshooting experience.
| Component | Description |
|---|---|
| Frontend | The operations console where engineers chat with the AI and view topology maps. |
| API | The central brain that handles security, user sessions, and coordinates between agents. |
| Worker | The background engine that runs discovery jobs, takes config backups, and captures packets without blocking your session. |
| Postgres | The system of record that stores historical data and network inventory. |
| Neo4j | A living topology map that tracks how every device, interface, and subnet connects to everything else. |
| Redis | A high-speed temporary storage used for managing background tasks and caching. |
| Ollama | The local engine that allows the AI to "think" and reason about network data without using the cloud. |
Sources: README.md:17-25, deploy/docker/README.md:7-13
Vendor Plugin System
To handle multiple manufacturers, the platform uses a standardized "connector" for each vendor. Whether you are troubleshooting a Cisco router or a Juniper switch, the platform normalizes the raw command output into a consistent format before the AI analyzes it. This ensures that the Troubleshooting Agent treats all hardware with a unified logic.
Sources: README.md:27-30, backend/app/plugins/vendors/cisco_nxos/parsers.py:1-15
Troubleshooting Workflow
The system follows a structured "Symptom → Hypothesis → Diagnosis" flow to ensure technical accuracy. This prevents the AI from "hallucinating" or making up network states that don't exist.
Agent Routing and Specialist Selection
When an engineer sends a request, the Master Architect (the team supervisor) determines which specialist is best suited for the task.
The diagram shows how the Master Architect routes a user's question to the correct specialized team member.
Sources: backend/app/llm/prompts/init.py:270-330, backend/app/agents/troubleshooting/agent.py:186-215
The Diagnostic Loop
The Troubleshooting Agent follows a specific three-step process:
- Symptom Classification: It identifies the domain (BGP, OSPF, ACL, or Routing) and the target device.
- Evidence Gathering: It calls specific read-only tools to pull live state from the device (e.g.,
read_live_bgp_peers). - Grounded Diagnosis: It writes a conclusion that cites every piece of evidence found.
The sequence diagram illustrates the internal logic of an agent gathering evidence before answering.
Sources: backend/app/agents/troubleshooting/agent.py:21-38, backend/app/agents/troubleshooting/agent.py:220-280
Analysis Domains and Tools
The Troubleshooting Agent uses specific tools to inspect different parts of the network stack. All tools are read-only, ensuring that no troubleshooting session can accidentally break a production configuration.
| Domain | Description | Tool Used |
|---|---|---|
| BGP | Inspects peering sessions and Autonomous System (AS) information. | read_live_bgp_peers |
| OSPF | Analyzes neighbor adjacencies and area configurations. | read_live_ospf_neighbors |
| ACL | Checks if traffic is being dropped by specific access lists. | read_live_acls |
| Routing | Looks up specific prefixes and next-hop information in the RIB. | get_device_routes |
Sources: backend/app/agents/troubleshooting/agent.py:100-115, backend/app/agents/troubleshooting/agent.py:133-145
Evidence Citation
Every diagnostic result includes EvidenceRefs. These are citations that point to the exact record pulled from the device. For example, if a route is missing, the agent will cite the specific routing table output it checked. This allows engineers to verify the AI's reasoning against the actual device state.
Sources: backend/app/agents/troubleshooting/agent.py:315-345, backend/app/agents/troubleshooting/agent.py:375-390
Change Approval Workflow
If a troubleshooting session identifies a necessary fix (e.g., adding a missing route), the platform follows a strict approval lifecycle. No agent can execute a change directly on a device.
The flow shows that a human must approve every change, and a backup is always taken before execution.
Sources: README.md:1-10, deploy/docker/README.md:45-55, backend/app/agents/ddi/agent.py:20-35
Conclusion
Network Troubleshooting within this platform provides a high-fidelity diagnostic experience by combining AI reasoning with deterministic evidence collection. By strictly separating read-only analysis from human-approved execution, the platform enables rapid MTTR (Mean Time To Repair) while maintaining the security and stability requirements of enterprise infrastructure. All troubleshooting steps are logged and grounded in the "living topology map" of the network, ensuring that the AI operates as a transparent extension of the engineering team.