Eseguire la migrazione degli agenti ospitati alla versione più recente

Questo articolo illustra come eseguire la migrazione degli agenti ospitati dall'anteprima pubblica iniziale alla versione più recente del servizio Foundry Agent. La versione più recente 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 Hosted Agent prima di aprile 2026 usando i pacchetti azure-ai-agentserver-agentframework o azure-ai-agentserver-langgraph oppure eventuale codice personalizzato che usava le API di hosting della versione di anteprima iniziale.

Se si usa un agente di codifica come GitHub Copilot, la competenza Microsoft Foundry consente di eseguire il mapping della distribuzione di anteprima esistente al modello di hosting più recente e aggiornare i comandi o il codice.

Cosa è cambiato

La versione più recente 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 esegue il provisioning delle risorse di calcolo quando arriva una richiesta e ne effettua il deprovisioning dopo il timeout di inattività configurato, che per impostazione predefinita è di 15 minuti. 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/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.3.0 o successiva (2.0.0).

• Interfaccia della riga di comando per sviluppatori di Azure versione 1.23.0 o successiva con l'estensione degli agenti Foundry aggiornata:

  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 in base al ruolo: concedere alle risorse downstream l'accesso all'identità Entra dedicata dell'agente. Vedere Modifiche di identità e controllo degli accessi in base al ruolo.
4. Aggiornare gli strumenti di Azure Developer CLI -- Installare la versione più recente dell'estensione azd Foundry Agents e aggiornare azure.yaml. Vedere Modifiche all'interfaccia della riga di comando per sviluppatori di Azure.
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. La versione più recente sostituisce questi pacchetti 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 ResponsesHostServer bridge.
• LangGraph : usare la azure-ai-agentserver-responses libreria di protocolli direttamente con ResponsesAgentServerHost.
• CrewAI, Kernel semantico o codice personalizzato : usare direttamente le librerie di protocollo (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 vengono aggiornati anche per la versione più recente:

Eseguire la migrazione degli agenti di Agent Framework

Se l'agente usa Microsoft Agent Framework, usare il ResponsesHostServer bridge 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()

Ultima versione:

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 Annotated indicazioni di tipo nelle 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 in 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()

Ultima versione:

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("FOUNDRY_MODEL_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() ->ResponsesAgentServerHost esplicito con @app.response_handler che restituisce 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, consulta gli esempi dell'agente Hosted di LangGraph.

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

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 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 esecuzione prolungata 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=AgentEndpointProtocol.RESPONSES, version="v1")

# Latest version
ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="1.0.0")

Protocollo del contenitore 2.0.0

La versione 2.0.0 del protocollo del contenitore modifica il modo in cui l'identità associata a ogni richiesta viene trasmessa al contenitore e alle chiamate ai servizi downstream. La versione 1.0.0 è deprecata. Dopo il periodo di deprecazione, la piattaforma blocca le richieste agli agenti che utilizzano ancora il protocollo 1.0.0.

Il protocollo 2.0.0 consente anche a una sessione di servire in modo sicuro più utenti. Nella versione 1.0.0 una sessione è associata all'identità di un singolo chiamante, quindi gli utenti simultanei nella stessa sessione possono interferire tra loro. Nella versione 2.0.0, ogni richiesta porta con sé il proprio contesto utente, così una sessione può servire molti utenti senza che le loro identità entrino in conflitto.

Per eseguire una migrazione:

1. Impostare la versione del protocollo del contenitore su 2.0.0 nel servizio azure.ai.agent in azure.yaml.
2. Inoltra l'intestazione x-agent-foundry-call-id per ogni richiesta nelle chiamate in uscita verso i servizi Foundry (Storage, Toolbox e altri agenti). Gli adattatori SDK ufficiali eseguono questa operazione automaticamente quando si chiamano tali servizi tramite i client. Se si effettuano chiamate HTTP non elaborate, leggere x-agent-foundry-call-id dalla richiesta in ingresso e aggiungerla, senza modifiche, alla richiesta in uscita. Non eseguire il parsing del valore: la piattaforma determina l'identità del chiamante a partire da esso.
3. Per partizionare i dati archiviati dal contenitore per utente, leggere l'intestazione x-agent-user-id . Per un esempio pratico, vedi Gestire più utenti in un'unica sessione di un agente ospitato.

Per l'elenco completo delle intestazioni della piattaforma e delle variabili di ambiente, consulta il contratto di runtime dell'agente ospitato.

API rimosse

Le API seguenti dell'anteprima iniziale non sono disponibili nella versione più recente:

Mapping dei comandi dell'interfaccia della riga di comando

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. Nella versione più recente, ogni agente ottiene un endpoint dedicato e l'SDK viene associato 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"}}
)

Ultima versione:

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

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" \
  -d '{"input": "Hello!", "model": "gpt-4.1", "stream": false}'

Gli endpoint attivi dipendono dai protocolli dichiarati nella definizione della versione dell'agente. Le risposte e le conversazioni vengono instradate nello spazio dei nomi compatibile con OpenAI in {project_endpoint}/agents/{name}/endpoint/protocols/openai/{responses|conversations}, mentre le chiamate, l'attività e la route A2A vengono indirizzate direttamente a {project_endpoint}/agents/{name}/endpoint/protocols/{invocations|activityprotocol|a2a}.

Modifiche dello stato della versione

Gli stati del ciclo di vita dell'agente passano da uno stato manuale a stati di provisioning automatico:

Modifiche all'identità e al 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. Concedere invece i ruoli del controllo degli accessi in base al ruolo per le risorse di Azure downstream direttamente all'identità Entra dell'agente.
2. Semplificare i ruoli di distribuzione: È necessario un Project Manager di Foundry a livello di progetto per creare e distribuire gli agenti Hosted.

Modifiche all'interfaccia della riga di comando per sviluppatori di Azure

Comandi aggiornati

Azione richiesta

1. Aggiornare l'estensione degli agenti di Foundry:

   azd ext install azure.ai.agents
   

2. Se il tuo azure.yaml specifica version: "v1" per le versioni del protocollo in un servizio azure.ai.agent, modificalo in version: "1.0.0".

Modifiche allo streaming dei log

Lacune conosciute

Le funzionalità seguenti dell'anteprima iniziale non sono ancora disponibili nella versione più recente:

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 altri). Sostituire from_agent_framework(agent).run() con ResponsesHostServer(agent).run(). Aggiorna AzureAIAgentClient da FoundryChatClient a ChatAgent, Agent da @ai_function a @tool.
• Utenti di LangGraph: sostituire azure-ai-agentserver-langgraph con azure-ai-agentserver-responses. Sostituire from_langgraph(graph).run() con un gestore ResponsesAgentServerHost 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 azure.yaml.
• Aggiornare azure.yaml se si usa azd (formato della versione del protocollo e impostazioni dell'agente nel azure.ai.agent servizio).
• 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.
• Rivedere il controllo degli accessi in base al ruolo: concedere l'accesso alle risorse downstream all'identità Entra dedicata dell'agente, non all'identità gestita dal progetto.
• Aggiornare l'estensione degli agenti Foundry azd 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

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