Contrato de runtime do agente hospedado

Um agente hospedado é um contêiner que atende a um contrato de runtime específico com a plataforma Microsoft Foundry. Essa referência descreve o que a plataforma espera do contêiner e como os pacotes do adaptador do SDK ajudam você a atender a esses requisitos.

Os pacotes do adaptador do SDK implementam todo o contrato para você. Se você usar azure-ai-agentserver-responses ou azure-ai-agentserver-invocationsimplementar apenas a lógica do manipulador.

Se você usar um agente de codificação como GitHub Copilot para implementar ou revisar um contêiner de agente hospedado, o Microsoft Foundry Skill poderá ajudar a verificar o contrato de runtime, o uso do adaptador e as suposições de implantação.

Requisitos de contrato

Seu contêiner deve:

Pontos de extremidade de protocolo

Um protocolo define o contrato HTTP entre o Foundry e o contêiner do agente. Seu contêiner implementa pelo menos um ponto de extremidade de protocolo.

Protocolo de respostas

O protocolo de respostas implementa a API de Respostas OpenAI. A plataforma envia solicitações POST /responses e espera uma resposta JSON ou um fluxo de eventos de Server-Sent (SSE).

Use o protocolo de respostas como a opção padrão. Ele é compatível com o ecossistema da API OpenAI.

Protocolo de invocações

O protocolo de invocações é um protocolo de passagem mínimo. Você define a estrutura de conteúdo e a plataforma a passa sem interpretação.

Use o protocolo de invocações quando precisar de controle total sobre as cargas de solicitação e resposta.

Pacotes de adaptador do SDK

Os pacotes do adaptador são específicos do protocolo e independentes da estrutura. Eles funcionam com qualquer estrutura de agente, incluindo Microsoft Agent Framework, LangGraph e código personalizado.

O adaptador manipula as seguintes partes do contrato para você:

• Configuração do servidor HTTP na porta 8088.
• O ponto de extremidade de investigação de integridade (GET /readiness).
• Análise de solicitação específica do protocolo e formatação de resposta.
• Hidratação do histórico de conversas (protocolo de respostas).
• Infraestrutura de streaming SSE.
• Instrumentação OpenTelemetry.
• Desligamento normal em SIGTERM.
• Consumo de variável de ambiente de plataforma.

Você implementa uma função de manipulador que recebe solicitações analisadas e retorna respostas.

Execução longa e resiliente (versão prévia)

Os adaptadores de protocolo compõem a tarefa resiliente e os primitivos de streaming em sua dependência AgentServer Core. Use esses primitivos quando o trabalho deve sobreviver a uma interrupção de processo ou os clientes devem se reconectar à saída reproduzida.

O adaptador de respostas pode gerenciar a execução resiliente para respostas em segundo plano armazenadas. Seu servidor aceita o processamento em segundo plano resiliente e seu manipulador é executado novamente ou retomado com segurança de um ponto de verificação durável. As respostas em primeiro plano não são invocadas novamente depois que o processo é interrompido.

O adaptador invocações não prescreve um contrato de status ou sondagem. Registre tarefas resilientes para execução durável e defina os pontos de extremidade de resposta, sondagem ou fluxo que expõem o progresso para seus clientes.

Para o modelo de execução, estratégias de ponto de verificação e comportamento de reprodução do cliente, consulte Resiliência para agentes hospedados de execução longa.

Exemplos de manipulador

Os exemplos completos de traga seus próprios protocolos e ambos os idiomas estão no repositório de amostras de fundiário .

Exemplo de protocolo de respostas

Esse manipulador mínimo encaminha a entrada do usuário para um modelo do catálogo de modelos do Foundry por meio da API de Respostas. O adaptador do SDK hidrata o histórico de conversas automaticamente por meio context.get_history() (Python) ou context.GetHistoryAsync() (C#), de modo que o agente mantém o 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;
    }
}

Exemplo de protocolo invocações

Com o protocolo de invocações, seu manipulador recebe qualquer JSON que o chamador postar e retorna qualquer JSON que seu código escolher. Não há histórico interno de conversas.

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

Os exemplos completos também incluem hidratação de histórico de conversas, tratamento de erros, telemetria, integração de caixa de ferramentas e Dockerfile e azure.yaml configuração.

Sonda de saúde

A plataforma envia GET /readiness para determinar se o contêiner está pronto para atender ao tráfego. Retorne 200 OK quando o contêiner estiver pronto ou um status não 200 para sinalizar que a plataforma deve reiniciar a instância. Os adaptadores do SDK registram esse ponto de extremidade automaticamente.

Rede e transporte

Desligamento normal

Quando a plataforma envia SIGTERM, o contêiner para de aceitar novas solicitações, conclui as solicitações em voo, libera as gravações $HOME pendentes (o sistema de arquivos de sessão) e sai de forma limpa. Os adaptadores do SDK lidam com essa sequência automaticamente.

Variáveis de ambiente de plataforma

A plataforma injeta variáveis de ambiente em seu contêiner na inicialização. Seu código pode ler as seguintes variáveis de chave:

Cabeçalhos de solicitação de plataforma (protocolo de contêiner 2.0.0)

Esses cabeçalhos se aplicam somente a agentes hospedados no protocolo de contêiner versão 2.0.0. No protocolo 2.0.0, a plataforma os injeta em cada solicitação para seus pontos de extremidade de protocolo, tanto para os protocolos respostas quanto invocações. Eles não são enviados para pontos de extremidade de infraestrutura, como a investigação de integridade. Trate seus valores como opacos e leia, mas não os substitua.

Ambos os cabeçalhos são confiáveis - a plataforma os gera a partir da identidade verificada - e nenhum deles é garantido quando você é executado localmente, portanto, manipule valores ausentes normalmente.

O SDK do AgentServer expõe-as como constantes PlatformHeaders e as lê para você , por meio FoundryAgentRequestContext.Current de .NET ou get_request_context() em Python. Para obter a lista completa de cabeçalhos de plataforma, incluindo cabeçalhos de resposta que o runtime adiciona, comox-agent-session-id, x-platform-serverex-platform-error-source, consulte a referência de biblioteca Azure AI Agent Server Core.

Para saber como o protocolo 2.0.0 altera a propagação de identidade, consulte Migrar agentes hospedados.

Exemplo: partição de dados armazenados por sessão

Quando o contêiner persistir dados de propriedade do usuário, pressione-os pela sessão (e, para sessões compartilhadas, o usuário) para que um chamador não possa ler os dados de outro. O exemplo de agente de anotação faz isso derivando um caminho $HOMEde arquivo por sessão em que os arquivos também podem ser acessados por meio da API de Arquivos de Sessão:

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

Quando mais de um usuário puder compartilhar uma sessão, adicione x-agent-user-id à chave. Consulte vários usuários multiplex em uma sessão de agente hospedado.

Encaminhar cabeçalhos de solicitação personalizados para o contêiner

A seção anterior aborda os cabeçalhos que a plataforma injeta. Separadamente, o gateway encaminha apenas um conjunto fixo de cabeçalhos de solicitação fornecidos pelo chamador para o contêiner. Qualquer cabeçalho de chamador fora desse conjunto é descartado no gateway antes que a solicitação chegue ao contêiner, o que mantém as credenciais e os cabeçalhos internos fora do contêiner por padrão.

Para passar seus próprios dados contextuais para o contêiner, use o prefixo de cabeçalho do cliente de passagem. x-client- A plataforma encaminha cada cabeçalho que começa com x-client- inalterado, para que você possa enviar valores como uma ID de locatário ou um sinalizador de recurso sem alterar o corpo da solicitação e, em seguida, lê-los em seu manipulador como qualquer outro cabeçalho de solicitação. O SDK do AgentServer define esse prefixo comoPlatformHeaders.ClientHeaderPrefix; para a lista completa de cabeçalhos de plataforma, consulte a referência de biblioteca do Azure AI Agent Server Core.

O gateway encaminha esses cabeçalhos de chamador para os pontos de extremidade do protocolo Respostas e Invocações:

O gateway nunca encaminha cabeçalhos de credencial, como Authorization, ou Host, Cookiee x-forwarded-*. Qualquer cabeçalho que não corresponda à lista de permissões é descartado, portanto, não dependa de cabeçalhos personalizados fora do x-client-* prefixo atingindo o contêiner.

Conteúdo relacionado

• O que são agentes hospedados?
• Ciclo de vida de desenvolvimento do agente
• Exemplos de agentes hospedados em Python