Quickstart: Uw eigen code implementeren als een gehoste agent

In Deploy your first hosted agent hebt u een voorbeeld geïmplementeerd. In deze quickstart implementeert u uw eigen Python of .NET -agentcode (C#) in Foundry Agent Service. Uw code kan elk agentframework gebruiken, zoals Microsoft Agent Framework, LangGraph, de GitHub Copilot SDK of de OpenAI Agents SDK, of code zonder opmaak die rechtstreeks een model aanroept.

Elke codestap bevat tabbladen voor uw taal en protocol. Selecteer in elke stap dezelfde combinatie, zoals C# (antwoorden).

Als u een coderingsagent zoals GitHub Copilot gebruikt, kan de Microsoft Foundry Skill u helpen de quickstart aan uw eigen codebasis aan te passen en de juiste azd implementatiestappen uit te voeren.

Prerequisites

Voordat u begint, hebt u het volgende nodig:

Uw projectmap moet voor Python minimaal het volgende bevatten:

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

Of, voor C#, een .NET-webproject:

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

Uw framework kiezen

De hostingbibliotheek die u in stap 1 toevoegt, verwerkt het protocol: de HTTP-server, statuscontroles en aanvraag- en antwoordschema's. Het is niet afhankelijk van een specifiek agentframework, zodat uw agentlogica alle pakketten kan gebruiken die u liever gebruikt, in Python of C#.

Als u een framework wilt gebruiken, voegt u de pakketten toe naast de hostingbibliotheek en roept u het framework aan vanuit de handler. De volgende tabel bevat algemene keuzes en een Python voorbeeld voor elk.

Framework Pakketten die moeten worden toegevoegd aan requirements.txt Sample
Gewone Python (een model rechtstreeks aanroepen) 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

In elk voorbeeld requirements.txt worden de exacte pakketversies vermeld. Zie de map met Python-voorbeelden voor de volledige verzameling voorbeelden die u zelf kunt meebrengen.

Voor C# voegt u frameworkpakketten toe aan uw projectbestand naast het hostingpakket en roept u vervolgens het framework aan van de handler in Program.cs. Zie de voorbeeldenmap voor eigen C#-voorbeelden voor de volledige set C#-voorbeelden.

Note

Microsoft Agent Framework heeft een ingebouwde hostingintegratie die gebruikmaakt van een eigen pakket. Zie Uw eerste gehoste agent implementeren om een Microsoft Agent Framework-agent te implementeren.

Beginnen met een voorbeeld in Visual Studio Code

Als u wilt beginnen met een werkende frameworksjabloon in plaats van uw eigen code, gebruikt u de voorbeeldgalerie in de Microsoft Foundry Toolkit voor Visual Studio Code:

  1. Selecteer in de Visual Studio Code Activiteitenbalk het pictogram Foundry Toolkit.
  2. Onder Hulpprogramma's voor ontwikkelaars>Ontwikkelhulpprogramma's voor agents selecteert u Agent maken.
  3. Selecteer onder Maken in code met volledige controleEen voorbeeld gebruiken.
  4. Gebruik bij Hosted agent maken op basis van voorbeeld de filters om de galerij te verfijnen:
    • Voor Framework selecteert u Agent Framework, Bring Your Own, LangGraph of Copilot SDK.
    • Selecteer voor Protocoltype de API voor antwoorden of aanroepen-API.
  5. Selecteer een voorbeeld en selecteer vervolgens Volgende.
  6. Voer een agentnaam in, selecteer uw Foundry-project en selecteer vervolgens Maken.

De toolkit zet het voorbeeld op in een nieuwe werkruimte en biedt een debugervaring met één klik via F5. Als u afhankelijkheden wilt installeren, lokaal wilt testen en wilt implementeren vanuit Visual Studio Code, volgt u de Visual Studio Code stappen in Uw eerste gehoste agent implementeren.

Kies uw protocol

Elke codestap heeft een tabblad voor elke combinatie van taal en protocol. Antwoorden beheren de gespreksgeschiedenis en zijn compatibel met OpenAI. Met aanroepen hebt u volledige controle over aanvraag- en antwoordschema's. Selecteer in elke stap dezelfde combinatie van taal en protocol.

Tip

Weet u niet zeker welk protocol moet worden gebruikt? Begin met antwoorden.

Stap 1: De hostingbibliotheek toevoegen

Voeg de protocolbibliotheek toe aan uw project. De bibliotheek verwerkt de HTTP-server, statuscontroles en protocolnaleving, onafhankelijk van het agentframework dat u gebruikt. Als u een framework gebruikt, voegt u de pakketten toe naast de hostingbibliotheek. Zie Kies uw framework.

Voeg de protocolbibliotheek toe aan uw requirements.txt:

azure-ai-agentserver-responses>=1.0.0b7

Stap 2: de hosting-wrapper toevoegen

Maak of werk uw agentinvoerpunt bij met de hosting-wrapper. In de volgende voorbeelden ziet u het minimale patroon. Vervang het gemarkeerde blok door de bestaande agentlogica.

Maken of bijwerken 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()

Note

Deze voorbeelden weerspiegelen de invoer van de gebruiker om de wrapper voor hosting te demonstreren. Vervang het gemarkeerde blok door uw eigen agentlogica: modeloproepen, RAG of een framework zoals LangGraph of de GitHub Copilot SDK. Zie de Python voorbeelden en C#-voorbeelden voor volledige voorbeelden.

Stap 3: Het project initialiseren

Voer azd ai agent init uit in de bronmap van uw agent. De Azure Developer CLI detecteert uw taal uit de projectbestanden:

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

De interactieve stroom vraagt om:

  • Agentnaam: Pas de naam aan of accepteer de standaardwaarde.
  • Foundry Project: selecteer Een bestaande Foundry-project gebruiken of Een nieuwe Foundry-project maken.
  • Abonnement: selecteer uw Azure-abonnement.
  • Locatie: Selecteer een Azure regio.

Als u klaar bent, ziet u: ai-agentdefinitie toegevoegd aan uw azd-project.

Voor elk van beide Python-protocollen voegt u PYTHONNOUSERSITE: "1" toe aan de bestaande agentservicemap van env in azure.yaml voordat u gaat testen of implementeren. Met deze instelling wordt laden van gebruikerssitepakketten uitgeschakeld voordat de interpreter wordt gestart. Installeer afhankelijkheden in de virtuele omgeving of image van de agent, niet met pip install --user. Zie Python opstarten configureren.

Stap 4: Azure resources inrichten

azd provision

Hiermee maakt u de vereiste Azure resources, zoals Application Insights.

Stap 5: de agent lokaal testen

azd ai agent run

Met deze opdracht maakt u een virtuele omgeving (Python) of herstelt en bouwt u het project (C#), installeert u afhankelijkheden en start u de agent. Het opent ook de agentinspector in uw browser, zodat u met de agent kunt chatten.

U kunt ook vanuit de CLI aanroepen in een afzonderlijke terminal:

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

Stap 6: Implementeren in Foundry Agent Service

azd deploy

Wanneer de opdracht is voltooid, ziet u in de uitvoer koppelingen naar de agentspeelplaats en het agenteindpunt:

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

Stap 7: Geïmplementeerde agent aanroepen

azd ai agent invoke "Hello from my hosted agent"

U ziet binnen een paar seconden een antwoord.

De hulpbronnen opschonen

Warning

Als de huidige azd-omgeving het Foundry-project heeft gemaakt, wordt met azd down de resourcegroep van het Foundry-project en alles daarin permanent verwijderd. Als u tijdens de initialisatie een bestaand project hebt geselecteerd, azd down blijft het project, de bijbehorende resourcegroep, de gehoste agent en andere quickstart-resources aanwezig. Verwijder alle resources die u niet meer nodig hebt uit het bestaande project afzonderlijk.

azd down

Probleemoplossingsproces

Issue Solution
ModuleNotFoundError: azure.ai.agentserver Controleer of de protocolbibliotheek is ingeschakeld requirements.txt en installeer deze opnieuw: pip install -r requirements.txt.
C#: The type or namespace name 'AgentServer' could not be found Controleer of er naar het protocolpakket wordt verwezen (dotnet add package Azure.AI.AgentServer.Responses --prerelease of Azure.AI.AgentServer.Invocations) en of het project gebruikmaakt van de web-SDK (dotnet new web).
C#: Cannot resolve scoped service ... Handler from root provider op dotnet run Het standaard-dotnet new webopstartprofiel stelt ASPNETCORE_ENVIRONMENT=Development in, waarmee strikte scopevalidatie wordt ingeschakeld. Gebruik azd ai agent run om te testen (dat in de gehoste modus wordt uitgevoerd), of stel dotnet run in voordat ASPNETCORE_ENVIRONMENT=Production.
FOUNDRY_PROJECT_ENDPOINT not set Gebruik azd ai agent run (stelt deze automatisch in) in plaats van de app rechtstreeks uit te voeren. Of voeg het toe aan uw .env bestand.
Connection refused bij lokale uitvoering Zorg ervoor dat er geen ander proces gebruikmaakt van poort 8088.
AuthorizationFailed tijdens het uitrollen U hebt Foundry Project Manager op projectniveau nodig.
Agent zit vast in provisioning Voer uit azd ai agent show om de status te controleren. De eerste implementatie kan 2-3 minuten duren tijdens de installatie van afhankelijkheden.
azd ai agent init Mislukt Voer azd version uit om 1.36.0 of hoger te verifiëren. Controleer en upgrade de huidige Foundry-extensies.

Zie voor de volledige machtigings- en roltoewijzingsmatrix de referentie voor gehoste agentmachtigingen.

Wat u hebt geleerd

In deze quickstart gaat u als volgt te werk:

  • Er is één hostingbibliotheek toegevoegd aan uw bestaande agentcode.
  • Een azd-project geïnitialiseerd vanuit uw bronmap.
  • Lokaal getest met azd ai agent run en azd ai agent invoke --local.
  • Geïmplementeerd in Foundry Agent Service met azd deploy.

Volgende stappen