Pular para o conteúdo principal
Antes de implantar no CrewAI AMP, é crucial verificar se seu projeto está estruturado corretamente. Tanto Crews quanto Flows podem ser implantados como “automações”, mas eles têm estruturas de projeto e requisitos diferentes que devem ser atendidos para uma implantação bem-sucedida.

​
Entendendo Automações

No CrewAI AMP, automações é o termo geral para projetos de IA Agêntica implantáveis. Uma automação pode ser:
  • Um Crew: Uma equipe independente de agentes de IA trabalhando juntos em tarefas
  • Um Flow: Um workflow orquestrado que pode combinar múltiplos crews, chamadas diretas de LLM e lógica procedural
Entender qual tipo você está implantando é essencial porque eles têm estruturas de projeto e pontos de entrada diferentes.

​
Crews vs Flows: Principais Diferenças

Projetos Crew

Equipes de agentes de IA independentes com crew.py definindo agentes e tarefas. Ideal para tarefas focadas e colaborativas.

Projetos Flow

Workflows orquestrados com crews embutidos em uma pasta crews/. Ideal para processos complexos de múltiplas etapas.
AspectoCrewFlow
Estrutura do projetosrc/project_name/ com crew.pysrc/project_name/ com pasta crews/
Localização da lógica principalsrc/project_name/crew.pysrc/project_name/main.py (classe Flow)
Função de ponto de entradarun() em main.pykickoff() em main.py
Tipo no pyproject.tomltype = "crew"type = "flow"
Comando CLI de criaçãocrewai create crew namecrewai create flow name
Localização da configuraçãosrc/project_name/config/src/project_name/crews/crew_name/config/
Pode conter outros crewsNãoSim (na pasta crews/)

​
Referência de Estrutura de Projeto

​
Estrutura de Projeto Crew

Quando você executa crewai create crew my_crew, você obtém esta estrutura: 
my_crew/
├── .gitignore
├── pyproject.toml          # Deve ter type = "crew"
├── README.md
├── .env
├── uv.lock                  # OBRIGATÓRIO para implantação
└── src/
    └── my_crew/
        ├── __init__.py
        ├── main.py          # Ponto de entrada com função run()
        ├── crew.py          # Classe Crew com decorador @CrewBase
        ├── tools/
        │   ├── custom_tool.py
        │   └── __init__.py
        └── config/
            ├── agents.yaml  # Definições de agentes
            └── tasks.yaml   # Definições de tarefas
A estrutura aninhada src/project_name/ é crítica para Crews. Colocar arquivos no nível errado causará falhas na implantação.

​
Estrutura de Projeto Flow

Quando você executa crewai create flow my_flow, você obtém esta estrutura: 
my_flow/
├── .gitignore
├── pyproject.toml          # Deve ter type = "flow"
├── README.md
├── .env
├── uv.lock                  # OBRIGATÓRIO para implantação
└── src/
    └── my_flow/
        ├── __init__.py
        ├── main.py          # Ponto de entrada com função kickoff() + classe Flow
        ├── crews/           # Pasta de crews embutidos
        │   └── poem_crew/
        │       ├── __init__.py
        │       ├── poem_crew.py  # Crew com decorador @CrewBase
        │       └── config/
        │           ├── agents.yaml
        │           └── tasks.yaml
        └── tools/
            ├── __init__.py
            └── custom_tool.py
Tanto Crews quanto Flows usam a estrutura src/project_name/. A diferença chave é que Flows têm uma pasta crews/ para crews embutidos, enquanto Crews têm crew.py diretamente na pasta do projeto.

​
Checklist Pré-Implantação

Use este checklist para verificar se seu projeto está pronto para implantação.

​
1. Verificar Configuração do pyproject.toml

Seu pyproject.toml deve incluir a seção [tool.crewai] correta: 
[tool.crewai]
type = "crew"
Se o type não corresponder à estrutura do seu projeto, o build falhará ou a automação não funcionará corretamente.

​
2. Garantir que o Arquivo uv.lock Existe

CrewAI usa uv para gerenciamento de dependências. O arquivo uv.lock garante builds reproduzíveis e é obrigatório para implantação. 
# Gerar ou atualizar o arquivo lock
uv lock

# Verificar se existe
ls -la uv.lock
Se o arquivo não existir, execute uv lock e faça commit no seu repositório: 
uv lock
git add uv.lock
git commit -m "Add uv.lock for deployment"
git push

​
3. Validar Uso do Decorador CrewBase

Toda classe crew deve usar o decorador @CrewBase. Isso se aplica a:
  • Projetos crew independentes
  • Crews embutidos dentro de projetos Flow
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List

@CrewBase  # Este decorador é OBRIGATÓRIO
class MyCrew():
    """Descrição do meu crew"""

    agents: List[BaseAgent]
    tasks: List[Task]

    @agent
    def my_agent(self) -> Agent:
        return Agent(
            config=self.agents_config['my_agent'],  # type: ignore[index]
            verbose=True
        )

    @task
    def my_task(self) -> Task:
        return Task(
            config=self.tasks_config['my_task']  # type: ignore[index]
        )

    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential,
            verbose=True,
        )
Se você esquecer o decorador @CrewBase, sua implantação falhará com erros sobre configurações de agents ou tasks ausentes.

​
4. Verificar Pontos de Entrada do Projeto

Tanto Crews quanto Flows têm seu ponto de entrada em src/project_name/main.py:
O ponto de entrada usa uma função run():
# src/my_crew/main.py
from my_crew.crew import MyCrew

def run():
    """Executa o crew."""
    inputs = {'topic': 'AI in Healthcare'}
    result = MyCrew().crew().kickoff(inputs=inputs)
    return result

if __name__ == "__main__":
    run()

​
5. Preparar Variáveis de Ambiente

Antes da implantação, certifique-se de ter:
  1. Chaves de API de LLM prontas (OpenAI, Anthropic, Google, etc.)
  2. Chaves de API de ferramentas se estiver usando ferramentas externas (Serper, etc.)
Se seu projeto depende de pacotes de um registro PyPI privado, você também precisará configurar credenciais de autenticação do registro como variáveis de ambiente. Consulte o guia Registros de Pacotes Privados para mais detalhes.
Teste seu projeto localmente com as mesmas variáveis de ambiente antes de implantar para detectar problemas de configuração antecipadamente.

​
Comandos de Validação Rápida

Execute estes comandos a partir da raiz do seu projeto para verificar rapidamente sua configuração: 
# 1. Verificar tipo do projeto no pyproject.toml
grep -A2 "\[tool.crewai\]" pyproject.toml

# 2. Verificar se uv.lock existe
ls -la uv.lock || echo "ERRO: uv.lock ausente! Execute 'uv lock'"

# 3. Verificar se estrutura src/ existe
ls -la src/*/main.py 2>/dev/null || echo "Nenhum main.py encontrado em src/"

# 4. Para Crews - verificar se crew.py existe
ls -la src/*/crew.py 2>/dev/null || echo "Nenhum crew.py (esperado para Crews)"

# 5. Para Flows - verificar se pasta crews/ existe
ls -la src/*/crews/ 2>/dev/null || echo "Nenhuma pasta crews/ (esperado para Flows)"

# 6. Verificar uso do CrewBase
grep -r "@CrewBase" . --include="*.py"

​
Erros Comuns de Configuração

ErroSintomaCorreção
uv.lock ausenteBuild falha durante resolução de dependênciasExecute uv lock e faça commit
type errado no pyproject.tomlBuild bem-sucedido mas falha em runtimeAltere para o tipo correto
Decorador @CrewBase ausenteErros “Config not found”Adicione decorador a todas as classes crew
Arquivos na raiz ao invés de src/Ponto de entrada não encontradoMova para src/project_name/
run() ou kickoff() ausenteNão é possível iniciar automaçãoAdicione a função de entrada correta

​
Próximos Passos

Uma vez que seu projeto passar por todos os itens do checklist, você está pronto para implantar:

Deploy para AMP

Siga o guia de implantação para implantar seu Crew ou Flow no CrewAI AMP usando a CLI, interface web ou integração CI/CD.