Construa com agentes, conversas e respostas

Microsoft Foundry Agent Service utiliza três componentes principais de runtime—agents, conversas e respostas—para alimentar interações com estado e de múltiplas etapas. Um agente utiliza um modelo do catálogo de modelos da Foundry, juntamente com instruções e ferramentas. Uma conversa mantém o histórico ao longo das interações. Uma resposta é a saída que o agente produz quando processa a entrada.

Este artigo explica cada componente e mostra como os usar em conjunto no código. Vai aprender a criar um agente, iniciar uma conversa, gerar respostas (com ou sem agente), adicionar mensagens de seguimento e transmitir resultados — com exemplos em Python, C#, JavaScript, Java e API REST.

Como os componentes de runtime funcionam em conjunto

Quando trabalha com um agente, segue um padrão determinado:

  • Crie um agente: Defina um agente para começar a enviar mensagens e a receber respostas.
  • Crie uma conversa (opcional): Use uma conversa para manter o histórico entre turnos. Se não usares uma conversa, leva o contexto adiante usando o resultado de uma resposta anterior.
  • Gerar uma resposta: O modelo Foundry do agente processa os itens de entrada na conversa e quaisquer instruções fornecidas no pedido. O agente pode acrescentar itens à conversa.
  • Verifique o estado da resposta: Monitorize a resposta até terminar (especialmente em modo streaming ou em segundo plano).
  • Recuperar a resposta: Mostrar a resposta gerada ao utilizador.

O diagrama seguinte ilustra como estes componentes interagem num ciclo típico de agentes.

Diagrama que mostra o ciclo de execução do agente: uma definição do agente e a geração opcional de respostas a partir do histórico de conversas, que pode chamar ferramentas, adicionar itens de volta à conversa e produzir itens de saída que exibe ao utilizador.

Fornece a entrada do utilizador (e, opcionalmente, o histórico de conversas), o serviço gera uma resposta (incluindo chamadas de ferramenta quando configurado), e os itens resultantes podem ser reutilizados como contexto para o turno seguinte.

Pré-requisitos

Para analisar as amostras deste artigo, precisa de:

pip install "azure-ai-projects>=2.0.0"
pip install azure-identity

Criar um agente

Um agente é uma definição de orquestração persistente que combina modelos de IA, instruções, código, ferramentas, parâmetros e controlos opcionais de segurança ou governação.

Armazene os agentes como ativos nomeados e versionados no Microsoft Foundry. Durante a geração de respostas, a definição do agente trabalha com o histórico de interação (conversa ou resposta anterior) para processar e responder à entrada do utilizador.

O exemplo seguinte cria um agente de prompt com um nome, modelo e instruções. Usa o cliente do projeto para criação de agentes e versionamento.

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

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

# Create project client to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a prompt agent
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant.",
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

Nota

Os agentes são agora identificados usando o nome e a versão do agente. Já não têm um GUID chamado AgentID .

Para tipos adicionais de agentes (workflow, alojado), veja Ciclo de vida de desenvolvimento de agentes.

Crie um agente com ferramentas

As ferramentas estendem o que um agente pode fazer para além da geração de texto. Quando associa ferramentas a um agente, este pode chamar serviços externos, executar código, pesquisar ficheiros e aceder a fontes de dados durante a geração de respostas — usando ferramentas como pesquisa web ou chamada de funções.

Pode anexar uma ou mais ferramentas quando cria um agente. Durante a geração da resposta, o agente decide se chama uma ferramenta com base na entrada do utilizador e nas suas instruções. O exemplo seguinte cria um agente com uma ferramenta de pesquisa web anexada.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create an agent with a web search tool
agent = project.agents.create_version(
    agent_name="my-tool-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that can search the web.",
        tools=[WebSearchTool()],
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

Para a lista completa das ferramentas disponíveis, consulte a visão geral das ferramentas. Para melhores práticas, consulte Melhores práticas para o uso de ferramentas.

Gerar respostas

A geração de resposta invoca o agente. O agente utiliza a sua configuração e qualquer histórico fornecido (conversa ou resposta anterior) para realizar tarefas chamando modelos e ferramentas. Como parte da geração de respostas, o agente acrescenta itens à conversa.

Também pode gerar uma resposta sem definir um agente. Neste caso, forneces todas as configurações diretamente no pedido e usas-nas apenas para essa resposta. Esta abordagem é útil para cenários simples com ferramentas mínimas.

Além disso, podes fazer um fork da conversa no ID da primeira resposta ou no ID da segunda resposta

Gerar uma resposta com um agente

O exemplo seguinte gera uma resposta usando uma referência a um agente, e depois envia uma pergunta de seguimento usando a resposta anterior como contexto.

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"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Ask a follow-up question using the previous response
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    previous_response_id=response.id,
    input="What is the population of that city?",
)
print(follow_up.output_text)

Quando um agente utiliza ferramentas durante a geração da resposta, a saída da resposta contém itens de chamada de ferramenta juntamente com a mensagem final. Pode iterar sobre response.output para inspecionar cada item e mostrar invocações de ferramentas — como pesquisas na internet, chamadas de funções ou buscas de ficheiros — antes de apresentar a resposta em texto.

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

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

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

response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What happened in the news today?",
)

# Print each output item, including tool calls
for item in response.output:
    if item.type == "web_search_call":
        print(f"[Tool] Web search: status={item.status}")
    elif item.type == "function_call":
        print(f"[Tool] Function call: {item.name}({item.arguments})")
    elif item.type == "file_search_call":
        print(f"[Tool] File search: status={item.status}")
    elif item.type == "message":
        print(f"[Assistant] {item.content[0].text}")

Gerar uma resposta sem armazenar

Por defeito, o serviço armazena o histórico de respostas do lado do servidor, por isso podes consultar previous_response_id o contexto multi-turno. Se definires store para false, o serviço não persiste na resposta. Deve manter o contexto da conversa por si próprio, passando itens de saída anteriores como entrada para a próxima solicitação.

Esta abordagem é útil quando precisa de controlo total sobre o estado da conversa, quer minimizar dados armazenados ou trabalha num ambiente sem retenção de dados.

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

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

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

# Generate a response without storing
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
    store=False,
)
print(response.output_text)

# Carry forward context client-side by passing previous output as input
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input=[
        {"role": "user", "content": "What is the largest city in France?"},
        {"role": "assistant", "content": response.output_text},
        {"role": "user", "content": "What is the population of that city?"},
    ],
    store=False,
)
print(follow_up.output_text)

Conversas e elementos de conversa

As conversas são objetos duráveis com identificadores únicos. Depois de criar, podes reutilizá-los ao longo das sessões.

As conversas armazenam itens, que podem incluir mensagens, chamadas de ferramentas, saídas de ferramentas e outros dados.

Cria uma conversa

O exemplo seguinte cria uma conversa com uma mensagem inicial do utilizador. Use o cliente OpenAI (obtido do cliente do projeto) para conversas e respostas.

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"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation with an initial user message
conversation = openai.conversations.create(
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What is the largest city in France?",
        }
    ],
)
print(f"Conversation ID: {conversation.id}")

Quando usar uma conversa

Use uma conversa sempre que precisar:

  • Continuidade em múltiplos turnos: Mantém uma história estável ao longo dos turnos sem reconstruir o contexto por ti próprio.
  • Continuidade entre sessões: Reutilizar a mesma conversa para um utilizador que regressa mais tarde.
  • Depuração mais fácil: Inspecionar o que aconteceu ao longo do tempo (por exemplo, chamadas de ferramentas e saídas).

Quando uma conversa é usada para gerar uma resposta (com ou sem agente), a conversa completa é fornecida como entrada para o modelo. A resposta gerada é então anexada à mesma conversa.

Nota

Se a conversa exceder o tamanho do contexto suportado pelo modelo, o modelo truncará automaticamente o contexto de entrada. A conversa em si não é truncada, mas apenas um subconjunto dela é usado para gerar a resposta.

Se não criares uma conversa, ainda podes construir fluxos de múltiplos turnos usando o resultado de uma resposta anterior como ponto de partida para o próximo pedido. Esta abordagem dá-te mais flexibilidade do que o antigo padrão baseado em threads, onde o estado estava fortemente acoplado aos objetos thread. Para orientações sobre migração, consulte Migrar para o SDK dos Agentes.

Tipos de itens de conversa

As conversas armazenam itens em vez de apenas mensagens de chat. Os itens captam o que aconteceu durante a geração da resposta para que o turno seguinte possa reutilizar esse contexto.

Os tipos comuns de itens incluem:

  • Itens da mensagem: Mensagens do utilizador ou assistente.
  • Itens de invocação de ferramenta: Registos das invocações de ferramentas que o agente tentou.
  • Itens de saída de ferramentas: Resultados devolvidos pelas ferramentas (por exemplo, resultados de recuperação).
  • Itens de saída: O conteúdo de resposta que apresenta de volta ao utilizador.

Adicionar itens a uma conversa

Depois de criar uma conversa, use conversations.items.create() para adicionar mensagens de utilizador subsequentes ou outros itens.

# Add a follow-up message to an existing conversation
openai.conversations.items.create(
    conversation_id=conversation.id,
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What about Germany?",
        }
    ],
)

Use uma conversa com um agente

Combina uma conversa com uma referência de agente para manter o histórico ao longo de vários turnos. O agente processa todos os itens da conversa e anexa automaticamente o seu resultado.

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

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation for multi-turn chat
conversation = openai.conversations.create()

# First turn
response = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Follow-up turn in the same conversation
follow_up = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the population of that city?",
)
print(follow_up.output_text)

Para exemplos que mostram como as conversas e respostas funcionam em conjunto no código, veja Criar e usar memória no Foundry Agent Service.

Respostas de streaming e em segundo plano

Para operações de longa duração, pode devolver resultados incrementalmente usando streaming ou executar de forma totalmente assíncrona no modo background. Nestes casos, normalmente monitoriza a resposta até que termine e depois processa os últimos elementos de saída.

Transmita uma resposta

O streaming devolve resultados parciais à medida que são gerados. Esta abordagem é útil para mostrar a saída aos utilizadores em tempo real.

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"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Stream a response using the agent
stream = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Explain how agents work in one paragraph.",
    stream=True,
)
for event in stream:
    if hasattr(event, "delta") and event.delta:
        print(event.delta, end="", flush=True)

Para detalhes sobre modos de resposta e como consumir saídas, veja API de Respostas.

Execute um agente em modo de segundo plano

O modo em segundo plano executa o agente de forma assíncrona, o que é útil para tarefas de longa duração como raciocínio complexo ou geração de imagens. Defina background para true e depois faça sondagens para o estado da resposta até que esta termine.

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

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Start a background response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Write a detailed analysis of renewable energy trends.",
    background=True,
)

# Poll until the response completes
while response.status in ("queued", "in_progress"):
    sleep(2)
    response = openai.responses.retrieve(response.id)

print(response.output_text)

Anexar memória a um agente (prévia)

A memória dá aos agentes a capacidade de reter informação entre sessões, para que possam personalizar respostas e recordar as preferências do utilizador ao longo do tempo. Sem memória, cada conversa começa do zero.

O Foundry Agent Service fornece uma solução de memória gerida (versão prévia) que se configura através dos armazenamentos de memória. Um armazenamento de memória define que tipos de informação o agente deve reter. Anexe um armazenamento de memória ao seu agente, e o agente usa as memórias armazenadas como contexto adicional durante a geração da resposta.

O exemplo seguinte cria um armazenamento de memória e anexa-o a um agente.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    MemoryStoreDefaultDefinition,
    MemoryStoreDefaultOptions,
)

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a memory store
options = MemoryStoreDefaultOptions(
    chat_summary_enabled=True,
    user_profile_enabled=True,
)
definition = MemoryStoreDefaultDefinition(
    chat_model="gpt-5.2",
    embedding_model="text-embedding-3-small",
    options=options,
)
memory_store = project.beta.memory_stores.create(
    name="my_memory_store",
    definition=definition,
    description="Memory store for my agent",
)
print(f"Memory store: {memory_store.name}")

Para detalhes conceptuais, consulte Memória no Serviço de Agentes da Foundry. Para orientações completas de implementação, consulte Criar e usar memória.

Segurança e tratamento de dados

Como as conversas e respostas podem persistir conteúdos fornecidos pelo utilizador e resultados de ferramentas, trate os dados de execução como dados de aplicação:

  • Evite guardar segredos em prompts ou no histórico de conversas. Use ligações e armazenamentos secretos geridos em vez disso (por exemplo, Configurar uma ligação Key Vault).
  • Use o privilégio mínimo para acesso à ferramenta. Quando uma ferramenta acede a sistemas externos, o agente pode potencialmente ler ou enviar dados através dessa ferramenta.
  • Tenha cuidado com serviços não-Microsoft. Se o seu agente chamar ferramentas apoiadas por serviços que não sejam da serviços Microsoft, alguns dados podem fluir para esses serviços. Para considerações relacionadas, consulte Descobrir ferramentas na Ferramentas da Fundição.

Limites e restrições

Os limites podem depender do modelo, da região e das ferramentas que associa (por exemplo, disponibilidade de streaming e suporte a ferramentas). Para disponibilidade atual e restrições para respostas, consulte API de Respostas.

Conteúdo relacionado

  • Last updated on