Introdução ao CrewAI para orquestração de múltiplos agentes de IA

1. O que é o CrewAI e por que orquestrar múltiplos agentes?

1.1. Definição e visão geral do CrewAI como framework de orquestração

CrewAI é um framework de código aberto para orquestração de múltiplos agentes de inteligência artificial. Ele permite que desenvolvedores criem equipes de agentes LLM (Large Language Models) que trabalham de forma colaborativa para executar tarefas complexas. Inspirado no conceito de "crews" (equipes), o framework gerencia automaticamente a comunicação entre agentes, a delegação de tarefas e a consolidação de resultados.

Diferente de soluções onde um único agente tenta resolver tudo, o CrewAI promove a especialização: cada agente tem um papel definido, objetivos claros e acesso a ferramentas específicas.

1.2. Problemas resolvidos: coordenação, divisão de tarefas e comunicação entre agentes

Os principais problemas que o CrewAI resolve incluem:

  • Coordenação manual: Em pipelines tradicionais, o desenvolvedor precisa escrever código para conectar cada etapa. Com CrewAI, o framework gerencia o fluxo automaticamente.
  • Divisão de tarefas: Tarefas complexas são decompostas em subtarefas atribuídas a agentes especializados, melhorando a qualidade do resultado.
  • Comunicação entre agentes: Agentes podem compartilhar contexto e resultados intermediários sem intervenção manual.

1.3. Comparação com outras abordagens

Abordagem Vantagens Desvantagens
Agente único Simplicidade Escopo limitado, gargalo de conhecimento
Pipelines sequenciais Previsibilidade Rigidez, difícil adaptação
CrewAI Flexibilidade, especialização, colaboração Complexidade inicial de configuração

2. Conceitos fundamentais do CrewAI

2.1. Agentes: definição, papéis, objetivos e personalização

Um agente no CrewAI é uma entidade com:
- Role (papel): define a função do agente (ex: "Pesquisador Sênior")
- Goal (objetivo): descreve o que o agente deve alcançar
- Backstory: contexto adicional para guiar o comportamento
- Tools: ferramentas que o agente pode usar (APIs, bancos de dados, etc.)

2.2. Tarefas (Tasks): criação, dependências e atribuição a agentes

Tarefas são unidades de trabalho que podem ser:
- Atômicas: uma única ação (ex: "Pesquisar sobre IA")
- Compostas: dependem de resultados de outras tarefas
- Assíncronas: executadas em paralelo quando não há dependências

2.3. Crew: a equipe de agentes e o fluxo de execução colaborativa

O Crew é o container que gerencia:
- A lista de agentes
- A sequência de tarefas
- O fluxo de comunicação
- O processo de consolidação dos resultados

3. Configuração do ambiente e instalação

3.1. Pré-requisitos: Python, LLMs suportados (OpenAI, Anthropic, Ollama)

  • Python 3.10 ou superior
  • Acesso a um LLM (OpenAI, Anthropic, Ollama, ou qualquer modelo compatível)
  • Gerenciador de pacotes pip

3.2. Instalação via pip e configuração de variáveis de ambiente

pip install crewai

Configure as variáveis de ambiente para o LLM escolhido:

# Para OpenAI
OPENAI_API_KEY=sua_chave_aqui
OPENAI_MODEL_NAME=gpt-4-turbo

# Para Anthropic
ANTHROPIC_API_KEY=sua_chave_aqui

# Para Ollama (local)
OLLAMA_BASE_URL=http://localhost:11434

3.3. Estrutura básica de um projeto CrewAI

meu_projeto/
├── main.py
├── agents.py
├── tasks.py
├── tools.py
└── .env

4. Criando seu primeiro Crew: exemplo prático com dois agentes

4.1. Definição do agente pesquisador e do agente redator

# agents.py
from crewai import Agent

pesquisador = Agent(
    role="Pesquisador de Tecnologia",
    goal="Encontrar as informações mais recentes e relevantes sobre {topic}",
    backstory="Você é um pesquisador experiente em tecnologia, especializado em 
               encontrar fontes confiáveis e dados atualizados.",
    verbose=True
)

redator = Agent(
    role="Redator Técnico",
    goal="Criar um artigo claro e informativo baseado na pesquisa fornecida",
    backstory="Você é um redator técnico com talento para transformar 
               informações complexas em conteúdo acessível.",
    verbose=True
)

4.2. Criação de tarefas encadeadas: pesquisa → sumarização → redação

# tasks.py
from crewai import Task

tarefa_pesquisa = Task(
    description="Pesquise sobre {topic} e compile os 5 pontos mais importantes.",
    expected_output="Lista dos 5 pontos mais importantes sobre {topic}",
    agent=pesquisador
)

tarefa_redacao = Task(
    description="Com base na pesquisa, escreva um artigo de 300 palavras sobre {topic}.",
    expected_output="Artigo completo em markdown sobre {topic}",
    agent=redator,
    context=[tarefa_pesquisa]  # Dependência da tarefa anterior
)

4.3. Execução do Crew e análise do resultado final

# main.py
from crewai import Crew
from agents import pesquisador, redator
from tasks import tarefa_pesquisa, tarefa_redacao

crew = Crew(
    agents=[pesquisador, redator],
    tasks=[tarefa_pesquisa, tarefa_redacao],
    verbose=True
)

resultado = crew.kickoff(inputs={"topic": "Inteligência Artificial em 2025"})
print("Resultado final:")
print(resultado)

5. Técnicas avançadas de orquestração

5.1. Comunicação entre agentes: compartilhamento de contexto e memória

O CrewAI permite que agentes compartilhem contexto através de:
- Contexto explícito: definido nas tarefas
- Memória compartilhada: armazenamento de informações entre execuções
- Delegação: um agente pode solicitar ajuda de outro

from crewai.memory import Memory

memoria = Memory()
memoria.store("pesquisa_atual", "Dados sobre IA generativa")

5.2. Uso de ferramentas (Tools) para acesso a APIs, bancos de dados e web scraping

# tools.py
from crewai_tools import SerperDevTool, ScrapeWebsiteTool

ferramenta_busca = SerperDevTool()
ferramenta_scraping = ScrapeWebsiteTool()

agente_pesquisador = Agent(
    tools=[ferramenta_busca, ferramenta_scraping],
    # ... outras configurações
)

5.3. Gerenciamento de erros, retentativas e fallbacks entre agentes

from crewai import Task, Agent

tarefa_com_fallback = Task(
    description="Processar dados",
    agent=agente_principal,
    max_retries=3,
    fallback_agent=agente_reserva,
    fallback_description="Tentar processamento alternativo"
)

6. Integração com outras ferramentas do ecossistema

6.1. Uso com Instructor para extração de dados estruturados

from instructor import patch
from crewai import Agent

# Patch no modelo para saída estruturada
client = patch(OpenAI())

class PesquisaResultado(BaseModel):
    topicos: List[str]
    resumo: str

agente_estruturado = Agent(
    llm=client,
    # ... outras configurações
)

6.2. Conexão com Dify e Flowise para pipelines visuais

CrewAI pode ser integrado como um nó em plataformas visuais:
- Dify: usando webhooks para acionar crews
- Flowise: através de plugins customizados

6.3. Streaming de respostas em tempo real com Node.js e FastAPI

# fastapi_endpoint.py
from fastapi import FastAPI
from crewai import Crew

app = FastAPI()

@app.post("/executar-crew")
async def executar_crew(topic: str):
    crew = Crew(...)
    resultado = await crew.kickoff_async(inputs={"topic": topic})
    return {"resultado": resultado}

7. Casos de uso reais e boas práticas

7.1. Automação de pesquisa e geração de relatórios

Empresas usam CrewAI para automatizar:
- Pesquisa de mercado semanal
- Relatórios de concorrência
- Análise de tendências tecnológicas

7.2. Chatbots com múltiplos especialistas (suporte, vendas, técnico)

Um chatbot pode ter agentes especializados:
- Agente de suporte: resolve problemas comuns
- Agente de vendas: recomenda produtos
- Agente técnico: explica funcionalidades avançadas

7.3. Dicas de design: granularidade de agentes, balanceamento de carga e monitoramento

  • Granularidade: Crie agentes para tarefas específicas, não genéricas
  • Balanceamento: Distribua tarefas igualmente entre agentes
  • Monitoramento: Use logs e métricas para acompanhar o desempenho
# Exemplo de monitoramento
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("crewai")

crew = Crew(
    agents=[...],
    tasks=[...],
    logger=logger
)

Referências