API de Agentic Plans

La API de Agentic Plans es la capa HTTP read-only sobre la pipeline de Agentic Superpowers (Brainstorm → Plan → Execute). Los planes los crean y mutan exclusivamente las pipeline tools del Master Agent (build_plan, complete_step, fail_step, skip_step, complete_plan, clarify_intent) — la API HTTP solo permite inspección. Documentación completa del módulo: Agentic Chat.

Todos los endpoints autenticados con Sanctum, scope al team, policy: solo view.

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

Valores de plan status: planning | executing | completed | failed | aborted. Valores de strategy: linear (default) — steps estrictamente secuenciales.

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

Valores de step status: pending | in_progress | completed | failed | skipped. Valores de assigned_agent: null (Master mismo) | master | analyze | explore | research | action. Límite de output_data: ≤ 64 kB JSON. Outputs mayores se truncan y se exponen como output_summary.

Patrón de polling

El Master Agent dirige la ejecución internamente. Los frontends hacen polling sobre el plan para mantener el stream de UI sincronizado.

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

# Recoger el output de todos los steps
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/agentic/plans/$PLAN/steps" \
  | jq '.data[] | {step_index, label, status, output_summary}'

Retry / Abort

No hay endpoints HTTP de retry o abort. Las mutaciones suceden exclusivamente vía las pipeline tools internas del Master Agent:

• Retry de un step — el Master Agent invoca fail_step, el pipeline manager redispatcha el step. Por HTTP solo es observable vía retry_count y last_error.
• Abort de un plan — el usuario manda en el chat una intent de abort («stop», «abbrechen») → el Master Agent invoca abort_plan → status: aborted.
• Skip de un step — el Master Agent invoca skip_step con motivo — el step queda en el log con status: skipped.

Los clientes externos que necesiten un comportamiento de abort envían la intent como mensaje de usuario por la chat send API; el Master Agent lo traduce a abort_plan.

Códigos de status

Pitfalls

• Sin endpoints de mutación. PATCH/DELETE sobre /v1/agentic/plans/* no está implementado a propósito — quien escribe es el Master Agent.
• output_data puede estar truncado. En outputs JSON grandes (> 64 kB) el campo está recortado; los outputs completos solo se ven en el log de tool calls de la sesión.
• subagent_session_id solo se rellena en steps de subagent. Los steps que ejecuta el Master tienen null — quien quiera leer el trace del subagent sigue el session ID en /v1/agentic/sessions/{id}.
• Frecuencia de polling. 2 s vale para UIs en vivo; con muchos planes en paralelo, mejor server-sent events o la chat stream API.

Relacionado: Agentic Chat · API de Chat Shares · API de Créditos.