Criando Agentes de IA Conversacional com Azure AI Foundry

O Azure AI Foundry, da Microsoft, simplifica o desenvolvimento de IA ao oferecer uma plataforma unificada para criar, implantar e gerenciar aplicações inteligentes. Funciona como o seu hub de desenvolvimento de IA, reunindo modelos de linguagem, gestão de dados e ferramentas de implantação em um único ambiente. A plataforma abstrai a complexidade do desenvolvimento de IA sem abrir mão da flexibilidade que os desenvolvedores precisam para criar soluções sofisticadas.

Vamos começar com uma interação básica de chat para entender os recursos fundamentais de conversação de um modelo de linguagem grande. Depois, vamos explorar o Azure AI Foundry Agent Service, no qual é possível criar agentes especializados para lidar com tarefas específicas, manter o contexto da conversa e fazer integração com fontes de dados externas.

Vou mostrar como criar rapidamente um agente básico que depende apenas dos seus dados de treinamento e, em seguida, uma versão aprimorada que incorpora outras fontes de conhecimento para entregar respostas mais precisas. Por fim, vamos demonstrar um exemplo prático em Python que mostra como integrar esses agentes diretamente nas suas aplicações para criar soluções escaláveis e inteligentes.

Ecossistema do Azure AI Foundry

Componentes de um Agente de IA

Neste exemplo, vamos fazer a configuração padrão do Azure AI Foundry e de um Agent Service usando o Portal do Azure. Os pré-requisitos para começar são apenas algumas permissões depois que você acessa sua assinatura do Azure.

• Tenha acesso a uma assinatura do Azure — você pode começar gratuitamente.
• Garanta que você tenha as funções Azure AI Account Owner e Azure AI Project Manager no escopo da assinatura.
• Se for fazer uma configuração padrão do Azure AI Foundry, garanta que você tenha permissão para atribuir funções a quaisquer recursos necessários (Cosmos DB, Azure AI Search, Azure Blob Storage). Para mais informações sobre funções de RBAC específicas do Azure AI Foundry Agent Service, consulte Azure AI Foundry Agent Service RBAC roles. A função interna necessária é Role Based Access Administrator, que concede a permissão-chave Microsoft.Authorization/roleAssignments/write
• Se aparecerem erros sobre registros ausentes ou provedores não registrados, é preciso registrar o provedor mencionado na mensagem de erro.

Implantando o Projeto e o Agente de IA básico

Use este modelo de implantação personalizado para provisionar o projeto e o agente do Azure AI Foundry necessários.

https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fazure-ai-foundry%2Ffoundry-samples%2Frefs%2Fheads%2Fmain%2Fsamples%2Fmicrosoft%2Finfrastructure-setup%2F40-basic-agent-setup%2Fbasic-setup.json

O link abre no Portal do Azure e cria um projeto do Azure AI Foundry, em que você pode trabalhar em um ambiente independente para colocar suas ideias de IA em prática rapidamente, criar protótipos e muito mais.

Selecione a assinatura e o grupo de recursos, preencha os outros campos (incluindo a localização) e deixe todos os campos relacionados ao modelo como estão. Isso fornece os detalhes para criar o projeto e implantar um modelo GPT-4o.

Clique no botão ‘Review + create’ para implantar o modelo. Leva alguns minutos para concluir.

Formulário do modelo de implantação para criar recursos do Azure AI Foundry

Quando a implantação terminar, clique em ‘Go to resource group’ para visualizar os recursos.

Grupo de recursos exibindo o projeto implantado

Clicando no link do projeto, você vai para o portal do Azure AI Foundry.

Link para acessar o projeto

Conversando com o modelo

Ao acessar o portal do Azure AI Foundry, se ele não levar você direto para o Playground do seu projeto, selecione o nome do projeto na página principal e, em seguida, clique em Playgrounds. Isso seleciona automaticamente a implantação do gpt-4o, e você já pode começar a conversar com o modelo. Teste alguns prompts e veja o que aparece. Experimente também instruções diferentes, restrinja as respostas a um determinado tópico ou adicione uma fonte de dados para complementar o modelo com seus próprios dados.

Por exemplo, instruí o modelo a responder apenas sobre terremotos e, em seguida, pedi uma receita.

Chat playground com instruções de exemplo para o modelo

Implantando o chatbot como aplicação web

Um recurso bem legal é poder implantar um chatbot simples como aplicação web. A implantação leva alguns minutos e, depois, é só clicar no link para abrir a aplicação web e testá-la. Vale lembrar que ainda há bastante coisa para ajustar antes de deixar algo assim pronto para produção, mas o exemplo mostra como é fácil criar um app web básico de chat.

Ao lado do botão ‘View code’, no topo da interface do Chat playground, selecione ‘Deploy as web app’.

Implantar o chatbot como aplicação web

Para abrir a aplicação web depois da implantação, vá em ‘My assets/Web apps’ e clique no link da aplicação implantada.

Abrindo a aplicação web

Repare que, no Chat playground, ao definir as instruções do modelo, restringi as respostas apenas a perguntas sobre terremotos. Como dá para ver na interface de chat da aplicação web, o modelo se recusou a contar uma piada, mas respondeu à pergunta sobre terremotos. Porém, o modelo foi treinado apenas com dados até outubro de 2023; então, na próxima seção, vou mostrar como complementá-lo com uma fonte de dados personalizada sem precisar treiná-lo novamente.

Exemplo da aplicação web do chatbot

Usando um agente para conversar com o modelo

Criando um agente simples

Agora que você já entende bem como funciona conversar com um modelo, vamos turbinar isso com um agente que encapsula essa funcionalidade. Em seguida, vamos complementar o conhecimento do modelo com uma fonte de dados personalizada e chamar esse agente em um exemplo simples em Python.

Selecione ‘Agents/New Agent’ para criar um novo agente. Defina um nome e um conjunto de instruções. As instruções são obrigatórias e devem ser específicas sobre o que o agente deve fazer — neste caso, será um agente que só responde a perguntas sobre terremotos. Você pode deixar Deployment como gpt-4o (padrão), e os valores padrão de Temperature e Top P estão bons assim. As alterações na configuração do agente são salvas automaticamente.

Configuração do agente para conversar sobre terremotos

Clicando no botão ‘Try in playground’, você consegue testar o agente da mesma forma que conversou diretamente com o modelo antes.

Complementando o agente com conhecimento adicional

O Azure AI Foundry oferece várias opções para integrar dados personalizados às suas aplicações e serviços de IA. Esse tema vai além do escopo deste artigo, mas você encontra mais informações aqui.

Como exemplo simples, vou adicionar um arquivo PDF como fonte de dados para enriquecer o conhecimento do meu agente sobre terremotos. Baixei uma cópia em PDF do artigo da Wikipédia sobre o terremoto da Península de Kamchatka de 2025, que você pode baixar aqui caso queira acompanhar e usá-lo no seu agente.

Com o PDF em mãos, clique no botão ‘+Add’ em Knowledge na configuração do agente e selecione ‘Files’ para fazer o upload. Mantenha os padrões para criar um novo vector store e, em seguida, clique em ‘Upload and save’.

PDF carregado para complementar o agente com mais conhecimento sobre terremotos

Ao clicar de novo em ‘Try in playground’, desta vez você já pode perguntar sobre o terremoto de julho de 2025.

Conversando com o agente após a inclusão da fonte de dados

Agora que você já entende bem como funciona um agente básico no Azure AI Foundry, vamos testar um código em Python que acessa o endpoint do modelo diretamente. Mas, antes, copie o endpoint do projeto do Azure AI Foundry na página Overview e o Agent ID na página do agente.

Página Overview mostrando o endpoint do projeto do Azure AI Foundry

Página do agente mostrando o Agent ID

Salve este código localmente em um arquivo chamado agent_earthquake_chat.py. É um exemplo simples e descontraído em Python, longe de estar pronto para produção :)

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import ListSortOrder

import os

endpoint = os.getenv("AZURE_FOUNDRY_ENDPOINT")
agent_id = os.getenv("AZURE_FOUNDRY_AGENT_ID")

if not endpoint or not agent_id:
    raise EnvironmentError("AZURE_FOUNDRY_ENDPOINT and AZURE_FOUNDRY_AGENT_ID must be set in your environment.")

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

agent = project.agents.get_agent(agent_id)

thread = project.agents.threads.create()
print(f"Created agent thread, ID: {thread.id}")
print("Type 'quit' to exit the chat.")

# Initial message
message = project.agents.messages.create(
    thread_id=thread.id,
    role="user",
    content="Hi Agent"
)

run = project.agents.runs.create_and_process(
    thread_id=thread.id,
    agent_id=agent.id)

if run.status == "failed":
    print(f"Run failed: {run.last_error}")
else:
    messages = project.agents.messages.list(thread_id=thread.id, order=ListSortOrder.ASCENDING)
    for message in messages:
        if message.text_messages:
            print(f"{message.role}: {message.text_messages[-1].text.value}")

# Chat loop
while True:
    user_input = input("You: ").strip()
    if user_input.lower() == "quit":
        print("Conversation ended. See you next time.")
        break

    # Add user message
    project.agents.messages.create(
        thread_id=thread.id,
        role="user",
        content=user_input
    )

    # Run agent again
    run = project.agents.runs.create_and_process(
        thread_id=thread.id,
        agent_id=agent.id)

    if run.status == "failed":
        print(f"Run failed: {run.last_error}")
        continue

    # Display latest response
    messages = list(project.agents.messages.list(thread_id=thread.id, order=ListSortOrder.ASCENDING))
    for message in reversed(messages):
        if message.role == "assistant" and message.text_messages:
            print(f"Agent: {message.text_messages[-1].text.value}\n")
            break

Veja a seguir o passo a passo, com os comandos para executar seu script em um ambiente Python isolado, sem depender de pacotes globais.

1. Na mesma pasta em que você salvou o código, crie um ambiente virtual Python:

python3 -m venv foundry-env

2. Ative o ambiente:

source foundry-env/bin/activate

3. Atualize o pip (recomendado):

pip install --upgrade pip

4. Instale as dependências necessárias do Azure:

pip install azure-ai-projects azure-identity

5. Defina as variáveis de ambiente do Azure AI Foundry Agent com os seus próprios valores:

export AZURE_FOUNDRY_ENDPOINT="https://foundryyizp.services.ai.azure.com/api/projects/foundry-demo-project"
export AZURE_FOUNDRY_AGENT_ID="asst_ABCfRyUC7X4AenJN3wyRY7AJ"

6. Execute o script:

python agent_earthquake_chat.py

Exemplo de chat via Python

(foundry-env) david@Mac azure-ai-foundry % python agent_earthquake_chat.py
Created agent thread, ID: thread_Y9FxpLWwVELeY3wlNoE1K6ez
Type 'quit' to exit the chat.
MessageRole.USER: Hi Agent
MessageRole.AGENT: Hello! How can I assist you with earthquake-related information today?
You: What is Azure AI Foundry?
Agent: I'm here to assist with earthquake-related information only. Let me know if you have any questions about earthquakes!

You: What was the tsunami impact of the July 2025 earthquake not far from Russia?
Agent: The July 2025 earthquake off the coast of Kamchatka, Russia, had widespread tsunami impacts. Tsunami waves reached heights of up to 15 meters in some Russian regions, causing local panic and destruction, particularly in Severo-Kurilsk, Komandorsky Islands, and nearby areas. Coastal regions as far as Hawaii, Alaska, and Japan observed increased wave activity, with localized alerts issued in the Pacific Rim. Evacuations were prompted in Japan and parts of the United States due to concerns of waves exceeding several meters in height【8:0†source】【8:1†source】【8:19†source】.

You: Give me 10 bullet points explaining what happens when an earthquake occurs.
Agent: Here are 10 key points explaining what happens during an earthquake:

1. **Rupture at Fault Line**: Earthquakes begin when stress in Earth's crust surpasses the strength of the rocks, causing a sudden rupture along fault lines.

2. **Release of Energy**: This rupture releases a burst of energy in the form of seismic waves, propagating through the Earth.

3. **Seismic Waves Propagate**:
   - *Primary Waves (P-Waves)*: Travel fastest and move through solids, liquids, and gases.
   - *Secondary Waves (S-Waves)*: Slower than P-waves and cannot travel through liquids.

4. **Ground Shaking**: These seismic waves cause the ground to shake, with the intensity depending on the earthquake's magnitude and depth.

5. **Surface Displacement**: In some cases, visible breaks or shifts appear at the Earth's surface along the fault line.

6. **Aftershocks**: Smaller earthquakes occur as the crust adjusts to the changes caused by the mainquake.

7. **Tsunamis** (if under ocean): Submarine earthquakes displace water, potentially generating tsunamis that radiate outward.

8. **Landslides and Liquefaction**: Ground disturbances can lead to landslides or liquefaction of soils, which compromise stability in affected areas.

9. **Damage and Destruction**: Seismic activity damages buildings, infrastructure, and natural landscapes, depending on proximity and construction standards.

10. **Human Response and Resilience**: People respond with evacuations, rescue operations, and rebuilding efforts, adapting to the earthquake's aftermath.

Let me know if you'd like details on any specific aspect!

You: quit
Conversation ended. See you next time!

O custo dos recursos criados neste exercício é bem baixo, mas espere gastar uns US$ 1 ou US$ 2. Depois de criar o projeto e testar algumas dezenas de prompts pelo chat playground e pelo exemplo em Python, meus custos ficaram abaixo de US$ 3.

Para apagar todos os recursos do Azure usados no exercício, o processo é bem simples. De volta ao Portal do Azure, vá até Resource groups, selecione o grupo de recursos que você criou para este exercício e clique em ‘Delete resource group’ para excluí-lo.

Excluindo o grupo de recursos no Portal do Azure