Phase 14 - Lesson 15

CrewAI: Crews e Flows Baseados em Papéis

O CrewAI é o framework multiagente baseado em papéis de 2026 — Agentes, Tarefas, Crews e Processos como as quatro primitivas. Orientação de produção da documentação: "para qualquer aplicação pronta para produção, comece com um Flow."

Tipo: Learn + Build Idiomas: Python (stdlib) Pré-requisitos: Phase 14 · 12 (Workflow Patterns), Phase 14 · 14 (Actor Model) Tempo: ~60 minutos

Objetivos de Aprendizagem

• Nomear as quatro primitivas do CrewAI — Agent, Task, Crew, Process — e a função de cada uma.
• Distinguir Crews (colaboração autônoma baseada em papéis) de Flows (fluxos de trabalho determinísticos orientados a eventos).
• Explicar por que a documentação recomenda começar com Flows para produção e Crews para exploração.
• Implementar um executor de Crew da biblioteca padrão (stdlib) e um executor de Flow da biblioteca padrão; mostrar quando cada um brilha.

O Problema

As equipes que adotam frameworks multiagentes enfrentam a mesma barreira: a "colaboração autônoma" parece ótima, mas quando os clientes relatam um bug, você precisa de uma reprodução determinística. O CrewAI divide isso explicitamente — Crews para colaboração criativa, Flows para fluxos de trabalho orientados a eventos, auditáveis e prontos para produção.

O Conceito

Quatro primitivas

• Agent. Papel + objetivo + backstory + ferramentas. O backstory é fundamental — ele molda o tom e o julgamento.
• Task. Descrição + expected_output + agente atribuído. Unidade de trabalho reutilizável.
• Crew. Contêiner que sequencia Agentes e Tarefas. Possui o Process de execução.
• Process. Sequencial, Hierárquico (com um Agente gerente) ou Consensual.

Crews vs Flows

• Crew. Autônomo, direcionado por LLM. Bom para tarefas abertas: pesquisa, brainstorming, primeiros rascunhos. O framework escolhe o formato em tempo de execução.
• Flow. Grafo orientado a eventos e de propriedade do código. Cada etapa é executada com base em um gatilho (decorador de função, correspondência de evento). Bom para produção: observável, testável, determinístico.

A documentação de 2026 do CrewAI diz: comece aplicações de produção com Flows; incorpore Crews como subetapas quando a autonomia compensar seu custo.

Sistema de memória

O CrewAI vem com quatro tipos de memória integrados prontos para uso: curto prazo (dentro da execução), longo prazo (entre execuções), entidade (fatos por entidade), contextual (montagem em tempo de recuperação). Integrações com bancos de dados vetoriais são nativas.

Integração com AWS Bedrock

O CrewAI possui integração documentada com o AWS Bedrock com ganchos de observabilidade do CloudWatch, AgentOps e Langfuse. A documentação da AWS cita uma velocidade 5,76x maior em relação ao LangGraph em tarefas de QA em seus benchmarks — considere números específicos de frameworks como direcionais, não absolutos.

Formato das dependências

Independente do LangChain. Python 3.10–3.13. Usa uv para gerenciamento de dependências. Mais de 30k estrelas no GitHub no início de 2026.

Onde este padrão falha

• Crew como produção. Usar uma Crew livre em produção sem um wrapper de Flow. A variabilidade do output é alta; a depuração é dolorosa.
• Backstory inflado. Backstories de 2000 palavras consomem o orçamento de contexto. Mantenha-os concisos.
• Confusão de Processo. O processo hierárquico adiciona um Agente gerente que realiza o roteamento; use apenas quando tiver 4+ especialistas.

Construa

code/main.py implementa versões stdlib de ambos:

• Agent, Task, Crew, SequentialCrew (uma tarefa por vez), HierarchicalCrew (roteamento por gerente).
• Flow com decoradores @start() e @listen() (substitutos para funções simples) que disparam em eventos nomeados.
• Mesma tarefa de três etapas (pesquisa, esboço, rascunho) implementada de ambas as formas.

Execute:

python3 code/main.py

O rastreamento da Crew é fluido e variável; o rastreamento do Flow é fixo e observável. Essa é a escolha.

Use

• CrewAI Flow para produção.
• CrewAI Crew para exploração, pareamento, primeiros rascunhos.
• LangGraph (Lesson 13) se você quiser uma máquina de estados mais explícita.
• AutoGen v0.4 (Lesson 14) se você quiser concorrência baseada no modelo de atores.

Envie

outputs/skill-crew-or-flow.md escolhe Crew vs Flow para uma tarefa e monta o andaime da implementação mínima.

Exercícios

1. Converta uma demonstração baseada em Crew para um Flow. Conte os pontos de contato onde a variabilidade cai.
2. Adicione memória de entidade à Crew: fatos sobre um cliente persistem entre as tarefas.
3. Implemente um processo Hierárquico: um Agente gerente escolhe qual especialista executa em seguida com base no output anterior.
4. Leia a introdução da documentação do CrewAI. Port seu brinquedo para a API real do crewai. O que muda sobre a testabilidade?
5. Conecte o AgentOps ou Langfuse a uma de suas execuções. Quais traces você perdeu na versão stdlib?

Termos-Chave

Leituras Adicionais

• Introdução da documentação do CrewAI — conceitos e caminho de produção recomendado
• Anthropic, Building Effective Agents — quando o uso de multiagentes ajuda e quando não ajuda
• Visão geral do LangGraph — a alternativa de máquina de estados