Compile a flow into a Storyline

A Storyline is a directed graph hung on an agent: it turns "answer one question" into "carry a whole task end to end" (intake, tutoring, coaching…). Nodes are steps (each with its own task / skills / kb / tools + writable profile dimensions); exits carry conditions (ai / user_choice / rule / callback / goto_storyline). The runtime never edits the agent's soul or safety boundary — it is constant from the first node to the last, which is exactly what a regulated or child-facing product needs.

Create a draft

create_storyline(
  agent_name="Support", key="loan-intake", name="Loan intake",
  profile_schema={"docs_ready": {"type": "bool"}},          # dims that accumulate across nodes
  graph={"nodes": [
    {"node_key": "n1", "title": "Understand need", "flags": {"is_entry": True},
     "on_enter_opening": "Hi — which kind of loan are you applying for?",
     "exits": [{"kind": "ai", "label": "need clear", "to_node_key": "n2",
                "ai_criteria": "the user stated the loan type and rough amount"}]},
    {"node_key": "n2", "title": "Collect documents",
     "task": "Collect the checklist items; chase missing ones across turns.",
     "exits": [{"kind": "user_choice", "label": "documents ready", "to_node_key": "n3",
                "user_choice": {"button_text": "I've uploaded everything"},
                "writes": [{"ref": "dim", "key": "docs_ready", "op": "set", "value": True}]}]},
    {"node_key": "n3", "title": "Hand off", "task": "Summarise the case and hand off to a human.",
     "flags": {"is_terminal": True}, "exits": []}
  ]},
  allow_agent_enroll=True,
  enroll_trigger="the visitor says they want to apply for a loan",
)

★ Validate, then publish ★

validate_storyline(storyline_id="…")   # → {"ok": true} is required to publish
publish_storyline(storyline_id="…")    # freezes an immutable version and goes live

Enrollment — who enters, and when (all require publishing)

• is_default=True — one per agent; auto-enrolls on the first conversation.
• allow_agent_enroll=True + enroll_trigger — the agent enrolls the user when it judges the trigger.
• Manual assignment in the console.

Exits are priority-ordered (list order): deterministic rule / user_choice / callback are judged first, ai last. Build if/else, retry loops and AND-joins out of deterministic exits — don't gamble on the LLM. Edit a draft with update_storyline (PUT semantics; keep every node_key stable, since exits and the funnel reference it).

Report back. Return the published Storyline's console link — https://console.agent4.io/#/storylines/<id> (the id from create_storyline) — with a one-line summary of the flow and how a user enters it.