API de Chat de Flow Conversacional

Visão Geral

Flows conversacionais implantados expõem uma API de sessão de chat na URL da automação. Em vez de uma única execução /kickoff, você cria uma sessão, envia mensagens do usuário como turnos, opcionalmente transmite tokens e eventos de runtime, e retoma pausas HITL quando um turno precisa de feedback humano.

O chat de Flow conversacional é experimental. Os endpoints só ficam disponíveis quando o Flow implantado reporta conversational: true e handle_turn: true em GET /inspect.

Para construir o Flow em si (conversational = True, handle_turn, routers, tracing), consulte o guia open-source Conversational Flows.

Pré-requisitos

Implante uma automação Flow que implemente turnos conversacionais (handle_turn).
Copie o bearer token da aba Status da automação (o mesmo token usado em /kickoff).
Confirme que o chat está habilitado via /inspect (abaixo).

Todas as requisições usam:

Authorization: Bearer YOUR_FLOW_TOKEN

Os exemplos deste guia usam a base https://your-flow-url.crewai.com.

Descobrir capacidade de chat

curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/inspect

Procure por flow.chat:

{
  "flow": {
    "chat": {
      "conversational": true,
      "handle_turn": true,
      "transports": ["webhook"],
      "experimental": true
    }
  }
}

Se qualquer flag for falsa, os endpoints de chat retornam 404 com "Conversational flow chat is not available".

Loop de chat ponta a ponta

Iniciar uma sessão

Crie uma sessão de chat. Opcionalmente registre um webhook de turno concluído e webhooks de eventos para a vida da sessão.

curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "completedTurnWebhookUrl": "https://your-server.com/webhooks/completed-turn",
    "webhooks": {
      "url": "https://your-server.com/webhooks/events",
      "events": ["*"],
      "realtime": false,
      "authentication": {
        "strategy": "bearer",
        "token": "my-secret-token"
      }
    }
  }' \
  https://your-flow-url.crewai.com/chat/start

Resposta:

{ "session_id": "11111111-2222-3333-4444-555555555555" }

Um body vazio ({} ou sem body) é válido quando você não precisa de webhooks.

Enviar uma mensagem do usuário

Enfileire um turno para a sessão:

curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Where is my order?",
    "stream": true
  }' \
  https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/message

Resposta:

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "queued"
}

Campo	Descrição
`message`	Obrigatório. Mensagem atual do usuário neste turno.
`stream`	Padrão `true`. Quando `true`, frames de token/evento são publicados para clientes WebSocket/SSE.
`messageHistory`	Transcript de fallback opcional (`[{ "role", "content" }, ...]`). O histórico da sessão no servidor é autoritativo; isso só é usado quando o histórico armazenado está vazio.

Roles aceitos em messageHistory: user, assistant, system, tool.

Aguardar o fim do turno

Faça polling do turno com o kickoff_id retornado (mesma API de status de um kickoff normal de Flow):

curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/status/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Apenas um turno pode ficar ativo por sessão. Um segundo /message enquanto active_kickoff_id estiver definido retorna 409:

{
  "detail": {
    "code": "session_busy",
    "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

Aguarde até o histórico mostrar active_kickoff_id: null (ou o turno atingir status terminal / pausa) antes de enviar a próxima mensagem.

Ler o histórico da sessão

curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/history

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "messages": [
    { "role": "user", "content": "Where is my order?" },
    { "role": "assistant", "content": "Your order is on the way." }
  ],
  "active_kickoff_id": null
}

Streaming de um turno

O streaming é opcional. Use quando a UI precisar de tokens ou eventos de runtime durante o turno. Os frames sempre incluem tipos de ciclo de vida (turn_started, turn_completed, turn_failed, token, error). Frames event adicionais podem ser filtrados com o query param events (* ou lista separada por vírgulas).

Opção A: mensagem HTTP + anexar SSE

POST /chat/{session_id}/message com "stream": true.
Anexe-se ao turno ativo:

curl -N \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  "https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/stream/events?events=*&last_event_id=0-0"

SSE retorna frames JSON text/event-stream (data: {...}), mais comentários de keepalive. O stream termina em turn_completed ou turn_failed. Se não houver turno ativo, este endpoint retorna 409 (No active chat turn).

Opção B: WebSocket (anexar ou enviar)

wss://your-flow-url.crewai.com/chat/{session_id}/stream?token=YOUR_FLOW_TOKEN&events=*&last_event_id=0-0

Auth: passe o bearer token como query param token, ou como header Authorization: Bearer ... quando o cliente suportar headers em WebSocket. Comportamento:

Turno ativo já em execução — o socket anexa e emite primeiro turn_started com data.status: "attached", depois transmite frames até um tipo terminal.
Sem turno ativo — envie uma mensagem JSON para enfileirar um turno e então consuma o stream:

{
  "message": "Where is my order?",
  "messageHistory": [],
  "events": "*",
  "lastEventId": "0-0"
}

O servidor responde com turn_started (status: "queued") e então frames do stream para aquele kickoff_id. Use last_event_id / lastEventId para retomar após desconexões.

Exemplos de frames do stream

{
  "type": "turn_started",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "status": "queued" }
}

{
  "type": "token",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "content": "Your order" }
}

{
  "type": "turn_completed",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": {}
}

HITL dentro de uma sessão de chat

Se um turno pausar para feedback humano (status / estado PAUSED), retome com o mesmo endpoint de resume de Flow usado em execuções sem chat:

curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "FLOW_OR_SESSION_ID",
    "feedback": "approved"
  }' \
  https://your-flow-url.crewai.com/resume_feedback

Em seguida, faça polling do kickoff_id de resume da resposta. Aguarde até /history mostrar active_kickoff_id: null antes de enviar a próxima mensagem de chat. Veja Workflows HITL e Gerenciamento HITL para Flows para a UX de revisão na plataforma.

Referência da API

Método	Path	Propósito
`GET`	`/inspect`	Descobrir se o chat conversacional está habilitado
`POST`	`/chat/start`	Criar uma sessão de chat
`POST`	`/chat/{session_id}/message`	Enfileirar um turno do usuário
`GET`	`/chat/{session_id}/history`	Ler mensagens e id do turno ativo
`GET`	`/chat/{session_id}/stream/events`	Stream SSE do turno ativo
`WS`	`/chat/{session_id}/stream`	Stream WebSocket (anexar ou enviar + stream)
`GET`	`/status/{kickoff_id}`	Polling do status de execução do turno (ou resume)
`POST`	`/resume_feedback`	Retomar um turno HITL pausado

Erros comuns

Status	Quando
`400`	`message` vazio
`404`	Chat não habilitado nesta implantação, ou `session_id` desconhecido
`409`	Sessão já tem turno ativo (`session_busy`), ou anexar SSE sem turno ativo
`422`	`session_id` não é um UUID válido
`503`	Armazenamento de sessão ou stream de chat indisponível

Relacionados

Conversational Flows

Construa Flows multi-turno com handle_turn, routers e tracing.

Kickoff Crew / Flow

Kickoff de execução única e polling de status na URL da implantação.

Webhook Streaming

Formato do payload de webhook de eventos e opções de autenticação.

Gerenciamento HITL para Flows

Revisão humana com email-first para etapas pausadas de Flow.

Começando

Construir

Operar

Gerenciar

Documentação de Integração

Guias

Triggers

Recursos

API de Chat de Flow Conversacional

Visão Geral

Pré-requisitos

Descobrir capacidade de chat

Loop de chat ponta a ponta

Streaming de um turno

Opção A: mensagem HTTP + anexar SSE

Opção B: WebSocket (anexar ou enviar)

Exemplos de frames do stream

HITL dentro de uma sessão de chat

Referência da API

Erros comuns

Relacionados

Conversational Flows

Kickoff Crew / Flow

Webhook Streaming

Gerenciamento HITL para Flows

​Visão Geral

​Pré-requisitos

​Descobrir capacidade de chat

​Loop de chat ponta a ponta

​Streaming de um turno

​Opção A: mensagem HTTP + anexar SSE

​Opção B: WebSocket (anexar ou enviar)

​Exemplos de frames do stream

​HITL dentro de uma sessão de chat

​Referência da API

​Erros comuns

​Relacionados

Conversational Flows

Kickoff Crew / Flow

Webhook Streaming

Gerenciamento HITL para Flows

Visão Geral

Pré-requisitos

Descobrir capacidade de chat

Loop de chat ponta a ponta

Streaming de um turno

Opção A: mensagem HTTP + anexar SSE

Opção B: WebSocket (anexar ou enviar)

Exemplos de frames do stream

HITL dentro de uma sessão de chat

Referência da API

Erros comuns

Relacionados