Snabbstart: Distribuera din egen kod som värdbaserad agent

I Distribuera din första värdbaserade agent distribuerade du ett exempel. I den här snabbstarten distribuerar du din egen Python- eller .NET-agentkod (C#) till Foundry Agent Service. Din kod kan använda alla agentramverk – till exempel Microsoft Agent Framework, LangGraph, GitHub Copilot SDK eller OpenAI Agents SDK – eller vanlig kod som anropar en modell direkt.

Varje kodsteg har flikar för ditt språk och protokoll. Välj samma kombination, till exempel C# (svar), i varje steg.

Om du använder en kodningsagent som GitHub Copilot kan Microsoft Foundry Skill hjälpa dig att anpassa snabbstarten till din egen kodbas och köra rätt azd distributionssteg.

Förutsättningar

Innan du börjar behöver du:

• En Azure prenumeration – Skapa en kostnadsfri.

• Om du har ett befintligt Foundry-projekt behöver du Foundry Project Manager på projektnivå. Om du behöver skapa ett nytt Foundry-projekt måste du ha rollen Owner på resursgruppsnivå. Den fullständiga rollmatrisen finns i Referens för värdbaserade agentbehörigheter.

• Azure Developer CLI (azd) 1.27.1 eller senare.

• Tillägget azd microsoft.foundry :

  azd ext install microsoft.foundry
  

• En autentiserad azd session:

  azd auth login
  

• Din befintliga agentkod i en lokal katalog.

• För Python-sökvägen, Python 3.13 eller senare.

• För C#-sökvägen: .NET 10 SDK eller senare.

• (Valfritt) Om du vill börja från ett exempel i Visual Studio Code installerar du Visual Studio Code och Microsoft Foundry Toolkit för Visual Studio Code.

Din projektkatalog bör som minst innehålla följande för Python:

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

Eller, för C#, ett .NET webbprojekt:

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

Välj ditt ramverk

Värdbiblioteket som du lägger till i steg 1 hanterar protokollet – HTTP-servern, hälsokontroller och scheman för begäran och svar. Det beror inte på ett specifikt agentramverk, så din agentlogik kan använda de paket du föredrar i Python eller C#.

Om du vill använda ett ramverk lägger du till paketen bredvid värdbiblioteket och anropar sedan ramverket från hanteraren. I följande tabell visas vanliga alternativ och ett Python exempel för var och en.

Framework	Paket att lägga till i requirements.txt	Sample
Oformaterad Python (anropa en modell direkt)	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

Varje exempel requirements.txt visar de exakta paketversionerna. Fullständig uppsättning bring-your-own-exempel finns i mappen Python exempel.

För C#lägger du till ramverkspaket i projektfilen bredvid värdpaketet och anropar sedan ramverket från hanteraren i Program.cs. Den fullständiga uppsättningen C#-exempel finns i mappen C# bring-your-own samples.

Note

Microsoft Agent Framework har en inbyggd värdintegrering som använder sitt eget paket. Information om hur du distribuerar en Microsoft Agent Framework-agent finns i Distribuera din första värdbaserade agent.

Börja från ett exempel i Visual Studio Code

Om du vill börja från en mall för arbetsramverk i stället för din egen kod använder du exempelgalleriet i Microsoft Foundry Toolkit för Visual Studio Code:

1. I aktivitetsfältet Visual Studio Code väljer du ikonen Foundry Toolkit.
2. Under Utvecklarverktyg>Agent Dev Tools väljer du Skapa agent.
3. Under Skapa i kod med fullständig kontroll väljer du Använd ett exempel.
4. I Skapa värdbaserad agent från exempel använder du filtren för att begränsa galleriet:
   • För Framework väljer du Agent Framework, Bring Your Own, LangGraph eller Copilot SDK.
   • För Protokolltyp väljer du Api för svar eller API för anrop.
5. Välj ett exempel och välj sedan Nästa.
6. Ange ett agentnamn, välj ditt Foundry-projekt och välj sedan Skapa.

Verktyget skapar ett exempelprojekt i en ny arbetsyta och konfigurerar felsökning med ett klick med F5. Om du vill installera beroenden, testa lokalt och distribuera från Visual Studio Code följer du Visual Studio Code steg i Distribuera din första värdbaserade agent.

Välj ditt protokoll

Varje kodsteg har en flik för varje kombination av språk och protokoll. Svar hanterar konversationshistorik och är OpenAI-kompatibel. Med anrop får du fullständig kontroll över begärande- och svarsscheman. Välj samma språk och protokollkombination i varje steg.

Tip

Vet du inte vilket protokoll som ska användas? Börja med Svar.

Steg 1: Lägg till värdbiblioteket

Lägg till protokollbiblioteket i projektet. Biblioteket hanterar HTTP-servern, hälsokontroller och protokollefterlevnad, oberoende av agentramverket som du använder. Om du använder ett ramverk lägger du till dess paket tillsammans med värdbiblioteket – se Välj ditt ramverk.

Python (svar)

Lägg till protokollbiblioteket i din requirements.txt:

azure-ai-agentserver-responses>=1.0.0b7

Python (Anrop)

Lägg till protokollbiblioteket i ditt requirements.txt:

azure-ai-agentserver-invocations>=1.0.0b5

C# (svar)

Skapa ett .NET webbprojekt och lägg till protokollpaketet:

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

C# (anrop)

Skapa ett .NET webbprojekt och lägg till protokollpaketet:

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

Steg 2: Lägg till värdomslutningen

Skapa eller uppdatera agentens startpunkt med värdwrappen. I följande exempel visas det minimala mönstret. Ersätt det markerade blocket med din befintliga agentlogik.

Python (svar)

Skapa eller uppdatera main.py:

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

Python (Anrop)

Skapa eller uppdatera main.py:

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

C# (svar)

Ersätt Program.cs:

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;
        });
    }
}

C# (anrop)

Ersätt Program.cs:

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);
    }
}

Note

De här exemplen återger användarens indata för att demonstrera värdinkapslingen. Ersätt det markerade blocket med din egen agentlogik – modellanrop, RAG eller ett ramverk som LangGraph eller GitHub Copilot SDK. Fullständiga exempel finns i Python exempel och C#-exempel.

Steg 3: Initiera projektet

Kör azd ai agent init från agentens källkatalog. CLI:et Azure Developer identifierar ditt språk från projektfilerna:

Python (svar)

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

Python (Anrop)

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

C# (svar)

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

C# (anrop)

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

De interaktiva flödesprompterna för:

• Agentnamn: Anpassa namnet eller acceptera standardvärdet.
• Foundry Project: Välj Använd en befintlig Foundry-project eller Skapa en ny Foundry-project.
• Prenumeration: Välj din Azure-prenumeration.
• Plats: Välj en Azure region.

När det är klart ser du: AI-agentdefinitionen har lagts till i azd-projektet!

Steg 4: Etablera Azure resurser

azd provision

Detta skapar nödvändiga Azure resurser, till exempel Application Insights.

Steg 5: Testa agenten lokalt

azd ai agent run

Det här kommandot skapar en virtuell miljö (Python) eller återställer och skapar projektet (C#), installerar beroenden och startar din agent. Den öppnar även agentkontrollen i webbläsaren så att du kan chatta med agenten.

Du kan också anropa från CLI i en separat terminal:

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

Steg 6: Distribuera till Foundry Agent-tjänsten

azd deploy

När kommandot är klart visar utdata länkar till agentens lekplats och agentslutpunkten:

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

Steg 7: Anropa den distribuerade agenten

azd ai agent invoke "Hello from my hosted agent"

Du bör se ett svar inom några sekunder.

Rensa resurser

Varning

Om den nuvarande azd miljön skapade Foundry-projektet, azd down tar permanent bort projektets resursgrupp och allt som ingår i den. Om du valde ett befintligt projekt under initieringen azd down lämnar du projektet, dess resursgrupp, den värdbaserade agenten och andra snabbstartsresurser på plats. Ta bort alla resurser som du inte längre behöver från det befintliga projektet separat.

azd down

Troubleshooting

Issue	Lösning
ModuleNotFoundError: azure.ai.agentserver	Kontrollera att protokollbiblioteket finns i requirements.txt och installera om: pip install -r requirements.txt.
C#: The type or namespace name 'AgentServer' could not be found	Kontrollera att protokollpaketet refereras till (dotnet add package Azure.AI.AgentServer.Responses --prerelease eller Azure.AI.AgentServer.Invocations) och att projektet använder webb-SDK (dotnet new web).
C#: Cannot resolve scoped service ... Handler from root provider på dotnet run	Standardinställningen dotnet new web för startprofilen anger ASPNETCORE_ENVIRONMENT=Development, vilket möjliggör strikt omfångsvalidering. Använd azd ai agent run för att testa (den körs i värdbaserat läge) eller ställ in ASPNETCORE_ENVIRONMENT=Production före dotnet run.
FOUNDRY_PROJECT_ENDPOINT not set	Använd azd ai agent run (ställer in det automatiskt) i stället för att köra appen direkt. Eller lägg till den i filen .env .
Connection refused vid lokal körning	Se till att ingen annan process använder port 8088.
AuthorizationFailed under distributionen	Du behöver Foundry Project Manager på projektnivå.
Agenten har fastnat provisioning	Kör azd ai agent show för att kontrollera status. De första driftsättningarna kan ta 2–3 minuter medan beroenden installeras.
azd ai agent init Misslyckas	Kör azd version för att verifiera 1.27.1 eller senare. Kör azd ext show azure.ai.agents för att verifiera 1.0.0-beta.4 eller senare. Uppgradera med azd ext upgrade azure.ai.agents.

Fullständig behörighets- och rolltilldelningsmatris finns i Referens för värdbaserade agentbehörigheter.

Det här har du lärt dig

I den här snabbstarten kommer du att göra följande:

• Ett värdbibliotek har lagts till i din befintliga agentkod.
• Initierade ett azd projekt från källkatalogen.
• Testas lokalt med azd ai agent run och azd ai agent invoke --local.
• Distribuerad till Foundry Agent Service med azd deploy.

Nästa steg

Hantera värdbaserad agentlivscykel

• Skapa en verktygslåda och använd den med en värdbaserad agent för att kombinera verktyg bakom en hanterad slutpunkt.

Relaterat innehåll

• Vad är värdbaserade agenter?
• Distribuera en värdbaserad agent från källkoden
• Distribuera en värdbaserad agent från en container
• Livscykel för agentutveckling
• Python exempel på värdbaserade agenter
• Ta med dina egna ramverksexempel (LangGraph, GitHub Copilot SDK med mera)
• Exempel på C#-hostade agenter