Ejecutar agentes vía API

Un run es una unidad de trabajo del agente iniciada por tu sistema: envías una instrucción, el agente la ejecuta, y el run lleva el estado y el resultado. Esta página recorre el ciclo completo — crear, consultar, recoger, cancelar.

Antes de empezar

Un token de API con modo read_write, creado en Settings → API tokens (autenticación).
El ID del agente, visible en la página del agente en el panel.

Crear un run

Envía la instrucción en input.message. Si el run reacciona a un evento, pon el payload del evento en input.data — el agente lo recibe como datos, nunca como instrucciones.

curl -X POST https://app.leme.ai/api/v1/agents/AGENT_ID/runs \
  -H "Authorization: Bearer leme_pat_v1_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-4821" \
  -d '{
    "input": {
      "message": "Califica este lead y responde con un resumen corto.",
      "data": { "leadId": "4821", "origen": "landing-page" }
    },
    "metadata": { "leadId": "4821" }
  }'

string

requerido

La instrucción para el agente. Hasta 128 KiB.

object

JSON libre con datos del evento, hasta 128 KiB. Llega al agente marcado como dato no confiable — úsalo para payloads que vienen del mundo externo.

object

Hasta 16 claves de texto (valores de hasta 512 caracteres). Se devuelve en el run y en los webhooks — úsalo para correlacionar con registros de tu sistema.

string

Continúa una sesión de API existente de este agente en lugar de iniciar una conversación nueva. Los runs de la misma sesión se procesan en orden.

string

URL HTTPS notificada cuando el run termina. Mira Webhooks de finalización.

string

Título opcional para la nueva sesión, visible en el panel.

La respuesta es 202 Accepted con el recurso del run:

{
  "id": "run_id",
  "object": "agent.run",
  "agentId": "agent_id",
  "sessionId": "session_id",
  "status": "queued",
  "statusDetail": null,
  "origin": "api",
  "input": { "message": "Califica este lead y responde con un resumen corto." },
  "output": null,
  "error": null,
  "metadata": { "leadId": "4821" },
  "createdAt": 1720000000000,
  "completedAt": null,
  "urls": { "self": "/api/v1/runs/run_id" }
}

Envía siempre un Idempotency-Key. Si tu solicitud se reintenta, recibes el run original en lugar de un duplicado. Detalles en la visión general de la API.

Seguir el run

Consulta la URL de urls.self hasta que el estado sea terminal:

curl https://app.leme.ai/api/v1/runs/RUN_ID \
  -H "Authorization: Bearer leme_pat_v1_..."

Estado	Significado	Terminal
`queued`	Esperando para empezar	No
`in_progress`	El agente está trabajando. `statusDetail: "delegated"` indica trabajo delegado a un proceso más largo	No
`waiting_approval`	En pausa esperando una aprobación humana en el panel	No
`completed`	Terminado — `output.text` trae la respuesta del agente	Sí
`failed`	Algo salió mal — mira `error.code` y `error.message`	Sí
`canceled`	Cancelado antes de empezar	Sí

Las respuestas no terminales incluyen un header retry-after con el intervalo sugerido entre consultas. Cuando el run termina:

{
  "id": "run_id",
  "status": "completed",
  "output": { "text": "Lead de alta prioridad: decisor en una empresa de 200 personas..." },
  "completedAt": 1720000042000
}

Un run en waiting_approval se reanuda cuando alguien aprueba la acción pendiente en el panel. Si registraste un callbackUrl, también recibes un evento run.waiting_approval en ese momento — útil para avisar a quien aprueba.

¿Prefieres no consultar en bucle? Registra un callbackUrl y recibe un webhook firmado al finalizar — mira Webhooks de finalización.

Listar runs

curl "https://app.leme.ai/api/v1/agents/AGENT_ID/runs?limit=20" \
  -H "Authorization: Bearer leme_pat_v1_..."

Devuelve { "runs": [...], "nextCursor": "..." }, del más reciente al más antiguo. Pasa cursor para la siguiente página y status para filtrar (por ejemplo, status=failed).

Cancelar un run

curl -X POST https://app.leme.ai/api/v1/runs/RUN_ID/cancel \
  -H "Authorization: Bearer leme_pat_v1_..."

Solo los runs todavía en queued pueden cancelarse. Un run ya en ejecución devuelve 409 not_cancellable; cancelar un run ya terminado es inofensivo y devuelve el recurso sin cambios.

Continuar una conversación

Cada run sin sessionId inicia una sesión nueva. Para mantener contexto entre runs — una conversación continua con el mismo agente — reutiliza el sessionId devuelto por el primer run:

curl -X POST https://app.leme.ai/api/v1/agents/AGENT_ID/runs \
  -H "Authorization: Bearer leme_pat_v1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "SESSION_ID",
    "input": { "message": "Ahora redacta un correo de seguimiento para ese lead." }
  }'

La sesión aparece en el panel como cualquier otra conversación, así que tu equipo puede leerla y retomarla en cualquier momento.

Primeros pasos

Agentes

Herramientas y permisos

Automatización

Artefactos

Espacio de trabajo

API

Ejecutar agentes vía API

Antes de empezar

Crear un run

Seguir el run

Listar runs

Cancelar un run

Continuar una conversación

​Antes de empezar

​Crear un run

​Seguir el run

​Listar runs

​Cancelar un run

​Continuar una conversación

Antes de empezar

Crear un run

Seguir el run

Listar runs

Cancelar un run

Continuar una conversación