--- title: Aria AgentFlow-JSON-Plan-Standard (BMW-Pattern adoptiert) type: project tags: [agentflow, plan, workflow, json-schema, tier-2-gap, b1-b2] date: 2026-05-21 status: draft related: - [[bmw-deep-dive/business-manual-genai-first-blueprint]] - [[aria-tech-stack-gaps]] - [[adopt-items-master-aggregate-2026-05-21]] linear: KAR-350 adopt: B1, B2 (BMW) --- # Aria AgentFlow-JSON-Plan-Standard > Tier-2 Gap G2-3: standardisiertes JSON-Plan-Format fuer Aria-Multi-Step-Workflows. > Adaptiert aus BMW Business-Manual Sektion 2.3.5 "How to build an AgentFlow" + Workflow-Orchestrator-Agent-Prompt. ## Plan-Schema (`plan-schema.json`) ```json { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "required": ["plan_id", "title", "process_goal", "termination_criterion", "steps"], "properties": { "plan_id": { "type": "string", "pattern": "^[a-z_]+$" }, "title": { "type": "string" }, "version": { "type": "string", "default": "1.0" }, "process_goal": { "type": "string", "minLength": 20 }, "termination_criterion": { "type": "object", "required": ["check_tool", "expected_state"], "properties": { "check_tool": { "type": "string" }, "expected_state": { "type": "string" } } }, "self_recovery": { "type": "string" }, "glossary": { "type": "object", "additionalProperties": { "type": "string" } }, "steps": { "type": "array", "minItems": 1, "items": { "type": "object", "required": ["id", "title", "context", "actions", "expected_transitions"], "properties": { "id": { "type": "string", "pattern": "^[a-z_]+$" }, "title": { "type": "string" }, "context": { "type": "string", "minLength": 30 }, "general_tools": { "type": "array", "items": { "type": "string" } }, "actions": { "type": "array", "items": { "type": "object", "required": ["name", "tool", "description"], "properties": { "name": { "type": "string" }, "tool": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "description": { "type": "string" } } } }, "expected_transitions": { "type": "array", "items": { "type": "object", "required": ["on", "to"], "properties": { "on": { "type": "string" }, "to": { "type": "string" } } } } } } } } } ``` ## Core Plan Tools (universell, von Orchestrator immer verfuegbar) | Tool | Funktion | |---|---| | `read_plan()` | Plan-Overview ohne Step-Details | | `get_step(step_id)` | Step-Details fuer aktiven Step | | `get_self_recovery()` | Recovery-Guidance bei Error/Stuck | | `wait_tool(seconds)` | Pause vor Retry, max 60s | ## Step-Scoped Domain Tools Jeder Step hat eigene `actions[].tool`-Whitelist. Orchestrator darf nur diese aufrufen wenn: 1. Step ist runnable (Dependencies erfuellt) 2. Tool ist im Step gelistet 3. Action-Description wird befolgt **Tools aus anderen Steps verwenden ist verboten.** ## Beispiel-Plan: KAR-Issue-Aufnehmen-Workflow ```json { "plan_id": "kar_issue_create", "title": "Neuen KAR-Issue aus Brain-Insight erstellen", "process_goal": "Aus einem Brain-Insight (z.B. Video-Note mit prioritaet: P0/P1) ein KAR-Issue im Linear erstellen, mit Cross-Reference zur Brain-Note und Linkage in Frontmatter.", "termination_criterion": { "check_tool": "linear_issue_exists", "expected_state": "kar_id_in_frontmatter_and_issue_in_linear" }, "self_recovery": "Bei Linear-API-Fail: wait_tool(10) + retry max 3x. Bei Brain-Frontmatter-Fail: skip ohne KAR-Erstellung, log warning.", "glossary": { "KAR": "KADiCon Aria Roadmap Linear-Team", "Brain-Note": "Markdown-File in /root/aria/brain/ mit Frontmatter" }, "steps": [ { "id": "validate_brain_note", "title": "Brain-Note + Frontmatter validieren", "context": "Sicherstellen dass das angegebene File existiert, Frontmatter parsebar ist, und prioritaet/klassifikation gesetzt sind.", "general_tools": ["read_file"], "actions": [ { "name": "Read note", "tool": "read_file", "description": "Lade den Inhalt der Brain-Note." }, { "name": "Parse frontmatter", "tool": "parse_frontmatter", "description": "Extrahiere title, source, prioritaet, klassifikation." } ], "expected_transitions": [ {"on": "valid", "to": "create_linear_issue"}, {"on": "invalid", "to": "plan_termination_failure"} ] }, { "id": "create_linear_issue", "title": "Linear-Issue erstellen", "context": "Aus dem Frontmatter ein KAR-Issue erstellen, im Backlog-State, mit dem Body als Cross-Reference zur Brain-Note.", "general_tools": ["linear_create_issue"], "actions": [ { "name": "Create", "tool": "linear_create_issue", "description": "POST mutation issueCreate mit teamId=KAR, stateId=backlog, priority gemaess prioritaet-Mapping." } ], "expected_transitions": [ {"on": "success", "to": "update_brain_frontmatter"}, {"on": "linear_api_fail", "to": "create_linear_issue"} ] }, { "id": "update_brain_frontmatter", "title": "Brain-Frontmatter um linear: KAR-N erweitern", "context": "Im Brain-File die Zeile 'linear: KAR-N' in Frontmatter eintragen, damit zukuenftige Runs den Issue nicht erneut erstellen.", "general_tools": ["write_file"], "actions": [ { "name": "Patch frontmatter", "tool": "write_file", "description": "Frontmatter-Block mit neuem 'linear: KAR-N' speichern." } ], "expected_transitions": [ {"on": "success", "to": "plan_termination"} ] } ] } ``` ## Workflow-Orchestrator-System-Prompt (Template) Liegt unter `/root/aria/scripts/agentflow/orchestrator-prompt.md`. ## Aria-Integration Aria-Skripte die Multi-Step machen koennen den Plan-Standard nutzen statt eigene if/else-Logik: - `aria-akp-ingest.py` → `plan_id: youtube_ingest_full` - `aria-akp-triage.py` → `plan_id: video_triage_haiku` - `aria-akp-deep.py` → `plan_id: video_deep_opus` - `aria-akp-to-linear.py` → `plan_id: kar_issue_create` (Beispiel oben) Vorteil: Plans sind versionierbar, auditierbar, testbar mit Mock-Tools. ## Naechste Schritte 1. ✅ Schema definiert (oben) 2. ✅ `aria-agentflow-execute.py` (kombiniert validate + execute, ~200 LOC) 3. ✅ Smoke-Test mit test-plan.json: 2 Steps, 2 Actions, alle ok (Audit-Log: 6 Events) 4. ⏳ Bestehende Skripte schrittweise auf Plan-Format migrieren (aria-akp-to-linear.py erster Kandidat) ### Smoke-Test-Ergebnis ```bash $ python3 aria-agentflow-execute.py validate /tmp/test-plan.json OK: test_echo_workflow is valid (2 steps) $ python3 aria-agentflow-execute.py run /tmp/test-plan.json Plan: test_echo_workflow - Test Echo Workflow Steps: 2 [step] step_one: Lese Plan-Overview action: Read plan overview (tool: core.read_plan) [step] step_two: Wait demo action: Wait 1 second (tool: core.wait_tool) DONE. Audit log entries: 6 ``` ### Action-Args-Format Actions koennen optional `args` (dict) haben: ```json { "name": "Wait 1 second", "tool": "core.wait_tool", "args": {"seconds": 1}, "description": "kurze Pause" } ``` Args werden als `**kwargs` an Tool-Funktion uebergeben. Ohne `args`: tool wird ohne Argumente aufgerufen. ## Verwandt - [[bmw-deep-dive/business-manual-genai-first-blueprint]] (Source-Pattern) - [[bmw-deep-dive/business-manual-sbm-processes]] (SBM-Inventory-Plan als BMW-Beispiel) - [[aria-tech-stack-gaps]] - [[adopt-items-master-aggregate-2026-05-21]]