Ejecuciones

Una ejecución es un agente que trabaja en una tarea en su propia microVM. Envías un prompt, una entrada JSON y los archivos y conexiones que puede usar. Ephemeral la pone en cola, inicia una máquina nueva, registra cada paso y destruye la máquina cuando termina la ejecución.

De qué se compone una ejecución

Toda ejecución tiene un prompt y una entrada opcional. El resto de la definición decide qué modelo usa, qué puede leer, a qué puede llamar, cuánto puede tardar y cuánto puede gastar. Puedes enviar toda la definición en línea, o indicar el nombre de un flujo de trabajo guardado y enviar solo la entrada.

{
  "prompt": "Find out why this payment failed. Follow the playbook.",
  "input": { "payment_id": "pay_123" },
  "model": "anthropic/claude-haiku-5.5",
  "files": [{ "file": "playbook.md" }],
  "connections": { "payments": { "ref": "payments-api", "allowed_methods": ["GET"] } },
  "timeout_seconds": 120,
  "shell": false,
  "max_cost_micros": 500000
}

Dentro de la microVM, el agente siempre puede leer los archivos que montaste. Con shell activado, que es lo predeterminado, también puede ejecutar comandos de shell y escribir archivos en su directorio de trabajo. Cada conexión que concedes añade herramientas a las que puede llamar, y con el acceso web activado puede leer páginas, buscar y llamar a API públicas. La máquina en sí no tiene internet. El directorio de trabajo se descarta junto con la máquina, así que nada pasa a la siguiente ejecución.

Ciclo de vida

Una ejecución pasa por estos estados. Los últimos cinco son finales; cuando una ejecución llega a uno de ellos, ya no vuelve a cambiar.

Las ejecuciones salen de la cola en el orden en que se crearon. Una instalación autoalojada ejecuta dos a la vez por defecto; el resto espera en queued. El tiempo límite se cuenta desde el momento en que una ejecución sale de la cola, así que el tiempo de espera no lo consume.

Límites

Seguir una ejecución

Hay tres formas de saber qué está haciendo una ejecución y cuándo termina.

• Consulta GET /v1/runs/{id} repetidamente hasta que el estado sea final.
• Transmite GET /v1/runs/{id}/events. Es un flujo de eventos enviados por el servidor que reproduce todo lo registrado hasta el momento y después continúa en vivo hasta que termina la ejecución.
• Configura un callback en la ejecución. Ephemeral envía una solicitud firmada a tu servidor cuando la ejecución alcanza un estado final.

Cerrar el flujo de eventos no afecta a la ejecución. Puedes reconectarte con el último ID de evento que recibiste y continuar desde ahí.

Tipos de evento

Ephemeral elimina los valores de credenciales conocidos, como los tokens de las conexiones, de los eventos y del resultado antes de almacenarlos. La referencia de la API muestra el formato exacto del flujo.

Cancelar una ejecución

POST /v1/runs/{id}/cancel detiene una ejecución que está en reserving, queued, starting o running. Se detiene el worker y se termina la microVM. Cancelar una ejecución que ya ha terminado no cambia nada.

Retención cero de datos

Establece zero_data_retention en true en una ejecución, o en un flujo de trabajo guardado, cuando la tarea sea sensible. Ephemeral no registra entonces nada del contenido de la ejecución: solo recibes la salida.

• Los eventos siguen llegando en directo mientras la ejecución trabaja, con GET /v1/runs/{id}/events en cualquier motor. Se guardan en un almacén transitorio y se eliminan unos minutos después de que termine la ejecución.
• La salida se devuelve una vez. El primer GET /v1/runs/{id} tras terminar la ejecución la incluye y la elimina. Si hay un callback, este entrega la salida y las lecturas la dejan en su sitio hasta entonces. En cualquier caso se elimina como máximo después de una hora. output_available y output_expires_at indican si todavía se conserva.
• Las llamadas al modelo van solo a proveedores que no conservan tus datos ni entrenan con ellos. Un modelo sin un proveedor así se rechaza con 400 antes de reservar nada.
• En el servicio alojado la ejecución cuesta un 10 % más: el recargo se aplica al cómputo, las llamadas al modelo y las solicitudes web, cuenta para el presupuesto y aparece en el desglose del coste. Las instalaciones autoalojadas no cobran nada extra.
• Los datos transitorios viven en tablas que todas las copias de seguridad omiten, así que una base de datos restaurada nunca los contiene.

Después de una ejecución

La ejecución conserva su resultado, mensaje de error, marcas de tiempo, eventos y coste. Considera el coste como definitivo cuando el estado es final y billing_pending es false; consulta presupuestos y facturación.

Las ejecuciones terminadas se eliminan 30 días después de finalizar, junto con sus eventos. Una ejecución se conserva más tiempo mientras su facturación, la entrega del callback o la limpieza de la microVM siguen pendientes. Las instalaciones autoalojadas pueden cambiar el periodo de retención.

Para volver a ejecutar la misma tarea, obtén GET /v1/runs/{id}/definition. Devuelve la definición que la ejecución usó realmente, sin credenciales, para que puedas revisarla, fijar un nuevo presupuesto y enviarla.