Pyats Parallel Ops

Parallel Fleet Operations

Runtime and discovery

Use the modern pyATS MCP Streamable HTTP server. For stateless HTTP set PYATS_MCP_TRANSPORT_MODE=stateless on the server. Discover its actual tool schemas before calling tools; an older installed clone may lack native pCalls. The modern server does not support direct STDIO. NetClaw provides scripts/pyats-stdio.py as a compatibility bridge to its stateless HTTP runtime; set PYATS_MCP_SCRIPT to that bridge (see docs/PYATS-HTTP-MIGRATION.md). Merely listing several shell commands does not execute a pyATS pCall.

Start every session with pyats_list_devices using {}. Use returned device names, group by role or site, and confirm the requested scope. Never invent device names or infer current operational state from a saved testbed.

Stateless HTTP describes protocol session handling; it does not mean the server has no caches, operation history, or stored snapshots. Do not depend on snapshots surviving a process restart. Keep configuration initialization disabled for read-only checks (init_config_commands: [] in testbed connection arguments).

Native parallel execution

For process-isolated read-only fan-out, call pyats_pcall_show_command:

{"device_names":["R1","R2","SW1"],"command":"show version"}

This uses pyats.async_.pcall, one child process per device. The response contains per-device results, a summary, and a concurrency field. Verify each result: an outer status: completed does not mean every device succeeded.

pyats_run_show_command_multi provides thread-based fan-out with lower overhead. Use it for routine collection when shared-process behavior is acceptable. Choose native pCall when process isolation is required or explicitly requested. Separate agent calls running concurrently are a third mechanism, not native pCall.

Fleet health workflow

Run one fleet call per command, collecting the results of each wave before the next. Avoid competing connections and commands to the same device.

1. show version — platform, image, uptime.
2. show processes cpu sorted — CPU and top consumers.
3. show ip interface brief — interface and protocol state.
4. Role-appropriate routing checks, such as show ip ospf neighbor or show ip bgp summary, only on devices where those protocols apply.
5. Additional memory, NTP, CDP/LLDP, or log checks appropriate to the platform.

Use the discovered schema and supply device_names and command as above. Show-command tools require a supported show command; do not use shell pipelines, configuration commands, or destructive operations as shortcuts.

Keep raw configurations, topology, testbed credentials, and device output local. Prefer environment references for testbed secrets. Never include credentials in reports, tracked fixtures, or external communications.

Failure handling and reporting

Produce a result for every requested device. A connection failure, timeout, command failure, or parse failure must be visible without discarding successful results. If the server returns an aggregate error, reconcile missing device results explicitly. Retry only appropriate read-only operations with a bounded budget; do not classify a device as healthy because a tool returned HTTP 200.

Raw-output fallback is evidence of command execution, not successful structured parsing. Label it accordingly. Investigate CPU above 90%, unexpected non-FULL OSPF neighbors, and BGP IDLE/ACTIVE peers using additional read-only checks. Do not change configuration to repair a health finding without the change management workflow.

Report severity first, then device, evidence, impact, and recommended action. Include requested/succeeded/failed counts, commands, elapsed time, and any unverified checks. Separate unreachable devices from confirmed unhealthy ones; a timeout alone does not establish production impact or incident severity.