Migrar para a nova experiência de desenvolvimento de agentes

Dica

Existe uma ferramenta de migração disponível para ajudar a automatizar a migração da API dos Assistentes para os Agentes.

O Foundry Agent Service oferece uma experiência de programador melhorada para construir agentes inteligentes que são fáceis de construir, versionar, operar e observar. A nova API dos agentes introduz um SDK modernizado, novas capacidades de nível empresarial e preserva as funcionalidades de identidade, governação e observabilidade em que se depende hoje.

Pré-requisitos

  • Uma subscrição do Azure. Crie um gratuitamente.
  • Um projeto Microsoft Foundry.
  • O SDK do Serviço Foundry Agent para a sua linguagem de programação e o pacote de identidade correspondente para autenticação. Instale os pacotes para a sua língua e inicie sessão com az login ou use DefaultAzureCredential:
pip install "azure-ai-projects>=2.0.0"
  • Código de agentes ou assistentes existentes que pretende migrar.

O código seguinte inicializa os clientes utilizados ao longo deste guia:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

Use project para criação de agentes e versionamento. openai (ou o equivalente na sua língua) para conversas e respostas.

Principais benefícios

Os novos agentes oferecem os seguintes benefícios:

Produtividade dos programadores

  • Mais modelos. Gera respostas usando qualquer modelo Foundry, seja no seu agente ou diretamente como uma chamada de geração de resposta.
  • Mais funcionalidades. Pesquisa Web, Pesquisa de Ficheiros, Interpretador de Código, chamada de ferramentas MCP, geração de imagens e resumos de raciocínio.
  • API primitiva moderna. Construído sobre a API Responses em vez da antiga API Assistants.
  • Modo de fundo. Suporte para ferramentas de longa duração (como geração de imagens) e fluxos duráveis (suporta cenários de desconexão/reconexão)
  • À prova de futuro. Novas funcionalidades e suporte a modelos apenas são adicionados aos novos agentes.
  • Novos tipos de agentes. Crie agentes baseados em prompts, agentes baseados em fluxos de trabalho (pré-visualização) e agentes alojados (pré-visualização).

Prontidão empresarial

  • Armazenamento de inquilino único. Utilize armazenamento de inquilino único, com a opção de usar o seu próprio Azure Cosmos DB para armazenar o estado e manter os seus dados seguros.
  • Segurança reforçada. Controla quem pode executar ou modificar definições de agentes.
  • Separação de funções. Define agentes uma vez e executa-os com vários inputs.
  • Agentes de implementação. Os agentes podem ser expostos como pontos terminais individuais.

Modernização de APIs

  • Melhor gestão do estado. Usa conversas em vez de threads e mensagens.
  • Contexto com estado. Retém automaticamente o contexto entre chamadas.
  • Superconjunto de APIs de Respostas. Baseia-se na API Responses e adiciona mais capacidades.
  • Fluxos de trabalho de um ou múltiplos agentes. Encadear agentes facilmente para fluxos de trabalho complexos.

Alterações principais

A tabela seguinte resume as principais alterações na API entre a experiência anterior e a atual do agente.

Antes Depois Detalhes
Fios Conversas Suporta fluxos de itens, não apenas mensagens.
Corridas Respostas As respostas enviam itens de entrada ou usam um objeto de conversa e recebem itens de saída. Os loops de chamadas de ferramenta são explicitamente geridos.
Assistentes / agentes Agentes (novo) Suporte para prompts preparados para uso empresarial, fluxos de trabalho e agentes alojados com contexto de estado por padrão para qualquer modelo Foundry.

Disponibilidade de ferramentas para agentes

A tabela seguinte compara as ferramentas para agentes disponíveis nos agentes clássicos e no novo Serviço de Agentes da Foundry. Use-o para identificar que ferramentas são transferidas diretamente, quais mudaram e quais são exclusivas da nova experiência.

Ferramenta Fundição (clássico) Fundição (nova)
Agente para Agente (A2A) Não Sim (Pré-visualização pública)
Pesquisa de IA do Azure Sim (GA) Sim (GA)
Funções do Azure Sim (GA) Não
Automação de Navegadores Sim (Pré-visualização pública) Sim (Pré-visualização pública)
Interpretador de Código Sim (GA) Sim (GA)
Utilização de computadores Sim (Pré-visualização pública) Sim (Pré-visualização pública)
Agentes Ligados Sim (Pré-visualização pública) Não (Recomendação: Workflow e ferramenta A2A)
Investigação Aprofundada Sim (Pré-visualização pública) Não (Recomendação: Modelo de Pesquisa Profunda com ferramenta de Pesquisa Web)
Agente de Dados Fabric Sim (Pré-visualização pública) Sim (Pré-visualização pública)
Pesquisa de ficheiros Sim (GA) Sim (GA)
Função Sim (GA) Sim (GA)
Aterramento com a Pesquisa Bing Sim (GA) Sim (GA)
Aterramento com Pesquisa Personalizada do Bing Sim (Pré-visualização pública) Sim (Pré-visualização pública)
Geração de Imagem Não Sim (Pré-visualização pública)
MCP Sim (Pré-visualização pública) Sim (GA)
OpenAPI Sim (GA) Sim (GA)
Fundamentos do SharePoint Sim (Pré-visualização pública) Sim (Pré-visualização pública)
Pesquisa na Web Não Sim (GA)

Importante

Na nova API, as APIs de conversas e respostas utilizam o cliente OpenAI (ou o seu equivalente linguístico). Em Python, chame project.get_openai_client(). Em C#, usa projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(). Em JavaScript, chame projectClient.getOpenAIClient(). Em Java, use AgentsClientBuilder para construir um ResponsesClient. A criação de agentes e a versão mantêm-se no cliente do projeto. Os exemplos em cada secção mostram qual cliente usar.

Migrar tópicos para conversas

Os Threads armazenavam mensagens do lado do servidor. Uma conversa pode armazenar itens, incluindo mensagens, chamadas de ferramentas, saídas de ferramentas e outros dados.

Pedidos

Os exemplos seguintes comparam a criação de threads (anterior) com a criação de conversas (atual). A abordagem atual utiliza o cliente OpenAI obtido de project.get_openai_client().

Anteriores - tópicos

thread = client.agents.threads.create( 
     messages=[{"role": "user", "content": "Tell me a one line funny story about unicorns"}], 
     metadata={"agent": "my-awesome-agent"}, 
) 

Atual - conversas

conversation = openai.conversations.create(
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "Tell me a one line funny "
                       "story about unicorns",
        }
    ],
    metadata={"agent": "my-awesome-agent"},
)

Respostas

As respostas JSON mostram as diferenças estruturais entre objetos thread e objetos de conversa.

Anteriores - tópicos

{ 
  "id": "thread_1234abcd",  
  "object": "thread",  
  "created_at": 1762217858,  
  "metadata": {"agent": "my-awesome-agent"},  
  "tool_resources": {} 
} 

Atual - conversas

{ 
  "id":"conv_1234abcd", 
  "created_at":1762217961, 
  "metadata":{"agent":"my-awesome-agent"}, 
  "object":"conversation" 
} 

Adicionar itens a uma conversa existente

Depois de criar uma conversa, use conversations.items.create() para adicionar mensagens seguintes. Este padrão substitui a adição de mensagens a threads por client.agents.messages.create().

Anterior - adicionar uma mensagem a um tópico

message = client.agents.messages.create(
    thread_id=thread.id,
    role="user",
    content="Follow-up question about the same topic",
)

Atual - adicionar itens a uma conversa

openai.conversations.items.create(
    conversation_id=conversation.id,
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "Follow-up question "
                       "about the same topic",
        }
    ],
)

Migrar execuções para respostas

As execuções de tarefas eram processos assíncronos que operavam com threads. As respostas são mais simples: fornecem um conjunto de itens de entrada para executar e recebem uma lista de itens de saída de volta. As respostas podem ser usadas sozinhas ou com objetos de conversa para armazenar contexto. A API de respostas utiliza o cliente OpenAI.

Pedidos

Os exemplos seguintes comparam a forma como invocas a lógica do agente. A abordagem anterior usava execuções assíncronas com polling. A abordagem atual chama responses.create() no cliente OpenAI.

Execuções anteriores

thread_id = "thread_abcd1234" 
assistant_id = "asst_efgh5678" 
run = project_client.agents.runs.create( 
  thread_id=thread_id,  
  agent_id=assistant_id, 
  additional_instructions="Please address the user as Jane Doe. The user has a premium account" 
) 
while run.status in ("queued", "in_progress"): 
  time.sleep(1) 
  run = project_client.agents.runs.get(thread_id=thread_id, run_id=run.id) 

Respostas Atuais

conversation_id = "conv_11112222AAAABBBB"

response = openai.responses.create(
    input="Hi, Agent! Draw a graph for a line "
          "with a slope of 4 and "
          "y-intercept of 9.",
    conversation=conversation_id,
    extra_body={
        "agent_reference": {
            "name": "my-agent",
            "type": "agent_reference",
        }
    },
)

Respostas

Execuções anteriores

{
  "id": "run_xyz",
  "object": "thread.run",
  "created_at": 1762218810,
  "assistant_id": "asst_efgh5678",
  "thread_id": "thread_abcd1234",
  "status": "completed",
  "started_at": 1762218810,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1762218812,
  "required_action": null,
  "last_error": null,
  "model": "gpt-4.1",
  "instructions": "You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers. Please address the user as Jane Doe. The user has a premium account",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "tool_resources": {},
  "metadata": {},
  "temperature": 1.0,
  "top_p": 1.0,
  "max_completion_tokens": null,
  "max_prompt_tokens": null,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "incomplete_details": null,
  "usage": {
    "prompt_tokens": 1216,
    "completion_tokens": 76,
    "total_tokens": 1292,
    "prompt_token_details": {
      "cached_tokens": 0
    }
  },
  "response_format": "auto",
  "tool_choice": "auto",
  "parallel_tool_calls": true
}

Respostas Atuais

{
  "id": "resp_3483e9c8dda4f165006909550333588190afc76a645a0e877a",
  "created_at": 1762219267.0,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "metadata": {
    "x-ms-telemetry-agent-kind": "",
    "x-ms-telemetry-user-agent": "OpenAI/Python 2.4.0",
    "x-ms-telemetry-response-start-time": "2025-11-04T01:21:06.5346780+00:00"
  },
  "model": "gpt-4.1",
  "object": "response",
  "output": [
    {
      "id": "msg_3483e9c8dda4f1650069095503abf881909917865574cddf2c",
      "content": [
        {
          "annotations": [],
          "text": "Of course! Here's a simple plot for the line with a rate of change of 4 and a y-intercept of 9.\\n\\nThe equation of the line is:\\n\\n\\\\[ y = 4x + 9 \\\\]\\n\\nLet's draw a graph for it:\\n\\n---\\n\\n```plaintext\\n  |\\n20|                     *\\n  |                  *\\n  |               *\\n  |            *\\n10|         *\\n  |      *\\n  |   *\\n  |*\\n  +---------------------------\\n   -2 -1  0  1  2  3\\n```\\n\\n**Key points:**\\n- The y-intercept is **9**, so at \\\\(x = 0\\\\), \\\\(y = 9\\\\) (point: (0,9))\\n- For each step right (increase in x), y goes up 4 units (rate of change \\\\(m = 4\\\\))\\n  - For \\\\(x = 1\\\\): \\\\(y = 4(1) + 9 = 13\\\\) (point: (1,13))\\n  - For \\\\(x = -1\\\\): \\\\(y = 4(-1) + 9 = 5\\\\) (point: (-1,5))\\n\\nIf you'd like a precise graph or want to visualize it interactively, let me know!",

          "type": "output_text",
          "logprobs": []
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "temperature": 1.0,
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "background": false,
  "conversation": {
    "id": "conv_3483e9c8dda4f16500GwcAgtdWlSmbMPzYLjWvDjiSe6LSFcC6"
  },
  "max_output_tokens": null,
  "max_tool_calls": null,
  "previous_response_id": null,
  "prompt": null,
  "prompt_cache_key": null,
  "reasoning": {
    "effort": null,
    "generate_summary": null,
    "summary": null
  },
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "top_logprobs": 0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 45,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 264,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 309
  },
  "user": null,
  "content_filters": null,
  "store": true
}

Migrar agentes clássicos para novos agentes

Se usar o client.agents.create_agent() método das versões anteriores do SDK, migre para client.agents.create_version(). O novo método introduz definições estruturadas de agentes com campos explícitos kind, model, e instructions .

Pedidos

Anterior

agent = client.agents.create_agent( 
    model="gpt-4.1", 
    name="my-agent",  # Name of the agent 
    instructions="You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.",  # Instructions for the agent 
    tools=code_interpreter.definitions,  # Attach the tool 
) 

Atualidade

from azure.ai.projects.models import (
    CodeInterpreterTool,
    PromptAgentDefinition,
)

agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1",
        instructions=(
            "You politely help with math "
            "questions. Use the Code "
            "Interpreter tool when asked to "
            "visualize numbers."
        ),
        tools=[CodeInterpreterTool()],
    ),
)

Respostas

Os seguintes exemplos de JSON comparam os objetos de resposta retornados pelos métodos de criação de agentes anteriores e atuais.

Anterior

{ 
  'id': 'asst_AVKrdr2KJthDnZiJ51nca1jy', 
  'object': 'assistant', 
  'created_at': 1762218496, 
  'name': 'my-agent', 
  'description': None, 
  'model': 'gpt-4.1', 
  'instructions': 'You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.', 
  'tools': [ 
    { 
      'type': 'code_interpreter' 
    } 
  ], 
  'top_p': 1.0, 
  'temperature': 1.0, 
  'tool_resources': { 
    'code_interpreter': { 
      'file_ids': [      
      ] 
    } 
  }, 
  'metadata': { 
  }, 
  'response_format': 'auto' 
} 

Atualidade

{
  "metadata": {},
  "object": "agent.version",
  "id": "code-agent:1",
  "name": "code-agent",
  "version": "1",
  "description": "Agent with code interpreter",
  "created_at": 1772045947,
  "definition": {
    "kind": "prompt",
    "model": "gpt-4.1",
    "instructions": "You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.",
    "tools": [
      {
        "type": "code_interpreter"
      }
    ]
  }
}

Migrar assistentes para novos agentes

Se o seu código usar a API OpenAI Assistants (client.beta.assistants.create()), migre para o Foundry Agent Service usando client.agents.create_version(). Os exemplos seguintes mostram as diferenças estruturais.

Anteriormente - assistentes

assistant = client.beta.assistants.create( 
    model="gpt-4.1", 
    name="my-assistant", 
    instructions="You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.",  # Instructions for the agent 
    tools=[{"type": "code_interpreter"}], 
) 

Atuais - novos agentes

from azure.ai.projects.models import (
    CodeInterpreterTool,
    PromptAgentDefinition,
)

agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1",
        instructions=(
            "You politely help with math "
            "questions. Use the Code "
            "Interpreter tool when asked to "
            "visualize numbers."
        ),
        tools=[CodeInterpreterTool()],
    ),
)

Execute a ferramenta de migração

Uma ferramenta migração está disponível no GitHub para ajudar a automatizar a migração dos seus agentes e assistentes. A ferramenta migra construções de código como definições de agentes, criação de threads, criação de mensagens e criação de execuções. Não migra dados de estado, como execuções passadas, tópicos ou mensagens. Após a migração, podes executar o novo código, e quaisquer novos dados de estado são criados no formato atualizado.

O exemplo seguinte mostra uma comparação completa de antes e depois. Note que o código atual é usado tanto project para criação de agentes como openai para conversas e respostas.

Anterior

agent = project_client.agents.create_agent( 
    model="gpt-4.1", 
    name="my-agent", 
    instructions="You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.",  # Instructions for the agent 
    tools=[{"type": "code_interpreter"}] 
) 
thread = project_client.agents.threads.create() 
message = project_client.agents.messages.create( 
    thread_id=thread.id, 
    role="user",  # Role of the message sender 
    content="Hi, Agent! Draw a graph for a line with a rate of change of 4 and y-intercept of 9.",  # Message content 
) 
run = project_client.agents.runs.create_and_process( 
    thread_id=thread.id, 
    agent_id=agent.id, 
    additional_instructions="Please address the user as Jane Doe. The user has a premium account", 
) 
messages = project_client.agents.messages.list(thread_id=thread.id) 
for message in messages: 
    print(f"Role: {message.role}, Content: {message.content}") 

Atualidade

from azure.ai.projects.models import (
    CodeInterpreterTool,
    PromptAgentDefinition,
)

# Create the agent
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1",
        instructions=(
            "You politely help with math "
            "questions. Use the Code "
            "Interpreter tool when asked "
            "to visualize numbers."
        ),
        tools=[CodeInterpreterTool()],
    ),
)

# Create a conversation with initial message
conversation = openai.conversations.create(
    items=[
        {
            "type": "message",
            "role": "user",
            "content": (
                "Hi, Agent! Draw a graph "
                "for a line with a rate "
                "of change of 4 and "
                "y-intercept of 9."
            ),
        }
    ],
)

# Send a response with the agent
response = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": agent.name,
            "type": "agent_reference",
        }
    },
    input=(
        "Please address the user as "
        "Jane Doe. The user has a "
        "premium account"
    ),
)

# Print the response output
for item in response.output:
    if item.type == "message":
        for block in item.content:
            print(block.text)

Verifique a sua migração

Depois de migrar o seu código, confirme que tudo funciona corretamente:

  1. Executa o código atualizado e verifica se corre sem erros.
  2. Verifique a criação do agente confirmando que create_version() devolve um objeto com os campos id e version.
  3. Teste uma conversa criando uma conversa, enviando uma resposta e verificando que os itens de saída são devolvidos.
  4. Confirme a retenção do contexto enviando múltiplas respostas à mesma conversa e verificando se o agente se lembra das mensagens anteriores.

Resolver problemas comuns

Sintoma Causa Resolução
Python: AttributeError: 'AIProjectClient' has no attribute 'conversations' Executou conversations.create() no cliente do projeto em vez do cliente OpenAI. Use project.get_openai_client() para obter o cliente OpenAI, depois chame openai.conversations.create().
C#: Azure.AI.Extensions.OpenAI espaço de nomes não encontrado O pacote NuGet Azure.AI.Extensions.OpenAI está em falta. Instala Azure.AI.Projects (que inclui Azure.AI.Extensions.OpenAI e Azure.AI.Projects.Agents como dependências).
JavaScript: getOpenAIClient is not a function Estás a usar uma versão mais antiga de @azure/ai-projects. Atualização para @azure/ai-projects@2.0.0 ou posterior: npm install @azure/ai-projects@2.0.0.
Java: AgentsClientBuilder não consegue resolver A dependência do azure-ai-agents Maven está ausente ou desatualizada. Adiciona com.azure:azure-ai-agents:2.0.0 às tuas dependências pom.xml.
create_agent() é removido Versões anteriores do SDK usavam create_agent(), que foi removido na v2.0.0. Substitui por create_version() (Python/JS) ou CreateAgentVersionAsync() (C#) ou createAgentVersion() (Java) e passa um objeto PromptAgentDefinition.
Os dados antigos da thread não estão disponíveis A ferramenta de migração não migra dados de estado (execuções anteriores, threads ou mensagens). Inicia novas conversas após a migração. Os dados históricos permanecem acessíveis através da API anterior até serem obsoletos.
responses.create() gera um erro de modelo O nome do modelo pode estar incorreto ou não estar disponível na sua região. Verifique o nome do modelo no seu projeto Foundry e verifique a disponibilidade da região do modelo.