Migración de agentes hospedados a la versión preliminar pública actualizada

Este artículo le guía a través de la migración de agentes hospedados desde la versión preliminar pública inicial a la versión preliminar pública actualizada del servicio Foundry Agent. La versión preliminar actualizada presenta un nuevo back-end de hospedaje, bibliotecas de protocolos, modelo de identidad y API de administración.

Esta guía se aplica a usted si ha implementado un agente hospedado antes de abril de 2026 mediante los azure-ai-agentserver-agentframework paquetes o azure-ai-agentserver-langgraph , o cualquier código personalizado que use las API de hospedaje de la versión preliminar inicial.

Qué ha cambiado

La actualización de la versión preliminar actualiza la plataforma existente con un modelo de sandbox basado en sesión. Cambios clave:

• Ciclo de vida de computación automático: no hay administración manual de inicio, parada o réplica. La plataforma aprovisiona los recursos de cómputo cuando llega una solicitud y los desaprovisiona después de 15 minutos de inactividad. Consulte Asignación de comandos de la CLI.
• Aislamiento basado en sesión — cada sesión obtiene su propia sandbox con almacenamiento $HOME y /files persistente, durante los turnos y períodos de inactividad.
• Las bibliotecas de protocolos reemplazan a los adaptadores de marco : los paquetes de adaptador específicos del marco (azure-ai-agentserver-agentframework, azure-ai-agentserver-langgraph) se reemplazan por bibliotecas específicas del protocolo (azure-ai-agentserver-responses, azure-ai-agentserver-invocations). Consulte Biblioteca de protocolos y migración del marco de trabajo.
• Identidad dedicada del agente desde el momento de la implementación — cada agente obtiene su propia identidad de Entra en el momento de la creación, reemplazando el modelo de identidad administrada del proyecto compartido. Consulte Cambios en Identidad y RBAC.
• Punto de conexión del agente dedicado : cada agente obtiene su propia dirección URL de punto de conexión (por ejemplo, {project_endpoint}/agents/{name}/endpoint/protocols/openai/v1/responses). Ya no se rutea a través de un endpoint de proyecto compartido con agent_reference como elemento en el cuerpo de la solicitud. Consulte Cambios en la invocación del agente.
• Nuevos protocolos : las invocaciones, la actividad y los protocolos A2A se unen al protocolo de respuestas existente. Un solo agente puede exponer varios protocolos simultáneamente.
• API REST para ciclo de vida completo — Cobertura REST completa para las operaciones de agente, versión, sesión y archivo. Consulte Cambios en los métodos del SDK.
• Eliminación de la creación de hosts de capacidad : la plataforma gestiona automáticamente el aprovisionamiento de infraestructuras. Ya no es necesario crear un host de funcionalidad de nivel de cuenta. Consulte API eliminadas.

Requisitos previos

• Azure SDK de proyectos de IA versión 2.1.0 o posterior (era 2.0.0).

• Azure CLI para desarrolladores versión 1.23.0 o posterior con la extensión de agentes Foundry actualizada:

  azd ext install azure.ai.agents
  

Pasos de migración de un vistazo

En los pasos siguientes se resume la migración de un extremo a otro. Cada vínculo enlaza a la sección detallada.

1. Actualizar las bibliotecas de protocolos y el código del agente : reemplace los adaptadores de marco por las nuevas bibliotecas de protocolos y actualice el punto de entrada del agente. Elija la ruta de acceso: Agent Framework, LangGraph o custom/BYO.
2. Actualización de las llamadas api, CLI y SDK : quite los comandos retirados de la CLI, actualice los métodos del SDK y cambie al punto de conexión del agente dedicado. Consulte APIs eliminadas, asignación de comandos de CLI, cambios en los métodos del SDK y cambios en la invocación de agentes.
3. Actualizar identidad y RBAC — conceda acceso a recursos descendentes a la identidad dedicada de Entra del agente. Consulte Cambios en Identidad y RBAC.
4. Actualizar las herramientas de la CLI de Azure para desarrolladores: instale la extensión más reciente de los agentes de azd Foundry y actualice agent.yaml. Consulte Cambios de la CLI de Azure para desarrolladores.
5. Reimplementación y comprobación : compile la imagen de contenedor, implemente mediante azd up o el SDK y confirme que la versión alcanza active el estado.

Para obtener un resumen de tareas por tarea, consulte la lista de comprobación de migración al final de este artículo.

Biblioteca de protocolos y migración del marco

La versión preliminar inicial usó paquetes de adaptadores específicos del marco (azure-ai-agentserver-agentframework, azure-ai-agentserver-langgraph) que encapsularon el código del agente. La versión preliminar actualizada reemplaza estas por bibliotecas específicas del protocolo y paquetes de integración de marcos actualizados.

La ruta de migración depende del marco que use:

• Microsoft Agent Framework — utiliza los paquetes de Agent Framework actualizados con el puente de ResponsesHostServer.
• LangGraph — Utiliza la biblioteca de azure-ai-agentserver-responses protocolos directamente con ResponsesAgentServerHost.
• CrewAI, Kernel semántico o código personalizado: use las bibliotecas de protocolos directamente (azure-ai-agentserver-responses o azure-ai-agentserver-invocations).

Cambios en el paquete

Bibliotecas de protocolos (todos los usuarios)

Paquetes de Agent Framework (solo usuarios de Agent Framework)

Los paquetes de Agent Framework también se actualizaron para la versión preliminar actualizada:

Migración de agentes de Agent Framework

Si el agente usa Microsoft Agent Framework, use el puente ResponsesHostServer de agent-framework-foundry-hosting. Este enfoque mantiene intacto el código de Agent Framework (definición del agente, herramientas, instrucciones) al usar la nueva biblioteca de protocolos en segundo plano.

Versión preliminar inicial:

from azure.ai.agentserver.agentframework import from_agent_framework
from agent_framework import ai_function, ChatAgent
from agent_framework.azure import AzureAIAgentClient

client = AzureAIAgentClient(
    project_endpoint=PROJECT_ENDPOINT,
    model_deployment_name="gpt-4.1",
    credential=DefaultAzureCredential(),
)

@ai_function
def get_weather(location: str) -> str:
    """Get the weather for a location."""
    return f"The weather in {location} is sunny."

agent = ChatAgent(
    chat_client=client,
    instructions="You are a helpful assistant.",
    tools=[get_weather],
)

if __name__ == "__main__":
    from_agent_framework(agent).run()

Vista previa actualizada:

import os

from agent_framework import Agent, tool
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential
from pydantic import Field
from typing_extensions import Annotated

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


@tool(approval_mode="never_require")
def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a location."""
    return f"The weather in {location} is sunny."


agent = Agent(
    client=client,
    instructions="You are a helpful assistant.",
    tools=[get_weather],
    default_options={"store": False},
)

server = ResponsesHostServer(agent)
server.run()

Diferencias clave:

• AzureAIAgentClient → FoundryChatClient (de agent_framework.foundry).
• ChatAgent → Agent (de agent_framework).
• @ai_function → @tool(approval_mode="never_require") con Annotated sugerencias de tipo para descripciones de parámetros.
• from_agent_framework(agent).run() → ResponsesHostServer(agent).run().
• Agregue default_options={"store": False} porque la plataforma de hospedaje administra el historial de conversaciones.

Para las herramientas de MCP, use client.get_mcp_tool() en lugar de definir herramientas en la create_version API:

mcp_tool = client.get_mcp_tool(
    name="GitHub",
    url="https://api.githubcopilot.com/mcp/",
    headers={"Authorization": f"Bearer {github_pat}"},
    approval_mode="never_require",
)

agent = Agent(client=client, tools=[mcp_tool], ...)

Para obtener ejemplos, consulte los ejemplos del agente hospedado en Agent Framework.

Migración de agentes de LangGraph

Si el agente usa LangGraph, reemplace el azure-ai-agentserver-langgraph adaptador por la biblioteca de azure-ai-agentserver-responses protocolos. La lógica del agente de LangGraph (definición de grafos, herramientas, configuración de LLM) permanece igual, solo cambia el punto de entrada de hospedaje.

Versión preliminar inicial:

from azure.ai.agentserver.langgraph import from_langgraph
from langchain_openai import AzureChatOpenAI
from langgraph.prebuilt import create_react_agent

llm = AzureChatOpenAI(azure_endpoint=ENDPOINT, azure_deployment="gpt-4o", ...)
tools = [my_tool_a, my_tool_b]
graph = create_react_agent(llm, tools=tools, prompt=SYSTEM_PROMPT)

if __name__ == "__main__":
    from_langgraph(graph).run()

Vista previa actualizada:

import asyncio
import os

import httpx
from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    ResponsesServerOptions,
    TextResponse,
)
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain_core.messages import AIMessage, HumanMessage
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent


FOUNDRY_PROJECT_ENDPOINT = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
MODEL = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "gpt-4.1")

_token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)


# httpx auth hook that injects a fresh Microsoft Entra token on every request.
class _AzureTokenAuth(httpx.Auth):
    def auth_flow(self, request):
        request.headers["Authorization"] = f"Bearer {_token_provider()}"
        yield request


llm = ChatOpenAI(
    base_url=f"{FOUNDRY_PROJECT_ENDPOINT}/openai/v1",
    api_key="placeholder",  # overridden by _AzureTokenAuth
    model=MODEL,
    use_responses_api=True,
    http_client=httpx.Client(auth=_AzureTokenAuth()),
)
tools = [my_tool_a, my_tool_b]
graph = create_react_agent(llm, tools=tools, prompt=SYSTEM_PROMPT)

app = ResponsesAgentServerHost(
    options=ResponsesServerOptions(default_fetch_history_count=20)
)


@app.response_handler
async def handle(
    request: CreateResponse,
    context: ResponseContext,
    cancellation_signal: asyncio.Event,
):
    async def run_graph():
        try:
            history = await context.get_history()
        except Exception:
            history = []
        user_input = await context.get_input_text() or ""

        # Convert platform history to LangChain messages
        lc_messages = []
        for item in history:
            if hasattr(item, "content"):
                for c in item.content:
                    if hasattr(c, "text") and c.text:
                        if item.role == "user":
                            lc_messages.append(HumanMessage(content=c.text))
                        else:
                            lc_messages.append(AIMessage(content=c.text))
        lc_messages.append(HumanMessage(content=user_input))

        result = await graph.ainvoke({"messages": lc_messages})
        raw = result["messages"][-1].content
        if isinstance(raw, list):
            yield "".join(
                block.get("text", "") if isinstance(block, dict) else str(block)
                for block in raw
            )
        else:
            yield raw or ""

    return TextResponse(context, request, text=run_graph())


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

Diferencias clave:

• azure-ai-agentserver-langgraph → azure-ai-agentserver-responses. Se quita el adaptador específico de LangGraph.
• from_langgraph(graph).run() → Explicit ResponsesAgentServerHost con un @app.response_handler que devuelve un TextResponse.
• Usa ChatOpenAI con base_url=f"{FOUNDRY_PROJECT_ENDPOINT}/openai/v1" en lugar de AzureChatOpenAI. Esto utiliza el punto final específico del proyecto, que requiere permisos a nivel de proyecto.
• El historial de conversaciones se captura a través de context.get_history() y se convierte en tipos de mensajes LangChain para la compatibilidad con múltiples turnos.
• La lógica del agente de LangGraph (herramientas, creación de grafos) no cambia. Para un control específico sobre llamadas de función, elementos de razonamiento o varios tipos de salida, use ResponseEventStream en lugar de TextResponse.

Integración de MCP Toolbox

Para conectar el agente de LangGraph a las herramientas del Cuadro de herramientas de Foundry a través de MCP, use langchain-mcp-adapters dentro del controlador. Cargar herramientas dinámicamente desde el punto de conexión de MCP:

from langchain_mcp_adapters.tools import load_mcp_tools
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client


@app.response_handler
async def handle(request, context, cancellation_signal):
    user_input = await context.get_input_text()
    endpoint = os.environ["TOOLBOX_ENDPOINT"]
    token = DefaultAzureCredential().get_token("https://ai.azure.com/.default").token
    headers = {
        "Authorization": f"Bearer {token}",
        "Foundry-Features": "Toolsets=V1Preview",
    }

    async with streamablehttp_client(endpoint, headers=headers) as (r, w, _):
        async with ClientSession(r, w) as session:
            await session.initialize()
            tools = await load_mcp_tools(session)
            graph = create_react_agent(llm, tools=tools, prompt=SYSTEM_PROMPT)
            result = await graph.ainvoke(
                {"messages": [{"role": "user", "content": user_input}]},
            )
            # ... extract answer and return TextResponse

Agregue estos paquetes a requirements.txt:

langchain-mcp-adapters>=0.1.0
mcp>=1.0.0

Para obtener ejemplos completos, consulte los ejemplos del agente hospedado en LangGraph.

Migración de agentes personalizados o BYO

Si usa CrewAI, Kernel semántico u otro código personalizado, use directamente la biblioteca de protocolos. Las bibliotecas de protocolos son independientes de cualquier marco particular, lo que significa que usted maneja la orquestación, las herramientas y la memoria en su propio código.

Protocolo de respuestas : se usa ResponsesAgentServerHost para agentes conversacionales. Registre el controlador con el @app.response_handler decorador:

import asyncio

from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()


@app.response_handler
async def handler(
    request: CreateResponse,
    context: ResponseContext,
    cancellation_signal: asyncio.Event,
):
    text = await context.get_input_text()
    return TextResponse(context, request, text=f"Echo: {text}")


app.run()

Para las respuestas de streaming, pase un iterable asincrónico a TextResponse. Para un control específico sobre llamadas de función, elementos de razonamiento o varios tipos de salida, use ResponseEventStream en lugar de TextResponse.

Protocolo de invocaciones : use InvocationAgentServerHost para agentes que necesitan cargas JSON arbitrarias (webhooks, procesamiento no conversacional). El controlador usa tipos Starlette Request/Response directamente:

from azure.ai.agentserver.invocations import InvocationAgentServerHost
from starlette.requests import Request
from starlette.responses import JSONResponse, Response

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle(request: Request) -> Response:
    data = await request.json()
    return JSONResponse({"greeting": f"Hello, {data['name']}!"})


app.run()

El protocolo Invocaciones también admite operaciones de larga duración con @app.get_invocation_handler y @app.cancel_invocation_handler para sondeo y cancelación.

Elija el protocolo en función del patrón de interacción del agente. Consulte Qué son los agentes hospedados: protocolos para obtener instrucciones sobre qué protocolo usar.

Cambio de formato de versión del protocolo

El formato de versión del protocolo ha cambiado de "v1" a semver "1.0.0":

# Initial preview
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")

# Refreshed preview
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0")

APIs eliminadas

Las siguientes API de la versión preliminar inicial no están disponibles en la versión preliminar actualizada:

Asignación de comandos de la CLI

Donde BASE_URL es https://{account}.services.ai.azure.com/api/projects/{project}.

Cambios en el método del SDK

Cambios en la invocación del agente

En la versión preliminar inicial, se enrutó a los agentes a través de un punto de conexión de proyecto compartido pasando el elemento agent_reference en el cuerpo de la solicitud. En la versión preliminar actualizada, cada agente obtiene un punto de conexión dedicado y el SDK se enlaza automáticamente a él.

Versión preliminar inicial:

openai_client = project.get_openai_client()
response = openai_client.responses.create(
    input=[{"role": "user", "content": "Hello!"}],
    extra_body={"agent_reference": {"name": "my-agent", "type": "agent_reference"}}
)

Vista previa actualizada:

openai_client = project.get_openai_client(agent_name="my-agent")
response = openai_client.responses.create(
    input="Hello!",
)
print(response.output_text)

project = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=PROJECT_ENDPOINT,
    allow_preview=True,
)

El agent_name parámetro indica al SDK que tiene como destino el punto de conexión dedicado del agente. Para las llamadas REST, use el punto de conexión del agente directamente:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: HostedAgents=V1Preview" \
  -d '{"input": "Hello!", "model": "gpt-4.1", "stream": false}'

Los puntos de conexión activos dependen de los protocolos que declare en la definición de la versión del agente. Las rutas de Respuestas y Conversaciones se encuentran en el espacio de nombres compatible con OpenAI en {project_endpoint}/agents/{name}/endpoint/protocols/openai/v1/{responses|conversations}, mientras que las rutas de Invocaciones, Actividad y A2A se encuentran directamente en {project_endpoint}/agents/{name}/endpoint/protocols/{invocations|activityprotocol|a2a}.

Cambios en el estado de la versión

Los estados del ciclo de vida del agente cambiaron de una máquina de estado manual a los estados de aprovisionamiento automático:

Cambios de identidad y RBAC

El modelo de identidad cambió significativamente:

Acción necesaria

1. Actualizar asignaciones de RBAC: la identidad administrada del proyecto ya no es la identidad en tiempo de ejecución. Conceda roles de control de acceso basado en roles (RBAC) para cualquier recurso posterior de Azure directamente a la identidad Entra del agente en lugar de.
2. Simplificar los roles de implementación: necesitas Azure AI Project Manager en el ámbito del proyecto para crear e implementar agentes hospedados.

cambios de la CLI para desarrolladores de Azure

Comandos actualizados

Acción necesaria

1. Actualice la extensión de Foundry Agents

   azd ext install azure.ai.agents
   

2. Si su agent.yaml especifica version: "v1" para las versiones de protocolo, cámbielo a version: "1.0.0".

Registro de cambios de streaming

Brechas conocidas

Las siguientes funcionalidades de la versión preliminar inicial aún no están disponibles en la versión preliminar actualizada:

Lista de comprobación de migración

Use esta lista de comprobación para realizar un seguimiento de la migración:

• Actualice azure-ai-projects el SDK a la versión 2.1.0 o posterior.
• Usuarios de Agent Framework: actualice los paquetes de Agent Framework (agent-framework-core, agent-framework-foundry, agent-framework-foundry-hosting, etc.). Reemplace from_agent_framework(agent).run() con ResponsesHostServer(agent).run(). Actualice AzureAIAgentClient → FoundryChatClient, ChatAgent → Agent, y @ai_function → @tool.
• Usuarios de LangGraph: Reemplace azure-ai-agentserver-langgraph con azure-ai-agentserver-responses. Reemplace from_langgraph(graph).run() con un controlador ResponsesAgentServerHost que devuelve un TextResponse. Use ChatOpenAI para el endpoint con ámbito de proyecto en lugar de AzureChatOpenAI. Agregue langchain-mcp-adapters y mcp , si usa Foundry Toolbox.
• Usuarios personalizados o BYO: Reemplace los paquetes de adaptadores de framework por bibliotecas de protocolo (azure-ai-agentserver-responses o azure-ai-agentserver-invocations). Reescriba los puntos de entrada del agente mediante ResponsesAgentServerHost o InvocationAgentServerHost.
• Actualice las cadenas de versión del protocolo de "v1" a "1.0.0" en el código y agent.yaml.
• Actualice agent.yaml si está utilizando azd (formato de versión del protocolo, elimine cualquier definición de tools de la configuración del agente).
• Elimine az cognitiveservices agent las llamadas de la CLI de scripts y canalizaciones de CI/CD; reemplácelas por comandos az rest o azd ai agent.
• Elimine los pasos de creación del host de capacidad de los scripts de aprovisionamiento.
• Actualizar el código de invocación del agente: use project.get_openai_client(agent_name=...) en lugar de extra_body con agent_reference.
• Revise RBAC: conceda acceso de recursos de bajada a la identidad entra dedicada del agente, no a la identidad administrada del proyecto.
• Actualice azd la extensión de agentes de Foundry a la versión más reciente.
• Compile la imagen de contenedor con --platform linux/amd64 (si aún no lo está).
• Vuelva a implementar el agente mediante azd up o el método del SDK create_version .
• Compruebe que la nueva versión alcanza el estado active antes de enviar tráfico.

Pasos siguientes

Contenido relacionado

• ¿Qué son los agentes alojados?
• Administración de agentes hospedados
• Administración de sesiones del agente hospedado