Deploy para AMP

Note

Depois de criar um Crew ou Flow localmente (ou pelo Crew Studio), o próximo passo é implantá-lo na plataforma CrewAI AMP. Este guia cobre múltiplos métodos de implantação para ajudá-lo a escolher a melhor abordagem para o seu fluxo de trabalho.

Pré-requisitos

Projeto Pronto para Implantação

Você deve ter um Crew ou Flow funcionando localmente com sucesso. Siga nosso guia de preparação para verificar a estrutura do seu projeto.

Repositório GitHub

Seu código deve estar em um repositório do GitHub (para o método de integração com GitHub).

Info

Crews vs Flows: Ambos os tipos de projeto podem ser implantados como “automações” no CrewAI AMP. O processo de implantação é o mesmo, mas eles têm estruturas de projeto diferentes. Veja Preparar para Implantação para detalhes.

Opção 1: Implantar Usando o CrewAI CLI

A CLI fornece a maneira mais rápida de implantar Crews ou Flows desenvolvidos localmente na plataforma AMP. A CLI detecta automaticamente o tipo do seu projeto a partir do pyproject.toml e faz o build adequadamente.

1. Instale o CrewAI CLI

   Se ainda não tiver, instale o CrewAI CLI:

   pip install crewai[tools]

   Tip

   A CLI vem com o pacote principal CrewAI, mas o extra [tools] garante todas as dependências de implantação.

2. Autentique-se na Plataforma Enterprise

   Primeiro, você precisa autenticar sua CLI com a plataforma CrewAI AMP:

   # Se já possui uma conta CrewAI AMP, ou deseja criar uma:
   crewai login

   Ao executar qualquer um dos comandos, a CLI irá:

   1. Exibir uma URL e um código de dispositivo único
   2. Abrir seu navegador para a página de autenticação
   3. Solicitar a confirmação do dispositivo
   4. Completar o processo de autenticação

   Após a autenticação bem-sucedida, você verá uma mensagem de confirmação no terminal!

3. Criar uma Implantação

   No diretório do seu projeto, execute:

   crewai deploy create

   Este comando irá:

   1. Detectar informações do seu repositório GitHub
   2. Identificar variáveis de ambiente no seu arquivo .env local
   3. Transferir essas variáveis com segurança para a plataforma Enterprise
   4. Criar uma nova implantação com um identificador único

   Com a criação bem-sucedida, você verá uma mensagem como:

   Deployment created successfully!
   Name: your_project_name
   Deployment ID: 01234567-89ab-cdef-0123-456789abcdef
   Current Status: Deploy Enqueued

4. Acompanhe o Progresso da Implantação

   Acompanhe o status da implantação com:

   crewai deploy status

   Para ver logs detalhados do processo de build:

   crewai deploy logs

   Tip

   A primeira implantação normalmente leva cerca de 1 minuto.

Comandos Adicionais da CLI

O CrewAI CLI oferece vários comandos para gerenciar suas implantações:

# Liste todas as suas implantações
crewai deploy list

# Consulte o status de uma implantação
crewai deploy status

# Veja os logs da implantação
crewai deploy logs

# Envie atualizações após alterações no código
crewai deploy push

# Remova uma implantação
crewai deploy remove <deployment_id>

Opção 2: Implantar Diretamente pela Interface Web

Você também pode implantar seus Crews ou Flows diretamente pela interface web do CrewAI AMP conectando sua conta do GitHub. Esta abordagem não requer utilizar a CLI na sua máquina local. A plataforma detecta automaticamente o tipo do seu projeto e trata o build adequadamente.

1. Enviar para o GitHub

   Você precisa enviar seu crew para um repositório do GitHub. Caso ainda não tenha criado um crew, você pode seguir este tutorial.

2. Conectando o GitHub ao CrewAI AMP
   1. Faça login em CrewAI AMP
   2. Clique no botão “Connect GitHub”

   

3. Selecionar o Repositório

   Após conectar sua conta GitHub, você poderá selecionar qual repositório deseja implantar:

   

   Tip

   Se seu Crew ou Flow estiver dentro de uma subpasta de monorepo, expanda Advanced e defina um diretório de trabalho antes de implantar. Consulte Implantações em Monorepo.

4. Definir as Variáveis de Ambiente

   Antes de implantar, você precisará configurar as variáveis de ambiente para conectar ao seu provedor de LLM ou outros serviços:

   1. Você pode adicionar variáveis individualmente ou em lote
   2. Digite suas variáveis no formato KEY=VALUE (uma por linha)

   

   Info

   Usando pacotes Python privados? Você também precisará adicionar suas credenciais de registro aqui. Consulte Registros de Pacotes Privados para as variáveis necessárias.

5. Implante Seu Crew
   1. Clique no botão “Deploy” para iniciar o processo de implantação
   2. Você pode monitorar o progresso pela barra de progresso
   3. A primeira implantação geralmente demora cerca de 1 minuto

   

   Após a conclusão, você verá:

   • A URL exclusiva do seu crew
   • Um Bearer token para proteger sua API crew
   • Um botão “Delete” caso precise remover a implantação

Opção 3: Reimplantar Usando API (Integração CI/CD)

Para implantações automatizadas em pipelines CI/CD, você pode usar a API do CrewAI para acionar reimplantações de crews existentes. Isso é particularmente útil para GitHub Actions, Jenkins ou outros workflows de automação.

1. Obtenha Seu Token de Acesso Pessoal

   Navegue até as configurações da sua conta CrewAI AMP para gerar um token de API:

   1. Acesse app.crewai.com
   2. Clique em Settings → Account → Personal Access Token
   3. Gere um novo token e copie-o com segurança
   4. Armazene este token como um secret no seu sistema CI/CD
2. Encontre o UUID da Sua Automação

   Localize o identificador único do seu crew implantado:

   1. Acesse Automations no seu dashboard CrewAI AMP
   2. Selecione sua automação/crew existente
   3. Clique em Additional Details
   4. Copie o UUID - este identifica sua implantação específica do crew
3. Acione a Reimplantação via API

   Use o endpoint da API de Deploy para acionar uma reimplantação:

   curl -i -X POST \
        -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
        https://app.crewai.com/crewai_plus/api/v1/crews/YOUR-AUTOMATION-UUID/deploy
   
   # HTTP/2 200
   # content-type: application/json
   #
   # {
   #   "uuid": "your-automation-uuid",
   #   "status": "Deploy Enqueued",
   #   "public_url": "https://your-crew-deployment.crewai.com",
   #   "token": "your-bearer-token"
   # }

   Info

   Se sua automação foi criada originalmente conectada ao Git, a API automaticamente puxará as últimas alterações do seu repositório antes de reimplantar.

4. Exemplo de Integração com GitHub Actions

   Aqui está um workflow do GitHub Actions com gatilhos de implantação mais complexos:

   name: Deploy CrewAI Automation
   
   on:
     push:
       branches: [ main ]
     pull_request:
       types: [ labeled ]
     release:
       types: [ published ]
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       if: |
         (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
         (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'deploy')) ||
         (github.event_name == 'release')
       steps:
         - name: Trigger CrewAI Redeployment
           run: |
             curl -X POST \
                  -H "Authorization: Bearer ${{ secrets.CREWAI_PAT }}" \
                  https://app.crewai.com/crewai_plus/api/v1/crews/${{ secrets.CREWAI_AUTOMATION_UUID }}/deploy

   Tip

   Adicione CREWAI_PAT e CREWAI_AUTOMATION_UUID como secrets do repositório. Para implantações de PR, adicione um label “deploy” para acionar o workflow.

Interaja com Sua Automação Implantada

Após a implantação, você pode acessar seu crew através de:

1. REST API: A plataforma gera um endpoint HTTPS exclusivo com estas rotas principais:

   • /inputs: Lista os parâmetros de entrada requeridos
   • /kickoff: Inicia uma execução com os inputs fornecidos
   • /status/{kickoff_id}: Consulta o status da execução

2. Interface Web: Acesse app.crewai.com para visualizar:

   • Aba Status: Informações da implantação, detalhes do endpoint da API e token de autenticação
   • Aba Run: Visualização da estrutura do seu crew
   • Aba Executions: Histórico de todas as execuções
   • Aba Metrics: Análises de desempenho
   • Aba Traces: Insights detalhados das execuções

Dispare uma Execução

No dashboard Enterprise, você pode:

1. Clicar no nome do seu crew para abrir seus detalhes
2. Selecionar “Trigger Crew” na interface de gerenciamento
3. Inserir os inputs necessários no modal exibido
4. Monitorar o progresso à medida que a execução avança pelo pipeline

Monitoramento e Análises

A plataforma Enterprise oferece recursos abrangentes de observabilidade:

• Gestão das Execuções: Acompanhe execuções ativas e concluídas
• Traces: Quebra detalhada de cada execução
• Métricas: Uso de tokens, tempos de execução e custos
• Visualização em Linha do Tempo: Representação visual das sequências de tarefas

Funcionalidades Avançadas

A plataforma Enterprise também oferece:

• Gerenciamento de Variáveis de Ambiente: Armazene e gerencie com segurança as chaves de API
• Conexões com LLM: Configure integrações com diversos provedores de LLM
• Repositório Custom Tools: Crie, compartilhe e instale ferramentas
• Crew Studio: Monte crews via interface de chat sem escrever código

Solução de Problemas em Falhas de Implantação

Se sua implantação falhar, verifique estes problemas comuns:

Falhas de Build

Arquivo uv.lock Ausente

Sintoma: Build falha no início com erros de resolução de dependências

Solução: Gere e faça commit do arquivo lock:

uv lock
git add uv.lock
git commit -m "Add uv.lock for deployment"
git push

Warning

O arquivo uv.lock é obrigatório para todas as implantações. Sem ele, a plataforma não consegue instalar suas dependências de forma confiável.

Estrutura de Projeto Incorreta

Sintoma: Erros “Could not find entry point” ou “Module not found”

Solução: Verifique se seu projeto corresponde à estrutura esperada:

• Crews JSON-first: Mantenha crew.jsonc ou crew.json e agents/ na raiz do projeto
• Crews clássicas: Use src/project_name/main.py com uma função de entrada run()
• Flows: Use src/project_name/main.py com uma função de entrada kickoff()

Veja Preparar para Implantação para diagramas de estrutura detalhados.

Decorador CrewBase Ausente em uma Crew Clássica

Sintoma: Erros “Crew not found”, “Config not found” ou erros de configuração de agent/task

Solução: Para crews clássicas Python/YAML, certifique-se de que todas as classes crew usam o decorador @CrewBase. Crews JSON-first não precisam desse decorador.

from crewai.project import CrewBase, agent, crew, task

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

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

    # ... resto da definição do crew

Info

Isso se aplica a classes crew Python clássicas, incluindo crews clássicas embutidas em projetos Flow. Crews JSON-first são validadas a partir de crew.jsonc e agents/.

Tipo Incorreto no pyproject.toml

Sintoma: Build tem sucesso mas falha em runtime, ou comportamento inesperado

Solução: Verifique se a seção [tool.crewai] corresponde ao tipo do seu projeto:

# Para projetos Crew:
[tool.crewai]
type = "crew"

# Para projetos Flow:
[tool.crewai]
type = "flow"

Falhas de Runtime

Falhas de Conexão com LLM

Sintoma: Erros de chave API, “model not found” ou falhas de autenticação

Solução:

1. Verifique se a chave API do seu provedor LLM está corretamente definida nas variáveis de ambiente
2. Certifique-se de que os nomes das variáveis de ambiente correspondem ao que seu código espera
3. Teste localmente com exatamente as mesmas variáveis de ambiente antes de implantar

Erros de Execução do Crew

Sintoma: Crew inicia mas falha durante a execução

Solução:

1. Verifique os logs de execução no dashboard AMP (aba Traces)
2. Verifique se todas as ferramentas têm as chaves API necessárias configuradas
3. Para crews JSON-first, valide crew.jsonc e os arquivos referenciados em agents/
4. Para crews clássicas, verifique se agents.yaml e tasks.yaml são válidos

Precisa de Ajuda?

Entre em contato com nossa equipe de suporte para ajuda com questões de implantação ou dúvidas sobre a plataforma AMP.