Agenten und Workflows

Ein Agent ist ein gespeicherter Assistent: ein Systemprompt, ein Modell, die integrierten Tools, die er verwenden darf, Remote-MCP-Server, Wissensdatenbanken und Dateien. Eine Workflow-Aufgabe ist eine unbeaufsichtigte KI-Ausführung: feste Anweisungen, die nach einem Cron-Zeitplan oder auf Abruf an ein Modell gehen, wobei jede Ausführung protokolliert wird. Das ist die API-Seite von Agenten und Workflows in der App.

Alle Pfade sind relativ zu https://api.stickyprompts.com/api/v1. Jeder Request läuft im Namen des Benutzers, dem der API-Schlüssel gehört.

Konventionen

• :id akzeptiert entweder die numerische ID oder den slug. Ein rein numerischer Wert wird immer als ID behandelt.
• Objekte serialisieren ihre Basisfelder großgeschrieben (ID, CreatedAt, UpdatedAt, DeletedAt, bei aktiven Zeilen immer null); alle anderen Felder sind snake_case.
• Seitenbasierte Listen akzeptieren page (Standard 1) und size (Standard 10), geben ein reines JSON-Array zurück und liefern die Gesamtzahlen in den Response-Headern X-Total-Count, X-Page und X-Page-Size.
• Fehler haben die Form {"error": "<message>"}. Ablehnungen durch Guardrails und Datenresidenz enthalten zusätzlich einen maschinenlesbaren Code: {"error": "...", "code": "..."}.

Agenten

Die API verwaltet die Konfiguration eines Agenten. Um mit einem Agenten zu chatten, übergeben Sie beim Start einer Unterhaltung seine agent_id, oder Sie erwähnen seinen tag per @mention, siehe Unterhaltungen und Nachrichten.

Das Agent-Objekt

{
  "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

Legt einen Agenten an.

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);

Antwort. 201 Created mit dem Agent-Objekt (ohne is_shared).

Fehler. 400 bei einem Body, der kein JSON ist, bei "Agent name is required", einem ungültigen Tag, einem Verstoß gegen die Datenresidenz ({"error": "...", "code": "NO_ENDPOINT_AVAILABLE"}, "NO_PROVIDER_ASSIGNED" und Ähnliches) oder einem Verstoß gegen die Regeln für sensible Daten in system_prompt ({"error", "code"}). 500 "Failed to create agent".

GET /agents

Listet Agenten auf, die Ihnen gehören, und Agenten, die mit Ihnen geteilt sind (direkt, über eines Ihrer Teams oder mit Ihrem gesamten Workspace). Das MCP-Tool list_agents gibt nur Ihre eigenen Agenten zurück.

Antwort. 200 mit einem Array aus Agent-Objekten, jedes mit is_shared. Bei dieser Route werden ai_model, mcp_servers, knowledge_bases und files nicht geladen.

GET /agents/:id

Gibt einen Agenten zurück, der Ihnen gehört oder mit Ihnen geteilt wurde, vollständig geladen: ai_model, mcp_servers, knowledge_bases, files und is_shared.

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

PATCH /agents/:id

Aktualisiert einen Agenten. Nur der Inhaber kann ihn aktualisieren; eine Freigabe gewährt keine Bearbeitungsrechte. Der Body akzeptiert dieselben Felder wie beim Anlegen, alle optional: Weggelassene Felder und Felder mit null bleiben unverändert. name darf nicht leer sein; system_prompt durchläuft den Schutz für sensible Daten, ai_model_id die Prüfung der Datenresidenz.

Antwort. 200 mit dem vollständig geladenen Agent-Objekt (ohne is_shared).

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

DELETE /agents/:id

Löscht einen Agenten, der Ihnen gehört, per Soft Delete. Seine Verknüpfungen mit MCP-Servern, Wissensdatenbanken und Dateien werden aufgehoben; die Dateien und Wissensdatenbanken selbst bleiben erhalten.

Antwort. 204 No Content. Fehler. 403 "You are not authorized to delete this agent".

Workflow-Aufgaben

Eine Workflow-Aufgabe sendet ihre instructions unbeaufsichtigt an ein Modell. So läuft eine Ausführung ab:

• Sofort wird eine Ausführung mit status: "running" angelegt; die eigentliche Arbeit geschieht im Hintergrund.
• Die Ausführung prüft zuerst das Kontingent des Inhabers (und scheitert gegebenenfalls mit error_text: "quota exceeded: <reason>"). Dann legt sie eine verborgene, nicht interaktive Unterhaltung mit dem Modell der Aufgabe an und sendet instructions als Nachricht.
• Alle integrierten Tools (web_search, image_generation, video_generation, speech_generation, music_generation) und alle Remote-MCP-Server, die der Inhaber konfiguriert hat, sind aktiviert. Tools, die das Modell nicht unterstützt, ignoriert es.
• Eine Ausführung hat ein festes Timeout von 45 Minuten (error_text: "The run took too long to complete").
• Bei Erfolg wird die endgültige Antwort in result_text gespeichert. Ausführungen, die durch einen Serverneustart unterbrochen werden, erhalten den Status error mit "The run was interrupted before it could finish" und werden nicht fortgesetzt.

Trigger. Der einzige Trigger-Typ ist cron. Es gibt keine Trigger für Webhooks, Events oder API-Aufrufe: Eine Ausführung startet entweder über einen cron-Trigger oder über POST /workflow-tasks/:id/manual-run. Ausgehende Webhooks gibt es ebenfalls nicht, den Abschluss müssen Sie also per Polling abfragen.

Status von Ausführungen. running (läuft), success (beendet, result_text gesetzt) und error (beendet, error_text gesetzt). success und error sind Endzustände. pending existiert als Wert, wird vom aktuellen Ausführungscode aber nicht gesetzt.

Das Objekt einer Workflow-Aufgabe

{
  "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

Legt eine Workflow-Aufgabe an.

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);

Antwort. 201 mit der Workflow-Aufgabe (ohne Ausführungsstatistik).

Fehler. 400 (Validierung, Trigger-Fehler, Datenresidenz {"error", "code"}, sensible Daten {"error", "code"}), 500.

GET /workflow-tasks

Listet Ihre eigenen Workflow-Aufgaben auf (sie lassen sich nicht teilen), die neuesten zuerst. Jedes Element enthält ai_model und triggers, aber weder total_run_count noch success_rate.

Antwort. 200 mit einem Array aus Workflow-Aufgaben.

GET /workflow-tasks/:id

Gibt eine Ihrer Workflow-Aufgaben mit ai_model, triggers, total_run_count und success_rate zurück.

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

PATCH /workflow-tasks/:id

Aktualisiert eine Ihrer Workflow-Aufgaben. Alle Felder sind optional; weggelassene Felder bleiben unverändert.

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 }'

Antwort. 200 mit der Workflow-Aufgabe (mit ai_model und triggers, ohne Ausführungsstatistik).

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

DELETE /workflow-tasks/:id

Nimmt die Trigger aus dem Zeitplan und löscht sie; die Aufgabe und ihre Ausführungen werden per Soft Delete gelöscht. Nur für den Inhaber.

Antwort. 204 No Content.

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

Startet sofort eine Ausführung, unabhängig davon, ob die Aufgabe oder ihre Trigger aktiviert sind. Nur für den Inhaber. Kein Body. Gibt 202 Accepted mit der neuen Ausführung zurück, während diese im Hintergrund weiterläuft. Es gibt keinen Callback: Fragen Sie GET /workflow-tasks/:id/executions ab, bis der status der Ausführung success oder error ist.

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;
  }
}

Antwort. 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 ist hier null, weil die verborgene Unterhaltung erst einen Moment später verknüpft wird.

Fehler. 404, 403 "You are not authorized to run this workflow task", 500 "Failed to start workflow run". Fehler bei Kontingent oder Modell lassen den HTTP-Aufruf nicht scheitern; sie zeigen sich erst später als status: "error" an der Ausführung.

GET /workflow-tasks/:id/executions

Gibt den Ausführungsverlauf einer Aufgabe zurück, die neuesten zuerst. Nur für den Inhaber.

Antwort. 200 mit einem Array aus Ausführungen. trigger_type ist bei einer manuellen Ausführung null und bei einer geplanten "cron". result_text wird als gerendertes HTML zurückgegeben.

[
  {
    "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
  }
]

Verwandte Seiten

• Unterhaltungen und Nachrichten - mit einem Agenten über agent_id oder ein @tag chatten.
• Integrationen - die CRM-, E-Mail- und Datenbankverbindungen, die ein Workflow nutzen kann.
• Tool-Referenz - list_agents, get_agent, list_workflow_tasks, get_workflow_task, run_workflow_task.