Migrar agentes alojados para a pré-visualização pública atualizada

Este artigo guia-o pela migração dos agentes alojados desde a pré-visualização pública inicial até à pré-visualização pública atualizada do Foundry Agent Service. A pré-visualização atualizada introduz um novo backend de alojamento, bibliotecas de protocolos, modelo de identidade e APIs de gestão.

Este guia aplica-se a si se tiver implementado um agente alojado antes de abril de 2026 usando os pacotes azure-ai-agentserver-agentframework ou azure-ai-agentserver-langgraph, ou qualquer código personalizado que tenha usado as APIs de alojamento em pré-visualização inicial.

O que mudou

A pré-visualização atualizada atualiza a plataforma existente com um modelo sandbox baseado em sessões. Alterações principais:

• Ciclo de vida automático de computação — Sem gestão manual de início, paragem ou réplicas. As provisões da plataforma calculam quando chega um pedido e desaprovisionam-no após 15 minutos de inatividade. Veja mapeamento de comandos CLI.
• Isolamento baseado em sessões — Cada sessão tem o seu próprio sandbox com armazenamento $HOME e /files persistente entre turnos e períodos de inatividade.
• As bibliotecas de protocolo substituem os adaptadores de framework — Os pacotes adaptadores específicos de framework (azure-ai-agentserver-agentframework, azure-ai-agentserver-langgraph) são substituídos por bibliotecas específicas de protocolo (azure-ai-agentserver-responses, azure-ai-agentserver-invocations). Ver Migração da biblioteca e framework de protocolos.
• Identidade dedicada de agente desde o momento de implementação — Cada agente recebe a sua própria identidade Entra na criação, substituindo o modelo de identidade gerida por projeto partilhado. Consulte Alterações de Identidade e RBAC.
• Endpoint de agente dedicado — Cada agente recebe a sua própria URL de endpoint (por exemplo, {project_endpoint}/agents/{name}/endpoint/protocols/openai/v1/responses). Já não faz o encaminhamento através de um endpoint de projeto partilhado com agent_reference no corpo da solicitação. Ver alterações na invocação do agente.
• Novos protocolos — Invocações, Atividade e protocolos A2A juntam-se ao protocolo Respostas existente. Um único agente pode expor múltiplos protocolos simultaneamente.
• API REST para ciclo de vida completo — Cobertura REST completa para operações de agente, versão, sessão e ficheiro. Ver alterações ao método SDK.
• Criação de servidor de capacidade removida — A plataforma gere automaticamente o provisionamento da infraestrutura. Já não precisa de criar um anfitrião de capacidades ao nível da conta. Ver APIs removidas.

Pré-requisitos

• Azure AI Projects SDK versão 2.1.0 ou posterior (era a 2.0.0).

• Azure Developer CLI versão 1.23.0 ou posterior com a extensão atualizada Foundry agents:

  azd ext install azure.ai.agents
  

Passos de migração num relance

Os passos seguintes resumem a migração de ponta a ponta. Cada uma liga para a secção detalhada.

1. Atualize as bibliotecas de protocolos e o código do agente — Substitua os adaptadores do framework pelas novas bibliotecas de protocolos e atualize o ponto de entrada do seu agente. Escolhe o teu caminho: Agent Framework, LangGraph ou personalizado/BYO.
2. Atualize chamadas de API, CLI e SDK — Remova comandos CLI retirados, atualize os métodos do SDK e mude para o endpoint dedicado do agente. Veja APIs removidas, mapeamento de comandos CLI, alterações ao método SDK e alterações na invocação do Agente.
3. Atualizar identidade e RBAC — Conceder acesso a recursos a jusante à identidade dedicada Entra do agente. Consulte Alterações de Identidade e RBAC.
4. Update Azure Developer CLI tooling — Instale a mais recente extensão azd Foundry agents e atualize agent.yaml. Consulte Mudanças na Azure CLI para Desenvolvedores.
5. Redistribua e confirme — Construa a imagem do seu contenedor, implemente usando azd up ou o SDK, e confirme se a versão atinge o estado de active.

Para um resumo de tarefa por tarefa, consulte a lista de verificação de migração no final deste artigo.

Migração de bibliotecas de protocolos e frameworks

A pré-visualização inicial usava pacotes adaptadores específicos do framework (azure-ai-agentserver-agentframework, azure-ai-agentserver-langgraph) que envolviam o código do seu agente. A pré-visualização atualizada substitui-as por bibliotecas específicas de protocolo e pacotes de integração de frameworks atualizados.

O seu caminho de migração depende do framework que utiliza:

• Microsoft Agent Framework — Use os pacotes atualizados do Agent Framework com a ponte ResponsesHostServer.
• LangGraph — Use a azure-ai-agentserver-responses biblioteca de protocolos diretamente com ResponsesAgentServerHost.
• CrewAI, Kernel Semântico ou código personalizado — Use as bibliotecas de protocolos diretamente (azure-ai-agentserver-responses ou azure-ai-agentserver-invocations).

Alterações no pacote

Bibliotecas de protocolos (todos os utilizadores)

Pacotes Agent Framework (apenas utilizadores do Agent Framework)

Os pacotes do Agent Framework também foram atualizados para a pré-visualização atualizada:

Migrar agentes do Agent Framework

Se o seu agente utilizar o Microsoft Agent Framework, utilize a ponte ResponsesHostServer do agent-framework-foundry-hosting. Esta abordagem mantém o seu código do Agent Framework (definição do agente, ferramentas, instruções) intacto enquanto utiliza a nova biblioteca de protocolos por baixo.

Pré-visualização 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()

Pré-visualização atualizada:

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

Principais diferenças:

• AzureAIAgentClient → FoundryChatClient (de agent_framework.foundry).
• ChatAgent → Agent (de agent_framework).
• @ai_function → @tool(approval_mode="never_require") com Annotated anotações de tipo para descrições de parâmetros.
• from_agent_framework(agent).run() → ResponsesHostServer(agent).run().
• Adicione default_options={"store": False} porque o histórico de conversas é gerido pela plataforma de alojamento.

Para ferramentas MCP, use client.get_mcp_tool() em vez de definir ferramentas na 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 exemplos, consulte os amostras de agentes alojadas pelo Agent Framework.

Migrar os agentes LangGraph

Se o seu agente usar LangGraph, substitua o azure-ai-agentserver-langgraph adaptador pela azure-ai-agentserver-responses biblioteca de protocolos. A lógica do seu agente LangGraph (definição do grafo, ferramentas, configuração do LLM) permanece inalterada — apenas o ponto de entrada de hospedagem muda.

Pré-visualização 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()

Pré-visualização atualizada:

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

Principais diferenças:

• azure-ai-agentserver-langgraph → azure-ai-agentserver-responses. O adaptador específico do LangGraph é removido.
• from_langgraph(graph).run() → Explícito ResponsesAgentServerHost com um @app.response_handler que devolve um TextResponse.
• Usa ChatOpenAI com base_url=f"{FOUNDRY_PROJECT_ENDPOINT}/openai/v1" em vez de AzureChatOpenAI. Isto utiliza o endpoint com âmbito de projeto, que requer apenas permissões ao nível do projeto.
• O histórico de conversas é obtido através de context.get_history() e convertido para tipos de mensagem LangChain para suporte a múltiplas interações.
• A lógica do agente LangGraph (ferramentas, criação de grafos) mantém-se inalterada. Para controlo detalhado sobre chamadas de funções, itens de raciocínio ou múltiplos tipos de saída, use ResponseEventStream em vez de TextResponse.

Integração com a Caixa de Ferramentas MCP

Para conectar o seu agente LangGraph às ferramentas da Foundry Toolbox via MCP, use langchain-mcp-adapters dentro do handler. Carregar as ferramentas dinamicamente a partir do 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

Adicione estes pacotes ao seu requirements.txt:

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

Para amostras completas, consulte as amostras de agentes alojadas pelo LangGraph.

Migrar agentes personalizados ou BYO

Se usares CrewAI, Kernel Semântico ou outro código personalizado, usa diretamente a biblioteca de protocolos. As bibliotecas de protocolos são independentes do framework — tu tratas da orquestração, ferramentas e memória no teu próprio código.

Protocolo de respostas — Uso ResponsesAgentServerHost para agentes conversacionais. Registe o seu handler com o @app.response_handler decorator:

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 respostas de streaming, passe um iterável assíncrono para TextResponse. Para controlo detalhado sobre chamadas de funções, itens de raciocínio ou múltiplos tipos de saída, use ResponseEventStream em vez de TextResponse.

Protocolo de invocações — Uso InvocationAgentServerHost para agentes que necessitam de cargas úteis JSON arbitrárias (webhooks, processamento não conversacional). O manipulador usa diretamente os tipos 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()

O protocolo Invocations também suporta operações prolongadas com @app.get_invocation_handler e @app.cancel_invocation_handler para interrogação e cancelamento.

Escolha o seu protocolo com base no padrão de interação do seu agente. Veja O que são agentes alojados — Protocolos para orientação sobre qual protocolo utilizar.

Alteração do formato da versão do protocolo

O formato da versão do protocolo mudou de "v1" para semver "1.0.0":

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

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

APIs removidas

As seguintes APIs da pré-visualização inicial não estão disponíveis na pré-visualização atualizada:

Mapeamento de comandos CLI

Onde BASE_URL é https://{account}.services.ai.azure.com/api/projects/{project}.

Alterações ao método SDK

Alterações na invocação do agente

Na pré-visualização inicial, encaminhava para os agentes através de um endpoint de projeto partilhado, passando um agent_reference no corpo do pedido. Na pré-visualização atualizada, cada agente recebe um endpoint dedicado e o SDK associa-se automaticamente a ele.

Pré-visualização 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"}}
)

Pré-visualização atualizada:

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

O agent_name parâmetro indica ao SDK para direcionar o endpoint dedicado do agente. Para chamadas REST, use diretamente o endpoint do 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}'

Os endpoints ativos dependem dos protocolos que declara na definição da versão do seu agente. As rotas de Respostas e Conversas estão sob o espaço de nomes compatível com OpenAI em {project_endpoint}/agents/{name}/endpoint/protocols/openai/v1/{responses|conversations}, enquanto Invocações, Atividade e A2A roteiam diretamente em {project_endpoint}/agents/{name}/endpoint/protocols/{invocations|activityprotocol|a2a}.

Alterações de estado da versão

Os estados do ciclo de vida do agente mudaram de uma máquina de estados manual para estados de provisão automática:

Identidade e alterações no RBAC

O modelo de identidade mudou significativamente:

Ação necessária

1. Atualização das atribuições RBAC: A identidade gerida pelo projeto já não é a identidade de execução. Conceda funções RBAC para os recursos Azure subjacentes diretamente à identidade Entra do agente.
2. Simplificar as funções de implementação: É necessário Azure AI Project Manager no âmbito do projeto para criar e lançar agentes alojados.

Alterações no Azure Developer CLI

Comandos atualizados

Ação necessária

1. Atualize a extensão dos agentes Foundry:

   azd ext install azure.ai.agents
   

2. Se o seu agent.yaml especificar version: "v1" para as versões do protocolo, altere para version: "1.0.0".

Alterações na transmissão de logs

Lacunas conhecidas

As seguintes capacidades da pré-visualização inicial ainda não estão disponíveis na pré-visualização atualizada:

Lista de verificação de migração

Use esta lista de verificação para acompanhar a sua migração:

• Atualize azure-ai-projects o SDK para a versão 2.1.0 ou posterior.
• Utilizadores do Agent Framework: Atualizar os pacotes do Agent Framework (agent-framework-core, agent-framework-foundry, agent-framework-foundry-hosting, etc.). Substitua from_agent_framework(agent).run() por ResponsesHostServer(agent).run(). Atualize AzureAIAgentClient → FoundryChatClient, ChatAgent → Agente @ai_function → @tool.
• Utilizadores do LangGraph: Substituir azure-ai-agentserver-langgraph por azure-ai-agentserver-responses. Substitua from_langgraph(graph).run() por um ResponsesAgentServerHost handler que devolve um TextResponse. Use ChatOpenAI com o endpoint de âmbito de projeto em vez de AzureChatOpenAI. Adicionar langchain-mcp-adapters e mcp se estiver a usar o Foundry Toolbox.
• Utilizadores personalizados/BYO: Substituir pacotes adaptadores de framework por bibliotecas de protocolo (azure-ai-agentserver-responses ou azure-ai-agentserver-invocations). Reescrever os pontos de entrada do agente usando ResponsesAgentServerHost ou InvocationAgentServerHost.
• Atualize as strings de versão do protocolo de "v1" para "1.0.0" no código e agent.yaml.
• Atualize agent.yaml se estiver a usar azd (formato de versão do protocolo, remova quaisquer tools definições da definição do agente).
• Remover chamadas CLI de scripts e pipelines CI/CD; substituí-las por comandos az rest ou azd ai agent.
• Remover os passos de criação de host de capacidades dos scripts de provisionamento.
• Atualizar o código de invocação do agente — usar project.get_openai_client(agent_name=...) em vez de extra_body com agent_reference.
• Revise o RBAC — conceda acesso a recursos a jusante à identidade dedicada Entra do agente, não à identidade gerida pelo projeto.
• Atualize azd a extensão dos agentes Foundry para a versão mais recente.
• Constrói a imagem do contentor com --platform linux/amd64 (se já não o fizer).
• Reimplante o seu agente usando azd up ou o método SDK create_version .
• Verifica se a nova versão atingiu active o estado antes de enviar o tráfego.

Próximos passos

Conteúdo relacionado

• O que são agentes hospedados?
• Gerir agentes alojados
• Gerir sessões de agentes alojadas