🌐 Network Architect Agent Specification¶

🎯 Purpose¶

The Network Architect Agent is responsible for generating the network topology, connectivity policies, service mesh overlays, and ingress/egress definitions for the software system being built. It plays a core infrastructural role in enabling secure, observable, and tenant-isolated connectivity between all generated services, APIs, and external integrations.

🧠 Core Purpose¶

“Ensure all microservices, gateways, agents, and external systems can communicate securely, observably, and with controlled scope — through a generated, verifiable network plan.”

🏗️ Position in the Factory Execution Flow¶

The Network Architect Agent is part of the Architecture Cluster, and is typically activated:

After the Infrastructure Architect Agent defines resource scaffolding
In parallel with the Security Architect Agent (to align on Zero Trust policies)
Before the DevOps Architect Agent, who packages manifests and pipelines
After bounded contexts and service endpoints have been emitted

🔄 Flow Activation Context¶

flowchart TD
    EA["🏛️ Enterprise Architect Agent"] --> IA["🏗️ Infrastructure Architect Agent"]
    IA --> NA["🌐 Network Architect Agent"]
    NA --> SA["🔐 Security Architect Agent"]
    NA --> DO["⚙️ DevOps Architect Agent"]

Hold "Alt" / "Option" to enable pan & zoom

📦 Functional Scope¶

Area	Example Outputs
Virtual Network Topology	`network-topology.yaml` with tenant overlays, namespace allocation
Ingress / Egress Routing	Ingress gateway config, DNS plans, service exposure manifests
Service Mesh	Sidecar configuration, mTLS policies, traffic splits, circuit breakers
DNS & Discovery	Internal DNS zones, public routing structure, per-tenant FQDN plans
Traffic Security	Collaborates on Zero Trust boundary enforcement, ingress/egress constraints

🧩 Example Use Case¶

A SaaS product defines 6 microservices (Booking, Notification, Billing), 2 gateways (internal + public), and 2 external APIs (Payments and Twilio). The Network Architect Agent produces:

Multi-zone VNET plan for AKS
Sidecar mesh policies (mTLS between internal services)
Tenant-aware DNS structure ({tenant}.booking.connectsoft.app)
Gateway route overlays and secure egress rules

🧠 Why It Matters¶

Without this agent:

Services may lack route visibility or hit misconfigured gateways
Tenants could leak data via shared DNS or exposed IPs
Security policies like Zero Trust or mTLS enforcement would be brittle or manual
Performance issues may arise from unoptimized topology or circuit breaking

🎯 Strategic Role in ConnectSoft¶

Capability	Enabled Outcome
Traceable networking	All services traceable via DNS, mesh, and topology maps (`traceId`, `zoneId`)
Secure communication	Mesh + firewall + policy generated by design, not by humans
Multi-tenant isolation	No cross-tenant DNS, ingress, or discovery leakage
Observability-aware routing	Traffic paths tied to telemetry and failure domains
GitOps-ready	All network definitions emitted as YAML and version-controlled

✅ Summary¶

The Network Architect Agent is essential for realizing the cloud-native, multi-tenant, zero-trust network layer of all generated systems
It sits between infrastructure scaffolding and DevOps delivery
It ensures the system has a valid, secure, observable topology for all service-to-service, ingress, and egress flows
Without this agent, orchestration, traceability, and security of communication would be fragile or manual

🧩 Responsibilities & Deliverables¶

The Network Architect Agent is accountable for the complete logical and physical connectivity plan for the generated software system. It ensures that every service, gateway, and tenant module operates within a secure, observable, scalable network design — across environments and clusters.

📋 Key Responsibilities¶

Responsibility	Description
Virtual Network Planning	Define logical VNET, subnet, and namespace allocation per environment and tenant.
Service Mesh Design	Emit mesh overlays (e.g., Istio, Linkerd) including traffic policies, retries, splits, mTLS.
Ingress Configuration	Generate ingress manifests for APIs, frontends, and external integrations (DNS, TLS termination).
Egress Policy Generation	Define allowed outbound traffic from internal services to third-party systems (e.g., payments, email, AI).
DNS Mapping	Construct DNS hierarchy (internal and external) with tenant overlays, service aliases, and traceable FQDNs.
Traffic Routing Rules	Define routing logic per service or context: blue-green, circuit-breaker, canary, shadow.
Zero Trust Boundaries	Integrate with Security Architect Agent to enforce network segmentation and trust zones.
Observability Mapping	Ensure network traces (`traceId`, `spanId`, `routeId`) are linked to topology for runtime insight.
Multi-Tenant Isolation	Ensure no cross-tenant traffic leakage, DNS overlap, or misrouted ingress.
Output Emission	Emit all configurations in YAML/JSON for GitOps-ready consumption by DevOps Architect Agent.

📦 Primary Deliverables¶

Artifact	Format	Description
`network-topology.yaml`	YAML	Declarative map of service names, ports, zones, tenants, and IP/CIDR plans.
`service-mesh-overlay.yaml`	YAML	Mesh routing rules, retries, mTLS, circuit breakers, shadowing config.
`ingress-gateways.yaml`	YAML	Public and internal ingress routing overlays with domains, TLS, headers, limits.
`egress-policy.yaml`	YAML	Allowed external targets, rate limits, egress gateway IPs, NAT rules.
`dns-map.yaml`	YAML	FQDN layout per service, tenant, zone (e.g., `billing.premium.vetclinic.connectsoft.app`).
`network-execution-metadata.json`	JSON	Trace and context metadata: `traceId`, `zoneId`, `clusterName`, `agentId`, `version`.

🧠 Example Deliverable Snapshot¶

`dns-map.yaml`¶

tenantZones:
  - tenantId: vetclinic-premium
    baseDomain: vetclinic.connectsoft.app
    services:
      - name: booking-api
        fqdn: booking.vetclinic.connectsoft.app
      - name: billing-ui
        fqdn: billing.vetclinic.connectsoft.app

`egress-policy.yaml`¶

rules:
  - service: billing-api
    allowedDestinations:
      - "https://api.stripe.com"
      - "https://audit.connectsoft.dev"
    allowPorts: [443]
    rateLimit: 500/min

✅ Agent Deliverables Enable:¶

Outcome	Enabled By
🔐 Zero Trust	Egress policies + service mesh + DNS segmentation
📊 Observability	Traceable network events per route, zone, tenant
⚙️ Automation	GitOps-ready YAML files emitted to infra repo
🧪 Testability	Simulated test flows and chaos engineering hooks
🔁 Elastic Scalability	Traffic-aware routing (canary, blue-green) and mesh readiness probes

📥 Inputs Consumed¶

To create a traceable, multi-tenant, and secure network architecture, the Network Architect Agent consumes a composite context from upstream architecture and infrastructure agents. Its input pipeline consists of structural blueprints, deployment goals, and zone-specific parameters emitted by other agents in the Architecture Cluster.

📋 Input Sources¶

Input Artifact	Source Agent	Description
`deployment-topology.yaml`	Infrastructure Architect Agent	List of environments, zones, clusters, service groups, and tenant overlays.
`microservice-map.yaml`	Solution Architect Agent	Logical map of services, endpoints, APIs, and responsibilities across bounded contexts.
`domain-zones.yaml`	Enterprise Architect Agent	Describes system-level separation (e.g., Core, External Integrations, Monitoring, Admin).
`security-zones.yaml`	Security Architect Agent	Annotates which services require isolation, mTLS, least privilege, or air-gapped routing.
`feature-contracts.json`	Product Owner Agent	Maps features and endpoints to user-facing modules (used for routing and DNS exposure).
`api-gateway-plan.yaml`	API Gateway Architect Agent	Describes ingress requirements: public routes, auth methods, rate limits, CORS, TLS.
`dns-policy.template.yaml`	Platform default or reused from memory	Blueprint or historical DNS layout pattern.
`egress-dependencies.yaml`	Generated by Orchestrator or reused from MCP	List of external systems (e.g., Stripe, Twilio, OpenAI) requiring secure access.

🧠 Mandatory Fields Extracted¶

From these documents, the agent extracts:

Semantic Field	Example
`serviceId`	`booking-api`, `auth-server`, `notification-worker`
`clusterName`	`aks-us-east`, `dev-eu-central`, `staging-west`
`zoneId`	`core-zone`, `dmz-zone`, `metrics-zone`
`tenantId`	`vetclinic-premium`, `petco-enterprise`
`ingressType`	`public`, `internal`, `mesh-only`
`exposedDomain`	`booking.vetclinic.connectsoft.app`
`needsEgress`	`true/false`, list of destinations
`tlsRequired`	`true`
`rateLimit`	`100/min`
`mtlsEnforced`	`true/false`
`allowedNamespaces`	`["auth", "api", "internal-tools"]`

🔄 Input Ingestion Flow¶

flowchart TD
  Topology["deployment-topology.yaml"]
  Microservices["microservice-map.yaml"]
  SecurityZones["security-zones.yaml"]
  Gateways["api-gateway-plan.yaml"]
  DNS["dns-policy.template.yaml"]
  ExternalDeps["egress-dependencies.yaml"]

  Topology --> MergeInputs
  Microservices --> MergeInputs
  SecurityZones --> MergeInputs
  Gateways --> MergeInputs
  DNS --> MergeInputs
  ExternalDeps --> MergeInputs

  MergeInputs --> NetworkPlanContext["📥 Network Architect Agent Context Initialized"]

Hold "Alt" / "Option" to enable pan & zoom

🧩 Sample Input Excerpt: `deployment-topology.yaml`¶

environments:
  - name: production
    cluster: aks-us-east
    zones:
      - name: core-zone
        purpose: application-logic
        namespace: core
      - name: dmz-zone
        purpose: api-ingress
        namespace: ingress

🔍 Observability and Metadata Tracked¶

During input parsing, the agent attaches:

Metadata Key	Value
`traceId`	Carried from orchestrator session
`sessionId`	Unique for each Network Architect Agent run
`projectId`	System-wide execution context
`blueprintId`	Source of domain boundaries and architectural constraints
`agentId`	`network-architect@v1.2.0`

✅ Summary¶

The Network Architect Agent consumes a rich, multi-agent context spanning:
- Topology
- Security
- Service endpoints
- Gateway and egress needs
This context is merged, normalized, and validated before planning begins
All inputs are versioned and traced using traceId, sessionId, and projectId

📤 Outputs Produced¶

The Network Architect Agent produces a complete, cloud-native, multi-tenant, and security-aligned networking blueprint, consisting of declarative artifacts ready for orchestration, GitOps pipelines, and policy enforcement.

These outputs form the canonical network control layer of the ConnectSoft AI Software Factory — consumable by infrastructure, security, DevOps, and runtime monitoring agents.

📦 Primary Output Artifacts¶

Artifact	Format	Description
`network-topology.yaml`	YAML	Logical map of VNETs, subnets, zones, namespaces, and tenant overlays across environments.
`service-mesh-overlay.yaml`	YAML	Configuration for sidecar proxies, mTLS, retries, timeout policies, traffic splits, and route weights.
`ingress-gateways.yaml`	YAML	Gateway-level routes for ingress (public/internal), TLS domains, CORS, header transforms, WAF flags.
`egress-policy.yaml`	YAML	Per-service outbound policy for external destinations (e.g., Stripe, Twilio), port controls, DNS constraints.
`dns-map.yaml`	YAML	Fully qualified domain name definitions for services, per-tenant subdomains, internal discovery.
`network-execution-metadata.json`	JSON	Trace + session metadata for observability, versioning, and coordination (`traceId`, `agentId`, etc.).

🧱 Output Folder Structure¶

/networking/
  network-topology.yaml
  service-mesh-overlay.yaml
  ingress-gateways.yaml
  egress-policy.yaml
  dns-map.yaml
  network-execution-metadata.json

→ All files are referenced in the emitted orchestration event NetworkTopologyReady.

🧠 Output Semantics¶

Each artifact is:

Tenant-scoped (includes tenantId, zoneId, and namespace)
Traceable (includes traceId, sessionId, agentId, and generatedAt)
Composable (used by DevOps, Cloud, and Security agents for final deployment pipelines)
Validatable (schema-bound for internal tests, Bicep overlays, and service mesh injection)

📘 `network-topology.yaml` (Excerpt)¶

environments:
  - name: production
    cluster: aks-prod-east
    zones:
      - name: core-zone
        namespace: core
        subnet: 10.0.1.0/24
        tenantIds:
          - vetclinic-premium
          - petco-enterprise
      - name: ingress-zone
        namespace: ingress
        subnet: 10.0.2.0/24

📘 `service-mesh-overlay.yaml` (Excerpt)¶

trafficPolicy:
  mtls: true
  retry:
    attempts: 3
    perTryTimeout: 5s
  circuitBreaker:
    maxConnections: 100
    maxPendingRequests: 20

📘 `ingress-gateways.yaml` (Excerpt)¶

gateways:
  - name: public-api-gateway
    domain: booking.vetclinic.connectsoft.app
    routes:
      - path: /appointments/*
        service: booking-api
        cors: true
        rateLimit: 100/min
        tlsTermination: true

📘 `egress-policy.yaml` (Excerpt)¶

egress:
  - service: billing-api
    allow:
      - https://api.stripe.com
      - https://audit.connectsoft.io
    ports: [443]

📘 `dns-map.yaml` (Excerpt)¶

tenants:
  - id: vetclinic-premium
    services:
      - name: booking-api
        fqdn: booking.vetclinic.connectsoft.app
      - name: billing-ui
        fqdn: billing.vetclinic.connectsoft.app

🛰️ Emitted Event¶

{
  "event": "NetworkTopologyReady",
  "traceId": "proj-713-v1",
  "artifacts": {
    "topology": "network-topology.yaml",
    "dns": "dns-map.yaml",
    "mesh": "service-mesh-overlay.yaml"
  },
  "sessionId": "network-arch-session-0421",
  "agentId": "network-architect@1.3.0",
  "emittedAt": "2025-05-14T17:45:00Z"
}

→ This triggers: ✅ DevOps Architect Agent ✅ Security Architect Agent ✅ Cloud Provisioner Agent

✅ Summary¶

The agent produces a declarative, complete network blueprint, compatible with:
GitOps
IaC deployment
Service mesh injection
DNS and routing layer
Every artifact is scoped, validated, and observable, enabling safe and automated release to production

🧠 Knowledge Base¶

The Network Architect Agent operates from a preloaded, continuously updated knowledge base consisting of networking principles, cloud-native best practices, and ConnectSoft-specific design rules. This internal knowledge allows the agent to reason independently, reuse architectural patterns, and adapt topology planning to tenant, domain, and blueprint variations.

📚 Embedded Knowledge Domains¶

Domain	What the Agent Knows
Cloud-Native Networking	VNETs, subnets, IP address management, Kubernetes namespaces, service discovery, overlay networking
Service Mesh Technologies	Istio, Linkerd, Envoy: configuration of retries, mTLS, traffic splitting, circuit breakers, shadowing
Ingress & Egress Controls	TLS termination, rate limiting, header injection, outbound IP rules, NAT
DNS Architecture	Multi-tenant DNS hierarchy, wildcard subdomains, internal/external resolution, service aliasing
Zero Trust Enforcement	Trust boundaries, mTLS, deny-by-default, tenant-scoped routing rules, network policy generation
Observability Integrations	Trace propagation, sidecar telemetry hooks, route correlation with `traceId`, `spanId`, `zoneId`
Multi-Tenant Design	Namespaces, routing overlays, DNS partitioning, egress segmentation across tenants
Resilience Patterns	Timeout policies, health-based traffic steering, circuit breakers, service fallback planning
Declarative Delivery Standards	YAML schema structures, metadata injection, GitOps-ready folder conventions
Compliance Constraints	Isolation policies per industry (e.g., healthcare zones, PCI DSS for billing modules)

🧩 Reusable Pattern Examples¶

🔁 Network Overlay Template¶

Reused across SaaS blueprints with:
- 3 zones (core, ingress, metrics)
- One namespace per zone per tenant
- Cross-zone mTLS and observability hooks

🔐 DNS Structure Pattern¶

{module}.{tenantId}.connectsoft.app → public
*.svc.cluster.local → internal DNS resolution
mesh-only modules have no ingress or public DNS

🧠 Common Mesh Settings¶

Retry: 3 attempts, 5s per try
Circuit breaker: maxConnections: 100, maxRequests: 50
Shadow route if confidenceScore < 0.85

🧠 Memory Types¶

Memory Type	Source	Purpose
Static Knowledge Base	Embedded into agent definition	Core cloud/networking design rules
Blueprint-Pattern Memory	Vector database via MCP	Recall similar topologies by goal/industry/traceId
Template Semantic Maps	Based on ConnectSoft templates	Known tenant overlays, DNS conventions, gateway structures
Policy Overlay Cache	Cached rulebooks	Common ingress/egress policies for reuse
AI Reasoning Memory	LLM-integrated planner	Interprets ambiguous constraints (e.g., "HIPAA-safe zone")

📘 Example: Vector Memory Hit (via MCP)¶

Query: “Design network plan for 3-tenant billing SaaS with PCI compliance”

Response:

- useMultiZone: true
- zoneLabels: [pci-core, pci-dmz, metrics]
- tenantNamespaces:
    - vetclinic-premium → `billing-core`, `billing-ingress`
    - petco → `pci-core-petco`, `metrics-petco`
- egressNATs: enabled

✅ Summary¶

The Network Architect Agent:

Has deep built-in knowledge of modern networking and mesh systems
Uses semantic memory + ConnectSoft-specific patterns for reuse
Enforces policy-aware, industry-aligned, multi-tenant-safe routing and DNS plans
Selects and adapts from its knowledge base autonomously — while allowing override through configuration

🔁 Process Flow (High-Level)¶

The Network Architect Agent follows a modular, traceable, and resumable execution pipeline. This flow is orchestrated through the ConnectSoft event-driven runtime, using both semantic skill planning and declarative artifact synthesis.

📊 High-Level Execution Flow¶

flowchart TD
    A["🚀 Trigger: StartAgentSession(NetworkArchitectAgent)"] --> B["📥 Load Inputs"]
    B --> C["🧠 Plan Network Topology"]
    C --> D["🔄 Generate Service Mesh Overlay"]
    C --> E["🌐 Compute DNS Structure"]
    C --> F["🔐 Generate Ingress/Egress Policies"]
    D --> G["🧾 Validate Topology & Policies"]
    E --> G
    F --> G
    G --> H["💾 Emit YAML Artifacts"]
    H --> I["📤 Emit NetworkTopologyReady Event"]
    I --> J["📡 Trigger DevOps, Security, Cloud Agents"]

Hold "Alt" / "Option" to enable pan & zoom

🪜 Step-by-Step Breakdown¶

Step	Description
1. Trigger & Session Context Init	Agent is activated by the Orchestrator after the Infrastructure or Solution Architect Agent completes their run.
2. Load Inputs	Consumes: `deployment-topology.yaml`, `microservice-map.yaml`, `security-zones.yaml`, etc.
3. Plan Network Topology	Assigns zones, namespaces, and subnets to each module and tenant.
4. Generate Mesh Overlay	Computes traffic shaping, retries, mTLS, circuit breakers for each service path.
5. Compute DNS & Discovery	Generates FQDNs per service/tenant and mesh-only service discovery rules.
6. Define Ingress & Egress Policies	Creates `ingress-gateways.yaml` and `egress-policy.yaml` based on known APIs, zones, and tenant rules.
7. Validate Plan	Runs rule checks: DNS uniqueness, subnet overlaps, trust boundary violations, tenant leaks.
8. Emit Artifacts	Saves all YAMLs + `network-execution-metadata.json` to workspace or Git.
9. Emit Event	Publishes `NetworkTopologyReady` to trigger DevOps, Cloud, and Security follow-ups.

🧠 Example Execution Trace¶

Phase	Time (ms)	Span
Load Input Context	120	`network.inputs.load`
Generate Zones & Namespaces	89	`network.topology.plan`
Emit Service Mesh Policies	131	`network.mesh.overlay.emit`
Validate DNS/FQDN Uniqueness	63	`network.dns.validate`
Save Files to Workspace	45	`network.artifact.persist`
Emit Event	21	`network.event.emit.NetworkTopologyReady`

🔍 Conditional Branches¶

Condition	Result
`meshEnabled = false`	Skip `service-mesh-overlay.yaml`
`externalIngress = none`	Skip `ingress-gateways.yaml`
`strictEgress = true`	Include deny-all + allowlist in `egress-policy.yaml`
`tenantIsolation = high`	Per-tenant namespace and FQDN split enforced

♻️ Orchestrator-Controlled Retries¶

If validation fails:

Orchestrator retries network.topology.plan
Agent auto-corrects with alternative overlay or fallback subnet layout
If confidence drops < 0.75, emits NetworkPlanAmbiguityWarning for review

✅ Summary¶

The Network Architect Agent follows a modular, observable, event-driven execution flow
Each step maps to an OpenTelemetry span, with retry and correction capability
All outputs are produced declaratively, versioned, and trigger downstream orchestration

🧠 Skills & Kernel Functions¶

The Network Architect Agent uses Semantic Kernel (SK) to dynamically plan and execute its responsibilities through composable, reusable AI skills. These skills are declarative, scoped by trust boundaries, and traceable via traceId, skillId, and agentId.

🧩 Core SK Skills Used¶

Skill Name	Purpose
`PlanNetworkZones`	Analyzes microservice layout and defines zones (core, ingress, metrics, etc.) per tenant and environment.
`AssignNamespaces`	Generates K8s-compatible namespaces per zone, service group, and tenant.
`EmitMeshPolicyOverlay`	Configures traffic routing, retries, timeouts, circuit breakers, mTLS, and destination rules.
`GenerateIngressOverlay`	Produces ingress manifest: domains, paths, TLS, CORS, rate limiting.
`GenerateEgressPolicy`	Builds outbound allowlist and deny rules per service, zone, and dependency.
`BuildDnsMap`	Constructs tenant-aware internal and external FQDNs per service.
`ResolveDnsConflicts`	Ensures FQDN uniqueness and generates fallback aliases.
`InjectObservabilityHooks`	Adds trace propagation annotations (`traceId`, `zoneId`, `routeId`) to each policy/rule.
`ValidateNetworkPlan`	Runs internal rules to ensure no overlap, leakage, or misalignment with trust boundaries.
`GenerateArtifactBundle`	Compiles YAMLs + metadata into a deployable GitOps-ready folder structure.

⚙️ Kernel Execution Composition¶

LoadInputs
→ PlanNetworkZones + AssignNamespaces
→ BuildDnsMap + ResolveDnsConflicts
→ EmitMeshPolicyOverlay + GenerateIngressOverlay + GenerateEgressPolicy
→ ValidateNetworkPlan
→ GenerateArtifactBundle

Each skill is:

Executed within the agent's session scope
Bound to retry logic if confidence is low
Logged via OpenTelemetry spans

🧠 Example Skill Prompt Template: `EmitMeshPolicyOverlay`¶

You are a network architect configuring service mesh rules for a multi-tenant Kubernetes cluster. Given the services and their zone assignments, emit traffic policies that ensure:

mTLS between all services

Retry for transient failures (3x, 5s timeout)

Circuit breaker for all public APIs

Shadow traffic enabled for low-confidence services

🔒 Skill Scope & Access Control¶

Each skill is executed only if:

Agent's agentId matches skillScope
Current blueprint or orchestrator context declares the skill is allowed
Agent has valid session token (traceId, projectId, tenantId, etc.)

If a skill is outside scope → orchestrator blocks it with SkillScopeViolation.

🔄 Retry-Aware Execution¶

Each skill returns:

Field	Description
`result`	YAML/JSON output
`confidence`	Float between 0–1
`retrySuggested`	True if confidence < threshold
`fallbackRecommended`	Trigger alternative logic or human review

🧠 Composite Skills (Built-in Chains)¶

Some behaviors use skill pipelines (e.g., Ingress Planning):

GenerateIngressOverlay
→ InjectObservabilityHooks
→ ValidateNetworkPlan

🧩 Skill Registry & Versioning¶

Skill	Version	Registered By
`EmitMeshPolicyOverlay`	v1.4.0	`network-architect-agent@1.3.0`
`GenerateEgressPolicy`	v1.1.2	`security-architect-agent` (shared skill)

✅ Summary¶

The Network Architect Agent is entirely skill-driven, using semantic, modular building blocks
Skills are executed with trace-aware, retry-safe, role-scoped behavior
Each skill maps to a pipeline stage, artifact block, or event emitter

🛠️ Technology Stack¶

The Network Architect Agent is designed as a cloud-native, event-driven, AI-powered agent. It uses a combination of Semantic Kernel (SK), cloud APIs, infrastructure-as-code generators, and vector memory tools to plan, validate, and emit the network architecture of a system.

🧱 Core Technology Components¶

Technology	Purpose
Semantic Kernel	Orchestrates planning and execution via composable AI skills (e.g., `PlanNetworkZones`, `EmitMeshPolicyOverlay`).
Azure OpenAI	Powers large language model reasoning behind network planning decisions, fallback routes, and naming.
Model Context Protocol (MCP) Server	Provides access to blueprint patterns, mesh overlays, DNS conventions, and prior architectural memory.
Azure Resource Manager / AKS APIs	Referenced for environment metadata (e.g., cluster names, namespaces, IP ranges) and validation.
Istio / Linkerd Templates	Render service mesh overlays and YAML manifests via pre-defined templates.
Bicep / Terraform (optional)	Used when infrastructure definitions include low-level VNET/subnet overlays (cross-agent collaboration).
OpenTelemetry (OTel)	Enables tracing, logging, metrics collection — emitting spans for each skill, validation, and output emission.
YAML + JSON DSLs	Standard output format for all artifacts (`network-topology.yaml`, `service-mesh-overlay.yaml`).
File + Blob Storage	All output artifacts and metadata are stored per `projectId`/`traceId` and available to other agents.
Vector DB (e.g., Qdrant, Pinecone)	Used via MCP to retrieve known mesh patterns, ingress DNS plans, or zone topologies.

☁️ Cloud-Native Runtime Properties¶

Trait	Implementation
Containerized by default	Packaged with sidecar mesh support and observability agents.
Tenant-aware	Every action is scoped by `tenantId`, `traceId`, and namespace.
Replayable	Execution can be resumed from skill or artifact stage using `sessionId`.
GitOps-compatible	All YAMLs, overlays, and DNS plans are stored and versioned for pipeline-based release.
Scalable and disposable	Agent can be run per environment or tenant in parallel (stateless, orchestrator-coordinated).

🧩 Technology Relationships Diagram¶

graph TD
  SK[Semantic Kernel]
  LLM[Azure OpenAI]
  MCP[🧠 MCP Server / Vector DB]
  TEMPLATES[Service Mesh + Ingress Templates]
  YAML[YAML Generators]
  OTel[OpenTelemetry]

  SK --> LLM
  SK --> MCP
  SK --> YAML
  YAML --> TEMPLATES
  SK --> OTel

Hold "Alt" / "Option" to enable pan & zoom

🧪 Tooling for Validation¶

Tool	Use
`kubeval` / `yamllint`	Ensures output manifest schema compliance
`istioctl analyze`	Validates service mesh overlay rules
`dnsmasq` / mocked CoreDNS	Simulates FQDN plan locally for trace validation
`trace-injector` (agent)	Injects `traceId`, `routeId`, `zoneId` into all routes, DNS entries, and observability outputs

✅ Summary¶

The Network Architect Agent runs on a cloud-native, container-first, and agent-coordinated stack
It leverages Semantic Kernel, Azure OpenAI, and MCP memory to generate intelligent, adaptive, and validated networking plans
It integrates natively into the ConnectSoft GitOps pipeline, service mesh ecosystem, and observability fabric

🗣️ System Prompt¶

The System Prompt defines the identity, responsibility, and output expectations of the Network Architect Agent. It acts as the persona contract for the agent — used during session initialization to frame its reasoning, constraints, and deliverables.

This prompt is injected automatically by the Orchestrator when issuing a StartAgentSession(NetworkArchitectAgent) command.

🧠 Bootstrapping System Prompt (ConnectSoft Format)¶

You are the Network Architect Agent in the ConnectSoft AI Software Factory.

Your role is to plan, validate, and emit the full declarative network architecture
for a multi-tenant, cloud-native software system generated by upstream agents.

You must ensure that:
- All services have secure, observable, and tenant-isolated connectivity
- Every tenant, zone, and environment is mapped to logical and physical network structures
- Traffic routing between services is governed by mTLS, retries, and policy overlays
- Ingress and egress traffic is explicitly defined, rate-limited, and scoped
- Internal DNS and service discovery is tenant-safe and traceable
- Service mesh overlays enforce circuit breakers and observability across the system

Your outputs must include:
- `network-topology.yaml`
- `service-mesh-overlay.yaml`
- `ingress-gateways.yaml`
- `egress-policy.yaml`
- `dns-map.yaml`
- `network-execution-metadata.json`

You operate under a zero-trust, GitOps-based, multi-agent coordination environment.
You MUST inject `traceId`, `sessionId`, `agentId`, and `tenantId` in all metadata.

If there is any ambiguity, fallback to reusable topology patterns or emit a
`NetworkPlanAmbiguityWarning` event to request human review.

Your outputs MUST be declarative, YAML-based, and safely deployable across environments.

You collaborate with: Infrastructure Architect, Security Architect, DevOps Architect, and API Gateway Architect Agents.

You are an autonomous agent. Be deterministic, compliant, and traceable.

🧩 System Prompt Highlights¶

Section	Purpose
🔹 Role definition	Frames the Network Architect as a declarative planner for cloud-native networking
🔐 Constraints	Zero Trust, tenant-isolation, mTLS, GitOps compliance
📤 Required outputs	Enumerates exact artifacts agent must produce
🔁 Collaboration	Indicates which agents are upstream/downstream in the lifecycle
📎 Metadata injection	Enforces observability and trace compliance
❗ Fallback policy	Defines recovery behavior on low-confidence plans or invalid topologies

🧠 Prompt Design Principles¶

Uses formal ConnectSoft tone
Speaks in terms of agent responsibilities, not user instructions
Assumes agent is part of a multi-agent system
Follows the Security-First and Cloud-Native Mindset defaults

✅ Summary¶

The system prompt bootstraps the agent into a deterministic, role-aligned behavior pattern
It ensures alignment to ConnectSoft’s architecture, security, and multi-tenant design principles
It defines clear expectations, outputs, fallbacks, and collaboration boundaries

🧾 Input Prompt Template¶

The Input Prompt Template defines how structured inputs (from upstream agents and the orchestrator) are formulated, merged, and injected into the Network Architect Agent’s reasoning context. It ensures the agent understands the deployment intent, tenant structure, service layout, and connectivity expectations across environments and zones.

🧠 Prompt Template Structure (YAML + Context Block)¶

The agent supports a hybrid input model:

🗂️ Structured YAML – Primary input format from orchestration flow
📋 Embedded Context Message – Optional natural-language summary (from Solution/Infrastructure Architect)

📄 Input YAML Payload¶

projectId: proj-713
traceId: proj-713-v1
sessionId: network-arch-session-0421
clusterName: aks-prod-east
environments:
  - name: production
    tenantIds:
      - vetclinic-premium
      - petco-enterprise
    zones:
      - name: core
        namespace: core
        subnet: 10.0.1.0/24
      - name: ingress
        namespace: ingress
        subnet: 10.0.2.0/24
microservices:
  - name: booking-api
    tenantScoped: true
    ingress: public
    egress:
      - https://api.stripe.com
  - name: internal-analytics
    tenantScoped: false
    ingress: mesh
    zone: metrics
securityZones:
  - zone: core
    mtlsRequired: true
    trustBoundary: internal
  - zone: ingress
    trustBoundary: external
egressPolicies:
  denyByDefault: true
  allow:
    - service: booking-api
      destinations:
        - https://api.stripe.com
        - https://monitoring.connectsoft.io

🧠 Optional Embedded Context Prompt¶

The application has 6 microservices and serves 2 tenants.  
All APIs must be exposed over HTTPS using TLS termination at the ingress gateway.  
Services inside the "core" zone must communicate over mTLS only.  
Only booking-api can access external services like Stripe.  
Internal analytics must not be externally reachable or listed in public DNS.

🧩 Key Input Fields the Agent Parses¶

Field	Purpose
`projectId`, `traceId`, `sessionId`	Tracing and observability linkage
`tenantIds`	Namespaces, DNS, and ingress separation
`zones[]`	Subnet/VNET allocation, mTLS and routing overlays
`microservices[]`	Ingress/egress mapping, zone assignment
`egressPolicies`	Outbound NAT constraints, zero-trust enforcement
`securityZones[]`	Trust boundaries and enforcement tiers

📋 Orchestrator Instruction Block¶

The orchestrator wraps the input with:

{
  "agentId": "network-architect-agent",
  "skillPlan": ["PlanNetworkZones", "GenerateEgressPolicy", "EmitMeshPolicyOverlay"],
  "input": { /* YAML payload above */ },
  "contextPrompt": "Network layout for multi-tenant booking platform with PCI-sensitive billing zone",
  "executionMode": "deterministic",
  "preferredOutputFormat": "yaml"
}

🧠 Reasoning Scopes Injected¶

Scope	Usage
`networking.intent`	Public ingress vs. internal-only services
`trust.zone`	External vs. internal boundary awareness
`mesh.mode`	mTLS, retries, circuit breaking
`dns.scope`	Internal-only or exposed DNS zones
`tenant.route`	Cross-tenant protection and namespace enforcement

✅ Summary¶

Input prompts are YAML-based, declarative, and optionally enriched with natural-language summaries
The template supports multi-zone, multi-tenant, zero-trust, and cloud-native constraints
This template is consumed by skills such as:
BuildDnsMap, EmitMeshPolicyOverlay, GenerateIngressOverlay, PlanNetworkZones

📤 Output Expectations¶

The Network Architect Agent produces a validated, GitOps-ready set of YAML and JSON artifacts that define the full network and service communication layer of a multi-tenant, cloud-native ConnectSoft solution. These outputs must be:

📦 Declarative
🔐 Tenant- and trust-aware
🌐 Compatible with service mesh and ingress controllers
📊 Observable and trace-linked
♻️ Reusable across environments and re-runnable by orchestrators

📁 Output File Structure¶

/networking/
  network-topology.yaml
  service-mesh-overlay.yaml
  ingress-gateways.yaml
  egress-policy.yaml
  dns-map.yaml
  network-execution-metadata.json

📦 Required Output Files (Structure + Purpose)¶

File	Format	Description
`network-topology.yaml`	YAML	Defines zone layout, tenant namespaces, subnets, and trust boundaries.
`service-mesh-overlay.yaml`	YAML	mTLS, retry, timeout, traffic shaping, circuit breaker, shadow rules.
`ingress-gateways.yaml`	YAML	Public/internal ingress config: routes, domains, TLS, rate limits.
`egress-policy.yaml`	YAML	Allowlist of outbound destinations, port rules, deny-by-default flags.
`dns-map.yaml`	YAML	Tenant-aware FQDN definitions, internal DNS zones, external DNS hierarchy.
`network-execution-metadata.json`	JSON	Metadata envelope: `traceId`, `sessionId`, `agentId`, `version`, output URIs.

🔖 Required Metadata in All Outputs¶

Each YAML file must include an injected metadata block:

metadata:
  traceId: proj-713-v1
  sessionId: network-arch-session-0421
  agentId: network-architect@1.3.0
  tenantId: vetclinic-premium
  environment: production
  generatedAt: 2025-05-14T18:02:00Z

📋 Schema Validation¶

All outputs are:

✅ Strictly schema-bound (validated via yamllint, kubeval, or custom JSON schema)
✅ Required to pass 100% before emitting NetworkTopologyReady event
❌ Any deviation causes OutputValidationFailed with skillId trace

📘 Example: `ingress-gateways.yaml`¶

gateways:
  - name: public-api
    routes:
      - path: /appointments/*
        service: booking-api
        tenant: vetclinic-premium
        rateLimit: 100/min
        tls: true
        domain: booking.vetclinic.connectsoft.app
        cors: true
        headers:
          inject:
            X-Tenant-Id: vetclinic-premium

📘 Example: `service-mesh-overlay.yaml`¶

trafficPolicy:
  mtls: true
  retry:
    attempts: 3
    perTryTimeout: 5s
  circuitBreaker:
    maxConnections: 100
    maxPendingRequests: 20
  trace:
    propagate: true
    annotations:
      traceId: proj-713-v1

🧩 Machine Readability¶

Artifacts are structured to support:

Consumer	Use
`DevOps Architect Agent`	Helm/Kustomize generation, ArgoCD sync
`Security Architect Agent`	Egress enforcement, mTLS enforcement
`Infrastructure Architect Agent`	Subnet layout, namespace mapping
`Studio Network Topology Viewer`	Visual map via `dns-map.yaml` and `network-topology.yaml`

🧠 Observability Hook Requirements¶

Signal	Source
`networkTopologyEmitted`	From `network-topology.yaml`
`dnsStructureReady`	From `dns-map.yaml`
`meshPolicyApplied`	After `service-mesh-overlay.yaml`
`egressValidated`	From `egress-policy.yaml`
`traceRouteCoverage%`	Ratio of routes with trace annotations

✅ Summary¶

The agent emits six standard output artifacts, all declarative, YAML/JSON, trace-linked, and GitOps-ready
Each file is schema-validatable, tenant-safe, and pipeline-consumable
Output is not optional — failure to emit any artifact = blocked downstream flow

🧠 Memory Models¶

To support reusable patterns, contextual reasoning, and decision validation, the Network Architect Agent leverages both short-term context memory and long-term semantic memory. These allow the agent to handle complex, multi-tenant topologies while staying consistent with ConnectSoft principles like observability, security, and traceability.

🧠 Memory Types and Layers¶

Memory Layer	Description	Backed By
Short-Term Context Memory	Maintains the working session's state: loaded inputs, decisions, trace metadata.	Semantic Kernel planner/session context
Long-Term Semantic Memory	Vector-based knowledge of prior topologies, mesh overlays, DNS layouts, ingress patterns.	MCP Server + Vector DB (e.g., Qdrant, Azure AI Search)
Knowledge Base (Static)	Hardcoded cloud-native network principles, mesh defaults, retry/backoff recipes.	Embedded SK templates and prompt libraries
Artifact Memory	Previously emitted artifacts from other agents (DNS policies, egress configs).	Blob/Git-based storage, indexed via `traceId`
Execution History	Timeline of skill calls, retries, confidence scores, and corrections.	Observability layer with OpenTelemetry spans

🧾 Short-Term Memory Use¶

Item	Used For
`microserviceMap[]`	Zone placement and ingress planning
`zoneAssignments[]`	Topology synthesis and namespace alignment
`egressRules[]`	Policy overlay and NAT decisions
`tenantIds[]`	DNS segmentation and namespace isolation
`confidenceScores[]`	Retry triggering and correction loops

Short-term memory resets at the end of a successful NetworkTopologyReady event — unless orchestration requires continuation.

🧠 Long-Term Memory Use (via MCP)¶

Use Case	Retrieved Memory Pattern
3-zone multi-tenant SaaS	VNET + mesh overlay pattern for dev/staging/prod
Healthcare system blueprint	PCI + HIPAA-compliant DNS and mTLS mesh
Payment egress planning	Allowlist template for Stripe, PayPal, Plaid
Rate-limited ingress	100r/s defaults for core APIs across tenant clusters
Shadow traffic for experiments	Partial clone pattern with circuit-breaker fallback

📘 Memory Embedding Sample (Vector Search)¶

{
  "input": "Multi-tenant API system with separate ingress for admins and clients",
  "embedding": "vector://proj713/zonePattern/v2",
  "matchConfidence": 0.94,
  "retrievedYaml": "network-topology.yaml from proj-610"
}

🧩 Metadata Tagging for Memory Reuse¶

Each emitted artifact includes:

memoryTags:
  - meshPattern: retry-circuitbreaker-defaults
  - dnsStrategy: multi-tenant-subdomain-v2
  - ingressTemplate: tls-public-core
  - isolationLevel: namespace-per-tenant

These tags allow other agents and Studio tools to retrieve, compare, and reuse infrastructure slices.

🧠 Intelligent Recall + Override Flow¶

Agent retrieves 3 matching topology plans via vector memory.
If matchConfidence > 0.85 → adapts known layout to current tenant map.
If matchConfidence < 0.6 → defaults to canonical mesh and DNS templates.
If blueprint has forceNewOverlay: true → ignores prior memory, starts clean.

✅ Summary¶

The agent uses layered memory (short-term, long-term, static, and historical) to reason effectively.
It retrieves and adapts prior mesh, DNS, and zone designs via semantic memory (MCP + vector DB).
Trace-aware tagging ensures emitted artifacts become future memory slices.

✅ Validation Rules¶

To ensure safe, secure, and deployable network artifacts, the Network Architect Agent performs strict multi-layer validation. These rules are enforced during its planning, composition, and emission stages — and aligned with zero trust, tenant isolation, and GitOps-compliance principles.

🧪 Validation Scope¶

Validation Type	Description
Schema Validation	Each emitted YAML/JSON must pass structural schema checks (e.g., subnet blocks, DNS records).
Topology Constraints	Subnets must not overlap; each zone must be uniquely assigned and properly nested.
Tenant Isolation Enforcement	Each `tenantId` must be namespace-scoped; no shared FQDNs, ingress routes, or zones allowed.
DNS Conflict Detection	No duplicate FQDNs across tenants or services; wildcard domains are properly disambiguated.
Ingress Rule Compliance	No route may expose a service without TLS or authentication unless marked `internal-only`.
Egress Rule Compliance	If `denyByDefault: true`, only explicitly allowlisted destinations are permitted.
mTLS + Trust Boundary Alignment	Any cross-zone traffic must validate trust level, mTLS flags, and mesh coverage.
Observability Hooks	Every service mesh rule must include trace propagation annotations or span configuration.
Rate Limit + Retry Logic	Conflicting retry + timeout + circuit breaker settings are flagged and resolved.
Output Coverage	All six standard artifacts (`network-topology.yaml`, `dns-map.yaml`, etc.) must be present.

📋 Sample Validation Matrix¶

Artifact	Rule	Validator
`network-topology.yaml`	Zones must not overlap IP ranges	`ZoneOverlapChecker`
`dns-map.yaml`	Each FQDN must be unique across tenants	`DnsConflictDetector`
`ingress-gateways.yaml`	Public routes must use TLS + rateLimit	`IngressPolicyValidator`
`egress-policy.yaml`	No unlisted destination allowed if denyAll is set	`EgressGuard`
`service-mesh-overlay.yaml`	mTLS must be enabled for core-zone	`MeshPolicyEnforcer`

⚠️ Example Failure Triggers¶

Scenario	Triggered Validation Failure
`billing-api` exposed without TLS	`IngressPolicyValidator.Fail("Missing TLS for public route")`
Two services emit `billing.vetclinic.connectsoft.app`	`DnsConflictDetector.Fail("FQDN already claimed by tenant zone")`
Missing retry logic in mesh policy	`MeshPolicyEnforcer.Warn("No retry policy for production service")`
Service defines egress but `denyByDefault` not set	`EgressGuard.Warn("Missing denyByDefault in egress-policy.yaml")`

🧠 Skill-Based Validation Routing¶

Validation is modular:

GenerateIngressOverlay → ValidateIngress → Inject → Emit
EmitMeshPolicyOverlay → ValidateMesh → Inject → Emit

Each validation is scoped via Semantic Kernel skill wrappers:

ValidateDnsMap
ValidateNetworkZoneLayout
CheckObservabilityAnnotations

🧾 Output Format with Validation Result¶

{
  "artifact": "service-mesh-overlay.yaml",
  "validation": {
    "status": "PASS",
    "warnings": [],
    "traceId": "proj-713-v1",
    "validatedAt": "2025-05-14T18:10:31Z"
  }
}

🔁 Fail-Fast and Retry Behavior¶

Severity	Agent Behavior
❌ Critical	Halt emission, emit `NetworkTopologyValidationFailed`
⚠️ Warning	Emit with caution, log `NetworkValidationWarning` and raise confidence flag
ℹ️ Info	Log for trace audit only, no effect on output

✅ Summary¶

Every output must pass multi-tiered validation: schema, policy, topology, observability, and trace compliance
Failing validations trigger agent retries, fallbacks, or escalation to orchestrator
All validation results are logged, traced, and queryable by other agents and the Studio

🔁 Retry & Correction Flow¶

The Network Architect Agent is designed to be resilient, self-correcting, and observability-first. If it produces an invalid, ambiguous, or incomplete output, it automatically enters a retry or correction loop orchestrated by internal skill logic and the Orchestrator’s supervision.

🔄 Retry Triggers¶

Condition	Action
❌ Failed schema validation	Re-run YAML generation step for the specific artifact
❌ DNS conflict	Trigger `ResolveDnsConflicts` skill with alternative aliasing strategy
⚠️ Low confidence (`< 0.75`)	Retry with fallback topology (e.g., 2-zone instead of 3-zone mesh)
❌ Missing observability annotations	Retry `InjectObservabilityHooks` skill
❌ Egress policy violates deny rules	Retry with `GenerateEgressPolicy` + corrected dependency analysis
❌ Tenant zone overlap	Retry `PlanNetworkZones` with disjoint IP strategy
❌ Service lacks TLS or ingress headers	Retry `GenerateIngressOverlay` and re-validate route config

🛠️ Correction Strategies¶

Error	Fallback Correction
FQDN conflict	Use hash-based alias: `booking-api-xyz.connectsoft.app`
Invalid subnet	Switch to next available /24 block from `zoneRangePool`
Mesh missing trace tags	Apply default telemetry annotation template
Retry + timeout conflict	Use `defaultRetryStrategy-v1`
Multi-tenant DNS collision	Separate tenants into distinct wildcard zones

🧠 Skill-Scoped Correction Graph¶

flowchart TD
    A[Initial Plan Attempt]
    A --> B{Validation Passes?}
    B -- Yes --> C[Emit Artifacts]
    B -- No --> D[Invoke Correction Skill]
    D --> E[Re-run Validation]
    E --> F{Confidence > 0.75?}
    F -- Yes --> C
    F -- No --> G[Emit NetworkPlanAmbiguityWarning]

Hold "Alt" / "Option" to enable pan & zoom

🧪 Confidence-Aware Retry Control¶

Threshold	Behavior
`> 0.90`	Accept plan without fallback
`0.75 – 0.90`	Accept but warn (`NetworkValidationWarning`)
`< 0.75`	Retry or escalate
`< 0.6` after retry	Escalate to orchestrator (`RequireHumanReview: true`)

📢 Events Emitted on Retry or Failure¶

Event	Purpose
`NetworkTopologyValidationFailed`	Indicates unrecoverable issue during artifact synthesis
`NetworkPlanAmbiguityWarning`	Output was valid but confidence is low or fallback was used
`NetworkRetryAttempted`	Correction loop was triggered and completed
`NetworkPlanCorrected`	Retried plan passed validation and was emitted

🔐 Trust Boundary Awareness¶

Retries will not:

Expand tenant access or visibility across namespaces/zones
Remove mTLS enforcement
Modify ingress from internal to public
Add egress targets not previously authorized

→ Ensures Zero Trust + Security-First enforcement even under fallback or correction.

👤 Optional Human Review Hook¶

{
  "event": "NetworkPlanAmbiguityWarning",
  "reason": "Low-confidence DNS mapping with potential collision",
  "requiresHumanApproval": true,
  "suggestedEdits": ["Rename booking-api to booking-vetclinic"]
}

✅ Summary¶

The Network Architect Agent automatically retries invalid or low-confidence outputs
Uses fallback patterns, correction skills, and trace metadata to resolve issues
Escalates only when retry fails or ambiguity remains unresolved
All retry paths are observable, traceable, and governed

🤝 Collaboration Interfaces¶

The Network Architect Agent is tightly integrated into the Architecture Cluster and collaborates with other agents via event-driven triggers, artifact consumption, and trace-aware service interfaces. It does not directly invoke other agents, but participates in a structured agent choreography model coordinated by the Orchestrator.

🧩 Collaboration Summary¶

Collaborating Agent	Interaction Type	Purpose
Infrastructure Architect Agent	Input Consumer	Receives deployment topology, environment zoning, and resource overlays.
Security Architect Agent	Bidirectional	Aligns on Zero Trust boundaries, mTLS enforcement, and egress/inbound traffic rules.
DevOps Architect Agent	Downstream Consumer	Applies emitted YAML manifests in GitOps pipelines and cluster manifests.
API Gateway Architect Agent	Interface Provider	Supplies gateway expectations, route configuration, domain-level auth and CORS policies.
Solution Architect Agent	Input Consumer	Provides microservice map, communication paths, and initial interface design.
Studio UI / Topology Explorer	Read-only Consumer	Visualizes DNS map, route mesh, service graph using emitted `network-topology.yaml`.
Observability Engineer Agent	Downstream Validator	Consumes mesh overlays and injects metrics, span IDs, and tracing policies.

🔁 Event-Driven Interactions¶

Event	Emitted By	Handled By
`DeploymentTopologyReady`	Infrastructure Architect	Network Architect Agent
`ProductPlanCreated`	Product Manager Agent	Solution + Network Architect Agents
`NetworkTopologyReady`	Network Architect Agent	DevOps, Security, Observability Agents
`IngressOverlayReady`	API Gateway Architect	Used by Network Architect to align DNS routing

🔗 Collaboration Sequence Example¶

sequenceDiagram
  participant IA as Infrastructure Architect Agent
  participant NA as Network Architect Agent
  participant SA as Security Architect Agent
  participant DO as DevOps Architect Agent

  IA->>NA: Emit deployment-topology.yaml
  NA->>SA: Emit service-mesh-overlay.yaml
  SA->>NA: Emit security-zones.yaml
  NA->>DO: Emit ingress-gateways.yaml, dns-map.yaml, egress-policy.yaml
  DO->>GitOps: Commit and deploy network plan

Hold "Alt" / "Option" to enable pan & zoom

📘 Artifact-Based Interfaces¶

Artifact	Format	Used By
`network-topology.yaml`	YAML	DevOps Agent, Infra Architect Agent
`service-mesh-overlay.yaml`	YAML	Security Architect Agent, Observability Agent
`ingress-gateways.yaml`	YAML	Gateway Agent, Security Agent
`egress-policy.yaml`	YAML	Firewall Validator Agent, Cloud Gateway Configurator
`dns-map.yaml`	YAML	Studio Viewer, DNS Provisioning Agent
`network-execution-metadata.json`	JSON	All agents — trace and session metadata sync

🤝 Protocols and API Formats¶

YAML-based artifacts (primary interface contract)
JSON metadata block (with traceId, agentId, sessionId)
Event messages via Event Bus (trigger/ack)
Optional HTTP callback endpoints (for advanced orchestrator plugins)
Git-based pull request sync (used by DevOps Agent)

🛑 Scope Boundaries¶

The Network Architect Agent does not:

Modify secrets or RBAC bindings (delegated to Security Architect)
Create Kubernetes clusters or provision VNETs (Infrastructure Architect’s domain)
Manage DNS records at registrar level (DNS Ops Agent or Terraform Generator)

✅ Summary¶

The Network Architect Agent collaborates via event contracts, artifact emission, and trace-based coordination
It depends on inputs from the Infrastructure, Gateway, and Security agents
Its outputs are used by DevOps, Observability, and Studio workflows
Interfaces are YAML-first, event-triggered, and trace-aware

🔎 Observability & Human Intervention Hooks¶

The Network Architect Agent is fully observable, trace-linked, and transparent by design. All of its operations — from planning to artifact emission — are tracked via OpenTelemetry, and support real-time introspection, post-run debugging, and studio visualization.

Additionally, the agent supports human-in-the-loop intervention at critical ambiguity or validation failure points.

📊 Observability Features¶

Category	Implementation
Tracing	Every skill execution, artifact validation, and event emission is traced with `traceId`, `sessionId`, and `agentId`.
Logging	Structured JSON logs include inputs, outputs, confidence scores, error types, and resolution strategies.
Metrics	Prometheus-style metrics for runtime latency, retry count, validation pass rate, DNS conflict frequency.
Span Emission	Skills emit OTel spans: `EmitMeshPolicyOverlay`, `ValidateNetworkTopology`, `GenerateEgressPolicy`, etc.
Error Tags	Logs and events include `errorCode`, `recoveryAction`, and `retryCount`.
Dashboards	Pluggable into Studio, Grafana, or Application Insights dashboards.

📋 Example: Emitted Span¶

{
  "spanName": "EmitMeshPolicyOverlay",
  "traceId": "proj-713-v1",
  "sessionId": "network-arch-session-0421",
  "agentId": "network-architect",
  "status": "Success",
  "confidence": 0.92,
  "durationMs": 128,
  "emittedAt": "2025-05-14T18:15:21Z"
}

📊 Key Metrics Tracked¶

Metric	Description
`network_plan_latency_ms`	Time to complete full planning cycle
`network_validation_pass_rate`	% of runs with no validation errors
`dns_conflict_count`	Number of FQDN conflicts detected during execution
`mesh_retry_attempts_total`	Retry attempts due to mTLS or circuit policy errors
`human_review_triggered_total`	Count of human intervention prompts emitted

👤 Human Intervention Hooks¶

Scenario	Trigger	Action
❌ Repeated DNS conflict across tenants	`NetworkPlanAmbiguityWarning`	Prompt operator to rename or disambiguate
❌ Subnet exhaustion	`ZoneOverlapError`	Offer IP override input
⚠️ Confidence below 0.6	`LowConfidencePlanGenerated`	Show topology diff + correction preview
❓ Unknown egress dependency	`MissingEgressMapping`	Allow user to authorize or deny destination
❌ Failed Zero Trust zone match	`TrustBoundaryMismatch`	Prompt to escalate to Security Architect Agent

🧠 Studio Integration¶

The agent emits artifacts and trace spans accessible via the Studio UI:

🌐 Network topology map with DNS and zone overlays
🔄 Mesh policy visualizer
🛰️ Ingress/egress preview tool
📈 Metrics dashboard per environment
🧾 Validation summary and retry log viewer
🧩 “Explain This Decision” trace navigator

✅ Summary¶

The agent is fully observable, traceable, and testable through OpenTelemetry and structured logging
Studio and downstream agents can query, visualize, and analyze the network architecture plan
Built-in human override hooks ensure ambiguous plans or security-sensitive decisions can be paused and corrected

🌐 Network Architect Agent Specification¶

🎯 Purpose¶

🧠 Core Purpose¶

🏗️ Position in the Factory Execution Flow¶

🔄 Flow Activation Context¶

📦 Functional Scope¶

🧩 Example Use Case¶

🧠 Why It Matters¶

🎯 Strategic Role in ConnectSoft¶

✅ Summary¶

🧩 Responsibilities & Deliverables¶

📋 Key Responsibilities¶

📦 Primary Deliverables¶

🧠 Example Deliverable Snapshot¶

dns-map.yaml¶

egress-policy.yaml¶

✅ Agent Deliverables Enable:¶

📥 Inputs Consumed¶

📋 Input Sources¶

🧠 Mandatory Fields Extracted¶

🔄 Input Ingestion Flow¶

🧩 Sample Input Excerpt: deployment-topology.yaml¶

🔍 Observability and Metadata Tracked¶

✅ Summary¶

📤 Outputs Produced¶

📦 Primary Output Artifacts¶

🧱 Output Folder Structure¶

🧠 Output Semantics¶

📘 network-topology.yaml (Excerpt)¶

📘 service-mesh-overlay.yaml (Excerpt)¶

📘 ingress-gateways.yaml (Excerpt)¶

📘 egress-policy.yaml (Excerpt)¶

📘 dns-map.yaml (Excerpt)¶

🛰️ Emitted Event¶

✅ Summary¶

🧠 Knowledge Base¶

📚 Embedded Knowledge Domains¶

🧩 Reusable Pattern Examples¶

🔁 Network Overlay Template¶

🔐 DNS Structure Pattern¶

🧠 Common Mesh Settings¶

🧠 Memory Types¶

📘 Example: Vector Memory Hit (via MCP)¶

✅ Summary¶

🔁 Process Flow (High-Level)¶

📊 High-Level Execution Flow¶

🪜 Step-by-Step Breakdown¶

🧠 Example Execution Trace¶

🔍 Conditional Branches¶

♻️ Orchestrator-Controlled Retries¶

✅ Summary¶

🧠 Skills & Kernel Functions¶

🧩 Core SK Skills Used¶

⚙️ Kernel Execution Composition¶

🧠 Example Skill Prompt Template: EmitMeshPolicyOverlay¶

🔒 Skill Scope & Access Control¶

🔄 Retry-Aware Execution¶

🧠 Composite Skills (Built-in Chains)¶

🧩 Skill Registry & Versioning¶

✅ Summary¶

🛠️ Technology Stack¶

🧱 Core Technology Components¶

☁️ Cloud-Native Runtime Properties¶

🧩 Technology Relationships Diagram¶

🧪 Tooling for Validation¶

✅ Summary¶

🗣️ System Prompt¶

🧠 Bootstrapping System Prompt (ConnectSoft Format)¶

🧩 System Prompt Highlights¶

🧠 Prompt Design Principles¶

✅ Summary¶

🧾 Input Prompt Template¶

🧠 Prompt Template Structure (YAML + Context Block)¶

📄 Input YAML Payload¶

🧠 Optional Embedded Context Prompt¶

🧩 Key Input Fields the Agent Parses¶

📋 Orchestrator Instruction Block¶

🧠 Reasoning Scopes Injected¶

✅ Summary¶

📤 Output Expectations¶

`dns-map.yaml`¶

`egress-policy.yaml`¶

🧩 Sample Input Excerpt: `deployment-topology.yaml`¶

📘 `network-topology.yaml` (Excerpt)¶

📘 `service-mesh-overlay.yaml` (Excerpt)¶

📘 `ingress-gateways.yaml` (Excerpt)¶

📘 `egress-policy.yaml` (Excerpt)¶

📘 `dns-map.yaml` (Excerpt)¶

🧠 Example Skill Prompt Template: `EmitMeshPolicyOverlay`¶

📘 Example: `ingress-gateways.yaml`¶

📘 Example: `service-mesh-overlay.yaml`¶