Microsoft Agent Framework: tools, workflows e multiagentes em Python

Ambiente e primeiro agente no MAF - Apresentação

Apresentando o instrutor e audiodescrição

Olá, muito prazer! Meu nome é Henrique Frizzo, sou instrutor na Alura. Trabalho com Python e automações há algum tempo e, há alguns meses, com agentes, principalmente no Copilot Studio. Recentemente, comecei a desenvolver agentes utilizando o Microsoft Agents Framework. Será um prazer compartilhar um pouco da minha experiência e do meu conhecimento com você nos próximos passos.

Para fins de acessibilidade, vou me autodescrever.

Audiodescrição: Henrique é um homem de pele clara, com cabelos e barba escuros. Veste uma blusa preta de manga longa. Ao fundo, há uma parede branca com luzes rosa e azul refletidas nela.

Definindo público-alvo e escopo do curso

Este curso é direcionado a pessoas que já programam em Python e que já têm experiência com automação e análise de dados.

Se você ainda está começando e não sabe muito bem o que é um dicionário, uma lista ou uma variável, infelizmente este curso ainda não é para você, pois aqui não vamos focar em explicar classes em Python, variáveis, listas, dicionários nem conteúdos semelhantes.

Aqui vamos focar explicitamente em mostrar como o math do Python funciona.

Se você está iniciando, recomendamos procurar na plataforma cursos introdutórios de Python e, depois, voltar para estudar conosco.

Apresentando conteúdo e suporte do curso

Neste curso, vamos aprender a desenvolver um agente do zero, utilizando o módulo math do Python e o Microsoft Agents Framework. Vamos aprender como enviar perguntas para esse agente, como ele consulta ferramentas externas por meio do Model Context Protocol (Protocolo de Contexto de Modelo — MCP), e vamos falar sobre observabilidade, isto é, compreender quais erros e problemas o nosso agente enfrenta e como corrigi-los, entre outros tópicos.

Não se esqueça de que este curso segue o padrão da Alura. A partir de agora, você tem acesso às nossas redes sociais, ao nosso Discord, ao nosso fórum e, claro, à Luri, nossa inteligência artificial, disponível para ajudar com quaisquer dúvidas em relação ao treinamento ao longo de todo o curso.

Agora, desligue o celular, feche as redes sociais, pegue água ou café e vamos em frente: nossa missão a partir de agora é incrível. Vamos lá!

Ambiente e primeiro agente no MAF - Entendendo o papel do MAF

Apresentando o MAF

Afinal, o que é o Microsoft Agents Framework e o que ele resolve? A partir de agora, não vamos repetir “Microsoft Agents Framework” o tempo todo; vamos chamá-lo de MAF, como nós costumamos fazer devido à extensão do nome.

O MAF é um framework (estrutura de desenvolvimento) em Python; também há suporte para .NET. Foi desenvolvido pela Microsoft, mas é mais comum utilizá-lo em Python. Trata-se de um framework que utilizamos para desenvolver agentes de inteligência artificial.

Atualmente, existem diversas ferramentas para o desenvolvimento de agentes de inteligência artificial, cada uma com suas vantagens e desvantagens. Conforme formos avançando neste treinamento, faremos comparações com outras ferramentas com as quais já trabalhamos e que estão disponíveis no mercado. Veremos, na prática, por que o MAF se sobressai em relação a outros agentes.

Contextualizando o caso de uso logístico

Qual é o tipo de problema que um agente desenvolvido com o MAF resolve? Imagine que você é uma pessoa colaboradora, ou que recebe a solicitação de uma pessoa colaboradora da empresa, que diz: “Precisamos saber quais pedidos estão atrasados, entender os motivos e gerar um relatório.” Essa é uma demanda relativamente comum no dia a dia empresarial. Em um setor logístico, podem ocorrer atrasos que geram reclamações, e precisamos entender por que isso está acontecendo.

Vamos imaginar que não temos um agente de inteligência artificial que faça isso para nós. O que precisamos fazer? Precisamos coletar os dados, compilá-los em uma ferramenta de transformação de dados, como o Power Query, e depois carregá-los em um software (programa) de análise de dados, como o Power BI ou o Python, que será nosso foco neste treinamento. Em seguida, realizamos nossas próprias análises, criamos gráficos e indicadores, tomamos decisões sobre por que os pedidos estão atrasados, quais são os motivos e, por fim, geramos um relatório.

Quando desenvolvemos um agente de inteligência artificial, conseguimos fornecer esses dados para ele. Conectado a uma LLM (modelo de linguagem de grande porte) — que utilizaremos neste treinamento e sobre a qual falaremos adiante —, esse agente, conectado a um “cérebro”, por assim dizer, consegue interpretar os dados, entender solicitações em linguagem natural e retornar respostas também em linguagem natural.

Detalhando as características do agente

O MAF, o agente que desenvolvemos aqui, possui algumas características...

Vamos considerar o seguinte: o agente interpretará a solicitação. Podemos imaginar uma situação em que realizamos uma ligação para um call center (central de atendimento) e informamos: “Tivemos este problema; nosso pedido está atrasado. Por quê?”.

Dentro do nosso agente, teremos também um chat client (cliente de bate-papo), onde vamos digitar para conversar com esse agente. Portanto, nosso agente será um agente de chat (bate-papo). Vamos escrever, não vamos falar por voz nem enviar imagens; solicitaremos tudo por texto.

Como mencionamos, vamos conectar isso ao Ollama, que funcionará como o “cérebro” do sistema. Explicaremos o que é o Ollama mais adiante; ele rodará localmente em nosso computador.

Dentro do agente, teremos as tools (ferramentas), que são, basicamente, trechos de código que consultam os dados reais da empresa. No nosso caso, não utilizaremos dados reais, portanto não exibiremos nada sigiloso. No futuro, ao concluir este treinamento, será possível conectar-se aos dados reais da sua empresa.

Vamos ter as sessions (sessões) também. Atualmente, já contamos com isso em diversas LLMs (Modelos de Linguagem de Grande Porte), como Microsoft Copilot, ChatGPT e Claude: elas mantêm o que chamamos de contexto. Por exemplo, se iniciarmos uma conversa sobre resolução de problemas na área de logística, a próxima pergunta, mesmo que não deixe explícito que ainda se trata de logística, será respondida considerando esse contexto, e as respostas girarão em torno desse tema específico.

Por fim, mais para o final do curso, teremos os nossos workflows (fluxos de trabalho), que organizam todas as etapas de um processo: a interação com as tools, as respostas e outras ações necessárias.

Justificando o uso de agentes

Mas por que precisamos desenvolver um agente para responder à pergunta específica sobre pedidos atrasados? Se copiarmos essa mesma pergunta e colarmos no Microsoft Copilot, no ChatGPT, no Claude, entre outros, é provável que a IA alucine ou busque soluções na internet. Isso acontece porque esses chats geralmente não têm a capacidade de se conectar diretamente aos dados do seu computador para fazer essa leitura, a menos que façamos um upload (envio de arquivos) dentro da própria ferramenta. Hoje, contamos com essa capacidade por meio de workspaces (espaços de trabalho) nas principais ferramentas de IA, nos quais é possível fornecer dados para que a IA faça a leitura e responda com base no contexto geral da conversa.

De forma geral, as IAs não fazem esse tipo de integração nativamente, mas os agentes fazem. Esse é o principal motivo pelo qual desenvolveremos um agente agora para a nossa empresa.

[♪ Música de encerramento ♪]

Ambiente e primeiro agente no MAF - Preparando o ambiente

Instalando ferramentas essenciais

Antes de criarmos diversos agentes de inteligência artificial no nosso projeto, precisamos preparar o ambiente. Precisamos de uma sequência de ferramentas que utilizaremos para a criação desses agentes. A primeira delas é o Python. Se não tivermos a linguagem Python instalada na máquina, não conseguiremos executar o MAF. Como este curso não é direcionado para pessoas que estão vendo Python pela primeira vez, é provável que você já tenha o Python instalado. Caso não tenha, acesse python.org/downloads, selecione o seu sistema operacional (no nosso caso, estamos utilizando Windows) e faça a instalação.

Você notará que o site apresenta a versão mais atual, como a 3.15. A versão que temos na máquina pode ser 3.11 ou 3.12, e isso não é um problema. Precisamos ter o Python 3; a subversão não é impeditiva. É possível que você esteja trabalhando com uma versão ainda mais recente, dependendo de quando estiver assistindo a este curso.

Em seguida, precisamos do Visual Studio Code (VS Code) instalado. Se você estiver utilizando Windows, é provável que já o tenha. Caso contrário, acesse code.visualstudio.com e faça o download (baixar) para Windows. Pode levar alguns minutos, mas não muito. Se preferir, faça uma pausa no vídeo. Todos os links estarão disponíveis para que você possa apenas clicar, caso ache mais fácil.

Por fim, precisamos fazer o download (baixar) do Ollama. O Ollama será o nosso LLM (modelo de linguagem grande) conectado ao agente. Ele possui vantagens e desvantagens. A grande vantagem, na nossa concepção, é que não pagaremos nada, pois é gratuito e roda na máquina local. A desvantagem é que, por rodar localmente, teremos algumas limitações de processamento. Para este curso, nada que impacte de forma significativa. Não há motivo para preocupação.

Escolha o seu SO (sistema operacional), clique em Download manual (baixar manualmente) e execute o instalador. A instalação do Ollama costuma demorar um pouco, de 10 a 15 minutos. Por isso, já realizamos esse processo previamente à gravação. É normal que demore mais; se parecer que está levando tempo, está dentro do esperado.

Organizando a pasta do projeto e verificando instalações

A próxima etapa é abrir a raiz de C: e criar uma pasta chamada "curso maf". Nessa pasta, vamos armazenar todos os arquivos, saídas e demais artefatos do projeto. Vamos manipulá-la pelo VS Code.

Antes de começarmos a escrever código, vamos abrir o PowerShell para verificar se o Python e o Ollama estão instalados corretamente. A forma mais direta é executar python --version.

Execute:

python --version

O terminal informará a versão instalada (por exemplo, 3.11). Em seguida, execute ollama --version.

ollama --version

Se o terminal também informar a versão, significa que tudo está instalado corretamente.

Configurando o VS Code e criando ambiente virtual

Com isso, estamos prontos para começar. Vamos para o VS Code. Abra o Visual Studio Code e conecte-o à pasta do projeto. Caso a pasta "curso maf" não apareça automaticamente, acesse o menu superior em File (Arquivo), clique em Open Folder (Abrir Pasta), localize a pasta "curso maf" e selecione-a. Pronto, a pasta do projeto estará aberta.

Agora, vamos abrir um novo terminal no VS Code, onde escreveremos as instruções do nosso agente. No menu, acesse Terminal (Terminal) e selecione a opção de novo terminal. O terminal será aberto já indicando que tudo o que programarmos será executado dentro da pasta "curso maf", localizada na raiz de C:.

Em seguida, vamos criar o nosso ambiente virtual. O que é um ambiente virtual? É um ambiente isolado do sistema operacional no qual instalaremos pacotes específicos e poderemos usar versões diferentes de bibliotecas sem interferir em outros projetos Python na sua máquina. Assim, se você já estiver executando outros projetos com versões específicas da linguagem ou de pacotes, isso não causará conflitos. O ambiente virtual criado nesta pasta será totalmente independente. Essa é a principal vantagem de utilizar um ambiente virtual.

Para isso, utilizaremos um comando que envolve py -3.12 e a criação do venv. O venv é a ferramenta padrão do Python para criação de ambientes virtuais — em inglês, virtual environment (ambiente virtual). Após executar o comando, o processo pode levar alguns instantes. Ao finalizar, o ambiente virtual estará criado.

Execute:

py -3.12 -m venv .venv

Para confirmarmos que o ambiente virtual foi criado, existem duas formas. A primeira é verificar dentro da pasta. Ao visualizarmos o diretório, já vemos que ele foi criado. A segunda é executarmos um teste com o comando Test-Path, que faz a verificação para nós. Como ele retorna True, significa que o ambiente virtual foi selecionado corretamente.

Test-Path .\.venv\Scripts\python.exe

Instalando o Microsoft Agent Framework e conferindo a instalação

Agora, vamos realizar a instalação do framework (estrutura) do Python, o Microsoft Agent Framework (MAF). Vamos copiar o comando de instalação, colá-lo e executar. Em outras palavras, vamos instalar o nosso agente com pip install, realizando a instalação do Agent Framework Core (Core (núcleo)) e utilizando o Ollama dentro dessa pasta. Ao pressionarmos Enter, a instalação pode demorar um pouco. Se demorar demais, interromperemos a gravação e retomaremos ao final da instalação. Aqui, a instalação ocorreu rapidamente, indicando que está tudo correto.

pip install --pre agent-framework-core agent-framework-ollama

Vamos confirmar a instalação com o comando pip show agent framework. Ao executá-lo, obtemos a confirmação de que deu tudo certo, incluindo a versão do framework (estrutura), atualmente 1.22, e um sumário. O MAF foi criado para desenvolver agentes de IA com Python e este é um pacote Core. Se todas essas informações aparecerem, está tudo em ordem.

pip show agent-framework-core

Configurando o interpretador do Python e inspecionando o Ollama

O próximo passo é configurar o Python no VS Code para facilitar o início da programação dos agentes em Python. Para isso, pressionamos Ctrl+Shift+P para abrir a barra de pesquisa, digitamos “Python” e selecionamos a opção “Python: Select Interpreter (Selecionar Interpretador do Python)”. Em seguida, escolhemos “Enter Interpreter Path (Informar caminho do interpretador)”. Vamos selecionar o diretório do interpretador. Para agilizar, copiamos o diretório previamente preparado. Estamos configurando o interpretador dentro da pasta do curso "MAF", na raiz de C:, utilizando o ambiente virtual e os scripts em Python. Ao confirmar, o VS Code passa a usar esse interpretador.

No terminal, vamos verificar a versão do Ollama. Executamos o comando e obtemos a mesma verificação que fizemos anteriormente no PowerShell.

ollama --version

Em seguida, solicitamos ao Ollama que liste as informações disponíveis, como nome, ID, tamanho ocupado no computador e a última modificação.

ollama list

Criando um teste simples em python

Agora, vamos criar um teste simples em Python. No próprio ambiente, dentro de "venv", acessamos o menu superior esquerdo e clicamos em “File (Arquivo)” e depois em “New File (Novo Arquivo)”. Salvamos o arquivo como teste.py dentro de "venv". Com o arquivo criado, colamos o código correspondente.

# Exibimos uma mensagem para confirmar
# que conseguimos executar um programa Python.
print("Python funcionando!")

# Importamos a classe utilizada para
# criar agentes com Microsoft Agent Framework.
from agent_framework import Agent

# Importamos a integração que permitirá
# conectar nossos agentes ao Ollama.
from agent_framework.ollama import OllamaChatClient

# Se chegamos até aqui, as bibliotecas
# foram instaladas e importadas com sucesso.
print("Microsoft Agent Framework funcionando!")

print("Integração com Ollama disponível!")

Neste pequeno exemplo, primeiro exibimos uma mensagem para garantir que o Python está funcionando — o print é um exemplo característico para essa verificação. Em seguida, importamos a classe utilizada para criar agentes dentro do MAF, por meio de from agent_framework import Agent. Essa é a classe utilizada no framework (estrutura) para a criação dos agentes. Depois, importamos a integração que permite conectar nossos agentes ao Ollama, utilizando from agent_framework.ollama import OllamaChatClient. Se chegamos até aqui, as bibliotecas foram instaladas e estão funcionando corretamente.

Executando e validando a integração

Para executar, podemos clicar no botão de execução no canto superior direito. Inicialmente, foi apresentado um erro, que em seguida foi corrigido. Ao verificar, percebemos que a execução ainda estava em andamento. Reexecutamos e, então, funcionou: a integração com o Ollama ficou disponível e o Python está operando corretamente.

Abrimos um novo terminal para confirmar. O erro identificado não é do nosso código. Ao executar novamente, tudo roda corretamente. Vamos investigar a origem dessa mensagem de erro, mas, de toda forma, agora está tudo funcionando.

Sobre o curso Microsoft Agent Framework: tools, workflows e multiagentes em Python

O curso Microsoft Agent Framework: tools, workflows e multiagentes em Python possui 124 minutos de vídeos, em um total de 41 atividades. Gostou? Conheça nossos outros cursos de Engenharia de LLMs & Agentes em Inteligência Artificial, ou leia nossos artigos de Inteligência Artificial.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

• Ambiente e primeiro agente no MAF
• Function Tools, MCP e aprovação
• Sessions, contexto e middleware
• Workflows com agentes
• Sistemas multiagentes
• Observabilidade e governança