Deploy a durable agent to Foundry hosted agents
Foundry hosted agents run your agent container in a sandbox that Foundry manages, and give the agent an endpoint and an identity. This guide deploys the LangGraph agent from the quickstart as a hosted agent. The agent keeps its Diagrid runner, so every request to the Foundry endpoint is a durable workflow in your Diagrid project.
How the hosted agent connects
| Concern | How it works in the sandbox |
|---|---|
| Protocol | The container serves the Foundry Responses protocol on port 8088 with the azure-ai-agentserver-responses package. The handler passes each request to the Diagrid runner. |
| Identity for Foundry | Foundry creates a Microsoft Entra identity for the agent when you deploy it. DefaultAzureCredential resolves to that identity in the sandbox, and you grant it access to the model. |
| Identity for Diagrid | The agent authenticates with the API token of its Diagrid ID. Foundry injects the token from a project connection, so it is in neither the image nor the agent definition. |
| Connectivity | The sandbox opens outbound connections to the HTTP and gRPC endpoints of your Diagrid project on port 443. Diagrid never connects in to the sandbox. |
If your Foundry resource routes outbound traffic through your own virtual network, allow the two project endpoints there. See Configure virtual networks in the Foundry documentation.
Prerequisites
- The quickstart completed with the LangGraph tab. You need its
travel-plannerfolder and itsfoundry-quickstartDiagrid project. - A Foundry project in a region that supports hosted agents
- The Foundry Project Manager role on the Foundry project, to create the connection and the agent
- Permission to assign roles on the Foundry resource and on the container registry, such as Owner or Role Based Access Control Administrator
- An Azure Container Registry
- jq
The commands on this page use these placeholders: <foundry-resource>, <foundry-project>, <resource-group>, <model-deployment> and <registry>.
1. Create a Diagrid ID for the hosted agent
Give the hosted agent its own ID:
diagrid agent create travel-planner-hosted --project foundry-quickstart --wait
Every process that connects with an ID must run the same agent code, because Diagrid can give any step of a run to any of them. A separate ID keeps the hosted agent apart from the agent you run on your machine.
2. Serve the Foundry Responses protocol
In the travel-planner folder, add the Foundry protocol library:
uv add "azure-ai-agentserver-responses==2.4.0"
Create main.py. It is agent.py from the quickstart with one change: instead of runner.serve(), a Foundry Responses host receives the request and passes it to the runner.
import os
from azure.ai.agentserver.responses import (
CreateResponse,
ResponseContext,
ResponsesAgentServerHost,
TextResponse,
)
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from diagrid.agent.langgraph import DaprWorkflowGraphRunner
from langchain.agents import create_agent
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_weather(city: str) -> str:
"""Get the weather forecast for a city."""
return f"The forecast for {city} is sunny, 22°C."
@tool
def search_flights(origin: str, destination: str) -> str:
"""Search for flights between two cities."""
return f"Found 3 flights from {origin} to {destination}, from $420 round trip."
# Microsoft Foundry model. In Foundry, DefaultAzureCredential resolves to the
# hosted agent's own identity, and FOUNDRY_PROJECT_ENDPOINT is injected.
model = ChatOpenAI(
model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
base_url=os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/") + "/openai/v1",
api_key=get_bearer_token_provider(
DefaultAzureCredential(), "https://ai.azure.com/.default"
),
)
agent = create_agent(
model,
tools=[get_weather, search_flights],
system_prompt="You are a travel planner. Use the tools to check the weather "
"and find flights, then reply with a short plan.",
)
# Diagrid: run the agent as a durable workflow.
runner = DaprWorkflowGraphRunner(graph=agent, name="travel-planner")
runner.start()
# Foundry: serve the Responses protocol on port 8088.
app = ResponsesAgentServerHost()
@app.response_handler
async def handler(request: CreateResponse, context: ResponseContext, _cancellation_signal):
task = await context.get_input_text() or ""
async for event in runner.run_async(
input={"messages": [{"role": "user", "content": task}]}
):
if event["type"] == "workflow_completed":
answer = event["output"]["messages"][-1]["content"]
return TextResponse(context, request, text=answer)
if event["type"] == "workflow_failed":
raise RuntimeError(f"Workflow {event['workflow_id']} failed: {event['error']}")
if __name__ == "__main__":
app.run()
Run it on your machine first:
diagrid dev run --project foundry-quickstart --id travel-planner-hosted -- uv run main.py
In a second terminal, send a request in the Responses format:
curl -X POST http://localhost:8088/responses \
-H "Content-Type: application/json" \
-d '{"input": "Plan a weekend trip from Seattle to Lisbon.", "stream": false}'
The response has "status": "completed" and the plan in output. Stop the agent with Ctrl+C before you continue.
3. Build the container image
Create a Dockerfile next to main.py:
FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim
WORKDIR /app
# Install the locked dependencies into /app/.venv, outside the session's $HOME.
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
COPY main.py .
# Foundry: disable user-site packages and serve on the Responses port.
ENV PYTHONNOUSERSITE=1
EXPOSE 8088
CMD ["/app/.venv/bin/python", "main.py"]
Create a .dockerignore file so that your local virtual environment stays out of the image:
.venv
__pycache__
Build the image in your registry. Foundry needs a linux/amd64 image, and a build in the registry produces one on any machine:
az acr build --registry <registry> --image travel-planner:v1 --platform linux/amd64 .
Foundry pulls the image with the managed identity of the Foundry project. Give that identity pull access to the registry:
az role assignment create \
--assignee-object-id "$(az cognitiveservices account project show --name <foundry-resource> --resource-group <resource-group> --project-name <foundry-project> --query identity.principalId --output tsv)" \
--assignee-principal-type ServicePrincipal \
--role AcrPull \
--scope "$(az acr show --name <registry> --query id --output tsv)"
4. Store the Diagrid API token in a Foundry connection
Print the endpoints of the Diagrid project and the API token of the hosted agent's ID:
diagrid project get foundry-quickstart
diagrid agent get travel-planner-hosted --project foundry-quickstart
Create a file named diagrid-connection.yaml with the gRPC endpoint and the API token:
type: api_key
target: <diagrid-grpc-endpoint>
credentials:
type: api_key
key: <diagrid-api-token>
Create the connection in the Foundry project, then delete the file:
az cognitiveservices account project connection create \
--name <foundry-resource> \
--resource-group <resource-group> \
--project-name <foundry-project> \
--connection-name diagrid \
--file diagrid-connection.yaml
rm diagrid-connection.yaml
Foundry stores the token as a secret. The agent definition in the next step refers to it as ${{connections.diagrid.credentials.key}}, and Foundry resolves that reference when a sandbox starts.
5. Create the hosted agent
Set the base URL of the Foundry project and get an access token:
BASE_URL="https://<foundry-resource>.services.ai.azure.com/api/projects/<foundry-project>"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken --output tsv)
Create the agent. Replace <diagrid-grpc-endpoint> and <diagrid-http-endpoint> with the endpoints from the previous step:
curl -X POST "$BASE_URL/agents?api-version=v1" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "travel-planner",
"definition": {
"kind": "hosted",
"container_configuration": {
"image": "<registry>.azurecr.io/travel-planner:v1"
},
"cpu": "1",
"memory": "2Gi",
"protocol_versions": [
{"protocol": "responses", "version": "2.0.0"}
],
"environment_variables": {
"AZURE_AI_MODEL_DEPLOYMENT_NAME": "<model-deployment>",
"DAPR_GRPC_ENDPOINT": "<diagrid-grpc-endpoint>",
"DAPR_HTTP_ENDPOINT": "<diagrid-http-endpoint>",
"DAPR_API_TOKEN": "${{connections.diagrid.credentials.key}}",
"PYTHONNOUSERSITE": "1"
}
}
}'
Foundry sets FOUNDRY_PROJECT_ENDPOINT in the sandbox itself. The three DAPR_ variables are the same ones that diagrid dev run set for you on your machine.
Check the version until its status is active:
curl -s "$BASE_URL/agents/travel-planner/versions/1?api-version=v1" \
-H "Authorization: Bearer $TOKEN" | jq -r .status
6. Give the agent access to the model
The response of the create request contains the agent's identity. Assign that identity the Cognitive Services OpenAI User role on the Foundry resource:
az role assignment create \
--assignee-object-id "$(curl -s "$BASE_URL/agents/travel-planner?api-version=v1" -H "Authorization: Bearer $TOKEN" | jq -r .instance_identity.principal_id)" \
--assignee-principal-type ServicePrincipal \
--role "Cognitive Services OpenAI User" \
--scope "$(az cognitiveservices account show --name <foundry-resource> --resource-group <resource-group> --query id --output tsv)"
Without a role, a hosted agent's identity can only use the Responses API of its project, as the Foundry permissions reference describes. This agent calls the Chat Completions API, which LangChain uses by default, so its identity needs the role. Wait a few minutes for the role assignment to take effect.
7. Invoke the hosted agent
Call the agent's Responses endpoint with a Microsoft Entra token:
curl -X POST "$BASE_URL/agents/travel-planner/endpoint/protocols/openai/responses?api-version=v1" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"input": "Plan a weekend trip from Seattle to Lisbon.", "store": true}'
The first request of a session takes longer, because Foundry starts a sandbox for it: about half a minute when this guide was tested. The response has "status": "completed" and the plan in output. This is the response with some fields left out:
{
"id": "caresp_0fa693af7026b9dd00GzVpohPAP9A3P6CWUYao9ePte5agKoVv",
"object": "response",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "Here’s a simple weekend plan for Seattle → Lisbon:\n\n- Weather: Lisbon is sunny and around 22°C …"
}
],
"status": "completed"
}
],
"agent_reference": { "type": "agent_reference", "name": "travel-planner", "version": "1" },
"status": "completed"
}
8. View the workflow in Diagrid
The request ran as a workflow under the hosted agent's Diagrid ID. List the executions of that ID:
diagrid workflow list --project foundry-quickstart --id travel-planner-hosted
APP ID WORKFLOW ID NAME START AT END AT STATUS VERIFICATION STATUS
travel-planner-hosted graph-0f33db5c-2b0b-424b-8fce-ac522ce7f991-f4fb0143 dapr.langgraph.TravelPlanner.workflow 2026-11-16T05:54:01.75405044Z 2026-11-16T05:54:06.755431607Z completed
The list also has the run from your local test in step 2.
Print the execution and its history in the same way as in the quickstart:
diagrid workflow get <workflow-id> --id travel-planner-hosted --project foundry-quickstart
The steps in the history ran inside the Foundry sandbox, and their results are stored in your Diagrid project.
Clean up
Delete the hosted agent and its sessions, then the connection:
curl -X DELETE "$BASE_URL/agents/travel-planner?api-version=v1&force=true" \
-H "Authorization: Bearer $TOKEN"
az cognitiveservices account project connection delete \
--name <foundry-resource> \
--resource-group <resource-group> \
--project-name <foundry-project> \
--connection-name diagrid
Delete the hosted agent's Diagrid ID:
diagrid agent delete travel-planner-hosted --project foundry-quickstart
A sandbox that is still running stays connected to Diagrid until its idle timeout, which is 15 minutes by default, even after you delete the agent.
Next steps
- Check Troubleshooting when a step doesn't behave as shown.
- Read how Microsoft's tooling deploys a hosted agent with the Azure Developer CLI in Deploy a hosted agent.
- Control which services and tools the agent can call with access policies.
- Watch runs, token use and failures in Operate agents.