Pular para o conteúdo principal

Começando

Montando um workflow do começo ao fim: chega uma nota fiscal, o agente lê e um pagamento é criado no seu ERP com o PDF original anexado.

Quatro passos, nenhum deles envolvendo deploy do seu lado.

1. Guarde a credencial​

O agente vai referenciá-la pelo nome, então o valor nunca aparece em um prompt.

curl -X POST https://api.inbox.kobana.com.br/v1/secrets \
  --cert ./client.crt --key ./client.key \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "FINANCE_TOKEN",
    "value": "erp-service-account-token",
    "notes": "Conta de serviço do ERP — rotaciona a cada 90 dias"
  }'
{
  "data": {
    "id": "f1e2d3c4-b5a6-4978-8899-aabbccddeeff",
    "key": "FINANCE_TOKEN",
    "notes": "Conta de serviço do ERP — rotaciona a cada 90 dias",
    "last_used_at": null
  }
}

A resposta não tem value, e nenhuma leitura posterior terá: o valor é somente escrita. Rotacionar depois é um PUT /v1/secrets com a mesma key — sem buscar id, sem mexer no agente.

2. Ensine o agente a emitir um workflow​

A plataforma executa o que o agente devolve; ela não escreve o workflow. Isso é papel do system_message do agente:

curl -X PATCH https://api.inbox.kobana.com.br/v1/agents/$AGENT_ID \
  --cert ./client.crt --key ./client.key \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "system_message": "Você lê notas fiscais recebidas por e-mail e as registra no ERP.\n\nResponda com um único objeto JSON com duas chaves:\n\n- `result`: os dados que você extraiu (fornecedor, valor, vencimento, número do documento).\n- `workflow`: as requisições necessárias para registrar, ou omita a chave quando nenhuma ação for necessária.\n\nCada passo do workflow é:\n{\"type\":\"request\",\"method\":\"POST\",\"url\":\"…\",\"headers\":{…},\"body\":{…},\"expected_status\":201}\n\nRegras:\n- Autentique com `${{secrets.FINANCE_TOKEN}}`. NUNCA escreva uma credencial literalmente.\n- Crie o pagamento primeiro, depois anexe o documento ao id que a primeira chamada devolveu, usando `${{steps.0.response.body.data.id}}`.\n- Inclua `${{kobana.email_id}}` no corpo do pagamento para o registro apontar de volta para o e-mail.\n- Se a nota for duplicada ou você não tiver confiança, devolva só `result`, sem `workflow`."
}
JSON

Todo PATCH que altera system_message incrementa Agent.version e salva um snapshot do prompt, então cada execução registra exatamente quais instruções produziram aquele workflow.

3. Envie um e-mail de teste​

Envie uma mensagem real para o endereço da inbox, ou submeta um .eml pela API — ele segue o mesmo caminho, incluindo filtros, agente e webhooks:

curl -X POST "https://api.inbox.kobana.com.br/v1/emails?inbox_id=$INBOX_ID" \
  --cert ./client.crt --key ./client.key \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: message/rfc822" \
  --data-binary @nota.eml

4. Leia o que aconteceu​

curl "https://api.inbox.kobana.com.br/v1/workflow-runs?email_id=$EMAIL_ID" \
  --cert ./client.crt --key ./client.key \
  -H "Authorization: Bearer $JWT"

Depois abra a execução para ver cada passo, a requisição como enviada e a resposta recebida:

curl "https://api.inbox.kobana.com.br/v1/workflow-runs/$RUN_ID" \
  --cert ./client.crt --key ./client.key \
  -H "Authorization: Bearer $JWT"
{
  "data": {
    "status": "success",
    "summary": { "total": 2, "succeeded": 2, "error": 0 },
    "duration_ms": 812,
    "steps": [
      {
        "position": 0,
        "status": "success",
        "request": {
          "method": "POST",
          "url": "https://erp.example.com/payables",
          "headers": { "Authorization": "Bearer [REDACTED]" }
        },
        "response": {
          "status": 201,
          "expected_status": 201,
          "body": "{\"data\":{\"id\":\"pay_42\"}}"
        }
      },
      {
        "position": 1,
        "status": "success",
        "request": { "url": "https://erp.example.com/payables/pay_42/attachments" },
        "response": { "status": 200 }
      }
    ]
  }
}

Repare no pay_42 na URL do segundo passo: o agente escreveu ${{steps.0.response.body.data.id}} e a plataforma resolveu a partir da primeira resposta.

5. Reagir em tempo real (opcional)​

Em vez de ficar consultando, assine os eventos terminais:

curl -X POST https://api.inbox.kobana.com.br/v1/webhooks \
  --cert ./client.crt --key ./client.key \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "resultado dos workflows",
    "url": "https://ops.example.com/hooks/kobana",
    "subscribed_events": ["workflow.run.succeeded", "workflow.run.failed"]
  }'

workflow.run.failed carrega data.failed_step, data.failed_steps (todos os passos que falharam) e data.error, além dos snapshots habituais de email e agent_run — o suficiente para abrir um chamado sem nos chamar de volta.

Fazendo o mesmo por um cliente de IA​

Cada passo acima existe como ferramenta MCP: secrets_create, agents_update, workflow_runs_list e workflow_runs_get. Submeter um .eml de teste não tem ferramenta — é upload de corpo cru, então use o endpoint HTTP acima ou emails_reprocess em uma mensagem que você já recebeu.

Para onde ir depois​