Contrato en tiempo de ejecución del agente hospedado

Un agente hospedado es un contenedor que cumple un contrato en tiempo de ejecución específico con la plataforma Microsoft Foundry. En esta referencia se describe lo que espera la plataforma del contenedor y cómo los paquetes del adaptador del SDK le ayudan a cumplir esos requisitos.

Los paquetes del adaptador del SDK implementan todo el contrato. Si usa azure-ai-agentserver-responses o azure-ai-agentserver-invocations, solo implementa la lógica del controlador.

Si usa un agente de codificación como GitHub Copilot para implementar o revisar un contenedor de agentes hospedado, la aptitud de Microsoft Foundry puede ayudar a comprobar el contrato en tiempo de ejecución, el uso del adaptador y las suposiciones de implementación.

Requisitos del contrato

El contenedor debe:

Puntos de conexión de protocolo

Un protocolo define el contrato HTTP entre Foundry y el contenedor del agente. El contenedor implementa al menos un punto de conexión de protocolo.

Protocolo de respuestas

El protocolo de respuestas implementa la API de respuestas de OpenAI. La plataforma envía solicitudes a POST /responses y espera una respuesta JSON o una secuencia de eventos de Server-Sent (SSE).

Use el protocolo de respuestas como opción estándar. Es compatible con el ecosistema de openAI API.

Protocolo de invocaciones

El protocolo de invocaciones es un protocolo de paso a través mínimo. Defina la estructura de carga y la plataforma la pasa sin interpretación.

Use el protocolo de invocaciones cuando necesite control total sobre las cargas de solicitud y respuesta.

Paquetes de adaptadores del SDK

Los paquetes de adaptador son específicos del protocolo y independientes del marco de trabajo. Funcionan con cualquier marco de agente, incluido Microsoft Agent Framework, LangGraph y código personalizado.

El adaptador controla las siguientes partes del contrato para usted:

• Configuración del servidor HTTP en el puerto 8088.
• Punto de conexión de sondeo de estado (GET /readiness).
• Análisis y formato de respuesta de solicitudes específicos del protocolo.
• Hidratación del historial de conversaciones (protocolo de respuestas).
• Infraestructura de streaming de SSE.
• Instrumentación de OpenTelemetry.
• Apagado correcto en SIGTERM.
• Consumo de variables de entorno de plataforma.

Implementa una función de controlador que recibe solicitudes analizadas y devuelve respuestas.

Ejecución prolongada y resistente (versión preliminar)

Los adaptadores de protocolo se componen con las primitivas de streaming y tareas resistentes en su dependencia de AgentServer Core. Use estos primitivos cuando el trabajo debe sobrevivir a una interrupción del proceso o los clientes deben volver a conectarse a la salida reproducida.

El adaptador de respuestas puede administrar la ejecución resistente para las respuestas en segundo plano almacenadas. El servidor opta por el procesamiento en segundo plano resistente y el controlador vuelve a ejecutarse o se reanuda de forma segura desde un punto de control duradero. Las respuestas en primer plano no se vuelven a invocar después de que se detenga el proceso.

El adaptador invocaciones no prescribe un estado ni un contrato de sondeo. Registre tareas resistentes para la ejecución duradera y, a continuación, defina la respuesta, el sondeo o los puntos de conexión de flujo que exponen el progreso a los clientes.

Para ver el modelo de ejecución, las estrategias de punto de control y el comportamiento de reproducción de cliente, consulte Resistencia para agentes hospedados de larga duración.

Ejemplos del controlador

Los ejemplos de bring-your-own completos para los protocolos y ambos lenguajes se encuentran en el repositorio foundry-samples .

Ejemplo del protocolo de respuestas

Este controlador mínimo reenvía la entrada del usuario a un modelo desde el catálogo de modelos foundry a través de la API de respuestas. El adaptador del SDK hidrata automáticamente el historial de conversaciones a través context.get_history() de (Python) o context.GetHistoryAsync() (C#), por lo que el agente mantiene el contexto entre turnos.

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

Ejemplo del protocolo invocaciones

Con el protocolo de invocaciones, el controlador recibe cualquier JSON que publique el autor de la llamada y devuelva cualquier JSON que elija el código. No hay ningún historial de conversaciones integrado.

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

Los ejemplos completos también incluyen la hidratación del historial de conversaciones, el control de errores, la telemetría, la integración del cuadro de herramientas y dockerfile y la azure.yaml configuración.

Sondeo de salud

La plataforma envía GET /readiness para determinar si el contenedor está listo para atender el tráfico. Devuelve 200 OK cuando el contenedor está listo o un estado distinto de 200 para indicar que la plataforma debe reiniciar la instancia. Los adaptadores del SDK registran este punto de conexión automáticamente.

Red y transporte

Apagado correcto

Cuando la plataforma envía SIGTERM, el contenedor deja de aceptar nuevas solicitudes, finaliza las solicitudes en curso, vacía las escrituras pendientes $HOME en (el sistema de archivos de sesión) y sale limpiamente. Los adaptadores del SDK controlan esta secuencia automáticamente.

Variables de entorno de plataforma

La plataforma inserta variables de entorno en el contenedor al iniciarse. El código puede leer las siguientes variables clave:

Encabezados de solicitud de plataforma (protocolo de contenedor 2.0.0)

Estos encabezados solo se aplican a los agentes hospedados en la versión 2.0.0 del protocolo de contenedor. En el protocolo 2.0.0, la plataforma los inserta en cada solicitud a los puntos de conexión de protocolo, tanto para los protocolos de respuestas como de invocaciones. No se envían a puntos de conexión de infraestructura como el sondeo de estado. Trate sus valores como opacos y lea, pero no los invalide.

Ambos encabezados son de confianza( la plataforma los genera a partir de la identidad comprobada) y tampoco se garantiza cuando se ejecuta localmente, por lo que se controla correctamente los valores que faltan.

El SDK de AgentServer expone estas constantes en PlatformHeaders y las lee automáticamente, a través FoundryAgentRequestContext.Current de en .NET o get_request_context() en Python. Para obtener la lista de encabezados de plataforma completa, incluidos los encabezados de respuesta que agrega el entorno de ejecución, como x-agent-session-id, x-platform-servery x-platform-error-source, consulte la referencia de la biblioteca de Azure AI Agent Server Core.

Para obtener información sobre cómo cambia el protocolo 2.0.0 la propagación de identidades, consulte Migración de agentes hospedados.

Ejemplo: partición de datos almacenados por sesión

Cuando el contenedor conserva los datos propiedad del usuario, escárelo por la sesión (y, para las sesiones compartidas, el usuario) para que un autor de la llamada no pueda leer los datos de otro. El ejemplo de agente de toma de notas lo hace derivando una ruta de acceso de archivo por sesión en $HOME, donde también se puede acceder a los archivos a través de la API de archivos de sesión:

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

Cuando más de un usuario puede compartir una sesión, agregue x-agent-user-id a la clave. Consulte Multiplex multiple users in one hosted agent session (Multiplex multiplex en una sesión del agente hospedado).

Reenvío de encabezados de solicitud personalizados al contenedor

En la sección anterior se tratan los encabezados que inserta la plataforma . Por separado, la puerta de enlace reenvía solo un conjunto fijo de encabezados de solicitud proporcionados por el autor de la llamada al contenedor. Cualquier encabezado de llamador fuera de ese conjunto se quita en la puerta de enlace antes de que la solicitud llegue al contenedor, lo que mantiene las credenciales y los encabezados internos fuera del contenedor de forma predeterminada.

Para pasar sus propios datos contextuales al contenedor, use el prefijo de encabezado de cliente de paso a través, x-client-. La plataforma reenvía todos los encabezados que comienzan sin x-client- cambios, por lo que puede enviar valores como un identificador de inquilino o una marca de característica sin cambiar el cuerpo de la solicitud y, a continuación, leerlos en el controlador como cualquier otro encabezado de solicitud. El SDK de AgentServer define este prefijo como PlatformHeaders.ClientHeaderPrefix; para obtener la lista completa de encabezados de la plataforma, consulte la referencia de la biblioteca principal del agente de IA de Azure.

La puerta de enlace reenvía estos encabezados de llamada a los puntos de conexión del protocolo de respuestas e invocaciones:

La puerta de enlace nunca reenvía encabezados de credenciales como Authorization, o Host, Cookiey x-forwarded-*. Se quita cualquier encabezado que no coincida con la lista de permitidos, por lo que no se basa en encabezados personalizados fuera del x-client-* prefijo que llega al contenedor.

Contenido relacionado

• ¿Qué son los agentes alojados?
• Ciclo de vida de desarrollo del agente
• Ejemplos de agentes hospedados en Python