Preparar para Implantação

Note

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 independentes de agentes de IA. Novas crews são JSON-first com crew.jsonc e agents/; crews clássicas ainda podem usar crew.py.

Projetos Flow

Workflows orquestrados com crews embutidos em uma pasta crews/. Ideal para processos complexos de múltiplas etapas.

Aspecto	Crew	Flow
Estrutura do projeto	Raiz do projeto com crew.jsonc e agents/	src/project_name/ com pasta crews/
Localização da lógica principal	crew.jsonc (clássico: src/project_name/crew.py)	src/project_name/main.py (classe Flow)
Função de ponto de entrada	Carregada a partir de crew.jsonc (clássico: run() em main.py)	kickoff() em main.py
Tipo no pyproject.toml	type = "crew"	type = "flow"
Comando CLI de criação	crewai create crew name	crewai create flow name
Localização da configuração	crew.jsonc, agents/, tools/ opcional	src/project_name/crews/crew_name/config/ ou pastas de crew JSON embutidas
Pode conter outros crews	Não	Sim (na pasta crews/)

Referência de Estrutura de Projeto

Estrutura de Projeto Crew

Quando você executa crewai create crew my_crew, recebe a estrutura JSON-first:

my_crew/
├── .gitignore
├── pyproject.toml          # Deve ter type = "crew"
├── README.md
├── .env
├── uv.lock                  # OBRIGATÓRIO para implantação
├── crew.jsonc               # Configurações, tarefas, processo e inputs
├── agents/
│   └── researcher.jsonc     # Definições de agentes
├── tools/                   # Ferramentas custom:<name> opcionais
├── knowledge/
└── skills/

Warning

Para crews JSON-first, mantenha crew.jsonc, agents/, tools/, knowledge/ e skills/ na raiz do projeto. Colocá-los dentro de src/ impede que crewai run e a validação de implantação encontrem a definição da crew.

Info

Projetos clássicos criados com crewai create crew my_crew --classic usam a estrutura antiga src/project_name/crew.py, src/project_name/config/agents.yaml e src/project_name/config/tasks.yaml. Essa estrutura continua suportada para crews Python com decorators.

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

Info

Crews independentes JSON-first usam arquivos JSON na raiz do projeto. Flows ainda usam src/project_name/ e podem conter crews embutidas clássicas ou pastas de crew JSON carregadas com crewai.project.load_crew.

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:

Para Crews

[tool.crewai]
type = "crew"

Para Flows

[tool.crewai]
type = "flow"

Warning

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 a Definição da Crew

Crews JSON-first

Crews JSON-first precisam ter crew.jsonc ou crew.json na raiz do projeto. O array agents deve apontar para arquivos em agents/, e cada task deve referenciar um nome de agent válido.

{
  "name": "Research Crew",
  "agents": ["researcher"],
  "tasks": [
    {
      "name": "research_task",
      "description": "Research {topic}.",
      "expected_output": "A concise report.",
      "agent": "researcher"
    }
  ],
  "inputs": {
    "topic": "AI Agents"
  }
}

Ferramentas customizadas são referenciadas como "custom:<name>" e devem existir em tools/<name>.py com uma subclasse de BaseTool.

Crews Python/YAML Clássicas

Crews clássicas e crews Python embutidas em Flows devem usar o decorador @CrewBase.

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
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,
        )

4. Verificar Pontos de Entrada do Projeto

Crews JSON-first independentes não precisam de um src/project_name/main.py escrito manualmente; crewai run e o empacotamento de implantação carregam crew.jsonc diretamente. Crews clássicas e Flows usam pontos de entrada Python:

Crews JSON-first

Execute localmente a partir da raiz do projeto:

crewai run

Crews Clássicas

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()

Para Flows

O ponto de entrada usa uma função kickoff() com uma classe Flow:

src/my_flow/main.py

from crewai.flow import Flow, listen, start
from my_flow.crews.poem_crew.poem_crew import PoemCrew

class MyFlow(Flow):
    @start()
    def begin(self):
        # Lógica do Flow aqui
        result = PoemCrew().crew().kickoff(inputs={...})
        return result

def kickoff():
    """Executa o flow."""
    MyFlow().kickoff()

if __name__ == "__main__":
    kickoff()

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.)

Info

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.

Tip

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. Para crews JSON-first, verificar crew.jsonc e agents/
([ -f crew.jsonc ] || [ -f crew.json ]) || echo "Nenhum crew.jsonc ou crew.json encontrado"
test -d agents || echo "Nenhum diretório agents/ encontrado"

# 4. Para Crews clássicas - 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. Para crews Python clássicas - verificar uso do CrewBase
grep -r "@CrewBase" . --include="*.py"

Erros Comuns de Configuração

Erro	Sintoma	Correção
uv.lock ausente	Build falha durante resolução de dependências	Execute uv lock e faça commit
type errado no pyproject.toml	Build bem-sucedido mas falha em runtime	Altere para o tipo correto
crew.jsonc ou agents/ ausente em uma crew JSON-first	Definição da crew não encontrada	Mantenha crew.jsonc e agents/ na raiz do projeto
Decorador @CrewBase ausente em uma crew clássica	Erros “Config not found”	Adicione o decorador a todas as classes crew clássicas
Arquivos clássicos na raiz ao invés de src/	Ponto de entrada não encontrado	Mova arquivos Python clássicos para src/project_name/
run() ou kickoff() ausente	Não é possível iniciar automação	Adicione 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.