Hospedar agentes do Microsoft Agent Framework como agentes hospedados pela Foundry

Use os pacotes de hospedagem do Microsoft Agent Framework para expor um agente do Agent Framework por meio dos protocolos para agentes hospedados no Foundry. Os pacotes de hospedagem permitem que você mantenha a lógica do agente no código, enquanto o Foundry gerencia o ambiente de execução hospedado, as sessões, a escalabilidade, a identidade e os endpoints de protocolo.

Neste artigo, você cria um agente mínimo do Agent Framework, expõe-o por meio do protocolo Respostas ou Invocações, testa-o por meio de HTTP e o implanta no Foundry com a CLI do desenvolvedor do Azure.

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

Pré-requisitos

• Uma assinatura do Azure. Criar um gratuitamente.
• Um projeto do Foundry.
• Um modelo de chat implantado, como gpt-4.1 ou gpt-4o.
• A função de Gerente de Projeto do Foundry no projeto para implantar um agente hospedado. Para obter detalhes, consulte Implantar um agente hospedado.
• CLI do Azure está conectado (az login) para que DefaultAzureCredential possa autenticar-se.

Instalar os pacotes

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

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

dotnet add package Azure.AI.AgentServer.Invocations

Escolher um protocolo de hospedagem

Os agentes hospedados podem expor um ou mais protocolos. Comece com respostas para a maioria dos agentes de conversação.

Para obter informações sobre o comportamento do protocolo e sessões, consulte Os agentes hospedados e gerencie sessões de agente hospedado.

Configurar variáveis de ambiente

Defina o ponto de extremidade do projeto e o nome de implantaçã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 é executado como um agente hospedado no Foundry, a plataforma injeta FOUNDRY_PROJECT_ENDPOINT e AZURE_AI_MODEL_DEPLOYMENT_NAME em runtime.

Protocolo de respostas

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

Criar um host de respostas

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()

python main.py

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

dotnet run

Testar o ponto de extremidade de respostas

Envie uma solicitação de respostas 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 uma ID de resposta. Para respostas de streaming, defina stream como true. O host emite eventos enviados pelo servidor da API de Respostas, como response.created, response.output_text.deltae response.completed.

Conversas em múltiplos turnos

Para continuar uma conversa, passe a ID de resposta anterior no previous_response_id campo da próxima solicitação:

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 por meio do ponto de extremidade de respostas do agente hospedado. Se turnos posteriores também precisarem do mesmo sistema de arquivos do sandbox hospedado, inclua agent_session_id ou use um ID conversation. Para obter detalhes, consulte Gerenciar sessões de agente hospedado.

Protocolo de invocações

Use o protocolo Invocations quando quem faz as chamadas não puder usar o formato de solicitação da API Responses ou quando seu cenário não for uma conversa. O host do Invocations gerencia o estado da sessão por meio de um parâmetro de consulta agent_session_id e de um cabeçalho de resposta.

Criar um host de invocações

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()

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

Testar o ponto de extremidade de invocações

Envie uma solicitação 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 vários turnos, reutilize o valor agent_session_id do cabeçalho da resposta como o parâmetro de consulta agent_session_id na solicitação 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 para o protocolo Invocations. Use o parâmetro de consulta agent_session_id para direcionar chamadas seguintes para o mesmo sandbox hospedado.

Implantar

Implante usando a CLI do Desenvolvedor do Azure (azd). O fluxo usa manifestos de exemplo e Docker para criar a imagem de contêiner do agente e distribuí-la para o runtime do agente hospedado do Foundry.

A implantação do agente hospedado requer a função Foundry Project Manager no projeto. Para obter detalhes, consulte Implantar um agente hospedado.

Instalar a extensão Azure Developer CLI

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

azd ext install azure.ai.agents
azd auth login

O Docker deve estar em execução localmente porque azd ai agent run cria a imagem de contêiner declarada no Dockerfile do exemplo. Para obter detalhes do comando, consulte a referência da CLI do desenvolvedor Azure.

Inicializar a partir de um manifesto de exemplo

Crie uma nova pasta e inicialize-a a partir de um manifesto de exemplo. Substitua a URL do manifesto pelo exemplo que você deseja 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 você ainda não tiver um projeto do Foundry e uma implantação de modelo, o fluxo de inicialização poderá guiá-lo durante a criação deles.

Provisionar recursos do Azure

Se o projeto inicializado usar um novo projeto do Foundry e uma implantação de modelo, provisione os recursos de Azure primeiro:

azd provision

Esse comando cria um grupo de recursos que contém, entre outros recursos, uma instância do Foundry, um projeto foundry com uma implantação de modelo, uma instância do Application Insights e um registro de contêiner para as imagens do agente hospedado.

Executar o contêiner localmente

Execute o host do agente localmente por meio de azd:

azd ai agent run

O host serve em http://localhost:8088. Em outro terminal, invoque o ponto de extremidade do protocolo local:

azd ai agent invoke --local "Hello!"

Você também pode invocar o endpoint diretamente com curl:

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

Implantar no Foundry

Implante o agente:

azd deploy

A implantação empacota o agente em uma imagem de contêiner, faz push dela para o registro de contêiner provisionado e a implanta no runtime do agente hospedado do Foundry.

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

• FOUNDRY_PROJECT_ENDPOINT: A URL do endpoint do projeto do Foundry no qual o agente está implantado.
• AZURE_AI_MODEL_DEPLOYMENT_NAME: o nome da implantação do modelo selecionado durante azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: a cadeia de conexão da instância do Application Insights do projeto.

Para obter conceitos completos de implantação, permissões e detalhes de gerenciamento, consulte Implantar um agente hospedado e gerenciar o ciclo de vida do agente hospedado.

Troubleshooting

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

O modelo não pode ser acessado no contêiner hospedado

Confirme se a versão do agente hospedado inclui AZURE_AI_MODEL_DEPLOYMENT_NAME e se a identidade do agente tem permissão para acessar o projeto Foundry. A plataforma define FOUNDRY_PROJECT_ENDPOINT; seu código deve ler essa variável quando for executado no Foundry.

O estado da conversa não continua

Para o protocolo Responses, passe previous_response_id ou um ID conversation nos turnos seguintes.

Para o protocolo Invocações, a plataforma não armazena o histórico de conversas. Use um parâmetro de consulta agent_session_id para direcionar chamadas subsequentes ao mesmo sandbox hospedado.

Incompatibilidade de versão do protocolo

Se as solicitações falharem após uma atualização, confirme se o manifesto e o pacote de hospedagem usam o protocolo versão 2.0.0. As versões de protocolo 1.0.0 e 2.0.0 são incompatíveis.

Próxima etapa

Conteúdo relacionado

• O que é o Serviço do Foundry Agent?
• Agentes hospedados
• Gerenciar sessões de agente hospedado
• Hospede agentes do LangGraph como agentes hospedados no Foundry