Step-by-Step: Deploy the Architecture Review Agent Using AZD AI CLI

Hey everyone! I am Shivam Goyal, a Microsoft MVP, and I am super excited to share a project that will save you a massive amount of time.

Have you ever built a brilliant AI agent in an afternoon, only to spend the next two weeks fighting with Docker containers, memory persistence, and cloud deployment scripts to get it running?

In our previous post, we introduced the Architecture Review Agent, an open-source tool built on Microsoft Foundry that automatically converts messy architectural notes into structured risk assessments and interactive Excalidraw diagrams.

But building an AI agent is only half the battle. Iterating on one and actually getting it running in a production-grade environment without losing your mind over infrastructure is a completely different story.

The Problem with Agentic Development Loops

The typical agent development loop is painful: you write your agent code, test it by copy-pasting inputs into a local REPL, manually build a container, push it to a registry, configure RBAC, deploy to your cloud target, realize you need to tweak three lines of logic, and start the whole cycle over again.

You often end up with an agent that is 100 lines of clean Python, surrounded by 400 lines of Bicep and a 12-step deployment guide.

The azd ai extension for the Azure Developer CLI (AZD) completely changes this equation. For the Architecture Review Agent, the entire workflow, from zero infrastructure to a live hosted agent you can invoke from the command line, is just a few simple commands. And moving from local testing to a live cloud deployment is a single azd up.

Here is how you can set up, invoke, and deploy your own Architecture Review Agent, and even publish it to Microsoft Teams, without needing a tenant admin.

Step 1: The Setup (No heavy lifting required)

First, make sure you have the Azure Developer CLI installed and grab the AI Agents extension.

# Install AZD
winget install microsoft.azd 

# Install the AI Agents extension 
azd extension install azure.ai.agents

Next, clone the repository and set up your local Python environment:

git clone https://github.com/Azure-Samples/agent-architecture-review-sample
cd agent-architecture-review-sample

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Finally, authenticate and tell AZD where your Microsoft Foundry project lives:

azd auth login
azd env new arch-review-dev

# Point it to your Foundry Project and Model
azd env set AZURE_AI_PROJECT_ENDPOINT "https://<your-resource>.services.ai.azure.com/api/projects/<your-project>"
azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "gpt-4.1"

Step 2: Run and Invoke Locally

With the AZD AI extension, you get a local server that behaves identically to a deployed Foundry-hosted agent. It uses the same localhost:8088 endpoint, the same OpenAI Responses API protocol, and the same conversation persistence.

Open your first terminal and start the runtime:

azd ai agent run

Now, open a second terminal. This is where the magic happens. The agent is completely format-agnostic. There is no schema you have to memorize. You can pass it a file, or just type out a whiteboard brain-dump inline.

Here is what the terminal experience looks like when running these commands and getting the structured report back:

Styled terminal showing all 3 azd ai agent invoke commands + full structured report output

Here are the three ways you can invoke it using "azd ai agent invoke --local":

Pattern A: The Structured YAML

If your team uses formal definitions, just point the agent to the file. The rule-based parser handles this instantly without an LLM call.

azd ai agent invoke --local "scenarios/ecommerce.yaml"

12-component ecommerce architecture diagram generated from YAML input.

Pattern B: The Whiteboard Brain-Dump (Inline Arrow Notation)

Arrow notation (A -> B -> C) is how engineers actually communicate on whiteboards and in Slack. Before now, this wasn't a valid input for architecture tools.

azd ai agent invoke --local "LB -> 3 API servers -> PostgreSQL primary with read replica -> Redis cache"

The parser automatically extracts the replica count, infers the component types (LB becomes a Gateway), and builds a valid connection graph, surfacing single points of failure instantly.

Pattern C: The Markdown Design Doc

Just point it to your existing READMEs or design docs.

azd ai agent invoke --local "scenarios/event_driven.md"

8-component event-driven streaming architecture generated from Markdown input

For all three patterns, the agent returns a structured Markdown report in your terminal and generates an interactive architecture.excalidraw file and a high-res PNG right in your local /output folder.

Step 3: One Command to the Cloud

When you are happy with how your agent performs locally, it's time to deploy. Forget manual Docker builds and complex credential management.

azd up

This single command orchestrates everything:

1. Provisions Infrastructure: Creates your Foundry AI Services account, ACR, App Insights, and managed identities with proper RBAC.
2. Builds and Pushes: Packages your Dockerfile and pushes the container image to ACR.
3. Deploys the Agent: Registers the image and creates a hosted agent version in Foundry Agent Service.

The output will hand you a live Agent Playground URL and a production-ready API endpoint. Your agent now automatically scales from 0 to 5 replicas, manages its own conversation state, and authenticates securely via Managed Identity.

Step 4: Publish to Teams and M365 Copilot (Zero Admin Required!)

Having an API is great, but agents are most powerful when they live where your users collaborate. You can publish this agent directly to Microsoft Teams and M365 Copilot natively from the Foundry portal.

The best part? You can use the Individual Scope.

1. Go to the Microsoft Foundry portal and find your deployed agent.
2. Click Publish to Teams and Microsoft 365 Copilot.
3. Fill out the basic metadata (Name, Description).
4. Select the Individual scope.

Because you are using an individual scope, no M365 admin approval is required. The portal automatically provisions the Azure Bot Service, packages the metadata, and registers the app. Within minutes, your agent will appear in your Teams Copilot agent store. You can generate a share link and instantly send it to your team for a workshop or demo.

What I Learned Building This Workflow

Shifting from custom deployment scripts to the azd ai CLI taught me three things:

1. The declarative contract is beautifully clean. Our azure.yaml declares the agent and infrastructure in about 30 lines. azd up translates that into a fully secure, production-grade Foundry environment.
2. The local-to-cloud gap is finally gone. The azd ai agent run behaves exactly like the cloud. The invocation you write locally works identically against the deployed endpoint.
3. Teams publishing is remarkably simple. I expected bot registration nightmares and tenant admin blockers. Instead, I filled out a form, waited two minutes, and was chatting with my architecture agent in Teams.

Resources & Next Steps

Now that we have a streamlined, single-hosted agent deployment, the natural next step is multi-agent orchestration. Imagine a triage agent that routes your design doc to a dedicated Security Reviewer Agent and a Scalability Reviewer Agent.

Try it out yourself by cloning the repository, running azd up, and let me know what you build!

• GitHub Repository: Azure-Samples/agent-architecture-review-sample
• Previous Article: Stop Drawing Architecture Diagrams Manually: Meet the Open-Source AI Architecture Review Agents | Microsoft Community Hub
• Microsoft Learn: Install the Azure Developer CLI
• Microsoft Foundry Documentation: Hosted agents in Foundry Agent Service (preview) - Microsoft Foundry