Quickstart: Deploy your own code as a hosted agent

In Deploy your first hosted agent, you deployed a sample. In this quickstart, you deploy your own Python agent code to Foundry Agent Service.

Prerequisites

Before you begin, you need:

• An Azure subscription--Create one for free.

• If you have an existing Foundry project, you need Foundry Project Manager at project scope. If you need to create a new Foundry project, you need Owner role at resource group scope. For the full role matrix, see Hosted agent permissions reference.

• Azure Developer CLI (AZD) 1.25.3 or later.

• The azd microsoft.foundry extension:

  azd ext install microsoft.foundry
  

• Your existing agent code in a local directory.

• Python 3.13 or later.

Your project directory should contain at minimum:

my-agent/
├── main.py              # Your agent entry point
└── requirements.txt     # Python dependencies

Choose your protocol

Select the tab that matches your agent's interaction pattern. Responses manages conversation history and is OpenAI-compatible. Invocations gives you full control over request and response schemas.

Step 1: Add the hosting library

Add the protocol library to your requirements.txt. The library handles the HTTP server, health checks, and protocol compliance.

azure-ai-agentserver-responses>=1.0.0b7

azure-ai-agentserver-invocations>=1.0.0b5

Step 2: Add the hosting wrapper

Create or update main.py with the hosting wrapper. The examples show the minimal pattern—replace the marked block with your existing agent logic.

import asyncio
from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()


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

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_input}"
    # ─────────────────────────────

    return TextResponse(context, request, text=reply)


app.run()

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

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    raw = (await request.body()).decode("utf-8").strip()
    try:
        body = json.loads(raw)
        user_message = (
            body.get("message") or body.get("input") or raw
        )
    except json.JSONDecodeError:
        user_message = raw

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_message}"
    # ─────────────────────────────

    return JSONResponse({"reply": reply})


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

Step 3: Initialize the project

Run azd ai agent init from your agent source directory:

azd ai agent init --protocol responses --deploy-mode code

azd ai agent init --protocol invocations --deploy-mode code

The interactive flow prompts for:

• Agent name: Customize the name or accept the default.
• Foundry Project: Select Use an existing Foundry project or Create a new Foundry project.
• Subscription: Select your Azure subscription.
• Location: Select an Azure region.

When complete, you see: AI agent definition added to your azd project successfully!

Step 4: Provision Azure resources

azd provision

This creates the required Azure resources, such as Application Insights.

Step 5: Test the agent locally

azd ai agent run

This command creates a virtual environment, installs dependencies, and launches your agent. It also opens the agent inspector in your browser so you can chat with the agent.

You can also invoke from the CLI in a separate terminal:

azd ai agent invoke --local "Hello from my hosted agent"

Step 6: Deploy to Foundry Agent Service

azd deploy

When the command finishes, the output shows links to the agent playground and the agent endpoint:

Deploying services (azd deploy)

  Done: Deploying service my-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/my-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/my-agent/versions/1

Step 7: Invoke the deployed agent

azd ai agent invoke "Hello from my hosted agent"

You should see a response within a few seconds.

Clean up resources

azd down

Troubleshooting

For the full permission and role-assignment matrix, see Hosted agent permissions reference.

What you learned

In this quickstart, you:

• Added one hosting library to your existing agent code.
• Initialized an azd project from your source directory.
• Tested locally with azd ai agent run and azd ai agent invoke --local.
• Deployed to Foundry Agent Service with azd deploy.

Next steps

• Build a toolbox and use it with a hosted agent to combine tools behind one managed endpoint.

Related content

• What are hosted agents?
• Deploy a hosted agent from source code
• Deploy a hosted agent from a container
• Agent development lifecycle
• Python hosted agent samples
• C# hosted agent samples