Agents hébergés Foundry

Agents hébergés dans Microsoft Service de l’agent Foundry vous permet de déployer des agents Agent Framework en tant qu’applications conteneurisées sur une infrastructure gérée par Microsoft. La plateforme gère la mise à l’échelle, la persistance de l’état de session, la sécurité et la gestion du cycle de vie pour vous concentrer sur la logique de votre agent.

Avec l'intégration de l'hébergement de l'Agent Framework, vous pouvez prendre n'importe quel Agent ou flux de travail et l'exposer à travers le protocole Foundry Responses ou Invocations avec un code minimal.

Quand utiliser des agents hébergés

Choisissez les agents hébergés Foundry lorsque vous souhaitez :

  • Infrastructure managée : il n’est pas nécessaire de configurer des conteneurs, des serveurs web ou des règles de mise à l’échelle vous-même.
  • Gestion de session intégrée : la plateforme conserve et charge les $HOME fichiers entre les tours et les périodes d’inactivité.
  • Identité de l’agent dédié : chaque agent déployé obtient sa propre identité Entra pour un accès sécurisé aux modèles, outils et services en aval.
  • Points de terminaison compatibles OpenAI : les clients peuvent interagir avec votre agent à l’aide de n’importe quel KIT de développement logiciel (SDK) compatible OpenAI via le protocole Réponses.

Note

Les agents hébergés Foundry sont actuellement en version préliminaire. Consultez la documentation sur les agents hébergés Foundry pour connaître la disponibilité, les limites et la tarification les plus récentes.

Prerequisites

Pour les tests locaux, vous avez également besoin des éléments suivants :

  • Un projet Microsoft Foundry avec un déploiement de modèle (par exemple, gpt-4o)
  • Azure CLI installé et authentifié (az login)

Installez le package NuGet d’hébergement :

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
dotnet add package Azure.AI.Projects --prerelease
  • Python 3.10 ou version ultérieure

Installez le package de Python d’hébergement :

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

Protocole des réponses

Le protocole Réponses est le point de départ recommandé pour la plupart des agents. Il expose un point de terminaison compatible /responses OpenAI et la plateforme gère automatiquement l’historique des conversations, la diffusion en continu et le cycle de vie des sessions.

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

AgentHost.CreateBuilder crée un hôte d’application préconfiguré pour l’environnement d’hébergement Foundry. AddFoundryResponses inscrit votre agent auprès du gestionnaire de protocole Réponses et MapFoundryResponses mappe le /responses point de terminaison HTTP.

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

ResponsesHostServer encapsule votre agent et l’expose via le protocole Foundry Responses. Définir store à False dans default_options évite de dupliquer l'historique des conversations, car l'infrastructure d'hébergement gère automatiquement cet historique.

Protocole d'invocation

Le protocole Invocations vous donne un contrôle total sur la requête et la réponse HTTP. Utilisez-le quand vous avez besoin de charges utiles personnalisées, de traitement non conversationnel ou de protocoles de streaming qui ne sont pas compatibles Avec OpenAI.

Avec le protocole Invocations en C#, vous implémentez un personnalisé InvocationHandler pour traiter les requêtes entrantes :

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

La AddInvocationsServer méthode inscrit les services de protocole Invocations. Vous implémentez InvocationHandler pour définir la façon dont votre agent traite chaque requête.

Pour une configuration légère, utilisez InvocationsHostServer du paquet agent_framework_foundry_hosting. Il encapsule votre agent de la même façon que ResponsesHostServer pour gérer automatiquement la gestion des sessions :

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

Pour un contrôle total sur la gestion des demandes, utilisez directement InvocationAgentServerHost du paquet azure.ai.agentserver.invocations et implémentez votre propre gestionnaire d’appels :

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

Avertissement

Le magasin de sessions en mémoire dans l’exemple de gestionnaire personnalisé est perdu lors du redémarrage. Utilisez un stockage durable (par exemple, Cosmos DB) en production.

Conseil / Astuce

Reportez-vous aux exemples Python ou aux exemples C# pour obtenir des exemples de projet d’agent hébergé. Vous pouvez également utiliser la azd ai agent init commande pour générer automatiquement un nouveau projet d’agent hébergé à partir de zéro. Reportez-vous à ce guide de démarrage rapide pour obtenir des instructions pas à pas.

Exécution locale

L’interface CLI Azure développeur (azd) offre le moyen le plus simple d’exécuter et de tester votre agent hébergé localement.

Initialiser un projet

Créez un dossier et initialisez à partir d’un exemple de manifeste :

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

Conseil / Astuce

Le manifeste peut être un chemin d’accès à un fichier YAML local ou à une URL vers un manifeste distant.

Définir des variables d’environnement

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

Exécuter l’hôte de l’agent

azd ai agent run

L’hôte de l’agent démarre sur http://localhost:8088.

Appeler l’agent

azd ai agent invoke --local "Hello!"

Ou utilisez curl:

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

Ou dans PowerShell :

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

Déploiement sur Foundry

Une fois que vous avez vérifié votre agent localement, déployez-le sur Microsoft Foundry :

  1. Provisionnez des ressources (si vous n’avez pas encore de projet Foundry) :

    azd provision

    Cela crée un groupe de ressources avec une instance Foundry, un projet, un déploiement de modèle, Application Insights et un registre de conteneurs.

  2. Déployez l’agent :

    azd deploy

    Cela empaquette votre agent en tant qu'image conteneur, l'envoie à Azure Container Registry et le déploie dans Foundry Agent Service.

L’infrastructure d’hébergement Foundry injecte automatiquement les variables d’environnement suivantes dans votre conteneur d’agent au moment de l’exécution :

Variable Description
FOUNDRY_PROJECT_ENDPOINT URL du point de terminaison du projet Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME Nom du déploiement du modèle (configuré pendant azd ai agent init).
APPLICATIONINSIGHTS_CONNECTION_STRING La chaîne de connexion Application Insights pour la télémétrie.

Une fois déployé, votre agent est accessible via son point de terminaison Foundry dédié et peut également être testé à partir du portail Foundry.

Étapes suivantes

Concepts des agents en mode hébergé

  • Last updated on