Foundry-gehoste agents

Met gehoste agents in Microsoft Foundry Agent Service kunt u in containers geplaatste agenttoepassingen implementeren in Microsoft beheerde infrastructuur. Het platform verwerkt schalen, sessiestatuspersistentie, beveiliging en levenscyclusbeheer, zodat u zich kunt richten op de logica van uw agent. Microsoft Foundry Hosted Agents is algemeen beschikbaar en ondersteunt agents die zijn gebouwd met uw eigen code of een voorkeursagentframework. In dit artikel wordt specifiek aandacht besteed aan de integratie van agentframeworkhosting.

Met behulp van de Agent Framework hosting integration kunt u een Agent blootstellen via het Foundry Responses or Invocations protocol met minimale code. Python ondersteunt ook het rechtstreeks hosten van een systeemeigen Workflow, zonder deze te converteren naar een agent.

Opmerking

U kunt ook agentcode implementeren die is gebouwd met andere frameworks voor Foundry gehoste agents met behulp van Azure Developer CLI-werkstromen (azd). Zie Wat zijn gehoste agents voor framework-agnostische concepten en implementatierichtlijnen? De rest van dit artikel is gericht op de integratie van Agent Framework.

Wanneer moet u gehoste agents gebruiken

Kies Foundry-gehoste agents als u dat wilt:

  • Beheerde infrastructuur : u hoeft zelf geen containers, webservers of schaalregels te configureren.
  • Ingebouwd sessiebeheer : het platform bewaart $HOME en geüploade bestanden over beurten en niet-actieve perioden.
  • Toegewezen agentidentiteit : elke geïmplementeerde agent krijgt een eigen Entra-identiteit voor veilige toegang tot modellen, hulpprogramma's en downstreamservices.
  • OpenAI-compatibele eindpunten : clients kunnen communiceren met uw agent met behulp van een openAI-compatibele SDK via het protocol Antwoorden.
  • Voor realtime audioagenten gebruikt u gehoste agents met Azure Speech in Foundry Tools (Voice Live) voor detectie van spraakactiviteiten aan de serverzijde, echo-annulering en ruisvermindering. Zie Voice Live gebruiken met gehoste agents voor meer informatie.

Opmerking

De Python-integratie agent-framework-foundry-hosting is vooraf beschikbaar. Microsoft Foundry Hosted Agents, de beheerde hostingservice, is algemeen beschikbaar.

Prerequisites

Voor lokale tests hebt u ook het volgende nodig:

  • Een Microsoft Foundry-project met een modelimplementatie (bijvoorbeeld gpt-4o)
  • Azure CLI geïnstalleerd en geverifieerd (az login)

Installeer het Hosting NuGet-pakket:

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
  • Python 3.10 of hoger

Installeer het prerelease-hostingpakket, de Foundry-client en Azure verificatiepakket:

pip install --pre agent-framework-foundry agent-framework-foundry-hosting azure-identity

In Foundry levert het platform de gebruikerscontext en oproepcontext van de beller; de hostinginfrastructuur gebruikt deze om de status per gebruiker te isoleren en de aanvraagcontext door te sturen naar Foundry-services. Lokale uitvoeringen ontvangen die platformcontext niet, dus toepassingen moeten hun eigen identiteits- en statuscontroles opgeven wanneer dat nodig is.

Protocol voor antwoorden

Het protocol Antwoorden is het aanbevolen startpunt voor de meeste agents. Het biedt een openAI-compatibel /responses eindpunt en het platform beheert automatisch de gespreksgeschiedenis, streaming en sessielevenscyclus.

Voor door Python gehoste agents heeft een antwoord dat voortijdig eindigt de status incomplete. Streaming-clients ontvangen een terminale gebeurtenis response.incomplete, terwijl niet-streaming-clients status ontvangen, ingesteld op incomplete. Een content_filter-eindreden komt overeen met incomplete_details.reason ingesteld op content_filter, en length komt overeen met max_output_tokens. Gegenereerde uitvoer- of weigeringsinhoud blijft beschikbaar in het antwoord.

using Azure.AI.AgentServer.Core;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));
var deployment = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME")
    ?? "gpt-4o";

AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a helpful AI assistant.",
        name: "my-agent");

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

var app = builder.Build();
app.Run();

Hiermee AgentHost.CreateBuilder maakt u een toepassingshost die vooraf is geconfigureerd voor de Foundry-hostingomgeving. AddFoundryResponses registreert uw agent bij de handler voor het antwoordprotocol en MapFoundryResponses wijst het /responses HTTP-eindpunt toe.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a helpful AI assistant.",
)

server = ResponsesHostServer(agent)
server.run()

De ResponsesHostServer omhult uw agent en stelt deze beschikbaar via het Foundry Responses-protocol. Het veld store van de aanroeper bepaalt of de externe respons en de door de host beheerde sessie- en goedkeuringsstatus worden opgeslagen. De history_source instelling selecteert onafhankelijk wie modelgeschiedenis levert:

history_source Gedrag van de modelgeschiedenis
"agent_server" (standaard) De host reconstrueert de opgeslagen externe antwoordentranscriptie en schakelt downstreamserviceopslag uit om dubbele geschiedenis te voorkomen.
"service" De host verzendt alleen de huidige invoer en slaat de vervolg-id van de opslagmodelservice privé op. Een opgeslagen providergesprek kan niet vertakken van een eerdere reactie.
"agent" De host verzendt alleen de huidige invoer. De standaardinstellingen voor opslag van de agent HistoryProvider of van de downstreamservice beheren de geschiedenis.

Combineer "agent_server" of "service" niet met een voor belasting geschikte HistoryProvider. De standaardmodus weigert ook vaste opties voor downstreamvervolging, zoals conversation_id, previous_response_iden conversation. Gebruiken history_source="agent" voor een aangepaste SupportsAgentRun implementatie.

De response_store constructorparameter selecteert de back-end voor persistentie van externe antwoorden. De oudere constructorparameter store is een afgeschafte alias voor response_store; geen van beide parameters stelt het veld per aanvraag store van de aanroeper in. Een verzoek met store=false is eenmalig: het slaat geen hostbeheerde status op, schakelt ondersteunde downstreamopslag uit en kan geen gebruik maken van background=true.

De host is eigenaar van de opgegeven agent en kan hostingspecifieke contextproviders toevoegen. Gebruik de agent niet opnieuw met een andere host of roep deze direct na de bouw van de host aan.

De antwoordhost behoudt systeemeigen computeroproepen, schermopnamen en veiligheidscontroles. Uw toepassing moet de aangevraagde acties uitvoeren en expliciet eventuele veiligheidscontroles erkennen. Zie Systeemeigen computergebruik voor de volledige stroom.

Een agentexemplaren of -factory kiezen

Zowel InvocationsHostServer als ResponsesHostServer accepteren via de parameter agent een agentinstantie of een synchrone of asynchrone functie zonder argumenten. De host hergebruikt een exemplaar voor zijn levensduur. Een aanroepbare functie wordt één keer per aanvraag uitgevoerd en de geretourneerde agent behoort tot die aanvraag.

Gebruik een aanroepbaar wanneer een reguliere agent veranderlijke status buiten AgentSession behoudt. Hosts behouden alleen hun ondersteunde sessie-, controlepunt- en functiegoedkeuringsopslagplaatsen, niet willekeurige velden op een agent met aanvraagscope.

Warning

Het hosten van een WorkflowAgent, zoals workflow.as_agent(), via agent= is verouderd. Een WorkflowAgent houdt de werkstroomstatus in het geheugen tussen uitvoeringen, dus één exemplaar mag nooit aanvragen van verschillende gebruikers of gesprekken verwerken. Host de workflow systeemeigen via workflow= en een request-aware factory-klasse.

Totdat u een Responses-host migreert, is een fabriek die voor elke aanvraag een nieuwe workflow, uitvoerders, verpakte agents, clients, providers en hulpprogramma's maakt, de veilige legacyvorm. Houd de naam van de workflow en executor-ID's stabiel zodat de host controlepunten kan herstellen. Voor een Invocations-host is deze verouderde factoryvorm alleen geschikt voor staatloze workflows met één interactieronde, omdat agenthosting geen workflowcontrolepunten herstelt.

Gebruik ook een factory wanneer een integratie de identiteit van een aanvraag met zich meedraagt of aanvraagspecifieke resources beheert. Maak bijvoorbeeld MCP-verbindingen, toolboxen, skillproviders, zoekclients, geheugenproviders en hun aanmeldgegevens binnen de factory wanneer deze de aanroep van het huidige platform of de gebruikerscontext gebruiken. Het hergebruiken van een procesbrede MCP-verbinding kan ervoor zorgen dat de identiteit van het verzoek waarmee deze is geopend, behouden blijft.

De host activeert en beëindigt voor elk verzoek door de factory aangemaakte agents. Agent beheert clients die via contextbeheer worden beheerd en MCP-hulpprogramma's, maar uw factory moet elke andere provider, transportlaag of inloggegevens die deze aanmaakt, afsluiten. Sluit gedeelde objecten die de toepassing extern aan de factory heeft aangeleverd niet.

Een systeemeigen workflow gebruiken met Responses

Python kan een gebouwde werkstroom rechtstreeks hosten via workflow=. Voor een systeemeigen werkstroom is een parse_response callback vereist waarmee de huidige antwoordaanvraag wordt toegewezen aan een getypeerde startinvoer of de volledige batch openstaande antwoorden:

from pydantic import BaseModel

from agent_framework_foundry_hosting import (
    CheckpointStoreProvider,
    HostedResponseRequest,
    ResponsesHostServer,
    WorkflowTurn,
)


class Ticket(BaseModel):
    text: str


def build_workflow(request: HostedResponseRequest):
    return build_fresh_workflow()


async def parse_response(request: HostedResponseRequest) -> WorkflowTurn[Ticket]:
    items = await request.get_input_items()
    if any(item.get("type") in ("function_call_output", "mcp_approval_response") for item in items):
        return WorkflowTurn(responses=await request.get_workflow_responses())

    text = await request.get_input_text()
    return WorkflowTurn(input=Ticket.model_validate_json(text or ""))


server = ResponsesHostServer(
    workflow=build_workflow,
    parse_response=parse_response,
    checkpoint_store_provider=CheckpointStoreProvider(
        allowed_checkpoint_types=[f"{Ticket.__module__}:{Ticket.__qualname__}"],
    ),
)

Gebruik een requestbewuste synchrone of asynchrone fabriek voor werkstromen die achtergrondwerk kunnen pauzeren, voortzetten of herstellen. De fabriek moet een nieuw gebouwde grafiek retourneren met nieuwe wijzigbare uitvoerders, agents, clients, providers en hulpprogramma's. Zorg ervoor dat de workflownaam en executor-ID's stabiel blijven, zodat de host het exacte controlepunt kan herstellen dat is gekoppeld aan het bovenliggende antwoord.

De vertrouwde platformgebruiker en Foundry-sandbox isoleren de status van de native workflow. De host valideert een volledige antwoordbatch die in behandeling is voordat er antwoordautorisatie wordt verbruikt. Verlopen, gedeeltelijke, dubbele, opnieuw afgespeelde, cross-user- en cross-sandbox-antwoorden mislukken voordat de workflow wordt uitgevoerd. Een aanvraag met store=false slaat de werkstroomstatus niet op en kan geen hervatbare pauze retourneren.

Voor een verouderde werkstroom die list[Message] accepteert, gebruikt u response_input_messages(request) om alleen de huidige Response-beurt te converteren. Het laadt geen eerdere externe geschiedenis of decodeert wachtende workflowreacties. Hosting agent=workflow.as_agent() blijft beschikbaar tijdens de huidige bètaversie, maar geeft een verouderingswaarschuwing. Zie de voorbeelden van de native Responses-workflow voor volledige voorbeelden.

De status behouden en langlopende gesprekken afhandelen

ResponsesHostServer en InvocationsHostServer configureer permanente sessiearchieven standaard. AgentSessionStoreProvider voorziet in een FoundryAgentSessionStore; Antwoordensessies maken gebruik van het agent_sessions logische archief, terwijl aanroepende sessies gebruikmaken van het afzonderlijke invocation_sessions archief. Deze opslagplaatsen gebruiken Foundry State Store wanneer ze worden gehost en de bestandsgebaseerde opslag van de SDK wanneer u lokaal werkt.

Voor workflowagents voor Responses levert CheckpointStoreProvider een FoundryCheckpointStore. Native Responses- en Invocations-workflows gebruiken dezelfde provider voor hun exacte continuation checkpoints. FunctionApprovalStoreProvider levert een FoundryFunctionApprovalStore voor agenthulpprogramma's waarvoor goedkeuring in behandeling is. Native workflowaanvragen en reacties op goedkeuring zijn in plaats daarvan gebonden aan werkstroomcontrolepunten.

Wanneer deze wordt uitgevoerd in Foundry, slaat de standaard-Python de status van de naamruimte op op basis van de gebruikers-id van het platform en de sessie-id van de Foundry-sandbox. Ze vereisen ook een platformoproep-id voor elke statusbewerking. De aanroep-id autoriseert en correleert de bewerking; het is geen gespreks-id en maakt geen deel uit van de opslagsleutel.

Voor antwoorden identificeert het door het platform geconfigureerde FOUNDRY_AGENT_SESSION_ID de sandbox, en een ander door de aanroeper opgegeven agent_session_id wordt geweigerd. Voor aanroepen controleert de host de gerouteerde agent_session_id queryparameter op basis van de aanvraagcontext. Als FOUNDRY_AGENT_SESSION_ID niet is geconfigureerd, moet de queryparameter aanwezig zijn, niet leeg zijn en overeenkomen met de aanvraagcontext. Ontbrekende, dubbele of conflicterende waarden worden geweigerd in plaats van een SDK-terugval-id te gebruiken.

Deze garanties zijn van toepassing op de standaard gehoste winkels. Aangepaste storeproviders moeten gelijkwaardige gebruikers- en sandboxisolatie implementeren, het interne AgentSession.session_id-element afzonderlijk van host-opzoeksleutels behouden en voorwaardelijke schrijfbewerkingen gebruiken, zodat verouderde verzoeken geen nieuwere momentopnamen kunnen overschrijven. Voor nieuwe sleutels moeten create-only-schrijfbewerkingen worden gebruikt in plaats van onvoorwaardelijke upserts. Bekijk het voorbeeld van aangepaste opslag voor een Cosmos DB-implementatie met schrijf- en verwijderingen met ETag-beveiliging.

Met history_source="agent"het geconfigureerde sessiearchief blijft de providerstatus behouden die wordt overgedragen door AgentSession, inclusief berichten van InMemoryHistoryProvider.

Beide hosts accepteren een StoreProvider[SessionStore] via agent_session_store_provider. Sessiestatus moet serialisatie ondersteunen AgentSession . Registreer codecs voor aangepaste statustypen metregister_state_type(); herstelde status behoudt niet Python objectidentiteit. Nieuwe standaardstores laten sessies 30 dagen na de laatste schrijfactie verlopen. Aangepaste providers bepalen hun eigen bewaartermijn.

De standaardopslagruimten met bereik lezen geen verouderde gegevens zonder bereik uit agent_sessions, invocation_sessions, controlepunten of functiegoedkeuringsgegevens. Start een nieuw antwoordgesprek in plaats van een oude previous_response_id of gespreks-id opnieuw te gebruiken. Aanroepen beginnen met een lege Agent Framework-sessie in de opslag met beperkte scope.

Geladen AgentSession records maken gebruik van ETag-voorwaarden. Als een andere aanvraag eerst dezelfde sessie doorgeeft, mislukt de verlopen schrijfbewerking in plaats van de nieuwere status te overschrijven. Deze controle biedt geen transacties of exactly-once-uitvoering voor agent- of hulpprogramma-bijwerkingen, zodat toepassingen nog steeds overlappende aanvragen moeten coördineren.

Voor antwoordspecifieke opslag geeft u een StoreProvider aan function_approval_store_provider of een ContextScopedStoreProvider aan checkpoint_store_providerdoor.

Extern achtergrondwerk gebruikt de voor de aanroeper zichtbare response.id voor polling. Met de standaardinstelling background_source="agent_server" blijft achtergronduitvoering op de host. Stel background_source="provider" alleen in met history_source="service" en een Responses-client met opslag die kan worden hervat. Als ResponsesServerOptions(resilient_background=True) ook is ingesteld, kan de host de polling van de provider pas hervatten nadat deze het privé-continuation-token heeft opgeslagen. Maak de bijwerkingen van de lokale tool idempotent, omdat als er een crash optreedt voordat het volgende token is opgeslagen, deze opnieuw kunnen worden uitgevoerd.

Importeer ResponsesServerOptions uit azure.ai.agentserver.responses en geef het door aan ResponsesHostServer via de parameter options. De beschikbare langlopende gespreksopties zijn afhankelijk van het type agent:

Vermogen Agenttype Vereisten en gedrag
Achtergrondherstel van workflowcontrolepunt Alleen werkstroom Stel ResponsesServerOptions(resilient_background=True)in. Verzend de aanvraag Antwoorden met store=true en background=true. Nadat de host opnieuw is opgestart, wordt het meest recente controlepunt voor duurzame werkstromen hervat of wordt de oorspronkelijke invoer opnieuw afgespeeld als er geen controlepunt bestaat. Stel geen checkpointopslag in voor de workflow, aangezien de host dit beheert. Maak externe bijwerkingen idempotent, omdat werk na het laatste duurzame controlepunt zich kan herhalen.
Providereigen achtergrondreacties Niet-workflow Agent met een Responses-client voor opslag Instellen history_source="service" en background_source="provider". Stel resilient_background=True in wanneer opgeslagen continuation tokens van providers behouden moeten blijven na een herstart van de host.
Stuurbare gesprekken Tijdelijk niet beschikbaar Stel niet in steerable_conversations=True. De host genereert RuntimeError tijdens de constructie, totdat de Agent Server SDK afgewezen steering turns veilig afhandelt.

Zie de aangepaste opslag, de basisgeschiedenis en achtergrond van antwoorden en flexibele langlopende werkstroomvoorbeelden voor volledige implementaties.

Bestanden lezen uit de gehoste sandbox

Behandel de persistente $HOME van een gehoste sandbox als een op aanvraag gerouteerde resource, niet als een algemene bestandssysteemgrens. Accepteer alleen bestanden die uw toepassing expliciet uploadt naar een toegewezen map, valideer de huidige sandbox-identiteit en negeer absolute paden, doorkruising, koppelingen, niet-gereglementeerde bestanden en oversized of ongeldige inhoud.

Voor het protocol Antwoorden routeert u een aanvraag naar een gehoste sessie met het agent_session_id hoofdtekstveld. De selectiefunctie voor queryreeksen is bedoeld voor aanroepen. Sessie-uploads en Toolbox-code-interpreterbestanden zijn afzonderlijke resources; een geüpload sandboxbestand wordt niet automatisch gekoppeld aan een Toolbox-container. Zie het voorbeeld van sessiebestanden voor gebonden UTF-8-leesbewerkingen en lokale en gehoste uploadrichtlijnen.

Opties voor beheeraanvragen

De host wijst systeemeigen velden voor het genereren van antwoorden toe aan de uitvoeringsopties van Agent Framework. Wordt bijvoorbeeld max_output_tokensmax_tokens, en parallel_tool_calls wordt allow_multiple_tool_calls. Afgevlakte waarden van extra_body overschrijven vertaalde systeemeigen waarden.

Gebruik de synchrone of asynchrone prepare_options(request, options) hook om modelopties van de aanroeper te verwijderen of te vervangen voordat een gewone agent wordt uitgevoerd. De hook kan geen door de host beheerde identiteit, opslag, voortzetting of transportvelden instellen. Voor een aangepaste SupportsAgentRun-implementatie die geen runtime-modelopties kan accepteren, stel unsupported_options in op "warn" (de standaardinstelling), "ignore" of "error".

Wanneer een door Foundry gehost MCP-hulpprogramma toestemming van de gebruiker vereist, retourneert ResponsesHostServer een onvolledig antwoord met een oauth_consent_request uitvoerelement. Presenteer de consent_link ervan aan de gebruiker en ga vervolgens verder met de ID van het onvolledige antwoord als previous_response_id nadat de gebruiker toestemming heeft gegeven. De host behoudt de agentsessie voor deze nieuwe poging en toont alleen absolute HTTPS-toestemmingskoppelingen.

Als uw host de verwachte autorisatiebronnen kent, beperk toestemmingslinks met allowed_oauth_consent_origins:

server = ResponsesHostServer(
    agent,
    allowed_oauth_consent_origins=[
        "https://logic-region.consent.azure-apihub.net",
        "https://auth.partner.example",
    ],
)

Als u de acceptatielijst weglaat, blijft de absolute HTTPS-validatie ongewijzigd zonder de doeloorsprong te beperken. Als u een lege lijst opgeeft, worden alle toestemmingslinks geweigerd. Alleen exacte HTTPS-oorsprongen configureren; vermeldingen met een pad, query of fragment worden geweigerd.

Protocol voor aanroepen

Het protocol Aanroepen geeft u volledige controle over de HTTP-aanvraag en -reactie. Gebruik deze wanneer u aangepaste payloads, niet-conversatiegerichte verwerking of streamingprotocollen nodig hebt die niet compatibel zijn met OpenAI.

Met het protocol Aanroepen in C# implementeert u een aangepaste InvocationHandler oplossing voor het verwerken van binnenkomende aanvragen:

using Azure.AI.AgentServer.Core;
using Azure.AI.AgentServer.Invocations;
using Microsoft.Agents.AI;

var builder = AgentHost.CreateBuilder(args);

builder.Services.AddSingleton<AIAgent, MyAgent>();
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

builder.RegisterProtocol("invocations", endpoints => endpoints.MapInvocationsServer());

var app = builder.Build();
app.Run();

De AddInvocationsServer methode registreert de protocolservices voor aanroepen. U implementeert InvocationHandler om te definiëren hoe uw agent elke aanvraag verwerkt.

Gebruik InvocationsHostServer van het agent_framework_foundry_hosting pakket voor een lichtgewicht installatie. Het wikkelt uw agent op dezelfde manier als ResponsesHostServer en beheert automatisch het sessiebeheer.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import InvocationsHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

server = InvocationsHostServer(agent)
server.run()

InvocationsHostServer accepteert dezelfde instantie- of request-scoped factoryvormen als beschreven voor de Responses host. Hiermee worden geserialiseerde sessies vanuit het geconfigureerde archief hersteld, zodat voltooide gesprekken kunnen worden voortgezet nadat de host opnieuw is opgestart. Zie Status behouden en langdurige gesprekken verwerken voor opslaggedrag, retentie en aanpassing.

Wanneer gehost gebruikt Invocations de geverifieerde aanvraagscope die wordt beschreven in Status behouden en langlopende gesprekken afhandelen. Behandel AgentSession.session_id als één ondoorzichtige waarde; parse deze niet en maak je niet afhankelijk van de interne weergave ervan. Lokale uitvoeringen behouden hun bestaande opslaggedrag voor één gebruiker.

Een systeemeigen werkstroom hosten met Invocations

Geef workflow= en een expliciete parse_request callback door om een systeemeigen werkstroom te hosten. De callback beheert het JSON-schema van de toepassing en retourneert een WorkflowTurn met getypte invoer of de volledige antwoordbatch in behandeling:

from pydantic import BaseModel
from starlette.requests import Request

from agent_framework_foundry_hosting import (
    CheckpointStoreProvider,
    InvocationsHostServer,
    WorkflowTurn,
)


class Ticket(BaseModel):
    ticket_id: str
    question: str


class TicketDecision(BaseModel):
    approved: bool


def build_workflow(_request: Request):
    return build_fresh_workflow()


async def parse_request(request: Request) -> WorkflowTurn[Ticket]:
    payload = await request.json()
    stream = payload.get("stream", False)

    if "responses" in payload:
        decisions = {
            request_id: TicketDecision.model_validate(value)
            for request_id, value in payload["responses"].items()
        }
        return WorkflowTurn(responses=decisions, stream=stream)

    ticket = Ticket.model_validate(payload)
    return WorkflowTurn(input=ticket, stream=stream)


server = InvocationsHostServer(
    workflow=build_workflow,
    parse_request=parse_request,
    checkpoint_store_provider=CheckpointStoreProvider(
        allowed_checkpoint_types=[
            f"{Ticket.__module__}:{Ticket.__qualname__}",
            f"{TicketDecision.__module__}:{TicketDecision.__qualname__}",
        ],
    ),
)

Neem elk aangepast applicatietype op dat door de werkstroom wordt opgeslagen in de allowed_checkpoint_types-lijst van de controlepuntprovider.

Gehoste werkstromen vereisen een requestbewuste fabriek die een nieuw opgebouwde graaf met stabiele werkstroom- en uitvoerders-id's retourneert. Een direct-build-workflow is alleen beschikbaar voor een lokale, eenmalige uitvoering die niet wordt onderbroken.

Antwoorden in niet-streamingworkflows maken gebruik van application/json met een gebeurtenislijst output. Streaming verzendt framed output en request_info gebeurtenissen, gevolgd door done alleen nadat de exacte werkstroomcursor is opgeslagen. Behandel streamed output als voorlopig tot done. Native workflows ondersteunen legacy_wire_format=True niet.

De host valideert reacties tegen het exacte wachtende controlepunt in het bereik van de vertrouwde gebruiker en sandbox. Als een workflow meerdere aanvragen in behandeling heeft, beantwoordt u de volledige batch in één keer. Zie voor een uitvoerbare parser, een workflow voor getypeerde tickets, een toestaanlijst voor checkpointtypen en JSON/SSE-voorbeelden de voorbeeld van de native Invocations-workflow.

Verzoeken en antwoorden van aanroepen aanpassen

Accepteert standaard POST /invocations een JSON-object met een tekenreeks message, een optioneel options object en een optionele Booleaanse stream waarde. Als u een toepassingsspecifieke nettolading wilt accepteren, geeft u een synchrone of asynchrone parse_request callback door die retourneert InvocationRun(messages, options, stream). Gebruik prepare_options om een kopie van de generatieopties voor de beller te filteren of te vervangen voordat de agent wordt gestart.

De host valideert de uitvoer van de hook en wijst controles voor platformidentiteit, opslag, continuering en agentuitvoering af. Voor agenten die geen runtime-opties accepteren, stel unsupported_options in op "warn" (de standaardinstelling), "ignore" of "error". Zie het voorbeeld van de parser voor aanroepen voor een volledige implementatie.

Een succesvolle niet-streamende aanvraag retourneert JSON in de vorm {"response": "..."}. Streaming maakt gebruik van server-sent events: een of meer event: delta-frames, gevolgd door event: done bij succes of event: error bij een fout. Een stroom kan delta’s uitsturen voordat er een fout optreedt, dus cliënten moeten done, en niet een delta, als succesvolle voltooiing beschouwen. De host verzendt done pas nadat deze de antwoordstroom heeft gefinaliseerd en de AgentSession persistent heeft opgeslagen. Dit session_id is de route-id van de platform-sandbox, niet de geserialiseerde AgentSession.session_idid.

Stel legacy_wire_format=True alleen in tijdens het migreren van bestaande clients die het eerdere antwoord in platte tekst en de ruwe stream van tekstchunks vereisen. Deze compatibiliteitsmodus is afgeschaft en converteert geen fouten naar geslaagde tekst. De host serialiseert aanvragen binnen dezelfde sessie slechts binnen één proces; een compare-and-swap-conflict tussen processen kan nog steeds optreden na effecten van externe tools.

Het Invocations-protocol hervat geen workflowuitvoeringen die in behandeling zijn of zijn onderbroken. Gebruik het aangepaste handlerpatroon in de volgende sectie wanneer u een ander gedrag voor werkstroomvervolging nodig hebt.

Voor volledige controle over de verwerking van aanvragen, gebruikt u InvocationAgentServerHost rechtstreeks uit het azure.ai.agentserver.invocations pakket en implementeert u uw eigen aanroephandler.

import os
from collections.abc import AsyncGenerator

from agent_framework import Agent, AgentSession
from agent_framework.foundry import FoundryChatClient
from azure.ai.agentserver.invocations import InvocationAgentServerHost
from azure.identity import DefaultAzureCredential
from starlette.requests import Request
from starlette.responses import JSONResponse, Response, StreamingResponse

_sessions: dict[str, AgentSession] = {}

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    """Handle streaming multi-turn chat."""
    data = await request.json()
    session_id = request.state.session_id
    stream = data.get("stream", False)
    user_message = data.get("message", None)

    if user_message is None:
        return Response(content="Missing 'message' in request", status_code=400)

    session = _sessions.setdefault(session_id, AgentSession(session_id=session_id))

    if stream:

        async def stream_response() -> AsyncGenerator[str]:
            async for update in agent.run(user_message, session=session, stream=True):
                yield update.text

        return StreamingResponse(
            stream_response(),
            media_type="text/event-stream",
            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
        )

    response = await agent.run([user_message], session=session, stream=stream)
    return JSONResponse({"response": response.text})


if __name__ == "__main__":
    app.run()

Warning

Het in-memory sessiearchief in het voorbeeld van de aangepaste handler gaat verloren bij opnieuw opstarten. Gebruik duurzame opslag (bijvoorbeeld Cosmos DB) in productie.

Voor een volledige implementatie van aanroepen raadpleegt u het voorbeeld van Foundry-hosted Telegram. Het plaatst API Management vóór de webhook van de gehoste agent en gebruikt beheerde identiteiten, Key Vault en Cosmos DB voor persistente gespreksgeschiedenis.

Opmerking

Ondersteuning voor Go voor door Foundry gehoste agents is binnenkort beschikbaar. Zie de opslagplaats Agent Framework Go voor de meest recente status.

Tip

Raadpleeg de Python-voorbeelden of de C#-voorbeelden voor voorbeelden van een gehost agentproject. Of gebruik de azd ai agent init opdracht om een nieuw gehost agentproject helemaal opnieuw te bouwen. Raadpleeg deze snelstartgids voor stapsgewijze instructies.

Lokaal uitvoeren

De Azure Developer CLI (azd) biedt de eenvoudigste manier om uw gehoste agent lokaal uit te voeren en te testen.

Een project initialiseren

Maak een nieuwe map en initialiseer vanuit een voorbeeldmanifest:

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -m <path-to-agent.manifest.yaml>

Tip

Het manifest kan een pad naar een lokaal YAML-bestand of een URL naar een extern manifest zijn.

Omgevingsvariabelen instellen

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL="<your-model-deployment>"

De agenthost uitvoeren

azd ai agent run

De agenthost wordt gestart op http://localhost:8088.

De agent aanroepen

azd ai agent invoke --local "Hello!"

Of gebruik curl:

curl -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello!"}'

Of in PowerShell :

(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Hello!"}').Content

Implementeren in Foundry

Nadat u uw agent lokaal hebt geverifieerd, implementeert u deze in Microsoft Foundry:

  1. Resources inrichten (als u nog geen Foundry-project hebt):

    azd provision

    Hiermee maakt u een resourcegroep met een Foundry-exemplaar, project, modelimplementatie, Application Insights en een containerregister.

  2. Implementeer de agent:

    azd deploy

    Hiermee wordt uw agent verpakt als een containerafbeelding, geüpload naar Azure Container Registry en geïmplementeerd in Foundry Agent Service.

De Foundry-hostinginfrastructuur injecteert automatisch de volgende omgevingsvariabelen in uw agentcontainer tijdens runtime:

Veranderlijk Beschrijving
FOUNDRY_PROJECT_ENDPOINT De eindpunt-URL voor het Foundry-project.
AZURE_AI_MODEL_DEPLOYMENT_NAME De naam van de implementatie van het door azd beheerde model die is geconfigureerd tijdens het configureren van azd ai agent init. Python-code kan lokaal de voorkeur geven aan FOUNDRY_MODEL en terugvallen op deze gehoste waarde.
APPLICATIONINSIGHTS_CONNECTION_STRING De Application Insights-verbindingsreeks voor telemetrie.

Zodra de agent is geïmplementeerd, is deze toegankelijk via het toegewezen Foundry-eindpunt en kan deze ook worden getest vanuit de Foundry-portal.

Volgende stappen 

Concepten van gehoste agents

  • Laatst bijgewerkt om