Hospedar agentes de Microsoft Agent Framework como agentes hospedados en Foundry

Use los paquetes de hospedaje de Microsoft Agent Framework para exponer un agente de Agent Framework a través de los protocolos de los agentes hospedados en Foundry. Los paquetes de hospedaje le permiten mantener la lógica del agente en el código mientras Foundry administra el tiempo de ejecución hospedado, las sesiones, la escala, la identidad y los puntos de conexión de protocolo.

En este artículo, creará un agente de Agent Framework mínimo, lo expondrá a través del protocolo Respuestas o Invocaciones, lo probará a través de HTTP e lo implementará en Foundry con la CLI del desarrollador de Azure.

La Microsoft Foundry Skill ayuda a implementar el adaptador, probar los protocolos y desplegar con azd.

Prerequisites

• Una suscripción a Azure. Crear uno gratis.
• Un proyecto de Foundry.
• Un modelo de chat implementado, como gpt-4.1 o gpt-4o.
• El rol Gestor de proyectos de Foundry en el proyecto para implementar un agente hospedado. Para obtener más información, consulte Implementación de un agente hospedado.
• CLI de Azure ha iniciado sesión (az login) para que DefaultAzureCredential pueda autenticarse.

Instalación de los paquetes

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

Elección de un protocolo de hospedaje

Los agentes hospedados pueden exponer uno o varios protocolos. Empiece con Responses para la mayoría de los agentes conversacionales.

Para obtener información general sobre el comportamiento y las sesiones del protocolo, consulte Agentes hospedados y Administración de sesiones de agentes hospedados.

Configuración de las variables de entorno

Establezca el punto de conexión del proyecto y el nombre de implementación del modelo para el desarrollo local:

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

En PowerShell:

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

Cuando el mismo código se ejecuta como un agente hospedado en Foundry, la plataforma inserta FOUNDRY_PROJECT_ENDPOINT y AZURE_AI_MODEL_DEPLOYMENT_NAME en tiempo de ejecución.

Protocolo de respuestas

Utilice el protocolo Responses cuando quiera un endpoint de chat compatible con OpenAI con streaming, historial de respuestas e hilos de conversación.

Creación de un host de respuestas

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

Probar el endpoint Responses

Envíe una solicitud de respuestas que no sea de streaming al 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"

El servidor responde con un objeto JSON que contiene el texto de respuesta y un identificador de respuesta. Para las respuestas en streaming, establezca stream en true. El host emite eventos enviados por el servidor de la API de respuestas, como response.created, response.output_text.deltay response.completed.

Conversaciones de múltiples turnos

Para continuar una conversación, pase el identificador de respuesta anterior en el previous_response_id campo de la siguiente solicitud:

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

Cuando el agente se ejecuta en Foundry, el mismo patrón funciona a través del punto de conexión Respuestas del agente hospedado. Si los turnos posteriores también necesitan el mismo sistema de archivos del entorno aislado hospedado, incluya agent_session_id o use un Id. conversation. Para más información, consulte Administración de sesiones de agente hospedadas.

Protocolo de invocaciones

Utilice el protocolo de invocaciones cuando quienes realizan las llamadas no puedan usar el formato de solicitud de la API Responses o cuando su caso de uso no sea una conversación de chat. El host de Invocations gestiona el estado de la sesión a través de un parámetro de consulta agent_session_id y un encabezado de respuesta.

Creación de un host de invocaciones

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

Probar el punto de conexión Invocations

Envíe una solicitud al servidor local:

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

Para conversaciones de varios turnos, reutiliza el valor agent_session_id del encabezado de la respuesta como parámetro de consulta agent_session_id en la siguiente solicitud:

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

La plataforma no almacena el historial de conversaciones para el protocolo invocaciones. Utiliza el parámetro de consulta agent_session_id para redirigir las llamadas posteriores al mismo entorno de pruebas hospedado.

Deploy

Implemente mediante la CLI para desarrolladores de Azure (azd). El flujo usa manifiestos de ejemplo y Docker para compilar la imagen de contenedor del agente e implementarla en el entorno de ejecución del agente hospedado de Foundry.

El despliegue del agente alojado requiere el rol Foundry Project Manager en el proyecto. Para obtener más información, consulte Implementación de un agente hospedado.

Instalación de la extensión de la CLI para desarrolladores de Azure

Instale la extensión del agente de IA e inicie sesión antes de inicializar un ejemplo:

azd ext install azure.ai.agents
azd auth login

Docker debe ejecutarse localmente porque azd ai agent run compila la imagen de contenedor declarada en el Dockerfile del ejemplo. Para obtener más información sobre los comandos, consulte la referencia de la CLI para desarrolladores de Azure.

Inicializar a partir de un manifiesto de ejemplo

Cree una nueva carpeta e inicialícela a partir de un manifiesto de ejemplo. Reemplace la dirección URL del manifiesto por el ejemplo que desea 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 las indicaciones de azd ai agent init. Si aún no tiene un proyecto y una implementación de modelos de Foundry, el flujo de inicialización puede guiarle a través de su creación.

Aprovisionamiento de los recursos de Azure

Si el proyecto inicializado usa un nuevo proyecto y una implementación de modelos de Foundry, aprovisione primero los recursos Azure:

azd provision

Este comando crea un grupo de recursos que contiene, entre otros recursos, una instancia de Foundry, un proyecto Foundry con una implementación de modelo, una instancia de Application Insights y un registro de contenedor para las imágenes del agente hospedado.

Ejecute el contenedor localmente

Ejecute el host del agente localmente a través de azd:

azd ai agent run

El host sirve en http://localhost:8088. En otro terminal, invoque el punto de conexión del protocolo local:

azd ai agent invoke --local "Hello!"

También puede llamar al punto de conexión directamente con curl:

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

Implementar en Foundry

Despliegue el agente:

azd deploy

La implementación empaqueta el agente en una imagen de contenedor, la inserta en el registro de contenedor aprovisionado y la implementa en el entorno de ejecución del agente hospedado de Foundry.

La infraestructura de hospedaje de Foundry inserta variables de entorno en tiempo de ejecución en el agente, entre las que se incluyen:

• FOUNDRY_PROJECT_ENDPOINT: la dirección URL del punto de conexión del proyecto Foundry donde se implementa el agente.
• AZURE_AI_MODEL_DEPLOYMENT_NAME: nombre de implementación del modelo seleccionado durante azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: La cadena de conexión de la instancia de Application Insights del proyecto.

Para obtener información completa sobre los conceptos de implementación, los permisos y la administración, consulte Implementación de un agente hospedado y Administración del ciclo de vida del agente hospedado.

Troubleshooting

Use esta lista de comprobación para diagnosticar problemas comunes al desarrollar agentes hospedados con Agent Framework.

No se puede acceder al modelo en el contenedor hospedado

Confirme que la versión del agente hospedado incluye AZURE_AI_MODEL_DEPLOYMENT_NAMEy que la identidad del agente tiene permiso para llamar al proyecto Foundry. La plataforma establece FOUNDRY_PROJECT_ENDPOINT; el código debe leer esa variable al ejecutarse en Foundry.

El estado de la conversación no continúa

Para el protocolo Responses, pase previous_response_id o un Id. de conversation en los turnos posteriores.

En el caso del protocolo Invocaciones, la plataforma no almacena el historial de conversaciones. Utiliza un parámetro de consulta agent_session_id para dirigir las llamadas posteriores al mismo entorno de pruebas alojado.

Error de coincidencia de la versión del protocolo

Si se produce un error en las solicitudes después de una actualización, confirme que el manifiesto y el paquete de hospedaje usan la versión 2.0.0 del protocolo. Las versiones de protocolo 1.0.0 y 2.0.0 son incompatibles.

Paso siguiente

Contenido relacionado

• ¿Qué es Foundry Agent Service?
• Agentes alojados
• Administración de sesiones del agente hospedado
• Hospedar agentes de LangGraph como agentes hospedados en Foundry