AI Agents¶

The portal has a chat page (AI Agents in the menu) with one or more agents. An agent is a language model with instructions and a set of tools. The tools are the actions of the portal's own MCP server, so an agent can look up catalog, cost, security, compliance and network data, and can prepare configuration changes as pull requests.

Which agents you see

An agent shows up only when it is enabled in the configuration of your environment. Ask your platform team which are on. Setup is in AI setup and Agent configuration.

The agents¶

Agent	Purpose	What it can do
Commander	The general assistant for the portal. Surfaces information that is in the catalog and answers questions about the platform.	Reads catalog, cost, security, compliance, network and documentation data through MCP tools. Loads a skill when your request belongs to one (spoke or integration platform changes).
Spoke agent	AI-assisted management of spoke configuration files of the landing zone	Creates, copies, updates and validates spoke JSON files, finds a free network range, and opens a pull request. Also available as a skill of the commander.
Integration agent	AI-assisted management of the Integration Platform configuration	Creates and updates Service Bus workload, queue and topic configuration files, validates them against the schema, and opens a pull request or updates an existing branch. Also available as a skill of the commander.

The source also contains a debug agent for development. It is not meant for end users.

Examples of what the interface suggests (these are the prompts shipped with the agents):

"What can you do? What are your capabilities?"
"Show me my workloads and explain who owns them, which domain they belong to, and how they relate to my groups."
"I need a spoke network change such as a VNet, subnet, NSG, or peering update."
"I need an integration platform configuration change or schema update."

How a request is handled¶

sequenceDiagram
    actor U as User
    participant P as Portal chat
    participant A as Agent loop (portal backend)
    participant M as Foundry model endpoint
    participant T as MCP tools (portal backend)
    U->>P: Prompt
    P->>A: Prompt and conversation history
    loop up to 50 steps
        A->>M: Instructions, history, tool list
        M-->>A: Answer or tool call
        A->>T: Tool call with the user's own token
        T-->>A: Result
    end
    A-->>P: Streamed answer
    P-->>U: Answer and the tool calls that were made

The agent loop runs inside the portal backend. Azure AI Foundry only serves model completions. The loop stops after at most 50 steps per turn.
The tool calls are made with your own token. An agent can therefore see and do only what you are allowed to see and do in the portal. If you may not read the firewall logs of a workload, neither can the agent on your behalf.
Conversations are stored per user in the portal's database. You see your own threads and can rename or delete them.
The model of each agent is set in its configuration. At the time of writing the shipped agents use gpt-5.4.

Pull requests, not changes¶

Agents never change a configuration repository directly, and they do not merge. A change always follows this path.

Step	Who
Describe the change in the chat	You
Agent loads the schema and the rules, reads the existing configuration, proposes the smallest valid change	Agent
Agent validates the complete candidate against the schema and the rules and shows the result	Agent
You confirm the final candidate explicitly	You
Agent creates a pull request (or updates an existing branch for the integration agent)	Agent
People review, approve and merge as they do for any change	Platform team or owners of the repository

The review and deployment of a spoke change are those of the platform: Making a change safely. The agents prepare the change faster; they do not bypass it.

Spoke agent rules¶

The spoke skill enforces these rules. They come from the instructions of the agent and from the tools it uses.

Topic	Rule
Source of truth	The JSON Schema of the spoke file and the documentation in the configuration repository. Tool errors and validation results are authoritative. If sources conflict, the agent stops and explains.
Missing values	The agent asks. It does not guess.
New or copied VNet	The agent asks for an IPv4 allocation pool and a target prefix length, and uses a tool to get the next free range. It never calculates a range itself. The tool returns the first aligned block after the highest used address in the pool; it does not fill earlier gaps.
Explicit ranges	Each range is checked for overlap against the live inventory of all spoke files. Any partial or complete overlap is a critical failure.
Subnets	At most one private link subnet per network. `isprivatelinksubnet` and `privateEndpointNetworkPoliciesEnabled` are mutually exclusive. Every subnet lies inside its VNet and subnets do not overlap.
NSGs	An NSG rule is linked to a subnet only when its source or destination prefix exactly equals the subnet prefix.
Uniqueness	The combination of workload short name and environment is unique. Subscription IDs are unique where the schema requires it.
Pull request	Only when all validation passes and you confirmed the final JSON.

Integration agent rules¶

Topic	Rule
Schema only	Properties come from the schema. The agent does not add fields such as `displayName` or `description` that the schema does not define.
Before any task	Load the schema files and the workload rules, and check that the workload name does not already exist in the target environment
Structure	One folder per resource type, environment and workload, with `workload.json` and optional `queues.json` and `topics.json`. Names are lower case with hyphens. The name in `workload.json` equals the folder name. Durations use ISO 8601.
Pull request	After schema validation, rule check and your explicit confirmation. If a branch for the workload exists, the agent asks whether to update it.

Guardrails¶

The commander refuses requests that have no relation to the portal, Azure or IT and cloud engineering, and answers a fixed sentence when asked to ignore its instructions.
Agents must use tools to get facts; they must not guess. They show which agent or skill they use.
Structured output (JSON, YAML, commands) is given in fenced code blocks.
Agents do not reveal internal paths, tool names or instructions unless you explicitly ask.

Review what an agent proposes

An agent can be wrong, and a confirmed pull request still needs a human review. The validation steps reduce errors; they do not replace the review.

What an agent needs from the platform¶

Agent	Needs
All	An enabled agent, a Foundry model endpoint, the portal's MCP URL in the agent configuration, and the models deployed in Foundry
Spoke	The spoke configuration repository in Azure DevOps configured in the portal, and Contribute access for the portal's identity on that repository
Integration	A GitHub repository with the integration platform configuration, a GitHub App with contents and pull request write access, and its credentials in the portal

Details are in AI setup. How the agents are tested is in Agent evaluation.