Saltar al contenido principal

Primeros pasos

Montar un workflow de punta a punta: llega una factura, el agente la lee y se crea una cuenta a pagar en su ERP con el PDF original adjunto.

Cuatro pasos, ninguno de los cuales implica desplegar nada de su lado.

1. Guarde la credencial​

El agente la referenciará por nombre, así el valor nunca aparece en un 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": "Cuenta de servicio del ERP — rota cada 90 días"
  }'
{
  "data": {
    "id": "f1e2d3c4-b5a6-4978-8899-aabbccddeeff",
    "key": "FINANCE_TOKEN",
    "notes": "Cuenta de servicio del ERP — rota cada 90 días",
    "last_used_at": null
  }
}

La respuesta no trae value, y ninguna lectura posterior lo hará: el valor es de solo escritura. Rotarlo después es un PUT /v1/secrets con la misma key — sin buscar el id, sin tocar el agente.

2. Enseñe al agente a emitir un workflow​

La plataforma ejecuta lo que el agente devuelve; no lo escribe. Eso corresponde al system_message del 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": "Lees facturas recibidas por correo y las registras en el ERP.\n\nResponde con un único objeto JSON con dos claves:\n\n- `result`: los datos que extrajiste (proveedor, importe, vencimiento, número de documento).\n- `workflow`: las peticiones necesarias para registrarla, u omite la clave cuando no haga falta ninguna acción.\n\nCada paso del workflow es:\n{\"type\":\"request\",\"method\":\"POST\",\"url\":\"…\",\"headers\":{…},\"body\":{…},\"expected_status\":201}\n\nReglas:\n- Autentica con `${{secrets.FINANCE_TOKEN}}`. NUNCA escribas una credencial literalmente.\n- Crea la cuenta a pagar primero y luego adjunta el documento al id que devolvió la primera llamada, usando `${{steps.0.response.body.data.id}}`.\n- Incluye `${{kobana.email_id}}` en el cuerpo para que el registro apunte de vuelta al correo.\n- Si la factura está duplicada o no tienes confianza, devuelve solo `result`, sin `workflow`."
}
JSON

Cada PATCH que cambia system_message incrementa Agent.version y guarda una instantánea del prompt, así cada ejecución registra exactamente qué instrucciones produjeron su workflow.

3. Envíe un correo de prueba​

Envíe un mensaje real a la dirección del inbox, o suba un .eml por la API — recorre el mismo camino, filtros, agente y webhooks incluidos:

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 @factura.eml

4. Lea qué pasó​

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

Después abra la ejecución para ver cada paso, la petición tal como se envió y la respuesta recibida:

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 }
      }
    ]
  }
}

Fíjese en pay_42 en la URL del segundo paso: el agente escribió ${{steps.0.response.body.data.id}} y la plataforma lo resolvió desde la primera respuesta.

5. Reaccionar en tiempo real (opcional)​

En vez de consultar en bucle, suscríbase a los eventos terminales:

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 de los workflows",
    "url": "https://ops.example.com/hooks/kobana",
    "subscribed_events": ["workflow.run.succeeded", "workflow.run.failed"]
  }'

workflow.run.failed lleva data.failed_step, data.failed_steps (todos los pasos que fallaron) y data.error, además de las instantáneas habituales de email y agent_run — suficiente para abrir un ticket sin volver a llamarnos.

Lo mismo desde un cliente de IA​

Cada paso de arriba existe como herramienta MCP: secrets_create, agents_update, workflow_runs_list y workflow_runs_get. Subir un .eml de prueba no tiene herramienta — es una subida de cuerpo crudo, así que use el endpoint HTTP de arriba o emails_reprocess sobre un mensaje que ya recibió.

A dónde ir después​