diff --git a/coffeeAGNTCY/agentic_patterns/README.md b/coffeeAGNTCY/agentic_patterns/README.md index b30482ca9..c2fd49d14 100644 --- a/coffeeAGNTCY/agentic_patterns/README.md +++ b/coffeeAGNTCY/agentic_patterns/README.md @@ -19,3 +19,6 @@ The agentic_patterns directory provides a starting point and reference for agent ### Agent Recruiter - `AGENTS.MD`, `README.md` +### Gateway (Multi-Platform MCP Aggregation) +- `AGENTS.MD`, `README.md` + diff --git a/coffeeAGNTCY/agentic_patterns/gateway/AGENTS.md b/coffeeAGNTCY/agentic_patterns/gateway/AGENTS.md new file mode 100644 index 000000000..b1a993694 --- /dev/null +++ b/coffeeAGNTCY/agentic_patterns/gateway/AGENTS.md @@ -0,0 +1,136 @@ +# Gateway Pattern Agents + +The Gateway Pattern enables autonomous agents to compose multi-platform +workflows through a single MCP gateway. The following agents demonstrate how +upstream consumers leverage the gateway to accomplish tasks spanning multiple +platform servers. + +## NOC Copilot Agent + +**Role**: Autonomous triage and incident management for network operations. + +**Workflow**: Monitors correlation engine alerts continuously. When triggered, +auto-pulls CMDB context to identify affected devices and services, checks the +ITSM platform for open changes or related incidents, runs diagnostics through +the monitoring platform, drafts an incident with full root cause analysis, and +escalates only when human approval is needed for remediation. Transforms L1 NOC +from reactive to supervisory. + +**Gateway interactions**: + +- Correlation Engine: subscribe to alerts, query correlated events +- CMDB Server: resolve device context, map dependencies +- ITSM Server: check open changes, create incidents, update resolution +- Monitoring Server: pull device health, interface diagnostics +- Configuration Server: apply remediation (requires HITL approval) +- Chat Server: post status updates to operations channel + +## Security Orchestration Agent + +**Role**: Automated threat detection, correlation, and containment across +security and network platforms. + +**Workflow**: Subscribes to security platform events, correlates lateral movement +indicators across security and network monitoring tools, calculates blast radius +via the CMDB, quarantines compromised endpoints through access control, blocks +command-and-control domains on the firewall, creates a P1 incident, and posts a +summary to the security operations channel. Human approval gates protect +destructive containment actions. + +**Gateway interactions**: + +- Security Server: detect threats, retrieve indicators of compromise +- Monitoring Server: correlate network anomalies with security events +- CMDB Server: map blast radius, identify affected assets +- Access Control Server: quarantine endpoints (requires HITL approval) +- Firewall Server: block domains (requires HITL approval) +- ITSM Server: create P1 incident +- Chat Server: post summary to SecOps channel + +## Change Validation Agent + +**Role**: Automated pre/post change verification across all platforms. + +**Workflow**: Before a maintenance window, captures baseline snapshots of health +scores, telemetry, and configuration state across every platform via the +gateway. After the change, re-runs the same queries, diffs the results, and +flags regressions. Writes before/after evidence to the ITSM change record. + +**Gateway interactions**: + +- All platform servers: snapshot health, telemetry, configuration state +- Correlation Engine: capture risk score baseline, compare post-change +- ITSM Server: attach before/after evidence to change record +- Chat Server: notify operations of validation results + +## Capacity Planning Agent + +**Role**: Proactive infrastructure capacity analysis and forecasting. + +**Workflow**: Periodically queries monitoring platforms for device utilization, +wireless density, path capacity, and rack space. Feeds historical telemetry +through the correlation engine's prediction capabilities. Generates quarterly +reports and creates proactive change requests before capacity thresholds are +breached. + +**Gateway interactions**: + +- Monitoring Server: device utilization, interface capacity +- Observability Server: wireless density, path metrics +- CMDB Server: rack space, power budgets +- Correlation Engine: trend analysis, threshold prediction +- ITSM Server: create proactive change requests + +## Compliance Auditor Agent + +**Role**: Scheduled compliance evidence collection and violation detection. + +**Workflow**: Runs on a defined schedule, systematically queries every platform +for compliance evidence (certificate expiry, endpoint posture, configuration +drift, access policy consistency, vulnerability exposure). Compiles findings, +flags violations, and compares against the last audit run. This agent has +read-only TBAC permissions across all servers. + +**Gateway interactions**: + +- All platform servers: read-only queries for compliance evidence +- Security Server: certificate expiry, vulnerability exposure +- Access Control Server: endpoint posture, policy consistency +- Configuration Server: configuration drift detection +- ITSM Server: file compliance reports, flag violations + +## Multi-Vendor Orchestration Agent + +**Role**: Cross-vendor agent coordination using AGNTCY discovery. + +**Workflow**: Discovers the gateway's MCP servers via the AGNTCY Agent Directory +alongside MCP servers from other vendors (cloud providers, third-party security, +SaaS platforms). Queries the gateway for campus and WAN telemetry while +simultaneously querying external MCP servers for cloud-side metrics. Correlates +across all sources. The gateway becomes one piece of a larger agent ecosystem, +demonstrating AGNTCY's Internet of Agents vision. + +**Gateway interactions**: + +- Agent Directory: discover gateway and external vendor MCP servers +- All gateway platform servers: campus/WAN queries +- External MCP servers: cloud/SaaS queries (outside gateway) +- Correlation Engine: cross-vendor event fusion + +## Executive Briefing Agent + +**Role**: Automated daily operational summary for leadership. + +**Workflow**: Generates a daily digest by querying the correlation engine for +overnight risk scores, pulling top incidents from the ITSM platform, grabbing +network health from monitoring, and security posture from the security platform. +Synthesizes into a concise summary with key metrics and posts to a leadership +communication channel. + +**Gateway interactions**: + +- Correlation Engine: overnight risk scores, active correlations +- ITSM Server: top incidents, open changes +- Monitoring Server: network health summary +- Security Server: security posture overview +- Chat Server: post daily briefing to leadership channel diff --git a/coffeeAGNTCY/agentic_patterns/gateway/README.md b/coffeeAGNTCY/agentic_patterns/gateway/README.md new file mode 100644 index 000000000..fc09293e9 --- /dev/null +++ b/coffeeAGNTCY/agentic_patterns/gateway/README.md @@ -0,0 +1,351 @@ +# Gateway Pattern: Multi-Platform MCP Aggregation + +## Overview + +The Gateway Pattern aggregates multiple MCP servers behind a single entry point, +enabling upstream agents to interact with heterogeneous platforms through a +unified discovery and routing layer. The gateway acts as an MCP server to +upstream consumers and an MCP client to each downstream platform server, +providing capability-based routing, cross-platform correlation, and +human-in-the-loop approval workflows. + +This pattern addresses a gap in current MCP deployments: while individual MCP +servers expose tools for single platforms, enterprise environments typically +operate dozens of platforms that must be queried, correlated, and acted upon +together. The Gateway Pattern composes AGNTCY's core components - Agent +Directory, OASF, Identity, TBAC, SLIM, and Observability - to solve this at +scale. + +## Architecture + +The gateway sits between upstream agents and downstream platform MCP servers. +Each platform gets its own dedicated MCP server process with independent +credentials, failure domains, and OASF records. The gateway discovers all +registered servers via the Agent Directory and routes requests by role category. + +```mermaid +flowchart TB + subgraph Upstream["Upstream Agents"] + A1["NOC Copilot Agent"] + A2["Security Orchestration Agent"] + A3["Change Validation Agent"] + end + + GW["MCP Gateway
(MCP Server to upstream,
MCP Client to downstream)"] + + subgraph Downstream["Platform MCP Servers"] + direction LR + S1["Monitoring
Server"] + S2["Configuration
Server"] + S3["Security
Server"] + S4["Observability
Server"] + S5["Correlation
Engine"] + end + + subgraph AGNTCY["AGNTCY Components"] + DIR["Agent Directory
+ OASF"] + ID["Identity
+ TBAC"] + OBS["Observability
+ Evaluation"] + end + + A1 & A2 & A3 --> GW + GW --> S1 & S2 & S3 & S4 & S5 + GW -.->|discover| DIR + GW -.->|verify| ID + GW -.->|trace| OBS +``` + +### Key Properties + +- **Fan-out**: A single upstream request may invoke tools on multiple downstream + servers. The gateway handles parallel dispatch and response aggregation. +- **Role-based routing**: Each downstream server registers with role categories + (monitoring, configuration, security, observability, automation, compliance). + The gateway routes based on role rather than server name, enabling + substitution and extension without upstream changes. +- **Independent failure domains**: Each platform server is a separate process. + A single server failure degrades capability without taking down the gateway. +- **Independent credentials**: Each server holds its own platform API + credentials and its own Agent Badge. No shared secrets across servers. + +## AGNTCY Component Mapping + +| Gateway Capability | AGNTCY Component | Usage | +|---|---|---| +| Server discovery | Agent Directory + OASF | Each platform server registers an OASF record with role categories and tool lists. The gateway queries the Directory at startup and on schedule to discover available servers. | +| Identity verification | Identity + Verifiable Credentials | Each server holds an MCP Server Badge (W3C VC) with a DataIntegrityProof signed by the operating organization. The gateway verifies badges before routing requests. | +| Access control | TBAC | Policies define which upstream agents can invoke which tools on which downstream servers. Read-only agents cannot call configuration endpoints. | +| Cross-server messaging | SLIM | Platform servers publish telemetry events over SLIM (pub/sub). The correlation engine subscribes to all streams and fuses events across platforms. | +| Observability | Observability + Evaluation | Gateway and all platform servers export OpenTelemetry traces. Cross-platform request chains are correlated via trace context propagation through the gateway. | +| Agent descriptions | OASF | The gateway itself registers an OASF record that aggregates the capabilities of all downstream servers, presenting a unified skill and domain set to upstream consumers. | + +## Communication Patterns + +### Discovery and Routing + +```mermaid +sequenceDiagram + participant Agent as Upstream Agent + participant Dir as Agent Directory + participant IdSvc as Identity Service + participant GW as MCP Gateway + participant S1 as Monitoring Server + + Agent->>Dir: Query OASF records
(domain: network_operations) + Dir-->>Agent: Gateway record
(aggregated capabilities) + + Agent->>IdSvc: Verify Gateway badge + IdSvc-->>Agent: Badge valid + + Agent->>GW: MCP request
(tool: get_device_health) + GW->>GW: Route by role category
(monitoring) + + GW->>IdSvc: Verify Monitoring Server badge + IdSvc-->>GW: Badge valid + + GW->>S1: MCP request
(tool: get_device_health) + S1-->>GW: Device health response + + GW-->>Agent: Aggregated response +``` + +### Cross-Platform Fan-Out + +For queries that span multiple platforms, the gateway fans out to multiple +servers in parallel: + +```mermaid +sequenceDiagram + participant Agent as Upstream Agent + participant GW as MCP Gateway + participant S1 as Monitoring Server + participant S2 as Security Server + participant S3 as Configuration Server + + Agent->>GW: MCP request
(tool: assess_device_risk) + + par Fan-out + GW->>S1: get_device_health + GW->>S2: get_security_posture + GW->>S3: get_config_compliance + end + + S1-->>GW: Health data + S2-->>GW: Security data + S3-->>GW: Compliance data + + GW->>GW: Aggregate and correlate + GW-->>Agent: Composite risk assessment +``` + +### Telemetry Fusion via SLIM + +Platform servers generate continuous telemetry that cannot be efficiently +delivered through synchronous MCP request/response. The pattern uses SLIM for +asynchronous telemetry delivery to a correlation engine. + +```mermaid +flowchart LR + S1["Monitoring
Server"] -->|pub| SLIM["SLIM
(pub/sub)"] + S2["Security
Server"] -->|pub| SLIM + S3["Observability
Server"] -->|pub| SLIM + SLIM -->|sub| CE["Correlation
Engine"] + CE -->|MCP tools| GW["Gateway"] +``` + +The correlation engine has two input channels: + +- **Asynchronous (SLIM pub/sub)**: Continuous telemetry feed from all platform + servers, enabling real-time correlation without polling. +- **Synchronous (MCP)**: On-demand queries from the gateway when an upstream + agent requests correlation analysis. + +The correlation engine does not require a large language model. Rule-based +correlation (entity overlap + time windows), statistical anomaly detection, and +expert-curated templates provide deterministic, explainable results without +model inference overhead. + +### Human-in-the-Loop Approval + +State-changing operations require human approval. TBAC policies enforce approval +gates at the tool level. + +```mermaid +sequenceDiagram + participant Agent as Upstream Agent + participant GW as MCP Gateway + participant TBAC as TBAC Policy Engine + participant Human as Human Operator + participant S1 as Configuration Server + + Agent->>GW: MCP request
(tool: apply_config_change) + GW->>TBAC: Check policy for
apply_config_change + TBAC-->>GW: Requires human approval + + GW->>Human: Approval request
(via chat, notification, etc.) + Human-->>GW: Approved + + GW->>S1: apply_config_change + S1-->>GW: Change applied + GW-->>Agent: Confirmation with
change evidence +``` + +TBAC policies can be configured at multiple granularity levels: + +- **Per-tool**: `apply_config_change` always requires approval. +- **Per-server**: All write operations on the Configuration Server require + approval. +- **Per-agent**: The Compliance Auditor agent has read-only access to all + servers regardless of tool. +- **Conditional**: Approval required only when blast radius exceeds a threshold. + +## Topology Variants + +### Centralized (Default) + +Platform MCP servers run centrally and communicate with controllers, dashboards, +and cloud platforms via their APIs. Best for fleet-wide analytics, policy +management, and environments where controller APIs are the primary integration +point. This is the topology described above. + +### Edge-Native + +MCP servers run on the network devices themselves using on-device container +runtimes. Each device self-registers in the Agent Directory via its OASF record. +Best for survivability during controller outages, low-latency device-local +queries, and access to state that controllers do not expose. + +Supported platforms include any network device with an embedded container +runtime: + +- Cisco Catalyst 9000 series via IOx +- Dell PowerSwitch via Third Party Container Management (TPCM) on Enterprise SONiC +- Whitebox switches running SONiC with native Docker support + +```mermaid +flowchart TB + GW["MCP Gateway"] + + subgraph Edge["Edge MCP Servers (on-device)"] + E1["Switch 1
IOx / TPCM"] + E2["Switch 2
IOx / TPCM"] + E3["Switch 3
IOx / TPCM"] + end + + subgraph Central["Central MCP Servers"] + C1["Controller
Server"] + C2["Security
Server"] + end + + GW --> E1 & E2 & E3 + GW --> C1 & C2 + E1 & E2 & E3 -.->|self-register| DIR["Agent Directory"] + C1 & C2 -.->|register| DIR +``` + +### Hybrid + +Both centralized and edge-native servers coexist. The gateway discovers all +servers through the same Agent Directory and routes by capability. +Controller-level queries (assurance scores, fabric health, policy compliance) +route to central servers. Device-level queries (interface counters, MAC tables, +config verification) route to edge servers. The correlation engine subscribes to +telemetry from both layers. + +## Workflow Examples + +### Closed-Loop Incident Management + +```mermaid +flowchart TB + CE["Correlation Engine
detects anomaly"] --> GW["Gateway"] + GW --> CMDB["CMDB Server
resolve device context"] + GW --> ITSM["ITSM Server
create P1 incident"] + GW --> MON["Monitoring Server
pull diagnostics"] + GW --> HITL["Human Approval
approve remediation"] + HITL --> CFG["Configuration Server
apply fix"] + CFG --> ITSM2["ITSM Server
update resolution notes"] +``` + +The correlation engine detects a cross-platform anomaly, the gateway resolves +device context from the CMDB, creates an incident in the ITSM platform, pulls +diagnostics from monitoring, obtains human approval for remediation, applies the +fix, and updates the incident with resolution notes. Full lifecycle through a +single gateway. + +### Security Orchestration + +```mermaid +flowchart TB + XDR["Security Server
detects lateral movement"] --> GW["Gateway"] + GW --> CMDB["CMDB Server
map blast radius"] + GW --> NAC["Access Control Server
quarantine endpoint"] + GW --> FW["Firewall Server
block C2 domain"] + GW --> ITSM["ITSM Server
create P1"] + GW --> CHAT["Chat Server
post summary to SecOps"] +``` + +A security agent correlates lateral movement across platforms, calculates blast +radius via the CMDB, executes containment with human approval for destructive +actions, and posts a summary to the security operations channel. + +### Change Validation + +```mermaid +flowchart LR + PRE["Pre-change
snapshot"] --> GW["Gateway
(fan-out to all servers)"] + GW --> WAIT["Wait for
change window"] + WAIT --> POST["Post-change
snapshot"] + POST --> DIFF["Diff pre/post
across platforms"] + DIFF --> ITSM["ITSM Server
attach evidence"] +``` + +A change validation agent captures pre-change baselines across every platform, +waits for the maintenance window, validates post-change state, flags +regressions, and attaches before/after evidence to the change record. + +## Building a Gateway with AGNTCY + +1. **Create an MCP server per platform.** Each server wraps a single platform's + API and exposes its capabilities as MCP tools. Each server runs as an + independent process with its own credentials. + +2. **Register OASF records.** Each platform server and the gateway itself + register OASF records in the Agent Directory with appropriate domains, skills, + and role metadata. + +3. **Issue Identity Badges.** Each server receives an MCP Server Badge (W3C VC) + from the operating organization. The gateway verifies badges during discovery + before routing any requests. + +4. **Define TBAC policies.** Create policies that specify which upstream agents + can invoke which tools. Enforce human-in-the-loop approval for state-changing + operations. + +5. **Connect telemetry via SLIM.** Platform servers publish telemetry events + over SLIM pub/sub. The correlation engine subscribes to all streams and + exposes its findings as MCP tools. + +6. **Instrument with OpenTelemetry.** Use the AGNTCY Observe SDK to export + traces from the gateway and all platform servers. Propagate trace context + through the gateway to enable cross-platform request correlation. + +7. **Register the gateway in the Directory.** The gateway's OASF record + advertises the aggregated capabilities of all downstream servers. Upstream + agents discover the gateway through the Directory like any other service. + +## Reference Implementation + +[MIGA MCP Gateway](https://github.com/keewillidevnet/miga-mcp-gateway) +implements this pattern for enterprise network infrastructure. It routes to +eight real, published upstream MCP servers, a mix of Cisco-official, community, +and vendor-official servers (ThousandEyes, Splunk, Meraki, Catalyst SD-WAN, +Catalyst Center, ISE, ServiceNow, and NetBox), plus its own correlation engine, +INFER, behind a single role-based gateway with a Webex conversational interface. + +MIGA implements the discovery, role-based routing, fan-out, and rule-based +correlation core described above, and publishes an OASF record per server to an +AGNTCY Directory. Identity badge verification, TBAC enforcement, SLIM telemetry +fusion, and OpenTelemetry tracing are described by this pattern and are on MIGA's +roadmap rather than fully wired today. MIGA is available on the +[Cisco Code Exchange](https://developer.cisco.com/codeexchange/).