Hane Platform

Workflow と案件

Workflow の定義、案件の始まり方と状態、待機、スケジュール、案件の操作を説明します。

このページでは、業務の進め方を Workflow として定義し、1 件ずつの仕事を案件として進める仕組みを説明します。待機・スケジュール・案件の操作もここで扱います。

Workflow と案件

Workflow は案件の進め方の定義で、案件は Workflow で進める 1 件の仕事です。案件は必ず 1 件の業務データのレコード（案件の対象）を持ちます。たとえば「契約満了への対応」という Workflow は、リース契約のレコードごとに 1 件の案件を進めます。

Workflow は workflows/v1alpha1 の Workflow マニフェストで書きます。

apiVersion: workflows/v1alpha1
kind: Workflow
metadata:
  name: lease-expiry
spec:
  case:
    purpose: 契約満了への対応を決める
    subject: LeaseContract                    # 案件の対象の型
    title: '"満了対応: " + subject.contract_no'
    businessKey: subject.contract_no          # 同じキーの案件を重ねて作らない
    deadline: subject.notice_due
    attention: [end_date, notice_due]         # 確定していなければ案件に要確認として出す
  start: check-values
  steps:
    check-values:
      branch:
        cases:
          - when: 'states.end_date != "confirmed"'
            next: confirm-dates
        default: decide
    confirm-dates:
      task:
        title: '"満了日を確かめる: " + subject.contract_no'
        assignment: fleet-desk                # AssignmentRule の名前
        due: "addDays(subject.notice_due, -30)"
        outcomes: { confirmed: 確かめて確定にした }
      on: { confirmed: decide }
    decide:
      task:
        title: '"更新の方針を決める: " + subject.contract_no'
        assignment: fleet-desk
        due: subject.notice_due
        outcomes: { renew: 再リースする, return: 返却する }
      on: { renew: done-renew, return: done-return }
    done-renew:
      complete: { outcome: renew }
    done-return:
      complete: { outcome: return }

条件やタイトルなどの式は CEL で書きます。式では、案件の対象のレコード（subject）とその値の状態（states）、案件（case）、前のステップの結果（steps）、案件の入力（input）を使えます。

ステップの種類

ステップ	すること
`task`	Task を作って担当に割り当て、閉じるのを待つ。結果（`outcomes` のどれか）で次へ進む
`notify`	担当や割り当ての規則のグループに、メールなどで知らせを送る
`branch`	CEL の条件で次のステップを選ぶ
`agent`	Agent を動かし、その結果で次へ進む。Agent が失敗・停止したら `on.failed` へ進む
`wait`	イベント、Agent が提案した操作の結果、書類の到着、メールの返信、時間を待つ
`record`	業務データのレコードをキーで探し、なければ作り、あれば直す。値は推定で、出典は案件とステップになる
`query`	対象のレコードから関係を ID でたどり、結果を次のステップで使えるようにする
`escalate`	担当に引き継ぐ Task を作り、閉じたら案件を終える
`complete`	案件を完了にし、結果（`outcome`）を記録する

案件の始まり方

案件は次のところから始まります。どの場合も、案件の対象のレコードと、そのときの有効なバージョンの Workflow で始まります。

スケジュール：毎日決まった時刻に、条件に合うレコードごとに案件を始めます（下の「スケジュール」）。
Agent：Agent の定義の workflows に挙げた Workflow を、Agent が workflow.start ツールで始めます。
文書の問い合わせ：書類から値が読めず要照会にしたとき、抽出の定義に書いた問い合わせの Workflow を始めます。

同じ業務キー（businessKey）で進行中の案件があれば、新しい案件は作りません。

案件の状態

ステータス	意味
`running`	ステップを進めている
`waiting`	Task・イベント・操作の結果などを待っている
`completed`	`complete` のステップに着いて終わった
`cancelled`	取り消した
`failed`	ステップが失敗した。理由は `error` と経過に残る

GET /v1/workflows/cases/{id} は、案件と、経過（ステップごとの出来事）、待機、案件が動いている Workflow の定義を返します。案件の attention には、case.attention に挙げた項目のうち確定していない値が入ります。

待機

案件が待っている間、Hane は何も動かしません。LLM を呼び続けることも、Agent の CLI を残しておくこともありません。待っている条件は保存され、Task が閉じた、イベントが届いた、期限が来たといったときに案件が再開します。

待つもの	書き方
Task	`task` のステップ。`timeout`（`30m`・`72h`・`7d` の形）を過ぎると Task を取り消して `on.expired` へ進む。`closeOn` で、指定したイベントが届いたら人を待たずに閉じることもできる
イベント	`wait.event` と `wait.match`（CEL）。条件に合うイベントが届くまで待つ
Agent が提案した操作	`wait.action`。承認と実行の結果（`succeeded`・`failed`・`cancelled`・`expired` など）と `timeout` の 7 通りの行き先を必ず書く
書類	`wait.document`。対象のレコードに結び付いた、指定した種類の書類が届くまで待つ
メールの返信	`wait.replies`。送ったメールすべてに返信が届くか、届かないと決まるまで待つ

wait のどの形にも timeout を付けられ、時間切れは on.timeout へ進みます。時間切れになっても、提案した操作を勝手に取り消したり送り直したりはしません。

スケジュール

スケジュールは workflows/v1alpha1 の Schedule マニフェストで書き、毎日決まった時刻に発火します。発火のときにすることは次の 3 つのどれかです。

書き方	発火したときにすること
`workflow` と `forEach`	`forEach.type` の型のレコードのうち `forEach.where`（CEL）に合うものごとに、案件を始める
`agent`	Agent を 1 回動かす。入力は発火した日とスケジュールの名前
`connection`	外部の接続先からの取り込みを 1 回始める

apiVersion: workflows/v1alpha1
kind: Schedule
metadata:
  name: daily-expiry-scan
spec:
  every: day
  at: "07:00"
  timezone: Asia/Tokyo
  forEach:
    type: LeaseContract
    where: 'record.status == "active" && record.notice_due != null && daysBetween(event.date, record.notice_due) <= 90'
  workflow: lease-expiry

スケジュールは ReleaseBundle を有効にしたときに登録し直されます。発火は、その時点の有効なバージョンを使います。

操作	API
一覧と次の発火の時刻	`GET /v1/workflows/schedules`
手動で発火する（発火の日は今日）	`POST /v1/workflows/schedules/{name}/trigger`
一時停止・再開	`POST /v1/workflows/schedules/{name}/pause`・`resume`

発火の結果には、条件に合ったレコードの数、作った案件の数、すでにあった案件の数、失敗したレコードと理由が残ります。

案件を操作する

失敗した案件や止めたい案件は、API かコンソールから操作します。操作には workflows:operate のスコープが要ります。

操作	API	内容
一覧	`GET /v1/workflows/cases`	`status`・`workflow`・`subject_id`・`business_key` で絞れる
取り消す	`POST /v1/workflows/cases/{id}/cancel`	理由（`reason`）が要る。案件の開いている Task も取り消す
やり直す	`POST /v1/workflows/cases/{id}/retry`	失敗した案件を、失敗したステップからやり直す
始め直す	`POST /v1/workflows/cases/{id}/restart`	今の案件を取り消し、同じ Workflow と対象のレコードで、いまの有効なバージョンの案件を始める

案件が complete のステップで終わると、成果（outcome record）が 1 件記録されます。成果は GET /v1/workflows/outcomes で読めます。同じ案件の同じ完了条件の成果は 1 件だけで、イベントが届き直しても増えません。

案件の完了・失敗・取り消しは、workflows.case.completed・workflows.case.failed・workflows.case.cancelled のイベントとして Webhook で受け取れます。

次に読む

承認と TaskTask の割り当て、引き受け、決定

AgentWorkflow から Agent を動かす

データと Workflow を使う業務アプリから案件を扱う手順

定義をコードで管理するWorkflow を有効にする流れ