Divination Run Protocol (Frontend <-> Backend)

This document defines the structured contract for divination run input, backend hexagram derivation, and run event output.

Protocol verification status:

Backend route source: backend/src/v1/agent/router.py
Backend derivation source: backend/src/core/divination/derivation.py
Runtime payload schema source: backend/src/schemas/domain/divination.py

Compatibility strategy

Current strategy: additive evolution only.
Existing required fields cannot be removed or renamed without migration notes.
Canonical divination terminology values must remain Chinese.

Route overview

Submit run: POST /api/v1/agent/runs
Stream events: GET /api/v1/agent/runs/{threadId}/events?runId=...

Run request contract

RunAgentInput uses AG-UI shape. This protocol constrains two sections:

messages[0].content (question text)
forwardedProps.divinationPayload (structured divination input)

Required request shape

{
  "threadId": "uuid",
  "runId": "run_20260403_xxx",
  "state": {},
  "messages": [
    {
      "id": "msg_run_20260403_xxx_user_0",
      "role": "user",
      "content": "我最近换工作是否合适？"
    }
  ],
  "tools": [],
  "context": [],
  "forwardedProps": {
    "runtime_mode": "chat",
    "client_time": {
      "device_timezone": "Asia/Shanghai",
      "client_now_iso": "2026-04-03T20:30:00+08:00",
      "client_epoch_ms": 1775219400000
    },
    "divinationPayload": {
      "divinationMethod": "手动起卦",
      "questionType": "事业",
      "question": "我最近换工作是否合适？",
      "divinationTimeIso": "2026-04-03T20:30:00+08:00",
      "yaoLines": [
        "少阳",
        "少阴",
        "老阳",
        "少阴",
        "少阳",
        "老阴"
      ]
    }
  }
}

AG-UI required base fields

state: required object, frontend sends {} by default.
messages[0].id: required string id for user message.
tools: required array, frontend sends empty array when no tools requested.
context: required array, frontend sends empty array when no extra context.

`divinationPayload` strict rules

divinationMethod: enum, allowed values 手动起卦 | 自动起卦
questionType: non-empty string, recommended Chinese category labels
question: non-empty string
divinationTimeIso: RFC3339 datetime with timezone offset
yaoLines: exactly 6 items, order is 初爻 -> 上爻
yaoLines item enum: 少阳 | 少阴 | 老阳 | 老阴
Additional fields are forbidden.

Event output contract

During run streaming, backend emits standard AG-UI lifecycle events and two divination-relevant payload events:

1) `DIVINATION_DERIVED`

Emitted once after backend derives hexagram data.
Payload field: divination (strict object).

divination object:

{
  "question": "我最近换工作是否合适？",
  "questionType": "事业",
  "divinationMethod": "手动起卦",
  "divinationTime": "2026年04月03日 20:30",
  "binaryCode": "101001",
  "changedBinaryCode": "100001",
  "guaName": "山火贲",
  "upperName": "艮",
  "lowerName": "离",
  "targetGuaName": "山雷颐",
  "worldPosition": 1,
  "responsePosition": 4,
  "hasChangingYao": true,
  "ganzhi": {
    "yearGanZhi": "丙午",
    "monthGanZhi": "壬辰",
    "dayGanZhi": "辛亥",
    "timeGanZhi": "乙巳",
    "yearKongWang": "子丑",
    "monthKongWang": "午未",
    "dayKongWang": "寅卯",
    "timeKongWang": "戌亥",
    "yueJian": "辰土",
    "riChen": "亥水",
    "yuePo": "戌土",
    "riChong": "巳火"
  },
  "wuXingStatuses": {
    "木": "囚",
    "火": "休",
    "土": "旺",
    "金": "相",
    "水": "死"
  },
  "yaoInfoList": [
    {
      "position": 1,
      "spiritName": "虎",
      "relationName": "官鬼",
      "tiganName": "卯",
      "elementName": "木",
      "isYang": true,
      "isChanging": false,
      "specialMark": "世"
    }
  ],
  "targetYaoInfoList": [],
  "fushenPositions": [2],
  "fushenInfoList": [
    {
      "position": 2,
      "relationName": "父母",
      "tiganName": "午",
      "elementName": "火"
    }
  ]
}

2) `TEXT_MESSAGE_END`

Standard final answer event.
Existing fields remain canonical: sign_level, summary, conclusion, focus_points, advice, keywords, answer.

Frontend should combine:

structural divination data from DIVINATION_DERIVED
interpretation text from TEXT_MESSAGE_END

Error contract linkage

All errors use RFC7807 with extension code and optional params.
Error code registry source: docs/protocols/common/http-error-codes.md.

4.6 KiB Raw Blame History