Access Network Config Audit Agent

An MCP server exposing read-only GPON access-network operations, and a LangGraph agent that uses it to audit ONT configuration against a golden baseline.

This runs against a simulated network. There is no real OLT, no real ONT, and no vendor equipment involved. The device layer is a SQLite database seeded with a small synthetic topology. Optical and profile values are modelled on ITU-T G.984 class B+ conventions but are not taken from any operator's production standard. See Limitations.

---

Why this exists

Configuration drift is a real operational problem in broadband access networks: ONTs get provisioned by hand, migrations leave legacy profiles behind, and a mis-set service VLAN can sit undetected until it causes an incident. Auditing it is exactly the kind of repetitive, well-specified work an agent should be good at — if the agent is built so that its findings can be trusted.

This project is an experiment in that "if".

---

Architecture

┌──────────────────┐
│  LangGraph agent │   decides what to inspect, correlates alarms
│  (LLM)           │   with findings, writes the report
└────────┬─────────┘
         │  LangChain StructuredTools (agent/mcp_bridge.py)
┌────────▼─────────┐
│   MCP server     │   5 read-only tools, stdio transport
│  (protocol)      │   read_only_hint=True on every tool
└────────┬─────────┘
         │
    ┌────┴─────┬──────────────┐
    │          │              │
┌───▼────┐ ┌───▼──────────┐ ┌─▼─────────────┐
│ OltAcc │ │ audit engine │ │ golden config │
│ (data) │ │ (pure code)  │ │   (YAML)      │
└────────┘ └──────────────┘ └───────────────┘

---

Three design decisions

1. The LLM does not decide compliance

The comparison between running config and golden baseline happens in audit/engine.py — ordinary, pure, unit-tested Python. The model orchestrates (which devices, which order, how to explain a finding) but never returns the verdict itself.

The reason is that an audit which gives different answers to the same input is not evidence of anything. tests/test_audit.py asserts the engine finds exactly the nine deviations planted by the seed script, and that repeated runs are byte-identical. None of that would be assertable if the logic lived in a prompt.

This also bounds the failure mode: the engine can only report deviations on fields that were actually retrieved, so the agent cannot invent a finding about a device that does not exist.

2. Read-only by design, and the constraint is checked

There is no set_config, no reboot, no provision. The absence is the point. An agent with a write path into a production access network can take subscribers off-line from one bad inference, and a prompt instruction is not a control.

The constraint is enforced at three levels rather than asserted once:

Level	Mechanism
Data layer	OltAccess exposes no write method at all
Protocol	every tool carries read_only_hint=True, destructive_hint=False
Client	MCPToolset.assert_read_only() refuses to start the agent if the server ever advertises a mutating tool

Remediation is emitted as a recommendation for a human to execute through change control. The system prompt forbids claiming an action was applied.

Extending this to writes would need, at minimum: a separate server with its own credentials, an explicit approval step in the call path, a dry-run mode, and per-call audit logging. That is deliberately out of scope.

3. MCP rather than direct function-calling

Binding these five functions straight into one agent's tool schema would have been less code. MCP was chosen because:

• The server is testable on its own. tests/test_mcp_server.py drives it over real stdio with no model involved — the tool contract is verified independently of whichever LLM happens to call it.
• The device layer is swappable without touching the agent. Replacing the simulator with GenieACS, NETCONF, or a vendor CLI means reimplementing OltAccess only.
• The same server is reusable by a different agent, a different model, or an operator's desktop MCP client.
• Capability boundaries are declared in the protocol, not buried in prompt text.

---

Golden baseline

audit/golden_config.yaml is the single source of truth for correct provisioning, versioned alongside the code. An audit result is only defensible if the baseline it was measured against is itself reviewable and diffable.

Severity model:

Severity	Meaning	Example rules
critical	Service-affecting now, or an isolation/security violation	vlan_mismatch, srv_profile_unapproved, admin_disabled, rx_power_out_of_range
major	Policy violation with degraded service or SLA risk	line_profile_unapproved, dba_profile_unapproved, gem_port_count
minor	Hygiene, documentation, or planning deviation	description_convention, distance_exceeded, rx_power_marginal

---

Tool surface

Tool	Purpose
list_onts(olt_id?, pon_port?)	Inventory discovery
get_ont_status(serial)	Operational state, Rx power, ranging distance
get_running_config(serial)	Configuration-bearing fields
diff_against_golden(serial)	Deterministic compliance verdict + findings
get_alarms(olt_id, active_only)	Active/cleared faults for correlation

---

Running it

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 1. Seed the simulated network (2 OLTs, 14 ONTs, 9 planted deviations)
python simulator/seed.py

# 2. Verify every layer — none of these need an API key
python tests/test_audit.py         # audit engine determinism + correctness
python tests/test_mcp_server.py    # MCP contract over real stdio
python tests/test_bridge.py        # MCP -> LangChain conversion + guardrail

# 3. Run the agent (needs an Anthropic API key)
export ANTHROPIC_API_KEY=...
python agent/audit_agent.py --olt OLT-BDG-GGK-01

The MCP server can also be attached to any MCP client directly:

python mcp_server/server.py     # stdio transport

---

Limitations

Stating these plainly matters more than the demo does.

1. The network is simulated. No GPON hardware, no vendor CLI, no OMCI. The simulator models the shape of ONT provisioning data, not any real OLT's command syntax or YANG model.
2. The golden baseline is invented. Profile names, VLAN ranges, and the naming convention are plausible but fictional. A real deployment's baseline would come from the operator's provisioning standard.
3. One use case only. Configuration audit. Fault handling, device configuration, and network optimisation are not implemented.
4. No scale testing. 14 ONTs. A real PON port carries up to 64 ONTs and a regional OLT thousands; per-device tool calls would not be the right shape at that size — a batch audit tool returning aggregated findings would be.
5. Alarm correlation is left to the model. The engine does not join alarms to findings; the agent is asked to notice the overlap. That part is therefore not deterministic, and it is the weakest link in the output.
6. No authentication or authorisation. stdio transport, single local user. Any real deployment needs credential scoping per OLT and per operator role.

---

Layout

simulator/    olt_sim.py    read-only device accessor (swap this for real transport)
              seed.py       synthetic topology with deliberately planted faults
audit/        engine.py     deterministic golden-config diff
              golden_config.yaml
mcp_server/   server.py     5 read-only MCP tools, stdio
agent/        mcp_bridge.py MCP -> LangChain tool conversion + guardrail check
              audit_agent.py LangGraph ReAct agent
tests/        test_audit.py, test_mcp_server.py, test_bridge.py