az prototype agent

  • Preview

Note

This reference is part of the prototype extension for the Azure CLI (version 2.50.0 or higher). The extension will automatically install the first time you run an az prototype agent command. Learn more about extensions.

Command group 'prototype' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Manage AI agents for prototype generation.

Agents are specialized AI personas that handle different aspects of prototype generation. Built-in agents ship with the extension; you can add custom agents or override built-in ones.

Built-in agents: cloud-architect, terraform, bicep, app-developer, documentation, qa-engineer, biz-analyst, cost-analyst, project-manager, security-reviewer, monitoring-agent

Agent resolution order: custom > override > built-in.

Use 'agent list' to see all available agents, 'agent add' to create custom agents, 'agent test' to validate an agent, and 'agent export' to share agent definitions.

Commands

Name Description Type Status
az prototype agent add

Add a custom agent to the project.

 Extension Preview
az prototype agent export

Export any agent (including built-in) as a YAML file.

 Extension Preview
az prototype agent list

List all available agents (built-in and custom).

 Extension Preview
az prototype agent override

Override a built-in agent with a custom definition.

 Extension Preview
az prototype agent remove

Remove a custom agent or override.

 Extension Preview
az prototype agent show

Show details of a specific agent.

 Extension Preview
az prototype agent test

Send a test prompt to any agent and display the response.

 Extension Preview
az prototype agent update

Update an existing custom agent's properties.

 Extension Preview

az prototype agent add

Preview

Command group 'prototype agent' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Add a custom agent to the project.

Creates a new custom agent definition in .prototype/agents/ and registers it in the project configuration manifest.

Interactive by default — when neither --file nor --definition is provided, walks you through description, capabilities, constraints, system prompt, and optional few-shot examples.

Non-interactive modes:

  • --definition copies a built-in agent's YAML as a starting point
  • --file uses your own YAML or Python definition

After creation, test the agent with 'az prototype agent test --name <name>'.

az prototype agent add [--acquire-policy-token]
                       [--change-reference]
                       [--definition]
                       [--file]
                       [--json]
                       [--name]

Examples

Interactive agent creation (default)

az prototype agent add --name my-data-agent

Start from the cloud_architect built-in definition

az prototype agent add --name my-architect --definition cloud_architect

Add agent from a user-supplied file

az prototype agent add --name security --file ./security-checker.yaml

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--definition

Name of a built-in definition to copy as a starting point (e.g., cloud_architect, bicep_agent, terraform_agent). Mutually exclusive with --file.

--file

Path to a YAML or Python agent definition file. Mutually exclusive with --definition.

--json -j

Output machine-readable JSON instead of formatted display.

Property Value
Default value: False
--name

Unique name for the custom agent (used as filename and registry key).

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az prototype agent export

Preview

Command group 'prototype agent' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Export any agent (including built-in) as a YAML file.

Exports the agent's metadata, system prompt, capabilities, constraints, and examples as a portable YAML file. The exported file can be shared with other projects or used as a starting point for customization.

Built-in agents can be exported to inspect or customize their definitions.

az prototype agent export [--acquire-policy-token]
                          [--change-reference]
                          [--json]
                          [--name]
                          [--output-file]

Examples

Export a built-in agent

az prototype agent export --name cloud-architect

Export to a specific path

az prototype agent export --name qa-engineer --output-file ./agents/qa.yaml

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--json -j

Output machine-readable JSON instead of formatted display.

Property Value
Default value: False
--name

Name of the agent to export.

--output-file -f

Output file path for the exported YAML.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az prototype agent list

Preview

Command group 'prototype agent' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

List all available agents (built-in and custom).

Displays agents grouped by source (built-in, custom, override) with name, description, and capabilities.

By default shows a formatted console display. Use --json for machine-readable output. Use --detailed for expanded capability details.

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

Examples

List all agents with formatted output

az prototype agent list

Get machine-readable JSON output

az prototype agent list --json

Show expanded details

az prototype agent list --detailed

List agents in JSON format with details

az prototype agent list --json --detailed

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--detailed -d

Show expanded capability details for each agent.

Property Value
Default value: False
--json -j

Output machine-readable JSON instead of formatted display.

Property Value
Default value: False
--show-builtin

Include built-in agents in the listing.

Property Value
Default value: True
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az prototype agent override

Preview

Command group 'prototype agent' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Override a built-in agent with a custom definition.

Replaces the behavior of a built-in agent with a custom implementation. The override is recorded in prototype.yaml and takes effect on the next command run.

The override file is validated: must exist on disk, parse as valid YAML, and contain a 'name' field. A warning is shown if the target name does not match a known built-in agent.

az prototype agent override [--acquire-policy-token]
                            [--change-reference]
                            [--file]
                            [--json]
                            [--name]

Examples

Override cloud-architect with custom definition

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

Override the terraform agent

az prototype agent override --name terraform --file ./custom-terraform.yaml

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--file

Path to YAML or Python agent definition file.

--json -j

Output machine-readable JSON instead of formatted display.

Property Value
Default value: False
--name

Name of the built-in agent to override.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az prototype agent remove

Preview

Command group 'prototype agent' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Remove a custom agent or override.

Removes a custom agent definition from .prototype/agents/ and cleans up the project configuration manifest entry. Can also remove overrides, restoring the built-in agent behavior.

Built-in agents cannot be removed.

az prototype agent remove [--acquire-policy-token]
                          [--change-reference]
                          [--json]
                          [--name]

Examples

Remove a custom agent

az prototype agent remove --name my-data-agent

Remove an override (restores built-in)

az prototype agent remove --name cloud-architect

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--json -j

Output machine-readable JSON instead of formatted display.

Property Value
Default value: False
--name

Name of the custom agent to remove.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az prototype agent show

Preview

Command group 'prototype agent' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Show details of a specific agent.

Displays agent metadata including description, source, capabilities, constraints, and a preview of the system prompt.

Use --detailed to show the full system prompt instead of a 200-character preview. Use --json for machine-readable output.

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

Examples

Show agent details

az prototype agent show --name cloud-architect

Show full system prompt

az prototype agent show --name cloud-architect --detailed

Get JSON output

az prototype agent show --name cloud-architect --json

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--detailed -d

Show full system prompt instead of 200-char preview.

Property Value
Default value: False
--json -j

Output machine-readable JSON instead of formatted display.

Property Value
Default value: False
--name

Name of the agent to show details for.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az prototype agent test

Preview

Command group 'prototype agent' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Send a test prompt to any agent and display the response.

Sends a prompt to the specified agent using the configured AI provider and displays the response. Useful for validating agent behavior after creation or update.

Reports the model used and token count after the response. Requires a configured AI provider (run 'az prototype init' first).

az prototype agent test [--acquire-policy-token]
                        [--change-reference]
                        [--json]
                        [--name]
                        [--prompt]

Examples

Test with default prompt

az prototype agent test --name cloud-architect

Test with custom prompt

az prototype agent test --name my-agent --prompt "Design a web app with Redis caching"

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--json -j

Output machine-readable JSON instead of formatted display.

Property Value
Default value: False
--name

Name of the agent to test.

--prompt

Test prompt to send to the agent.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az prototype agent update

Preview

Command group 'prototype agent' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Update an existing custom agent's properties.

Interactive by default — walks through the same prompts as 'agent add' with current values as defaults. Press Enter to keep existing values.

Providing any field flag (--description, --capabilities, --system-prompt-file) switches to non-interactive mode and only changes the specified fields.

Only custom YAML agents can be updated.

az prototype agent update [--acquire-policy-token]
                          [--capabilities]
                          [--change-reference]
                          [--description]
                          [--json]
                          [--name]
                          [--system-prompt-file]

Examples

Interactive update with current values as defaults

az prototype agent update --name my-agent

Update only the description

az prototype agent update --name my-agent --description "New description"

Update capabilities

az prototype agent update --name my-agent --capabilities "architect,deploy"

Update system prompt from file

az prototype agent update --name my-agent --system-prompt-file ./new-prompt.txt

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--capabilities

Comma-separated list of capabilities (e.g., architect,deploy).

--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--description

New description for the agent.

--json -j

Output machine-readable JSON instead of formatted display.

Property Value
Default value: False
--name

Name of the custom agent to update.

--system-prompt-file

Path to a text file containing the new system prompt.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False