Eseguire la migrazione degli agenti ospitati all'anteprima pubblica aggiornata

Questo articolo illustra la migrazione degli agenti ospitati dall'anteprima pubblica iniziale all'anteprima pubblica aggiornata del servizio Foundry Agent. L'anteprima aggiornata introduce un nuovo back-end di hosting, librerie di protocolli, modello di identità e API di gestione.

Questa guida si applica all'utente se hai distribuito un agente ospitato prima di aprile 2026 usando i pacchetti azure-ai-agentserver-agentframework o azure-ai-agentserver-langgraph codice personalizzato che utilizzava le API di hosting dell'anteprima iniziale.

Cosa è cambiato

L'anteprima aggiornata aggiorna la piattaforma esistente con un modello sandbox basato su sessione. Modifiche chiave:

• Ciclo di vita di calcolo automatico : nessun avvio manuale, arresto o gestione delle repliche. La piattaforma effettua il provisioning delle risorse di calcolo quando arriva una richiesta e effettua il deprovisioning dopo 15 minuti di inattività. Vedi mappatura dei comandi CLI.
• Isolamento basato sulla sessione — ogni sessione ottiene la propria sandbox con archiviazione persistente $HOME e /files tra turni e periodi di inattività.
• Le librerie di protocollo sostituiscono gli adattatori del framework : i pacchetti di adattatori specifici del framework (azure-ai-agentserver-agentframework, azure-ai-agentserver-langgraph) vengono sostituiti da librerie specifiche del protocollo (azure-ai-agentserver-responses, azure-ai-agentserver-invocations). Vedere Libreria di protocolli e migrazione del framework.
• Identità dell'agente dedicato dal momento della distribuzione : ogni agente ottiene la propria identità Entra al momento della creazione, sostituendo il modello di identità gestita del progetto condiviso. Vedere Modifiche di identità e controllo degli accessi in base al ruolo.
• Endpoint agente dedicato — ogni agente ottiene il proprio URL dell'endpoint, ad esempio {project_endpoint}/agents/{name}/endpoint/protocols/openai/v1/responses. Non è più possibile instradare attraverso un endpoint di progetto condiviso con agent_reference nel corpo della richiesta. Vedere Modifiche alla chiamata dell'agente.
• Nuovi protocolli : chiamate, attività e protocolli A2A vengono aggiunti al protocollo Risposte esistente. Un singolo agente può esporre più protocolli contemporaneamente.
• API REST per il ciclo di vita completo : copertura REST completa per le operazioni di agente, versione, sessione e file. Vedere Modifiche al metodo SDK.
• La creazione dell'host di funzionalità è stata rimossa : la piattaforma gestisce automaticamente il provisioning dell'infrastruttura. Non è più necessario creare un host di funzionalità a livello di account. Vedere Removed APIs (API rimosse).

Prerequisiti

• Azure AI Projects SDK versione 2.1.0 o successiva (2.0.0).

• Azure Developer CLI versione 1.23.0 o successiva con l'estensione aggiornata degli agenti Foundry:

  azd ext install azure.ai.agents
  

Passaggi di migrazione a colpo d'occhio

La procedura seguente riepiloga la migrazione completa. Ognuno collega alla sezione dettagliata.

1. Aggiornare le librerie di protocolli e il codice dell'agente : sostituire gli adattatori del framework con le nuove librerie di protocolli e aggiornare il punto di ingresso dell'agente. Scegliere il percorso: Agent Framework, LangGraph o personalizzato/BYO.
2. Aggiornare le chiamate API, interfaccia della riga di comando e SDK : rimuovere i comandi dell'interfaccia della riga di comando ritirati, aggiornare i metodi SDK e passare all'endpoint dell'agente dedicato. Vedere Rimozione delle API, mappatura dei comandi dell'interfaccia a riga di comando, modifiche ai metodi SDK e modifiche all'invocazione dell'agente.
3. Aggiornare l'identità e il controllo degli accessi basato sui ruoli: concedere l'accesso alle risorse downstream all'identificativo dedicato Entra dell'agente. Vedere Modifiche di identità e controllo degli accessi in base al ruolo.
4. Aggiornare gli strumenti della CLI per sviluppatori Azure — installare l'ultima estensione degli agenti Foundry azd e aggiornare agent.yaml. Consulta Azure Developer CLI changes.
5. Ridistribuire e verificare : compilare l'immagine del contenitore, eseguire la distribuzione con azd up o l'SDK e verificare che la versione raggiunga active lo stato.

Per un riepilogo delle attività per attività, vedere l'elenco di controllo per la migrazione alla fine di questo articolo.

Libreria di protocolli e migrazione del framework

L'anteprima iniziale usava pacchetti di adattatori specifici del framework (azure-ai-agentserver-agentframework, azure-ai-agentserver-langgraph) che eseguivano il wrapping del codice dell'agente. L'anteprima aggiornata sostituisce questi elementi con librerie specifiche del protocollo e pacchetti di integrazione del framework aggiornati.

Il percorso di migrazione dipende dal framework usato:

• Microsoft Agent Framework : usare i pacchetti aggiornati di Agent Framework con il bridge ResponsesHostServer.
• LangGraph : usare la azure-ai-agentserver-responses libreria di protocolli direttamente con ResponsesAgentServerHost.
• CrewAI, Kernel semantico o codice personalizzato : usare direttamente le librerie di protocolli (azure-ai-agentserver-responses o azure-ai-agentserver-invocations).

Modifiche del pacchetto

Librerie di protocollo (tutti gli utenti)

Pacchetti di Agent Framework (solo utenti di Agent Framework)

I pacchetti di Agent Framework sono stati aggiornati anche per l'anteprima aggiornata:

Eseguire la migrazione degli agenti di Agent Framework

Se l'agente usa Microsoft Agent Framework, usare il bridge ResponsesHostServer da agent-framework-foundry-hosting. Questo approccio mantiene intatto il codice di Agent Framework (definizione dell'agente, strumenti, istruzioni) usando la nuova libreria di protocolli.

Anteprima iniziale:

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

Anteprima aggiornata:

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

Differenze principali:

• AzureAIAgentClient FoundryChatClient → (da agent_framework.foundry).
• ChatAgent Agent → (da agent_framework).
• @ai_function → @tool(approval_mode="never_require") con gli hint di tipo Annotated per le descrizioni dei parametri.
• from_agent_framework(agent).run() → ResponsesHostServer(agent).run().
• Aggiungere default_options={"store": False} perché la cronologia delle conversazioni è gestita dalla piattaforma di hosting.

Per gli strumenti MCP, usare client.get_mcp_tool() invece di definire gli strumenti nell'API create_version :

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], ...)

Per esempi, vedere gli esempi dell'agente ospitato di Agent Framework.

Eseguire la migrazione degli agenti LangGraph

Se l'agente usa LangGraph, sostituire l'adattatore azure-ai-agentserver-langgraph con la libreria di azure-ai-agentserver-responses protocolli. La logica dell'agente LangGraph (definizione del grafo, strumenti, configurazione LLM) rimane invariata, ma solo il punto di ingresso dell'hosting cambia.

Anteprima iniziale:

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

Anteprima aggiornata:

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

Differenze principali:

• azure-ai-agentserver-langgraph → azure-ai-agentserver-responses. L'adattatore specifico di LangGraph viene rimosso.
• from_langgraph(graph).run() → Explicit ResponsesAgentServerHost con un @app.response_handler che restituisce un TextResponse.
• Usa ChatOpenAI con base_url=f"{FOUNDRY_PROJECT_ENDPOINT}/openai/v1" invece di AzureChatOpenAI. Viene usato l'endpoint con ambito progetto, che richiede solo autorizzazioni a livello di progetto.
• La cronologia delle conversazioni viene recuperata tramite context.get_history() e convertita in tipi di messaggi LangChain per il supporto a più turni.
• La logica dell'agente LangGraph (strumenti, creazione del grafo) rimane invariata. Per il controllo dettagliato sulle chiamate di funzione, sulla logica degli elementi o su più tipi di output, usare ResponseEventStream anziché TextResponse.

Integrazione della casella degli strumenti MCP

Per connettere l'agente LangGraph agli strumenti nella casella degli strumenti Foundry tramite MCP, usare langchain-mcp-adapters all'interno del gestore. Caricare gli strumenti in modo dinamico dall'endpoint 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

Aggiungere questi pacchetti a requirements.txt:

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

Per esempi completi, vedere gli esempi dell'agente ospitato LangGraph.

Eseguire la migrazione di agenti personalizzati o BYO (Bring Your Own)

Se si usa CrewAI, Kernel semantico o altro codice personalizzato, usare direttamente la libreria di protocolli. Le librerie di protocolli sono indipendenti dal framework, quindi puoi gestire l'orchestrazione, gli strumenti e la memoria nel tuo codice personalizzato.

Protocollo di risposte : usare ResponsesAgentServerHost per gli agenti di conversazione. Registra il tuo gestore con il decoratore @app.response_handler.

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

Per le risposte in streaming, passare un iterabile asincrono a TextResponse. Per il controllo dettagliato sulle chiamate di funzione, sulla logica degli elementi o su più tipi di output, usare ResponseEventStream anziché TextResponse.

Protocollo chiamate : usare InvocationAgentServerHost per gli agenti che necessitano di payload JSON arbitrari (webhook, elaborazione non conversazionale). Il gestore usa direttamente i tipi Starlette Request/Response :

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

Il protocollo Invocations supporta anche operazioni a lunga esecuzione con @app.get_invocation_handler e @app.cancel_invocation_handler per il polling e l'annullamento.

Scegliere il protocollo in base al modello di interazione dell'agente. Vedere Che cosa sono gli agenti ospitati - Protocolli per indicazioni su quale protocollo usare.

Modifica del formato della versione del protocollo

Il formato della versione del protocollo è cambiato da "v1" a semver "1.0.0":

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

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

API rimosse

Le API seguenti dell'anteprima iniziale non sono disponibili nell'anteprima aggiornata:

Mapping dei comandi CLI

Dove BASE_URL è https://{account}.services.ai.azure.com/api/projects/{project}.

Modifiche al metodo SDK

Modifiche alla chiamata dell'agente

Nell'anteprima iniziale, hai instradato gli agenti tramite un endpoint di progetto condiviso, passando un parametro agent_reference nel corpo della richiesta. Nell'anteprima aggiornata, ogni agente ottiene un endpoint dedicato e l'SDK lo associa automaticamente.

Anteprima iniziale:

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"}}
)

Anteprima aggiornata:

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

Il agent_name parametro indica all'SDK di specificare come destinazione l'endpoint dedicato dell'agente. Per le chiamate REST, usare direttamente l'endpoint dell'agente:

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

Gli endpoint attivi dipendono dai protocolli dichiarati nella definizione della versione dell'agente. Le routes Risposte e Conversazioni si trovano sotto lo spazio dei nomi compatibile con OpenAI in {project_endpoint}/agents/{name}/endpoint/protocols/openai/v1/{responses|conversations}, mentre Invocazioni, Attività e A2A si dirigono direttamente a {project_endpoint}/agents/{name}/endpoint/protocols/{invocations|activityprotocol|a2a}.

Modifiche dello stato della versione

Gli stati del ciclo di vita dell'agente sono passati da una macchina a stati manuale a stati di provisioning automatizzati.

Modifiche di identità e controllo degli accessi in base al ruolo

Il modello di identità è cambiato in modo significativo:

Azione richiesta

1. Aggiornare le assegnazioni RBAC: l'identità gestita del progetto non è più l'identità di runtime. Assegna invece i ruoli di controllo degli accessi in base ai ruoli per ogni risorsa downstream di Azure direttamente all'identità Entra dell'agente.
2. Simplificare i ruoli di distribuzione: è necessario Azure AI Project Manager nell'ambito project per creare e distribuire agenti ospitati.

modifiche all'interfaccia della riga di comando per sviluppatori Azure

Comandi aggiornati

Azione richiesta

1. Aggiornare l'estensione degli agenti di Foundry:

   azd ext install azure.ai.agents
   

2. agent.yaml Se l'oggetto specifica le versioni del protocollo version: "v1", cambiarlo in version: "1.0.0".

Modifiche allo streaming dei log

Lacune conosciute

Le funzionalità seguenti dell'anteprima iniziale non sono ancora disponibili nell'anteprima aggiornata:

Elenco di controllo per la migrazione

Usare questo elenco di controllo per tenere traccia della migrazione:

• Aggiornare azure-ai-projects l'SDK alla versione 2.1.0 o successiva.
• Utenti di Agent Framework: aggiornare i pacchetti di Agent Framework (agent-framework-core, agent-framework-foundry, agent-framework-foundry-hostinge così via). Sostituire from_agent_framework(agent).run() con ResponsesHostServer(agent).run(). Aggiornare AzureAIAgentClient → FoundryChatClient, ChatAgent → Agente @ai_function → @tool.
• Utenti di LangGraph: sostituire azure-ai-agentserver-langgraph con azure-ai-agentserver-responses. Sostituire from_langgraph(graph).run() con un ResponsesAgentServerHost gestore che restituisce un oggetto TextResponse. Usare ChatOpenAI con l'endpoint con ambito di progetto anziché AzureChatOpenAI. Aggiungere langchain-mcp-adapters e mcp se si usa la casella degli strumenti Foundry.
• Utenti personalizzati/BYO: sostituire i pacchetti dell'adattatore framework con librerie di protocolli (azure-ai-agentserver-responses o azure-ai-agentserver-invocations). Riscrivere i punti di ingresso dell'agente usando ResponsesAgentServerHost o InvocationAgentServerHost.
• Aggiornare le stringhe di versione del protocollo da "v1" a "1.0.0" nel codice e agent.yaml.
• Aggiornare agent.yaml se si usa azd (formato di versione del protocollo, rimuovere eventuali tools definizioni dalla definizione dell'agente).
• Rimuovere le chiamate az cognitiveservices agent CLI dagli script e dalle pipeline CI/CD; sostituire con comandi az rest o azd ai agent.
• Rimuovere i passaggi di creazione dell'host di funzionalità dagli script di provisioning.
• Aggiornare il codice di chiamata dell'agente: usare project.get_openai_client(agent_name=...) invece di extra_body con agent_reference.
• Esaminare il controllo degli accessi in base al ruolo: concedere alle risorse downstream l'accesso all'identità Entra dedicata dell'agente, non all'identità gestita del progetto.
• Aggiornare l'estensione azd agenti Foundry alla versione più recente.
• Creare un'immagine del contenitore con --platform linux/amd64 (se non è già stato fatto).
• Ridistribuire l'agente usando azd up o il metodo SDK create_version .
• Verificare che la nuova versione raggiunga lo stato active prima di inviare il traffico.

Passaggi successivi

Contenuto correlato

• Che cosa sono gli agenti ospitati?
• Gestire gli agenti ospitati
• Gestire le sessioni dell'agente ospitato