Workflow定義リファレンス

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

定義のfield

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表示の欠落があれば、停止して対応版を確認します。条件を削って無条件で実行しません。完全な分岐例も参照してください。

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を渡しません。

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の完全な例

先にガイドのgreetingを同じProjectへ公開します。次にchat workflow init approve-greeting --project <team>/<project>でDraftを作り、次のworkflow.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を作ります。

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を受け付けません。

表の角括弧は任意引数を示すもので、入力しません。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しません。

上限と超過時の対応

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