Migrar agentes hospedados para a versão prévia pública atualizada

Este artigo orienta você na migração de agentes hospedados da visualização pública inicial para a visualização pública atualizada do Foundry Agent Service. A versão prévia atualizada apresenta um novo back-end de hospedagem, bibliotecas de protocolo, modelo de identidade e APIs de gerenciamento.

Este guia se aplica a você caso tenha implantado um agente hospedado antes de abril de 2026 usando os pacotes azure-ai-agentserver-agentframework ou azure-ai-agentserver-langgraph qualquer código personalizado que utilizou as APIs de hospedagem em versão prévia inicial.

O que mudou

A versão prévia atualizada implementa um modelo de sandbox baseado em sessão na plataforma existente. Principais alterações:

• Ciclo de vida de computação automática – não há início manual, interrupção ou gerenciamento de réplica. A plataforma provisiona a computação quando uma solicitação chega e a desprovisiona após 15 minutos de inatividade. Consulte o mapeamento de comando da CLI.
• Isolamento baseado em sessão — Cada sessão recebe seu próprio sandbox com armazenamento persistente $HOME e /files entre turnos e períodos ociosos.
• As bibliotecas de protocolo substituem adaptadores de estrutura — os pacotes de adaptador específicos da estrutura (azure-ai-agentserver-agentframework, azure-ai-agentserver-langgraph) são substituídos por bibliotecas específicas do protocolo (azure-ai-agentserver-responses, azure-ai-agentserver-invocations). Consulte Biblioteca de Protocolos e Migração de Framework.
• Identidade dedicada do agente a partir do tempo de implantação – cada agente recebe sua própria identidade Entra durante a criação, substituindo o modelo compartilhado de identidade gerenciada pelo projeto. Consulte as alterações de Identidade e RBAC.
• Ponto de extremidade do agente dedicado – cada agente obtém sua própria URL de ponto de extremidade (por exemplo, {project_endpoint}/agents/{name}/endpoint/protocols/openai/v1/responses). Você não precisa mais rotear por meio de um ponto de extremidade de projeto compartilhado com agent_reference no corpo da solicitação. Consulte as alterações de invocação do Agente.
• Novos protocolos — invocações, atividades e protocolos A2A ingressam no protocolo de respostas existente. Um único agente pode expor vários protocolos simultaneamente.
• API REST para ciclo de vida completo – cobertura REST completa para operações de agente, versão, sessão e arquivo. Consulte as alterações de método do SDK.
• Criação de host de capacidade removida — A plataforma gerencia o provisionamento de infraestrutura automaticamente. Você não precisa mais criar um host de capacidade no nível da conta. Consulte APIs removidas.

Pré-requisitos

• Azure SDK de Projetos de IA versão 2.1.0 ou posterior (era 2.0.0).

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

  azd ext install azure.ai.agents
  

Etapas de migração em um relance

As etapas a seguir resumem a migração de ponta a ponta. Cada um direciona para a seção detalhada.

1. Atualizar bibliotecas de protocolo e código do agente – substitua os adaptadores da estrutura pelas novas bibliotecas de protocolo e atualize o ponto de entrada do agente. Escolha seu caminho: Agent Framework, LangGraph ou custom/BYO.
2. Atualização de chamadas de API, CLI e SDK — Remove comandos de CLI obsoletos, atualiza métodos de SDK e migra para o ponto de extremidade de agente dedicado. Consulte APIs removidas, mapeamento de comando da CLI, alterações de método do SDK e alterações de invocação do Agente.
3. Atualização de identidade e RBAC — Concede acesso a recursos downstream à identidade Entra dedicada do agente. Consulte as alterações de Identidade e RBAC.
4. Atualizar as ferramentas da Azure Developer CLI — Instalar a mais recente azd Extensão e atualização dos agentes do Foundry agent.yaml. Consulte alterações da CLI do Desenvolvedor do Azure.
5. Reimplantar e verificar : crie sua imagem de contêiner, implante usando azd up ou o SDK e confirme se a versão atinge active o status.

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

Biblioteca de protocolos e migração de estrutura

A versão preliminar inicial utilizava pacotes adaptadores específicos da estrutura (azure-ai-agentserver-agentframework, azure-ai-agentserver-langgraph) que encapsulavam o código de seu agente. A versão prévia atualizada substitui-as por bibliotecas específicas do protocolo e pacotes de integração de estrutura atualizados.

Seu caminho de migração depende de qual estrutura você usa:

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

Alterações de pacote

Bibliotecas de protocolo (todos os usuários)

Pacotes do Agent Framework (somente usuários do Agent Framework)

Os pacotes do Agent Framework também foram atualizados para a versão prévia atualizada:

Migrar agentes do Agent Framework

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

Versão prévia 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()

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 dicas de tipo Annotated 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 é gerenciado pela plataforma de hospedagem.

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 obter exemplos, consulte os exemplos de agente hospedado do Agent Framework.

Migrar agentes do LangGraph

Se o agente usar o LangGraph, substitua o adaptador azure-ai-agentserver-langgraph pela biblioteca de protocolos azure-ai-agentserver-responses. A lógica do agente do LangGraph (definição de grafo, ferramentas, configuração de LLM) permanece a mesma: somente o ponto de entrada de hospedagem é alterado.

Versão prévia 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()

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() → Explicit ResponsesAgentServerHost com um @app.response_handler que retorna um TextResponse.
• Usa ChatOpenAI com base_url=f"{FOUNDRY_PROJECT_ENDPOINT}/openai/v1" em vez de AzureChatOpenAI. Isso usa o ponto de extremidade com escopo de projeto, que requer apenas permissões em nível de projeto.
• O histórico de conversas é obtido via context.get_history() e convertido em tipos de mensagem LangChain para suporte a múltiplas interações.
• A lógica do agente do LangGraph (ferramentas, criação de grafo) não é alterada. Para controle refinado sobre chamadas de função, itens de raciocínio ou vários tipos de saída, use ResponseEventStream em vez de TextResponse.

Integração da Caixa de Ferramentas do MCP

Para conectar seu agente LangGraph às ferramentas do Foundry Toolbox via MCP, use langchain-mcp-adapters dentro de seu manipulador. Carregue ferramentas dinamicamente a partir do endpoint do 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 obter exemplos completos, consulte os exemplos de agente hospedado do LangGraph.

Migrar agentes personalizados ou BYO

Se você usar CrewAI, Kernel semântico ou outro código personalizado, use a biblioteca de protocolos diretamente. As bibliotecas de protocolo são independentes da estrutura– você lida com orquestração, ferramentas e memória em seu próprio código.

Protocolo de respostas – Uso ResponsesAgentServerHost para agentes de conversação. Registre seu manipulador com o decorador @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()

Para respostas de streaming, passe uma iterável assíncrona para TextResponse. Para controle refinado sobre chamadas de função, itens de raciocínio ou vários tipos de saída, use ResponseEventStream em vez de TextResponse.

Protocolo de Invocações — use InvocationAgentServerHost para agentes que precisam de cargas JSON arbitrárias (webhooks, processamento não conversacional). O manipulador usa os tipos Starlette Request/Response diretamente.

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 de longa duração com @app.get_invocation_handler e @app.cancel_invocation_handler para sondagem e cancelamento.

Escolha seu protocolo com base no padrão de interação do agente. Veja o que são agentes hospedados – Protocolos para orientação sobre qual protocolo usar.

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

O formato de versão do protocolo foi alterado 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 versão prévia inicial não estão disponíveis na versão prévia atualizada:

Mapeamento de comando da CLI

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

Alterações no método SDK

Alterações na invocação do agente

Na versão preliminar inicial, você roteava para agentes por meio de um ponto de extremidade de projeto compartilhado, passando um agent_reference no corpo da solicitação. Na versão prévia atualizada, cada agente obtém um ponto de extremidade dedicado e o SDK é associado a ele automaticamente.

Versão prévia 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"}}
)

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 informa ao SDK que ele deve direcionar o endpoint dedicado do agente. Para chamadas REST, use o endpoint do agente diretamente.

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 pontos de extremidade ativos dependem dos protocolos que você declara na definição de versão do agente. As rotas de Respostas e Conversas residem no namespace compatível com OpenAI em {project_endpoint}/agents/{name}/endpoint/protocols/openai/v1/{responses|conversations}, enquanto Invocations, Activity e A2A roteiam diretamente em {project_endpoint}/agents/{name}/endpoint/protocols/{invocations|activityprotocol|a2a}.

Alterações de status de versão

Os estados do ciclo de vida do agente foram alterados de uma máquina de estados manual para estados de provisionamento automático:

Alterações de identidade e RBAC

O modelo de identidade foi alterado significativamente:

Ação necessária

1. Atualizar atribuições de RBAC: a identidade gerenciada pelo projeto não é mais a identidade de tempo de execução. Conceda funções de RBAC para quaisquer recursos do Azure downstream diretamente à identidade Entra do agente.
2. Simplifique os papéis de implantação: você precisa de Azure AI Project Manager no escopo do projeto para criar e implantar agentes hospedados.

Alterações na CLI do Desenvolvedor do Azure

Comandos atualizados

Ação necessária

1. Atualize a extensão de agentes do Foundry:

   azd ext install azure.ai.agents
   

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

Alterações de streaming de log

Lacunas conhecidas

Os seguintes recursos da versão prévia inicial ainda não estão disponíveis na versão prévia atualizada:

Lista de verificação de migração

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

• Atualize azure-ai-projects o SDK para a versão 2.1.0 ou posterior.
• Usuários do Agent Framework: atualizar pacotes do Agent Framework (agent-framework-core, agent-framework-foundry, agent-framework-foundry-hostingetc.). Substitua from_agent_framework(agent).run() por ResponsesHostServer(agent).run(). Atualizar AzureAIAgentClient → FoundryChatClient, ChatAgent → Agente @ai_function → @tool.
• Usuários do LangGraph: substitua por azure-ai-agentserver-langgraphazure-ai-agentserver-responses. Substitua from_langgraph(graph).run() por um ResponsesAgentServerHost manipulador que retorna um TextResponse. Use ChatOpenAI com o ponto de extremidade com escopo de projeto em vez de AzureChatOpenAI. Adicionar langchain-mcp-adapters e mcp se estiver usando a Caixa de Ferramentas do Foundry.
• Usuários personalizados/BYO: substitua pacotes de adaptador de estrutura por bibliotecas de protocolo (azure-ai-agentserver-responses ou azure-ai-agentserver-invocations). Reescreva 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 em agent.yaml.
• Atualize agent.yaml se estiver usando azd (formato de versão do protocolo, remova todas as definições tools da definição do agente).
• Remova as chamadas de CLI az cognitiveservices agent dos scripts e pipelines de CI/CD; substitua-as por comandos az rest ou azd ai agent.
• Remova as etapas de criação de hosts de capacidade dos scripts de provisionamento.
• Atualizar código de invocação do agente — use project.get_openai_client(agent_name=...) em vez de extra_body com agent_reference.
• Revise o RBAC — conceda acesso a recursos downstream à identidade Entra dedicada do agente, e não à identidade gerenciada pelo projeto.
• Atualize azd a extensão de agentes do Foundry para a versão mais recente.
• Crie uma imagem de contêiner com --platform linux/amd64 (se ainda não estiver).
• Reimplante seu agente usando azd up ou o método SDK create_version .
• Verifique se a nova versão alcança o status active antes de enviar o tráfego.

Próximas etapas

Conteúdo relacionado

• O que são agentes hospedados?
• Gerenciar agentes hospedados
• Gerenciar sessões de agente hospedado