Hospedar agentes do Microsoft Agent Framework como agentes alojados no Foundry

Utilize os pacotes de alojamento do Microsoft Agent Framework para expor um agente do Agent Framework através dos protocolos dos agentes alojados no Foundry. Os pacotes de alojamento permitem-lhe manter a lógica do agente no código, enquanto o Foundry gere o ambiente de execução alojado, as sessões, a escalabilidade, a identidade e os pontos finais de protocolo.

Neste artigo, cria um agente mínimo do Agent Framework, expõe-o através do protocolo Responses ou Invocations, testa-o através de HTTP e implementa-o no Foundry com a CLI do Azure Developer.

O Microsoft Foundry Skill pode ajudar a implementar o adaptador, testar os protocolos e implementar com azd.

Pré-requisitos

• Uma assinatura do Azure. Crie um gratuitamente.
• Um projeto da Foundry.
• Um modelo de chat implementado, como gpt-4.1 ou gpt-4o.
• A função de Gestor de Projeto do Foundry no projeto de implementação de um agente alojado. Para mais detalhes, consulte Implementar um agente hospedado.
• CLI do Azure logado (az login) para que DefaultAzureCredential possa autenticar.

• Python 3.10 ou posterior.

• .NET 10 SDK ou posterior.

Instale os pacotes

Instale o Agent Framework e o pacote de alojamento Foundry:

pip install -U agent-framework agent-framework-foundry-hosting azure-identity python-dotenv

O agent_framework_foundry_hosting pacote fornece os servidores anfitriões para os protocolos Foundry:

• ResponsesHostServer para o endpoint /responses compatível com OpenAI.
• InvocationsHostServer para o endpoint genérico /invocations.

Adicione o Agent Framework e os pacotes de alojamento Foundry ao seu projeto:

dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.Foundry.Hosting
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

Para o protocolo Invocations, adicione também o pacote servidor Invocations:

dotnet add package Azure.AI.AgentServer.Invocations

Estes pacotes fornecem as extensões host para os protocolos Foundry:

• AddFoundryResponses e MapFoundryResponses para o endpoint /responses compatível com OpenAI.
• AddInvocationsServer e MapInvocationsServer para o endpoint genérico /invocations.

Escolha um protocolo de alojamento

Agentes alojados podem expor um ou mais protocolos. Comece pelas Respostas para a maioria dos agentes conversacionais.

Protocolo	Endpoint	Utilizar quando
Responses	/responses	Pretende chat, streaming, histórico de respostas e encadeamento de conversas compatíveis com a OpenAI.
Invocações	/invocations	Queres uma forma JSON personalizada, um endpoint ao estilo webhook ou processamento não conversacional.

Para obter contexto sobre o comportamento do protocolo e as sessões, consulte Agentes alojados e Gerir sessões de agentes alojados.

Configurar variáveis de ambiente

Defina o endpoint do projeto e o nome de implementação do modelo para desenvolvimento local:

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

No PowerShell:

$env:FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

Quando o mesmo código corre como agente alojado no Foundry, a plataforma injeta FOUNDRY_PROJECT_ENDPOINT e AZURE_AI_MODEL_DEPLOYMENT_NAME em tempo de execução.

Protocolo de Respostas

Utilize o protocolo Responses quando quiser um endpoint de chat compatível com a OpenAI, com streaming, histórico de respostas e encadeamento de conversas.

Crie um anfitrião de Respostas

Crie um ficheiro com o nome main.py que contenha um agente mínimo do Agent Framework que utilize um modelo Foundry.

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
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    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.",
        # The hosting infrastructure manages conversation history, so the
        # service doesn't need to store it.
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

O que este excerto faz: Cria um agente Agent Framework suportado por um modelo Foundry através FoundryChatClientde , e depois passa o agente para ResponsesHostServer. O host inicia um servidor HTTP e expõe o agente através de POST /responses. Por defeito, o servidor associa-se à porta 8088.

Referência: Documentação do Microsoft Agent Framework

Executa a aplicação localmente:

python main.py

Crie um Program.cs ficheiro com um agente mínimo do Agent Framework que utilize um modelo Foundry através do protocolo Responses.

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

// Create the agent via the AI project client using the Responses API.
AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a friendly assistant. Keep your answers brief.",
        name: "assistant",
        description: "A simple general-purpose AI assistant");

// Host the agent as a Foundry hosted agent using the Responses API.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);

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

O que este excerto faz: Cria um AIAgent a partir do cliente do projeto Foundry, regista-o como um host Foundry Responses com AddFoundryResponses, e mapeia o POST /responses endpoint com MapFoundryResponses. Por defeito, o host serve na porta 8088.

Referência: AIProjectClient | DefaultAzureCredential

Executa a aplicação localmente:

dotnet run

Teste o endpoint Respostas

Envie um pedido Responses sem streaming para o servidor local.

Bash:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Give me one practical tip for testing hosted agents.","stream":false}'

PowerShell::

$body = @{
  input  = "Give me one practical tip for testing hosted agents."
  stream = $false
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri http://localhost:8088/responses `
    -Method Post `
    -Body $body `
    -ContentType "application/json"

O servidor responde com um objeto JSON que contém o texto de resposta e um ID de resposta. Para respostas de streaming, defina stream para true. O host emite eventos enviados pelo servidor da API de Respostas, como response.created, response.output_text.delta, e response.completed.

Conversas em vários turnos

Para continuar uma conversa, passe o ID de resposta anterior no previous_response_id campo do próximo pedido:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Can you make that more concise?","previous_response_id":"<previous-response-id>","stream":false}'

Quando o agente é executado no Foundry, o mesmo padrão funciona através do endpoint Response do agente hospedado. Se turnos posteriores também precisarem do mesmo sistema de ficheiros sandbox alojado, inclua agent_session_id ou use um conversation ID. Para mais detalhes, consulte Gerir sessões de agentes alojados.

Protocolo de invocações

Utilize o protocolo Invocations quando os autores das suas chamadas não puderem usar o formato de pedido da API Responses ou quando o seu cenário não for uma conversa em chat. O host Invocations gere o estado da sessão através de um agent_session_id parâmetro de consulta e um cabeçalho de resposta.

Criar um host de Invocações

Use a mesma configuração de agente do exemplo de Respostas, mas comece InvocationsHostServer em vez de ResponsesHostServer.

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
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    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()


if __name__ == "__main__":
    main()

O que este excerto faz: Hospeda o agente do Agent Framework através POST /invocationsde . O host gere o estado por sessão através do agent_session_id parâmetro de consulta e do cabeçalho de resposta.

Referência: Documentação do Microsoft Agent Framework

O protocolo Invocations usa um InvocationHandler que implementas para processar cada pedido. Regista o servidor de Invocações e o teu handler, depois mapeia os endpoints.

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

var builder = WebApplication.CreateBuilder(args);

// Register your agent and the Invocations server services.
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

var app = builder.Build();

// Map the Invocations protocol endpoints:
//   POST /invocations              - invoke the agent
//   GET  /invocations/{id}         - get result
//   POST /invocations/{id}/cancel  - cancel
app.MapInvocationsServer();
app.Run();

O que este excerto faz: Regista os serviços do servidor Invocations e a sua InvocationHandler implementação, depois mapeia os /invocations endpoints. Implementas MyInvocationHandler para definir como cada pedido é processado. Para um exemplo completo de handler, veja o exemplo .NET Invocations.

Referência: AddInvocationsServer

Teste o endpoint de Invocations

Envie um pedido para o servidor local:

curl -sS -X POST http://localhost:8088/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"My name is Alice.","stream":false}'

Para conversas com múltiplas interações, reutilize o valor agent_session_id do cabeçalho de resposta como parâmetro de consulta agent_session_id no pedido seguinte:

curl -sS -X POST "http://localhost:8088/invocations?agent_session_id=<session-id>" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is my name?"}'

A plataforma não armazena o histórico de conversas do protocolo Invocations. Use o agent_session_id parâmetro de consulta para encaminhar chamadas posteriores para o mesmo sandbox alojado.

Desplegar

Implemente usando a CLI do Azure Developer (azd). O fluxo utiliza manifestos de amostra e Docker para construir a imagem do contentor do agente e implementá-la no runtime do agente hospedado no Foundry.

A implementação de agentes alojados requer a função de Foundry Project Manager no projeto. Para mais detalhes, consulte Implementar um agente hospedado.

Instalar a extensão Azure Developer CLI

Instale a extensão do agente de IA e inicie sessão antes de inicializar um exemplo:

azd ext install azure.ai.agents
azd auth login

O Docker deve estar a correr localmente porque azd ai agent run constrói a imagem do contentor declarada no Dockerfile da amostra. Para detalhes dos comandos, consulte a referência Azure Developer CLI .

Inicializar a partir de um manifesto de exemplo

Cria uma nova pasta e inicializa-a a partir de um manifesto de exemplo. Substitua o URL do manifesto pelo exemplo que quer usar.

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/python/samples/04-hosting/foundry-hosted-agents/responses/01_basic/agent.manifest.yaml

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/agent.manifest.yaml

Siga as instruções de azd ai agent init. Se ainda não tiver um projeto e implementação de modelos no Foundry, o fluxo de inicialização pode guiá-lo na sua criação.

Provisionar recursos do Azure

Se o projeto inicializado usar um novo projeto Foundry e implementação de modelos, provisione primeiro os recursos Azure:

azd provision

Este comando cria um grupo de recursos que contém, entre outros recursos, uma instância Foundry, um projeto Foundry com uma implementação de modelo, uma instância Application Insights e um registo de contentores para as imagens do agente alojado.

Executar um contêiner localmente

Execute localmente o host do agente através de azd:

azd ai agent run

O host é executado em http://localhost:8088. Noutro terminal, invoque o endpoint local do protocolo:

azd ai agent invoke --local "Hello!"

Também pode chamar diretamente o endpoint com curl:

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

Deslocação para a Fundição

Instalar o agente:

azd deploy

A implantação empacota o agente numa imagem de contentor, envia-a para o registo de contentores aprovisionado e implementa-a no ambiente de execução do agente alojado no Foundry.

A infraestrutura de alojamento da Foundry injeta variáveis do ambiente de runtime no agente, incluindo:

• FOUNDRY_PROJECT_ENDPOINT: O URL do endpoint do projeto Foundry onde o agente está alojado.
• AZURE_AI_MODEL_DEPLOYMENT_NAME: O nome de implementação do modelo selecionado durante azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: A cadeia de ligação da instância do Application Insights do projeto.

Para conceitos completos de implementação, permissões e detalhes de gestão, consulte Implementar um agente hospedado e Gerir o ciclo de vida do agente hospedado.

Solução de problemas

Use esta lista de verificação para diagnosticar problemas comuns ao desenvolver agentes hospedados com o Agent Framework.

O modelo não pode ser alcançado no contentor alojado

Confirme que a versão do agente alojado inclui AZURE_AI_MODEL_DEPLOYMENT_NAME, e que a identidade do agente tem permissão para aceder ao projeto Foundry. A plataforma define FOUNDRY_PROJECT_ENDPOINT; o teu código deve ler essa variável ao correr no Foundry.

O estado de conversa não continua

Para o protocolo Responses, forneça previous_response_id ou um ID de conversation em interações posteriores.

No protocolo Invocations, a plataforma não armazena o histórico de conversas. Use um agent_session_id parâmetro de consulta para encaminhar chamadas posteriores para o mesmo sandbox alojado.

Incompatibilidade da versão do protocolo

Se os pedidos falharem após uma atualização, confirme que o seu manifesto e o pacote de alojamento usam ambos a versão 2.0.0 do protocolo. As versões dos protocolos 1.0.0 e 2.0.0 são incompatíveis.

Passo seguinte

Implementar um agente alojado

Conteúdo relacionado

• O que é o Foundry Agent Service?
• Agentes alojados
• Gerir sessões de agentes alojadas
• Aloje agentes LangGraph como agentes alojados no Foundry