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 de integratie van agentframeworkhosting kunt u een Agent, inclusief een werkstroom die is verpakt met Workflow.as_agent(), beschikbaar maken via het protocol Foundry Responses of Invocations met minimale code.

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
dotnet add package Azure.AI.Projects --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("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["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. Voor een niet-werkstroomagent gebruikt de standaardinstelling history_source="agent_server" de geconfigureerde agentserverantwoordprovider als de geschiedenisbron van het model. De host voorkomt dat de downstreammodelservice een tweede kopie behoudt wanneer de clientgeschiedenis standaard opslaat.

Combineer de standaardgeschiedenisbron niet met een HistoryProvider bron met load_messages=True. Stel ook de conversation, previous_response_id of conversation_id opties voor servicevoortzetting van de downstreamservice niet in. De host weigert deze configuraties om dubbele geschiedenis te voorkomen.

Gebruik ResponsesHostServer(agent, history_source="agent") wanneer de geschiedenisprovider of downstream-modelservice van de agent de gespreksgeschiedenis moet beheren. Deze modus geeft alleen de huidige aanvraaginvoer van agentserver door en behoudt de geschiedenis en het serviceopslaggedrag van de agent. Aangepaste SupportsAgentRun implementaties moeten deze modus gebruiken. De store parameter blijft gescheiden: het selecteert de antwoordprovider die invoer en uitvoer van de Antwoorden-API in beide modi persistent maakt.

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.

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 callable als de agent buiten AgentSession een wijzigbare toestand behoudt. Creëer in het bijzonder een WorkflowAgent vanuit een factory die een nieuwe workflow, executors en ingepakte agents opbouwt:

def create_workflow_agent():
    return build_workflow().as_agent(name="support-workflow")


server = ResponsesHostServer(agent=create_workflow_agent)

Houd de naam van de werkstroom en uitvoerprogramma-id's stabiel, zodat latere antwoordenaanvragen opgeslagen controlepunten kunnen vinden. ResponsesHostServer behoudt zijn ondersteunde status via de sessie-, checkpoint- en functiegoedkeuringsopslag; het slaat geen willekeurige velden permanent op in een agent met aanvraagbereik. Bekijk de werkstroom en tolerante langlopende werkstroomvoorbeelden .

De status behouden en langlopende gesprekken afhandelen

ResponsesHostServer configureert standaard door Foundry ondersteunde stores. Voor agents die niet tot een workflow behoren, biedt AgentSessionStoreProvider een FoundryAgentSessionStore. Voor workflowagents levert CheckpointStoreProvider een FoundryCheckpointStore. FunctionApprovalStoreProvider biedt een FoundryFunctionApprovalStore voor goedkeuringen in behandeling. Deze opslagplaatsen gebruiken Foundry State Store wanneer ze worden gehost en de lokale status van Agent Server wanneer u lokaal uitvoert.

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

Als u opslag wilt aanpassen, geeft u een StoreProvider aan agent_session_store_provider of function_approval_store_provider. Geef een ContextScopedStoreProvider door aan checkpoint_store_provider. Implementeer SessionStoreStoreProvider[SessionStore] en gebruik bijvoorbeeld uw eigen sessiearchief voor niet-werkstroomagenten.

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
Robuuste reacties op de achtergrond 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.
Stuurbare gesprekken Alleen voor niet-workflow Stel ResponsesServerOptions(steerable_conversations=True) in en verzend Responses-verzoeken met store=true. Houd beurten in één lineaire keten door dezelfde conversation-waarde opnieuw te gebruiken. U kunt ook de direct voorafgaande previous_response_id verzenden en het opgeloste agent_session_idbestand behouden. De host weigert verouderde voorgangers die een afsplitsing zouden veroorzaken.

ResponsesHostServer geeft RuntimeError weer als u veerkrachtige achtergrondreacties inschakelt voor een niet-workflowagent of aanstuurbare gesprekken voor een workflowagent. Zie de aangepaste opslag, flexibele langlopende werkstroom en stuurbare langlopende agentvoorbeelden voor volledige implementaties.

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.

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["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. De ingebouwde sessies worden tijdens de levensduur van de host in het geheugen opgeslagen en blijven na een herstart niet behouden. Het Invocations-protocol hervat geen workflowuitvoeringen die in behandeling zijn of zijn onderbroken. Gebruik het aangepaste handlerpatroon in de volgende sectie met duurzame toepassingsopslag wanneer u een ander vervolggedrag 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["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 voorbeelden Python 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 AZURE_AI_MODEL_DEPLOYMENT_NAME="<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 modelimplementatie (geconfigureerd tijdens azd ai agent init).
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

  • Last updated on