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

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.
(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:

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

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 Python packages you prefer. To use a framework, add its packages to requirements.txt next to the hosting library, then call the framework from the handler in main.py. The following table lists common choices and a sample for each.

Framework	Packages to add to `requirements.txt`	Sample
Plain Python (call a model directly)	`azure-ai-projects`	hello-world
LangGraph	`langgraph`, `langchain-azure-ai`	langgraph-chat
GitHub Copilot SDK	`github-copilot-sdk`	github-copilot
OpenAI Agents SDK	`openai-agents`	openai-agents-sdk

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

Microsoft Agent Framework has a built-in hosting integration that uses its own package. To deploy a Microsoft Agent Framework agent, see Deploy your first hosted agent.

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:

In the Visual Studio Code Activity Bar, select the Foundry Toolkit icon.
Under Developer Tools > Agent Dev Tools, select Create Agent.
Under Create in code with full control, select Use a sample.
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.
Select a sample, and then select Next.
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

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.

Not sure which protocol to use? Start with Responses.

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, independent of the agent framework you use. If you use a framework, add its packages to the same file - see Choose your framework.

    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()

These examples echo user input to demonstrate the hosting wrapper. Replace the marked block with your own agent logic - model calls, RAG, or a framework like LangGraph or the GitHub Copilot SDK. For complete examples, see the Python samples and C# samples.

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 permanently deletes every resource in the resource group, including the Foundry project and hosted agent. If the resource group contains other resources, those are also deleted.

azd down

Troubleshooting

Issue	Solution
`ModuleNotFoundError: azure.ai.agentserver`	Verify the protocol library is in `requirements.txt` and reinstall: `pip install -r requirements.txt`.
`FOUNDRY_PROJECT_ENDPOINT not set`	Use `azd ai agent run` (sets it automatically) instead of `python main.py`. Or add it to your `.env` file.
`Connection refused` on local run	Ensure no other process is using port 8088.
`AuthorizationFailed` during deploy	You need `Foundry Project Manager` at project scope.
Agent stuck in `provisioning`	Run `azd ai agent show` to check status. First deploys can take 2–3 minutes while dependencies install.
`azd ai agent init` fails	Run `azd version` to verify 1.25.3 or later. Update the extension: `azd ext upgrade microsoft.foundry`.

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

Manage hosted agent lifecycle

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

Get started

Developer tools and integrations

Models

Agents

Tools and knowledge

Observability

Evaluation

Quickstart: Deploy your own code as a hosted agent

Prerequisites

Choose your framework

Start from a sample in Visual Studio Code

Choose your protocol

Step 1: Add the hosting library

Step 2: Add the hosting wrapper

Step 3: Initialize the project

Step 4: Provision Azure resources

Step 5: Test the agent locally

Step 6: Deploy to Foundry Agent Service

Step 7: Invoke the deployed agent

Clean up resources

Troubleshooting

What you learned

Next steps

Manage hosted agent lifecycle

​Prerequisites

​Choose your framework

​Start from a sample in Visual Studio Code

​Choose your protocol

​Step 1: Add the hosting library

​Step 2: Add the hosting wrapper

​Step 3: Initialize the project

​Step 4: Provision Azure resources

​Step 5: Test the agent locally

​Step 6: Deploy to Foundry Agent Service

​Step 7: Invoke the deployed agent

​Clean up resources

​Troubleshooting

​What you learned

​Next steps

Manage hosted agent lifecycle

​Related content

Prerequisites

Choose your framework

Start from a sample in Visual Studio Code

Choose your protocol

Step 1: Add the hosting library

Step 2: Add the hosting wrapper

Step 3: Initialize the project

Step 4: Provision Azure resources

Step 5: Test the agent locally

Step 6: Deploy to Foundry Agent Service

Step 7: Invoke the deployed agent

Clean up resources

Troubleshooting

What you learned

Next steps

Related content