Ügynökök és munkafolyamatok

Az ügynök egy mentett asszisztens: rendszerprompt, modell, a használható beépített eszközök, távoli MCP-szerverek, tudásbázisok és fájlok. A munkafolyamat-feladat (workflow task) felügyelet nélküli AI-futtatás: rögzített utasítások, amelyeket a rendszer cron-ütemezés szerint vagy igény szerint elküld egy modellnek, és minden futtatást végrehajtásként (execution) rögzít. Ezek az Ügynökök és a Munkafolyamatok oldalon bemutatott alkalmazásfunkciók API-oldali megfelelői.

Minden útvonal a https://api.stickyprompts.com/api/v1 alapcímhez képest értendő. Minden kérés annak a felhasználónak a nevében fut, akié az API-kulcs.

Konvenciók

• A :id a numerikus ID és a slug értéket is elfogadja. A csak számjegyekből álló értéket a rendszer mindig azonosítóként (ID) kezeli.
• Az objektumok alapmezői nagybetűvel kezdődnek (ID, CreatedAt, UpdatedAt, DeletedAt, ez utóbbi élő rekordoknál mindig null); minden más mező snake_case.
• Az oldalakra bontott listák a page (alapértelmezés: 1) és a size (alapértelmezés: 10) paramétert fogadják, csupasz JSON-tömböt adnak vissza, az összesítéseket pedig az X-Total-Count, X-Page és X-Page-Size válaszheaderekben küldik.
• A hibák formája {"error": "<message>"}. A védőkorlát- és adatrezidencia-elutasítások egy gépi kódot is hozzáadnak: {"error": "...", "code": "..."}.

Ügynökök

Az API az ügynökök konfigurációját kezeli. Ha egy ügynökkel szeretnél beszélgetni, add meg az agent_id értékét a beszélgetés indításakor, vagy említsd meg a tag értékét @mention formában. Erről a Beszélgetések és üzenetek oldalon olvashatsz.

Az Agent objektum

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

Létrehoz egy ügynököt.

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

Válasz. 201 Created az Agent objektummal (is_shared nélkül).

Hibák. 400 nem JSON formátumú törzs, "Agent name is required", érvénytelen tag, adatrezidencia-sértés ({"error": "...", "code": "NO_ENDPOINT_AVAILABLE"}, "NO_PROVIDER_ASSIGNED" és hasonlók), illetve a system_prompt mezőben talált érzékeny adat ({"error", "code"}) esetén. 500 "Failed to create agent".

GET /agents

Listázza a saját ügynökeidet és a veled megosztottakat (akár közvetlenül, akár valamelyik csapatodon keresztül, akár a teljes munkaterülettel osztották meg őket). A list_agents MCP-eszköz csak a saját ügynökeidet adja vissza.

Válasz. 200 Agent objektumok tömbjével, mindegyikben is_shared mezővel. Ezen a végponton az ai_model, mcp_servers, knowledge_bases és files mező nincs betöltve.

GET /agents/:id

Visszaad egy saját vagy veled megosztott ügynököt, teljesen betöltve: ai_model, mcp_servers, knowledge_bases, files és is_shared.

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

PATCH /agents/:id

Frissít egy ügynököt. Csak a tulajdonos frissítheti; a megosztás nem ad szerkesztési jogot. A törzs ugyanazokat a mezőket fogadja, mint a létrehozás, de mindegyik opcionális: a kihagyott vagy null értékű mezők nem változnak. A name nem lehet üres; a system_prompt átmegy az érzékenyadat-szűrőn, az ai_model_id pedig az adatrezidencia-ellenőrzésen.

Válasz. 200 a teljesen betöltött Agent objektummal (is_shared nélkül).

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

DELETE /agents/:id

Logikailag törli (soft delete) a saját ügynöködet. Az ügynök MCP-szerverekhez, tudásbázisokhoz és fájlokhoz fűződő kapcsolatai megszűnnek, magukat a fájlokat és tudásbázisokat azonban a rendszer nem törli.

Válasz. 204 No Content. Hibák. 403 "You are not authorized to delete this agent".

Munkafolyamat-feladatok

A munkafolyamat-feladat felügyelet nélkül elküldi az instructions mezőben megadott utasításokat egy modellnek. Egy futtatás így zajlik:

• A rendszer azonnal létrehoz egy végrehajtást status: "running" állapottal; maga a munka a háttérben zajlik.
• A futtatás először ellenőrzi a tulajdonos kvótáját (ha ez nem sikerül: error_text: "quota exceeded: <reason>"), majd létrehoz egy rejtett, nem interaktív beszélgetést a feladat modelljével, és üzenetként elküldi az instructions tartalmát.
• Minden beépített eszköz (web_search, image_generation, video_generation, speech_generation, music_generation) és a tulajdonos által beállított összes távoli MCP-szerver engedélyezve van. A modell figyelmen kívül hagyja azokat az eszközöket, amelyeket nem támogat.
• Egy futtatásnak szigorú, 45 perces időkorlátja van (error_text: "The run took too long to complete").
• Sikeres futtatás után a végső válasz a result_text mezőbe kerül. A szerver újraindítása miatt megszakadt végrehajtások error állapotot kapnak a "The run was interrupted before it could finish" üzenettel, és nem folytatódnak.

Triggerek. Az egyetlen triggertípus a cron. Webhook-, esemény- vagy API-hívás-alapú trigger nincs: egy futtatás vagy egy cron triggerből, vagy a POST /workflow-tasks/:id/manual-run hívásból indul. Kimenő webhookok sincsenek, ezért a befejezést ismételt lekérdezéssel kell figyelni.

A végrehajtás állapotai. running (folyamatban), success (befejeződött, a result_text ki van töltve) és error (befejeződött, az error_text ki van töltve). A success és az error végállapot. A pending létezik értékként, de a jelenlegi futtatási kód nem állítja be.

A Workflow task objektum

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

Létrehoz egy munkafolyamat-feladatot.

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

Válasz. 201 a munkafolyamat-feladattal (futtatási statisztikák nélkül).

Hibák. 400 (validációs hiba, triggerhiba, adatrezidencia: {"error", "code"}, érzékeny adat: {"error", "code"}), 500.

GET /workflow-tasks

Listázza a saját munkafolyamat-feladataidat (ezek nem oszthatók meg), a legújabbal kezdve. Minden elem tartalmazza az ai_model és a triggers mezőt, a total_run_count és a success_rate mezőt viszont nem.

Válasz. 200 munkafolyamat-feladat objektumok tömbjével.

GET /workflow-tasks/:id

Visszaadja az egyik munkafolyamat-feladatodat az ai_model, a triggers, a total_run_count és a success_rate mezővel együtt.

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

PATCH /workflow-tasks/:id

Frissíti az egyik munkafolyamat-feladatodat. Minden mező opcionális; a kihagyott mezők nem változnak.

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

Válasz. 200 a munkafolyamat-feladattal (ai_model és triggers mezővel, futtatási statisztikák nélkül).

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

DELETE /workflow-tasks/:id

Kiveszi az ütemezésből és törli a triggereket, a feladatot és a végrehajtásait pedig logikailag törli (soft delete). Csak a tulajdonos hívhatja.

Válasz. 204 No Content.

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

Azonnal elindít egy futtatást, függetlenül attól, hogy a feladat vagy a triggerei engedélyezve vannak-e. Csak a tulajdonos hívhatja. Kéréstörzs nem kell. A végpont 202 Accepted választ ad az új végrehajtással, a futtatás pedig a háttérben folytatódik. Visszahívás (callback) nincs: kérdezd le ismételten a GET /workflow-tasks/:id/executions végpontot, amíg a végrehajtás status értéke success vagy error nem lesz.

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

Válasz. 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
}

A conversation_context_id itt azért null, mert a rejtett beszélgetés csak egy pillanattal később kapcsolódik a végrehajtáshoz.

Hibák. 404, 403 "You are not authorized to run this workflow task", 500 "Failed to start workflow run". A kvóta- és modellhibák miatt maga a HTTP-hívás nem lesz sikertelen; ezek később, a végrehajtás status: "error" állapotaként jelennek meg.

GET /workflow-tasks/:id/executions

Visszaadja egy feladat futtatási előzményeit, a legújabbal kezdve. Csak a tulajdonos hívhatja.

Válasz. 200 a végrehajtások tömbjével. A trigger_type kézi futtatásnál null, ütemezettnél "cron". A result_text renderelt HTML-ként érkezik.

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

Kapcsolódó oldalak

• Beszélgetések és üzenetek - beszélgetés egy ügynökkel az agent_id vagy egy @tag segítségével.
• Integrációk - a CRM-, e-mail- és adatbázis-kapcsolatok, amelyeket egy munkafolyamat használhat.
• Eszközreferencia - list_agents, get_agent, list_workflow_tasks, get_workflow_task, run_workflow_task.