Edit

Deploy a steerable agent (preview)

In this article, you deploy a long-running hosted agent that supports steering: when a second turn arrives on the same conversation while the first turn is still running, the platform queues the new turn and cooperatively cancels the current one instead of rejecting it with 409 conversation_locked.

The sample is a Microsoft Agent Framework agent that turns steering on with a single option.

Note

Long-running agents are in preview. APIs and package versions are subject to change.

Prerequisites

  • An Azure subscription with Microsoft Foundry access and a model deployment.
  • The Azure Developer CLI (azd) with the Foundry agents extension.
  • The Azure CLI.
  • uv to run the steering client.

Get the sample

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/python/steering-maf

The agent enables steering when it constructs the host:

app = ResponsesAgentServerHost(
    options=ResponsesServerOptions(steerable_conversations=True),
)

By using steerable_conversations=True, a second turn on a busy conversation is queued and the running handler is cooperatively cancelled, rather than returning 409 conversation_locked.

Provision and deploy

Authenticate, create an environment, and provision the project. When prompted for a location, choose a region that supports hosted agents.

azd extension install azure.ai.agents
azd auth login
az login

azd env new
azd provision
azd deploy

Get the hosted Responses endpoint and create a session:

azd ai agent show --output json
azd ai agent sessions create --output json

Run the steering client

Pass the endpoint and the returned agent_session_id to the client. The client starts a long streaming turn, submits a second turn on the same conversation two seconds later, and shows the first turn ending early before the queued turn completes.

uv run ./client.py \
  --endpoint "https://<account>.services.ai.azure.com/api/projects/<project>/agents/steering-agent/endpoint/protocols/openai/responses?api-version=v1" \
  --session-id "<agent-session-id>"

Both turns use the same hosted session and Responses conversation ID. The first turn observes the queued input and winds down at its next safe point; the queued turn then runs to completion.

Clean up

azd down

Related content

  • Last updated on