Contrat d’exécution de l’agent hébergé

Un agent hébergé est un conteneur qui remplit un contrat d’exécution spécifique avec la plateforme Microsoft Foundry. Cette référence décrit ce que la plateforme attend de votre conteneur et la façon dont les packages d’adaptateurs sdk vous aident à répondre à ces exigences.

Les packages d’adaptateurs sdk implémentent l’intégralité du contrat pour vous. Si vous utilisez azure-ai-agentserver-responses ou azure-ai-agentserver-invocations, vous implémentez uniquement votre logique de gestionnaire.

Si vous utilisez un agent de codage comme GitHub Copilot pour implémenter ou examiner un conteneur d’agent hébergé, la compétence Microsoft Foundry peut vous aider à vérifier le contrat d’exécution, l’utilisation de l’adaptateur et les hypothèses de déploiement.

Conditions requises pour les contrats

Votre conteneur doit :

Points de terminaison de protocole

Un protocole définit le contrat HTTP entre Foundry et votre conteneur d’agent. Votre conteneur implémente au moins un point de terminaison de protocole.

Protocole des réponses

Le protocole réponses implémente l’API Réponses OpenAI. La plateforme envoie des requêtes et POST /responses attend une réponse JSON ou un flux d’événements Server-Sent (SSE).

Utilisez le protocole de réponses comme choix standard. Il est compatible avec l’écosystème d’API OpenAI.

Protocole d'invocation

Le protocole d’appel est un protocole pass-through minimal. Vous définissez la structure de charge utile et la plateforme la transmet sans interprétation.

Utilisez le protocole d’appel lorsque vous avez besoin d’un contrôle total sur les charges utiles de requête et de réponse.

Packages d’adaptateurs sdk

Les packages d’adaptateurs sont spécifiques au protocole et indépendants de l’infrastructure. Ils fonctionnent avec n’importe quelle infrastructure d’agent, notamment Microsoft Framework d’agent, LangGraph et du code personnalisé.

L’adaptateur gère les parties suivantes du contrat pour vous :

• Configuration du serveur HTTP sur le port 8088.
• Point de terminaison de la sonde d’intégrité (GET /readiness).
• Analyse des requêtes et mise en forme de réponse spécifiques au protocole.
• Hydratation de l’historique des conversations (protocole de réponses).
• Infrastructure de diffusion en continu SSE.
• Instrumentation OpenTelemetry.
• Arrêt correct le SIGTERM.
• Consommation de variables d’environnement de plateforme.

Vous implémentez une fonction de gestionnaire qui reçoit des demandes analysées et retourne des réponses.

Exécution longue et résiliente (préversion)

Les adaptateurs de protocole composent avec la tâche résiliente et les primitives de diffusion en continu dans leur dépendance AgentServer Core. Utilisez ces primitives lorsque le travail doit survivre à une interruption de processus ou les clients doivent se reconnecter à la sortie relecture.

L’adaptateur Réponses peut gérer l’exécution résiliente pour les réponses en arrière-plan stockées. Votre serveur opte pour un traitement en arrière-plan résilient, et votre gestionnaire réexécute ou reprend en toute sécurité à partir d’un point de contrôle durable. Les réponses de premier plan ne sont pas réinvocées après l’arrêt du processus.

L’adaptateur d’appel ne prescrit pas de contrat d’état ou d’interrogation. Inscrivez des tâches résilientes pour une exécution durable, puis définissez la réponse, l’interrogation ou les points de terminaison de flux qui exposent la progression à vos clients.

Pour le modèle d’exécution, les stratégies de point de contrôle et le comportement de relecture du client, consultez Résilience pour les agents hébergés de longue durée.

Exemples de gestionnaires

Les exemples complets de bring-your-own pour les deux protocoles et les deux langages se trouvent dans le référentiel foundry-samples .

Exemple de protocole Réponses

Ce gestionnaire minimal transfère l’entrée utilisateur à un modèle à partir du catalogue de modèles Foundry via l’API Réponses. L’adaptateur sdk hydrate automatiquement l’historique des conversations via context.get_history() (Python) ou context.GetHistoryAsync() (C#), afin que l’agent conserve le contexte entre les tours.

import asyncio
import os

from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    ResponsesServerOptions,
    TextResponse,
)
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

# FOUNDRY_PROJECT_ENDPOINT is auto-injected in hosted Foundry containers and
# set by 'azd ai agent run' for local development.
_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
_model = os.environ["FOUNDRY_MODEL_NAME"]

_project_client = AIProjectClient(
    endpoint=_endpoint, credential=DefaultAzureCredential()
)
_responses_client = _project_client.get_openai_client().responses

app = ResponsesAgentServerHost(
    options=ResponsesServerOptions(default_fetch_history_count=20),
)


@app.response_handler
async def handler(
    request: CreateResponse,
    context: ResponseContext,
    _cancellation_signal: asyncio.Event,
):
    user_input = await context.get_input_text() or "Hello!"
    history = await context.get_history()

    # Build the model input from prior conversation turns + the current message.
    input_items = []
    for item in history:
        # Map history items to {"role": ..., "content": ...} dicts; see the
        # full sample for the unpacking helper.
        ...
    input_items.append({"role": "user", "content": user_input})

    response = await asyncio.get_running_loop().run_in_executor(
        None,
        lambda: _responses_client.create(
            model=_model,
            instructions="You are a helpful AI assistant.",
            input=input_items,
            store=False,  # platform manages history; don't store at model level
        ),
    )

    return TextResponse(context, request, text=response.output_text)


app.run()

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.Identity;
using OpenAI.Responses;

ResponsesServer.Run<HelloWorldHandler>(configure: builder =>
{
    var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
        ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
    var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME")
        ?? throw new InvalidOperationException("FOUNDRY_MODEL_NAME is not set.");

    var projectClient = new AIProjectClient(
        new Uri(endpoint), new DefaultAzureCredential());
    var responsesClient = projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForModel(model);

    builder.Services.AddSingleton(responsesClient);
});

public sealed class HelloWorldHandler(ProjectResponsesClient responsesClient)
    : ResponseHandler
{
    private const string SystemPrompt = "You are a helpful AI assistant.";

    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request,
            createText: ct => GenerateTextAsync(context, ct));
    }

    private async Task<string> GenerateTextAsync(
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        var userInput = await context.GetInputTextAsync(
            cancellationToken: cancellationToken) ?? "Hello!";
        var history = await context.GetHistoryAsync(cancellationToken);

        var options = new CreateResponseOptions { Instructions = SystemPrompt };
        // Map history items into options.InputItems via
        // ResponseItem.Create*MessageItem(...). See the full sample.
        options.InputItems.Add(ResponseItem.CreateUserMessageItem(userInput));

        var result = await responsesClient.CreateResponseAsync(options);
        return result.Value.GetOutputText() ?? string.Empty;
    }
}

Exemple de protocole Invocations

Avec le protocole d’appel, votre gestionnaire reçoit le code JSON que l’appelant publie et retourne le code JSON choisi. Il n’y a pas d’historique de conversation intégré.

from starlette.requests import Request
from starlette.responses import JSONResponse, Response
from azure.ai.agentserver.invocations import InvocationAgentServerHost

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request) -> Response:
    data = await request.json()
    message = data.get("message", "Hello!")
    return JSONResponse({"echo": message})


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

using Azure.AI.AgentServer.Invocations;
using Microsoft.AspNetCore.Http;

InvocationsServer.Run(handler: async (HttpContext httpContext) =>
{
    var data = await httpContext.Request
        .ReadFromJsonAsync<Dictionary<string, object>>();
    var message = data is { } d && d.TryGetValue("message", out var m)
        ? m?.ToString() ?? "Hello!"
        : "Hello!";
    await httpContext.Response.WriteAsJsonAsync(new { echo = message });
});

Les exemples complets incluent également l’hydratation de l’historique des conversations, la gestion des erreurs, la télémétrie, l’intégration de la boîte à outils et le fichier Dockerfile et azure.yaml la configuration.

Sonde de santé

La plateforme envoie GET /readiness pour déterminer si votre conteneur est prêt à servir le trafic. Retournez 200 OK une fois le conteneur prêt ou un état autre que 200 pour signaler que la plateforme doit redémarrer l’instance. Les adaptateurs sdk inscrivent automatiquement ce point de terminaison.

Réseau et transport

Arrêt approprié

Lorsque la plateforme envoie SIGTERM, votre conteneur cesse d’accepter de nouvelles demandes, termine les demandes en cours d’exécution, vide les écritures en attente dans $HOME (le système de fichiers de session) et se ferme correctement. Les adaptateurs sdk gèrent automatiquement cette séquence.

Variables d’environnement de plateforme

La plateforme injecte des variables d’environnement dans votre conteneur au démarrage. Votre code peut lire les variables clés suivantes :

En-têtes de requête de plateforme (protocole conteneur 2.0.0)

Ces en-têtes s’appliquent uniquement aux agents hébergés sur le protocole conteneur version 2.0.0. Sur le protocole 2.0.0, la plateforme les injecte sur chaque requête à vos points de terminaison de protocole, à la fois pour les protocoles Réponses et Appels. Ils ne sont pas envoyés aux points de terminaison d’infrastructure tels que la sonde d’intégrité. Traitez leurs valeurs comme opaques, et lisez, mais ne les remplacez pas.

Les deux en-têtes sont fiables : la plateforme les génère à partir d’une identité vérifiée et aucune n’est garantie lorsque vous exécutez localement, de sorte que gérer les valeurs manquantes correctement.

Le Kit de développement logiciel (SDK) AgentServer les expose sous forme de constantes PlatformHeaders et les lit pour vous , via FoundryAgentRequestContext.Current .NET ou get_request_context() dans Python. Pour obtenir la liste complète d’en-têtes de plateforme, y compris les en-têtes de réponse que le runtime ajoute tels que x-agent-session-id, x-platform-serveret x-platform-error-source, consultez la référence de la bibliothèque Azure AI Agent Server Core.

Pour savoir comment le protocole 2.0.0 modifie la propagation des identités, consultez Migrer des agents hébergés.

Exemple : partitionner des données stockées par session

Lorsque votre conteneur conserve les données appartenant à l’utilisateur, cléz-la par la session (et, pour les sessions partagées, l’utilisateur) afin qu’un appelant ne puisse pas lire les données d’un autre. L’exemple d’agent de prise de notes effectue cette opération en dérivant un chemin d’accès de fichier par session sous $HOME, où les fichiers sont également accessibles via l’API Fichiers de session :

# note_store.py - one JSONL file per session, stored under $HOME.
def _get_file_path(session_id: str) -> str:
    safe_id = "".join(c if c.isalnum() or c in "-_" else "_" for c in session_id)
    base_dir = os.environ.get("HOME", os.getcwd())
    return os.path.join(base_dir, f"notes_{safe_id}.jsonl")

// NoteStore.cs - one JSONL file per session, stored under $HOME.
private static string GetFilePath(string sessionId)
{
    var safeId = string.Join("_", sessionId.Split(Path.GetInvalidFileNameChars()));
    var baseDir = Environment.GetEnvironmentVariable("HOME")
        ?? Directory.GetCurrentDirectory();
    return Path.Combine(baseDir, $"notes_{safeId}.jsonl");
}

Lorsque plusieurs utilisateurs peuvent partager une session, ajoutez-y x-agent-user-id la clé. Consultez Multiplex plusieurs utilisateurs dans une session d’agent hébergée.

Transférer des en-têtes de requête personnalisés à votre conteneur

La section précédente couvre les en-têtes injectés par la plateforme . Séparément, la passerelle transfère uniquement un ensemble fixe d’en-têtes de requête fournis par l’appelant à votre conteneur. Tout en-tête d’appelant en dehors de ce jeu est supprimé à la passerelle avant que la requête atteigne votre conteneur, ce qui conserve les informations d’identification et les en-têtes internes hors de votre conteneur par défaut.

Pour transmettre vos propres données contextuelles à votre conteneur, utilisez le préfixe d’en-tête du client direct. x-client- La plateforme transfère chaque en-tête qui commence par x-client- inchangé. Vous pouvez donc envoyer des valeurs telles qu’un ID de locataire ou un indicateur de fonctionnalité sans modifier le corps de la demande, puis les lire dans votre gestionnaire comme n’importe quel autre en-tête de requête. Le Kit de développement logiciel (SDK) AgentServer définit ce préfixe en tant que PlatformHeaders.ClientHeaderPrefix; pour la liste d’en-têtes de plateforme complète, consultez la référence de la bibliothèque Azure AI Agent Server Core.

La passerelle transfère ces en-têtes d’appelant aux points de terminaison de protocole Réponses et Appels :

La passerelle ne transfère jamais les en-têtes d’informations d’identification tels que Authorization, ou HostCookie, et x-forwarded-*. Tout en-tête qui ne correspond pas à la liste verte est supprimé, ne vous appuyez donc pas sur des en-têtes personnalisés en dehors du x-client-* préfixe qui atteint votre conteneur.

Contenu connexe

• Qu’est-ce que les agents hébergés ?
• Cycle de vie du développement de l’agent
• Exemples d'agents hébergés Python