Runtimecontract voor gehoste agent

Een gehoste agent is een container die voldoet aan een specifiek runtime-contract met het Microsoft Foundry-platform. In deze verwijzing wordt beschreven wat het platform van uw container verwacht en hoe de SDK-adapterpakketten u helpen aan deze vereisten te voldoen.

De SDK-adapterpakketten implementeren het volledige contract voor u. Als u gebruikt azure-ai-agentserver-responses of azure-ai-agentserver-invocations, implementeert u alleen uw handlerlogica.

Als u een coderingsagent zoals GitHub Copilot gebruikt om een gehoste agentcontainer te implementeren of te controleren, kan de Microsoft Foundry Skill helpen bij het controleren van het runtime-contract, het gebruik van de adapter en de implementatie.

Contractvereisten

Uw container moet:

Protocoleindpunten

Een protocol definieert het HTTP-contract tussen Foundry en uw agentcontainer. Uw container implementeert ten minste één protocoleindpunt.

Protocol voor antwoorden

Het protocol voor antwoorden implementeert de OpenAI-antwoorden-API. Het platform verzendt aanvragen naar POST /responses en verwacht een JSON-antwoord of een SSE-stroom (Server-Sent Events).

Gebruik het antwoordprotocol als standaardoptie. Het is compatibel met het OpenAI API-ecosysteem.

Protocol voor aanroepen

Het protocol voor aanroepen is een minimaal passthrough-protocol. U definieert de nettoladingstructuur en het platform doorloopt deze zonder interpretatie.

Gebruik het protocol voor aanroepen wanneer u volledige controle nodig hebt over de nettoladingen van aanvragen en antwoorden.

SDK-adapterpakketten

De adapterpakketten zijn protocolspecifiek en frameworkneutraal. Ze werken met elk agentframework, waaronder Microsoft Agent Framework, LangGraph en aangepaste code.

De adapter verwerkt de volgende onderdelen van het contract voor u:

• HTTP-serverinstallatie op poort 8088.
• Het eindpunt van de statustest (GET /readiness).
• Protocolspecifieke aanvraagparsering en antwoordopmaak.
• Hydratatie van gespreksgeschiedenis (protocol voor antwoorden).
• SSE-streaminginfrastructuur.
• OpenTelemetry-instrumentatie.
• Probleemloos afsluiten op SIGTERM.
• Verbruik van platformomgevingsvariabelen.

U implementeert een handler-functie die geparseerde aanvragen ontvangt en antwoorden retourneert.

Langdurige en tolerante uitvoering (preview)

De protocoladapters bestaan uit de tolerante taak en streamingprimitief in hun AgentServer Core-afhankelijkheid. Gebruik deze primitieven wanneer werk een procesonderbreking moet overleven of clients opnieuw verbinding moeten maken met opnieuw afgespeelde uitvoer.

De adapter Antwoorden kan tolerante uitvoering beheren voor opgeslagen achtergrondreacties. Uw server kiest voor tolerante achtergrondverwerking en uw handler wordt veilig opnieuw uitgevoerd of hervat vanaf een duurzaam controlepunt. Reacties op de voorgrond worden niet opnieuw aangeroepen nadat het proces stopt.

De adapter Aanroepen schrijft geen status of polling-contract voor. Registreer tolerante taken voor duurzame uitvoering en definieer vervolgens het antwoord, polling of stream-eindpunten die de voortgang beschikbaar maken voor uw clients.

Zie Tolerantie voor langlopende gehoste agents voor het uitvoeringsmodel, controlepuntstrategieën en gedrag van clientherhaling.

Handlervoorbeelden

De volledige bring-your-own samples voor beide protocollen en beide talen bevinden zich in de opslagplaats foundry-samples .

Voorbeeld van antwoordprotocol

Deze minimale handler stuurt gebruikersinvoer door naar een model vanuit de Foundry-modelcatalogus via de Response-API. De SDK-adapter hydrateert de gespreksgeschiedenis automatisch via context.get_history() (Python) of context.GetHistoryAsync() (C#), zodat de agent context in stand houdt.

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;
    }
}

Voorbeeld van het aanroepprotocol

Met het aanroepprotocol ontvangt uw handler elke JSON die de beller plaatst en retourneert elke JSON die uw code kiest. Er is geen ingebouwde gespreksgeschiedenis.

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

De volledige voorbeelden omvatten ook hydratatie van gespreksgeschiedenis, foutafhandeling, telemetrie, integratie van werksets en Dockerfile en azure.yaml setup.

Gezondheidsonderzoek

Het platform verzendt GET /readiness om te bepalen of uw container gereed is om verkeer te verwerken. Retourneert 200 OK wanneer de container gereed is of een niet-200-status om aan te geven dat het platform het exemplaar opnieuw moet starten. De SDK-adapters registreren dit eindpunt automatisch.

Netwerk en transport

Probleemloos afsluiten

Wanneer het platform wordt verzonden SIGTERM, stopt uw container met het accepteren van nieuwe aanvragen, worden aanvragen tijdens de vlucht voltooid, worden schrijfbewerkingen in behandeling verwijderd naar $HOME (het sessiebestandssysteem) en wordt deze op een schone manier afgesloten. De SDK-adapters verwerken deze reeks automatisch.

Platformomgevingsvariabelen

Het platform injecteert omgevingsvariabelen in uw container bij het opstarten. Uw code kan de volgende sleutelvariabelen lezen:

Platformaanvraagheaders (containerprotocol 2.0.0)

Deze headers zijn alleen van toepassing op gehoste agents op containerprotocolversie 2.0.0. Op protocol 2.0.0 injecteert het platform ze op elke aanvraag naar uw protocoleindpunten, voor zowel de protocollen Antwoorden als Aanroepen. Ze worden niet verzonden naar infrastructuureindpunten, zoals de statustest. Behandel de waarden als ondoorzichtig en lees ze, maar overschrijf ze niet.

Beide headers zijn betrouwbaar: het platform genereert ze op basis van geverifieerde identiteit en geen van beide wordt gegarandeerd wanneer u lokaal wordt uitgevoerd, dus zorg ervoor dat ontbrekende waarden correct worden verwerkt.

De AgentServer SDK toont deze als constanten aan PlatformHeaders en leest ze voor u FoundryAgentRequestContext.Current door in .NET of get_request_context() in Python. Zie de x-agent-session-id voor de volledige lijst met platformheaders, inclusief antwoordheaders die de runtime toevoegt, zoals x-platform-server, x-platform-error-sourceen .

Zie Gehoste agents migreren voor meer informatie over hoe protocol 2.0.0 identiteitsdoorgifte wijzigt.

Voorbeeld: opgeslagen gegevens per sessie partitioneren

Wanneer uw container gegevens bewaart die eigendom zijn van de gebruiker, moet u deze sleutel gebruiken door de sessie (en, voor gedeelde sessies, de gebruiker), zodat de ene beller de gegevens van een andere gebruiker niet kan lezen. Het voorbeeld van de notitieagent doet dit door een pad per sessiebestand onder $HOMEaf te leiden, waar bestanden ook bereikbaar zijn via de Sessiebestanden-API:

# 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");
}

Wanneer meerdere gebruikers een sessie kunnen delen, voegt u deze toe x-agent-user-id aan de sleutel. Zie Multiplex meerdere gebruikers in één gehoste agentsessie.

Aangepaste aanvraagheaders doorsturen naar uw container

In de vorige sectie worden headers beschreven die het platform injecteert. Afzonderlijk stuurt de gateway alleen een vaste set doorroepende aanvraagheaders door naar uw container. Elke aanroeperheader buiten die set wordt verwijderd bij de gateway voordat de aanvraag uw container bereikt, waardoor referenties en interne headers standaard buiten uw container blijven.

Als u uw eigen contextuele gegevens wilt doorgeven aan uw container, gebruikt u het voorvoegsel van de passthrough-clientheader. x-client- Het platform stuurt elke header die begint met x-client- ongewijzigd, zodat u waarden zoals een tenant-id of een functievlag kunt verzenden zonder de aanvraagbody te wijzigen en deze vervolgens in uw handler te lezen, net zoals elke andere aanvraagheader. De AgentServer SDK definieert dit voorvoegsel als PlatformHeaders.ClientHeaderPrefix; voor de volledige lijst met platformheaders raadpleegt u de naslaginformatie over de Azure AI Agent Server Core-bibliotheek.

De gateway stuurt deze aanroeperheaders door naar de eindpunten van het antwoord- en aanroepprotocol:

De gateway stuurt nooit referentieheaders Authorizationzoals , of Host, Cookieen x-forwarded-*. Eventuele headers die niet overeenkomen met de acceptatielijst, worden verwijderd, dus vertrouw niet op aangepaste headers buiten het x-client-* voorvoegsel dat uw container bereikt.

Verwante inhoud

• Wat zijn gehoste agenten?
• Levenscyclus van agentontwikkeling
• Door Python gehoste agentvoorbeelden