Workflow定義リファレンス

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

同じSessionへの順序付きメッセージ

session.prompt.fileが初回作業です。同じSessionへ続けて送る作業を、follow_upsに実行順で指定します。

session:
  agent: writer.yourname
  prompt: { file: prompts/title.md }
  follow_ups:
    - { file: prompts/article.md }

たとえばtitle.mdでタイトルを考え、article.mdでそのタイトルを使って記事を書きます。各ファイルには、そのturnの作業だけを書きます。前の作業は会話に残り、turn別outputsや新しい参照変数は作りません。最後の作業後にWorkflowが完了指示を別送します。すべての作業ファイルをprompts/内に置き、参照は起動前に検証します。follow_upsの省略・空配列は初回だけを意味し、nullは拒否されます。初回と同じファイルの再使用を含め、作業は最大128件です。作業・完了の各本文は100,000 UTF-8 bytes、描画後の計画全体は1 MiB以内です。後続だけが不正・過大でもAttemptは起動しません。

DraftではInitial message、Follow-up 1…を選んで各本文を編集し、追加・削除・順序はworkflow.yamlで変えます。AttemptにはCompletion reportも表示します。未送信本文は受け付けた計画であり、送信済みの会話履歴ではありません。Draft変更後も受理済み本文は変わりません。実行状態の記録がない場合も成功と推測しません。

新規Draftの検証・公開・Draft Runはschema 2/3を使います。既存Draftはschema_version: 2へ変更してcompletion placeholderを削除し、検証・公開します。旧schema 1 RevisionとRunは履歴閲覧専用です。起動・retry・取消はできません。再実行は移行後の公開Workflowから新Runを開始してください。定義は過去の版と異なる場合があります。元のpromptと結果は保持されます。

親子で構成された実行に旧Revisionが含まれる場合は、自身がschema 2のRunも一連の実行全体として履歴専用になります。APIのexecution_retiredで判別し、再実行は移行後の公開Workflowから新Runとして開始します。

定義のfield

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

Session StepのRuntime

session.runtimeを省略すると、そのStepはAgentの既定のRuntimeと設定（mode・model・effort）で起動します。既定はAttemptの起動時に解決されます。Agentの既定は、人間のownerがProjectのComposerのRuntime設定からSave as agent defaultで保存します（Agents）。Stepのpromptにmodelやeffortを書いても設定は変わりません。

特定のStepだけ別の設定が必要ならruntimeを指定します。

session:
  agent: writer.yourname
  runtime:
    kind: codex-acp
    config: {}
  prompt:
    file: prompts/write.md

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

条件・skip・合流

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_reasonにcondition_not_matched（参照と実際の値付き）またはdependency_skipped（先行Step付き）として記録されます。skipしたStepにはAttempt・Session・Ask・子Runを作らず、retryもできません。失敗・取消・blocked・未確定の依存を成功したskipとは扱いません。

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

Run outputsは単一のStep参照、または宣言順の候補配列を指定できる。候補はskippedだけを飛ばし、最初の成功Stepを選ぶ。失敗・取消・未完了・選択先の欠落や型違いで古い候補へ戻らない。単一参照と配列の最後の参照はskipされ得ないStepに限る（通常依存によるskip伝播を含む）。全候補は必須output pathで、解決先schemaはdescriptionや配列順も含め同一でなければならない。空配列は無効。固定Revisionとlatest Attemptから導出し、Run成功と全実行Stepのcompletion受理後に確定する。

outputs:
  verdict:
    - '{{ steps.recheck.outputs.verdict }}'
    - '{{ steps.check.outputs.verdict }}'

初回checkがpassでrecheckがskipならcheck、再チェック後はpass/failを問わずrecheckの値を返す。各Stepのverdictを同じ必須schemaにし、checkはskipされないStepとする。候補配列を使えるのはRunのトップレベルoutputsだけで、条件・子Workflow入力binding・promptの参照には使えない。

全Stepが成功またはskipならRunは成功になり得ますが、Run outputsには実行した全Stepの成功completion受理が必要です。子Runの成功だけでは、親Stepが出力を受理した証拠になりません。成果を使う前に親Runと実際のoutputsを確認してください。WebUIのRun詳細とDraftの図は、各Stepの条件・join・skip理由を表示します。

Bundleのファイルとpath

編集するrootは、ProjectのWorkflowではaachat/teams/<team>/projects/<project>/workflows/<slug>/、TeamのWorkflowではaachat/teams/<team>/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は拒否されます。解決されていないmerge競合のmarkerを含むファイルがあると、validate・publish・run --draftは送信前に停止します。Bundleはrepository全体のsnapshotではないので、無関係なファイルは外へ置きます。実行するAttemptからは、固定された読み取り専用Bundleを$AA_WORKFLOW_DIRで参照します。

Step Sessionが作業できるのはWorkflowのProjectだけです。promptが別Projectのaachat/teams/<team>/projects/<project>/…を指すと、validate・publish・run --draftが止まらない警告project_path_not_available_hereを返します。Team Bundleでは、Projectのpathを書くとすべてこの警告の対象です。必要な文章はBundleに置いて$AA_WORKFLOW_DIRから読むか、Run入力で渡します。

検証・公開・Draft Runでは、Sessionの初回promptやfollow-upが具体的に示す $AA_WORKFLOW_DIR/<path> がBundleにない場合、bundle_reference_missing 警告を返します。公開・実行は止めません。警告には参照元のtaskファイルと欠落パスが出るので、ファイルを同梱するか参照を直してください。Project・TeamのBundleで同じ検査を行います。変数・placeholder・glob・空白を含むパスや、scriptなど参照先ファイルの内部までは検査しません。既存の公開Revision・Runは変わりません。

入力・出力schemaの対応範囲

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

formatはuriだけに対応します。任意のJSON Schemaは使えません。$ref、allOf、oneOf、anyOf、nullable、型のunion arrayは未対応です。小さなschemaをその場に定義してください。文書pathは通常のstringにできます。format: uriはURIの形式であり、成果物の実在や適切なアクセス権を保証しません。WebUIのRunダイアログは、トップレベルの入力がすべて文字列・数値・整数・boolean（列挙値を含む）のときだけフォームを表示します。objectやarrayの入力が1つでもあれば、入力全体を1つのJSON objectとして入力します。

prompt参照と公開する値

Session promptでは文章に{{ inputs.reader }}や{{ steps.write.outputs.greeting }}を埋め込めます。Step出力を参照するには、相手がneedsに指定された直接の依存先でなければなりません。途中のStepに依存しても、その祖先すべてを参照できるわけではありません。参照するschema pathは実在する必要があります。作業ファイルに {{ aachat.step_completion }} は書きません。全作業の終了後に、Workflowがoutput schemaと完了手順を別turnで送ります。

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

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

子WorkflowとDecisionの完全な例

先にガイドのgreetingを同じProjectか、team:greetingで指せるTeamへ公開します。次にchat workflow init approve-greeting --project <team>/<project>でDraftを作り、次のworkflow.yamlを書きます。

schema_version: 2
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を作ります。

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を固定します。子は同じ所有者の公開Workflowか、team:<slug>で指すTeamの公開Workflowでなければならず、固定する子が持てるのはSessionとDecision Stepだけです。子Workflowの入れ子は拒否されます。未公開の子は検証に通りません。後から新しい子を公開しても、既存の親RevisionやRunは変わりません。取り込むには親Draftを再検証して公開します。失敗した子Runを開いて内部Stepを復旧し、子の取消は親Runから行います。

コマンドリファレンス

Session内のAgent向けのchat workflowコマンドです。識別子は実際の値へ置き換えます。表の角括弧は任意引数を示すもので、入力しません。Project単位の操作は--project <team>/<project>（Project slugだけも可）を受け付け、省略するとcwdのProjectを使います。validate・publish・run --draftはBundle pathから所有者（ProjectまたはTeam）を判断し、cwdを変える必要はありません。Team Bundleのrun --draftは、実行先Projectを--projectかcwdから取ります。completeは現在のAttemptを対象にし、Run IDを受け付けません。

補足：

• runは--stdinと--input-file <path>のどちらか1つを指定し、入力はJSON objectです。list・runs・attemptsのpage sizeは1–100で、既定はlistとattemptsが50、runsが4です。次のpageは応答のnext_pageのコマンドをそのまま使います。
• Project全体のrunsはroot Runを表示し、Workflow slugを付けるとそのrootと子Runを親の識別情報付きで表示します。--stateはrunning・waiting_for_decision・cancelling・attention_required・succeeded・cancelledのいずれかです。各項目にはinputと、成功後のoutputsが含まれ、自由記述の文字列は100文字のpreviewになりtruncated: trueが付きます。全文はdetail_readのstatusで読みます。
• listは公開済みでアーカイブされていないWorkflowを、そのProjectとTeamの分まで返します。TeamのWorkflowはslugがteam:<slug>です。--archivedはアーカイブ済みを未公開Draftも含めて返します。
• statusは各Stepの要約とfeedback_count、available_actionsを返します。--detailは定義・入力・prompt・起動情報・feedback本文を含む完全な記録です。
• runの--client-nonceを省略すると、Session・Project・Workflow・入力から要求の識別子が決まり、同じコマンドの再実行は同じRunを返します（created: false）。新しいUUIDを渡すと同じ入力で別のRunを開始します。initとretryの--client-nonceは、まったく同じ要求を再試行するときだけ再利用します。変更した入力にnonceを再利用しません。
• --waitは永続的な待機登録で、CLIをblockしません。Workflow AttemptのSession内では使えません。
• archive・restoreは--previewで影響を確認し、その応答の値を--expected-lifecycle-version <N> --confirmation-token <token>に渡すと確認した内容のまま適用します。
• WebUIを使わず通常のターミナルから操作するaachat workflowコマンドもあります。構文はCLIを参照してください。

応答の読み方

出力は共通の{"ok": true, "data": {...}}、失敗時は{"ok": false, "error": ...}の形です。jqで値を取り出すときは.dataから辿ります。

• validate：valid、warnings、workflow_steps、content_hash。validがfalseならエラーはworkflow_validation_failedです。
• init：bundle_ready、Bundleのpathを示すbundle.path、client_nonce。1分以内に手元へBundleが用意されなければworkflow_bundle_not_readyになり、同じnonceの復旧コマンドが返ります。
• run：accepted、created、run、available_actions、detail_read、開始したStep Sessionのstartups[]。startups[].startup.stateはstarted・failed・preparing・runtime_offlineのいずれかで、serverは最大40秒待ってから返します（ガイド）。run --waitの後段（待機登録）が失敗した場合はok: falseでも、確定したRun IDとnonce、失敗した段階がdataに残ります。新しく作り直す前に既存のRunを確認します。
• complete：acceptedがtrueのときだけ、そのAttemptの完了意思が受理されています。Run全体の成功ではありません。
• archive・restore：triggers（一時停止したTrigger）、継続する既存Run、triggers_resumed: false。

chat workflow status <run-id> --detail は各Step/itemの最新試行のSession累計 token_usage と、起動時モデル設定 observed_launch を返します。過去の試行は attempts（続きは next_page）、一試行は attempt で読みます。5項目は input_tokens、output_tokens、cache_read_tokens、cache_creation_tokens、turn_count です。通常の status も使用量を保持し、observed_launch は省略します。

値は読取時点のSession累計で、工程・Run全体の総量ではありません。保存済みの完了ターンだけを含み、試行終了後も増える場合があります。子Run・別Sessionは加算しません。field省略はSession値がないこと、0は保存値であり、実消費0や計測完備を意味しません。runtime内部のサブエージェントの包含は未確認です。起動時設定は全ターンのモデルを保証しません。model optionの id と applied_config_options[].config_id を対応させ、proof: observed は観測済み、ack は適用受付まで、適用記録のないoptionは起動時snapshotとして読みます。aliasはそのまま扱い、観測の欠損を要求値で補完しません。

上限と超過時の対応

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

Session Stepの開始branch

任意の session.working_branch は、同じProjectのworkspace repository内のremote branchを開始点にします。literal文字列、Runのrequired string入力（"{{ inputs.start_branch }}"）、直接のneedsにあるStepのrequired string出力を指定できます。途中のobjectもrequiredである必要があります。子Workflowの出力はpinされたRevisionのschemaで検証します。join: true はliteralかRun入力のみを使えます。

省略はProject/Teamから解決した既定を使い、前工程の指定を暗黙継承しません。明示的な空文字（trim後の空白だけも含む）はrepository既定branchを使います。null、非文字列、部分的な式、origin/...、refs/...、HEADは使えません。参照から得た値を式として再評価しません。

各Sessionは起動時に取得したremote先端から個別の管理branchで始まります。指定はpush先・PR先を決めず、自動commit・push・mergeはしません。前工程はcommit・push完了後にbranch名を返してください。branchが後で進むと次の開始点も進みます。retryは同じbranch名の最新先端を取得し、同じSessionの再開・follow-upは既存workspaceを維持します。remoteが存在しなければ起動失敗となり、既定branchへfallbackしません。

以下をBundleに保存し、maker.ownerをProjectのAgent名へ置き換えて chat workflow validate <Bundle path> で検証できます。workflow.yaml:

schema_version: 2
name: Branch handoff
description: Continue from the previous Step's pushed files
inputs: {type: object, additionalProperties: false, properties: {}}
steps:
  prepare:
    needs: []
    session:
      agent: maker.owner
      prompt: {file: prompts/prepare.md}
    outputs:
      type: object
      additionalProperties: false
      required: [branch]
      properties:
        branch: {type: string}
  continue:
    needs: [prepare]
    session:
      agent: maker.owner
      working_branch: "{{ steps.prepare.outputs.branch }}"
      prompt: {file: prompts/continue.md}
    outputs: {type: object, additionalProperties: false, properties: {}}

prompts/prepare.md:

Create the files in your workspace. Commit and push them to your Session branch,
then return that branch name in outputs.branch.

prompts/continue.md:

Read the previous Step's files directly from the workspace and continue the work.

一覧の各要素を実行する

schema 3のsession・decision・workflow Stepに for_each: '{{ inputs.candidates }}' を追加すると、一覧の各位置を独立して実行します。参照元はrequiredなRun inputまたは直接needの成功output。array schemaには items と100以下の maxItems が必要です。本文・follow-up・decision body・child inputsでは {{ item }} / {{ item.name }} を使えます。whenは一覧全体へ適用します。

同じRun・Stepは最大4件を並行受付し、回答待ちやchildも枠を使います。0件はAttemptなしで成功します。outputsは1件分を定義し、全件成功すると後続は入力順の steps.<key>.outputs.items を受け取ります。集約はcompletion wrapper込み128 KiB/depth 32以内に収め、大きな成果は保存先への参照を返してください。

失敗しても他の件は進みます。履歴・retry・外部feedbackには0始まりの --item-index N を指定します。retry対象は available_actions.retry_items のみで、成功済み件は再実行しません。1件に複数工程が必要ならchild Workflowを使います。schema 2の親はschema 3のchildをpinできません。