API Agentic Plans

L'API Agentic Plans est la couche HTTP read-only au-dessus du pipeline Agentic Superpowers (Brainstorm → Plan → Execute). Les plans sont exclusivement créés et mutés par le Master-Agent via ses outils pipeline (build_plan, complete_step, fail_step, skip_step, complete_plan, clarify_intent) — l'API HTTP ne permet que l'inspection. Doc module complète : Agentic Chat.

Tous les endpoints sont authentifiés Sanctum, team-scoped, policy : view only.

Endpoints

Réponse Plan

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

Valeurs de status du plan : planning | executing | completed | failed | aborted. Valeurs de strategy : linear (défaut) — steps strictement séquentiels.

Réponse Steps

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

Valeurs de status d'un step : pending | in_progress | completed | failed | skipped. Valeurs de assigned_agent : null (Master lui-même) | master | analyze | explore | research | action. Limite output_data : ≤ 64 kB JSON. Les outputs plus larges sont tronqués et reportés dans output_summary.

Pattern de polling

Le Master-Agent pilote l'exécution en interne. Les frontends pollent le plan pour garder le stream UI synchronisé.

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

# Récupérer l'output de tous les steps
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/agentic/plans/$PLAN/steps" \
  | jq '.data[] | {step_index, label, status, output_summary}'

Retry / Abort

Il n'y a pas d'endpoints HTTP pour retry ou abort. Les mutations passent exclusivement par les outils pipeline internes du Master-Agent :

• Retry d'un step — le Master-Agent appelle fail_step, le pipeline manager redispatche le step. Côté HTTP, observable seulement via retry_count et last_error.
• Abort d'un plan — l'utilisateur envoie une intent d'abandon dans le chat (« stop », « abbrechen ») → le Master-Agent appelle abort_plan → status: aborted.
• Skip d'un step — le Master-Agent appelle skip_step avec une raison — le step reste dans le log avec status: skipped.

Les clients externes qui ont besoin d'un comportement d'abort envoient l'intent comme message utilisateur via l'API chat-send ; le Master-Agent traduit cela en abort_plan.

Codes de statut

Pièges

• Pas d'endpoints de mutation. PATCH/DELETE sur /v1/agentic/plans/* n'est volontairement pas implémenté — celui qui écrit, c'est le Master-Agent.
• output_data est tronqué. Pour les gros outputs JSON (> 64 kB), le champ est tronqué ; les outputs complets ne sont disponibles que via le tool-call log de la session.
• subagent_session_id n'est défini que pour les steps subagent. Les steps propres au Master ont null — qui veut lire le trace subagent suit le session-ID dans /v1/agentic/sessions/{id}.
• Fréquence de polling. 2 s est OK pour des UIs live ; en cas de plans parallèles nombreux, préfère du Server-Sent-Events ou l'API chat-stream.

Voir aussi : Agentic Chat · API Chat Shares · API Crédits.