Storylines · for AI agents

플로우를 스토리라인으로 컴파일하기

다단계 프로세스를 상태 유지형 방향성 그래프로 변환합니다 — 생성, 검증, 게시합니다.

MCP tools:create_storylinevalidate_storylinepublish_storylinelist_storylinesupdate_storyline

**스토리라인(Storyline)**은 에이전트에 연결된 방향성 그래프입니다. 이는 "질문 하나에 답하기"를 "전체 작업을 끝까지 수행하기"(수집, 튜터링, 코칭 등)로 전환합니다. 노드는 단계이며, 각 단계에는 고유한 작업/스킬/지식베이스(KB)/도구 및 기록 가능한 프로필 차원이 포함됩니다. 나가는 경로(exits)에는 조건(ai / user_choice / rule / callback / goto_storyline)이 있습니다. 런타임은 에이전트의 핵심(soul)이나 안전 경계를 절대 수정하지 않습니다 — 첫 번째 노드부터 마지막 노드까지 일정하며, 이는 규제 대상 제품이나 아동 대상 제품에 정확히 필요한 사항입니다.

초안 만들기

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_storyline(storyline_id="…")   # → {"ok": true} is required to publish
publish_storyline(storyline_id="…")    # freezes an immutable version and goes live

등록 — 누가, 언제 진입하는가 (모두 게시 필요)

is_default=True — 에이전트당 하나; 첫 번째 대화 시 자동 등록됨.
allow_agent_enroll=True + enroll_trigger — 에이전트가 트리거를 판단할 때 사용자를 등록함.
entry="user" (또는 "both") — 해당 흐름은 채팅 위젯의 가이드드 플로우 메뉴와 새 채팅 드롭다운에 나열되므로, 사용자가 의도적으로 시작합니다(버튼 클릭, 모델 판단 아님). display_name과 한 줄 description을 제공하십시오 — 메뉴에 표시되는 내용입니다. concurrency="session"과 결합하여 "대화당 하나의 사례" 흐름을 구성하십시오: 각 선택은 새로운 사례를 엽니다.
콘솔에서 수동 할당.

사용자가 보는 것 — 가시성, 배너 및 읽기 전용 맵

user_visibility는 실행 중인 흐름의 최종 사용자 프레젠테이션을 제어합니다(기본값 invisible):

invisible — UI 없음; 흐름이 조용히 진행됨(이전 동작).
named — 채팅 위에 얇은 배너에 흐름의 이름이 표시됨. 그 이상 없음.
trail — 배너 + View 버튼이 읽기 전용 맵을 엽니다: 이미 완료된 단계는 제목을 표시하며, 미완료 분기와 미래 단계는 익명의 회색 블록으로 표시됩니다(서버 측에서 가려짐 — 사용자는 흐름의 길이는 알 수 있지만 내용은 알 수 없음).
full — 단계 x / y가 있는 배너 + 전체 맵: 모든 단계가 명명되고 완료됨/현재/미완료에 따라 색상 코딩됨.

추가 기능: allow_exit=True는 배너에 종료 버튼을 추가합니다(종료된 흐름은 해당 대화에서 자동 재등록되지 않음; 사용자가 선택한 흐름은 메뉴에서 다시 진입할 수 있으며 진행 상황은 유지됨). show_profile=True는 맵 아래에 프로필 차원의 현재 값을 나열합니다(스키마에 min/max가 선언된 경우 숫자는 진행률 막대로 표시됨). 각 노드별로 rewind: "reset" | "keep"을 사용하면 사용자가 전체 맵에서 완료된 단계를 클릭하여 해당 단계로 돌아갈 수 있습니다 — reset은 진입 시 캡처된 프로필 스냅복원을 복원하고, keep은 수집된 데이터를 유지합니다(학습/검토 흐름용). 실제 세계의 부작용(기록 제출, 문서 제출 등)은 절대 롤백되지 않으므로, 부작용이 없는 단계에만 표시하십시오. IM 채널(Telegram/WhatsApp)에서 /storyline 명령어는 현재 흐름을 보고하며, trail/full의 경우 해당 읽기 전용 맵으로의 유효 기간이 짧은 서명 링크를 반환합니다.

레거시 learner_visibility 매개변수 이름과 hidden / completed_only 값은 여전히 허용됩니다(각각 invisible / trail로 매핑됨)지만 더 이상 권장되지 않습니다 — user_visibility를 사용하십시오.

동시성 — 진행 상황이 사람을 따르는가, 아니면 사례를 따르는가?

concurrency는 이 라인에서 한 사용자가 가질 수 있는 실행 수를 결정합니다:

"user" (기본값) — 사람당 하나의 실행; 모든 대화는 동일한 진행 상황을 계속합니다. 교육 과정, 온보딩, KYC에 적합함: "이 사람이 어디까지 왔는가".
"session" — 대화당 하나의 실행; 새 채팅은 새롭고 독립적인 사례를 시작합니다. 면허 신청, 지원 티켓, 제품별 흐름에 적합함: "이 사례가 어디까지 왔는가". 동일한 사용자가 세 가지 채팅에서 세 가지 제품 신청을 실행할 수 있으며, 각각 고유한 진행 상황과 블랙보드를 가집니다.

상태를 올바른 위치에 배치하십시오: 사례 상태는 블랙보드에(실행과 함께 생성되고 소멸함 — 제품 이름, 이 신청서의 문서 목록), 사람에 대한 사실은 프로필 차원에(사용자를 따라 실행과 스토리라인을 가로질러 이동함 — 회사 세부 정보, 검증된 신원). 대화당 하나의 사례는 의도적입니다: 다른 사례를 열려면 다른 채팅을 엽니다. concurrency 변경은 향후 등록에만 영향을 미치며, 이미 진행 중인 실행은 키를 유지합니다.

체크리스트, 게이트된 선택, 파일 및 결정적 동작

네 가지 노드 수준 기능은 "AI가 언제 완료되는지 결정한다"를 누적되고 결정적인 상태로 전환합니다:

checklist — 노드에 [{key, label}, …]. 각 턴마다 플랫폼은 방문자가 실제로 제공한 것(업로드 또는 구체적인 세부 정보가 포함된 설명 — 약속은 포함되지 않음)에서 항목을 체크하고, 모든 항목이 체크되었을 때 {"op": ">=", "left": {"ref": "checklist"}, "right": {"value": 1}}과 같은 종료 규칙이 진행을 진행시킵니다. 읽기 전용 맵은 사용자에게 실시간 ✓/○ 목록을 표시합니다. 이는 신청/승인 흐름에 적합한 형태입니다: 1단계에서 필요한 사항을 공지하고, 2단계의 체크리스트가 항목별로 수집합니다.
choices_offer: "on_ready" — 선택 버튼에 대한 게임 스타일의 타이밍: 단계가 완료될 때까지(체크리스트 완료 또는 제공된 choices_ready_criteria가 참으로 판단될 때까지) 숨겨져 있으며(텍스트 매칭도 비활성화됨 — 버튼 단어를 입력하여 앞서 나가는 것 방지), 그제야 표시됩니다. 대안 간 진정한 결정을 위해 user_choice를 사용하십시오; 단일 "계속" 버튼은 신호입니다.
{"ref": "files"} 종료 규칙 내 — 이 노드에 있는 동안 업로드된 파일/이미지 수(이동 시 초기화). files >= 2는 완전히 결정적인 "문서 수신" 게이트입니다.
questions — 노드별 아이스브레이커 칩(최대 6개): 사용자가 이 단계에 있을 때 묻는 질문이며, 해당 단계에 있을 때 탭 가능한 제안으로 표시됩니다. on_enter_opening과 쌍으로 사용하여 각 단계가 자신을 소개하고 진입 방법을 제공합니다 — 사용자는 "여기서 무엇을 해야 하는가"라고 궁금해해서는 안 됩니다.
on_enter_actions / on_complete_actions — [{tool, args}] 플랫폼은 단계가 진입되거나 흐름이 완료될 때 결정적으로 실행합니다(예: 종료 단계에서 mcp__agent4__submit_lead로 리드를 제출). 문자열 인수는 중괄호 템플릿으로 차원 및 블랙보드 키를 보간합니다. 실패는 로깅되며 채팅을 중단하지 않습니다.

스토리라인이 길어지더라도 컨텍스트는 평평하게 유지됩니다: 각 턴은 현재 노드(작업, 리소스, 선택), 프로필 차원 및 크기 제한이 있는 블랙보드만 주입하며, 전체 그래프나 과거 단계를 주입하지 않습니다. 긴 여정(한 학년, 시즌 전체 게임 아크)은 체인 스토리라인(on_complete: goto_next)이어야 합니다: 각 라인의 블랙보드는 새로 시작하지만 프로필 차원은 계승되며, 이는 "과거를 요약하고 현재를 그대로 유지"하는 것과 정확히 같습니다.

종료 판정은 이제 마지막 메시지뿐만 아니라 최근 대화 창과 수집된 상태를 보지만, ai_criteria는 방문자가 말하거나 수행한 사항에 관한 것이어야 합니다 — 위의 체크리스트 메커니즘은 여전히 어떤 텍스트 기준보다 강력합니다.

설계의 함정 — 각각이 프로덕션에서 멈춘 흐름을 초래했습니다

이것을 구축하는 당신(에이전트)이 이러한 버그의 가장 가능한 저자입니다. 게시하기 전에 각각을 확인하십시오:

rule 종료에는 작성자가 필요합니다. readiness >= 100은 실제로 readiness를 작성하는 것이 없는 한 막다른 길입니다 — 종료의 writes(결정적 — 선호됨), source: "ai"가 있는 노드의 profile_writes(대화에서 점수 매김), 다른 스토리라인 또는 수동 콘솔 편집. validate_storyline은 이제 이를 warn.rule_unwritten_dim으로 플래그합니다 — 외부 작성자가 존재함을 알지 않는 한 해당 경고를 버그로 처리하십시오. 이 정확한 실수가 한 번 발송되었습니다: 두 번째 단계가 아무것도 작성하지 않는 차원에 게이트를 둔 세 단계 수집 흐름; 사용자는 결코 그것을 통과할 수 없었습니다.
AI 점수 매김 차원은 거의 정확한 경계에 도달하지 않습니다. 차원이 모델에 의해 점수 매겨진 경우, >= 100(또는 == max)은 실제로 발동하지 않습니다 — 모델은 보수적으로 점수 매깁니다. 현실적인 임계값(>= 70)에 게이트를 두거나, 단계의 완료를 user_choice로 만들고 종료의 writes를 사용하여 값을 결정적으로 설정하십시오.
user_choice는 버튼 텍스트와 정확히 일치해야 하며 — 라벨은 무엇을 하는지 명시해야 합니다. 방문자의 메시지는 button_text와 같아야 합니다. 표시된 라인에서는 위젯이 이를 실제 버튼으로 렌더링하므로, 완벽하고 정확한 동사 구문을 작성하십시오 — "Start"가 아닌 "Start document collection" ("무엇을 시작? — 테스트에서 실제 피드백). 구별되게 작성하고 청중의 언어를 사용하십시오. invisible 라인에는 버튼이 없습니다 — 노드 task에 옵션을 다시 명시하십시오. 진정한 결정(어느 분기, 제출 vs 편집 계속)에 user_choice를 선호하십시오; "이 단계를 완료했는가"는 AI/종료 규칙의 작업이지 버튼의 작업이 아닙니다.
게시하는 것은 이미 진행 중인 실행에 영향을 미치지 않습니다. 등록은 시작된 리비전에 고정됩니다 — 버그 수정 릴리스는 새로운 실행에만 도달합니다. 기존 사용자를 이동하려면 POST /storylines/{id}/enrollments/migrate를 호출하십시오(reset은 진입점으로, move는 노드로 — 둘 다 실행을 현재 게시된 리비전에 다시 고정).
배포하기 전에 사용자로서 라인을 걷습니다. 공유의 /s/ 페이지를 열고, 흐름에 진입하고, 모든 버튼과 분기를 클릭하여 끝에 도달하십시오. 편집기의 테스트 실행은 그래프를 시뮬레이션합니다; 실제 페이지만이 오프닝, 버튼, 가시성 및 완성을 함께 실행합니다.

종료 경로는 우선순위 순서(목록 순서)입니다: 결정적 rule / user_choice / callback이 먼저 판정되고, ai가 마지막입니다. 결정적 종료로 if/else, 재시도 루프 및 AND-조인을 구성하십시오 — LLM에 도박하지 마십시오. update_storyline(PUT 세맨틱스; 종료와 깔때기가 참조하므로 모든 node_key를 안정적으로 유지)로 초안을 편집하십시오.

보고하십시오. 게시된 스토리라인의 콘솔 링크 — https://console.agent4.io/#/storylines/<id> (create_storyline에서 얻은 id) — 와 흐름 및 사용자가 진입하는 방법에 대한 한 줄 요약을 반환하십시오.