Agentic-Plans-API

Die Agentic-Plans-API ist die Read-only-HTTP-Schicht ueber die Agentic-Superpowers-Pipeline (Brainstorm → Plan → Execute). Plaene werden ausschliesslich vom Master-Agent ueber seine Pipeline-Tools (build_plan, complete_step, fail_step, skip_step, complete_plan, clarify_intent) erstellt und mutiert — die HTTP-API erlaubt nur Inspektion. Volle Modul-Doku: Agentic Chat.

Alle Endpoints Sanctum-authentifiziert, team-scoped, Policy: view only.

Endpoints

Plan Response

{
  "data": {
    "id": 12,
    "session_id": 42,
    "goal": "Konkurrenz-Analyse example.com",
    "brainstorm_summary": null,
    "strategy": "linear",
    "status": "executing",
    "current_step_id": 35,
    "total_steps": 4,
    "completed_steps": 1,
    "failed_steps": 0,
    "started_at": "2026-05-01T08:30:00Z",
    "completed_at": null,
    "total_tool_calls": 9,
    "total_credits_used": 5,
    "created_at": "2026-05-01T08:29:55Z"
  }
}

Plan-Status-Werte: planning | executing | completed | failed | aborted. Strategie-Werte: linear (Default) — Steps strikt sequenziell.

Steps Response

{
  "data": [
    {
      "id": 35,
      "step_index": 0,
      "label": "Top-10 SERP-Konkurrenten ermitteln",
      "description": "...",
      "complexity": "trivial",
      "assigned_agent": null,
      "status": "completed",
      "retry_count": 0,
      "last_error": null,
      "output_summary": "10 Konkurrenten: ahrefs.com, semrush.com, ...",
      "output_data": { "competitors": ["ahrefs.com", "..."] },
      "tool_calls_made": 1,
      "credits_used": 1,
      "latency_ms": 3120,
      "subagent_session_id": null,
      "started_at": "2026-05-01T08:30:01Z",
      "completed_at": "2026-05-01T08:30:04Z"
    }
  ]
}

Step-Status-Werte: pending | in_progress | completed | failed | skipped. assigned_agent-Werte: null (Master selbst) | master | analyze | explore | research | action. output_data-Limit: ≤ 64 kB JSON. Groessere Outputs werden truncated und als output_summary ausgewiesen.

Polling-Pattern

Der Master-Agent treibt die Execution intern. Frontends pollen den Plan, um den UI-Stream synchron zu halten.

TOKEN="$RANKION_API_TOKEN"
BASE="https://rankion.ai/api/v1"
PLAN=12

while true; do
  R=$(curl -s -H "Authorization: Bearer $TOKEN" "$BASE/agentic/plans/$PLAN")
  STATUS=$(echo "$R" | jq -r '.data.status')
  DONE=$(echo "$R"   | jq -r '.data.completed_steps')
  TOTAL=$(echo "$R"  | jq -r '.data.total_steps')
  echo "[$STATUS] $DONE / $TOTAL Steps"
  case "$STATUS" in
    completed|failed|aborted) break ;;
  esac
  sleep 2
done

# Output aller Steps abholen
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/agentic/plans/$PLAN/steps" \
  | jq '.data[] | {step_index, label, status, output_summary}'

Retry / Abort

Es gibt keine HTTP-Endpoints zum Retry oder Abort. Mutationen passieren ausschliesslich ueber die internen Pipeline-Tools des Master-Agents:

• Retry eines Steps — Der Master-Agent ruft fail_step auf, der Pipeline-Manager dispatcht den Step erneut. Per HTTP nur observierbar via retry_count und last_error.
• Abort eines Plans — User sendet im Chat eine Abbrechen-Intent ("stop", "abbrechen") → Master-Agent ruft abort_plan → status: aborted.
• Skip eines Steps — Master-Agent ruft skip_step mit Grund — Step bleibt im Log mit status: skipped erhalten.

Externe Clients, die ein Abort-Verhalten brauchen, schicken die Intent als User-Message ueber die Chat-Send-API; der Master-Agent uebersetzt das in abort_plan.

Status-Codes

Pitfalls

• Keine Mutation-Endpoints. PATCH/DELETE auf /v1/agentic/plans/* ist absichtlich nicht implementiert — wer schreibt, ist der Master-Agent.
• output_data ist truncated. Bei grossen JSON-Outputs (> 64 kB) ist das Feld gekuerzt; vollstaendige Outputs nur ueber das Tool-Call-Log der Session.
• subagent_session_id ist nur fuer Subagent-Steps gesetzt. Master-eigene Steps haben null — wer den Subagent-Trace lesen will, folgt der Session-ID in /v1/agentic/sessions/{id}.
• Polling-Frequenz. 2 s ist OK fuer Live-UIs; bei vielen parallelen Plaenen lieber Server-Sent-Events oder die Chat-Stream-API nutzen.

Verwandt: Agentic Chat · Chat-Shares-API · Credits-API.