Agents et workflows

Un agent est un assistant enregistré : un prompt système, un modèle, les outils intégrés qu’il peut utiliser, des serveurs MCP distants, des bases de connaissances et des fichiers. Une tâche de workflow est une exécution d’IA sans intervention humaine : des instructions fixes envoyées à un modèle selon une planification cron ou à la demande, chaque lancement étant enregistré sous forme d’exécution. C’est le pendant API des Agents et des Workflows de l’application.

Tous les chemins sont relatifs à https://api.stickyprompts.com/api/v1. Chaque requête s’exécute au nom de l’utilisateur propriétaire de la clé API.

Conventions

• :id accepte soit l’ID numérique, soit le slug. Une valeur purement numérique est toujours traitée comme un ID.
• Les objets sérialisent leurs champs de base avec une majuscule (ID, CreatedAt, UpdatedAt, DeletedAt, ce dernier valant toujours null sur les lignes actives) ; tous les autres champs sont en snake_case.
• Les listes paginées acceptent page (par défaut 1) et size (par défaut 10), renvoient un simple tableau JSON et placent les totaux dans les headers de réponse X-Total-Count, X-Page et X-Page-Size.
• Les erreurs ont la forme {"error": "<message>"}. Les refus liés aux garde-fous et à la résidence des données ajoutent un code machine : {"error": "...", "code": "..."}.

Agents

L’API gère la configuration d’un agent. Pour discuter avec un agent, passez son agent_id lorsque vous démarrez une conversation, ou mentionnez son tag (@mention) : voir Conversations et messages.

L’objet Agent

{
  "ID": 412,
  "CreatedAt": "2026-09-28T09:14:03.512Z",
  "UpdatedAt": "2026-09-28T09:14:03.512Z",
  "DeletedAt": null,
  "user_id": 88,
  "name": "Support Triage",
  "slug": "k7Xq2bd",
  "tag": "support-triage",
  "icon": "headset",
  "color": "#3B82F6",
  "description": "Classifies Northwind support tickets and drafts replies",
  "system_prompt": "You are the first-line support agent for Northwind Analytics...",
  "ai_model_id": 31,
  "ai_model": { "ID": 31, "name": "...", "...": "..." },
  "tools": [{ "name": "web_search", "use": true }],
  "knowledge_base_limit_node_ids": null,
  "world_knowledge": false,
  "knowledge_bases": [{ "ID": 7, "...": "..." }]
}

POST /agents

Crée un agent.

curl -X POST https://api.stickyprompts.com/api/v1/agents \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Triage",
    "tag": "support-triage",
    "icon": "headset",
    "description": "Classifies Northwind support tickets and drafts replies",
    "system_prompt": "You are the first-line support agent for Northwind Analytics. Classify each ticket, rate urgency 1-3 and draft a reply.",
    "ai_model_id": 31,
    "tools": [{ "name": "web_search", "use": false }],
    "knowledge_base_ids": [7]
  }'

import os, requests

r = requests.post(
    "https://api.stickyprompts.com/api/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
    json={
        "name": "Support Triage",
        "tag": "support-triage",
        "icon": "headset",
        "description": "Classifies Northwind support tickets and drafts replies",
        "system_prompt": "You are the first-line support agent for Northwind Analytics. "
                         "Classify each ticket, rate urgency 1-3 and draft a reply.",
        "ai_model_id": 31,
        "tools": [{"name": "web_search", "use": False}],
        "knowledge_base_ids": [7],
    },
)
r.raise_for_status()
agent = r.json()
print(agent["ID"], agent["tag"])

const agent = await fetch("https://api.stickyprompts.com/api/v1/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STICKY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Support Triage",
    tag: "support-triage",
    icon: "headset",
    description: "Classifies Northwind support tickets and drafts replies",
    system_prompt:
      "You are the first-line support agent for Northwind Analytics. Classify each ticket, rate urgency 1-3 and draft a reply.",
    ai_model_id: 31,
    tools: [{ name: "web_search", use: false }],
    knowledge_base_ids: [7],
  }),
}).then((r) => r.json());
console.log(agent.ID, agent.tag);

Réponse. 201 Created avec l’objet Agent (sans is_shared).

Erreurs. 400 pour un corps non JSON, "Agent name is required", un tag non valide, une violation des règles de résidence des données ({"error": "...", "code": "NO_ENDPOINT_AVAILABLE"}, "NO_PROVIDER_ASSIGNED", etc.) ou une violation liée aux données sensibles dans system_prompt ({"error", "code"}). 500 "Failed to create agent".

GET /agents

Liste les agents qui vous appartiennent et ceux qui sont partagés avec vous (directement, via l’une de vos équipes ou avec tout votre espace de travail). L’outil MCP list_agents ne renvoie que vos propres agents.

Réponse. 200 avec un tableau d’objets Agent, chacun avec is_shared. Sur cette route, ai_model, mcp_servers, knowledge_bases et files ne sont pas chargés.

GET /agents/:id

Renvoie un agent qui vous appartient ou qui a été partagé avec vous, entièrement chargé : ai_model, mcp_servers, knowledge_bases, files et is_shared.

Erreurs. 404 "Agent not found", 403 "You don't have access to this agent".

PATCH /agents/:id

Met à jour un agent. Seul son propriétaire peut le modifier ; le partage ne donne aucun droit de modification. Le corps accepte les mêmes champs qu’à la création, tous facultatifs : les champs omis ou null restent inchangés. name ne peut pas être vide ; system_prompt passe par le filtre de données sensibles et ai_model_id par la vérification de résidence des données.

Réponse. 200 avec l’objet Agent entièrement chargé (sans is_shared).

Erreurs. 400, 403 "You are not authorized to update this agent", 404 "Agent not found", 500.

DELETE /agents/:id

Supprime de façon logique un agent qui vous appartient. Ses liens vers les serveurs MCP, les bases de connaissances et les fichiers sont effacés ; les fichiers et les bases de connaissances eux-mêmes ne sont pas supprimés.

Réponse. 204 No Content. Erreurs. 403 "You are not authorized to delete this agent".

Tâches de workflow

Une tâche de workflow envoie ses instructions à un modèle, sans intervention humaine. Déroulement d’une exécution :

• Une exécution est créée immédiatement avec status: "running" ; le travail se fait en arrière-plan.
• L’exécution vérifie d’abord le quota du propriétaire (en cas d’échec : error_text: "quota exceeded: <reason>"), puis crée une conversation masquée et non interactive avec le modèle de la tâche, et envoie instructions comme message.
• Tous les outils intégrés (web_search, image_generation, video_generation, speech_generation, music_generation) et tous les serveurs MCP distants configurés par le propriétaire sont activés. Le modèle ignore les outils qu’il ne prend pas en charge.
• Une exécution est soumise à un délai maximal strict de 45 minutes (error_text: "The run took too long to complete").
• En cas de succès, la réponse finale est enregistrée dans result_text. Les exécutions interrompues par un redémarrage du serveur sont marquées error avec "The run was interrupted before it could finish" et ne sont pas reprises.

Déclencheurs. Le seul type de déclencheur est cron. Il n’existe pas de déclencheur par webhook, par événement ou par appel d’API : une exécution démarre soit à partir d’un déclencheur cron, soit via POST /workflow-tasks/:id/manual-run. Il n’existe pas non plus de webhook sortant : la fin d’une exécution doit donc être détectée par interrogation périodique.

Statuts d’exécution. running (en cours), success (terminée, result_text renseigné) et error (terminée, error_text renseigné). success et error sont des états finaux. La valeur pending existe, mais le code d’exécution actuel ne l’attribue jamais.

L’objet tâche de workflow

{
  "ID": 57,
  "CreatedAt": "2026-09-28T09:20:11Z",
  "UpdatedAt": "2026-09-28T09:20:11Z",
  "DeletedAt": null,
  "user_id": 88,
  "name": "Monday pipeline digest",
  "slug": "Tq9mZr4b",
  "description": null,
  "ai_model_id": 31,
  "ai_model": { "ID": 31, "...": "..." },
  "instructions": "Summarise last week's new deals in our CRM and email the summary to the Northwind sales team.",
  "enabled": true,
  "triggers": [
    {
      "ID": 90,
      "workflow_task_id": 57,
      "type": "cron",
      "enabled": true,
      "cron_expression": "0 8 * * 1",
      "timezone": "Europe/Budapest",
      "last_triggered_at": null,
      "next_trigger_at": "2026-09-28T08:00:00+02:00"
    }
  ]
}

POST /workflow-tasks

Crée une tâche de workflow.

curl -X POST https://api.stickyprompts.com/api/v1/workflow-tasks \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monday pipeline digest",
    "ai_model_id": 31,
    "instructions": "Summarise last week'"'"'s new deals in our CRM and email the summary to the Northwind sales team.",
    "triggers": [
      { "type": "cron", "enabled": true, "cron_expression": "0 8 * * 1", "timezone": "Europe/Budapest" }
    ]
  }'

import os, requests

r = requests.post(
    "https://api.stickyprompts.com/api/v1/workflow-tasks",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
    json={
        "name": "Monday pipeline digest",
        "ai_model_id": 31,
        "instructions": "Summarise last week's new deals in our CRM and email "
                        "the summary to the Northwind sales team.",
        "triggers": [{"type": "cron", "enabled": True,
                      "cron_expression": "0 8 * * 1", "timezone": "Europe/Budapest"}],
    },
)
r.raise_for_status()
print(r.json()["triggers"][0]["next_trigger_at"])

const task = await fetch("https://api.stickyprompts.com/api/v1/workflow-tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STICKY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Monday pipeline digest",
    ai_model_id: 31,
    instructions:
      "Summarise last week's new deals in our CRM and email the summary to the Northwind sales team.",
    triggers: [{ type: "cron", enabled: true, cron_expression: "0 8 * * 1", timezone: "Europe/Budapest" }],
  }),
}).then((r) => r.json());
console.log(task.ID, task.triggers[0].next_trigger_at);

Réponse. 201 avec la tâche de workflow (sans statistiques d’exécution).

Erreurs. 400 (validation, erreurs de déclencheur, résidence des données {"error", "code"}, données sensibles {"error", "code"}), 500.

GET /workflow-tasks

Liste vos propres tâches de workflow (elles ne peuvent pas être partagées), de la plus récente à la plus ancienne. Chaque élément inclut ai_model et triggers, mais pas total_run_count ni success_rate.

Réponse. 200 avec un tableau d’objets tâche de workflow.

GET /workflow-tasks/:id

Renvoie l’une de vos tâches de workflow avec ai_model, triggers, total_run_count et success_rate.

Erreurs. 404 "Workflow task not found", 403 "You don't have access to this workflow task".

PATCH /workflow-tasks/:id

Met à jour l’une de vos tâches de workflow. Tous les champs sont facultatifs ; un champ omis reste inchangé.

curl -X PATCH https://api.stickyprompts.com/api/v1/workflow-tasks/57 \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Réponse. 200 avec la tâche de workflow (avec ai_model et triggers, sans statistiques d’exécution).

Erreurs. 400, 403 "You are not authorized to update this workflow task", 404, 500.

DELETE /workflow-tasks/:id

Déprogramme et supprime les déclencheurs, puis supprime de façon logique la tâche et ses exécutions. Réservé au propriétaire.

Réponse. 204 No Content.

POST /workflow-tasks/:id/manual-run

Lance une exécution immédiatement, que la tâche ou ses déclencheurs soient activés ou non. Réservé au propriétaire. Sans corps. Renvoie 202 Accepted avec la nouvelle exécution, qui se poursuit en arrière-plan. Il n’y a pas de rappel (callback) : interrogez GET /workflow-tasks/:id/executions jusqu’à ce que le status de l’exécution vaille success ou error.

curl -X POST https://api.stickyprompts.com/api/v1/workflow-tasks/57/manual-run \
  -H "Authorization: Bearer $STICKY_API_KEY"

# Then poll the run history until the execution is success or error
curl "https://api.stickyprompts.com/api/v1/workflow-tasks/57/executions?page=1&size=5" \
  -H "Authorization: Bearer $STICKY_API_KEY"

import os, time, requests

BASE = "https://api.stickyprompts.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"}

run = requests.post(f"{BASE}/workflow-tasks/57/manual-run", headers=H).json()
while True:
    time.sleep(10)
    executions = requests.get(f"{BASE}/workflow-tasks/57/executions",
                              headers=H, params={"page": 1, "size": 10}).json()
    ex = next((e for e in executions if e["ID"] == run["ID"]), None)
    if ex and ex["status"] in ("success", "error"):
        print(ex["status"], ex["result_text"] or ex["error_text"])
        break

const BASE = "https://api.stickyprompts.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.STICKY_API_KEY}` };

const run = await fetch(`${BASE}/workflow-tasks/57/manual-run`, { method: "POST", headers }).then((r) => r.json());
for (;;) {
  await new Promise((r) => setTimeout(r, 10_000));
  const executions = await fetch(`${BASE}/workflow-tasks/57/executions?page=1&size=10`, { headers }).then((r) => r.json());
  const ex = executions.find((e) => e.ID === run.ID);
  if (ex && (ex.status === "success" || ex.status === "error")) {
    console.log(ex.status, ex.result_text ?? ex.error_text);
    break;
  }
}

Réponse. 202 Accepted :

{
  "ID": 1203,
  "CreatedAt": "2026-09-28T09:31:00Z",
  "UpdatedAt": "2026-09-28T09:31:00Z",
  "DeletedAt": null,
  "workflow_task_id": 57,
  "trigger_type": null,
  "conversation_context_id": null,
  "status": "running",
  "started_at": "2026-09-28T09:31:00Z",
  "finished_at": null,
  "result_text": null,
  "error_text": null
}

conversation_context_id vaut null ici, car la conversation masquée n’est rattachée qu’un instant plus tard.

Erreurs. 404, 403 "You are not authorized to run this workflow task", 500 "Failed to start workflow run". Les échecs liés au quota ou au modèle ne font pas échouer l’appel HTTP ; ils apparaissent plus tard sous la forme status: "error" sur l’exécution.

GET /workflow-tasks/:id/executions

Renvoie l’historique des exécutions d’une tâche, de la plus récente à la plus ancienne. Réservé au propriétaire.

Réponse. 200 avec un tableau d’exécutions. trigger_type vaut null pour une exécution manuelle et "cron" pour une exécution planifiée. result_text est renvoyé sous forme de HTML rendu.

[
  {
    "ID": 1203,
    "workflow_task_id": 57,
    "trigger_type": null,
    "conversation_context_id": 88123,
    "status": "success",
    "started_at": "2026-09-28T09:31:00Z",
    "finished_at": "2026-09-28T09:32:14Z",
    "result_text": "<p>Last week 4 new deals were created...</p>",
    "error_text": null
  }
]

Voir aussi

• Conversations et messages - discuter avec un agent via agent_id ou un @tag.
• Intégrations - les connexions CRM, e-mail et base de données qu’un workflow peut utiliser.
• Référence des outils du serveur MCP - list_agents, get_agent, list_workflow_tasks, get_workflow_task, run_workflow_task.