Construa um AI Agent com o CrewAI: Tutorial Passo a Passo

O CrewAI é um framework Python open source para construir sistemas de AI multiagente: você define agents individuais com um papel e um conjunto de ferramentas, atribui tarefas a eles e os executa juntos como uma "crew" que colabora em direção a um único resultado. É uma alternativa baseada em código aos construtores visuais no-code, como o Lindy ou o n8n, criada para equipes que querem controle direto sobre como os agents raciocinam, transferem trabalho e chamam ferramentas. Este guia mostra como instalá-lo, construir uma crew multiagente funcional e decidir se é a plataforma certa para a sua equipe.

O Que o CrewAI Realmente É

O CrewAI é um framework Python independente, não uma camada construída sobre o LangChain. Ele traz seus próprios primitivos para agents, tasks, crews e orquestração, e funciona com OpenAI, Anthropic, modelos locais por meio do Ollama e a maioria dos demais grandes provedores de LLM. O framework principal é open source, sob a licença MIT; uma camada comercial separada, o CrewAI Enterprise (também chamado de AMP), acrescenta implantação hospedada, dashboards de observabilidade e gestão de equipes para organizações que não querem executar e monitorar as crews por conta própria.

Isso já não é uma categoria de projeto de hobby. O Gartner projeta que 40% dos aplicativos corporativos terão AI agents específicos para tarefas até o final de 2026, contra menos de 5% em 2025, e o próprio site do CrewAI informa que mais de 450 milhões de fluxos de trabalho agentic passam pelo framework todos os meses, com adoção em empresas como DocuSign, Experian, PepsiCo e IBM.

É um dos vários frameworks de código criados especificamente para sistemas multiagente, ao lado de opções como o LangGraph, o AutoGen da Microsoft e o OpenAI Agents SDK. Nenhum deles é objetivamente o "melhor". A proposta específica do CrewAI é uma API legível e baseada em papéis: você descreve os agents como descreveria uma equipe, com um papel, um objetivo e uma história de fundo que molda o tom e o julgamento, o que torna a lógica de uma crew mais fácil de reler daqui a um ano do que a de um framework mais centrado em grafos.

O Gartner também registrou separadamente um aumento de 1.445% nas consultas de clientes sobre sistemas multiagente entre o primeiro trimestre de 2024 e o segundo trimestre de 2025, e frameworks como o CrewAI são uma resposta direta a essa demanda: uma forma de construir os padrões orquestrador-trabalhador e de transferência entre pares abordados em sistemas multiagente sem escrever a lógica de coordenação do zero.

O Vocabulário do CrewAI, Mapeado para os 6 Blocos de Construção

Se você leu como construir um AI agent, já conhece os seis blocos de que todo agent precisa: Papel, Ferramentas, Regras, Manual de cenários, Lógica de decisão e Barreiras de proteção. O CrewAI dá a cada um deles um lugar concreto no código.

Nada disso é exclusivo do CrewAI do ponto de vista conceitual. O que muda de plataforma para plataforma é quanto disso você escreve em vez de configurar visualmente, exatamente a pergunta que no-code vs código em AI agents foi feito para ajudar você a responder.

Instalando o CrewAI

O CrewAI se instala como qualquer pacote Python:

pip install crewai
pip install 'crewai[tools]'

O extra tools traz a biblioteca de ferramentas nativas do CrewAI, incluindo uma ferramenta de busca na web e ferramentas de manipulação de arquivos, para que você não precise escrever cada integração do zero. Defina uma chave de API do provedor de LLM que estiver usando (OpenAI, Anthropic ou um modelo local por meio do Ollama) como variável de ambiente, e você estará pronto para definir sua primeira crew.

Um Exemplo Prático: Uma Crew de Pesquisa com Três Agents

Aqui está uma crew mínima com três agents, que espelha uma tarefa que vários blueprints do Rework tratam individualmente: pesquisar uma conta-alvo, analisar o que foi encontrado e redigir um resultado. Pense nela como o AI Account Research Agent, o AI Competitive Intelligence Agent e o AI Content Drafting Agent trabalhando como uma única crew coordenada, em vez de três ferramentas separadas.

from crewai import Agent, Task, Crew, Process

researcher = Agent(
    role="Account Researcher",
    goal="Gather accurate, current facts about a target company",
    backstory="You research companies for a B2B sales team and never state a fact you can't source.",
    tools=[search_tool],
)

analyst = Agent(
    role="Competitive Analyst",
    goal="Turn raw research into a clear point of view on fit and risk",
    backstory="You've reviewed hundreds of accounts and know what actually predicts a good fit.",
)

writer = Agent(
    role="Brief Writer",
    goal="Draft a one-page account brief a rep can read in two minutes",
    backstory="You write tight, scannable briefs, never a wall of text.",
)

research_task = Task(
    description="Research {company}: recent news, tech stack, and org changes.",
    expected_output="A bulleted list of sourced facts.",
    agent=researcher,
)

analysis_task = Task(
    description="Assess fit and flag risks based on the research.",
    expected_output="A short fit score with reasoning.",
    agent=analyst,
    context=[research_task],
)

brief_task = Task(
    description="Draft a one-page brief combining the research and analysis.",
    expected_output="A one-page account brief.",
    agent=writer,
    context=[research_task, analysis_task],
    human_input=True,
)

crew = Crew(
    agents=[researcher, analyst, writer],
    tasks=[research_task, analysis_task, brief_task],
    process=Process.sequential,
)

result = crew.kickoff(inputs={"company": "Acme Corp"})

O parâmetro context em analysis_task e brief_task é a transferência: ele diz ao CrewAI quais saídas de tasks anteriores devem ser repassadas, a mesma transferência estruturada que sistemas multiagente descreve como a diferença entre uma cadeia que funciona e uma cadeia que falha em silêncio. Definir human_input=True na última task significa que uma pessoa revisa o briefing antes de ele ser entregue, uma versão leve do portão abordado em intervenção humana em AI agents.

Processo Sequencial vs Hierárquico

O CrewAI oferece duas formas de executar uma crew, e elas correspondem diretamente aos dois padrões de coordenação abordados em sistemas multiagente.

Comece pelo sequencial. É mais fácil de entender e depurar, já que a ordem de execução é exatamente a que você escreveu. Recorra ao hierárquico quando o próximo passo certo depender genuinamente de um julgamento, e não apenas de "execute a task 2 depois da task 1".

Ferramentas, Memória e RAG

Um agent sem ferramentas só consegue conversar. Os agents do CrewAI chamam ferramentas como qualquer agent, tema abordado em profundidade em como os AI agents usam ferramentas: um nome, uma descrição e um schema que o modelo preenche. O CrewAI traz de fábrica uma ferramenta de busca, ferramentas de arquivos e diretórios e um interpretador de código, e aceita qualquer função Python personalizada como ferramenta para o restante.

A memória funciona em três níveis: a memória de curto prazo, que mantém uma execução da crew coerente; a memória de longo prazo, que persiste fatos entre execuções; e a memória de entidades, que acompanha pessoas, empresas ou registros específicos que a crew já viu antes. Memória de AI agents aborda a versão geral disso e as armadilhas que valem para qualquer plataforma, como um repositório de memória que fica desatualizado ou um agent que trata um contexto antigo como mais atual do que é.

Para fundamentar uma crew nos seus próprios documentos, em vez do conhecimento geral do modelo, o CrewAI oferece suporte a fontes de conhecimento que você anexa a um agent ou a uma crew, a versão do CrewAI para o padrão de recuperação abordado em RAG para AI agents.

Barreiras de Proteção e Testes Antes de Entrar no Ar

Dois recursos fazem a maior parte do trabalho de barreiras de proteção no CrewAI. As funções guardrail no nível da task validam a saída de um agent antes de ela ser aceita e a rejeitam ou tentam de novo se falhar em uma verificação que você define, como "o briefing deve citar pelo menos uma fonte". A flag human_input=True pausa uma task para que uma pessoa revise ou edite a saída antes de a crew continuar. Ambos correspondem à disciplina abordada em barreiras de proteção para AI agents: os limites rígidos que um agent nunca deve ultrapassar sozinho.

Não coloque uma crew no ar logo após um teste bem-sucedido com uma única entrada. Como avaliar e testar AI agents mostra como montar um conjunto de testes de verdade a partir de casos históricos antes que qualquer agent, construído com o CrewAI ou não, toque em volume de produção.

Custo e Limites

O framework em si não custa nada para executar. O que você paga é o uso da API do LLM, e uma crew multiagente consome tokens mais rápido do que um único agent fazendo o mesmo trabalho, já que o raciocínio de cada agent e cada transferência acrescentam uma chamada própria. Uma crew sequencial de três agents com um gerente hierárquico por cima pode facilmente chegar a quatro a seis chamadas ao modelo para uma tarefa que um único agent bem delimitado poderia resolver em uma ou duas. É o mesmo trade-off de latência e custo que sistemas multiagente aborda com mais profundidade: mais agents significam mais superfície de coordenação, e mais superfície de coordenação custa mais para executar e para depurar.

Os limites de taxa vêm do seu provedor de LLM, não do CrewAI. Se você executa uma crew hierárquica ou várias chamadas paralelas de agents, vai atingir os limites de taxa do provedor bem antes de atingir qualquer limite do próprio framework. O CrewAI Enterprise acrescenta dashboards de uso que tornam esse custo visível por crew, algo útil quando você já executa mais do que algumas crews em produção e precisa saber qual delas é cara.

Quando Escolher o CrewAI e Quando Escolher as Alternativas

Fatos Principais

• O CrewAI é um framework Python open source independente (licença MIT) para construir sistemas multiagente, com uma camada comercial, o CrewAI Enterprise, para implantação hospedada e observabilidade.
• Seus quatro conceitos centrais, Agent, Task, Crew e Process, correspondem diretamente aos 6 blocos de construção do Rework para qualquer agent: papel, ferramentas, regras, manual, lógica de decisão e barreiras de proteção.
• Process.sequential corresponde ao padrão de coordenação por transferência entre pares; Process.hierarchical corresponde ao orquestrador-trabalhador, com o CrewAI atribuindo automaticamente um agent gerente para delegar.
• O Gartner registrou um aumento de 1.445% nas consultas de clientes sobre sistemas multiagente entre o primeiro trimestre de 2024 e o segundo trimestre de 2025, a curva de demanda que frameworks como o CrewAI foram criados para atender.
• Uma crew multiagente custa mais em tokens e latência do que um único agent bem delimitado fazendo o mesmo trabalho, já que cada agent e cada transferência acrescentam uma chamada própria ao modelo.

Para Onde Ir a Seguir

O CrewAI é um caminho para um sistema multiagente, não o único. Se você ainda está decidindo se código ou uma plataforma no-code atende melhor a sua equipe, no-code vs código em AI agents percorre essa decisão diretamente. Quando uma crew funcionar de forma confiável nos testes, implantando AI agents em produção aborda o lançamento, o monitoramento e o plano de rollback antes de você entregar a ela volume real. E se o Python não é onde a sua equipe quer viver no dia a dia, o panorama de ferramentas para desenvolvedores e o guia de compra de assistentes de código com AI são boas próximas paradas para escrever e manter o próprio código mais rápido.