Skip to main content

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.

A Diagrid-enabled agent in a Foundry hosted sandboxMicrosoft FoundryHosted sandboxDiagridYour clientEntra ID tokenAgent endpointResponses protocolAgent containerLangGraph + DiagridModel deploymentcalled as the agent identityWorkflowsAPI token
A Diagrid-enabled agent in a Foundry hosted sandboxThe sandbox only opens outbound connections. It calls the model as the agent identity, and reaches Diagrid with the API token of its Diagrid ID.

How the hosted agent connects​

ConcernHow it works in the sandbox
ProtocolThe 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 FoundryFoundry 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 DiagridThe 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.
ConnectivityThe 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-planner folder and its foundry-quickstart Diagrid 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.

main.py
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:

Dockerfile
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:

.dockerignore
.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:

diagrid-connection.yaml
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​