DEV Community: Morten Christensen

Multi-agent orchestration on Azure AI Foundry with .NET: AsAIFunction, A2A, and when one agent is enough

Morten Christensen — Mon, 27 Jul 2026 07:59:30 +0000

When you build a Foundry agent that needs more than one capability, the natural impulse is to reach for multi-agent orchestration. Spin up a ResearchAgent, a WriterAgent, an OrchestratorAgent. Problem solved, right? In my experience, that's not always the case. Most scenarios that feel like they need multiple agents can be handled cheaper and with less operational surface area by a single agent with well-chosen tools.

This post covers three things: a concrete heuristic for deciding when to split agents, the two in-process orchestration patterns available in the Microsoft Agent Framework .NET SDK, and the Foundry Workflows retirement coming December 1, 2026. If your team built orchestration in the visual portal designer, I'll show you what the migration path actually looks like in code.

I'm showing my preferred approach here. If you structure this differently, or if the A2A story has changed since I wrote this, I'd be curious to hear more about it.

When one agent is actually enough

Four reasons I'll reach for multiple agents instead of one agent with more tools:

The specialists need different models. A ReasoningAgent that plans and decomposes a task benefits from a slower, more capable model; a SummaryAgent that just reformats output can use something cheaper and faster. Mixing those workloads in a single agent means paying the heavier model's rate for work that doesn't need it.
The specialists belong to different teams and need independent versioning and deployment. If the ResearchAgent is owned by one team and the WriterAgent by another, coupling them into a single process creates coordination overhead every time either team ships. If everything is handled by a single team this would be less of an issue, but I would still emphasize thinking about 'Separation of Concern'.
One specialist has a traffic pattern that warrants independent scaling: bursty load that would starve the others if they shared capacity.
The specialist lives in a different subscription, project, or organisation and can only be reached over a network.

If none of those conditions hold, stay with one agent. A single gpt-4.1-mini deployment with three function tools will be cheaper and far easier to trace than three agents calling each other. The pattern I'd call orchestration by default, adding an OrchestratorAgent before you have a specific reason for it, adds a model call at every hop and makes traces meaningfully harder to read.

In-process composition with AsAIFunction()

When you do have a genuine reason to split, the simplest path in the Agent Framework .NET SDK is AsAIFunction(). It exposes an AIAgent as an AIFunction, so the outer agent can call the inner agent as a tool, entirely within the same process. No HTTP round-trip, no Foundry deployment for the inner agent.

This is not the same as the Foundry Responses API agent-reference pattern. With AsAIFunction(), the inner agent is instantiated in your C# process with its own model connection. The outer agent's decision to call it happens through the normal tool-calling mechanism: the LLM emits a tool call, the framework resolves it to the inner AIAgent.RunAsync(), and the result comes back as a tool response. Session state lives in memory.

Here's the minimal version. A WeatherAgent that answers weather questions, exposed as a callable tool to a MainAgent:

// example-01: WeatherAgent as a callable tool of MainAgent via AsAIFunction()

using System.ComponentModel;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// GetWeather is a static local function. [Description] attributes on the method
// and its parameter let AIFunctionFactory.Create() generate a JSON function schema
// that the model can call.
[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location)
    => $"The weather in {location} is cloudy with a high of 15°C.";

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-4.1-mini";

// DefaultAzureCredential — for local dev, use `az login` first.
// In production, prefer ManagedIdentityCredential to avoid fallback probing.
AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());

// Wrap the static C# method as an AITool with a function schema.
AITool weatherTool = AIFunctionFactory.Create(GetWeather);

// Create the WeatherAgent in-process. Nothing is deployed to Foundry.
// AsAIAgent() is an extension method from Microsoft.Agents.AI.Foundry.
AIAgent weatherAgent = aiProjectClient.AsAIAgent(
    deploymentName,
    instructions: "You answer questions about the weather.",
    name: "WeatherAgent",
    tools: [weatherTool]);

// Expose the WeatherAgent as a named AIFunction the MainAgent can invoke as a tool.
// AsAIFunction() is the in-process composition primitive — no HTTP round-trip.
AIAgent mainAgent = aiProjectClient.AsAIAgent(
    deploymentName,
    instructions: "You are a helpful assistant who responds in Portuguese.",
    name: "MainAgent",
    tools: [weatherAgent.AsAIFunction()]);

// CreateSessionAsync initialises in-memory conversation state.
// Pass the same session into every RunAsync() call to retain context across turns.
AgentSession session = await mainAgent.CreateSessionAsync();
Console.WriteLine(await mainAgent.RunAsync("What is the weather like in Amsterdam?", session));

A few things to pay attention to in that code. AIFunctionFactory.Create(GetWeather) wraps the static C# method as an AITool with a function schema the framework can serialise and send to the model. aiProjectClient.AsAIAgent(deploymentName, instructions, name, tools) creates the agent in-process, nothing is deployed to Foundry. weatherAgent.AsAIFunction() packages the whole WeatherAgent as a named tool the MainAgent can invoke. And mainAgent.CreateSessionAsync() sets up the conversation state; pass the same session into every RunAsync() call if you want the agent to remember earlier turns.

The call flow: the user asks MainAgent about Amsterdam weather, MainAgent decides to call the WeatherAgent tool, WeatherAgent invokes its own GetWeather function, and the result climbs back up the stack as a tool response. All of this is in memory. From the outer agent's perspective it looks like any other tool call.

Oh, and a small twist: the main agent will respond in Portuguese. There is no point in having a main agent if it's just getting the weather from another agent and doing nothing else, so here the main agent also has a specialized instruction.

Install Microsoft.Agents.AI.Foundry (1.5.0 at time of writing) and it brings in Microsoft.Agents.AI, Azure.AI.Projects, and the other dependencies transitively. Set FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL in your environment, authenticate with az login for local development, and that's the full setup.

Three agents, one pipeline

Once two agents compose cleanly, adding a third follows the same pattern. The scenario that actually justifies three agents: a ResearchAgent that retrieves current information using a web search tool, a WriterAgent that takes research output and produces structured text, and an OrchestratorAgent that coordinates them in sequence.

// example-02: Three-agent sequential pipeline via AsAIFunction()

using System.ComponentModel;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// --- Stub tools ---

// Real implementation: call Bing Grounding tool or a web search API.
// Stub returns hardcoded research so the pipeline runs without a search subscription.
[Description("Research a topic and return a summary with key facts.")]
static string GetCurrentResearch(
    [Description("The topic to research.")] string topic)
{
    Console.WriteLine($"[ResearchAgent tool] GetCurrentResearch(\"{topic}\")");
    return $$$"""
    {
      "topic": "{{{topic}}}",
      "summary": "Recent studies show significant advances in {{{topic}}}.",
      "keyFacts": [
        "Fact 1: adoption grew 40% in the past year",
        "Fact 2: leading practitioners cite cost reduction as the primary driver",
        "Fact 3: open standards are gaining momentum over proprietary approaches"
      ]
    }
    """;
}

// Real implementation: write to a file or blob storage.
// Stub prints to Console so the delegation pattern is observable.
[Description("Write a short article draft and save it.")]
static void WriteArticle(
    [Description("The article content to write.")] string content,
    [Description("The filename to save the article to.")] string filename)
{
    Console.WriteLine($"[WriterAgent tool] WriteArticle(\"{filename}\")");
    Console.WriteLine("--- Draft content ---");
    Console.WriteLine(content);
    Console.WriteLine("--- End draft ---");
}

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-4.1-mini";

AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());

// ResearchAgent: uses a web-search stub tool.
AIAgent researchAgent = aiProjectClient.AsAIAgent(
    deploymentName,
    instructions: "You are a research specialist. When asked to research a topic, call GetCurrentResearch and return the results.",
    name: "ResearchAgent",
    tools: [AIFunctionFactory.Create(GetCurrentResearch)]);

// WriterAgent: uses a file-writing stub tool.
AIAgent writerAgent = aiProjectClient.AsAIAgent(
    deploymentName,
    instructions: "You are a technical writer. When given research results, call WriteArticle to draft a short article.",
    name: "WriterAgent",
    tools: [AIFunctionFactory.Create(WriteArticle)]);

// OrchestratorAgent: treats both specialists as named tools via AsAIFunction().
// The system prompt makes the delegation sequence deterministic.
AIAgent orchestratorAgent = aiProjectClient.AsAIAgent(
    deploymentName,
    instructions: """
        You coordinate a research and writing pipeline.
        Step 1: Call ResearchAgent with the user's topic to gather research.
        Step 2: Call WriterAgent with the research results to produce a draft.
        After both steps complete, summarise what was done.
        """,
    name: "OrchestratorAgent",
    tools: [researchAgent.AsAIFunction(), writerAgent.AsAIFunction()]);

// A single session is kept alive across both specialist calls.
// The orchestrator accumulates intermediate results in this session.
AgentSession orchestratorSession = await orchestratorAgent.CreateSessionAsync();

string topic = "multi-agent orchestration patterns";
Console.WriteLine($"[OrchestratorAgent] Starting pipeline for topic: \"{topic}\"");
Console.WriteLine();

var result = await orchestratorAgent.RunAsync(
    $"Research and write a short article about: {topic}",
    orchestratorSession);

Console.WriteLine();
Console.WriteLine("[OrchestratorAgent] Pipeline complete.");
Console.WriteLine(result.Text);

There are a couple of things about this pattern that are easy to get wrong.

The orchestrator does not automatically receive the inner agents' intermediate tool calls. When it calls ResearchAgent, it gets back the text result. It never sees the individual web search calls the research agent made internally. That's usually what you want: specialists hide their implementation details behind a clean result boundary.

Context does not flow between specialists on its own, either. If WriterAgent needs the research results, the orchestrator has to include them explicitly in the message it sends to the writer. You own that assembly step. The framework does not thread context through for you.

And the cost. Each specialist invocation is a separate model call. If the orchestrator loops over five topics and calls both specialists per topic, you're looking at ten model calls just for the specialists, plus the orchestrator's own calls on top of that. Multi-agent is not free. Run the numbers against a single-agent approach before committing.

A2A (Agent 2 Agent): when the specialist lives somewhere else

AsAIFunction() only works when both agents run in the same process. The moment a specialist lives in a different Foundry project, a different subscription, or a different organisation, you need A2A.

The A2A tool implements the open A2A protocol, so it works with any A2A-compatible endpoint, not just agents built on Foundry. You configure a project connection in the Foundry portal (key-based auth, managed OAuth, managed identity, or agent identity are all supported), and your agent references that connection by name at runtime. The code example has a readme with a step by step guide for creating the connection via Foundry.

// example-03: A2A cross-boundary agent call using Azure.AI.Projects SDK

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using OpenAI.Responses;

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string modelDeployment = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-4.1-mini";
string a2aConnectionName = Environment.GetEnvironmentVariable("FOUNDRY_A2A_CONNECTION_NAME")
    ?? throw new InvalidOperationException("FOUNDRY_A2A_CONNECTION_NAME is not set.");
// Only needed when the connection type is not RemoteTool_Preview (i.e., raw A2A endpoints
// stored as a non-RemoteTool connection type won't carry the URI automatically).
string? a2aBaseUri = Environment.GetEnvironmentVariable("FOUNDRY_A2A_BASE_URI");

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());

// Resolve the connection name to a full AIProjectConnection.
// The .Id property is the ARM resource path used by A2APreviewTool.
AIProjectConnection a2aConnection = projectClient.Connections.GetConnection(a2aConnectionName);

// Configure the A2A tool with the connection ID.
A2APreviewTool a2aTool = new()
{
    ProjectConnectionId = a2aConnection.Id
};

// The docs describe checking for "RemoteA2A" connection type to decide whether to set BaseUri.
// In Azure.AI.Projects 2.0.1, the corresponding enum value is ConnectionType.RemoteTool
// (string value "RemoteTool_Preview"). A RemoteTool connection carries the A2A endpoint URI
// inside the connection record; other connection types require BaseUri to be set explicitly.
if (a2aConnection.Type != ConnectionType.RemoteTool)
{
    if (string.IsNullOrWhiteSpace(a2aBaseUri))
    {
        throw new InvalidOperationException(
            $"Connection '{a2aConnection.Name}' has type '{a2aConnection.Type}' (not RemoteTool). " +
            "Set FOUNDRY_A2A_BASE_URI to the A2A endpoint base URI.");
    }
    a2aTool.BaseUri = new Uri(a2aBaseUri);
}

// Build the agent definition with the A2A tool.
DeclarativeAgentDefinition agentDefinition = new(model: modelDeployment)
{
    Instructions = "You are a helpful assistant.",
    Tools = { a2aTool }
};

// Create a server-side Prompt Agent version.
// This deploys the agent definition to Foundry; the returned ProjectsAgentVersion
// carries .Name and .Version for subsequent calls.
ProjectsAgentVersion agentVersion = projectClient.AgentAdministrationClient
    .CreateAgentVersion(
        agentName: "example-03-a2a-agent",
        options: new ProjectsAgentVersionCreationOptions(agentDefinition));

Console.WriteLine($"Agent created: {agentVersion.Name} (version {agentVersion.Version})");

try
{
    // Get a ProjectResponsesClient scoped to this agent.
    // GetProjectResponsesClientForAgent takes an AgentReference (name + version),
    // not just a string — the overload in the Microsoft docs that accepts a bare string
    // does not exist in Azure.AI.Extensions.OpenAI 2.0.0.
    AgentReference agentRef = new(agentVersion.Name, agentVersion.Version);
    ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForAgent(agentRef);

    // Send the message, forcing the agent to use the A2A tool via CreateRequiredChoice().
    CreateResponseOptions responseOptions = new()
    {
        ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
        InputItems = { ResponseItem.CreateUserMessageItem("What can the secondary agent do?") }
    };

    ResponseResult response = await responseClient.CreateResponseAsync(responseOptions);

    if (response.Status != ResponseStatus.Completed)
    {
        throw new InvalidOperationException($"Response did not complete. Status: {response.Status}");
    }

    Console.WriteLine($"[Response from remote A2A agent]: {response.GetOutputText()}");
}
finally
{
    // Clean up the server-side agent version regardless of success or failure.
    projectClient.AgentAdministrationClient
        .DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
    Console.WriteLine("Agent version deleted.");
}

The gotcha that caught me first: A2APreviewTool needs a ProjectConnectionId, not a raw URL. Resolve the connection name to a full connection object with projectClient.Connections.GetConnection(connectionName) at startup. The .Id property is what the tool uses.

The connection type check deserves a clear explanation, because the official docs sample and the C# SDK spell the connection type differently and it looks like a contradiction. The official docs sample does string.Equals(a2aConnection.Type.ToString(), "RemoteA2A"), comparing against the string "RemoteA2A", which is the backend REST connection category name that comes back from the Foundry portal API. That string does not exist as a named constant in the C# SDK. In Azure.AI.Projects 2.0.1, the typed value is ConnectionType.RemoteTool, whose .ToString() is "RemoteTool_Preview". Same concept, completely different strings. The code here uses the typed SDK value, ConnectionType.RemoteTool, which is correct. A RemoteTool connection carries the A2A endpoint URI inside the connection record automatically; any other type doesn't, so you also need to set a2aTool.BaseUri explicitly. The code handles that branch inline.

When wiring up the responses client, GetProjectResponsesClientForAgent expects an AgentReference(name, version), not a bare string. The single-string overload shown in some documentation does not exist in Azure.AI.Extensions.OpenAI 2.0.0. Use new AgentReference(agentVersion.Name, agentVersion.Version) as the code shows.

The OpenAI.Responses types used here (CreateResponseOptions, ResponseToolChoice, ResponseResult, and friends) carry [Experimental("OPENAI001")] in the SDK. Without <NoWarn>$(NoWarn);OPENAI001</NoWarn> in your PropertyGroup, the build fails with errors rather than warnings. Add that suppression before you try to compile; the example includes it and the comment explains why.

Example-03 uses Azure.AI.Projects 2.0.1 directly rather than via Microsoft.Agents.AI.Foundry. One thing worth knowing: on net10.0, DefaultAzureCredential resolves without a separate Azure.Identity package reference. Azure.Core 1.53.0 embeds the identity types for that target, so the using Azure.Identity; directive resolves through the transitive chain. You do not need an extra <PackageReference>.

Before you build anything for production on this: the A2A feature is currently in public preview. The Azure.AI.Projects 2.0.1 NuGet package is a stable GA release, so that's not the issue. The issue is the A2A feature itself, which Microsoft's official docs flag with a preview banner and the note that it is not recommended for production workloads. A2APreviewTool is not a holdover class name from an earlier API; it reflects where the feature sits today. No SLA, behaviour subject to change. For demos and internal tooling, fine. For customer-facing infrastructure, wait for GA or decide consciously that you accept the risk.

ResponseToolChoice.CreateRequiredChoice() is worth using when you want to guarantee the agent actually calls the remote endpoint rather than answering from its own context.

When does A2A actually earn its overhead? When the specialist is owned by a different team and deployed independently, when multiple callers need to reach the same endpoint without sharing a process, or when you're integrating with a non-Microsoft agent that speaks the A2A protocol. You might also have an agent that you want to expose to multiple consumers (internally or externally) where it makes sense to call the agent through A2A with authentication.

For same-team, same-codebase work, AsAIFunction() beats A2A on every practical dimension.

Personally, I'm currently exploring using A2A from an n8n workflow calling an agent that knows how to provide me with a daily brief. The daily brief agent has an agent card and sits behind authentication, which n8n knows how to call.

Choosing the pattern in code

If you're onboarding a team to these patterns, it helps to make the decision explicit in code rather than leaving it in a doc somewhere that nobody reads. The following example captures a simplistic approach to selecting a scenario.

I was unsure to whether to include this code in the post - it could probably also have been a matrix with options and green checks / red x's, but then it would be something you put in your docs (that nobody reads) and I wanted to have something like this in code ... here you go:

// example-04: Static decision harness — recommends an agent composition pattern

// ---- Scenarios ----

var scenarios = new (string Label, AgentScenario Scenario)[]
{
    (
        "same process, same model, 1 specialist",
        new AgentScenario(
            SpecialistsNeedDifferentModels: false,
            IndependentDeploymentRequired: false,
            CrossProcessOrCrossSubscription: false,
            NumberOfSpecialists: 1)
    ),
    (
        "same process, different models, 2 specialists",
        new AgentScenario(
            SpecialistsNeedDifferentModels: true,
            IndependentDeploymentRequired: false,
            CrossProcessOrCrossSubscription: false,
            NumberOfSpecialists: 2)
    ),
    (
        "different models, independent deployment needed",
        new AgentScenario(
            SpecialistsNeedDifferentModels: true,
            IndependentDeploymentRequired: true,
            CrossProcessOrCrossSubscription: false,
            NumberOfSpecialists: 2)
    ),
    (
        "cross-subscription specialist",
        new AgentScenario(
            SpecialistsNeedDifferentModels: false,
            IndependentDeploymentRequired: false,
            CrossProcessOrCrossSubscription: true,
            NumberOfSpecialists: 1)
    ),
};

foreach (var (label, scenario) in scenarios)
{
    var rec = RecommendPattern(scenario);
    Console.WriteLine($"Scenario: {label} → {rec.Pattern}: \"{rec.Rationale}\"");
}

// ---- Decision logic ----

static Recommendation RecommendPattern(AgentScenario scenario)
{
    // Rule 1: cross-process or cross-subscription boundary — only A2A can reach it.
    if (scenario.CrossProcessOrCrossSubscription)
        return new(CompositionPattern.A2A,
            "Cross-subscription boundary requires A2A.");

    // Rule 2: independently deployed specialist — use A2A to avoid coupling deployments.
    if (scenario.IndependentDeploymentRequired)
        return new(CompositionPattern.A2A,
            "Independent deployment requires A2A; use A2APreviewTool.");

    // Rule 3: multiple specialists with different model requirements — AsAIFunction lets
    // each specialist use its own model connection while staying in-process.
    if (scenario.SpecialistsNeedDifferentModels && scenario.NumberOfSpecialists >= 2)
        return new(CompositionPattern.AsAIFunction,
            "Use AsAIFunction() to compose specialists in-process.");

    // Rule 4: multiple specialists, same model — AsAIFunction works; evaluate whether
    // a single agent with multiple tools is simpler before committing to orchestration.
    if (scenario.NumberOfSpecialists >= 2)
        return new(CompositionPattern.AsAIFunction,
            "Use AsAIFunction() to compose specialists in-process; " +
            "consider single-agent-with-tools first if specialists share a model.");

    // Rule 5: one specialist, same process — no orchestration layer needed.
    return new(CompositionPattern.SingleAgentWithTools,
        "One agent with tools handles this; no orchestration needed.");
}

// ---- Types (must follow all top-level executable statements in C# top-level programs) ----

record AgentScenario(
    bool SpecialistsNeedDifferentModels,
    bool IndependentDeploymentRequired,
    bool CrossProcessOrCrossSubscription,
    int NumberOfSpecialists
);

enum CompositionPattern
{
    SingleAgentWithTools,
    AsAIFunction,
    A2A
}

record Recommendation(CompositionPattern Pattern, string Rationale);

This is pure C#, no Foundry SDK required. The value is as executable documentation: it makes the selection criteria visible and gives you something concrete to point to in a code review when someone reaches for A2APreviewTool and AsAIFunction() would have been fine.

Foundry Workflows retirement

If you use the Foundry visual workflow designer, the date to note is December 1, 2026. After that, the portal designer and in-portal execution stop working. The orchestration patterns themselves (sequential pipelines, group chat, human-in-the-loop) are not disappearing. They carry over to Agent Framework, which supports both declarative YAML and code-first.

The migration options Microsoft recommends:

Your situation	Where to go
Sequential or group-chat orchestration, want code-first	Microsoft Agent Framework (YAML or C#)
Visual designer is a requirement for your team	Azure Logic Apps
One agent calling another, no formal workflow needed	A2A

Before you do anything else, export your workflow YAML from the portal. The YAML view gives you a portable definition, and in many cases you can take that exported YAML into an Agent Framework project and run it as a hosted agent with minimal changes. That's the closest thing to a lift-and-shift that exists.

One pattern worth flagging separately: group-chat orchestration (where agents hand off to each other dynamically based on context) is documented in Agent Framework and the portal supports it today. But there is no published .NET sample for group chat at time of writing. If that's your target pattern, watch the agent-framework GitHub; samples appear regularly. For the migration path with the most stable .NET footing right now, sequential composition via AsAIFunction() or the A2A tool is a good place to start.

Observability

Be upfront with your team about this: multi-agent workflow tracing is currently in preview. Single-agent OpenTelemetry integration is GA and works well. Step 07 in the Foundry samples covers it. But cross-agent trace correlation, the ability to see a ResearchAgent → OrchestratorAgent → WriterAgent span tree in a single trace, is not yet production-ready.

For now, instrument each agent individually and correlate by session ID when you need to stitch runs together. It's a manual process and honestly a bit annoying, but running blind is worse. Keep an eye on the workflow tracing docs as multi-agent observability matures. It's the obvious next step once the patterns themselves have stabilised.

Before you go

The agent-as-function-tool pattern handles most real-world multi-agent scenarios in .NET without introducing deployment complexity. A2A is the right answer when you hit an actual organisational or process boundary (this could be an integration between an off-the-shelf workflow engine and your custom agent). Everything else is usually just adding hops for its own sake, and every hop is a model call you're paying for.

Start with the simplest thing that can work. One agent, good tools, a clear system prompt. You can always split later when the need arises.

Code Examples

You can find the examples and a markdown version of this article on my github. On github you'll find that the article has a few more notes in the code, which I intentionally left out here as its a bit verbose.
Code examples for this article

Sources

https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/agent-to-agent: A2A tool: full C# SDK sample for both Prompt Agent (using A2APreviewTool) and Hosted Agent (using weatherAgent.AsAIFunction()) patterns, connection types, authentication methods, A2A endpoint hosting options (2026-07-21).
https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/workflow: Workflow patterns (sequential, group chat, human-in-the-loop), retirement announcement (December 1, 2026), migration guide to Agent Framework / Logic Apps / A2A, YAML portability (2026-07-21).
https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/02-agents/AgentProviders/foundry: .NET foundry agent samples including Agent_Step11_AsFunctionTool (in-process multi-agent composition), confirming the AsAIFunction() and AsAIAgent() extension method patterns (2026-07-21).
https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/tool-catalog: Tool catalog overview confirming A2A tool as GA custom tool; Toolbox as MCP-compatible multi-tool bundle for cross-agent reuse (2026-07-21).

Building Your First Agent with Microsoft Foundry Agent Service from .NET

Morten Christensen — Thu, 23 Jul 2026 07:04:13 +0000

For this post I wanted to share how I approached building my first agent in Microsoft Foundry Agent Service with C#. Every resource you actually need, every CLI command that provisions it, and the SDK code explained rather than assumed. If you've found a cleaner setup, or disagree with any of the trade-offs I mention here, I'd genuinely like to hear it.

I'm writing this because the official quickstart is Python-first and hides the Azure setup behind azd scaffolding. It doesn't tell you which resources you actually need, what the RBAC role assignments are, or why the SDK now ships four NuGet packages and which one will silently break your build. The C# SDK stabilised at 2.0.0 in mid-2026, the product was renamed from Azure AI Foundry at the same time, and the RBAC role names changed too. Hit the documentation cold and three separate things look broken at once. None of them are.

First, the naming situation

The service was called Azure AI Foundry. It's now called Microsoft Foundry. The RBAC roles went with it: the role you assign to give a developer project access is now Foundry User (previously Azure AI User). The role IDs (the GUIDs) are unchanged, which matters when you script the assignment. Portal screens, error messages, and a lot of existing tutorials still use the old names. You're not confused; the rollout just isn't finished yet.

What you need in Azure

Four things:

A Foundry resource (top-level Azure resource, kind AIServices)
A project inside that resource
A deployed model
A role assignment so your identity can call the API

That's it. No Storage account, no Search index, nothing else for the basic prompt-agent path. Here's a setup script:

#!/usr/bin/env bash
# setup.sh — Provision all Azure resources needed for the Foundry Agent Service examples.
# Run from any directory. Requires the Azure CLI (az) to be installed and logged in.
#
# Usage:
#   chmod +x setup.sh
#   ./setup.sh
#
# The final line prints the PROJECT_ENDPOINT you should export before running the C# examples.

set -euo pipefail

RESOURCE_GROUP="foundry-agent-rg"
LOCATION="eastus2"
RESOURCE_NAME="foundry-agent-demo"   # Must be globally unique — change this to something specific to your org
PROJECT_NAME="first-agent-project"
DEPLOYMENT_NAME="gpt-5.4-mini"
MODEL_NAME="gpt-5.4-mini"
MODEL_VERSION="2026-03-17"           # Verified GA version for gpt-5.4-mini as of July 2026
SKU_NAME="GlobalStandard"
SKU_CAPACITY=10

echo "=== Step 1: Create resource group ==="
az group create \
  --name "$RESOURCE_GROUP" \
  --location "$LOCATION"

echo ""
echo "=== Step 2: Create Foundry resource ==="
echo "Note: This can take 1–2 minutes. --allow-project-management cannot be changed after creation."
az cognitiveservices account create \
  --name "$RESOURCE_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --kind AIServices \
  --sku S0 \
  --location "$LOCATION" \
  --custom-domain "$RESOURCE_NAME" \
  --allow-project-management \
  --yes

echo ""
echo "=== Step 3: Create project ==="
az cognitiveservices account project create \
  --name "$RESOURCE_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --project-name "$PROJECT_NAME"

echo ""
echo "=== Step 4: Deploy model ==="
az cognitiveservices account deployment create \
  --name "$RESOURCE_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --deployment-name "$DEPLOYMENT_NAME" \
  --model-name "$MODEL_NAME" \
  --model-format "OpenAI" \
  --model-version "$MODEL_VERSION" \
  --sku-name "$SKU_NAME" \
  --sku-capacity "$SKU_CAPACITY"

echo ""
echo "=== Step 5: Get project resource ID for RBAC ==="
PROJECT_ID=$(az cognitiveservices account project show \
  --name "$RESOURCE_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --project-name "$PROJECT_NAME" \
  --query id -o tsv)
echo "Project resource ID: $PROJECT_ID"

echo ""
echo "=== Step 6: Get current user ==="
CURRENT_USER=$(az account show --query user.name -o tsv)
echo "Current user: $CURRENT_USER"

echo ""
echo "=== Step 7: Assign Foundry User role on project ==="
# Using the stable GUID for the Foundry User role (previously 'Azure AI User').
# The display name was renamed; the GUID is unchanged.
az role assignment create \
  --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
  --assignee "$CURRENT_USER" \
  --scope "$PROJECT_ID"

echo ""
echo "=== Done ==="
echo ""
echo "Project endpoint URL:"
echo "https://${RESOURCE_NAME}.services.ai.azure.com/api/projects/${PROJECT_NAME}"
echo ""
echo "Set this in your shell before running the C# examples:"
echo "export PROJECT_ENDPOINT=\"https://${RESOURCE_NAME}.services.ai.azure.com/api/projects/${PROJECT_NAME}\""
echo "export AGENT_NAME=\"first-agent\""

A couple of things worth calling out. The --custom-domain value becomes part of your project endpoint URL and must be globally unique, so pick something specific to your organisation, not just foundry-agent-demo. The --allow-project-management flag cannot be changed after the resource is created, so don't skip it.

Use the role definition GUID for the assignment rather than the display name. The display name was just renamed and, depending on your tenant, it may resolve incorrectly during the rollout period. The GUID is stable.

Deploy into East US 2 if you have a choice. The model router and every standard built-in tool are available there. Some regions are missing tools, and the tool availability matrix is worth checking before you commit if you plan to use code interpreter or file search.

The project endpoint you'll use in code looks like https://<resource-name>.services.ai.azure.com/api/projects/<project-name>. Copy it from the Foundry portal once provisioning finishes, or construct it from the names you used in the script.

Prompt agents or hosted agents?

Before writing any code, it's worth being clear about what you're actually building. Foundry Agent Service has two meaningfully different modes.

Prompt agents are defined declaratively: model, instructions, tools. Foundry runs them for you. No application code to maintain, no compute to pay for. You send a request to the Responses API and get an answer back. For internal tools, question-answering, pipelines without custom orchestration logic: this is where I'd start.

Hosted agents are code you write yourself (Agent Framework, LangGraph, the OpenAI Agents SDK, or anything else), packaged as a container and run on Foundry-managed compute. You get a managed endpoint, autoscaling, and a dedicated Entra identity. You also pay for container compute on top of inference. This is the right choice when you need custom business logic embedded in the agent, not just configuration.

This article covers prompt agents. Hosted agents from .NET use the Microsoft Agent Framework (a separate open-source project) and are different enough to deserve their own treatment. I'll cover that in the next post in this series.

The packages, and the one to avoid

The C# SDK for Foundry requires four packages:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <!-- Azure AI Projects: thin client over the Foundry project API.
         Provides AIProjectClient and access to AgentAdministrationClient. -->
    <PackageReference Include="Azure.AI.Projects" Version="2.0.1" />

    <!-- Azure AI Projects Agents: agent administration surface.
         Provides DeclarativeAgentDefinition, ProjectsAgentVersion,
         CreateAgentVersion, DeleteAgentVersion, and the tool type hierarchy. -->
    <PackageReference Include="Azure.AI.Projects.Agents" Version="2.0.0" />

    <!-- Azure AI Extensions OpenAI: invocation surface.
         Provides ProjectResponsesClient, ProjectConversationsClient,
         ProjectConversation, and GetProjectResponsesClientForAgent. -->
    <PackageReference Include="Azure.AI.Extensions.OpenAI" Version="2.0.0" />

    <!-- Azure Identity: DefaultAzureCredential (resolves via az login locally,
         managed identity in production — same code path either way). -->
    <PackageReference Include="Azure.Identity" Version="1.21.0" />

    <!--
      *** DO NOT ADD ***
      Azure.AI.Projects.OpenAI (preview) defines the same types as
      Azure.AI.Extensions.OpenAI in different namespaces. Installing both
      causes ambiguous reference compile errors that are difficult to diagnose.
      Use only Azure.AI.Extensions.OpenAI.
    -->
  </ItemGroup>

</Project>

Azure.AI.Projects is the thin client over the Foundry project API. Azure.AI.Projects.Agents adds the agent administration surface: creating, versioning, and deleting definitions. Azure.AI.Extensions.OpenAI is what you use to invoke the agent; it provides ProjectResponsesClient, which calls the Responses API on your project endpoint. Azure.Identity covers credentials.

The one to avoid is Azure.AI.Projects.OpenAI. It's a preview package that defines the same types in a different namespace. Install it alongside Azure.AI.Extensions.OpenAI and you get ambiguous reference compile errors that take a while to trace back to the source. The comment in the project file says the same thing. Just don't add it.

Creating your first agent

Here's a complete console application. It creates a prompt agent, asks a question, then asks a follow-up that only makes sense if the model remembers the first answer:

using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;
using System.ClientModel;

// Configuration — read from environment variables.
string projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("PROJECT_ENDPOINT environment variable is not set.");

string agentName = Environment.GetEnvironmentVariable("AGENT_NAME") ?? "first-agent";

// 1. Create the project client.
AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// 2. Define the agent declaratively: model choice + system instructions.
DeclarativeAgentDefinition agentDefinition = new("gpt-5.4-mini")
{
    Instructions = "You are a helpful assistant."
};

// 3. Register the agent version.
ClientResult<ProjectsAgentVersion> agentVersionResult =
    projectClient.AgentAdministrationClient.CreateAgentVersion(
        agentName,
        options: new ProjectsAgentVersionCreationOptions(agentDefinition));

ProjectsAgentVersion agentVersion = agentVersionResult.Value;
Console.WriteLine($"Agent registered: name={agentVersion.Name}, version={agentVersion.Version}");

// 4. Create a conversation.
ClientResult<ProjectConversation> conversationResult =
    projectClient.ProjectOpenAIClient
        .GetProjectConversationsClient()
        .CreateProjectConversation(options: null);

ProjectConversation conversation = conversationResult.Value;
Console.WriteLine($"Conversation created: id={conversation.Id}");

// 5. Get a responses client bound to this agent and conversation.
ProjectResponsesClient responsesClient =
    projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForAgent(
            defaultAgent: new AgentReference(agentVersion.Name),
            defaultConversationId: conversation.Id);

// 6. First turn.
ClientResult<ResponseResult> turn1Result =
    responsesClient.CreateResponse(userInputText: "What is the capital of Denmark?",
                                   previousResponseId: null);

ResponseResult turn1 = turn1Result.Value;
Console.WriteLine($"[Turn 1]: {turn1.GetOutputText()}");

// 7. Second turn — the model knows from conversation history what "that city" refers to.
ClientResult<ResponseResult> turn2Result =
    responsesClient.CreateResponse(userInputText: "And what is the population of that city?",
                                   previousResponseId: null);

ResponseResult turn2 = turn2Result.Value;
Console.WriteLine($"[Turn 2]: {turn2.GetOutputText()}");

// Note: agent version is intentionally not deleted here.
// example-04 creates its own agent; cleanup instructions are in README.md.

A few things to walk through.

AIProjectClient takes the project endpoint URI and a TokenCredential. Locally, DefaultAzureCredential resolves via az login. In production it picks up a managed identity without any code change.

ClientResult<T> shows up on every method that returns something from the service. It's in the System.ClientModel package, which is pulled in transitively, but you still need using System.ClientModel; in your file. Call .Value to get the actual object.

DeclarativeAgentDefinition is where model choice and system instructions live. It goes into CreateAgentVersion, which registers a versioned definition in Foundry. Each call creates a new immutable version. The method returns ClientResult<ProjectsAgentVersion>; call .Value to get the ProjectsAgentVersion, which carries the stable name and version string you'll reference at invocation time.

ProjectConversation is what carries history across turns. Pass the conversation ID to GetProjectResponsesClientForAgent alongside new AgentReference(agentVersion.Name), and each CreateResponse call on that client automatically includes prior context. One detail: CreateResponse always requires a previousResponseId argument, even if you're passing null. The second question in the example knows what "that city" refers to because of the conversation binding, not because you're stitching history together yourself. Honestly this is the bit that surprised me most. Less work than I expected.

Adding web search

The web search tool grounds the agent's responses in real-time public web data. It runs Bing Search under the hood. Two things to know before you enable it: there's an additional per-query cost, and the Microsoft Data Protection Addendum does not apply to data sent to Bing. If you're in a regulated environment, check the Grounding with Bing terms first. For internal tools or prototypes, it's fine.

The change to the agent definition is small:

using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;
using System.ClientModel;

// Configuration — read from environment variables.
string projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("PROJECT_ENDPOINT environment variable is not set.");

string agentName = Environment.GetEnvironmentVariable("AGENT_NAME") ?? "web-search-agent";

// 1. Create the project client.
AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// 2. Define the agent with the web search tool.
DeclarativeAgentDefinition agentDefinition = new("gpt-5.4-mini")
{
    Instructions = "You are a helpful assistant that can search the web."
};

agentDefinition.Tools.Add(
    ResponseTool.CreateWebSearchPreviewTool(
        userLocation: WebSearchToolLocation.CreateApproximateLocation(
            country: "DK",
            region: "Capital Region",
            city: "Copenhagen",
            timezone: null)));

// 3. Register the agent version.
ClientResult<ProjectsAgentVersion> agentVersionResult =
    projectClient.AgentAdministrationClient.CreateAgentVersion(
        agentName,
        options: new ProjectsAgentVersionCreationOptions(agentDefinition));

ProjectsAgentVersion agentVersion = agentVersionResult.Value;
Console.WriteLine($"Agent registered: name={agentVersion.Name}, version={agentVersion.Version}");

// 4. Create a conversation.
ClientResult<ProjectConversation> conversationResult =
    projectClient.ProjectOpenAIClient
        .GetProjectConversationsClient()
        .CreateProjectConversation(options: null);

ProjectConversation conversation = conversationResult.Value;

// 5. Get a responses client bound to this agent and conversation.
ProjectResponsesClient responsesClient =
    projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForAgent(
            defaultAgent: new AgentReference(agentVersion.Name),
            defaultConversationId: conversation.Id);

// 6. Call the agent with a web search query.
ClientResult<ResponseResult> responseResult =
    responsesClient.CreateResponse(
        userInputText: "What is in the tech news today?",
        previousResponseId: null);

ResponseResult response = responseResult.Value;

// 7. Print the text response.
Console.WriteLine($"\nResponse: {response.GetOutputText()}");

// 8. Extract URL citations from the response output items.
Console.WriteLine("\nCitations:");
bool foundCitation = false;

foreach (ResponseItem item in response.OutputItems)
{
    if (item is MessageResponseItem messageItem)
    {
        foreach (ResponseContentPart part in messageItem.Content)
        {
            // OutputTextAnnotations is only populated on output_text parts.
            if (part.Kind == ResponseContentPartKind.OutputText)
            {
                foreach (ResponseMessageAnnotation annotation in part.OutputTextAnnotations)
                {
                    if (annotation is UriCitationMessageAnnotation citation)
                    {
                        Console.WriteLine($"  Citation: {citation.Title} — {citation.Uri}");
                        foundCitation = true;
                    }
                }
            }
        }
    }
}

if (!foundCitation)
{
    Console.WriteLine("  (no URL citations returned — web search may not have been triggered)");
}

// 9. Clean up: delete the agent version.
// DeleteAgentVersion takes agentName and agentVersion (the version string, e.g. "1").
projectClient.AgentAdministrationClient.DeleteAgentVersion(
    agentName: agentVersion.Name,
    agentVersion: agentVersion.Version);

Console.WriteLine($"\nCleaned up: agent version {agentVersion.Name}:{agentVersion.Version} deleted.");

The invocation is identical to the basic example. CreateResponse returns ClientResult<ResponseResult>; call .Value.GetOutputText() for the text. The difference shows up in what's attached to that response: the output items contain UriCitationMessageAnnotation entries for the sources the model cited.

Two things to watch for if you copy this. First: the correct factory is ResponseTool.CreateWebSearchPreviewTool, not CreateWebSearchTool. Both exist in OpenAI 2.9.x. CreateWebSearchTool serialises to "type": "web_search", which the Foundry Responses API currently rejects with a 400. CreateWebSearchPreviewTool serialises to "web_search_preview", which Foundry accepts. Second: DeclarativeAgentDefinition.Tools is a read-only property. You can't set it in an object initialiser. Call .Add() after construction, as the code above does.

The userLocation hint is optional but worth setting if your agent answers questions for users in a specific region. Bing uses it to bias results. Omitting it still works.

Web search is in preview. It's available in East US 2 and most major regions, but check the tool support matrix for your target region before you depend on it in production.

Cost and a few regional notes

For prompt agents you pay for inference tokens. When web search is enabled, Bing Search usage is on top of that. With gpt-5.4-mini Global Standard and developer-level traffic, a full day of testing runs well under a dollar. No premium quota tier required.

Tool availability varies by region. Code interpreter is unavailable in South Central US and Spain Central as of this writing. East US 2 has the broadest coverage. Check the tool support matrix before you settle on a deployment region; it's easier to pick the right one up front than to migrate a resource after the fact.

The DeclarativeAgentDefinition you built here maps directly to what you'd put in a CI/CD pipeline. Create the agent version during deployment, update the definition when instructions change, roll back by version ID when something breaks. That versioning model is where prompt agents become production-usable rather than just a demo.

Hosted agents from .NET, and what the Microsoft Agent Framework brings to that picture, is where this series goes next.

Code Examples

Sources

https://learn.microsoft.com/en-us/azure/foundry/agents/overview — Agent Service overview, agent type comparison, GA confirmation (2026-07-21)
https://learn.microsoft.com/en-us/azure/foundry/how-to/develop/sdk-overview?pivots=programming-language-csharp — .NET SDK packages, C# code samples, package conflict warning, RBAC role rename notice (2026-07-21)
https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/function-calling — C# prompt agent and hosted agent function calling samples, tool execution loop (2026-07-21)
https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent — Hosted agent prerequisite resources, provisioning steps (2026-07-21)
https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/limits-quotas-regions — GA status confirmation, regional support matrix, tool availability by region and model (2026-07-21)

One approach to structuring terraform

Morten Christensen — Sun, 19 Mar 2023 14:59:42 +0000

For this post I wanted to share how I prefer to structure my terraform code for use with multiple environments, modules and how I can work with it locally. If you have a different approach then please feel free to leave a comment - I'm always happy to learn and improve.

First off, the folder structure. The infrastructure folder sits in the root along side src, test, build and whatever else goes in the git repository.

.
├── infrastructure
│   │── environments
│   │   ├── dev
│   │   ├── live
│   │   ├── main
│   └── modules

Within an environment folder I would put local.backend.tfvars and local.secrets.tfvars files for local development purposes. These files should NOT be committed to git, so I always make sure to include them in the .gitignore file of the repository.
Then there is the backend.tfvars file, which is used to configure the backend used for the terraform state. Finally the (maybe?) most important file for the environment variables.tfvars, which contains all the environment specific variables. A good example of this is using different SKUs of Azure App Service in Development versus Production. It could also be the subscription used for the environment - maybe you want to use an Azure Dev/Test Subscription for Development and a CSP/PAYG subscription for Production.

The main folder contains the main.tf, secrets.tf, outputs.tf and variables.tf files. Depending on the size and content of the main.tf file I tend to split it up into multiple files, so I don't end up having to scroll thousands of lines of code. The structure and naming of files can vary depending on what makes sense, but one simple approach is to divide the different types of resources into different files. There will likely be things like KeyVault or Networking, which ties into other resources, so it really depends.

The modules folder is used for reusable modules. It's not always relevant, but I tend to keep the modules outside of the environments. The structure highlights that its reusable across environments.

Working locally

When you need to run Terraform locally against the Development environment, use the steps listed below.

Ensure that you have both local.backend.tfvars and local.secrets.tfvars in your environment folder with the actual keys in place.

cd infrastructure/environments/main
terraform init -backend-config="../dev/local.backend.tfvars"
terraform validate
terraform plan -var-file="../dev/local.secrets.tfvars" -detailed-exitcode -out=tfplan

Let's have a look at the content of the local.backend.tfvars when using Azure Blob Storage as the backend for the terraform state.

resource_group_name     = "rg-terraform-state-we-dev"
storage_account_name    = "terraformwestatedev"
container_name          = "terraform-state-dev"
key                     = "azure/terraform.tfstate"
access_key              = "<actual access key goes here>"

The content of the local.secrets.tfvars should correspond to what you put in the secrets.tf from within the main folder, and what is needed to create resources within Azure/AWS/GCP. For Azure it would be Service Principal details.

tenant_id       = "<actual tenant id goes here>"
subscription_id = "<actual subscription id goes here>"
client_id       = "<actual client id goes here>"
client_secret   = "<actual client secret goes here>"

When working locally you could connect to the development environment or use a different subscription / account setup. If you use the same subscription and terraform state locally as when deploying to development, you should be aware of the changes between working locally versus deploying via CI/CD. The deployed changes might revert what you are testing locally, and other deployments might fail because the state is expecting resources, which are not part of what is being deployed.

main.tf

With the backend and secrets setup as mentioned above there is one important thing to include in the main.tf file - the required providers and something like azurerm as the backend like so:

terraform {
  backend "azurerm" {}
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "= 2.29.0"
    }
    cloudflare = {
      source  = "terraform-providers/cloudflare"
      version = "~> 2.9.0"
    }
  }
}

The backend part is what will be "filled" with the *backend.tfvars files.

Azure DevOps, Terraform and Secrets

When running infrastructure as code (IaC) as part of a pipeline in something like Azure DevOps (same applies to Github Actions and other CI/CD setups), you want to keep your secrets safe and inject them when needed as part of the pipeline.
In order to run the terraform init, plan and apply commands there needs to be a backend for storing state and there needs to be secrets (like a Service Principal) for creating the actual resources in Azure. We also need to know, which environment we are deploying to, so we can select the right one (using the variables.tfvars file that corresponds to the environment).

The secrets can be added as a variable group for the environment under Pipelines/Library in Azure DevOps. You could also store the secrets in KeyVault and connect KeyVault to Azure DevOps, so they are not visible by anyone.

The backend.tfvars for the development environment would typically look like this:

resource_group_name     = "rg-terraform-state-we-dev"
storage_account_name    = "terraformwestatedev"
container_name          = "terraform-state-dev"
key                     = "azure/terraform.tfstate"
access_key              = "#{terraform_access_key}"

As you can see its pretty much the same as the local.backend.tfvars where the only difference is the access_key property, which will be replaced within the pipeline.

The secrets.tf file within the main folder will be variable definitions for the secrets needed to run the terraform. These variables will need to be set in the pipeline, so the IaC can be initialized.

variable "tenant_id" {
  description = "Azure subscription tenant id."
}

variable "subscription_id" {
  description = "Azure subscription id."
}

variable "client_secret" {
  description = "Azure provider client secret"
}

variable "client_id" {
  description = "Azure provider Azure AD client id."
}

Within the variables.tfvars file for an environment I keep the variable secrets as tokens, which can later be replaced:

tenant_id       = "#{tenant_id}"
subscription_id = "#{subscription_id}"
client_id       = "#{client_id}"
client_secret   = "#{client_secret}"

When doing this in Azure DevOps with a YAML pipeline I use the following approach for replacing the tokens with secrets and generating - here its the validation stage of the pipeline:

parameters:
  variable_group_name:
  environment_name:
  working_directory:
  source_branch:

jobs:
  - job: Validate
    displayName: Terraform Validate Plan
    continueOnError: false
    variables:
      - name: tf_work_dir
        value: "$(working_directory)/environments/main"
      - group: ${{ format('telemetry-{0}', parameters.environment_name) }}
      - ${{ if ne(parameters.variable_group_name, '') }}:
          - group: ${{ format('{0}-{1}', parameters.variable_group_name, parameters.environment_name) }}
    steps:
      - task: qetza.replacetokens.replacetokens-task.replacetokens@3
        displayName: "Replace tokens in *.tfvars with variables from the desired Variable Group"
        inputs:
          targetFiles: "$(working_directory)/environments/$(environment_name)/*.tfvars => *.env.tfvars"
          encoding: "auto"
          writeBOM: true
          actionOnMissing: "warn"
          keepToken: false
          tokenPrefix: "#{"
          tokenSuffix: "}"
      - bash: |
          terraform init -backend-config="../$(environment_name)/backend.env.tfvars" -input=false
        displayName: Initialize configuration
        workingDirectory: $(tf_work_dir)
      - bash: terraform validate
        displayName: Validate configuration
        workingDirectory: $(tf_work_dir)

      - bash: |
          terraform plan -var-file="../$(environment_name)/variables.env.tfvars" -input=false
        displayName: Create execution plan
        workingDirectory: $(tf_work_dir)

With this setup I can work with terraform locally, and I can choose to create a throw-away environment for trying out different things locally without interfering with Development. Alternatively, I can run it against the Development environment, which can be handy if resources needs to be imported or deleted without having to involve a pipeline.
I can create any number of environments, which can have each their own subscription and resource configuration.

Here is the file structure with all of the mentioned files

The screenshot is from a real world telemetry service, which is composed of a Cloudflare Worker (point of entry / reverse proxy) and an Azure backend (API and Storage).