Microsoft Foundry — Agent Service
Azure's managed agent runtime. Now branded Microsoft Foundry (portal ai.azure.com; docs
under /azure/foundry/, previous generation under /azure/foundry-classic/; RBAC roles
renamed "Foundry User/Owner/…"). The classic Agent Service went GA May 2025 (REST
api-version 2025-05-01) with the OpenAI-Assistants-style agents / threads / runs /
messages model; the current service centers on the Responses API as the single entry
point. Overview: https://learn.microsoft.com/azure/foundry/agents/overview
Two agent types
| Type |
What it is |
When |
| Prompt agents |
Config-only: instructions + model + tools, authored in portal or SDK/REST. Fully managed runtime — no code or compute to manage. |
Tool-using assistants where instructions + built-in tools suffice |
| Hosted agents (preview) |
Your code — built with Agent Framework, LangGraph, OpenAI Agents SDK, Anthropic SDK, GitHub Copilot SDK, or custom — shipped as a container or zip. Foundry provides the managed endpoint, autoscale, dedicated Entra identity per agent, session-state persistence, and observability. Your code calls the Responses API for models + platform tools. |
Custom agent loops that still want managed hosting/identity/observability |
Classic threads/runs semantics: run states queued → in_progress → requires_action → completed/failed/cancelled/expired; threads up to 100K messages; optional BYO Cosmos DB
for thread storage.
Tools
- Built-in: web search / Grounding with Bing (+ Bing Custom Search), Code Interpreter,
File Search (vector stores), function calling, Azure AI Search, Azure Functions, Logic
Apps (event triggers), Microsoft Fabric, SharePoint, Deep Research (o3-deep-research),
Browser Automation, Computer Use, Image Generation, memory.
- Custom: MCP servers, OpenAPI 3.0/3.1 specs, A2A (preview).
- Connected agents — compose multi-agent systems without an external orchestrator.
- Publishing targets include Teams / M365 Copilot and the Entra Agent Registry.
SDKs and CLI
| Surface |
Names |
| Python |
azure-ai-projects (>=2.0.0, AIProjectClient) + azure-identity; classic threads/runs library azure-ai-agents; hosted-agent server libs azure-ai-agentserver-responses / azure-ai-agentserver-invocations |
| .NET |
Azure.AI.Projects (AgentAdministrationClient) |
| Agent Framework hosting |
pip install agent-framework agent-framework-foundry-hosting → ResponsesHostServer |
| CLI |
azd ext install microsoft.foundry; azd ai agent show | invoke | monitor |
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
project_client = AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
)
agent = project_client.agents.get("<your-agent-name>")
client = project_client.get_openai_client() # Responses API access
# Classic threads/runs REST (GA api-version 2025-05-01)
curl -X POST "$ENDPOINT/threads/thread_abc123/runs?api-version=2025-05-01" \
-H "Authorization: Bearer $AGENT_TOKEN" -H "Content-Type: application/json" \
-d '{"assistant_id": "asst_abc123"}'
Identity, observability, evaluation
- Identity: hosted agents get a dedicated Microsoft Entra identity; grant that
identity least-privilege access to downstream resources instead of sharing app secrets.
- Observability: server-side traces for prompt and hosted agents in the portal
(90 days); Application Insights auto-injection for hosted agents; OpenTelemetry via the
Microsoft OpenTelemetry Distro (
microsoft-opentelemetry). External agents can be
registered for trace/eval scoping.
- Evaluations: agent evaluators (Task Adherence, Intent Resolution) and
AIAgentConverter in azure-ai-evaluation — run evaluations as a pre-deploy gate
(see /msagent-deploy).
Practices
- Prefer prompt agents until you actually need a custom loop; hosted agents add container
lifecycle you must own.
- Use connected agents before reaching for an external orchestrator; reserve Agent
Framework workflows for logic Foundry can't express.
- Ground on your data via File Search/Azure AI Search rather than stuffing context into
instructions.
- BYO thread storage (Cosmos DB) when compliance requires data in your subscription.
- Reaching M365 channels: publish from the portal (auto-provisions Azure Bot Service +
Entra) or front with the M365 Agents SDK — see
skills/agent-interop.
1---2name: microsoft-foundry3description: Run agents on Microsoft Foundry (formerly Azure AI Foundry) Agent Service — prompt agents vs hosted agents, threads/runs and the Responses API, built-in tools (Bing grounding, code interpreter, file search, MCP, OpenAPI, A2A), connected agents, Entra agent identity, SDKs, and observability/evaluations.4---56# Microsoft Foundry — Agent Service78Azure's managed agent runtime. Now branded **Microsoft Foundry** (portal ai.azure.com; docs9under `/azure/foundry/`, previous generation under `/azure/foundry-classic/`; RBAC roles10renamed "Foundry User/Owner/…"). The classic Agent Service went **GA May 2025** (REST11api-version `2025-05-01`) with the OpenAI-Assistants-style **agents / threads / runs /12messages** model; the current service centers on the **Responses API** as the single entry13point. Overview: https://learn.microsoft.com/azure/foundry/agents/overview1415## Two agent types1617| Type | What it is | When |18|---|---|---|19| **Prompt agents** | Config-only: instructions + model + tools, authored in portal or SDK/REST. Fully managed runtime — no code or compute to manage. | Tool-using assistants where instructions + built-in tools suffice |20| **Hosted agents** (preview) | *Your* code — built with **Agent Framework, LangGraph, OpenAI Agents SDK, Anthropic SDK, GitHub Copilot SDK, or custom** — shipped as a container or zip. Foundry provides the managed endpoint, autoscale, **dedicated Entra identity per agent**, session-state persistence, and observability. Your code calls the Responses API for models + platform tools. | Custom agent loops that still want managed hosting/identity/observability |2122Classic threads/runs semantics: run states `queued → in_progress → requires_action →23completed/failed/cancelled/expired`; threads up to 100K messages; optional BYO Cosmos DB24for thread storage.2526## Tools2728- **Built-in:** web search / Grounding with Bing (+ Bing Custom Search), Code Interpreter,29 File Search (vector stores), function calling, Azure AI Search, Azure Functions, Logic30 Apps (event triggers), Microsoft Fabric, SharePoint, Deep Research (o3-deep-research),31 Browser Automation, Computer Use, Image Generation, memory.32- **Custom:** **MCP** servers, **OpenAPI 3.0/3.1** specs, **A2A** (preview).33- **Connected agents** — compose multi-agent systems without an external orchestrator.34- Publishing targets include Teams / M365 Copilot and the **Entra Agent Registry**.3536## SDKs and CLI3738| Surface | Names |39|---|---|40| Python | **`azure-ai-projects` (>=2.0.0, `AIProjectClient`)** + `azure-identity`; classic threads/runs library `azure-ai-agents`; hosted-agent server libs `azure-ai-agentserver-responses` / `azure-ai-agentserver-invocations` |41| .NET | `Azure.AI.Projects` (`AgentAdministrationClient`) |42| Agent Framework hosting | `pip install agent-framework agent-framework-foundry-hosting` → `ResponsesHostServer` |43| CLI | `azd ext install microsoft.foundry`; `azd ai agent show \| invoke \| monitor` |4445```python46import os47from azure.identity import DefaultAzureCredential48from azure.ai.projects import AIProjectClient4950project_client = AIProjectClient(51 endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],52 credential=DefaultAzureCredential(),53)54agent = project_client.agents.get("<your-agent-name>")55client = project_client.get_openai_client() # Responses API access56```5758```bash59# Classic threads/runs REST (GA api-version 2025-05-01)60curl -X POST "$ENDPOINT/threads/thread_abc123/runs?api-version=2025-05-01" \61 -H "Authorization: Bearer $AGENT_TOKEN" -H "Content-Type: application/json" \62 -d '{"assistant_id": "asst_abc123"}'63```6465## Identity, observability, evaluation6667- **Identity:** hosted agents get a dedicated **Microsoft Entra identity**; grant that68 identity least-privilege access to downstream resources instead of sharing app secrets.69- **Observability:** server-side traces for prompt and hosted agents in the portal70 (90 days); Application Insights auto-injection for hosted agents; OpenTelemetry via the71 **Microsoft OpenTelemetry Distro** (`microsoft-opentelemetry`). External agents can be72 registered for trace/eval scoping.73- **Evaluations:** agent evaluators (Task Adherence, Intent Resolution) and74 `AIAgentConverter` in `azure-ai-evaluation` — run evaluations as a pre-deploy gate75 (see `/msagent-deploy`).7677## Practices7879- Prefer prompt agents until you actually need a custom loop; hosted agents add container80 lifecycle you must own.81- Use connected agents before reaching for an external orchestrator; reserve Agent82 Framework workflows for logic Foundry can't express.83- Ground on your data via File Search/Azure AI Search rather than stuffing context into84 instructions.85- BYO thread storage (Cosmos DB) when compliance requires data in your subscription.86- Reaching M365 channels: publish from the portal (auto-provisions Azure Bot Service +87 Entra) or front with the M365 Agents SDK — see `skills/agent-interop`.
markus41