Foundry-gehoste agents

Hosted agents in Microsoft Foundry Agent Service kunt u Agent Framework-agents implementeren als containertoepassingen in Microsoft beheerde infrastructuur. Het platform verwerkt schalen, sessiestatuspersistentie, beveiliging en levenscyclusbeheer, zodat u zich kunt richten op de logica van uw agent.

Met de integratie van Agent Framework hosting kunt u elke Agent of werkstroom gebruiken en deze met minimale code beschikbaar maken via het Foundry Responses- of Invocations-protocol.

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.

Opmerking

Foundry gehost agents zijn momenteel in preview. Raadpleeg de documentatie voor gehoste Foundry-agents voor de nieuwste beschikbaarheid, limieten en prijzen.

Vereiste voorwaarden

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 hostingpakket Python:

pip install agent-framework agent-framework-foundry-hosting

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.

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.",
    default_options={"store": False},
)

server = ResponsesHostServer(agent)
server.run()

De ResponsesHostServer omhult uw agent en stelt deze beschikbaar via het Foundry Responses-protocol. Door store in te stellen op False in default_options wordt voorkomen dat de gespreksgeschiedenis wordt gedupliceerd, omdat de hostinginfrastructuur de geschiedenis automatisch beheert.

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()

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()

Waarschuwing

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

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:

Variabel 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