Agent Template Integration Guide

This guide explains how agents in the ConnectSoft AI Software Factory discover, compose, and use templates and overlays. It covers the complete workflow from template discovery to final code generation.

Overview

Agents interact with the template system through:

• Template Catalog Domain - Discovery and resolution of templates
• Recipe System - Composition of base templates with overlays
• Composition Engine - Application of overlays and token replacement
• Parameter Resolution - Mapping blueprint requirements to template parameters

Template Discovery

Discovery Process

Agents discover templates through the Template Catalog domain:

Discovery Steps: 1. Agent analyzes blueprint requirements 2. Agent constructs query based on requirements 3. Agent queries Template Catalog domain 4. Template Catalog returns matching templates 5. Agent evaluates and selects best template

Query Construction:

query:
  type: microservice
  tags:
    - identity
    - event-driven
  features:
    - MassTransit
    - NHibernate
  compatibility:
    dotnetVersion: "8.0"
    cloudPlatform: "Azure"

Agent Template Discovery Flow

flowchart TD
    START[Agent Receives Blueprint]
    ANALYZE[Analyze Blueprint Requirements]
    QUERY[Construct Template Query]
    CATALOG[Query Template Catalog]
    RESULTS[Receive Matching Templates]
    EVALUATE[Evaluate Templates]
    SELECT[Select Best Template/Recipe]
    RESOLVE[Resolve Template Components]

    START --> ANALYZE
    ANALYZE --> QUERY
    QUERY --> CATALOG
    CATALOG --> RESULTS
    RESULTS --> EVALUATE
    EVALUATE --> SELECT
    SELECT --> RESOLVE

    style START fill:#E3F2FD
    style CATALOG fill:#BBDEFB
    style SELECT fill:#C8E6C9
    style RESOLVE fill:#A5D6A7

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

Template Selection Criteria

Agents evaluate templates based on:

Matching Criteria: - Template type matches requirement - Tags match domain requirements - Features match blueprint features - Compatibility matches environment - Version is latest compatible

Scoring Algorithm: - Exact tag matches: +10 points - Feature matches: +5 points per feature - Compatibility matches: +3 points - Latest version: +2 points - Highest score wins

Overlay Composition

Multi-Overlay Composition

Agents compose multiple overlays to create complex templates:

Composition Process: 1. Agent selects base template 2. Agent identifies required overlays 3. Agent validates overlay compatibility 4. Agent creates or selects recipe 5. Agent applies overlays in order 6. Agent merges metadata and code

Agent Multi-Overlay Composition Flow

sequenceDiagram
    participant Agent as Microservice Generator Agent
    participant Blueprint as Microservice Blueprint
    participant Catalog as Template Catalog
    participant Recipe as Recipe System
    participant Compose as Composition Engine

    Agent->>Blueprint: Read Requirements
    Blueprint-->>Agent: Domain: Identity, Features: [Worker]
    Agent->>Catalog: Query Base Template
    Catalog-->>Agent: Base Template (microservice-base)
    Agent->>Catalog: Query Identity Overlay
    Catalog-->>Agent: Identity Overlay (identity-backend)
    Agent->>Catalog: Query Worker Overlay
    Catalog-->>Agent: Worker Overlay (worker)
    Agent->>Recipe: Create Recipe (Base + Identity + Worker)
    Recipe->>Compose: Execute Recipe
    Compose->>Compose: Apply Base Template
    Compose->>Compose: Apply Identity Overlay
    Compose->>Compose: Apply Worker Overlay
    Compose->>Compose: Merge Metadata
    Compose->>Compose: Replace Tokens
    Compose-->>Agent: Final Composed Template

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

Overlay Selection Logic

Agents select overlays based on blueprint requirements:

Selection Rules: - Domain Overlays - Selected based on blueprint domain - blueprint.domain: Identity → Select Identity overlay - blueprint.domain: Audit → Select Audit overlay

• Feature Overlays - Selected based on blueprint features
• blueprint.features: [Worker] → Select Worker overlay

• blueprint.features: [Scheduler] → Select Scheduler overlay

• Infrastructure Overlays - Selected based on deployment

• blueprint.deployment: Kubernetes → Select K8s overlay
• blueprint.observability: Enhanced → Select Observability overlay

Example Selection:

Blueprint:
  domain: Identity
  features: [Worker, Scheduler]
  deployment: Kubernetes

Selected Overlays:
  - identity-backend (domain overlay)
  - worker (feature overlay)
  - scheduler (feature overlay)
  - kubernetes (infrastructure overlay)

Template Parameter Resolution

Parameter Sources

Agents resolve template parameters from multiple sources:

Source Priority: 1. Blueprint Parameters (highest priority) - Service name, domain, features - Persistence type, messaging type - Deployment configuration

1. Recipe Parameters
2. Recipe-defined defaults

3. Recipe parameter overrides

4. Template Defaults

5. Base template parameter defaults

6. Overlay parameter defaults

7. Agent Configuration

8. Agent-specific configuration
9. Environment-specific defaults

Agent Template Parameter Resolution Flow

flowchart TD
    START[Agent Receives Blueprint]
    BLUEPRINT[Extract Blueprint Parameters]
    RECIPE[Load Recipe Parameters]
    TEMPLATE[Load Template Defaults]
    CONFIG[Load Agent Configuration]
    MERGE[Merge Parameters by Priority]
    VALIDATE[Validate All Parameters]
    APPLY[Apply Parameters to Template]

    START --> BLUEPRINT
    BLUEPRINT --> RECIPE
    RECIPE --> TEMPLATE
    TEMPLATE --> CONFIG
    CONFIG --> MERGE
    MERGE --> VALIDATE
    VALIDATE --> APPLY

    style START fill:#E3F2FD
    style MERGE fill:#BBDEFB
    style VALIDATE fill:#FFF9C4
    style APPLY fill:#A5D6A7

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

Parameter Mapping

Agents map blueprint requirements to template parameters:

Mapping Examples:

Blueprint:
  serviceName: "IdentityService"
  persistence: "NHibernate"
  messaging: "MassTransit"
  domain: "Identity"
  features: ["Worker"]

Mapped Parameters:
  ServiceName: "IdentityService"
  RootNamespace: "MyCompany.IdentityService"
  PersistenceType: "NHibernate"
  MessagingType: "MassTransit"
  UseIdentityOverlay: true
  UseWorkerOverlay: true

Template Validation

Validation Process

Agents validate templates before use:

Validation Steps: 1. Structure Validation - Check template structure is valid 2. Metadata Validation - Validate template.json structure 3. Compatibility Validation - Check version compatibility 4. Dependency Validation - Verify all dependencies resolved 5. Parameter Validation - Ensure all required parameters present

Validation Errors: - Template structure invalid - Metadata missing or invalid - Version incompatibility - Missing dependencies - Required parameters missing

Error Handling

Agents handle template errors gracefully:

Error Handling: 1. Validation Errors - Agent reports validation failures 2. Resolution Errors - Agent tries alternative templates 3. Composition Errors - Agent reports composition failures 4. Parameter Errors - Agent requests missing parameters

Fallback Strategies: - Try alternative template versions - Try alternative overlay combinations - Request human intervention - Generate error report

Agent Workflow Integration

Microservice Generator Agent Workflow

The Microservice Generator Agent integrates template composition:

Workflow Steps: 1. Receive Blueprint - Agent receives microservice blueprint 2. Discover Templates - Agent queries Template Catalog 3. Select Recipe - Agent selects or generates recipe 4. Resolve Components - Agent resolves base + overlays 5. Validate Compatibility - Agent validates all versions 6. Compose Template - Agent composes final template 7. Resolve Parameters - Agent resolves all parameters 8. Apply Parameters - Agent applies parameters to template 9. Generate Code - Agent generates service code 10. Validate Output - Agent validates generated code

Integration with Other Agents

Template system integrates with other agents:

Domain Modeler Agent: - Receives template structure - Aligns domain model with template structure - Generates domain code in template structure

Adapter Generator Agent: - Receives template structure - Generates adapters in template structure - Integrates with template infrastructure

Tech Lead Agent: - Validates template composition - Reviews generated code structure - Ensures compliance with standards

Recipe Usage by Agents

Recipe Selection

Agents select recipes based on requirements:

Selection Process: 1. Agent queries Template Catalog for recipes 2. Agent filters recipes by requirements 3. Agent evaluates recipe compatibility 4. Agent selects best matching recipe

Recipe Evaluation: - Recipe matches requirements: +10 points - Recipe has compatible versions: +5 points - Recipe has required overlays: +3 points per overlay - Recipe is well-tested: +2 points

Recipe Generation

Agents can generate recipes dynamically:

Generation Process: 1. Agent analyzes blueprint requirements 2. Agent selects base template 3. Agent selects required overlays 4. Agent validates compatibility 5. Agent generates recipe structure 6. Agent stores recipe (optional)

Generated Recipe Example:

recipeId: identity-worker-service-dynamic
version: 1.0.0
baseTemplate:
  templateId: microservice-base
  version: "^1.5.0"
overlays:
  - overlayId: identity-backend
    version: "^2.1.0"
  - overlayId: worker
    version: "^1.0.0"
parameters:
  ServiceName: "IdentityWorkerService"
  RootNamespace: "MyCompany.IdentityWorker"
  UseMassTransit: true
  UseNHibernate: true

Best Practices

Template Discovery

Best Practices: - Use specific queries for better matches - Cache template metadata for performance - Validate templates before use - Handle errors gracefully

Overlay Composition

Best Practices: - Validate overlay compatibility before composition - Apply overlays in correct order - Test composed templates thoroughly - Document overlay combinations

Parameter Resolution

Best Practices: - Use blueprint as primary parameter source - Provide sensible defaults - Validate all parameters before use - Document parameter mappings

Related Documents

• Template Architecture Implementation - Factory implementation details
• Microservice Generator Agent - Agent specification
• Template Catalog Domain - Template Catalog specification