Agent System

Agent System

Overview

The az prototype extension uses a multi-agent system with 20 built-in agents that collaborate to design, build, and deploy Azure prototypes. Each agent has a defined role, a set of capabilities, keyword-based task matching, and a coordination contract that declares its inputs, outputs, and delegation targets.

Agents are managed through a central registry that supports three layers: custom, override, and builtin. Users can extend the system with custom agents, override built-in behavior, or use the defaults out of the box.

All substantive work is delegated to agents. Stages (init, design, build, deploy) orchestrate agent execution but do not perform work directly.

Built-in Agents

Architects (5)

Agent	Role	Capabilities	Keywords (subset)	Web Search
cloud-architect	Azure architecture design and cross-service coordination	ARCHITECT, COORDINATE, ANALYZE	architect, design, service, infrastructure, networking, security, azure	Yes
infrastructure-architect	Infrastructure layer oversight -- directs terraform and bicep agents	INFRASTRUCTURE_ARCHITECT, COORDINATE, ANALYZE	infrastructure, networking, compute, container, vnet, subnet, nsg, firewall	Yes
data-architect	Data layer ownership -- databases, storage, data access patterns	DATA_ARCHITECT, ANALYZE	database, sql, cosmos, storage, blob, redis, data, schema, query, partition	Yes
application-architect	Application layer ownership -- delegates to language-specific developers	APPLICATION_ARCHITECT, COORDINATE, ANALYZE	application, app, code, api, frontend, backend, business logic, presentation	Yes
security-architect	Cross-cutting security -- RBAC, identity, encryption, inter-layer access	SECURITY_ARCHITECT, SECURITY_REVIEW, ANALYZE	security, rbac, identity, encryption, tls, firewall, access, credential	No

IaC Agents (2)

Agent	Role	Capabilities	Keywords (subset)	Web Search
terraform-agent	Terraform module generation using azapi provider	TERRAFORM	terraform, tf, hcl, infrastructure, iac, module	Yes
bicep-agent	Bicep template generation using Azure Verified Modules	BICEP	bicep, arm, template, infrastructure, iac	Yes

Language-Specific Developers (4)

Agent	Role	Capabilities	Sub-Layers	Web Search
csharp-developer	C#/.NET application code generation	DEVELOP_CSHARP	api, business-logic, data-access, background, presentation	Yes
python-developer	Python application code generation	DEVELOP_PYTHON	api, business-logic, data-access, background	Yes
react-developer	React/TypeScript frontend code generation	DEVELOP_REACT	presentation	Yes
app-developer	Generic fallback for unsupported languages (Java, Go, Rust, etc.)	DEVELOP	(none)	Yes

Supporting Agents (9)

Agent	Role	Capabilities	Keywords (subset)	Web Search
biz-analyst	Requirements discovery, gap analysis, assumptions surfacing	BIZ_ANALYSIS, ANALYZE	requirement, gap, assumption, business, stakeholder, scope, user story	No
project-manager	Backlog generation, scope management, coordination	BACKLOG_GENERATION, COORDINATE	backlog, story, task, issue, work item, sprint, epics, github, devops	No
qa-engineer	Error analysis, diagnosis, fix guidance, troubleshooting	QA	error, bug, fail, exception, crash, log, debug, fix, diagnose	Yes
cost-analyst	Azure cost estimation at S/M/L tiers using Retail Prices API	COST_ANALYSIS	cost, price, budget, estimate, spend, sku, billing	No
doc-agent	Project documentation generation (README, guides, runbooks)	DOCUMENT	document, readme, guide, runbook, docs, configuration	No
security-reviewer	Pre-deployment IaC security scanning	SECURITY_REVIEW	security, review, scan, audit, vulnerability, rbac, encryption, tls	No
monitoring-agent	Observability configuration (App Insights, alerts, dashboards)	MONITORING	monitor, alert, observability, diagnostic, metrics, app insights, dashboard	No
governor	Governance policy enforcement via embedding-based retrieval and review	GOVERNANCE	governance, policy, compliance, violation, enforce, review, audit	No
advisor	Per-stage trade-off analysis, risk notes, production readiness	ADVISORY	advisory, trade-off, limitation, consideration, risk, scalability, production	No

Delegation Priority Chain

When determining which agent handles a task, the registry applies a strict priority chain defined in find_agent_for_task():

1. Error/issue/bug -- qa-engineer ALWAYS (QA owns the full diagnostic lifecycle)
2. Service + IaC tool -- terraform-agent or bicep-agent (matched by iac_tool parameter)
3. Scope/requirements/communication -- project-manager
4. Multiple services (>2) -- cloud-architect
5. Discovery/requirements analysis -- biz-analyst
6. Documentation -- doc-agent
7. Cost estimation -- cost-analyst
8. Fallback -- keyword scoring via find_best_for_task() (each agent scores the task against its _keywords with _keyword_weight)
9. Ultimate fallback -- project-manager

Each priority level uses signal word sets (e.g., _ERROR_SIGNALS, _SCOPE_SIGNALS, _DISCOVERY_SIGNALS) matched against the task description, or explicit task_type overrides.

Agent Resolution Order

The AgentRegistry resolves agents by name in this order:

1. Custom agents -- user-defined agents added via az prototype agent add
2. Override agents -- user overrides of built-in agents via az prototype agent override
3. Built-in agents -- agents shipped with the extension

This means a custom agent with the same name as a built-in agent takes precedence. An override replaces a built-in while preserving the name. The same resolution order applies to find_by_capability() and list_all().

Layer Ownership

Each architectural layer is owned by a dedicated architect agent. The owner maintains awareness of all services and patterns within its boundary and delegates code generation to the appropriate specialist agents. See Layer Architecture for the full taxonomy.

Layer	Owner	Delegates To	Scope
core	cloud-architect	terraform-agent, bicep-agent	Identity, observability, cross-cutting coordination
infra	infrastructure-architect	terraform-agent, bicep-agent	Networking, compute, security services, AI services, supporting services
data	data-architect	terraform-agent, bicep-agent	Databases, storage, messaging, caching
app	application-architect	csharp-developer, python-developer, react-developer	Application source code across all sub-layers
docs	doc-agent	(none)	Architecture and deployment documentation

The security-architect operates as a cross-cutting reviewer across infra, data, and app layers. It reviews output from other agents and directs corrections but does not own a layer or generate code directly.

The cloud-architect is the top-level coordinator across all layers. It owns the core cross-cutting layer directly and serves as the escalation point for multi-layer architectural decisions.

Agent Contracts

Each agent declares an AgentContract with four fields:

• inputs -- Artifact keys the agent expects in AgentContext.artifacts. Missing inputs are warnings (the agent may still run with reduced context).
• outputs -- Artifact keys the agent produces after execution.
• delegates_to -- Agent names this agent may delegate sub-tasks to.
• sub_layers -- Application sub-layers this agent can generate code for (presentation, api, business-logic, data-access, background). Empty means the agent does not participate in sub-layer delegation.

Agent	Inputs	Outputs	Delegates To	Sub-Layers
cloud-architect	requirements	architecture, deployment_plan	terraform-agent, bicep-agent, app-developer
infrastructure-architect	architecture	infrastructure_code	terraform-agent, bicep-agent
data-architect	architecture	data_infrastructure, data_access_patterns	terraform-agent, bicep-agent
application-architect	architecture, infrastructure_code	application_design, application_code	csharp-developer, python-developer, react-developer	presentation, api, business-logic, data-access, background
security-architect	architecture, infrastructure_code, application_code	security_review	(none)
biz-analyst	(none)	requirements, scope	(none)
project-manager	requirements, scope, architecture	backlog_items	cloud-architect, cost-analyst
terraform-agent	architecture, deployment_plan	iac_code	(none)
bicep-agent	architecture, deployment_plan	iac_code	(none)
csharp-developer	architecture, application_design	csharp_code	(none)	api, business-logic, data-access, background, presentation
python-developer	architecture, application_design	python_code	(none)	api, business-logic, data-access, background
react-developer	architecture, application_design	react_code	(none)	presentation
app-developer	architecture	app_code	(none)
qa-engineer	(none)	qa_diagnosis	terraform-agent, bicep-agent, app-developer, cloud-architect
cost-analyst	architecture	cost_estimate	(none)
doc-agent	architecture, requirements	documentation	(none)
security-reviewer	architecture, iac_code	security_findings	terraform-agent, bicep-agent
monitoring-agent	architecture, deployment_plan	monitoring_config	terraform-agent, bicep-agent

The orchestrator uses contracts to validate that artifact dependencies are satisfiable before executing a plan (check_contracts()). The sub_layers field enables the application-architect to route code generation tasks to the developer agent that covers the required sub-layer. See Application Architecture for details on sub-layer delegation.

Parallel Orchestration

The AgentOrchestrator supports both sequential and parallel execution of agent teams.

Sequential execution (execute_plan): Tasks run one after another in plan order.

Parallel execution (execute_plan_parallel): Uses ThreadPoolExecutor (default max_workers=4) with a dependency graph derived from agent contracts:

1. Build an adjacency graph: task i depends on task j if j produces an artifact that i needs.
2. Find tasks whose dependencies are all completed (the "ready" set).
3. Submit ready tasks to the thread pool concurrently.
4. As tasks complete, update the completed set and find newly ready tasks.
5. If a cycle is detected (no tasks are ready but some remain), fall back to sequential execution for the remaining tasks.

The orchestrator also supports AI-driven planning via plan(), which decomposes an objective into agent-assigned tasks by calling the AI provider.

Agent Commands

List agents

az prototype agent list [--show-builtin] [--detailed]

Lists all registered agents. --show-builtin includes built-in agents (default: true). --detailed shows expanded capability details for each agent.

Show agent details

az prototype agent show --name NAME [--detailed]

Shows details for a specific agent. --detailed displays the full system prompt instead of a 200-character preview.

Add a custom agent

az prototype agent add --name NAME --file FILE
az prototype agent add --name NAME --definition BUILTIN

Registers a custom agent. --file points to a YAML or Python agent definition. --definition copies a built-in definition as a starting point (e.g., cloud_architect, bicep_agent, terraform_agent). The two options are mutually exclusive.

Override a built-in agent

az prototype agent override --name NAME --file FILE

Overrides a built-in agent with a custom definition. The override takes precedence over the built-in but uses the same name.

Remove a custom agent

az prototype agent remove --name NAME

Removes a custom agent from the registry.

Update a custom agent

az prototype agent update --name NAME [--description DESC] [--capabilities CAPS] [--system-prompt-file FILE]

Updates properties of an existing custom agent. --capabilities accepts a comma-separated list (e.g., architect,deploy).

Test an agent

az prototype agent test --name NAME [--prompt PROMPT]

Sends a test prompt to the named agent and displays the response. Useful for validating custom agent behavior.

Export an agent

az prototype agent export --name NAME [--output-file FILE]

Exports an agent definition as YAML. Useful for creating overrides or sharing agent configurations.

Custom Agents

Custom agents can be defined in two formats and are stored in .prototype/agents/ within the project directory. They are registered automatically when the extension loads.

YAML Agent Definition

A declarative format that specifies the agent's name, description, capabilities, constraints, and system prompt. YAML agents are wrapped in a YAMLAgent that delegates to the AI provider with the defined system prompt.

# .prototype/agents/data-architect.yaml
name: data-architect
description: Specialized agent for data pipeline and analytics architectures
role: architect

capabilities:
  - architect
  - analyze

constraints:
  - All data must be encrypted at rest and in transit
  - Use Azure Data Factory for orchestration when batch processing is needed
  - Prefer serverless (Synapse Serverless SQL, Functions) over provisioned resources

system_prompt: |
  You are a data architecture specialist for Azure. You design data pipelines,
  analytics solutions, and data platform architectures using Azure services.

  Key principles:
  - Medallion architecture (bronze/silver/gold) for data lakes
  - Event-driven ingestion where possible
  - Cost-optimized storage tiering

  Always produce a clear service diagram and data flow description.

examples:
  - user: "Design a pipeline for ingesting CSV files from blob storage"
    assistant: |
      ## Data Pipeline Design

      **Services:**
      - Azure Blob Storage (landing zone)
      - Azure Data Factory (orchestration)
      - Azure Data Lake Storage Gen2 (medallion layers)

      **Flow:** Blob trigger → ADF pipeline → bronze (raw) → silver (cleansed) → gold (aggregated)

tools:
  - terraform
  - bicep

Register it:

az prototype agent add --name data-architect --file ./data-architect.yaml

Or copy a built-in as a starting point:

az prototype agent add --name my-architect --definition cloud_architect
# Edit .prototype/agents/my-architect.yaml, then it's ready to use

Python Agent Definition

A Python file containing a class that subclasses BaseAgent. This gives full control over execute() and can_handle() for multi-step or specialized pipelines.

# .prototype/agents/compliance_agent.py
from azext_prototype.agents.base import (
    AgentCapability,
    AgentContext,
    AgentContract,
    BaseAgent,
)
from azext_prototype.ai.provider import AIMessage, AIResponse

SYSTEM_PROMPT = """\
You are a compliance review agent specializing in Azure regulatory requirements.
You review architecture designs and IaC code for compliance with:
- SOC 2 Type II controls
- HIPAA safeguards (when healthcare data is involved)
- PCI DSS requirements (when payment data is involved)

Output a structured compliance checklist with pass/fail/warning for each control.
"""


class ComplianceAgent(BaseAgent):
    _temperature = 0.2          # Low temperature for consistent reviews
    _max_tokens = 8192
    _keywords = ["compliance", "regulatory", "soc2", "hipaa", "pci", "audit", "controls"]
    _keyword_weight = 0.15
    _enable_web_search = True   # Can fetch latest compliance docs
    _include_standards = True   # Include design standards in context
    _knowledge_role = "security-reviewer"

    _contract = AgentContract(
        inputs=["architecture", "iac_code"],
        outputs=["compliance_report"],
        delegates_to=["security-reviewer"],
    )

    def __init__(self):
        super().__init__(
            name="compliance-agent",
            description="Regulatory compliance review for Azure architectures",
            capabilities=[AgentCapability.SECURITY_REVIEW, AgentCapability.ANALYZE],
            constraints=[
                "Always cite the specific control ID (e.g., SOC2 CC6.1, HIPAA 164.312(a)(1))",
                "Never approve architectures with public endpoints storing sensitive data",
            ],
            system_prompt=SYSTEM_PROMPT,
        )

    def execute(self, context: AgentContext, task: str) -> AIResponse:
        # The base class handles system messages, governance injection,
        # MCP tool calls, and web search markers automatically
        return super().execute(context, task)

    def can_handle(self, task_description: str) -> float:
        # Base class keyword matching, or add custom logic
        score = super().can_handle(task_description)
        # Boost score if regulatory terms appear
        regulatory_terms = ["compliance", "regulatory", "hipaa", "pci", "soc"]
        if any(term in task_description.lower() for term in regulatory_terms):
            score = min(1.0, score + 0.3)
        return score

Register it:

az prototype agent add --name compliance-agent --file ./compliance_agent.py

BaseAgent Configuration Attributes

These class variables control agent behavior and can be set in both YAML and Python agents:

Attribute	Default	Description
_temperature	0.7	AI sampling temperature
_max_tokens	4096	Maximum response tokens
_keywords	[]	Keywords for task matching
_keyword_weight	0.1	Score weight per keyword match
_governance_aware	True	Inject governance context into prompts
_include_templates	True	Include workload templates in context
_include_standards	True	Inject design standards into system prompts
_enable_web_search	False	Enable [SEARCH: query] markers for runtime docs
_enable_mcp_tools	True	Allow agent to use MCP server tools
_knowledge_role	None	Knowledge injection role (e.g., "architect", "infrastructure", "developer")
_max_tool_iterations	10	Max MCP tool call loop iterations

Agent Overrides

Overrides let you replace a built-in agent's behavior while keeping the same name. This is useful when you want to customize how a specific agent works without changing the delegation chain or contracts that reference it.

Workflow:

1. Export the built-in agent:

   az prototype agent export --name cloud-architect --output-file my-architect.yaml

2. Modify the exported YAML (adjust system prompt, keywords, constraints, etc.)
3. Register the override:

   az prototype agent override --name cloud-architect --file my-architect.yaml

The override takes effect immediately for the current project. To restore the built-in behavior, remove the override file from .prototype/agents/overrides/.

Common override scenarios:

• Add organization-specific constraints to a built-in agent's system prompt
• Change the default temperature or max tokens for a specific agent
• Add custom keywords to improve task routing for your domain
• Enable web search on an agent that doesn't have it by default

Testing Custom Agents

Validate your agent before using it in a real pipeline:

# Test with a default prompt
az prototype agent test --name compliance-agent

# Test with a specific prompt
az prototype agent test --name compliance-agent --prompt "Review this architecture for HIPAA compliance: App Service + Cosmos DB + Blob Storage"

See also: Governance for how policies and standards integrate with agent system prompts.