Executar workflows a partir de um agente externo

Um agente externo é um agente de IA que roda fora da Jelou: Microsoft Copilot Studio, Amazon Bedrock Agents, um runtime próprio ou qualquer modelo com chamada de ferramentas. Com este guia, esse agente pode iniciar workflows publicados no Brain Studio, por exemplo um onboarding ou uma abertura de conta que pedem documento, e-mail e endereço, e deixar que o workflow conduza a conversa com o cliente até terminar.

Neste guia, skill e workflow significam a mesma coisa: um fluxo publicado do seu projeto que pode ser executado de fora.

Como funciona

O agente decide quando executar um workflow. O workflow decide o que perguntar e coleta os dados.

O cliente escreve para o seu agente

Por exemplo: “Quero abrir uma conta poupança”.

Seu agente inicia o workflow

Ele chama a Jelou por MCP ou pela API REST com o identificador do cliente. A Jelou responde com um executionId e executa o workflow em segundo plano.

O workflow conversa com o cliente

O workflow envia suas mensagens para o WhatsApp do cliente: pede o documento, mostra botões ou abre um formulário. A Jelou encaminha as respostas do cliente ao workflow. Enquanto isso, seu agente não responde.

O workflow termina e a conversa volta para o seu agente

Quando a execução chega a um estado final (concluída, com falha ou cancelada), seu agente retoma a conversa.

Diagrama de sequência: o cliente escreve para o seu agente, seu agente inicia o workflow na Jelou e recebe um executionId, o workflow pede o documento e abre um formulário seguro enquanto seu agente fica em silêncio, e ao terminar a conversa volta para o seu agente

O erro mais comum é o agente continuar respondendo enquanto o workflow espera a resposta do cliente. O cliente recebe duas respostas ao mesmo tempo e o workflow perde o dado que esperava. Enquanto houver um workflow ativo para esse cliente, seu agente deve ficar em silêncio.

Escolha como se conectar

Opção	Use se…	O que seu agente recebe
MCP	Seu agente fala MCP: Copilot Studio, Amazon Bedrock Agents, Claude, OpenAI Agents etc.	Cada workflow publicado aparece como uma ferramenta. A chamada espera até o workflow precisar de uma resposta ou terminar.
API REST	Qualquer backend ou agente que faça chamadas HTTP.	Você inicia o workflow com uma chamada e consulta o resultado pelo `executionId`.
Canal personalizado	Seu app é o canal (web, app móvel) e você não usa WhatsApp.	A Jelou envia as mensagens do workflow para o seu `webhookUrl`. Consulte Canal personalizado.

As opções MCP e API REST deste guia são para conversas de WhatsApp.

Requisitos, do zero

Um workflow publicado

Crie e publique o workflow no Brain Studio (por exemplo, Abertura de conta). Teste primeiro pelo próprio WhatsApp do bot para confirmar que ele funciona sozinho.

Um canal de WhatsApp conectado ao projeto

O workflow envia suas mensagens pelo bot de WhatsApp do projeto. Anote o botId desse canal.

Uma chave de API com os scopes corretos

Crie uma chave em Chaves de API com estes scopes:

Scope	Para
`workflows:read`	Listar os workflows do projeto
`workflows:execute`	Iniciar workflows (e usar MCP)
`executions:read`	Consultar o resultado de uma execução

Chame sempre por https://gateway.jelou.ai: é lá que os scopes da chave são aplicados. A chave vai no cabeçalho x-api-key.

Os identificadores

brainId: o identificador do projeto.
skillId: o identificador do workflow (você o obtém ao listar os workflows).
referenceId: o identificador do cliente no WhatsApp, normalmente o número sem + (por exemplo, 50712345678).

Fazer as mensagens do cliente chegarem ao seu agente

Se é o seu agente que atende o WhatsApp do bot, a Jelou precisa encaminhar para ele as mensagens recebidas por esse bot. Esse redirecionamento é configurado pela equipe da Jelou: solicite-o informando o bot e a URL do seu agente. Enquanto houver um workflow ativo, seu agente devolve à Jelou cada mensagem do cliente sem respondê-la, para que chegue ao workflow. A equipe da Jelou explica como devolvê-las ao configurar o redirecionamento.

Opção A: MCP

Conecte seu agente como cliente MCP ao servidor de workflows do seu projeto:

https://gateway.jelou.ai/workflows/mcp/{brainId}

Autentique com o cabeçalho x-api-key. O servidor expõe:

Uma ferramenta por workflow publicado do projeto, com os dados de entrada do workflow como parâmetros e um campo _context para o cliente.
workflow_reply, para passar ao workflow a resposta do cliente.

Passo a passo

Inicie o workflow

Chame a ferramenta do workflow com o cliente em _context:

{
  "_context": { "referenceId": "50712345678", "channel": "WHATSAPP" }
}

A chamada espera até o workflow precisar de uma resposta do cliente ou terminar, por no máximo cerca de 120 segundos. A resposta tem este formato:

{
  "status": "pending_input",
  "executionId": "8f2c…",
  "outbox": [ { "type": "TEXT", "text": "Para começar, pode me informar o número do seu documento?" } ],
  "cursor": 1
}

Não repita o outbox

outbox contém as mensagens que o workflow já entregou ao cliente pelo WhatsApp. Seu agente as lê para saber o que foi dito, mas não as envia de novo nem as parafraseia.

Espere a resposta real do cliente

Se status for pending_input, espere a próxima mensagem do cliente e repasse-a sem alterações:

{ "text": "8-123-4567", "_context": { "referenceId": "50712345678" } }

Nunca invente respostas nem preencha dados pelo cliente. O servidor encontra a execução ativa pelo referenceId: você não precisa enviar o executionId.

Repita até um estado final

`status`	O que fazer
`pending_input`	Espere a resposta do cliente e chame `workflow_reply(text)`
`running`	O workflow ainda está processando: chame `workflow_reply` com `text: ""` para continuar esperando
`completed` / `failed` / `cancelled`	Final. A conversa volta para o seu agente

Se a resposta indicar um conflito (claim.conflict, thread_busy), já existe uma execução em andamento para esse cliente. Não tente de novo nem inicie outra. Espere a atual terminar.

Opção B: API REST

Liste os workflows do projeto

curl "https://gateway.jelou.ai/workflows/v1/skills?brainId=SEU_BRAIN_ID&limit=100" \
  -H "x-api-key: SUA_CHAVE_API"

Use o id de cada workflow como skillId. A descrição de cada workflow é o que seu agente deve ler para decidir quando usá-lo.

Inicie o workflow

curl -X POST "https://gateway.jelou.ai/workflows/v2/skills/SEU_SKILL_ID/execute" \
  -H "x-api-key: SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
    "channel": "WHATSAPP",
    "origin": "API",
    "botId": "SEU_BOT_ID",
    "referenceId": "50712345678",
    "message": { "type": "text", "text": "Quero abrir uma conta poupança" }
  }'

string

obrigatório

O canal da conversa. Use WHATSAPP.

string

obrigatório

A origem da execução. Use API.

string

obrigatório

O bot de WhatsApp do projeto. Com botId e referenceId, a Jelou carrega o cliente real e o workflow escreve para ele.

string

obrigatório

O número de WhatsApp do cliente sem +.

object

O que o cliente pediu, com as palavras dele. Não inclua dados pessoais aqui (veja Dados pessoais).

Resposta:

{
  "status": "success",
  "message": "…",
  "data": { "executionId": "8f2c…" }
}

Esta chamada não tem chave de idempotência. Se ela falhar com um erro 5xx, não a repita automaticamente: a execução pode ter começado, e uma nova tentativa abriria uma segunda solicitação para o mesmo cliente. Consulte primeiro o resultado com o executionId, se você o tiver, ou avise o cliente sobre o erro.

Deixe o workflow conduzir

A Jelou envia as mensagens do workflow para o WhatsApp do cliente e encaminha as respostas dele ao workflow. Seu agente não as reenvia pela API. Enquanto o workflow estiver ativo:

não responda às mensagens do cliente;
devolva-as à Jelou sem alterações (veja o último passo de Requisitos);
guarde o executionId e marque a conversa como ocupada por um workflow.

Detecte quando termina

Consulte o resultado:

curl "https://gateway.jelou.ai/workflows/v1/executions/EXECUTION_ID/result" \
  -H "x-api-key: SUA_CHAVE_API"

Retorna { "executionId", "status", "output" }. output fica vazio até a execução terminar.

`status`	Significado
`STARTED`, `PROCESSING`	Em andamento
`WAITING`	Esperando o cliente (uma resposta ou um formulário)
`COMPLETED`	Terminou com sucesso. A conversa volta para o seu agente
`CANCELED`, `CRASHED`	Terminou sem concluir. A conversa volta para o seu agente

Consulte com intervalos crescentes (por exemplo, a cada poucos segundos) e defina seu próprio tempo máximo. Se o cliente abandonar o workflow, não espere para sempre para retomar a conversa.

Hoje só é possível cancelar execuções iniciadas por MCP. Uma execução iniciada pela API REST termina sozinha: ao ser concluída ou quando seu tempo de espera expira.

Formulários (webviews) dentro do workflow

Muitos workflows de dados pessoais abrem um formulário seguro em vez de pedir cada dado pelo chat. Por exemplo, um formulário de abertura com e-mail, endereço e atividade econômica. A Jelou abre o formulário com o executionId da execução. Quando o cliente o envia, o formulário devolve o resultado à Jelou e o workflow continua. Seu agente não faz nada nesta etapa: ele não intercepta o formulário nem reenvia seus dados. Se o workflow parecer parado em WAITING depois de enviar um formulário, o cliente provavelmente ainda não o preencheu.

Dados pessoais

Workflows de onboarding e abertura de conta lidam com dados sensíveis: documento, e-mail, endereço, renda. O desenho recomendado é que esses dados circulem apenas entre o cliente e o workflow, nunca pelo seu agente.

Não passe dados pessoais em message

Envie só o que o cliente pediu (“quero abrir uma conta”). O workflow pede o documento e os demais dados por conta própria, com suas validações. Se seu agente já conhece um dado, não o reenvie como texto livre: o workflow vai pedi-lo ou obtê-lo das próprias fontes.

Fixe a identidade no servidor, não no modelo

O referenceId, o botId e qualquer identificador do cliente devem vir da sessão do seu servidor, nunca do que o modelo escreve. Se o modelo pudesse escolher o referenceId, poderia iniciar um workflow para outra pessoa. Em agentes do Copilot Studio ou do Bedrock, passe esses valores pela configuração da ação ou pelo contexto da sessão, não como parâmetros que o modelo preenche.

Trate o outbox e os resultados como dados sensíveis

O outbox do MCP e o output de uma execução podem conter dados do cliente. Não os grave em logs, não os mostre em painéis e não os repasse a outros sistemas sem necessidade.

O que seu agente envia por conta própria não passa pelos filtros da Jelou

As mensagens enviadas pelo workflow passam pelos controles de dados da Jelou. As mensagens que seu agente envia diretamente ao cliente, não: aplique suas próprias regras de mascaramento antes de enviá-las.

Privilégio mínimo na chave de API

Dê à chave apenas os scopes que seu agente usa (workflows:read, workflows:execute, executions:read). Guarde-a como segredo da sua plataforma e gire-a se for exposta.

Exemplo completo: abertura de conta

O cliente: “Quero abrir uma conta poupança”

Seu agente reconhece a intenção e não pede dados por conta própria.

Seu agente inicia o workflow

Por MCP (a ferramenta do workflow com _context.referenceId) ou por REST (POST /v2/skills/{skillId}/execute). O referenceId vem da sessão do servidor. Marque a conversa como ocupada.

O workflow pede o documento

A mensagem chega ao WhatsApp do cliente. Seu agente não a repete.

O cliente responde com o documento

A Jelou entrega a resposta ao workflow. Com MCP, seu agente a repassa sem alterações com workflow_reply. Seu agente não a guarda nem a interpreta.

O workflow abre o formulário de dados

O cliente preenche e-mail e endereço no formulário seguro. O formulário devolve o resultado à Jelou.

O workflow termina

status passa a COMPLETED (REST) ou completed (MCP). Seu agente retoma a conversa: “Posso ajudar com mais alguma coisa?”

Conversa de WhatsApp de exemplo: o cliente pede para abrir uma conta, o agente responde, o workflow pede o documento e abre o formulário seguro, confirma a solicitação e o agente retoma a conversa

Solução de problemas

Sintoma	Causa provável	Solução
`401 Unauthorized`	Chave ausente ou inválida, ou falta um scope	Verifique `x-api-key` e os scopes da chave
`404 User or company could not be found`	`botId` ou `referenceId` não correspondem	Use o `botId` do canal de WhatsApp do projeto e o número sem `+`
O cliente recebe duas respostas	Seu agente respondeu com um workflow ativo	Deixe o agente em silêncio até a execução chegar a um estado final
São criadas duas solicitações para o mesmo cliente	Nova tentativa automática ou início duplicado	Não repita um 5xx às cegas. Com MCP, respeite `claim.conflict`
A execução fica em `WAITING`	O cliente não respondeu ou não preencheu o formulário	Espere e aplique seu próprio tempo máximo. Não inicie outra execução

Primeiros Passos

Desenvolvedor

Jelou CLI

Mensagens Outbound

Caixa de entrada

Marketplace

Canais

Configuração

Faturamento

Executar workflows a partir de um agente externo

Como funciona

Escolha como se conectar

Requisitos, do zero

Opção A: MCP

Passo a passo

Opção B: API REST

Formulários (webviews) dentro do workflow

Dados pessoais

Exemplo completo: abertura de conta

Solução de problemas

​Como funciona

​Escolha como se conectar

​Requisitos, do zero

​Opção A: MCP

​Passo a passo

​Opção B: API REST

​Formulários (webviews) dentro do workflow

​Dados pessoais

​Exemplo completo: abertura de conta

​Solução de problemas

Como funciona

Escolha como se conectar

Requisitos, do zero

Opção A: MCP

Passo a passo

Opção B: API REST

Formulários (webviews) dentro do workflow

Dados pessoais

Exemplo completo: abertura de conta

Solução de problemas