Host Microsoft Agent Framework agents as Foundry hosted agents

Learn how to host Microsoft Agent Framework agents on Foundry hosted agents with the Responses and Invocations protocols

Use the Microsoft Agent Framework hosting packages to expose an Agent Framework agent through the protocols for Foundry hosted agents. The hosting packages let you keep your agent logic in code while Foundry manages the hosted runtime, sessions, scale, identity, and protocol endpoints.

In this article, you create a minimal Agent Framework agent, expose it through either the Responses or Invocations protocol, test it through HTTP, and deploy it to Foundry with the Azure Developer CLI.

Prerequisites

• An Azure subscription. Create one for free.
• A Foundry project.
• A deployed chat model, such as gpt-4.1 or gpt-4o.
• The Foundry Project Manager role on the project to deploy a hosted agent. For details, see Deploy a hosted agent.
• Azure CLI signed in (az login) so DefaultAzureCredential can authenticate.

Install the packages

Choose a hosting protocol

Hosted agents can expose one or more protocols. Start with Responses for most conversational agents.

Protocol	Endpoint	Use when
Responses	/responses	You want OpenAI-compatible chat, streaming, response history, and conversation threading.
Invocations	/invocations	You want a custom JSON shape, a webhook-style endpoint, or non-conversational processing.

For background on protocol behavior and sessions, see Hosted agents and Manage hosted agent sessions.

Configure environment variables

Set the project endpoint and model deployment name for local development:

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

In PowerShell:

$env:FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

When the same code runs as a hosted agent in Foundry, the platform injects FOUNDRY_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME at runtime.

Responses protocol

Use the Responses protocol when you want an OpenAI-compatible chat endpoint with streaming, response history, and conversation threading.

Create a Responses host

Test the Responses endpoint

Send a non-streaming Responses request to the local server.

Bash:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Give me one practical tip for testing hosted agents.","stream":false}'

PowerShell:

$body = @{
  input  = "Give me one practical tip for testing hosted agents."
  stream = $false
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri http://localhost:8088/responses `
    -Method Post `
    -Body $body `
    -ContentType "application/json"

The server responds with a JSON object that contains the response text and a response ID. For streaming responses, set stream to true. The host emits Responses API server-sent events, such as response.created, response.output_text.delta, and response.completed.

Multi-turn conversations

To continue a conversation, pass the previous response ID in the previous_response_id field of the next request:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Can you make that more concise?","previous_response_id":"<previous-response-id>","stream":false}'

When the agent runs in Foundry, the same pattern works through the hosted agent Responses endpoint. If later turns also need the same hosted sandbox filesystem, include agent_session_id or use a conversation ID. For details, see Manage hosted agent sessions.

Invocations protocol

Use the Invocations protocol when your callers can’t use the Responses API request shape or when your scenario isn’t a chat conversation. The Invocations host manages session state through an agent_session_id query parameter and response header.

Create an Invocations host

Test the Invocations endpoint

Send a request to the local server:

curl -sS -X POST http://localhost:8088/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"My name is Alice.","stream":false}'

For multi-turn conversations, reuse the agent_session_id value from the response header as the agent_session_id query parameter on the next request:

curl -sS -X POST "http://localhost:8088/invocations?agent_session_id=<session-id>" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is my name?"}'

The platform doesn’t store conversation history for the Invocations protocol. Use the agent_session_id query parameter to route later calls to the same hosted sandbox.

Deploy

Deploy by using the Azure Developer CLI (azd). The flow uses sample manifests and Docker to build the agent container image and roll it out to the Foundry hosted agent runtime.

Hosted agent deployment requires the Foundry Project Manager role on the project. For details, see Deploy a hosted agent.

Install the Azure Developer CLI extension

Install the AI agent extension and sign in before you initialize a sample:

azd ext install azure.ai.agents
azd auth login

Docker must be running locally because azd ai agent run builds the container image declared in the sample’s Dockerfile. For command details, see the Azure Developer CLI reference.

Initialize from a sample manifest

Create a new folder and initialize it from a sample manifest. Replace the manifest URL with the sample you want to use.

Follow the prompts from azd ai agent init. If you don’t already have a Foundry project and model deployment, the initialization flow can guide you through creating them.

Provision Azure resources

If the initialized project uses a new Foundry project and model deployment, provision the Azure resources first:

azd provision

This command creates a resource group that contains, among other resources, a Foundry instance, a Foundry project with a model deployment, an Application Insights instance, and a container registry for the hosted agent images.

Run the container locally

Run the agent host locally through azd:

azd ai agent run

The host serves on http://localhost:8088. In another terminal, invoke the local protocol endpoint:

azd ai agent invoke --local "Hello!"

You can also call the endpoint directly with curl:

curl -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello!"}'

Deploy to Foundry

Deploy the agent:

azd deploy

The deployment packages the agent into a container image, pushes it to the provisioned container registry, and rolls it out to the Foundry hosted agent runtime.

The Foundry hosting infrastructure injects runtime environment variables into the agent, including:

• FOUNDRY_PROJECT_ENDPOINT: The endpoint URL for the Foundry project where the agent is deployed.
• AZURE_AI_MODEL_DEPLOYMENT_NAME: The model deployment name selected during azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: The connection string for the project’s Application Insights instance.

For complete deployment concepts, permissions, and management details, see Deploy a hosted agent and Manage hosted agent lifecycle.

Troubleshooting

Use this checklist to diagnose common issues while developing hosted agents with Agent Framework.

The model can’t be reached in the hosted container

Confirm that the hosted agent version includes AZURE_AI_MODEL_DEPLOYMENT_NAME, and that the agent identity has permission to call the Foundry project. The platform sets FOUNDRY_PROJECT_ENDPOINT; your code should read that variable when running in Foundry.

Conversation state doesn’t continue

For the Responses protocol, pass previous_response_id or a conversation ID on later turns.

For the Invocations protocol, the platform doesn’t store conversation history. Use an agent_session_id query parameter to route later calls to the same hosted sandbox.

Protocol version mismatch

If requests fail after an upgrade, confirm that your manifest and hosting package both use protocol version 2.0.0. Protocol versions 1.0.0 and 2.0.0 are incompatible.

Next step

Deploy a hosted agent

Related content

• What is Foundry Agent Service?
• Hosted agents
• Manage hosted agent sessions
• Host LangGraph agents as Foundry hosted agents