Kickoff Crew

Visão Geral

Uma vez que você tenha implantado seu crew na plataforma CrewAI AMP, é possível iniciar execuções pela interface web ou pela API. Este guia aborda ambos os métodos.

Método 1: Usando a Interface Web

Passo 1: Navegue até seu Crew Implantado

Faça login no CrewAI AMP
Clique no nome do crew na sua lista de projetos
Você será direcionado para a página de detalhes do crew

Passo 2: Iniciar Execução

Na página de detalhes do seu crew, você tem duas opções para iniciar uma execução:

Opção A: Kickoff Rápido

Clique no link Kickoff na seção Test Endpoints
Insira os parâmetros de entrada necessários para seu crew no editor JSON
Clique no botão Send Request

Opção B: Usando a Interface Visual

Clique na aba Run na página de detalhes do crew
Insira os inputs necessários nos campos do formulário
Clique no botão Run Crew

Passo 3: Monitorar o Progresso da Execução

Após iniciar a execução:

Você receberá uma resposta contendo um kickoff_id - copie este ID
Esse ID é fundamental para o acompanhamento da sua execução

Passo 4: Verificar o Status da Execução

Para monitorar o andamento da sua execução:

Clique no endpoint “Status” na seção Test Endpoints
Cole o kickoff_id no campo indicado
Clique no botão “Get Status”

A resposta de status mostrará:

Estado atual da execução (running, completed, etc.)
Detalhes sobre quais tarefas estão em andamento
Quaisquer outputs gerados até o momento

Passo 5: Visualizar Resultados Finais

Quando a execução for concluída:

O status mudará para completed
Você poderá visualizar todos os resultados e outputs da execução
Para uma visão mais detalhada, acesse a aba Executions na página de detalhes do crew

Método 2: Usando a API

Você também pode iniciar crews programaticamente usando a REST API do CrewAI AMP.

Autenticação

Todas as requisições à API exigem um bearer token para autenticação:

curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com

Seu bearer token está disponível na aba Status na página de detalhes do seu crew.

Verificando o Status do Crew

Antes de executar operações, você pode verificar se seu crew está funcionando corretamente:

curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com

Uma resposta de sucesso trará uma mensagem indicando que o crew está operacional:

Healthy%

Passo 1: Recuperar Entradas Necessárias

Primeiro, descubra quais entradas seu crew exige:

curl -X GET \
  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
  https://your-crew-url.crewai.com/inputs

A resposta será um objeto JSON contendo um array de parâmetros de entrada obrigatórios, por exemplo:

{ "inputs": ["topic", "current_year"] }

Este exemplo mostra que este crew em particular requer dois inputs: topic e current_year.

Passo 2: Iniciar Execução

Inicie a execução fornecendo os inputs obrigatórios:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
  -d '{"inputs": {"topic": "AI Agent Frameworks", "current_year": "2025"}}' \
  https://your-crew-url.crewai.com/kickoff

A resposta incluirá um kickoff_id que você precisará para o acompanhamento:

{ "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv" }

Passo 3: Verificar Status da Execução

Use o kickoff_id para obter o status da execução:

curl -X GET \
  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
  https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv

A resposta mostra o estado da execução, o progresso e o resultado. Envie a requisição novamente para obter uma nova resposta. Este é um exemplo de resposta para um crew em execução:

{
  "state": "RUNNING",
  "status": "Task is Running",
  "progress": {
    "unit": "task",
    "completed": 1,
    "total": 3,
    "remaining": 2,
    "current": "write_report",
    "current_agent": "Researcher",
    "started_at": "2025-09-10T18:00:00+00:00",
    "updated_at": "2025-09-10T18:02:14+00:00",
    "duration_seconds": 134.0
  },
  "last_event": {
    "type": "tool_usage_started",
    "timestamp": "2025-09-10T18:02:14+00:00",
    "tool_name": "SerperDevTool",
    "agent_role": "Researcher"
  },
  "events_count": 24,
  "events_by_type": {
    "crew_kickoff_started": 1,
    "task_started": 2,
    "agent_execution_started": 2,
    "tool_usage_started": 3
  },
  "triggered_by": { "type": "user", "id": "4711" },
  "execution_origin": "api",
  "source": "memory"
}

Campos da Resposta

Campo	Descrição
`state`	O estado da execução: `PENDING`, `STARTED`, `RUNNING`, `SUCCESS`, `FAILED`, `PAUSED` ou `REVOKED`.
`status`	Uma mensagem curta sobre o estado.
`result`	A saída final. O campo fica vazio até a execução parar.
`result_json`	A saída final em JSON, se a saída for um objeto JSON.
`usage_metrics`	A contagem de tokens da execução.
`progress`	Quanto do trabalho está completo. Consulte Progresso.
`last_event`	O evento mais recente. Consulte Eventos.
`events`	Os eventos mais recentes. O evento mais antigo vem primeiro.
`events_count`	O número de eventos que a execução enviou.
`events_by_type`	O número de eventos de cada tipo.
`triggered_by`	A identidade que iniciou a execução. Consulte Atribuição.
`execution_origin`	A origem da requisição. Consulte Origem da Execução.
`last_step`	O passo de agente mais recente. Somente para crews.
`last_executed_task`	A tarefa mais recente que o crew completou. Somente para crews.
`flow_id`	O identificador de um flow que espera feedback humano.
`source`	A origem dos dados: `memory` ou `application`.

Um campo que não tem valor é null.

Progresso

O objeto progress mostra quanto do trabalho está completo.

Campo	Descrição
`unit`	A unidade de trabalho. Um crew usa `task`. Um flow usa `step`.
`completed`	O número de unidades completas.
`total`	O número de unidades da execução.
`remaining`	O número de unidades que não estão completas.
`current`	O nome da tarefa ou do método que executa agora.
`current_agent`	O papel do agente que trabalha agora.
`started_at`	A hora em que o worker iniciou a execução.
`updated_at`	A hora da alteração mais recente.
`duration_seconds`	O número de segundos do início até `updated_at`.

Um flow seleciona o próximo passo enquanto executa. O número de passos não é conhecido antes de o flow parar. Para um flow, total e remaining são sempre null:

{
  "unit": "step",
  "completed": 4,
  "total": null,
  "remaining": null,
  "current": "summarize",
  "current_agent": null,
  "started_at": "2025-09-10T18:00:00+00:00",
  "updated_at": "2025-09-10T18:00:41+00:00",
  "duration_seconds": 41.2
}

Não calcule uma porcentagem para um flow. Mostre o valor de completed como uma contagem de passos.

Eventos

Um evento mostra o que a execução fez em um dado momento. Cada evento é um resumo. Um evento não contém os prompts, as saídas nem o estado do flow.

Campo	Descrição
`type`	O tipo do evento, por exemplo `task_started`.
`timestamp`	A hora do evento.
`crew_name`	O nome do crew, se o evento tiver um.
`flow_name`	O nome do flow, se o evento tiver um.
`method_name`	O nome do método do flow, se o evento tiver um.
`task_name`	O nome da tarefa, se o evento tiver um.
`agent_role`	O papel do agente, se o evento tiver um.
`tool_name`	O nome da ferramenta, se o evento tiver um.
`model`	O nome do modelo, se o evento tiver um.
`error`	A mensagem de erro, se o evento tiver uma.

A lista events mantém os 100 eventos mais recentes. Se a execução enviar mais eventos, a plataforma remove os eventos mais antigos da lista. O campo events_count dá o número de todos os eventos. O campo events_by_type também conta todos os eventos. Esses dois campos continuam corretos quando a lista está cheia.

Atribuição

O objeto triggered_by mostra quem iniciou a execução.

Campo	Descrição
`type`	O tipo da identidade: `user`, `service_account` ou `unknown`.
`id`	O identificador da identidade no CrewAI AMP.

A resposta dá apenas o tipo e o identificador. Ela não dá o nome, o endereço de e-mail nem a organização. Cada token de um deployment pode ler o status de cada execução desse deployment. A resposta não inclui dados pessoais. Se a requisição usar o AUTH_TOKEN fixo do deployment, o tipo é unknown. Se a plataforma não souber a identidade, triggered_by é null.

Origem da Execução

O campo execution_origin mostra como a execução começou.

Valor	Descrição
`ui`	Um usuário iniciou a execução na interface do CrewAI AMP.
`schedule`	Um agendamento iniciou a execução.
`trigger`	Um gatilho de automação iniciou a execução.
`chat`	Uma mensagem de chat iniciou a execução.
`hitl-resume`	A plataforma continuou a execução após o feedback humano.
`replay`	Um replay iniciou a execução.
`api`	Uma requisição à API do deployment iniciou a execução.

Configurações Opcionais

Defina estas variáveis de ambiente no deployment para alterar o log de eventos.

Variável	Padrão	Descrição
`CREWAI_STATUS_EVENTS`	`true`	Defina o valor como `false` para parar o log de eventos e os dados de progresso.
`CREWAI_STATUS_MAX_EVENTS`	`100`	O número de eventos na lista `events`.
`CREWAI_STATUS_EVENT_FLUSH_SECONDS`	`2.0`	O número mínimo de segundos entre duas escritas do log de eventos.

Estes limites se aplicam:

Um deployment que executa o crewAI 1.15.21 ou anterior retorna null para os dados de progresso e para os dados de eventos. Atualize a versão do crewAI no seu projeto e faça o deploy da crew novamente.
Uma execução que espera na fila tem o estado PENDING. Ela retorna null para triggered_by.
Um flow que continua após feedback humano conta apenas os passos após o feedback.
Uma resposta com "source": "application" retorna null para os dados de progresso e para os dados de eventos.

Gerenciando Execuções

Execuções de Longa Duração

Para execuções que possam demandar mais tempo:

Considere implementar um mecanismo de polling para verificar status periodicamente
Utilize webhooks (se disponíveis) para notificação quando a execução for concluída
Implemente tratamento de erros para possíveis timeouts

Contexto da Execução

O contexto da execução inclui:

Inputs fornecidos no momento do kickoff
Variáveis de ambiente configuradas durante o deploy
Qualquer estado mantido entre as tarefas

Depuração de Execuções com Falha

Se uma execução falhar:

Verifique a aba “Executions” para logs detalhados
Avalie a aba “Traces” para detalhes passo a passo da execução
Procure por respostas LLM e uso de ferramentas nos detalhes do trace

Precisa de Ajuda?

Entre em contato com nossa equipe de suporte para obter ajuda com problemas de execução ou dúvidas sobre a plataforma Enterprise.

Começando

Construir

Operar

Gerenciar

Documentação de Integração

Guias

Triggers

Recursos

Visão Geral

Método 1: Usando a Interface Web

Passo 1: Navegue até seu Crew Implantado

Passo 2: Iniciar Execução

Opção A: Kickoff Rápido

Opção B: Usando a Interface Visual

Passo 3: Monitorar o Progresso da Execução

Passo 4: Verificar o Status da Execução

Passo 5: Visualizar Resultados Finais

Método 2: Usando a API

Autenticação

Verificando o Status do Crew

Passo 1: Recuperar Entradas Necessárias

Passo 2: Iniciar Execução

Passo 3: Verificar Status da Execução

Campos da Resposta

Progresso

Eventos

Atribuição

Origem da Execução

Configurações Opcionais

Gerenciando Execuções

Execuções de Longa Duração

Contexto da Execução

Depuração de Execuções com Falha

Precisa de Ajuda?

​Visão Geral

​Método 1: Usando a Interface Web

​Passo 1: Navegue até seu Crew Implantado

​Passo 2: Iniciar Execução

​Opção A: Kickoff Rápido

​Opção B: Usando a Interface Visual

​Passo 3: Monitorar o Progresso da Execução

​Passo 4: Verificar o Status da Execução

​Passo 5: Visualizar Resultados Finais

​Método 2: Usando a API

​Autenticação

​Verificando o Status do Crew

​Passo 1: Recuperar Entradas Necessárias

​Passo 2: Iniciar Execução

​Passo 3: Verificar Status da Execução

​Campos da Resposta

​Progresso

​Eventos

​Atribuição

​Origem da Execução

​Configurações Opcionais

​Gerenciando Execuções

​Execuções de Longa Duração

​Contexto da Execução

​Depuração de Execuções com Falha

Precisa de Ajuda?

Visão Geral

Método 1: Usando a Interface Web

Passo 1: Navegue até seu Crew Implantado

Passo 2: Iniciar Execução

Opção A: Kickoff Rápido

Opção B: Usando a Interface Visual

Passo 3: Monitorar o Progresso da Execução

Passo 4: Verificar o Status da Execução

Passo 5: Visualizar Resultados Finais

Método 2: Usando a API

Autenticação

Verificando o Status do Crew

Passo 1: Recuperar Entradas Necessárias

Passo 2: Iniciar Execução

Passo 3: Verificar Status da Execução

Campos da Resposta

Progresso

Eventos

Atribuição

Origem da Execução

Configurações Opcionais

Gerenciando Execuções

Execuções de Longa Duração

Contexto da Execução

Depuração de Execuções com Falha