Rychlý start: Nasazení vlastního kódu jako hostovaného agenta

V části Nasazení prvního hostovaného agenta jste nasadili ukázku. V tomto rychlém startu nasadíte vlastní kód agenta Python nebo .NET (C#) do služby Foundry Agent Service. Váš kód může používat libovolnou architekturu agenta, jako je Microsoft Agent Framework, LangGraph, sada GitHub Copilot SDK nebo sada OPENAI Agents SDK nebo prostý kód, který přímo volá model.

Každý krok kódu obsahuje karty pro váš jazyk a protokol. V každém kroku vyberte stejnou kombinaci, například C# (Odpovědi).

Pokud používáte programovacího agenta, jako je GitHub Copilot, pomůže vám Microsoft Foundry Skill přizpůsobit rychlý start vlastnímu základu kódu a spustit správné azd kroky nasazení.

Předpoklady

Než začnete, potřebujete:

• Předplatné Azure – Kreate si ho zdarma.

• Pokud máte stávající projekt Foundry, potřebujete Foundry Project Manager v rozsahu projektu. Pokud potřebujete vytvořit nový projekt Foundry, potřebujete roli Owner v oboru skupiny prostředků. Úplnou matici rolí najdete v referenčních informacích k oprávněním hostovaného agenta.

• Azure Developer CLI (azd) 1.27.1 nebo novější verze.

• Rozšíření azd microsoft.foundry :

  azd ext install microsoft.foundry
  

• Ověřená azd relace:

  azd auth login
  

• Váš stávající kód agenta v místním adresáři.

• Pro cestu Python Python 3.13 nebo novější.

• Pro variantu s jazykem C# je vyžadována sada SDK .NET 10 nebo novější.

• (Volitelné) Pokud chcete začít z ukázky v Visual Studio Code, nainstalujte Visual Studio Code a sadu Microsoft Foundry Toolkit for Visual Studio Code.

Projektový adresář by měl obsahovat alespoň následující položky pro Python:

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

Nebo pro C# webový projekt v .NET:

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

Vyberte svůj framework

Hostitelská knihovna, kterou přidáte v kroku 1 , zpracovává protokol – server HTTP, kontroly stavu a schémata požadavků a odpovědí. Nezávisí na konkrétní platformě agenta, takže logika agenta může v Python nebo C# používat libovolné balíčky, které dáváte přednost.

Chcete-li použít framework, přidejte jeho balíčky vedle hostovací knihovny a pak framework zavolejte z obslužné rutiny. Následující tabulka uvádí běžné volby a ukázku Python pro každou z nich.

.NET Framework	Balíčky, které se mají přidat do requirements.txt	Sample
Prostý Python (přímé volání modelu)	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

Jednotlivé ukázky requirements.txt uvádějí přesné verze balíčků. Úplnou sadu vlastních ukázek najdete ve složce Python samples.

V jazyce C# přidejte balíčky architektury do souboru projektu vedle hostitelského balíčku a pak volejte architekturu z obslužné rutiny v Program.cs. Úplnou sadu příkladů jazyka C# najdete ve složce s vlastními ukázkami jazyka C#.

Note

Microsoft Agent Framework má integrovanou integraci hostování, která používá vlastní balíček. Pokud chcete nasadit agenta Microsoft Agent Framework, přečtěte si téma Nasazení prvního hostovaného agenta.

Začněte od ukázky v Visual Studio Code

Pokud chcete začít od pracovní šablony architektury místo vlastního kódu, použijte ukázkovou galerii v Microsoft Foundry Toolkit pro Visual Studio Code:

1. Na panelu aktivit Visual Studio Code vyberte ikonu Foundry Toolkit.
2. V částiVývojářské nástroje Agent Dev Tools> vyberte Vytvořit agenta.
3. V části Vytvořit v kódu s úplnou kontrolou vyberte Použít ukázku.
4. Při vytváření hostovaného agenta z ukázky použijte filtry k zúžení galerie:
   • V případě rozhraní vyberte Agent Framework, Bring Your Own, LangGraph nebo Copilot SDK.
   • Jako typ protokolu vyberte rozhraní API odpovědí nebo rozhraní API pro vyvolání.
5. Vyberte ukázku a pak vyberte Další.
6. Zadejte název agenta, vyberte projekt Foundry a pak vyberte Vytvořit.

Sada nástrojů vygeneruje ukázku do nového pracovního prostoru a nastaví ladicí prostředí F5 jedním kliknutím. Pokud chcete nainstalovat závislosti, otestovat místně a nasadit z Visual Studio Code, postupujte podle Visual Studio Code kroků v části Nasazení prvního hostovaného agenta.

Zvolte svůj protokol.

Každý krok kódu má kartu pro každou kombinaci jazyka a protokolu. Odpovědi spravují historii konverzací a jsou kompatibilní s OpenAI. Volání poskytuje úplnou kontrolu nad schématy požadavků a odpovědí. V každém kroku vyberte stejný jazyk a kombinaci protokolu.

Tip

Nejste si jistí, jaký protokol použít? Začněte odpověďmi.

Krok 1: Přidání hostitelské knihovny

Přidejte do projektu knihovnu protokolů. Knihovna zajišťuje HTTP server, kontroly stavu a soulad s protokolem, a to nezávisle na použitém agentním frameworku. Pokud používáte architekturu, přidejte její balíčky spolu s knihovnou hostingu – viz Volba architektury.

Python (odpovědi)

Přidejte knihovnu protokolů do složky requirements.txt:

azure-ai-agentserver-responses>=1.0.0b7

Python (vyvolání)

Přidejte knihovnu protokolů do složky requirements.txt:

azure-ai-agentserver-invocations>=1.0.0b5

C# (odpovědi)

Vytvořte .NET webový projekt a přidejte balíček protokolu:

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

C# (vyvolání)

Vytvořte .NET webový projekt a přidejte balíček protokolu:

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

Krok 2: Přidání obálky pro hostování

Vytvořte nebo aktualizujte vstupní bod agenta pomocí hostovacího wrapperu. Následující příklady ukazují minimální vzor. Nahraďte označený blok stávající logikou agenta.

Python (odpovědi)

Vytvoření nebo aktualizace 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 (vyvolání)

Vytvoření nebo aktualizace 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# (odpovědi)

Nahradit 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# (vyvolání)

Nahradit 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

V těchto příkladech se ozve vstup uživatele, který demonstruje obálku hostování. Označený blok nahraďte vlastní logikou agenta – volání modelu, RAG nebo rozhraní, jako je LangGraph nebo GitHub Copilot SDK. Kompletní příklady najdete v Python ukázkách a ukázkách jazyka C#.

Krok 3: Inicializace projektu

Spusťte azd ai agent init v adresáři se zdrojovým kódem agenta. Rozhraní příkazového řádku pro vývojáře Azure rozpozná váš jazyk ze souborů projektu:

Python (odpovědi)

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

Python (vyvolání)

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

C# (odpovědi)

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

C# (vyvolání)

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

Interaktivní postup vyzve k zadání:

• Název agenta: Přizpůsobte název nebo přijměte výchozí hodnotu.
• Project Foundry: Vyberte Použít existující project Foundry nebo vytvořte nový project Foundry.
• Předplatné: Vyberte své předplatné Azure.
• Umístění: Vyberte Azure oblast.

Po dokončení uvidíte: Definice agenta AI byla úspěšně přidána do projektu azd!

Pro kterýkoli z protokolů Python přidejte PYTHONNOUSERSITE: "1" do stávající mapy služby agenta env v azure.yaml před testováním nebo nasazením. Toto nastavení zakáže načítání balíčků z uživatelského site adresáře před spuštěním interpretu. Nainstalujte závislosti ve virtuálním prostředí nebo imagi agenta, nikoli pomocí pip install --user. Viz Konfigurace spouštění Pythonu.

Krok 4: Zřízení prostředků Azure

azd provision

Tím se vytvoří požadované Azure prostředky, jako je Application Insights.

Krok 5: Místní testování agenta

azd ai agent run

Tento příkaz vytvoří virtuální prostředí (Python) nebo obnoví a sestaví projekt (C#), nainstaluje závislosti a spustí agenta. Otevře se také inspektor agenta v prohlížeči, abyste mohli chatovat s agentem.

Můžete také vyvolat z rozhraní příkazového řádku v samostatném terminálu:

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

Krok 6: Nasazení do služby agenta Foundry

azd deploy

Po dokončení příkazu se ve výstupu zobrazí odkazy na dětské hřiště agenta a koncový bod agenta:

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

Krok 7: Vyvolání nasazeného agenta

azd ai agent invoke "Hello from my hosted agent"

Během několika sekund by se měla zobrazit odpověď.

Vyčistěte zdroje

Warning

Pokud aktuální azd prostředí vytvořilo projekt Foundry, azd down trvale odstraní skupinu prostředků projektu a vše v ní. Pokud jste během inicializace vybrali existující projekt, azd down ponechá projekt, jeho skupinu prostředků, hostovaného agenta a další prostředky rychlého startu. Odstraňte všechny prostředky, které už nepotřebujete z existujícího projektu samostatně.

azd down

Řešení problémů

Issue	Solution
ModuleNotFoundError: azure.ai.agentserver	Ověřte, že je knihovna protokolů v requirements.txt a přeinstalujte: pip install -r requirements.txt.
C#: The type or namespace name 'AgentServer' could not be found	Ověřte, že se na balíček protokolu odkazuje (dotnet add package Azure.AI.AgentServer.Responses --prerelease nebo Azure.AI.AgentServer.Invocations) a že projekt používá webovou sadu SDK (dotnet new web).
C#: Cannot resolve scoped service ... Handler from root provider na dotnet run	Výchozí spouštěcí profil dotnet new web nastavuje ASPNETCORE_ENVIRONMENT=Development, což umožňuje přísné ověřování rozsahu. Použijte azd ai agent run k testování (běží v hostovaném režimu) nebo nastavte ASPNETCORE_ENVIRONMENT=Production před dotnet run.
FOUNDRY_PROJECT_ENDPOINT not set	Místo přímého spuštění aplikace použijte azd ai agent run (nastaví ji automaticky). Nebo ho přidejte do .env souboru.
Connection refused při lokálním spuštění	Ujistěte se, že žádný jiný proces nepoužívá port 8088.
AuthorizationFailed během nasazování	Potřebujete Foundry Project Manager na úrovni projektu.
Agent se zasekl provisioning	Spusťte azd ai agent show a zkontrolujte stav. První nasazení může trvat 2–3 minuty, než se nainstalují závislosti.
azd ai agent init Nezdaří	Spusťte azd version, chcete-li ověřit, že používáte verzi 1.27.1 nebo novější. Spusťte azd ext show azure.ai.agents, abyste ověřili verzi 1.0.0-beta.4 nebo novější. Aktualizujte pomocí azd ext upgrade azure.ai.agents.

Úplný přehled oprávnění a matice přiřazení role najdete v referenčních informacích k oprávněním hostovaného agenta.

Co jste se naučili

V tomto rychlém průvodci vám:

• Přidání jedné hostitelské knihovny do existujícího kódu agenta
• Inicializovali jste projekt ze zdrojového azd adresáře.
• Testováno místně s azd ai agent run a azd ai agent invoke --local.
• Nasazeno do služby Foundry Agent Service s azd deploy.

Další kroky

Správa životního cyklu hostovaných agentů

• Sestavte sadu nástrojů a použijte ji s hostovaným agentem ke kombinování nástrojů za jedním spravovaným koncovým bodem.

Související obsah

• Co jsou hostovaní agenti?
• Nasazení hostovaného agenta ze zdrojového kódu
• Nasazení hostovaného agenta z kontejneru
• Životní cyklus vývoje agentů
• Ukázky agentů hostovaných v Pythonu
• Ukázky vlastní architektury (LangGraph, GitHub Copilot SDK a další)
• Ukázky agentů hostovaných v C#