> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Executar workflows a partir de um agente externo

> Conecte um agente que roda fora da Jelou (Copilot Studio, Amazon Bedrock Agents, seu próprio runtime ou qualquer LLM com ferramentas) para que ele execute workflows publicados, como um onboarding ou uma abertura de conta, passo a passo e sem expor dados pessoais.

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.

> [!NOTE]
>
> 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.

**1. O cliente escreve para o seu agente**

Por exemplo: *"Quero abrir uma conta poupança"*.

**2. 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.

**3. 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.

**4. 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](https://mintcdn.com/jelouai/RsS2oQfVkEw3sI-F/assets/images/agentes-ia/agentes-externos-flujo_pt.png?fit=max\&auto=format\&n=RsS2oQfVkEw3sI-F\&q=85\&s=4f1b6ae574c617193c014225b9fbf174)

> [!WARNING]
>
> 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](https://docs.jelou.ai/pt/api/custom-channel/introducao.md). |

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

## Requisitos, do zero

**1. 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.

**2. Um canal de WhatsApp conectado ao projeto**

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

**3. Uma chave de API com os scopes corretos**

Crie uma chave em [Chaves de API](https://docs.jelou.ai/pt/guias/configuracao/chaves-api.md) 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`.

**4. 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`).

**5. 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

**1. Inicie o workflow**

Chame a ferramenta do workflow com o cliente em `_context`:

```json theme={null}
{
  "_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:

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

**2. 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.

**3. Espere a resposta real do cliente**

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

```json theme={null}
{ "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`.

**4. 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 |

> [!NOTE]
>
> 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

**1. Liste os workflows do projeto**

```bash theme={null}
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.

**2. Inicie o workflow**

```bash theme={null}
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" }
  }'
```

**channel** `string` *required*

O canal da conversa. Use `WHATSAPP`.

**origin** `string` *required*

A origem da execução. Use `API`.

**botId** `string` *required*

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

**referenceId** `string` *required*

O número de WhatsApp do cliente sem `+`.

**message** `object`

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

Resposta:

```json theme={null}
{
  "status": "success",
  "message": "…",
  "data": { "executionId": "8f2c…" }
}
```

> [!WARNING]
>
> 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.

**3. 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](#requisitos-do-zero));
* guarde o `executionId` e marque a conversa como *ocupada por um workflow*.

**4. Detecte quando termina**

Consulte o resultado:

```bash theme={null}
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.

> [!NOTE]
>
> 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

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

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

**2. 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.

**3. O workflow pede o documento**

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

**4. 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.

**5. 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.

**6. 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](https://mintcdn.com/jelouai/RsS2oQfVkEw3sI-F/assets/images/agentes-ia/agentes-externos-whatsapp_pt.png?fit=max\&auto=format\&n=RsS2oQfVkEw3sI-F\&q=85\&s=6cc317905cfce64e6ec2ce4bca27b088)

## 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.