---
title: "How to Build an Agent With Azure AI Foundry"
url: "https://atlan.com/know/ai-agent/microsoft/how-to-build-an-agent-with-azure-ai-foundry/"
description: "Build an agent with Azure AI Foundry using prompt or hosted agents. Compare both paths, costs, and how to ensure your agents have full enterprise context."
author: "Emily Winks"
author_role: "Data Governance Expert"
published: "2026-08-12"
updated: "2026-08-12T00:00:00.000Z"
---

---

## Quick answer: How do you build an agent with Azure AI Foundry?

Azure AI Foundry (now rebranded as Microsoft Foundry) is the Azure service to build and run agents and agentic applications within Azure. Foundry has an Agent Service, which you can use to manage the runtime, identity, observability, and scalability of agents.

With Foundry, you can deploy agents in two different ways:

1. **Prompt Agents**: Deploy agents that are fully managed and prompt them to get things done without the hassle of having to manage agent code or compute. Pay only for token usage and tool use, and not runtime costs.

2. **Hosted Agents**: Deploy agents by writing, managing, packaging and maintaining your agent code yourself. Pay for the runtime, tokens, build process, and every other service that the agent uses separately.

---

## How do you build a prompt agent using Azure AI Foundry?

The simplest way to [create a prompt agent](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/prompt-agent?tabs=python) is to use the [Foundry portal](https://ai.azure.com/), where you get a step-by-step process to add instructions, select a model, add tools, and complete the agent build without worrying about where and how the code is deployed.

To create a [prompt agent](https://learn.microsoft.com/en-us/azure/foundry/concepts/choose-build-approach), follow these steps:

1. Create a Foundry project, which acts as the isolation boundary.

2. Go to the [model catalog](https://learn.microsoft.com/en-us/azure/foundry/concepts/foundry-models-overview) and choose one of the models, and deploy it.

3. Once you deploy it, go to the Build section, select Agents, and then the Create agent option; map your deployment to that agent.

4. Write instructions for your agent explaining its core job, goals, constraints, and boundaries.

5. Set up tools from the [tool catalog](https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/tool-catalog) that the agent can use, such as semantic search, code interpretation, web search, or image generation. Once tools are set, the agent is ready to be tested.

6. Test and work with the agent in the [Foundry playground](https://learn.microsoft.com/en-us/azure/foundry/concepts/concept-playgrounds).

Once you are done with initial testing of the agent, you can continue to edit and improve your agent within the playground. Every edit to the agent is version-controlled and snapshotted. This means that you can compare different versions of your agent and evaluate its performance over time.

When the agent is ready, you can publish it to an endpoint. Publishing automatically assigns the agent a Microsoft Entra agent identity, which shows up for governance and visibility in the [Microsoft 365 admin center's agent registry](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/agent-registry?view=o365-worldwide), a separate management surface, not something you add the agent to manually. That registry entry is a governance primitive, not a context one, which is why [agent context layer design](https://atlan.com/know/ai-agent/agent-context-layer-design/) decisions, what context that identity can actually pull once the agent is live, still need to happen separately.

![Entra agent registry for your Foundry agents](/images/how-to-build-an-agent-with-azure-ai-foundry/1-entra-agent-registry.webp){width=602 height=297}

**Source**: Microsoft Learn, https://learn.microsoft.com/en-us/microsoft-365/admin/manage/agent-registry?view=o365-worldwide

This is the fully managed path for creating an agent using Foundry. It saves you the headache of managing the runtime and infrastructure, building the agent image, and pulling and pushing the image to and from an image registry.

But there are times when you need customizability and flexibility in your agent to add capabilities that aren't available in the prompt agent option. That's when you look [towards a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/hosted-agents). Let's see how a hosted agent works in Foundry.

  Get the blueprint for your AI context stack
  See the four-layer architecture, from metadata foundation to agent orchestration, with practical implementation steps for 2026.
  Get the Stack Guide

---

## How do you build a hosted agent using Azure AI Foundry?

The basic agent harness that prompt agents provide doesn't suffice for complex production-grade use cases, especially when you need to control the agent loop and write your own orchestration logic. In such cases, you might choose an agent framework other than Microsoft Agent Framework, such as [LangGraph](https://atlan.com/know/ai-agent/ai-agent-memory/what-is-langgraph/), [CrewAI](https://atlan.com/know/ai-agent/what-is-crewai/), Anthropic Agent SDK, [OpenAI Agents SDK](https://atlan.com/know/open-ai-agents-sdk-vs-lang-chain-vs-crew-ai/), or [Mastra](https://atlan.com/know/best-ai-agent-harness-tools-2026/).

When you [create agents using an agent framework of your choice](https://atlan.com/know/ai-agent/how-to-choose-agentic-framework-enterprise/), you also get to package and push them to an agent image registry. This is the registry that Foundry will use to spin up micro VMs for running your agents. The easiest way to spin up your own agent is by using the [Azure Developer command-line tool](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd). Once you do, the steps aren't that different from prompt agents.

After setting up a Foundry project, you need to create a scaffold for your [agent harness](https://atlan.com/know/what-is-an-agent-harness/). This scaffold is defined and driven by an `azure.yaml` config file. Once that's done, go through the following steps:

1. Provision the infrastructure needed using `azd provision`. You'll need to provision a resource group, a model deployment, an Azure Container Registry, a Log Analytics Workspace, an Application Insights resource, and a managed identity for the agent.

2. The scaffold will have a basic agent definition, without any instructions or tools defined. However, you can add some once you have the scaffold tested. Test your agent locally with `azd ai agent run --no-inspector`.

3. Open another terminal window and try to run this: `azd ai agent invoke --local "Is this thing working?"`

4. Then you can deploy your agent to build the container image and push it to ACR. To do this, use the `azd deploy` command.

5. After publishing the agent, you can check the status of the agent with the `azd ai agent show` command.

Hosted agents, just like prompt agents, can use the same tool catalog and model catalog. The tools are available through the [Foundry Toolbox](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/toolbox), which is exposed using an [MCP endpoint](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/model-context-protocol) that the hosted agent can interact with directly. Hosted deployments that orchestrate more than one agent add a further wrinkle: [context engineering for multi-agent systems](https://atlan.com/know/context-engineering/context-engineering-for-multi-agents/) has to keep every sub-agent working from the same facts, not just calling the same tools.

Irrespective of which path you take to create your agents in Foundry, you need context beyond instructions and toolsets. You need [organizational context](https://atlan.com/know/how-to-implement-enterprise-context-layer-for-ai/). Let's look at how to get that context and why, despite the tool catalog having over 1,400 options, there's a better alternative to make context available to agents.

  Find your context gaps before Foundry does
  Run the Context Gap Calculator to see where an agent's context is thin before you wire tools into a hosted agent.
  Try the Gap Calculator

---

## How do you get relevant context for Azure AI Foundry agents?

Both prompt and hosted agents have access to the same set of tools from the tool catalog and also Microsoft services that facilitate context via specialized storage and retrieval, such as Azure AI Search, Cosmos DB, Azure Blob Storage, and Foundry IQ.

Despite having many tools in the tool catalog, agents can hit a wall when trying to get context in a typical enterprise. That's because enterprises comprise hundreds of systems, including systems of record, cloud platforms, external integrations, documentation systems, and communication systems.

Getting context from these systems alone isn't enough. The context itself has to be contextualized in relation to other systems, which is why you need information about [lineage](https://atlan.com/data-lineage/), [governance](https://atlan.com/know/data-governance/for-ai/), [quality](https://atlan.com/know/ai-agent/context-quality-testing-for-ai-agents/), [ownership](https://atlan.com/know/who-owns-the-context-layer/), and [policy](https://atlan.com/know/ai-governance-operating-model/). Each system's context stops at its boundary, which is why you need an [enterprise context layer](https://atlan.com/know/what-is-context-layer/) to stitch everything together and present a cogent, coherent, searchable and queryable layer where an agent can get the context it needs to do its work.

That connective-tissue gap is why a dedicated [agent context layer](https://atlan.com/know/agent-context-layer/) has become its own category, separate from a general-purpose [context graph](https://atlan.com/know/what-is-a-context-graph/), which itself gets confused with a [knowledge graph](https://atlan.com/know/context-graph-vs-knowledge-graph/) or an [ontology](https://atlan.com/know/context-graph-vs-ontology/) often enough that teams end up debating vocabulary instead of shipping. Some teams try [combining knowledge graphs with LLMs](https://atlan.com/know/combining-knowledge-graphs-llms/) directly to close that gap, but it still leaves the freshness and ownership problem unsolved.

That's exactly where [Atlan](https://atlan.com/) comes in. It saves you from having a ridiculous number of integrations, auth setups, and tool namespaces. Let's see how.

---

## How does Atlan enrich Foundry agents with an enterprise context layer?

Built on the **[Context Lakehouse](https://atlan.com/context-lakehouse/)** architecture, Atlan is the [Context Layer for AI](https://atlan.com/context-layer/). At the core is Atlan's **[MCP Server](https://atlan.com/know/what-is-atlan-mcp/)**, which delivers context to agents at runtime.

At the same time, Atlan connects to all the enterprise systems; a Foundry agent only has to act as the MCP client and ask Atlan for relevant context, thereby offloading a heavy piece of work that the agent would otherwise have to take up.

Atlan can be [added as a remote MCP tool](https://docs.atlan.com/product/capabilities/atlan-ai/how-tos/remote-mcp-overview) to a Foundry agent, using which agents can search assets, get context around them, traverse lineage, check governance and policy rules, and also write context back to Atlan.

Core capabilities include:

* **Enterprise Data Graph**: A [graph](https://atlan.com/know/enterprise-data-graph/) that contains the entity relationships between systems, assets, code, and products.

* [**Active Ontology**](https://atlan.com/know/what-is-ontology-in-ai/): Active Ontology distills organizational language and knowledge into glossary terms, domains, metrics, and relationships as a semantic layer, aligned with [Open Semantic Interchange](https://atlan.com/snowflake-open-semantic-interchange-launch-partner/).

* **Context Engineering Studio**: Use the [Context Engineering Studio](https://atlan.com/context-engineering-studio/) to build [Context Repos](https://atlan.com/know/ai-agent/context-repository-for-ai-agents/) for your projects, run evaluations based on different contexts, and deploy the best version for your agents to use.

The enterprise context layer offloads the complexity of gathering, accumulating, and organizing context. Atlan handles that work, while your Foundry agents communicate with Atlan's MCP server to get the most relevant and up-to-date context for any given task.

This is the same architecture regardless of which words a team reaches for. Whether you frame it as [context engineering](https://atlan.com/know/what-is-context-engineering/), as the difference between an [ontology and a semantic layer](https://atlan.com/know/ontology-vs-semantic-layer/), or as a straightforward [Model Context Protocol](https://atlan.com/know/what-is-model-context-protocol/) integration, the job is the same: one governed context source instead of agents assembling their own from scratch. It is also why analysts increasingly frame the problem as a [context graph](https://atlan.com/know/gartner-context-graphs/) challenge rather than a catalog one, and why [context engineering for AI governance](https://atlan.com/know/context-engineering-ai-governance/) treats policy as something that travels with the context instead of a review step bolted on afterward.

  See Atlan's context layer in action
  Watch a live walkthrough of how Atlan delivers context to AI agents at runtime.
  Watch Atlan in Action

---

## Moving forward with building an agent using Azure AI Foundry

Azure AI Foundry gives you two options to deploy agents into production: prompt agents and hosted agents. Prompt agents don't need you to manage the underlying infrastructure, agent loops, or any code. They are configuration-only and hassle-free. Hosted agents provide flexibility and customizability to address specific agentic needs, like using an agent framework, a runtime, or a container registry of your choice.

Irrespective of which type of agent you deploy using Azure AI Foundry, the important bit is the context, which is usually scattered across hundreds of systems in a typical enterprise setting.

The context of each of those systems stops at their own respective boundaries. That's where the need for Atlan arises, as it acts as the Context Layer for AI. Atlan's enterprise context layer stitches context from multiple systems and gives agents a unified view. Because of this, rather than maintaining one integration per system, you can point your agents to Atlan, and the context problem gets solved. Solving it organizationally still means deciding [whether data teams or AI teams should own the context layer](https://atlan.com/know/context-layer-ownership-data-vs-ai-teams/), since that call shapes how fast a Foundry rollout can move.

  Book a Demo

---

## FAQs about how to build an agent with Azure AI Foundry

### 1. What is the difference between prompt agents and hosted agents?

Prompt agents are fully managed, no-code agents where you only have to manage the configuration. Hosted agents, on the other hand, let you deploy your own containerized code, run by Foundry on infrastructure that it manages.

### 2. Which agent frameworks can I use for hosted agents?

You are free to choose almost any agent framework, including Microsoft Agent Framework, LangGraph, Anthropic Agent SDK, OpenAI Agents SDK, CrewAI, and AutoGen.

### 3. How do Foundry agents interact with Atlan's MCP server?

To use Atlan's MCP server, you need to add it as a remote MCP tool in Foundry. This allows a Foundry agent to act as an MCP client and send requests to the MCP server to get relevant context when it's working on a task.

### 4. What is a Foundry Toolbox?

A Foundry Toolbox is a curated set of tools that is available through a single MCP endpoint for a Foundry agent to use. The agent can access a wide range of tools, including web search, vector search, code interpretation, and more, from this single endpoint.

### 5. How much does it cost to run agents in Azure AI Foundry?

Prompt agents don't get charged separately for infrastructure. The only charge is based on token consumption and tool usage. Hosted agents, on the other hand, are charged based on the container infrastructure, token usage, and other Azure services they use.

---

## Sources

1. Microsoft Foundry, Microsoft Azure. https://ai.azure.com/home
2. Quickstart: Create a Prompt Agent, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/prompt-agent?tabs=python
3. Overview of Microsoft Foundry Models, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/concepts/foundry-models-overview
4. Types of Tools in Foundry Agent Service, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/tool-catalog
5. Microsoft Foundry Playgrounds, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/concepts/concept-playgrounds
6. Manage Agent Registry in Microsoft 365 Admin Center, Microsoft Learn. https://learn.microsoft.com/en-us/microsoft-365/admin/manage/agent-registry?view=o365-worldwide
7. Create and Manage a Toolbox in Foundry, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/toolbox?pivots=python
8. Connect Agents to Model Context Protocol Servers, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/model-context-protocol?pivots=python
9. Choose How to Build With Microsoft Foundry, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/concepts/choose-build-approach
10. What Are Hosted Agents?, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/hosted-agents