Körtidskontrakt för värdbaserad agent

En värdbaserad agent är en container som uppfyller ett specifikt körningskontrakt med Microsoft Foundry-plattformen. Den här referensen beskriver vad plattformen förväntar sig av din container och hur SDK-adapterpaketen hjälper dig att uppfylla dessa krav.

SDK-adapterpaketen implementerar hela kontraktet åt dig. Om du använder azure-ai-agentserver-responses eller azure-ai-agentserver-invocationsimplementerar du endast din hanteringslogik.

Om du använder en kodningsagent som GitHub Copilot för att implementera eller granska en värdbaserad agentcontainer kan Microsoft Foundry Skill hjälpa dig att kontrollera körningskontraktet, adapteranvändningen och distributionsantagandena.

Kontraktskrav

Containern måste:

Protokollslutpunkter

Ett protokoll definierar HTTP-kontraktet mellan Foundry och din agentcontainer. Containern implementerar minst en protokollslutpunkt.

Svarsprotokoll

Svarsprotokollet implementerar OpenAI-svars-API:et. Plattformen skickar begäranden till POST /responses och förväntar sig antingen ett JSON-svar eller en SSE-ström (Server-Sent Events).

Använd svarsprotokollet som standardval. Det är kompatibelt med OpenAI API-ekosystemet.

Anropsprotokoll

Anropsprotokollet är ett minimalt direktprotokoll. Du definierar nyttolaststrukturen och plattformen skickar den utan tolkning.

Använd anropsprotokollet när du behöver fullständig kontroll över nyttolasten för begäran och svar.

SDK-adapterpaket

Adapterpaketen är protokollspecifika och ramverksagnostiska. De arbetar med alla agentramverk, inklusive Microsoft Agent Framework, LangGraph och anpassad kod.

Adaptern hanterar följande delar av kontraktet åt dig:

• HTTP-serverkonfiguration på port 8088.
• Slutpunkten för hälsoavsökningen (GET /readiness).
• Protokollspecifik frågeparsing och svarsformatering.
• Hydrering av konversationshistorik (svarsprotokoll).
• SSE-strömningsinfrastruktur.
• OpenTelemetry-instrumentation.
• Graciös avstängning på SIGTERM.
• Förbrukning av plattformsmiljövariabler.

Du implementerar en hanteringsfunktion som tar emot parsade begäranden och returnerar svar.

Tidskrävande och elastisk körning (förhandsversion)

Protokollkorten består av den motståndskraftiga uppgiften och strömmande primitiver i deras AgentServer Core-beroende. Använd dessa primitiver när arbetet måste överleva ett processavbrott eller klienter måste återansluta till återreplikerade utdata.

Svarskortet kan hantera elastisk körning för lagrade bakgrundssvar. Servern väljer elastisk bakgrundsbearbetning och din hanterare kör eller återupptar antingen på ett säkert sätt från en varaktig kontrollpunkt. Förgrundssvar anropas inte igen när processen har stoppats.

Kortet Anrop föreskriver inte något status- eller avsökningskontrakt. Registrera elastiska uppgifter för varaktig körning och definiera sedan svars-, avsöknings- eller strömslutpunkter som exponerar förloppet för dina klienter.

För körningsmodellen, kontrollpunktsstrategier och beteende för återspelning av klienter, se Motståndskraft för långvariga värdbaserade agenter.

Exempel på hanterare

De fullständiga bring-your-own-exemplen för båda protokollen och båda språken finns på lagringsplatsen foundry-samples .

Exempel på svarsprotokoll

Den här minimala hanteraren vidarebefordrar användarindata till en modell från foundry-modellkatalogen via svars-API:et. SDK-adaptern återfuktar konversationshistoriken automatiskt via context.get_history() (Python) eller context.GetHistoryAsync() (C#), så agenten behåller kontexten över varv.

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

Exempel på anropsprotokoll

Med anropsprotokollet tar hanteraren emot det JSON som anroparen publicerar och returnerar det JSON-kod du väljer. Det finns ingen inbyggd konversationshistorik.

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 fullständiga exemplen omfattar även hydrering av konversationshistorik, felhantering, telemetri, integrering av verktygslåda och Dockerfile och azure.yaml konfiguration.

Hälsoavsökning

Plattformen skickar GET /readiness för att avgöra om containern är redo att hantera trafik. Returnera 200 OK när containern är klar eller en status som inte är 200 för att signalera att plattformen ska starta om instansen. SDK-korten registrerar den här slutpunkten automatiskt.

Nätverk och transport

Graciös avstängning

När plattformen skickar SIGTERMslutar containern att acceptera nya begäranden, slutför begäranden under flygning, töms väntande skrivningar till $HOME (sessionsfilsystemet) och avslutas rent. SDK-korten hanterar den här sekvensen automatiskt.

Plattformsmiljövariabler

Plattformen matar in miljövariabler i containern vid start. Koden kan läsa följande nyckelvariabler:

Plattformsbegärandehuvuden (containerprotokoll 2.0.0)

Dessa huvuden gäller endast för värdbaserade agenter i containerprotokollversion 2.0.0. På protokoll 2.0.0 matar plattformen in dem på varje begäran till protokollslutpunkterna, både för protokollen Svar och anrop. De skickas inte till infrastrukturslutpunkter som hälsoavsökningen. Behandla deras värden som ogenomskinliga och lästa men åsidosätt dem inte.

Båda rubrikerna är tillförlitliga – plattformen genererar dem från verifierad identitet – och ingen av dem garanteras när du kör lokalt, så hantera saknade värden korrekt.

AgentServer SDK exponerar dessa som konstanter på PlatformHeaders och läser dem åt dig – via FoundryAgentRequestContext.Current i .NET eller get_request_context() i Python. För den fullständiga listan över plattformshuvuden, inklusive svarshuvuden, lägger runtime till till exempel x-agent-session-id, x-platform-serveroch x-platform-error-source, i referensen för Azure AI Agent Server Core-bibliotek.

Information om hur protokoll 2.0.0 ändrar identitetsspridning finns i Migrera värdbaserade agenter.

Exempel: partition lagrade data per session

När containern bevarar användarägda data måste du ange dem efter sessionen (och för delade sessioner, användaren) så att en anropare inte kan läsa en annans data. Exemplet med anteckningsagenten gör detta genom att härleda en filsökväg per session under $HOME, där filer också kan nås via API:et sessionfiler:

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

När fler än en användare kan dela en session lägger du till x-agent-user-id i nyckeln. Se Multiplex flera användare i en värdbaserad agentsession.

Vidarebefordra anpassade begärandehuvuden till din container

I föregående avsnitt beskrivs rubriker som plattformen matar in. Separat vidarebefordrar gatewayen endast en fast uppsättning begärandehuvuden som tillhandahålls av anroparen till containern. Alla anroparhuvud utanför den uppsättningen tas bort vid gatewayen innan begäran når containern, vilket håller autentiseringsuppgifter och interna huvuden utanför containern som standard.

Om du vill skicka dina egna kontextuella data till containern använder du prefixet för direktklienthuvud, x-client-. Plattformen vidarebefordrar varje rubrik som börjar med x-client- oförändrad, så att du kan skicka värden som ett klient-ID eller en funktionsflagga utan att ändra begärandetexten och sedan läsa dem i hanteraren som andra begäranderubriker. AgentServer SDK definierar det här prefixet som PlatformHeaders.ClientHeaderPrefix; för den fullständiga plattformshuvudlistan kan du läsa referensen för Azure AI Agent Server Core-bibliotek.

Gatewayen vidarebefordrar dessa anroparhuvuden till protokollslutpunkterna Svar och anrop:

Gatewayen vidarebefordrar aldrig autentiseringshuvuden som Authorization, eller Host, Cookieoch x-forwarded-*. Alla huvuden som inte matchar listan över tillåtna tas bort, så förlita dig inte på anpassade rubriker utanför prefixet x-client-* som når containern.

Relaterat innehåll

• Vad är värdbaserade agenter?
• Livscykel för agentutveckling
• Python exempel på värdbaserade agenter