Flujos de trabajo

Un flujo de trabajo es una definición de ejecución guardada con un nombre. Contiene el prompt, el modelo, los archivos, las conexiones, el tiempo límite y los ajustes de shell y web. Tu código lo inicia por su nombre y envía solo lo que cambia de una ejecución a otra.

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "max_cost_micros": 500000
}

Qué se guarda y qué envía cada ejecución

Guarda un flujo de trabajo en el panel, en Flujos de trabajo, con PUT /v1/workflows/{name} o con ephemeral workflows save. JSON es el formato de transmisión; la CLI también lee YAML. Los nombres empiezan por una letra o un dígito y pueden contener letras, dígitos, _, . y -, hasta 128 caracteres.

Sustituir campos guardados

Cualquiera de prompt, model, files, connections, timeout_seconds, shell y web en la solicitud de ejecución sustituye al valor guardado solo para esa ejecución. Los archivos y las conexiones se sustituyen como una colección completa. Nunca se combinan con los guardados.

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "connections": {},
  "max_cost_micros": 500000
}

Un objeto o array vacío borra esa colección para la ejecución. Para cambiar una conexión o un archivo, envía la lista completa que quieres que tenga la ejecución.

Cuándo se resuelven las referencias

Un flujo de trabajo hace referencia a archivos y conexiones guardadas por su nombre. Ephemeral resuelve esos nombres cuando se crea la ejecución, y la ejecución conserva lo que resolvió. Un nombre de archivo se resuelve a la última subida con ese nombre, así que subir una nueva versión de playbook.md cambia lo que lee la siguiente ejecución sin editar el flujo de trabajo.

Si un archivo o una conexión a los que se hace referencia ya no existen, la solicitud de ejecución falla con 400 e indica la referencia que falta. No se pone nada en cola y no se cobra nada.

Describir la entrada y la salida

Tres campos opcionales permiten que un flujo de trabajo se describa a sí mismo, para que personas, otro código y agentes de IA sepan cómo llamarlo sin leer su prompt. description dice en una o dos frases qué hace el flujo de trabajo y qué entrada espera (hasta 500 caracteres). input_schema es un JSON Schema al que debe ajustarse el input de la ejecución. output_schema es un JSON Schema al que debe ajustarse la salida de la ejecución. Los tres se devuelven con GET /v1/workflows?detail=true y con la herramienta MCP list_workflows, y también funcionan en una ejecución en línea.

description: Current weather for a city. Input is a city name.
prompt: Look up the current weather for the city in the input and report it.
web: true
input_schema:
  type: object
  required: [city]
  properties:
    city: { type: string }
output_schema:
  type: object
  required: [city, temperature_c, summary]
  properties:
    city: { type: string }
    temperature_c: { type: number }
    summary: { type: string }

La entrada se comprueba al crear una ejecución, ya venga de la API, de la CLI, de una herramienta MCP o de una programación. Si no coincide, la solicitud falla con 400 e indica cada problema como una ruta y un motivo, por ejemplo input.city: required. No se pone nada en cola y no se cobra nada. La entrada de una programación se comprueba al crearla o cambiarla y de nuevo en cada inicio; un inicio que ya no coincide queda registrado como el último error de la programación.

La salida debe ser JSON que cumpla output_schema. Al agente se le indica el esquema y se le pide que responda solo con el JSON. Si su respuesta no coincide, recibe los errores exactos y se le pide que la corrija, hasta dos veces. Después Ephemeral vuelve a comprobar la salida: si coincide, la ejecución queda en succeeded, con el texto JSON como salida y sin bloque de código alrededor. Si no coincide, la ejecución termina en failed con un error como output did not match output_schema: output.temperature_c: got string, want number, y se conserva el texto de la salida para que veas qué escribió el agente. Una ejecución con retención cero de datos no conserva ningún detalle en el error.

Los esquemas usan JSON Schema draft 2020-12 (un $schema que indique draft 7 o anterior también funciona), de hasta 32 KiB cada uno, y solo pueden referirse a definiciones dentro del propio esquema, como #/$defs/address. Un esquema no válido se rechaza con 400 al guardar el flujo de trabajo o crear la ejecución.

Editar un flujo de trabajo

Guardar de nuevo un flujo de trabajo lo reemplaza. No hay historial de versiones. Las ejecuciones creadas antes del cambio conservan la definición con la que se crearon; para ver exactamente qué usó una ejecución, lee su definición.

Leer un flujo de trabajo lo devuelve sin las credenciales de las conexiones ni los secretos de las URL. Si lo guardas de nuevo sin esos campos, se conservan las credenciales almacenadas mientras el tipo de autenticación siga siendo el mismo.