Add a protocol adapter to your hosted agent

Add Responses or Invocations protocol support to a hosted agent: install the SDK adapter package, wire up a handler, declare the protocol, and redeploy.

Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

A protocol adapter is a lightweight SDK wrapper that lets your agent code speak one of the Microsoft Foundry hosted agent protocols. In this article, you install the SDK adapter package, wire up a handler, declare the protocol in azure.yaml, and redeploy. Add an adapter when you bring your own code that doesn’t already implement the hosted agent runtime contract.

Prerequisites

• A hosted agent project. To create one, see Initialize a hosted agent project with the Azure Developer CLI.
• Python 3.10 or later, or .NET 8 or later.
• Your agent logic in a function you can call from a handler.

Choose a protocol

Protocol	When to use
responses	Conversational agents. You get automatic conversation history, streaming, and OpenAI Responses API compatibility.
invocations	Non-conversational or custom-payload workloads. You define the request and response shape.

For the full contract details, see Hosted agent runtime contract.

Install the SDK package

Python

    # For the Responses protocol
    pip install azure-ai-agentserver-responses

    # For the Invocations protocol
    pip install azure-ai-agentserver-invocations

Implement a handler

The patterns below are abridged from the bring-your-own samples in the foundry-samples repository. Use them as a starting point and copy the full sample for production code.

Responses protocol

Python

    import asyncio
    import os

    from azure.ai.agentserver.responses import (
        CreateResponse,
        ResponseContext,
        ResponsesAgentServerHost,
        ResponsesServerOptions,
        TextResponse,
    )
    from azure.ai.projects import AIProjectClient
    from azure.identity import DefaultAzureCredential

    _endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    _model = os.environ["FOUNDRY_MODEL_NAME"]

    _project_client = AIProjectClient(
        endpoint=_endpoint, credential=DefaultAzureCredential()
    )
    _responses_client = _project_client.get_openai_client().responses

    app = ResponsesAgentServerHost(
        options=ResponsesServerOptions(default_fetch_history_count=20),
    )

    @app.response_handler
    async def handler(
        request: CreateResponse,
        context: ResponseContext,
        _cancellation_signal: asyncio.Event,
    ):
        user_input = await context.get_input_text() or "Hello!"

        # --- Your agent logic goes here ---
        response = await asyncio.get_running_loop().run_in_executor(
            None,
            lambda: _responses_client.create(
                model=_model,
                instructions="You are a helpful AI assistant.",
                input=[{"role": "user", "content": user_input}],
                store=False,
            ),
        )
        # -----------------------------------

        return TextResponse(context, request, text=response.output_text)

    app.run()

Invocations protocol

Python

    from starlette.requests import Request
    from starlette.responses import Response, JSONResponse
    from azure.ai.agentserver.invocations import InvocationAgentServerHost

    app = InvocationAgentServerHost()

    @app.invoke_handler
    async def handle_invoke(request: Request) -> Response:
        data = await request.json()
        # --- Your agent logic goes here ---
        # The payload shape is entirely up to you
        message = data.get("message", "Hello!")
        return JSONResponse({"reply": message})

    if __name__ == "__main__":
        app.run()

Declare the protocol in azure.yaml

Add or update the protocols field in the azure.ai.agent service in your azure.yaml:

services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    protocols:
      - protocol: responses
        version: 2.0.0

For invocations, use the following protocol:

services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    protocols:
      - protocol: invocations
        version: 1.0.0

Update your startup command

Make sure the startupCommand in the azure.ai.agent service points to the entry point that starts the server:

services:
  my-agent:
    host: azure.ai.agent
    startupCommand: python main.py

Test locally and redeploy

# Test locally
azd ai agent run

# In another terminal
azd ai agent invoke --local "Hello!"

# Deploy
azd deploy

For the invocations protocol, use --input-file to send your custom payload:

azd ai agent invoke --local -f request.json

Add a second protocol

An agent can support multiple protocols. To add a second one, install the additional SDK package, register both handlers in your entry point, and add both protocols to the azure.ai.agent service in azure.yaml:

services:
  my-agent:
    host: azure.ai.agent
    protocols:
      - protocol: responses
        version: 2.0.0
      - protocol: invocations
        version: 1.0.0

When an agent supports multiple protocols, azd ai agent invoke uses the responses protocol by default. Pass -p/--protocol to select responses or invocations explicitly.

Related content

• Hosted agent runtime contract
• What are hosted agents?
• Author azure.yaml for hosted agents