Agentes hospedados da Foundry

os agentes Hosted no Microsoft Foundry Agent Service permitem implantar agentes do Agent Framework como aplicativos em contêineres para infraestrutura gerenciada por Microsoft. A plataforma lida com dimensionamento, persistência de estado de sessão, segurança e gerenciamento de ciclo de vida para que você possa se concentrar na lógica do agente. Agentes Hospedados do Microsoft Foundry estão em disponibilidade geral.

Com a integração de hospedagem do Agent Framework, você pode expor um Agent, incluindo um fluxo de trabalho encapsulado com Workflow.as_agent(), por meio do protocolo Foundry Responses ou Invocations com um mínimo de código.

Quando usar agentes hospedados

Escolha os agentes hospedados do Foundry quando quiser.

  • Infraestrutura gerenciada – não é necessário configurar contêineres, servidores Web ou regras de dimensionamento por conta própria.
  • Gerenciamento de sessão integrado — a plataforma persiste $HOME e os arquivos enviados entre turnos e períodos de inatividade.
  • Identidade do agente dedicado – cada agente implantado obtém sua própria identidade de Entra para acesso seguro a modelos, ferramentas e serviços downstream.
  • Endpoints compatíveis com OpenAI – os clientes podem interagir com seu agente usando qualquer SDK compatível com OpenAI através do protocolo Responses.

Note

A integração com agent-framework-foundry-hosting Python está em versão preliminar. Microsoft Foundry Hosted Agents, o serviço de hospedagem gerenciada, está disponível em geral.

Prerequisites

Para testes locais, você também precisa:

Instale o pacote NuGet de hospedagem:

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
dotnet add package Azure.AI.Projects --prerelease
  • Python 3.10 ou posterior

Instale o pacote de hospedagem de pré-lançamento, o cliente Foundry e o pacote de autenticação do Azure:

pip install --pre agent-framework-foundry agent-framework-foundry-hosting azure-identity

No Foundry, a plataforma fornece o contexto de usuário do chamador e o contexto de chamada; a infraestrutura de hospedagem os usa para isolar o estado por usuário e encaminhar o contexto de solicitação para os serviços do Foundry. As execuções locais não recebem esse contexto de plataforma, portanto, os aplicativos devem fornecer sua própria identidade e controles de estado quando necessário.

Protocolo de respostas

O protocolo Respostas é o ponto de partida recomendado para a maioria dos agentes. Ela expõe um ponto de extremidade/responses compatível com OpenAI e a plataforma gerencia o histórico de conversas, streaming e ciclo de vida da sessão automaticamente.

using Azure.AI.AgentServer.Core;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));
var deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";

AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a helpful AI assistant.",
        name: "my-agent");

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

var app = builder.Build();
app.Run();

O AgentHost.CreateBuilder cria um host de aplicativo pré-configurado para o ambiente de hospedagem do Foundry. AddFoundryResponses registra seu agente com o manipulador de protocolo Responses e MapFoundryResponses mapeia o /responses endpoint HTTP.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a helpful AI assistant.",
)

server = ResponsesHostServer(agent)
server.run()

O ResponsesHostServer encapsula seu agente e o expõe por meio do protocolo Foundry Responses. Para um agente sem fluxo de trabalho, por padrão, history_source="agent_server" usa o provedor de resposta do Agent Server configurado como fonte do histórico do modelo. O host impede que o serviço de modelo downstream mantenha uma segunda cópia quando o cliente armazena o histórico por padrão.

Não combine a fonte de histórico padrão com uma HistoryProvider que tenha load_messages=True. Além disso, não defina as opções conversation_id, conversation ou previous_response_id de continuação do serviço downstream. O host rejeita essas configurações para impedir o histórico duplicado.

Use ResponsesHostServer(agent, history_source="agent") quando o provedor de histórico do agente ou o serviço de modelo downstream precisar gerenciar o histórico de conversas. Esse modo passa apenas a entrada de solicitação atual do Servidor do Agente e preserva o histórico do agente e o comportamento de armazenamento do serviço. Implementações personalizadas SupportsAgentRun devem usar esse modo. O parâmetro store permanece separado: ele seleciona o provedor de respostas que armazena de forma persistente as entradas e saídas da API de Respostas em ambos os modos.

O host é proprietário do agente fornecido e pode adicionar provedores de contexto específicos de hospedagem. Não reutilize o agente com outro host ou invoque-o diretamente após a construção do host.

Manter o estado e lidar com conversas de longa execução

ResponsesHostServer configura repositórios com suporte do Foundry por padrão. Para agentes sem fluxo de trabalho, AgentSessionStoreProvider fornece um FoundryAgentSessionStore. Para agentes de fluxo de trabalho, CheckpointStoreProvider fornece um FoundryCheckpointStore. FunctionApprovalStoreProvider fornece um FoundryFunctionApprovalStore para aprovações pendentes. Esses armazenamentos utilizam o Foundry State Store quando hospedados e o estado do Agent Server local quando executados localmente.

Com history_source="agent", o repositório de sessão configurado persiste o estado do provedor transportado por AgentSession, incluindo mensagens de InMemoryHistoryProvider.

Para personalizar o armazenamento, passe um StoreProvider para agent_session_store_provider ou function_approval_store_provider. Passe um ContextScopedStoreProvider para checkpoint_store_provider. Por exemplo, implemente SessionStore e StoreProvider[SessionStore] para usar seu próprio armazenamento de sessão de agente que não seja de workflow.

Importe ResponsesServerOptions de azure.ai.agentserver.responses e passe-o para options por meio do parâmetro ResponsesHostServer. As opções disponíveis de conversa de longa duração dependem do tipo de agente:

Capacidade Tipo de agente Requisitos e comportamento
Respostas resilientes em segundo plano Somente fluxo de trabalho Defina ResponsesServerOptions(resilient_background=True). Enviar a solicitação respostas com store=true e background=true. Após uma reinicialização, o host retomará o ponto de verificação de fluxo de trabalho durável mais recente ou repetirá a entrada original se nenhum ponto de verificação existir. Não configure o armazenamento de ponto de verificação no fluxo de trabalho, pois o host o gerencia. Torne os efeitos colaterais externos idempotentes porque o trabalho após o último ponto de verificação durável pode se repetir.
Conversas direcionáveis Apenas itens fora de fluxo de trabalho Definir ResponsesServerOptions(steerable_conversations=True) e enviar solicitações de respostas com store=true. Mantenha as curvas em uma única cadeia linear reutilizando o mesmo valor conversation. Como alternativa, envie o previous_response_id imediatamente anterior e preserve o agent_session_id resolvido. O host rejeita predecessores obsoletos que criariam uma bifurcação.

ResponsesHostServer gera RuntimeError se você habilitar respostas em segundo plano resilientes para um agente sem fluxo de trabalho ou conversas direcionáveis ​​para um agente com fluxo de trabalho. Para implementações completas, consulte o armazenamento personalizado, o fluxo de trabalho de execução longa resiliente e os exemplos de agente de execução longa direcionável .

Quando uma ferramenta MCP hospedada pela Foundry requer consentimento do usuário, ResponsesHostServer retorna uma resposta incompleta com um oauth_consent_request item de saída. Apresente seu consent_link ao usuário e, em seguida, continue com a ID da resposta incompleta como previous_response_id depois que o usuário fornecer seu consentimento. O host preserva a sessão do agente para essa repetição e expõe apenas links de consentimento HTTPS absolutos.

Protocolo de invocações

O protocolo Invocações fornece controle total sobre a solicitação HTTP e a resposta. Use-o quando precisar de cargas personalizadas, processamento não conversacional ou protocolos de streaming que não sejam compatíveis com OpenAI.

Com o protocolo Invocações em C#, você implementa uma classe personalizada InvocationHandler para processar solicitações de entrada:

using Azure.AI.AgentServer.Core;
using Azure.AI.AgentServer.Invocations;
using Microsoft.Agents.AI;

var builder = AgentHost.CreateBuilder(args);

builder.Services.AddSingleton<AIAgent, MyAgent>();
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

builder.RegisterProtocol("invocations", endpoints => endpoints.MapInvocationsServer());

var app = builder.Build();
app.Run();

O método AddInvocationsServer registra os serviços do Protocolo de Invocações. Você implementa InvocationHandler para definir como seu agente processa cada solicitação.

Para uma configuração leve, use InvocationsHostServer do pacote agent_framework_foundry_hosting. Ele encapsula seu agente da mesma forma ResponsesHostServer e manipula o gerenciamento de sessão automaticamente:

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import InvocationsHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

server = InvocationsHostServer(agent)
server.run()

Para obter controle total sobre o tratamento de solicitações, use InvocationAgentServerHost diretamente do azure.ai.agentserver.invocations pacote e implemente seu próprio manipulador de invocação:

import os
from collections.abc import AsyncGenerator

from agent_framework import Agent, AgentSession
from agent_framework.foundry import FoundryChatClient
from azure.ai.agentserver.invocations import InvocationAgentServerHost
from azure.identity import DefaultAzureCredential
from starlette.requests import Request
from starlette.responses import JSONResponse, Response, StreamingResponse

_sessions: dict[str, AgentSession] = {}

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    """Handle streaming multi-turn chat."""
    data = await request.json()
    session_id = request.state.session_id
    stream = data.get("stream", False)
    user_message = data.get("message", None)

    if user_message is None:
        return Response(content="Missing 'message' in request", status_code=400)

    session = _sessions.setdefault(session_id, AgentSession(session_id=session_id))

    if stream:

        async def stream_response() -> AsyncGenerator[str]:
            async for update in agent.run(user_message, session=session, stream=True):
                yield update.text

        return StreamingResponse(
            stream_response(),
            media_type="text/event-stream",
            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
        )

    response = await agent.run([user_message], session=session, stream=stream)
    return JSONResponse({"response": response.text})


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

Aviso

O repositório de sessão na memória no exemplo do manipulador personalizado é perdido na reinicialização. Use o armazenamento durável (por exemplo, Cosmos DB) em produção.

Para obter uma implantação completa de Invocações, consulte o exemplo do Telegram hospedado pela Foundry. Posiciona o API Management à frente do webhook do agente hospedado e usa identidades gerenciadas, Key Vault e Cosmos DB para um histórico de conversas persistente.

Note

O suporte do Go para agentes hospedados no Foundry estará disponível em breve. Consulte o repositório Agent Framework Go para obter o status mais recente.

Tip

Consulte os exemplos Python ou os exemplos C# para obter exemplos de um projeto de agente hospedado. Ou use o azd ai agent init comando para estruturar um novo projeto de agente hospedado do zero. Consulte este guia de início rápido para obter instruções passo a passo.

Execução local

A CLI do desenvolvedor Azure (azd) fornece a maneira mais fácil de executar e testar seu agente hospedado localmente.

Inicializar um projeto

Crie uma nova pasta e inicialize a partir de um manifesto de exemplo:

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -m <path-to-agent.manifest.yaml>

Tip

O manifesto pode ser um caminho para um arquivo YAML local ou uma URL para um manifesto remoto.

Definir variáveis de ambiente

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="<your-model-deployment>"

Executar o host do agente

azd ai agent run

O host do agente é iniciado em http://localhost:8088.

Invocar o agente

azd ai agent invoke --local "Hello!"

Ou use curl:

curl -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello!"}'

Ou no PowerShell:

(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Hello!"}').Content

Implantando na Foundry

Depois de verificar o agente localmente, implante-o no Microsoft Foundry:

  1. Provisionar recursos (se você ainda não tiver um projeto do Foundry):

    azd provision

    Isso cria um grupo de recursos com uma instância do Foundry, um projeto, uma implantação de modelo, o Application Insights e um registro de contêiner.

  2. Implante o agente:

    azd deploy

    Isso empacota seu agente como uma imagem de contêiner, envia-o por push para Registro de Contêiner do Azure e o implanta no Serviço do Foundry Agent.

A infraestrutura de hospedagem do Foundry injeta automaticamente as seguintes variáveis de ambiente no contêiner do agente em runtime:

Variable Description
FOUNDRY_PROJECT_ENDPOINT URL do endpoint do projeto Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME O nome do modelo de implantação (configurado durante azd ai agent init).
APPLICATIONINSIGHTS_CONNECTION_STRING A cadeia de conexão do Application Insights para telemetria.

Após a implantação, seu agente fica acessível por meio de seu ponto de extremidade do Foundry dedicado e também pode ser testado no portal do Foundry.

Próximas Etapas 

Conceitos de agentes hospedados

  • Last updated on