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

# Ejecutar agentes vía API

> Crea un run, sigue su estado y recoge la respuesta del agente

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](/es/api/overview#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.

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

<ParamField body="input.message" type="string" required>
  La instrucción para el agente. Hasta 128 KiB.
</ParamField>

<ParamField body="input.data" type="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.
</ParamField>

<ParamField body="metadata" type="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.
</ParamField>

<ParamField body="sessionId" type="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.
</ParamField>

<ParamField body="callbackUrl" type="string">
  URL HTTPS notificada cuando el run termina. Mira
  [Webhooks de finalización](/es/api/webhooks).
</ParamField>

<ParamField body="title" type="string">
  Título opcional para la nueva sesión, visible en el panel.
</ParamField>

La respuesta es `202 Accepted` con el recurso del run:

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

<Note>
  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](/es/api/overview#idempotencia).
</Note>

## Seguir el run

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

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

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

<Note>
  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.
</Note>

¿Prefieres no consultar en bucle? Registra un `callbackUrl` y recibe un webhook firmado al finalizar — mira [Webhooks de finalización](/es/api/webhooks).

## Listar runs

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

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

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