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 or .NET (C#) agent code to Foundry Agent Service. Your code can use any agent framework - such as Microsoft Agent Framework, LangGraph, the GitHub Copilot SDK, or the OpenAI Agents SDK - or plain code that calls a model directly.

Each code step has tabs for your language and protocol. Select the same combination, such as C# (Responses), in every step.

If you use a coding agent like GitHub Copilot, the Microsoft Foundry Skill can help adapt the quickstart to your own codebase and run the right azd deployment steps.

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.36.0 or later.

• The microsoft.foundry extension:

  azd ext install microsoft.foundry
  

• An authenticated azd session:

  azd auth login
  

• Your existing agent code in a local directory.

• For the Python path, Python 3.13 or later.

• For the C# path, the .NET 10 SDK or later.

• (Optional) To start from a sample in Visual Studio Code, install Visual Studio Code and the Microsoft Foundry Toolkit for Visual Studio Code.

Your project directory should contain at minimum, for Python:

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

Or, for C#, a .NET web project:

my-agent/
├── Program.cs           # Your agent entry point
└── my-agent.csproj      # Project file (web SDK)

Choose your framework

The hosting library you add in Step 1 handles the protocol - the HTTP server, health checks, and request and response schemas. It doesn't depend on a specific agent framework, so your agent logic can use any packages you prefer, in Python or C#.

To use a framework, add its packages next to the hosting library, then call the framework from the handler. The following table lists common choices and a Python sample for each.

Each sample's requirements.txt lists the exact package versions. For the full set of bring-your-own samples, see the Python samples folder.

For C#, add framework packages to your project file next to the hosting package, then call the framework from the handler in Program.cs. For the full set of C# examples, see the C# bring-your-own samples folder.

Start from a sample in Visual Studio Code

To start from a working framework template instead of your own code, use the sample gallery in the Microsoft Foundry Toolkit for Visual Studio Code:

1. In the Visual Studio Code Activity Bar, select the Foundry Toolkit icon.
2. Under Developer Tools > Agent Dev Tools, select Create Agent.
3. Under Create in code with full control, select Use a sample.
4. On Create Hosted Agent from Sample, use the filters to narrow the gallery:
   • For Framework, select Agent Framework, Bring Your Own, LangGraph, or Copilot SDK.
   • For Protocol Type, select Responses API or Invocations API.
5. Select a sample, and then select Next.
6. Enter an agent name, select your Foundry project, and then select Create.

The toolkit scaffolds the sample into a new workspace and sets up a one-click F5 debug experience. To install dependencies, test locally, and deploy from Visual Studio Code, follow the Visual Studio Code steps in Deploy your first hosted agent.

Choose your protocol

Each code step has a tab for every combination of language and protocol. Responses manages conversation history and is OpenAI-compatible. Invocations gives you full control over request and response schemas. Select the same language and protocol combination in every step.

Step 1: Add the hosting library

Add the protocol library to your project. The library handles the HTTP server, health checks, and protocol compliance, independent of the agent framework you use. If you use a framework, add its packages alongside the hosting library - see Choose your framework.

azure-ai-agentserver-responses>=1.0.0b7

azure-ai-agentserver-invocations>=1.0.0b5

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Responses --prerelease

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Invocations --prerelease

Step 2: Add the hosting wrapper

Create or update your agent entry point with the hosting wrapper. The following 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()

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;

ResponsesServer.Run<EchoHandler>();

public sealed class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request, createText: async ct =>
        {
            var userInput = await context.GetInputTextAsync(cancellationToken: ct) ?? "";

            // ─── YOUR AGENT LOGIC HERE ───
            var reply = $"Hello! You said: {userInput}";
            // ──────────────────────────────

            return reply;
        });
    }
}

using System.Text.Json;
using Azure.AI.AgentServer.Invocations;
using Microsoft.AspNetCore.Http;

InvocationsServer.Run<EchoHandler>();

public sealed class EchoHandler : InvocationHandler
{
    public override async Task HandleAsync(
        HttpRequest request,
        HttpResponse response,
        InvocationContext context,
        CancellationToken cancellationToken)
    {
        var raw = (await new StreamReader(request.Body).ReadToEndAsync(cancellationToken)).Trim();

        string userMessage;
        try
        {
            var body = JsonDocument.Parse(raw).RootElement;
            userMessage =
                (body.TryGetProperty("message", out var m) ? m.GetString() : null)
                ?? (body.TryGetProperty("input", out var input) ? input.GetString() : null)
                ?? raw;
        }
        catch (JsonException)
        {
            userMessage = raw;
        }

        // ─── YOUR AGENT LOGIC HERE ───
        var reply = $"Hello! You said: {userMessage}";
        // ──────────────────────────────

        await response.WriteAsJsonAsync(new { reply }, cancellationToken);
    }
}

Step 3: Initialize the project

Run azd ai agent init from your agent source directory. The Azure Developer CLI detects your language from the project files:

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

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

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!

For either Python protocol, add PYTHONNOUSERSITE: "1" to the existing agent service's env map in azure.yaml before testing or deployment. This setting disables user-site package loading before the interpreter starts. Install dependencies in the agent's virtual environment or image, not with pip install --user. See Configure Python startup.

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 (Python) or restores and builds the project (C#), 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
• Bring-your-own framework samples (GitHub Copilot SDK and more)
• C# hosted agent samples