Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
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:
Een Azure-abonnement--Maak er gratis een.
Als u een bestaand Foundry-project hebt, hebt u
Foundry Project Managerop projectniveau nodig. Als u een nieuw Foundry-project wilt maken, hebt u de rolOwnerop resourcegroepniveau nodig. Zie voor de volledige rolmatrix de referentie voor machtigingen voor gehoste agents.De
microsoft.foundryextensie:azd ext install microsoft.foundryEen geverifieerde
azdsessie:azd auth loginUw bestaande agentcode in een lokale map.
Voor het Python pad Python 3.13 of hoger.
Voor het C#-pad is de .NET 10 SDK of later vereist.
(Optioneel) Als u wilt beginnen met een voorbeeld in Visual Studio Code, installeert u Visual Studio Code en de Microsoft Foundry Toolkit voor Visual Studio Code.
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:
- Selecteer in de Visual Studio Code Activiteitenbalk het pictogram Foundry Toolkit.
- Onder Hulpprogramma's voor ontwikkelaars>Ontwikkelhulpprogramma's voor agents selecteert u Agent maken.
- Selecteer onder Maken in code met volledige controleEen voorbeeld gebruiken.
- 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.
- Selecteer een voorbeeld en selecteer vervolgens Volgende.
- 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 runenazd ai agent invoke --local. - Geïmplementeerd in Foundry Agent Service met
azd deploy.
Volgende stappen
- Bouw een werkset en gebruik deze met een gehoste agent om hulpprogramma's achter één beheerd eindpunt te combineren.
Verwante inhoud
- Wat zijn gehoste agenten?
- Een gehoste agent implementeren vanuit broncode
- Een gehoste agent implementeren vanuit een container
- Levenscyclus van agentontwikkeling
- Door Python gehoste agentvoorbeelden
- Bring-Your-Own Framework-voorbeelden (LangGraph, GitHub Copilot SDK en meer)
- C# gehoste agentvoorbeelden