Workflows · Documentation Ephemeral

Enregistrez des définitions d'exécution sous un nom et lancez-les avec POST /v1/runs. Les clés member et admin peuvent utiliser tous les endpoints de cette page. Voir workflows pour la façon dont les champs enregistrés et les remplacements se combinent.

Enregistrer un workflow

PUT/v1/workflows/{name}

Crée le workflow, ou le remplace si le nom existe. Les noms commencent par une lettre ou un chiffre et contiennent jusqu'à 128 lettres, chiffres, _, . ou -.

Corps

promptstringobligatoire

La tâche. 128 Kio au maximum.

modelstring

ID du modèle. En son absence, chaque exécution utilise le modèle par défaut au moment de sa création.

filesarray

Entrées de fichiers, comme dans une requête d'exécution. Les noms sont résolus à la création de chaque exécution.

connectionsobject

Connexions indexées par le nom que voit l'agent. Préférez les entrées {"ref": "<saved name>"}.

descriptionstring

Ce que fait le workflow et quelle entrée il attend. 500 caractères au maximum.

input_schemaobject

Un JSON Schema auquel l'input de chaque exécution doit correspondre ; une exécution qui ne correspond pas est refusée avec 400. Voir décrire l'entrée et la sortie.

output_schemaobject

Un JSON Schema auquel la sortie de chaque exécution doit correspondre ; la sortie est alors du JSON, et une exécution dont la sortie ne correspond pas échoue. Voir décrire l'entrée et la sortie.

timeout_secondsinteger

De 1 à 3600. Les exécutions utilisent 300 en son absence.

shellboolean

Les exécutions utilisent true en son absence.

webboolean | object

Accès web pour les exécutions du workflow : true, ou un objet avec allow et search. Désactivé en son absence.

Un workflow ne peut pas contenir input, max_cost_micros ni callback ; ces champs relèvent de chaque exécution. La réponse est {"name": "investigate-payment"}.

curl -X PUT $EPHEMERAL_URL/v1/workflows/investigate-payment \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find out why this payment failed. Follow the playbook.",
    "model": "anthropic/claude-haiku-5.5",
    "files": [{ "file": "playbook.md" }],
    "connections": { "payments": { "ref": "payments-api", "allowed_methods": ["GET"] } },
    "timeout_seconds": 120,
    "shell": false
  }'

Lancer un workflow

Envoyez le nom du workflow à POST /v1/runs avec l'entrée et le budget de cette exécution. Tout champ de définition que vous incluez remplace la valeur enregistrée pour cette exécution ; files et connections remplacent la collection entière.

Terminal

curl $EPHEMERAL_URL/v1/runs \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workflow":"investigate-payment","input":{"payment_id":"pay_123"},"max_cost_micros":500000}'

Si le workflow n'existe pas, la requête échoue avec 400 et le message saved workflow not found.

Lister les workflows

GET/v1/workflows

Renvoie les workflows de l'organisation par ordre alphabétique, chacun sous la forme d'un objet avec son name. Ajoutez ?detail=true pour inclure la description, l'input_schema et l'output_schema de chaque workflow qui en a. Récupérez un workflow par son nom pour voir toute sa définition.

JSON

[{ "name": "investigate-payment" }, { "name": "weekly-report" }]

Avec ?detail=true, un agent voit ce que chaque workflow attend et renvoie :

JSON

[
  {
    "name": "weather",
    "description": "Current weather for a city. Input is a city name.",
    "input_schema": { "type": "object", "required": ["city"], "properties": { "city": { "type": "string" } } },
    "output_schema": { "type": "object", "required": ["city", "temperature_c", "summary"] }
  },
  { "name": "weekly-report" }
]

Lire un workflow

GET/v1/workflows/{name}

Renvoie la définition enregistrée. Les identifiants des connexions en ligne sont retirés et les valeurs de requête de leurs URL sont masquées.

Pour modifier un workflow, récupérez-le, changez-le et réenregistrez-le avec PUT. Les champs d'identifiants que vous laissez vides conservent leurs valeurs stockées, tant que le type d'authentification de la connexion reste inchangé.

Supprimer un workflow

DELETE/v1/workflows/{name}

Supprime le workflow et renvoie 204 No Content. Les exécutions qui l'ont déjà utilisé ne sont pas affectées.

Les workflows ne sont pas versionnés. L'enregistrer ou le supprimer prend effet pour la prochaine exécution qui le nomme.