Introdução
O CrewAI é uma biblioteca open source desenvolvida para criar times de agentes de inteligência artificial que atuam de forma colaborativa. A ideia central é permitir que diferentes agentes desempenhem papéis específicos dentro de um fluxo de trabalho, coordenando-se para atingir objetivos mais complexos.
Cada agente pode ser configurado com um papel (role), um objetivo (goal) e um histórico contextual (backstory), o que o torna mais especializado e alinhado a determinadas tarefas. Esse modelo é especialmente útil em aplicações de economia e finanças, onde podemos montar equipes virtuais de agentes capazes de buscar dados do Banco Central, interpretar indicadores e produzir relatórios automáticos.
Para obter o código e o tutorial deste exercício faça parte do Clube AM e receba toda semana os códigos em R/Python, vídeos, tutoriais e suporte completo para dúvidas.
Funcionamento prático do CrewAI
O CrewAI é uma plataforma que permite automatizar tarefas complexas por meio de agentes inteligentes que trabalham de forma colaborativa. Seu funcionamento se organiza em quatro blocos principais: Agentes, Tarefas, Tools (Ferramentas) e Equipes, cada um com funções bem definidas para tornar o processo eficiente e estruturado.
1. Agentes
No CrewAI, um agente é um “profissional virtual” especializado em uma função específica. Cada agente é configurado por três atributos fundamentais:
- Role (Papel): define a função principal do agente. Pode ser algo como “pesquisador econômico”, “analista de dados” ou “gerador de relatórios”. Esse atributo direciona a forma como o agente processa informações e prioriza tarefas.
- Goal (Objetivo): descreve a meta do agente dentro do fluxo de trabalho. Por exemplo, “coletar os dados de inflação mensal do Brasil” ou “gerar um relatório resumido sobre o desempenho do PIB”. O objetivo orienta as ações do agente e estabelece um critério de sucesso mensurável.
- Backstory (Contexto): fornece uma narrativa que guia a interpretação do agente sobre suas responsabilidades. Por exemplo, o contexto pode indicar que o agente deve focar em precisão estatística ou em clareza de comunicação, influenciando suas decisões na execução das tarefas.
Essa configuração cria agentes especializados e autônomos, capazes de executar tarefas complexas e interagir com outros agentes de forma coordenada.
2. Tarefas
As tarefas no CrewAI representam ações concretas que cada agente deve realizar. Cada tarefa é definida por três elementos:
- Descrição: explica detalhadamente o que precisa ser feito, garantindo que o agente entenda exatamente a ação requerida.
- Resultado esperado: define o output da tarefa, que pode ser um dado, uma análise ou um relatório, tornando explícito o que se espera do agente.
- Associação ao agente: cada tarefa é atribuída a um agente específico, conectando o conhecimento e a função do agente à ação desejada.
Um exemplo prático seria uma tarefa onde o agente precisa “buscar a inflação acumulada em 12 meses usando a API do Banco Central” e o resultado esperado é o valor correto do indicador. Essa formalização garante que o processo seja transparente e que os resultados sejam consistentes.
3. Tools (Ferramentas)
As tools são componentes reutilizáveis que permitem aos agentes interagir com o mundo externo — APIs, bases de dados, scripts, serviços de armazenamento, geradores de relatórios, executores de jobs, etc. No CrewAI as tools são tratadas como recursos first-class: registradas, versionadas e invocáveis por agentes.
Como funcionam na prática
- Cada tool expõe uma interface clara (entradas, saídas, erros esperados, limites de tempo).
- As agents chamam a tool através dessa interface: enviam parâmetros e recebem um resultado estruturado.
- A Crew mantém um registro (registry) das tools disponíveis para descoberta e autorização.
Metadados típicos de uma tool
- nome, tipo (API/DB/script), esquema de entrada/saída, requisitos de autenticação, timeout, política de retry, versão, e tags de uso.
- além disso, cada tool costuma ter um contrato de idempotência (para evitar duplicação) e um conector de mock para testes.
Mapeamento entre tarefas e tools
- Ao definir uma tarefa, indique a tool(s) preferencial(is) a ser(em) usada(s).
- Se a tool falhar, o agente pode ter alternativas (fallbacks), ou a Crew pode re-orquestrar para outro agente/tool.
- Resultado de uma tool deve ser persistido no workspace compartilhado para permitir que outros agentes o consumam.
4. Equipe (Crew)
A equipe, chamada de Crew, é a camada de orquestração do sistema. Ela organiza os agentes e suas tarefas em um fluxo de trabalho eficiente. A Crew garante que:
- Os agentes colaborem de forma coordenada, evitando sobreposição de funções.
- As tarefas sejam executadas na ordem correta, respeitando dependências entre ações.
- O processo seja iniciado e monitorado por um comando central, normalmente através do método
.kickoff(), que dispara o ciclo completo.
Por exemplo, ao iniciar a Crew com .kickoff(), os agentes responsáveis por coletar dados, processar informações e gerar relatórios passam a executar suas tarefas em sequência ou de forma paralela, dependendo da configuração, e entregam o resultado final de maneira integrada.
Passo 1: Configuração no Google Colab
# Instalar CrewAI e dependências
!pip install crewai langchain_google_genai python-bcb --quietfrom langchain_google_genai import ChatGoogleGenerativeAI
from crewai import Agent, Task, Crew, LLM
from crewai.tools import tool
from bcb import sgs
import pandas as pdPasso 2: Configurar Gemini 2.0 Flash
import getpass, os
if not os.environ.get("GOOGLE_API_KEY"):
os.environ["GOOGLE_API_KEY"] = getpass.getpass("Enter API key for Google Gemini: ")
llm = LLM(model='gemini/gemini-2.0-flash',
api_key=os.environ["GOOGLE_API_KEY"]
)Passo 3: Criar uma Função de Consulta ao IPCA
import pandas as pd
from bcb import sgs
import logging
# Configuração de log para monitorar o uso da tool
logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
@tool('get_ipca_12m')
def get_ipca_12m(series_id: int = 433, start: str = "2015-01-01") -> dict:
"""
Consulta o IPCA no SGS/BCB e calcula a variação acumulada em 12 meses.
Parâmetros
----------
series_id : int
ID da série do SGS (default=433 para IPCA).
start : str
Data de início no formato YYYY-MM-DD.
Retorno
-------
dict
Exemplo:
{
"series_id": 433,
"date": "2025-08-31",
"ipca_12m": 3.45
}
"""
try:
# Baixar série do SGS
logging.info(f"Consultando série {series_id} a partir de {start}")
ipca = sgs.get({ "ipca": series_id }, start=start)
if ipca.empty:
raise ValueError("Nenhum dado retornado pela API do SGS.")
# Calcular inflação acumulada em 12 meses
dfr = ipca.rolling(12)
i12 = dfr.apply(lambda x: (1 + x/100).prod() - 1).dropna() * 100
# Selecionar último valor disponível
ultimo = i12.dropna().tail(1)
if ultimo.empty:
raise ValueError("Não foi possível calcular a inflação em 12 meses.")
resultado = {
"series_id": series_id,
"date": ultimo.index[0].strftime("%Y-%m-%d"),
"ipca_12m": round(float(ultimo["ipca"].values[0]), 2)
}
logging.info(f"Resultado obtido: {resultado}")
return resultado
except Exception as e:
logging.error(f"Erro ao consultar IPCA: {e}")
return { "error": str(e) }Passo 4: Definir os Agentes
# Agente 1: coleta dados
coletor = Agent(
role="Pesquisador Econômico",
goal="Coletar dados de inflação (IPCA) do SGS/BCB",
backstory="Especialista em buscar dados de fontes oficiais",
tools = [get_ipca_12m],
llm = llm
)
# Agente 2: analisa dados
analista = Agent(
role="Analista de Conjuntura",
goal="Interpretar os dados do IPCA e explicar o resultado",
backstory="Economista com experiência em inflação e política monetária",
llm = llm
)Passo 5: Criar Tarefas e Equipe
# Tarefa 1: coleta de dados
tarefa_coleta = Task(
description="Buscar a inflação acumulada em 12 meses usando a API do BCB",
expected_output="Valor da inflação em 12 meses",
agent=coletor
)
# Tarefa 2: análise
tarefa_analise = Task(
description="Interpretar a inflação em 12 meses e explicar em linguagem clara",
expected_output="Análise textual",
agent=analista
)
# Criar equipe (Crew)
crew = Crew(
agents=[coletor, analista],
tasks=[tarefa_coleta, tarefa_analise]
)resultado = crew.kickoff()
print(resultado)Conclusão
O CrewAI oferece uma forma clara e modular de construir equipes de agentes inteligentes. Enquanto cada agente possui uma função e responsabilidade bem definidas, as tarefas estruturam as ações esperadas e a equipe garante a coordenação.
Aplicado ao campo econômico, esse modelo permite criar pipelines automáticos para:
- Consultar e processar dados em tempo real.
- Executar previsões de séries temporais.
- Gerar relatórios automatizados de conjuntura econômica.
Essa abordagem representa um avanço importante na automação de análises, colocando agentes para trabalharem em conjunto como uma equipe de economistas digitais.
Quer aprender mais?
Conheça nossa Formação do Zero à Análise de Dados Econômicos e Financeiros usando Python e Inteligência Artificial. Aprenda do ZERO a coletar, tratar, construir modelos e apresentar dados econômicos e financeiros com o uso de Python e IA.
