# Deploy a durable agent to Foundry hosted agents

[Foundry hosted agents](https://learn.microsoft.com/azure/foundry/agents/concepts/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](https://docs.diagrid.io/integrations/microsoft-foundry/getting-started?agentframework=langgraph) 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.

**Diagram: A Diagrid-enabled agent in a Foundry hosted sandbox.** The sandbox only opens outbound connections. It calls the model as the agent identity, and reaches Diagrid with the API token of its Diagrid ID.

- **Microsoft Foundry**: Agent endpoint (Responses protocol), Model deployment (called as the agent identity)
  - **Hosted sandbox**: Agent container (LangGraph + Diagrid)
- **Diagrid**: Workflows
- Your client (Entra ID token)

- Your client (Entra ID token) → Agent endpoint (Responses protocol)
- Agent endpoint (Responses protocol) → Agent container (LangGraph + Diagrid)
- Agent container (LangGraph + Diagrid) → Model deployment (called as the agent identity)
- Agent container (LangGraph + Diagrid) → Workflows (API token)

## 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](https://learn.microsoft.com/azure/foundry/agents/how-to/virtual-networks) in the Foundry documentation.

## Prerequisites

- The [quickstart](https://docs.diagrid.io/integrations/microsoft-foundry/getting-started?agentframework=langgraph) 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](https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agents#region-availability)
- 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](https://learn.microsoft.com/azure/container-registry/container-registry-get-started-azure-cli)
- [jq](https://jqlang.org/download/)

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:

```bash
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:

```bash
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.

```python title="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:

```bash
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:

```bash
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 title="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:

```text title=".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:

```bash
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:

```bash
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:

```bash
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:

```yaml title="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:

```bash
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:

```bash
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:

```bash
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`:

```bash
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:

```bash
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](https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions#agent-access-beyond-defaults) 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:

```bash
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:

```json
{
  "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:

```bash
diagrid workflow list --project foundry-quickstart --id travel-planner-hosted
```

```text
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](https://docs.diagrid.io/integrations/microsoft-foundry/getting-started#8-inspect-the-execution):

```bash
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:

```bash
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:

```bash
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](https://docs.diagrid.io/integrations/microsoft-foundry/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](https://learn.microsoft.com/azure/foundry/agents/how-to/deploy-hosted-agent).
- Control which services and tools the agent can call with [access policies](https://docs.diagrid.io/develop/agents/langgraph/langgraph-access-policies).
- Watch runs, token use and failures in [Operate agents](https://docs.diagrid.io/operate/project-operations/agents).
