---
title: "Workflow定義リファレンス"
description: "Bundleのpath、Stepの種類、型schema、prompt参照、子Workflow、コマンドと実行上限を説明します。"
---

# Workflow定義リファレンス

`workflow.yaml`の編集時に使うリファレンスです。Session Stepの完全な例と作成から成果確認までの手順は[Workflowガイド](/ja/docs/workflows)を参照してください。定義は`schema_version: 1`のYAMLで、未対応のfieldは拒否されます。YAMLのanchor、alias、merge key、tagには対応しません。公開や実行の前に、実際のDraftを検証します。

## 定義のfield

| field | 契約 |
|---|---|
| `schema_version` | 必須の整数`1`。 |
| `name` | 必須の空でない表示名。Workflowの識別にはDraftディレクトリのslugを使います。 |
| `description` | 必須の説明文字列。 |
| `inputs` | Run入力の閉じたobject schema。入力がなければ`properties: {}`を使います。 |
| `steps` | 1–64 Stepの必須map。keyは`^[a-z][a-z0-9_-]{0,63}$`。 |
| `outputs` | 公開する出力名と、完全なStep出力参照を対応付ける省略可能なmap。JSON Schemaではありません。省略時は公開する値なし。 |
| `steps.<key>.needs` | 直接依存の必須list。rootは`[]`。1 Stepあたり32、全体256 edgeまで。不明・重複する依存や循環は拒否されます。 |
| `steps.<key>.when` | 直接依存の出力に対する省略可能な条件。すべてのStep種類に使えます。`value`と、`equals`または`otherwise: true`のどちらか一方を指定します。 |
| `steps.<key>.join` | 省略可能なboolean。既定は`false`。`true`はSession、空でない`needs`、`when`なしの場合だけ使えます。 |
| `steps.<key>.session` | Stepの種類を1つだけ指定。`agent`、`runtime`、`prompt.file`が必須。Session Stepは`outputs` schemaも宣言します。 |
| `steps.<key>.decision` | Stepの種類を1つだけ指定。静的で空でない`question`と`body.file`が必須。`options`は省略可能。Stepの`outputs`は宣言しません。 |
| `steps.<key>.workflow` | Stepの種類を1つだけ指定。公開済みの子の`slug`が必須。`inputs`で子のfieldを対応付けます。Stepの`outputs`は宣言しません。 |

Session Stepでは`runtime.kind`が必須です。`runtime.config`はoption IDを文字列またはbooleanへ対応付けるmapで、省略または`{}`を指定できます。文字列はACPのoption value IDで、任意の表示名ではありません。数値は受け付けません。利用可能なkindとoptionは`chat project members <team>/<project> --runtime-profiles`で調べます。実行時にもAgentのmembership、ownerの利用可能性、Runtimeの互換性が必要です。

`needs`は実行順の依存関係であり、条件式ではありません。1つのStepへSession、Decision、子Workflowを併記できません。`scripts/`のファイルはAgentが使える補助資料です。置くだけでshell Stepができたり、コマンドが自動実行されたりはしません。

## 条件・skip・合流

**対応版の前提:** これらのfieldには対応するAPI/server・WebUI・CLIが必要です。このガイドでは利用環境への提供を確認できていません。利用前に管理者へ稼働版を確認し、そのserverで実際のDraftを検証し、試行Runの条件・skip理由・outputsを確認してください。不明なfieldのエラーや条件・skip表示の欠落があれば、停止して対応版を確認します。条件を削って無条件で実行しません。[完全な分岐例](/ja/docs/workflows)も参照してください。

`needs`は引き続き依存関係を表します。結果で工程を選ぶには明示的に`when`を加えます。`when.value`には、直接の依存先の必須booleanまたはstring enumへの完全な参照`{{ steps.<direct-need>.outputs.<path> }}`を1つ指定します。自由記入stringを許す例外はDecisionの`answer`だけです。`equals`は型と値の完全一致で、booleanの`true`とstringの`"true"`は異なり、文字列をtrimしたり意味を推論したりしません。enumでは宣言された値だけを比較できます。Run inputs、省略可能な出力path、任意式、型変換、ループ、障害回復分岐は扱いません。

`otherwise: true`は、**Revision全体で同じ正規化された参照**を使う`equals`のどれにも一致しない場合だけ該当します。その参照に`equals`が少なくとも1つ必要で、`otherwise`は最大1つです。同じ値に一致するStepが複数あれば、すべてが実行対象になります。booleanやenumでは、どの枝でも作業しない未被覆値を残せます。

Decisionの回答では、`equals`は公開された選択肢に一致させます。回答による分岐には`otherwise`の**Session**が必須で、`needs`はそのDecisionだけ、promptはその`answer`を直接参照します。自由回答と未被覆の選択肢はこのSessionが受け取ります。人間の条件と権限を保ち、追加判断が必要ならAskで尋ねます。回答の一致は新しい権限を与えず、後からAskを編集しても固定した回答revisionは変わりません。

条件不一致は`skipped`となり、skipしたStepへ依存する通常Stepもskipします。skipしたStepにはAttempt・Session・Ask・signal・子Runを作りません。失敗・取消・blocked・未確定の依存を成功したskipとは扱いません。

`join: true`のSessionは、直接依存の**すべて**が成功またはskipになるまで待ち、全枝skipでも動きます。失敗や取消は通過しません。promptから`steps.*.outputs.*`を直接参照してはいけません。代わりに、serverがcompletion指示の直前へ添付する`Workflow dependency results`を読みます。Step key順のcanonical JSON配列で、依存ごとの`step`、`state`と、受理済み`outputs`またはskipの`reason`を持ちます。添付も100,000-byteのprompt上限に含まれ、retryと過去promptの復元でも保持されます。

トップレベルの`outputs`は、skipを引き継ぐ通常の下流Stepも含め、skipされ得るStepを参照できません。代わりにjoinの必須出力を公開します。全Stepが成功またはskipならRunは成功になり得ますが、Run outputsには実行した全Stepの成功completion受理が必要です。子Runの成功だけでは、親Stepが出力を受理した証拠になりません。成果を使う前に親Runと実際の`outputs`を確認してください。

## Bundleのファイルとpath

編集するrootは`aachat/projects/<team>/<project>/workflows/<slug>/`です。Bundleには必須の`workflow.yaml`、任意のroot `README.md`、`prompts/`または`scripts/`配下のtext fileを置けます。Sessionの`prompt.file`とDecisionの`body.file`は、Bundle内に実在する`prompts/`配下のファイルを指します。

大文字小文字を区別する相対pathと、通常のUTF-8 textを使います。絶対path、backslash、空またはdotのpath segment、dotfile、`_published`、重複path、U+0000は拒否されます。Bundleはrepository全体のsnapshotではないので、無関係なファイルは外へ置きます。実行するAttemptからは、固定された読み取り専用Bundleを`$AA_WORKFLOW_DIR`で参照します。

## 入力・出力schemaの対応範囲

Runの`inputs`とSession Stepの`outputs`のrootはobjectです。**入れ子も含め、すべてのobjectに`additionalProperties: false`が必要です。** `properties`でfieldを宣言し、`required`で必須fieldを指定します。任意fieldは省略できますが、不在の代わりに`null`を渡しません。

| 対応する構造 | 値・keyword |
|---|---|
| 型 | `object`、`string`、`number`、`integer`、`boolean`、`array` |
| object | `properties`、`required`、`additionalProperties` |
| array | `items`、`minItems`、`maxItems` |
| string | `minLength`、`maxLength`、`pattern`、`format` |
| number | `minimum`、`maximum` |
| 共通 | `type`、`enum`、`description` |

`format`は`uri`だけに対応します。任意のJSON Schemaは使えません。`$ref`、`allOf`、`oneOf`、`anyOf`、nullable、型のunion arrayは未対応です。小さなschemaをその場に定義してください。文書pathは通常のstringにできます。`format: uri`はURIの形式であり、成果物の実在や適切なアクセス権を保証しません。

## prompt参照と公開する値

Session promptでは文章に`{{ inputs.reader }}`や`{{ steps.write.outputs.greeting }}`を埋め込めます。Step出力を参照するには、相手が`needs`に指定された**直接の依存先**でなければなりません。途中のStepに依存しても、その祖先すべてを参照できるわけではありません。参照するschema pathは実在する必要があります。生成された完了手順のmarker `{{ aachat.step_completion }}`は、各Session promptの末尾に1回だけ置き、後ろには空白だけを許容します。

Decision本文も入力と直接依存先を参照できますが、完了markerは含めません。questionとoptionsは静的な値です。serverがAskを作って人間の回答を受理するため、AgentはDecisionのcompletion payloadを送りません。

トップレベルの`outputs`では、例えば`greeting: "{{ steps.write.outputs.greeting }}"`のように、元schemaで必須のStep出力pathを指定します。Runの入力を直接参照することはできません。serverが対応付けから閉じた出力schemaを導きます。子の成功出力は、後続作業の開始前に親Stepへ1回だけ書き込まれます。

## 子WorkflowとDecisionの完全な例

先に[ガイド](/ja/docs/workflows)の`greeting`を同じProjectへ公開します。次に`chat workflow init approve-greeting --project <team>/<project>`でDraftを作り、次の`workflow.yaml`を書きます。

```yaml
schema_version: 1
name: approve-greeting
description: Ask a human to review a generated greeting.
inputs:
  type: object
  additionalProperties: false
  properties:
    reader:
      type: string
      minLength: 1
  required: [reader]
outputs:
  greeting: "{{ steps.compose.outputs.greeting }}"
  answer: "{{ steps.review.outputs.answer }}"
steps:
  compose:
    needs: []
    workflow:
      slug: greeting
      inputs:
        reader: "{{ inputs.reader }}"
  review:
    needs: [compose]
    decision:
      question: Is this greeting ready to use?
      body:
        file: prompts/review.md
      options: [Use it, Revise it]
```

`prompts/review.md`を作ります。

```text
Please review this greeting for {{ inputs.reader }}:

{{ steps.compose.outputs.greeting }}

Choose whether it is ready, or explain the revision needed.
```

ガイドと同じ手順でslugを`approve-greeting`に置き換え、検証し、必要なら`{"reader":"Alex"}`でDraft Runを試し、公開します。子が`greeting`を作り、その後Runを開始した人間（Agentが開始した場合はその人間owner）へAskが届きます。Decisionの宛先を任意に設定するfieldはありません。成功したRunは`greeting`と`answer`を公開します。`Revise it`を選んでも、その回答でDecisionは完了します。この定義に修正Stepはありません。回答を解釈するには後続Session Stepを追加し、枝を選ぶには`when`と必須の`otherwise` Sessionを定義します。

Decisionの`options`は自由記入なら省略または空にし、選択肢がある場合は重複しない2–5個にします。Decisionへ`outputs`を追加しません。必須のstring `answer`を持つobject schemaが自動で導かれます。serverは採用した回答revisionを固定するため、後からAskを編集してもこのRunは変わりません。

子の`workflow.inputs`の各値は、literal JSON値か、入力・直接依存先を指す完全な参照式1つです。参照式の周りへ文章を補間しません。子の必須入力をすべて結び付け、schemaが受け付けるfieldだけ渡します。渡し先が任意入力でも、参照元pathは必須でなければなりません。参照元schemaは対応する制約も含め渡し先の契約の部分集合である必要があり、基本型の一致だけでは不十分です。例えば`reader: "{{ inputs.reader }}"`の代わりに`reader: Alex`というliteralを指定できます。

serverは実行・公開の検証時に、子の現在の公開Revisionを固定します。子は**同じProject**で利用可能でなければならず、固定する子が持てるのはSessionとDecision Stepだけです。子Workflowの入れ子は拒否されます。後から新しい子を公開しても、既存の親RevisionやRunは変わりません。取り込むには親Draftを再検証して公開します。失敗した子Runを開いて内部Stepを復旧し、子の取消は親Runから行います。

## コマンドリファレンス

Session内のAgent向けコマンドです。識別子は実際の値へ置き換えます。多くのProject操作は`--project <team>/<project>`を受け付け、省略するとcwdからProjectを判断します。`validate`にはDraftのProject cwdとserver接続が必要です。`publish`と`run --draft`はDraft pathからProjectを判断します。`complete`は現在のAttemptを対象にし、Run IDを受け付けません。

| 操作 | 構文 |
|---|---|
| Draft作成 | `chat workflow init <slug> --project <team>/<project>` |
| 検証 | DraftのProjectで`chat workflow validate workflows/<slug>` |
| 公開一覧 | `chat workflow list --project <team>/<project> [--last 50] [--before <cursor>]` |
| 公開契約・Step一覧（開始前確認は[Workflows](/ja/docs/workflows)） | `chat workflow show <slug> --project <team>/<project>` |
| 履歴 | `chat workflow runs [<slug>] --project <team>/<project> [--last 50] [--before <cursor>]` |
| Draft Run | `chat workflow run --draft <draft-path> --stdin` |
| 公開Run | `chat workflow run <slug> --project <team>/<project> --stdin [--wait]` |
| 公開 | `chat workflow publish <draft-path>` |
| Run詳細 | `chat workflow status <run-id> --project <team>/<project>` |
| 取消 | `chat workflow cancel <run-id> --project <team>/<project>` |
| 再試行 | `chat workflow retry <run-id> --step <key> --project <team>/<project>` |
| Attempt完了 | `chat workflow complete --stdin` |
| Attempt feedback | `chat workflow feedback [<run-id> --step <key> --project <team>/<project>] [--attempt N] --stdin` |

表の角括弧は任意引数を示すもので、入力しません。`run`は`--stdin`と`--input-file <path>`のどちらか1つを指定します。`list`と`runs`のpage sizeは1–100、既定50です。Project全体の`runs`はrootを表示し、Workflow slugを付けるとそのrootと子Runを親の識別情報付きで表示します。`init`、`run`、`retry`は、まったく同じ要求の再試行用に`--client-nonce <uuid>`を受け付けます。変更した入力にnonceを再利用しません。必ず`available_actions`と構造化された復旧応答に従います。`--wait`は永続的な待機登録で、CLIをblockしません。

## 上限と超過時の対応

| 対象 | 上限 | 超えた場合 |
|---|---|---|
| Bundleの1 file | 256 KiB | 補助textを短くするか分割します。 |
| Bundle全体 | 1 MiB、128 files | 無関係なassetを除きます。 |
| 相対path | UTF-8で256 bytes | pathを短くします。 |
| 依存graph | 64 Steps、各Stepのneedsは32、全体256 edges | 1段の合成制約を守ってgraphを縮小します。 |
| 描画後のSession prompt | 生成する完了手順を含む100,000 bytes | prompt、入力、上流textを短くします。 |
| Decision question / 各option | 空ではなく2,000 / 200 bytes以下 | 固定textを短くし、重複しない2–5 optionsまたは自由記入にします。 |
| 描画後のDecision本文 | 100,000 bytes | 変更不能な入力や定義を修正し、新Runで実行します。 |
| Run input | 128 KiB、JSON depth 32 | 大きな内容はProject resourceへ保存して参照を渡し、深い入れ子を平坦化します。 |
| completion JSON / Run outputs | 128 KiB、JSON depth 32 | 短い成果物参照を返します。 |
| 失敗completionの診断 | 空ではなく4 KiB以下 | 原因と次の操作を残して診断を短くし、再試行します。 |
| Attempt feedback | 8,192 bytes | 問題を具体的な短い記述にします。 |

KiBとMiBは2進単位です。bytesは文字数ではありません。これらはWorkflowの上限であり、Database SQLやSession follow-upの周期制約とは別です。schema検証の成功はRuntimeの実行可能性や成果物の正しさを保証しません。状態別のretry、取消、完了受理は[Run復旧ガイド](/ja/docs/workflows)、予定された起動の失敗は[Triggerガイド](/ja/docs/triggers)を参照してください。