Wat zijn gehoste agents?

Wanneer u agentische toepassingen bouwt met behulp van opensource-frameworks, beheert u doorgaans veel geavanceerde problemen: containerisatie, webserverinstallatie, beveiliging, geheugenpersistentie, schalen, instrumentatie en terugdraaiacties van versies. Deze taken worden nog lastiger in heterogene cloudomgevingen.

Gehoste agents in Foundry Agent Service lossen deze uitdagingen op voor Microsoft Foundry-gebruikers. Gehoste agents roepen modellen aan uit de Foundry-modelcatalogus om redenering uit te voeren terwijl uw aangepaste code indeling verwerkt. Met dit beheerde platform kunt u AI-agents veilig en op schaal implementeren en gebruiken. U kunt uw aangepaste agentcode of een voorkeursagentframework gebruiken met gestroomlijnde implementatie en beheer.

Wanneer moet u gehoste agents gebruiken

Kies gehoste agents in plaats van promptgebaseerde agents als u het volgende moet doen:

  • Bring your own code - gebruik elk framework (Agent Framework, LangGraph, Semantic Kernel of aangepaste code) in plaats van alleen prompt-definities.
  • Gebruik aangepaste protocollen - accepteer webhooks of niet-OpenAI-payloads via het Invocations-protocol.
  • Rekenresources beheren: geef CPU en geheugen op voor de sandbox van uw agent.
  • Stateful workloads uitvoeren : bestanden en status behouden via $HOME en het eindpunt /files.

Hoe het werkt

Je verpakt je agent als een container-image en uploadt deze naar Azure Container Registry. Wanneer u implementeert, haalt Agent Service de installatiekopie op, stelt de rekencapaciteit in, wijst een toegewezen Microsoft Entra ID (agentidentiteit) toe, en stelt een toegewezen eindpunt beschikbaar. Tijdens runtime verwerkt uw agentcode aanvragen van clients en kunnen Foundry-modellen, Werksethulpprogramma's en downstream-Azure-services aanroepen met behulp van de agentidentiteit. Het platform verwerkt schalen, sessiestatuspersistentie, waarneembaarheid en levenscyclusbeheer.

Belangrijk

Wanneer u Hosted Agents gebruikt met andere Microsoft producten en services, moet u alle relevante documentatie voor dergelijke producten en services lezen en gerelateerde risico's en nalevingsoverwegingen begrijpen.

Als u Hosted Agent gebruikt met servers van derden, agents, code of niet-Azure Directe modellen ("Systemen van derden"), doet u dit op eigen risico. Systemen van derden zijn niet-Microsoft Producten onder de Microsoft Productvoorwaarden en vallen onder hun eigen licentievoorwaarden van derden. U bent verantwoordelijk voor alle gebruiks- en bijbehorende kosten.

We raden u aan alle gegevens te bekijken die worden gedeeld met en ontvangen van systemen van derden en om kennis te nemen van procedures van derden voor het verwerken, delen, bewaren en locatie van gegevens. Evenzo is het belangrijk om, als u verbinding maakt met of integreert met Microsoft-services en -functies buiten Foundry, te bekijken hoe zij met gegevens omgaan. Het is uw verantwoordelijkheid om te beheren of uw gegevens buiten de nalevings- en geografische grenzen van uw organisatie en eventuele gerelateerde implicaties stromen, en dat de juiste machtigingen, grenzen en goedkeuringen worden ingericht.

U bent verantwoordelijk voor het zorgvuldig beoordelen en testen van toepassingen die u bouwt in de context van uw specifieke use cases en het nemen van alle juiste beslissingen en aanpassingen. Dit omvat het implementeren van uw eigen verantwoorde AI-oplossingen, zoals metaprompts, inhoudsfilters of andere veiligheidssystemen, en ervoor zorgen dat uw toepassingen voldoen aan de juiste kwaliteit, betrouwbaarheid, beveiliging en betrouwbaarheidsstandaarden. Zie de transparantienotitie van de Foundry Agent Service.

Sleutelbegrippen

Gehoste agents

Gehoste agents zijn in containers geplaatste AI-toepassingen die worden uitgevoerd op agentservice. In tegenstelling tot promptgestuurde agents — die volledig worden gedefinieerd via prompts en toolconfiguratie in de Foundry-portal — zijn Hosted agents eigen code die is verpakt als een containerimage. U kiest het framework, beheert het runtimegedrag en implementeert de image in door Microsoft beheerde infrastructuur.

Het platform beheert automatisch de levenscyclus van de container op basis van activiteit, door resources in te richten wanneer u een versie maakt en deze vrij te geven wanneer de inactiviteitstime-out is bereikt.

Isolatiemodel

Gehoste agents worden per sessie uitgevoerd in VM-geïsoleerde sandboxes. Elke sessie krijgt een toegewezen sandbox met een permanent bestandssysteem ($HOME en /files), waardoor scale-to-zero wordt ingeschakeld, met stateful hervatten en voorspelbare koude starts. Sessies worden van elkaar geïsoleerd en de status wordt automatisch hersteld wanneer een sessie wordt hervat na inactiviteit.

Protocollen: Antwoorden, Aanroepen en Aanroepen (WebSocket)

Gehoste agentcontainers kunnen een of meer protocollen beschikbaar maken. Elk protocol wordt geleverd door een lichtgewicht bibliotheek die de HTTP- of WebSocket-server, statuscontroles en OpenTelemetry-integratie verwerkt. De protocollen Responses, Invocations en Invocations (WebSocket) zijn beschikbaar in alle regio's die Hosted agents ondersteunen.

Welk protocol moet ik gebruiken?

Scenario Protocol Waarom
Conversatiechatbot of assistent Reacties Het platform beheert de gespreksgeschiedenis, streaminggebeurtenissen en sessielevenscyclus. Gebruik elke OpenAI-compatibele SDK als de client.
Q&A met meerdere rondes met RAG of tools Reacties Ingebouwde threading van gespreks-ID's en verwerking van hulpprogrammaresultaten.
Achtergrond/asynchrone verwerking Reacties achtergrond: true met platformbeheerde polling en annulering, zonder dat aangepaste code nodig is.
Agent gepubliceerd naar Teams of Microsoft 365 Reacties + Activiteit Het antwoordprotocol maakt de agentlogica mogelijk; het platform overbrugt automatisch reacties op het activiteitsprotocol voor kanaallevering.
Webhookontvanger (GitHub, Stripe, Jira, enzovoort) Aanroepen Het externe systeem verzendt een eigen payload-indeling. U kunt deze niet wijzigen zodat deze overeenkomt met /responsen.
Niet-gespreksverwerking (classificatie, extractie, batch) Aanroepen De invoer is gestructureerde gegevens, geen chatbericht. Willekeurige JSON in, willekeurige JSON out.
Aangepast streamingprotocol (AG-UI, enzovoort) Aanroepen AG-UI en andere protocollen voor agent-UI zijn niet openAI-compatibel. U hebt onbewerkte SSE-besturingselementen nodig.
Protocolbrug (GitHub Copilot, eigen systemen) Aanroepen De aanroeper heeft een eigen protocol dat niet wordt toegewezen aan /responses.
Real-time spraakagent (microfoon in, spraak uit) Aanroepen (WebSocket) Bidirectioneel streamen via één permanente verbinding. Koppel deze met Pipecat, LiveKit of Voice Live in uw container. Zie Een spraakagent bouwen.

Tip

Ik weet het niet? Begin met antwoorden. U kunt later altijd een eindpunt voor aanroepen toevoegen. Een gehoste agent kan beide protocollen tegelijkertijd ondersteunen.

Protocolvergelijking

Reacties Aanroepen
Het beste voor De meeste agents, het platform beheert de gespreksgeschiedenis, de levenscyclus van streaming en de uitvoering op de achtergrond. Agents die volledige HTTP-controle, aangepaste payloads of langlopende asynchrone workflows nodig hebben
Payload OpenAI-compatibele responsenovereenkomst Willekeurige JSON via /invocations: u definieert het schema
Client-SDK Elke OpenAI-compatibele SDK (Python, JS, C#) werkt standaard Aangepaste client: u definieert het contract
Sessiegeschiedenis Platformbeheer via gespreks-id U beheert sessies (in-memory, Cosmos DB, enzovoort)
Streaming Platformbeheerde ResponseEventStream met levenscyclusgebeurtenissen Onbewerkte SSE: u kunt gebeurtenissen rechtstreeks opmaken en schrijven
Achtergrond/langlopend Ingebouwd (achtergrond: waar + platform-gecontroleerde polling) Handmatig bijhouden van taken en aangepaste polling-eindpunten

Aanvullende protocollen

Gehoste agents ondersteunen ook het protocol Activiteit voor Teams en Microsoft 365-kanaalintegratie. Wanneer u het Responses-protocol gebruikt voor agentlogica en publiceert naar Microsoft 365-kanalen, zoals Teams, wordt het platform automatisch naar het Activiteiten-protocol gekoppeld voor kanaallevering. Er is geen afzonderlijke koppeling vereist. Het A2A-protocol ondersteunt delegatie van agent-naar-agent. Ondersteunde protocollen kunnen worden gecombineerd in één agent.

Agentidentiteit en eindpunt

Elke gehoste agent die is geïmplementeerd in een Foundry-project krijgt een eigen dedicated Microsoft Entra ID (agentidentiteit) en toegesneden eindpunt, beide automatisch gemaakt tijdens de implementatie. U hoeft beheerde identiteiten of routering niet handmatig te configureren.

Het eindpunt is direct na de implementatie beschikbaar. Publicatie is niet vereist voor programmatische toegang:

  • Antwoorden: {project_endpoint}/agents/{name}/endpoint/protocols/openai/responses
  • Aanroepen: {project_endpoint}/agents/{name}/endpoint/protocols/invocations
  • Aanroepen (WebSocket): wss://{account}.services.ai.azure.com/api/projects/{project}/agents/{name}/endpoint/protocols/invocations_ws?api-version=v1
  • A2A (preview): {project_endpoint}/agents/{name}/endpoint/protocols/a2a

Welke eindpunten actief zijn, is afhankelijk van de protocollen die zijn gedeclareerd in de definitie van de agentversie. Stel deze definitie in de azure.ai.agent service in azure.yaml in wanneer u azd gebruikt, of via protocol_versions wanneer u de SDK gebruikt.

Er zijn twee identiteiten betrokken:

Identiteit Scope Purpose
Microsoft Entra ID (agentidentiteit, per agent) Automatisch gemaakt tijdens de implementatie De identiteit waarmee de agentcontainer wordt geauthenticeerd bij runtime. Wordt gebruikt voor modeloproep, toegang tot hulpprogramma's en downstream-Azure-services.
Project beheerde identiteit (project breed) Door het systeem toegewezen aan het Foundry-project Wordt gebruikt door het platform voor infrastructuurbewerkingen (bijvoorbeeld Container Registry Repository Reader in het containerregister). Niet de runtime-identiteit van de agent.

De agentidentiteit heeft standaard toegang tot modeldeductie via het projecteindpunt en de sessieopslag. Wijs voor externe resources (bijvoorbeeld uw eigen Azure Storage) RBAC-rollen handmatig toe aan de Microsoft Entra ID van de agent. Zie Agent-toegang buiten de standaardinstellingen voor meer informatie.

Wanneer gehoste agents worden geïntegreerd via Microsoft 365 kanalen (bijvoorbeeld Teams), kunnen gehoste agents werken in twee identiteitsmodi, afhankelijk van hoe ze worden aangeroepen:

  • Door de gebruiker aangeroepen scenario's (interactief): als er een gebruikerstoken aanwezig is, ondersteunt het platform OAuth 2.0 On-Behalf-Of (OBO) stromen. In dit geval kan de agent downstreamservices aanroepen namens de gebruiker met behulp van de gedelegeerde machtigingen van de gebruiker, afhankelijk van Microsoft Entra ID tenantbeleid.

  • Autonome of achtergrondscenario's: Als er geen gebruikerstoken beschikbaar is, authenticeert de agent zich met zijn eigen Microsoft Entra ID (agentidentiteit), meestal via een beheerde identiteit, om toegang te krijgen tot downstreamservices.

In beide gevallen behoudt de agent de toegewezen Microsoft Entra ID voor verificatie, autorisatie en controle. Zie Agent-toepassingen en agentidentiteitsconcepten voor meer informatie.

Sessies en gesprekken

Gehoste agents gebruiken sessies en gesprekken om de status te beheren. Hoe ze werken, is afhankelijk van het protocol.

Sessies

Een sessie-id identificeert een logische sessie met persistente status, inclusief $HOME en bestanden die zijn geüpload via het eindpunt /files. Het platform voorziet in computercapaciteit op aanvraag en herstelt de opgeslagen status daarop.

  • Statuspersistentie: $HOME- en /files-inhoud blijven behouden over omdraaiingen en over niet-actieve perioden. Wanneer de berekening niet actief wordt en terug wordt gebracht (op een nieuwe of bestaande infrastructuur), wordt de status van de sessie automatisch hersteld.
  • Isolatie: elke sessie is geïsoleerd van andere sessies.
  • Automatische levenscyclus: sessies worden gemaakt bij eerste gebruik. De inrichting van het platform wordt automatisch uitgevoerd en de inrichting ongedaan gemaakt.
  • Sessieduur: de time-out voor inactiviteit is 15 minuten—als er binnen die periode geen verzoek binnenkomt, stelt het platform de rekencapaciteit buiten gebruik en slaat het de sessiestatus op. Een sessie wordt na 30 dagen inactiviteit definitief verwijderd.
  • Api's voor sessiebeheer: sessies weergeven, sessies beëindigen en bestanden per sessie uploaden of downloaden.

Gesprekken

Een gespreks-id is een duurzaam overzicht van gespreksgeschiedenis (berichten, hulpprogramma-oproepen en antwoorden) die zijn opgeslagen in Foundry.

  • Persistentie: gespreksgeschiedenis wordt opgeslagen in Foundry en blijft onafhankelijk van de rekenstatus behouden.
  • Toegang via meerdere kanalen: gebruikers hebben toegang tot hetzelfde gesprek vanuit de speeltuin, API, Teams of andere gepubliceerde kanalen.

Hoe sessies en gesprekken werken met elk protocol

Protocol voor antwoorden: gespreks-id is het primaire concept. Het platform beheert de gespreksgeschiedenis automatisch en koppelt een sessie-id aan elk gesprek. Het platform retourneert de sessie-id naar de client, die deze kan gebruiken om bestanden te uploaden via het /files-eindpunt, waardoor deze bestanden beschikbaar zijn voor de berekening van het gesprek.

Protocol voor aanroepen: sessie-id is het primaire concept. De client beheert de sessie-id rechtstreeks om de status tussen interacties te behouden. De client kan inhoud uploaden via het eindpunt /files met behulp van de sessie-id om deze beschikbaar te maken voor de sessie. Er is geen platformbeheerde gespreksgeschiedenis: u beheert de status in uw eigen code.

Levenscyclus van sessie berekenen

Staat Wat gebeurt er?
Actieve De computer draait. Aanvragen worden naar het systeem doorgestuurd. De inhoud van $HOME en /files is beschikbaar.
Idle Geen aanvragen gedurende 15 minuten. Compute is ongedaan gemaakt. Sessiestatus ($HOME, /files) blijft behouden.
Hervat Er wordt opnieuw naar dezelfde sessie-id verwezen. Het platform voorziet in nieuwe rekencapaciteit en herstelt de opgeslagen toestanden.

Beveiliging en gegevensverwerking

Behandel een gehoste agent als productiecode van een toepassing.

Belangrijk

Gebruik systemen van derden op eigen risico en implementeer altijd passende beheersmaatregelen voor verantwoorde AI. U bent verantwoordelijk voor het beheren van alle gegevens die buiten de nalevings- en geografische grenzen van uw organisatie kunnen stromen. Meer informatie.

  • Plaats geen geheimen in containerinstallatiekopieën of omgevingsvariabelen. Gebruik beheerde identiteiten en verbindingen en sla geheimen op in een beheerd geheim archief. Zie Een Key Vault-verbinding instellen voor hulp.
  • Wees voorzichtig met niet-Microsoft hulpprogramma's en servers. Als uw agent hulpprogramma's aanroept die worden ondersteund door niet-Microsoft-services, kunnen sommige gegevens naar die services stromen. Controleer het beleid voor het delen, bewaren en locatie van gegevens voor alle niet-Microsoft service waarmee u verbinding maakt.

Platformdetails

Versiebeheer

Elke aanroep voor het maken van een versie produceert een onveranderbare agentversie. De versie is een momentopname van de containerimage, resourcetoewijzing, omgevingsvariabelen en protocolconfiguratie. Als u uw agent wilt bijwerken, maakt en implementeert u een nieuwe versie.

Een agenteindpunt dient één versie tegelijk en stuurt 100% van het verkeer naar die versie. Verkeer splitsen tussen versies wordt niet ondersteund.

Omgevingsvariabelen zijn het primaire mechanisme voor het doorgeven van configuratie aan uw container tijdens runtime (bijvoorbeeld het projecteindpunt, de naam van de modelimplementatie en aangepaste instellingen). Ze worden ingesteld per versie en kunnen onveranderbaar zijn zodra de versie is gemaakt.

Observeerbaarheid

Gehoste agents bieden ingebouwde waarneembaarheid. Het platform injecteert automatisch een Application Insights-verbindingsreeks in uw agentcontainer via omgevingsvariabelen. Agents die gebruikmaken van de protocolbibliotheken verzenden standaard OpenTelemetry-traceringen, die worden weergegeven in de gekoppelde Application Insights-resource onderTransaction Search of >onderzoeken.

Zie Tracering inschakelen in uw project voor hulp bij configuratie en analyse.

Werkset in Foundry

Belangrijk

Het rechtstreeks toevoegen van hulpprogramma's aan de definitie van een gehoste agent wordt niet ondersteund. We raden u aan toolboxen te gebruiken in Foundry.

Gehoste agents hebben toegang tot met Foundry beheerde hulpprogramma's (Code Interpreter, Web Search, Azure AI Zoeken, OpenAPI, aangepaste MCP-verbindingen, A2A) via een Toolbox MCP-eindpunt ingericht in uw Foundry-project. Uw agentcode maakt verbinding met dit eindpunt met behulp van standaard MCP-clientbibliotheken. Het platform injecteert geen hulpprogramma's automatisch. Voor details, zie de op intentie gebaseerde gereedschapskist in Foundry cureren. Gebruik de werkset in Foundry om hulpprogramma's in een gehoste agent te verbinden met geconsolideerde verificatieondersteuning voor OAuth Identity Passthrough, agentidentiteit, sleutel en meer.

Taalondersteuning

Gehoste agents ondersteunen Python en C#. U kunt elk agentframework gebruiken. De protocolbibliotheken zijn frameworkneutraal. Zie de opslagplaats foundry-samples-opslagplaats voor voorbeelden die gebruikmaken van Microsoft Agent Framework, LangGraph en aangepaste code.

Sandbox-grootten

Gehoste agent sandboxes ondersteunen de volgende CPU- en geheugencombinaties:

CPU Memory
0,5 vCPU 1 GiB
1 vCPU 2 GiB
2 vCPU 4 GiB

Sessieopslag

Elke sessie heeft een permanente $HOME. De inhoud ervan blijft behouden wanneer de rekenomgeving na 15 minuten inactiviteit wordt vrijgegeven, en wordt hersteld wanneer de sessie wordt hervat, zodat bestanden die onder $HOME zijn weggeschreven inactieve perioden overleven. Bestanden die via het /files-eindpunt worden geüpload, worden weggeschreven naar $HOME en maken gebruik van dezelfde opslag. Aan elke sessie wordt een totaal schijfbudget toegewezen van maximaal 20 GiB bij 1 vCPU of groter, waarbij het proportioneel omlaag wordt geschaald voor kleinere CPU-lagen. Ongeveer 20% van dat budget is gereserveerd voor systeemgebruik en is niet zichtbaar of beschikbaar voor uw agent. De rest wordt gedeeld tussen uw containerimage, $HOME, en eventuele andere schrijfbare locaties in uw container.

Schalen en de juiste grootte aanpassen

Gehoste agents schalen per sessie, niet per replica. Het platform maakt een nieuwe vm-geïsoleerde sandbox voor elke sessie op aanvraag, voert deze uit voor de duur van de sessie (time-out voor inactiviteit 15 minuten, maximale levensduur 30 dagen) en scheurt deze uit wanneer de sessie afloopt. Er is geen aantal replica's om te configureren en geen warm pool om te dimensioneren.

Omdat elke sessie wordt uitgevoerd in een eigen sandbox, beschrijven de cpu- en geheugenwaarden die u hebt ingesteld op een agentversie één sessie, niet de cumulatieve footprint van de agent. De facturering is gebaseerd op het CPU- en geheugengebruik van alle actieve sessies samen, dus overdimensionering vermenigvuldigt de kosten met het aantal gelijktijdige sessies.

Voer een representatieve workload uit en inspecteer het resourcegebruik in de gekoppelde Application Insights-resource om de juiste grootte te krijgen:

  1. Open de App Insights-resource in de Azure-portal en selecteer Investigate>Performance.
  2. Bekijk de CPU, het beschikbare geheugen, de aanvraagsnelheid en de gemiddelde duur van de aanvraag gedurende het tijdsbereik dat u hebt getest.

Vergelijk de waargenomen pieken met de cpu en het toegewezen geheugen. Als aanhoudende pieken boven ongeveer 70% van de toegewezen capaciteit uitkomen, verhoog dan de toewijzing voor de volgende agentversie; als de pieken er ruim onder blijven, verlaag die dan om de kosten te beperken. Test altijd opnieuw na een wijziging, omdat elke nieuwe versie onveranderbaar is.

Privénetwerken

Gehoste agents ondersteunen de implementatie binnen netwerk-geïsoleerde Foundry-resources en kunnen gebruikmaken van een door de klant geleverde Azure Virtual Network voor uitgaand verkeer. Hierdoor kunnen agents in netwerk-geïsoleerde Foundry-implementaties privébronnen, zoals databases of interne API's, bereiken. Zie Virtuele netwerken configureren voor meer informatie.

Opmerking

Foundry-projecten die na 25 juni 2026 zijn gemaakt, ondersteunen een privé, met netwerkbeveiliging beveiligde Azure Container Registry voor uw agentimage. Voor projecten die vóór die datum zijn gemaakt, moet het register bereikbaar blijven via het openbare eindpunt. Bestaande projecten worden niet beïnvloed. Zie Beperkingen voor meer informatie.

Limieten, prijzen en beschikbaarheid

Prijzen

Facturering van beheerde hostingruntime is gebaseerd op het verbruik van CPU- en geheugenbronnen tijdens actieve sessies. Zie de pagina Met prijzen van Foundry voor actuele tarieven.

Beschikbaarheid van regio's

Gehoste agents zijn momenteel beschikbaar in de volgende regio's:

  • Australië - oost
  • Brazilië - zuid
  • Canada - centraal
  • Canada East
  • Central US
  • East US
  • East US 2
  • Frankrijk - centraal
  • Duitsland West Centraal
  • Italy North
  • Japan Oost
  • Japan Westelijk
  • Centraal Korea
  • VS - noord-centraal
  • Noorwegen - oost
  • Polen - centraal
  • Zuid-Afrika - noord
  • Zuid-Centraal Verenigde Staten
  • Zuid-India
  • Azië - zuidoost
  • Spanje - centraal
  • Zweden - centraal
  • Zwitserland - noord
  • West-Zwitserland
  • UAE North
  • UK South
  • UK West
  • West-Centraal VS
  • West Europe
  • West VS
  • West US 3

Opmerking

Deze lijst wordt bijgewerkt zodra er extra regio's beschikbaar komen.

Volgende stappen

Taak Link
Uw eerste gehoste agent bouwen en implementeren Quickstart: Uw eerste gehoste agent implementeren
Implementeren met behulp van de Foundry SDK Een gehoste agent implementeren met behulp van de Foundry SDK
Logboeken bijwerken, verwijderen, aanroepen of streamen Gehoste agents beheren
Instellen van tracering en monitoring Tracering inschakelen in uw project
Agentinstructies automatisch optimaliseren Overzicht van de agent-optimalisator
Prestaties van agents evalueren Agent-evaluatoren
Publiceren naar Teams, Microsoft 365 of aangepaste apps Agenttoepassingen
Door codevoorbeelden bladeren Python voorbeelden en C#-voorbeelden

Verwante inhoud

  • Last updated on