An AI agent that can only talk isn't much use to an ACI operations team. It can summarize a fault log you paste in, sure — but it can't tell you Leaf-104's health score right now, and it definitely shouldn't be pushing a contract change just because it "reasoned" its way there. What separates a chatbot from something you'd actually let near APIC is tools — the functions an agent is allowed to call to read from, act on, or talk about your fabric.
This post breaks down how tools work in an AI agent, using Cisco ACI as the running example throughout, so the concepts map directly onto things you already manage — health scores, contracts, EPGs, and change windows.
Why "Just Talking" Isn't Enough on ACI
Picture an agent with no tools at all:
Agent: "I think Leaf-104 might be unhealthy, but I have no way to check."
Not useful. Now give it a single tool that can query APIC's health score API:
Agent: [calls
get_node_health(node="Leaf-104")] → "Leaf-104's health score is 62. Two contract-related faults are currently active on this leaf."
Same question, completely different value. That's the entire point of tools — they turn an agent from something that speculates into something that can actually verify against the fabric's real state.
The Four Tool Categories, Mapped to ACI
Every tool an ACI-aware agent might use falls into one of four buckets. Knowing which bucket a task belongs to tells you immediately how much oversight it needs.
1. Retrieval Tools — Read-Only Lookups
These pull information without changing anything: health scores, fault counts, contract relationships, endpoint locations.
ACI examples:
get_node_health(node)— pull a leaf or spine's current health scoreget_epg_faults(epg)— list active faults on a given EPGget_endpoint_location(ip_or_mac)— find which leaf/port an endpoint is learned onget_contract_relationships(tenant, epg)— list which contracts an EPG consumes/provides
Retrieval tools are the safest category — an agent can call these freely without much risk, which is exactly why they're the easiest place to start trusting AI in ACI operations.
2. Execution Tools — Tools That Change the Fabric
These make actual changes: pushing a contract, modifying a Bridge Domain setting, restarting a service, triggering a firmware upgrade. Because ACI's policy model propagates changes fabric-wide, execution tools deserve the most design care of any category.
ACI examples:
deploy_contract(tenant, epg_consumer, epg_provider, filter, mode)update_bridge_domain(tenant, bd, setting, value, mode)trigger_firmware_upgrade(node, target_version, mode)
Notice the repeated mode parameter — more on that below. It's the single most important detail in an ACI execution tool's design.
3. Communication Tools — Looping in Humans
These don't touch the fabric at all — they notify people. Sending a Slack alert about a degraded leaf, opening a ServiceNow ticket for a recurring fault, paging the on-call engineer when a Multi-Site link drops.
ACI examples:
send_slack_alert(channel, message)— e.g., posting when a leaf's health score drops below thresholdcreate_servicenow_ticket(summary, severity, affected_tenant)page_oncall(team, reason)— for something like an APIC cluster losing quorum
These tools are how an agent stays useful even when it shouldn't act on its own — escalating to a human is often the correct behavior, not a fallback.
4. Perception Tools — Making Sense of Raw Data
These interpret information rather than fetch or change it: parsing a wall of fault codes into a plain-English summary, correlating a traffic spike with a recent contract change, summarizing a week of APIC audit logs.
ACI examples:
summarize_faults(tenant, time_range)— turn 200 raw fault codes into three actionable findingscorrelate_traffic_anomaly(epg, time_range)— check if a spike lines up with a recent policy pushparse_audit_log(node, time_range)— extract what actually changed and who changed it
Perception tools are what let an agent reason well before it decides whether a retrieval or execution tool is even needed.
How the Agent Actually Picks a Tool
The agent doesn't understand ACI the way you do — it reads tool descriptions and matches them against the question. This is why the wording of a tool's description matters as much as the code behind it.
Say someone asks: "Is EPG WEB-EPG healthy right now?"
The agent scans its available tools and finds get_epg_faults described as "Retrieve current fault count and severity for a given EPG." That's a strong match — it extracts WEB-EPG as the input and calls it.
A vague description like "Gets ACI stuff" would leave the agent guessing between three different tools that all sound plausible. A precise description — naming exactly what the tool returns and for what object type — is what makes tool selection reliable instead of a coin flip.
Anatomy of an ACI Tool Schema
Take deploy_contract as a worked example of what a well-designed execution tool schema looks like:
- Name:
deploy_contract— the unique identifier the agent calls - Description: "Push a contract between two EPGs in a tenant. Warning: makes real fabric changes." — the explicit warning matters; it tells the agent (and anyone reviewing its plan) that this isn't a harmless lookup
- Input schema:
tenant— which tenant this applies toepg_consumer/epg_provider— the two EPGs the contract connectsfilter— the port/protocol filter being appliedmode— constrained to an enum of"preview"or"apply", defaulting to"preview"
That last field is the load-bearing detail. A default of preview means the agent's first call only shows what would happen — the actual zoning-rule programming on the leaves doesn't happen until a human (or a separate, explicit step) chooses apply.
Schema design principles worth carrying into any ACI tool you build:
- Write descriptions specific enough that two tools never sound interchangeable
- Type every input (don't let a device ID be passed as a free-text string with no validation)
- Use enums to constrain choices like
mode,severity, orscope - Default to the safe option, never the destructive one
- Mark required fields so the agent can't fire a call with the tenant or EPG left blank
Safety Considerations for ACI-Facing Tools
A tool that can act on a shared fabric needs guardrails baked in from the start — not bolted on after the first incident.
Destructive actions. A tool like update_bridge_domain can affect flooding or ARP behavior fabric-wide. Mitigation: default to preview mode, require explicit confirmation before applying, and never let an agent's very first call against a tool be a live push.
Credential exposure. If a tool logs its inputs and one of those inputs happens to include an APIC admin token or a TACACS credential passed through for auth, that's a real exposure. Mitigation: never log sensitive fields — scrub credentials before anything gets written to a log or a transcript.
Ineffective guardrails. A tool scoped to "manage the entire fabric" is too broad — it hands an agent far more blast radius than any single task requires. Mitigation: scope each tool tightly — a contract-deployment tool shouldn't also be able to touch fabric access policies.
Cascading failures. ACI workflows chain tool calls — the output of a health check might feed into whether a firmware upgrade proceeds. If one tool returns bad or stale data, a downstream tool can act on it. Mitigation: build rollback into any tool that changes state, and don't let a single failed check silently get treated as a pass.
The Validation Pipeline Before Anything Executes
Before an execution tool is allowed to actually touch APIC, three checks should pass, in order:
- Schema compliance — Are all required fields present and correctly typed? If
tenantis missing ormodeisn't one of the allowed enum values, reject the call before it goes anywhere near the fabric. - Authorization — Does this user or agent identity actually have permission to call this tool? An agent scoped to read-only monitoring shouldn't be able to invoke
deploy_contractat all, regardless of what it "decides" to do. - Safety checks — Is this action allowed right now? A change-freeze window, an active P1 incident, or an in-progress firmware upgrade are all reasons to block an otherwise-valid call.
Only after all three pass should the tool actually run against APIC.
Quick Reference: Tool Category vs. Oversight Needed
| Category | ACI Example | Oversight Level |
|---|---|---|
| Retrieval | get_node_health, get_epg_faults | Minimal — safe to run freely |
| Execution | deploy_contract, update_bridge_domain | High — preview mode, confirmation, rollback |
| Communication | send_slack_alert, page_oncall | Low — but should avoid alert fatigue |
| Perception | summarize_faults, correlate_traffic_anomaly | Low — but accuracy matters, since downstream decisions rely on it |
Final Thoughts
Tools are what make an AI agent useful on a real ACI fabric instead of just a chatbot that can describe what a health score is. The four categories — retrieval, execution, communication, perception — map cleanly onto operations work you already do every day. The schema design determines whether tool selection is reliable or a guessing game. And the safety layer — preview-by-default execution, tight scoping, credential hygiene, and a validation pipeline before anything runs — is what determines whether you'd actually trust an agent near production APIC.
None of this replaces your judgment. It's what lets an agent earn a little bit of it, one well-scoped tool at a time.
FAQ
Q: Should an AI agent ever have direct, unsupervised write access to APIC? A: Generally no. Execution tools should default to preview mode and require explicit confirmation before applying, with authorization and safety checks run before every call — the same discipline you'd want from any junior engineer making fabric changes.
Q: What's the biggest mistake in designing ACI tool schemas for an agent? A: Vague tool descriptions. If two tools' descriptions sound interchangeable, the agent will eventually pick the wrong one — and on ACI, the wrong tool call can mean a fabric-wide policy change instead of a simple status check.
Q: Are perception tools (like fault summarization) risky the same way execution tools are? A: Not in the same way — they don't change the fabric — but their accuracy still matters, because a bad summary can lead a human or a downstream tool call to the wrong conclusion.
Related Reading on Networklearner:
- AI Planning Strategies for Cisco ACI Engineers: ReAct, Plan-and-Execute, and Tree of Thoughts in the Fabric
- AI Agent Reasoning Loop (ReAct) Explained for Network Engineers
- AI Agent Perception and Context Windows Explained for Network Engineers
- Understanding AI Agents for Network Engineers: LLMs, Prompts, Tokens and Context Explained
- Agentic AI for Network Engineers: What It Actually Means
- Reactive Automation vs Generative AI vs Agentic AI in Networking
- More posts on Networklearner
Need help with Cisco ACI, Nexus, data center networking, or network automation?
I am a CCIE Data Center engineer with 18+ years of enterprise networking experience, working hands-on with production ACI fabrics.
Contact me for consulting, troubleshooting, design reviews, and project support: rockingoa@gmail.com
No comments:
Post a Comment