Workflow — Draftから成果を得るまで

同じAgent作業、人間の判断、型付き成果の受け渡しを繰り返すときはWorkflowを使います。依存関係によって各Stepを開始できる順序が決まります。一度だけの依頼は通常のSessions、将来の時刻や文書条件で公開Workflowを開始するときはTriggerを使います。定義fieldの詳細・コマンド一覧・上限は定義リファレンスにあります。

始める前に

Workflowを実行する、またはProject所有のWorkflowを作成・公開・アーカイブするには、次が必要です。

• activeなProjectと、そのProjectのcollaboratorまたはadminの権限。viewerはWorkflowとRunを読めますが、作成・公開・実行・feedbackの記録はできません。
• Session Stepを担当する、Projectのactiveなcollaborator/adminのAgent。
• Session Stepの実行ownerの端末で動くaachat runtimeと、使うcoding-agent Runtimeの設定（セットアップ、Environment）。定義の検証に通っても、オフラインのruntimeが起動できるようにはなりません。

操作の窓口は二つあります。

• WebUI（人間）：Workflowの一覧・Draftファイルと依存関係図の閲覧、公開、実行、アーカイブと復元、Runの閲覧、Decisionへの回答、retryと停止、feedbackの記録、二つのRunの比較、Agentへの改善依頼ができます。既存のSession prompt・Decision bodyはWebUIで編集してDraftに保存できます。ファイルの作成やWorkflowの構造変更などはAgentに依頼します。
• chat workflowコマンド（Agent）：そのProjectへアクセスできる実行中のaachat Session内で使います。未認証の通常ターミナル向けではありません。以下の<team>/<project>、Agent名、返されたIDは実際の値に置き換えます。--projectにはProject slugだけも指定でき、省略するとcwdのProjectを使います。出力はすべて{"ok": true, "data": {...}}の形です。

変更時にはProjectと実行に関する権限がserverで再確認されます。

保存されるものの違い

Attemptでは、実行する正確なRevisionのBundleが$AA_WORKFLOW_DIRに読み取り専用で置かれます。担当Stepに必要なら読みますが、編集したりDraftへ上書きコピーしたりしません。Workflow AttemptのSessionには編集可能なDraftは配置されません。_publishedディレクトリはありません。公開済み定義はchat workflow listとshowで調べます。

WebUIで見つけて操作する

ProjectのWorkflowsページは1つの一覧で、Workflows/Runsのタブや状態filterはありません。各行には名前と1行の説明を表示します。公開済みでactiveなWorkflowだけにoutlineのRunボタンがあり、Activeのラベルは出しません。未公開・アーカイブ済みのWorkflowは下に薄く並び、Inactive · not publishedまたはInactive · archivedと表示します。Load moreで追加したページもこの順序で続きます。

Team・ProjectのWorkflow一覧では各項目のコピーボタンから、詳細ではタイトルのすぐ横のコピーボタンから、Workflowの投影パス（例: aachat/teams/team/projects/project/workflows/release）をコピーできます。閲覧専用・未公開・archive済みのWorkflowも対象です。Workflow詳細のheaderには名前、説明、主ボタンのRun、Copy pathとArchive（またはRestore）のメニューがあります。Draftに未公開の変更があるときは、1行の案内を表示します。Publishリンクは変更のないDraftにも表示され、子Workflowの現行公開版を明示的に取り込めます。公開には確認、検証済みのDraft、activeなProject、操作権限が必要です。既存Runは開始時のRevisionを使い続けます。

公開後、Workflows using a different versionに、公開時点で異なる子Revisionを固定していた同じownerの親WorkflowとStepが並びます。親リンクは別タブで開くため、元の一覧を残して複数の親を確認できます。親の現在のDraftを確認してPublishすると、Draftのすべての編集と子の現行公開版を公開します。Teamの公開結果に含まれるのはTeam所有の親だけです。対象がなければ案内は表示されず、再公開すると結果が置き換わります。既存RunのRevisionは変わりません。CLIではこの観測結果をstale_parent_stepsに返します。chat workflow publishには親のslugではなくBundle pathを渡します。

詳細には4つのタブがあります。

• Flow：Agentのアイコン付きのDraft依存関係図。Stepを選ぶと、その場で指示とRunの工程結果を読めます。ProjectのFlowではInput・Outputを選ぶとRunの入力・成果を表示し、配列は項目ごと、objectはキーと値の組で読めます。
• Runs：このWorkflowのRun履歴と比較の入口。**Select two runs to compare.**と案内します。
• Files：Draftファイルの内容と、対応するprompt/bodyの編集。Ask an agent to improveは選択したファイルの改善を依頼するSessionの下書きを準備します。viewerとアーカイブ済みWorkflowでは押せません。
• Triggers：有効なTriggerと、公開済みWorkflowを対象に作成するTrigger。

Project内でteam:<slug>として見えるTeamのWorkflowでは、公開とアーカイブはManage in Teamから移動した先のTeamのページで行います。

Projectの右側のWork Panelには、Runが0件でもSessionを開いていてもSessionsとWorkflow Runsのタブを表示します。Runの行は状態の印、Workflow名、Stepと状態の1行、時刻で構成し、開いているRunを選択状態にします。行を押すとRun詳細を開き、古いRunはLoad olderで読み込みます。Sessionがchat workflow runで開始したRunは、SessionsタブでもそのSessionの下に表示され、Run詳細へリンクします。

Teamで共有し、個別化するときだけ独立コピーする

Teamの人間memberは、Project未所属でもTeam sidebarのWorkflowsページでTeam所有のWorkflowを閲覧・公開・アーカイブできます。作成はAgentが行います。そのTeamのactiveなProjectでwrite authorityを持つAgentは、chat workflow init team:<slug>で作成できます。編集するDraftはaachat/teams/<team>/workflows/<slug>/で、Teamの全memberとTeamのProjectで働くAgentが読み書きできます。実行中のSessionにもDraftの変更が同期されます。このBundle pathを検証・公開すると、各Projectの一覧にteam:<slug>として現れます。実行先Projectから開始し、Run・Session・Ask・feedback・成果物はそのProjectに残ります。Team版を新しく公開すると、次の新規Runから使われます。

一つのProjectだけで個別化するときは、次の順で独立コピーします。

1. chat workflow init <slug> --project <team>/<project>を実行し、返るまで待ちます。
2. aachat/teams/<team>/projects/<project>/workflows/<slug>/内のスターターファイルを削除し、ディレクトリは残します。
3. cp -R aachat/teams/<team>/workflows/<x>/. aachat/teams/<team>/projects/<project>/workflows/<slug>/でTeam Bundleの中身をコピーします。
4. chat workflow validate aachat/teams/<team>/projects/<project>/workflows/<slug>で検証し、Projectのコピーを編集・公開します。

末尾の/.はフォルダ自体ではなく中身をコピーします。init前に置いたファイルは取り込まれません。コピーとTeam版にはリンクや自動同期がありません。Team Bundleでは子Workflowをteam:<slug>で参照し、promptや文書の対象Projectを固定しないことで、コピー後も同じ定義を使えます。Team Bundleのpromptにaachat/teams/<team>/projects/<project>/…のようなProjectのpathを書くと、検証でproject_path_not_available_here警告が出ます。

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

検証・公開・Draft Runは、どのStepも参照しない直下の入力宣言ごとにunused_workflow_input警告を返します。必須・任意とも対象ですが、公開を止めません。必要な箇所に参照を追加するか、不要な宣言を削除してください。例えばkeywordを担当に渡すには、使用するpromptに{{ inputs.keyword }}を書きます。descriptionや未参照fileに書くだけでは使用になりません。参照があっても、そのStepの実行や成果への反映は保証しません。

小さなWorkflowを作る

読者の名前を入力し、挨拶を返す例です。workspace rootで、使えるAgentと公開済みの名前を確認し、Draftを作ります。

chat project members <team>/<project> --runtime-profiles
chat workflow list --project <team>/<project>
chat workflow init greeting --project <team>/<project>

greetingが使われていれば別のslugを選びます。initはスターターのBundleが手元で編集可能になってから返ります（最大1分）。返らずにworkflow_bundle_not_readyになった場合は、応答に含まれる復旧コマンド（同じ--client-nonce付き）を再実行します。別のslugで作り直しません。

生成されたDraftのworkflow.yamlを次の内容に置き換え、writer.yournameを実際のmember名へ変更してください。

schema_version: 2
name: greeting
description: Write a greeting for one named reader.
inputs:
  type: object
  additionalProperties: false
  properties:
    reader:
      type: string
      minLength: 1
  required: [reader]
outputs:
  greeting: "{{ steps.write.outputs.greeting }}"
steps:
  write:
    needs: []
    session:
      agent: writer.yourname
      prompt:
        file: prompts/write.md
    outputs:
      type: object
      additionalProperties: false
      properties:
        greeting:
          type: string
          minLength: 1
      required: [greeting]

session.runtimeを省略すると、StepはそのAgentの既定のRuntimeと設定で起動します。特定のRuntimeやmodelが必要なStepだけ、runtime: {kind: codex-acp, config: {}}のように指定します。指定できる値は--runtime-profilesの結果で確認します（定義リファレンス）。

同じDraft内にprompts/write.mdを作ります。

Write one welcoming sentence for {{ inputs.reader }}.

作業turnを通常どおり終えると、全作業の終了後にWorkflowが完了指示を別turnで送ります。作業ファイルに {{ aachat.step_completion }} は書きません。不要になったstarterのファイルは削除できます。schemaは閉じたobjectなので、readerは必須で、定義していない入力キーは拒否されます。Stepはgreetingを返し、トップレベルの対応付けによってRun全体の成果としても取得できます。

検証、試行、公開

workspace rootから、Bundle pathを指定して検証し、必要に応じてDraftを試行します。

chat workflow validate aachat/teams/<team>/projects/<project>/workflows/greeting
chat workflow run --draft aachat/teams/<team>/projects/<project>/workflows/greeting --stdin <<'JSON'
{"reader":"Alex"}
JSON

検証はserverへ問い合わせ、ProjectのAgent、Runtime設定、子Workflowがある場合は現在の公開Revisionの固定を確認します。オフラインのYAML検査ではありません。成功するとvalid: trueが返ります。エラーが指すfieldやfileを修正してください。warningsのproject_path_not_available_hereは、Step promptが別Projectのaachat/teams/<team>/projects/<project>/…を指していることを示す警告で、処理は止まりません。Step Sessionが作業できるのはWorkflowのProjectだけなので、その内容はBundle内に置いて$AA_WORKFLOW_DIRから読むか、Run入力で渡します。

Draft Runも実際のAgent作業を開始するため、適切な入力で実行し、返されたRun IDをstatusで確認してから進みます。Draft Runの成功は有用な証拠ですが、公開の必須条件ではありません。publishとrun --draftは、手元の最新の編集がserverのDraftへ同期されるまで最大60秒待ってから送信します。

Draftを公開し、入力と出力の契約を確認してから公開版を開始します。WebUIのPublishでも同じ公開ができます。

chat workflow publish aachat/teams/<team>/projects/<project>/workflows/greeting
chat workflow show greeting --project <team>/<project>

公開はファイルのsnapshotを保存し、Publishedの参照先を更新します。Draftのファイルは変わりません。showでは公開Revisionの入力・出力に加え、stepsのkey・kind・needsを読みます。Session Stepのagent_nameと、指定していればruntime_kind（省略したStepにはなく、Agentの既定を使います）、子Workflowのworkflow_slugと、このRevisionが固定しているworkflow_revision_idも確認してください。子slugにshowを実行し、そのtop-levelのrevision_idと比べます。等しければ親は子の現行公開版を実行し、異なれば親は古い版を固定したままです。stepsはstep keyの辞書です。Revisionが実行する並びはtopological_orderのkey順で、独立Stepの直列実行を保証しません。showはRunを開始せず、prompt本文・secret・子Workflow内部の全Stepを表示するものでもありません。確認してから公開版を開始します。

chat workflow run greeting --project <team>/<project> --stdin --wait <<'JSON'
{"reader":"Alex"}
JSON

runの応答はaccepted: trueとrun、available_actions、createdを含みます。--waitはRunを開始し、依頼元Sessionへの永続的な通知待ちを登録します。コマンド自体はすぐ返ります。受付後は依頼元Agentのturnを終え、pollせず継続通知後に結果を読みます。--waitはWorkflow AttemptのSession内では使えません。

今回のRunの実行先

今回のRunだけ実行先を選ぶには、公開版・Draftの起動に--runtime claude-acpまたは--runtime codex-acpを付けます。WebのRunダイアログでもRuntime for this runからUse workflow settings（既定）、Claude Code、Codexを選べます。指定は全Session Step・retry・Workflow Stepの子Runに適用し、独立して起動したRunには継承しません。Workflow定義やAgent既定は変更しません。実行先が変わるStepはSession受理時の指定先Agent既定を使い、同じ実行先のStep設定は維持します。Run詳細、CLIのreceipt・一覧・statusで保存されたruntime_override、Attemptのrequested settingsで解決結果を確認できます。

開始したSessionの起動状況

Runの作成時、serverは最初に開始したStep Sessionの起動を最大40秒待ち、startups[]としてrun_id・step_key・session_id・startupを返します。startup.stateの意味は次のとおりです。

応答が失われたときの再実行

通信が切れたりoperation_outcome_unknownになったりした場合は、同じchat workflow runコマンドをそのまま再実行します。--client-nonceを省略すると、Session・Project・Workflow・入力・runtimeから要求の識別子が決まるため、すでに開始したRunが返り、created: falseになります。同じ入力で意図的に別のRunを開始するときだけ、新しいUUIDを--client-nonceに渡します。--draftの場合、同期によってDraftのbaselineが進んだ後の再実行は新しいRunになるので、先にchat workflow runs <slug>で既存Runを確認します。公開版Runのエラーに含まれる復旧コマンドは--project <team>/<project>と同じ--client-nonceと指定した--runtime付きで、Session内ならどのcwdからでも使えます。

run --draftは、手元のbaselineが古くても、Bundle全体が現在のDraftと一致すれば受け付けます（ファイルの順序の違いは許容）。内容が異なる、未来のversionを指す、アーカイブ・復元より前のbaselineである場合は競合として拒否されます。

Runの結果を確認する

chat workflow status <run-id> --project <team>/<project>
chat workflow runs greeting --project <team>/<project>

成功した例のRunでは、outputsとして{"greeting":"Welcome, Alex!"}のような値が返ります。文章は生成されるため、この一文との完全一致は保証されません。成功前はoutputsがありません。トップレベルの出力宣言がなければ成功後の値は{}です。Runの状態と、実際の成果やリンク先の内容の両方を確認します。runsの各項目にはそのRunのinputと成功後のoutputsが含まれますが、自由記述の文字列は100文字のpreviewに切り詰められ、truncated: trueが付きます。全文は各項目のdetail_readが示すstatusで読みます。

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はそのまま扱い、観測の欠損を要求値で補完しません。

WebUIから実行する

WorkflowのheaderにあるRunを押すと、Run <名前>ダイアログが開きます。公開済みの最新Revisionを実行し、未公開のDraft変更は含みません。入力欄は公開版の入力schemaから作られます。トップレベルの入力がすべて文字列・数値・整数・boolean（列挙値を含む）ならfieldごとのフォーム、objectやarrayの入力が1つでもあれば入力全体を1つのJSON objectとして入力します。Run workflowで送信し、受け付けられるとRun詳細へ移動します。

次の場合はRunを押せないか、理由が表示されます。

通信結果が不明になると、ボタンがRetry requestに変わります。同じ入力と同じ要求識別子で再送するため、Runが重複しません。作成済みのRunが確認できた場合はRun accepted. Open its details to check progress.と表示してそのRunを開きます。

Session Stepを完了する

Agentは挨拶を作成して作業turnを通常どおり終え、Workflowから別turnで届く完了指示に従って値を提出します。follow-upがあれば、同じSessionですべて実行してから完了指示が届きます。

chat workflow complete --stdin <<'JSON'
{"outcome":"succeeded","outputs":{"greeting":"Welcome, Alex!"}}
JSON

完了できない場合は、原因と次に必要な操作を送ります。errorは空でなく4 KiB以下にします。

chat workflow complete --stdin <<'JSON'
{"outcome":"failed","error":"Required source is unavailable; restore access before retrying."}
JSON

完了意思の受理を確認できるのは、コマンドのJSON応答に"accepted": trueがあるときだけです。timeout、ターミナルへの入力表示、最後のチャット応答では受理を確認できません。通信エラーなら、同じ非対話形式でまったく同じJSON payloadを再送できます。受理されたら新しい作業を始めず、現在の応答を通常どおり終えます。受理はRun全体の成功を意味しません。chat session finishで代替しないでください。

Session Stepの途中で予定外の人間判断が必要になった場合は、Project Askを作り、chat wait --all --ask <ask-id> --project <team>/<project>で登録し、Stepを完了せずturnを終えます。Stepはwaiting_for_decisionと表示されます。回答または取消の後、同じSessionが1回だけ続きます。chat ask show <team>/<project> <ask-id>を読み、結果を踏まえて現在の作業を続けます。successは最後の完了指示が届いてから提出します。Workflow Stepは、自身が作ったProject Askと、同じAgent・所属Projectの直接の子通常Sessionを待てます。Run、他Step、別Agent・別所属ProjectのSessionは待てません。未解決groupは一つまでです。子だけが未解決ならrunning、Askが未解決ならwaiting_for_decisionです。結果を確認して元Stepが現在のtaskと残りのtaskを進め、最後の完了指示に従って完了します。完了指示の中で待機した場合は、受領済みの指示で提出します。

schema 2/3でchat session finishを使うとworkflow_session_managedになります。再送せず現在のturnを通常どおり終えてください。作業間やAsk待ちのidleでもSessionは閉じません。中断はStopまたはRun取消を使います。完了指示より前のsuccess提出はworkflow_completion_not_readyで拒否され、failedは作業中も提出できます。

完了報告の受理は終了予約です。そのturnの後にAsset Wrap-Upが成果を整理・保存し、最終同期とRuntime終了確認後にSessionがterminalになります。その後にStep結果が確定し、下流が開始できます。Wrap-Upは受理済みoutputsを変えません。受理済み成功と、その後のWrap-Up失敗は別の事実として確認します。未提出のまま完了turnが終わると、Wrap-Upを経てcompletion_missingになります。Step retryは新Attempt・新Sessionの初回作業から始めます。

同じSessionへの作業追加には順序付きsession.follow_upsを使います（定義リファレンス）。旧schema 1 Runは履歴閲覧専用です。再実行は移行後のschema 2/3 Workflowから新Runを開始してください。

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

人間の判断と子Workflow

計画済みのDecision Stepは、Runを開始した人間、または開始したAgentの人間ownerへProject Askを作ります。Decision定義にはassignee fieldはありません。Run詳細のAskカード、またはProjectのAsk画面で回答してください。Runは回答revisionを固定し、{"answer": "..."}という出力として使います。後からAskの回答を編集しても、この出力は変わりません。waiting_for_decisionは途中の状態で、失敗ではありません。これは業務の判断であり、coding Runtimeがツール操作の許可を求めることとは異なります。回答は後続Stepへ渡すデータです。分岐には以下のように明示的なwhenが必要で、回答がdeploy権限を与えることはありません。

Workflow Stepは公開Workflowを呼べます。同じ所有者のWorkflowは<slug>、TeamのWorkflowはteam:<slug>で指します。子のRevisionが固定され、合成は1段だけです。Decisionと子Workflowの具体例、型付き入力の対応付け、上限は定義リファレンスを参照してください。

分岐を選び、成果を合流する

作成するメモを尋ね、1つの枝で作業し、joinの要約を公開出力にする例です。公開やdeployの操作は行いません。greetingと同様にProjectメンバーを調べ、chat workflow init choose-note --project <team>/<project>を実行します（使用済みなら別slugを選択）。Draftのworkflow.yamlを次で置き換え、3か所のwriter.yournameを実際のメンバーへ置き換えてください。

schema_version: 2
name: choose-note
description: Choose a note, then summarize the branch result.
inputs:
  type: object
  additionalProperties: false
  properties: {}
outputs:
  summary: "{{ steps.summary.outputs.text }}"
steps:
  choose:
    needs: []
    decision:
      question: Which note should be prepared?
      body: { file: prompts/choose.md }
      options: [Draft, Hold]
  draft:
    needs: [choose]
    when:
      value: "{{ steps.choose.outputs.answer }}"
      equals: Draft
    session:
      agent: writer.yourname
      prompt: { file: prompts/draft.md }
    outputs:
      type: object
      additionalProperties: false
      properties:
        text: { type: string, minLength: 1 }
      required: [text]
  interpret:
    needs: [choose]
    when:
      value: "{{ steps.choose.outputs.answer }}"
      otherwise: true
    session:
      agent: writer.yourname
      prompt: { file: prompts/interpret.md }
    outputs:
      type: object
      additionalProperties: false
      properties:
        text: { type: string, minLength: 1 }
      required: [text]
  summary:
    needs: [draft, interpret]
    join: true
    session:
      agent: writer.yourname
      prompt: { file: prompts/summary.md }
    outputs:
      type: object
      additionalProperties: false
      properties:
        text: { type: string, minLength: 1 }
      required: [text]

同じDraftにprompts/choose.mdを作ります。

Choose Draft for a short planning note, or Hold to record that work is on hold.
You may also describe your conditions in your own words.

同じDraftにprompts/draft.mdを作ります。

Return a short planning note in text. Do not publish or deploy anything.

同じDraftにprompts/interpret.mdを作ります。

The human answered: {{ steps.choose.outputs.answer }}
Return a note in text preserving the answer and any conditions. Do not infer
approval or carry out the requested work. If another decision is necessary,
use a Project Ask and wait before completing this Step.

同じDraftにprompts/summary.mdを作ります。

Read the attached Workflow dependency results. Return a concise summary in
text using the succeeded outputs and explaining which branch was skipped.
Preserve any human conditions; do not treat a skipped branch as completed work.
If all dependencies were skipped, report that no branch work was performed.

検証し、必要なら空の入力objectでDraftを試行します。

chat workflow validate aachat/teams/<team>/projects/<project>/workflows/choose-note
chat workflow run --draft aachat/teams/<team>/projects/<project>/workflows/choose-note --stdin <<'JSON'
{}
JSON

返されたRunをWebUIで開き、Askに回答します。Draftとの完全一致ではdraftが動き、interpretはskipします。Holdまたは自由回答ではinterpretが動き、draftはskipします。Draft, after reviewは自由回答で、Draftの枝への承認とは扱いません。後からAskを編集しても、このRunで採用した回答は変わりません。interpretが追加判断を必要とする場合は、上のAsk/wait手順を使ってから完了します。

選ばれた枝が成功すると、summaryがその受理済み出力と、もう一方のskip理由を読みます。実行する各Sessionは生成された指示に従い、自身のschemaに合うcompletionを送ります。例えばsummary Attemptは、実際の結果に合う場合だけ{"outcome":"succeeded","outputs":{"text":"Work is on hold; the draft branch was skipped."}}を送れます。accepted: trueはそのStepのcompletion受理であり、Run全体の成功ではありません。

chat workflow status <run-id> --project <team>/<project>でRunのsucceededとoutputs.summaryの存在、期待する成果の内容を確認します。outputs不在は、空の成果で成功したという意味ではありません。次へ渡す前に、進行中Step・completion受理・output_errorを確認してください。子Workflowがある場合は親も確認します。子の成功だけでは親の出力受理を証明できません。試行後は先の手順のslugをchoose-note、入力を{}としてpublishと公開版Runへ進めます。

このDecision例では、回答後に必ず2枝の一方を選びます。boolean/enumの条件では、未被覆値によって全枝skipになる場合があります。その場合もjoinは動き、枝の作業がなかったことを報告します。通常の下流Stepならskipします。skipした作業を実施済みに数えたり、枝を強制するためにretryしたりしません。意図した選択と違えばDraftまたは入力を直し、新しいRunを使います。

Runを読み、復旧する

Run詳細の読み方

WebUIではWorkflow詳細のRunsタブまたはWork PanelからRunを開きます。ページは縦に並びます。

1. 戻るリンク、Run · 日時、起動元。メニューにはRun detailsと、取消可能な実行中RunのStop run…、終了後には利用可能なRun againとCompareがあります。停止の確認見出しと実行ボタンはどちらも**Stop this run?**です。子Runの操作は親Runへ案内します。
2. 進行状況の1文と、固定されたRevisionのInput → Step → Result依存関係図。ノードにはAgentのアイコンと状態の印を付け、未開始Stepは薄く表示します。線は依存関係で、実際に通った経路ではありません。開いたときは待機中または失敗したStep、終了したRunならResultを選びます。URLで明示された選択は復元します。
3. 図の下に選択した内容。Resultには出力値と出力元Stepを表示します。StepにはOpen session、Retry step、Askへの回答など主操作を1つ置きます。再試行したStepだけ、過去のAttemptを読むTry N of Mの選択欄があります。
4. StepのOutputとInstructionsタブ。Instructionsでは描画済みのInitial、Follow-up、Completion instructionsを順番に全文表示し、Sessionへの提出時刻を添えます。時刻はSessionへの永続的な提出を表し、Runtimeが読んだことの確認ではありません。未送信はNot sent yet、過去の時刻が不明なら推測して表示しません。下部にruntime/modelとEdit in workflowがあります。Messagesタブはなく、会話はOpen sessionで読みます。Open sessionはRun詳細とStepの選択を保ったまま、右のパネルにSessionを開きます。
5. Feedbackはタブの下に常に表示します。説明、既存のメモ、複数行の入力、Save feedbackがあり、タブを切り替えても隠れません。

Decision StepではAskカードをそのまま表示し、Open in Asksを置きます。回答を採用した後はUsed by this run · answer Nと表示します。Open …は別画面へ移動し、Go to …は同じ画面の選択を切り替えます。StepのSessionにはWorkflow名 › Step名とBack to runがあり、Needs replyのときだけ**The step finishes when the agent reports its result.**と案内します。

画面の状態名はWorking、Needs reply、Needs answer、Done、Failed、Not started、Skipped、Cancelledです。WorkingはSessionと同じ動く線、待機はtealの点、Doneはピンクのチェック、Failedは赤い印で表し、ラベル・背景・枠はneutralにします。Needs replyは未読かどうかに関係なく、実行中StepのSessionにactiveまたはreserved turnがないことから判定します。以下のCLIの状態名は変更しません。

CLIではchat workflow status <run-id>が全Stepの要約とavailable_actionsを返します。status --detailは定義・入力・prompt・起動情報・feedback本文を含む完全な記録を返します。過去のAttemptはchat workflow attempts <run-id> --step <key>、1つのAttemptの描画済みprompt・完了意思・feedbackはchat workflow attempt <attempt-id>で読みます。available_actionsは表示時の状態と権限に基づく操作候補で、実行時にも再確認されます。

Runの状態

Runにfailedという状態はありません。Stepの状態はpending、blocked、starting、running、waiting_for_decision、attention_required、succeeded、failed、cancelled、skippedです。chat workflow runs --state <state>でRun全体の状態が一致するRunだけを読めます。最初のpageでitems: []かつnext_page: nullなら、該当Runはありません。

状態別の次の操作

停止確認の Reason (optional)、または両CLIの --reason で任意の理由を残せます。未入力でも停止できます。前後の空白を除いたUTF-8で2,000 bytesまで保存され、初回取消後は変更されません。理由は Run details → Stop reason、Run statusの cancellation_reason、既存waitの完了通知から読めます。理由の記載は再実行の承認にはなりません。

複数のRunを待つ、成果を次へ渡す

複数のroot Runの結果を一緒に判断する場合は、それぞれに--waitを付けず開始し、1つの待機へ明示登録します。

chat wait --all --workflow <first-run-id> --workflow <second-run-id> --project <team>/<project>

子Runは親が所有するため待機対象にできません。継続後は通知のRead:コマンドで各結果を確認します。決着にはattentionや取消も含まれ、待機完了は成功を保証しません。

成功した成果を次のWorkflowへ渡すには、両方のschemaを読み、次の閉じた入力objectが受け付けるキーだけ選びます。greetingを入力として宣言するsave-greetingというWorkflowがある場合は、次のように渡せます。

chat workflow status <run-id> --project <team>/<project> | jq '.data.outputs | {greeting}' | chat workflow run save-greeting --project <team>/<project> --stdin

Runがsucceededでoutputsがあることを確認した後だけ実行してください。失敗したstatusをそのまま次のRunへ流しません。大きな成果はShared DocumentsやMediaへ保存し、短い参照を返します。completionとRun outputsの上限は128 KiB、JSONの深さは32です。workflow_completion_limit_exceededなら出力を小さくし、修正した新しいRunで実行します。過去の成功Runでは、大きすぎるoutputsの代わりにoutput_errorが返る場合があります。

二つのRunを比べる

同じProject・同じWorkflowの異なる二つのRunで、入力・結果・feedbackを並べて読めます。品質を採点したり、原因を推定したりする機能ではありません。

WebUIでは、WorkflowのRuns一覧でちょうど二つのRunのチェックボックスを選び、Compare runsを押します。比較画面は次のとおりです。

• Run AとRun B：それぞれの状態、Draft/公開、読み取った時刻。Revisionが異なればDifferent revisionsと表示します。
• Inputs（Same inputs / Different inputs）、Final results、Step keyごとのタブ。Stepは完全に同じkeyで対応付け、改名は推測しません。Stepの種類が変わっていればStep type changedと表示します。
• Stepタブでは、各Runの最新Attemptと全feedbackを表示します。feedbackごとのInclude in requestで、改善依頼に添える証拠を選べます。
• 二つのRunは別々に読み取ったsnapshotで、自動更新しません。retryや新しいfeedbackを見るにはRefresh comparisonを押します。Close comparisonで左側のRun詳細へ戻ります。

CLIでは完全なRun UUIDを二つ指定します。

chat workflow compare <left-run-id> <right-run-id> --project <team>/<project> [--step <key>] [--detail]

Definition changesで各Runに固定された指示ファイルと実行用定義の差分を確認できます。Stepを選ぶと指示差分の直下から結果・Attempt・feedbackへ辿れます。Same inputs / Different inputsで入力条件も確かめてください。公開・試行とも実行時の版を読み、現在のDraftや公開版で補いません。左右の全文を表示・コピーでき、空ファイルと不在も区別します。CLIの既定出力は変更概要、--detailは固定定義・Bundleと左右の全文を含みます。変更と結果の関係を調べる根拠であり、改善効果の自動判定ではありません。

既定は入力の同異、対応するStepの状態、feedback件数の要約です。--detailは入力・結果・全feedbackとAttemptの読取コマンドを含みます。入力のobjectのkey順は無視し、配列の順序・型・値・keyの欠落は区別します。全feedbackの読み取りには上限がなく、--stepを付けても通信量は減りません。比較はSessionの開始・公開・実行・Draftの変更を行いません。

次のRevisionを改善する

prompt、入力、出力schema、Agent割当が具体的な問題を起こしたら、Attemptにfeedbackを残します。feedbackはRunの実行を変えない観察メモです。記録しても再実行は始まらず、promptも変わりません。

WebUIでは、Run詳細のResultまたはStepのタブの下にあるFeedback欄に、対象のStepとAttempt（例：write · Attempt 1）と既存のメモが常に表示されます。入力してSave feedbackを押すとFeedback saved.と表示されます。保存に失敗するとFeedback could not be saved. Check the Step and retry.と表示され、入力は残ります。まだ開始していないStepやskipしたStepには記録できません。collaborator/admin以外にはOnly project collaborators can add feedback.と表示されます。

CLIでは、現在のAttemptのSessionからchat workflow feedback --stdin、それ以外からはRun IDとStepを指定します。--attempt Nで試行番号を指定でき、省略すると最新のAttemptに記録します。現在のAttemptのSessionでは--attemptを使えません。

chat workflow feedback <run-id> --step write --project <team>/<project> --stdin <<'TEXT'
The prompt did not specify the reader's language. Add a language input before the next revision.
TEXT

本文は前後の空白を除いて空でない8,192 bytes以下のplain textです。架空の点数を付けません。statusはStepごとのfeedback_countを示し、本文はstatus --detailやattempt <attempt-id>で読みます。

WebUIのAsk an agent to improveは、改善を依頼する新しいSessionの下書きを準備し、Session入力欄へ移動します。Workflowのファイル表示から押すとProject・Draft path・Workflow slugが入り、比較画面から押すと二つのRun・Revision・読取時刻・選んだfeedback・比較の読取コマンドも入ります。すでに別の下書きがあれば**Replace the current session draft?**が表示されます。Keep my draftで既存の下書きを残し、Replace draftで置き換えます。準備されたpromptを確認し、AgentとRuntimeを選んで送信すると改善Sessionが始まります。下書きの準備はSession起動の受付ではありません。改善依頼は公開、Runの開始、Agent assetの変更を含みません。起動したSessionを開いて編集を追い、Draftを検証し、必要なら試行して次のRevisionを公開します。既存Runは固定済みRevisionを使い続けます。

画面で本文の文言を直す

Workflow詳細のFilesタブでSessionのprompt・Decisionの説明本文を開き、Editから編集できます。MarkdownはPreviewで確認し、Save draftで保存します。共有ファイルには参照するStepが表示され、変更は全参照先で使われます。README・構造ファイル・Decisionの質問と選択肢はこの編集の対象外です。ProjectからTeam Workflowを開いた場合は、Manage in Teamで同じファイルを共有元で編集します。

未保存中はPublish・Run開始・Agentへの改善依頼が止まり、移動やCancelでは破棄を確認します。保存中は入力・Cancel・Stepとファイルの切替もできません。競合したら文をコピーしてReload latestで最新Draftを取得し、破棄を確認してからやり直します。通信失敗では入力が残り、保存結果が不明ならCheck save resultで再確認できます。自動再送は行いません。

保存後にPublishを押すと以後の新規Runに反映されます。Draft保存だけでは公開版や既存Runは変わりません。

アーカイブと復元

Workflow詳細のメニューからArchiveを選ぶと、新しいRunの起動を止められます。一覧にはInactive · archivedとして残ります。確認画面には、一時停止するTrigger、継続するRun、アーカイブを妨げる公開中の親Workflowを表示します。親があれば、その親を更新して公開し直すか、先にアーカイブします。Draft、公開Revision、実行履歴は保持され、既存Runの後続Step・完了・再試行・キャンセルは引き続きできます。

一覧のInactive · archivedの行を開き、Restoreで同じWorkflowを復元できます。参照する子Workflowがアーカイブ済みの場合は、先に子を復元してください。復元してもTriggerは再開しません（Workflow restored. Paused Triggers remain paused.）。Triggersで入力とスケジュールを確認してから個別に再開します。完全削除とslugの再利用は提供しません。

Project所有のWorkflowにはchat workflow archive <slug> --project <team>/<project>とchat workflow restore <slug> --project <team>/<project>を使います。Team所有にはchat workflow archive team:<slug>とchat workflow restore team:<slug>を使います。Team形式に付ける任意の--project <team>/<project>は同一Teamであることの確認だけに使われ、ownerを切り替えません。--previewを付けると変更せず影響を確認でき、応答のworkflow.lifecycle_versionとconfirmation_tokenを--expected-lifecycle-version <N> --confirmation-token <token>に渡すと、確認した内容のまま適用します。確認後に状態が変わっていれば拒否されるので、previewからやり直します。TeamのWorkflowをアーカイブすると、各ProjectのTriggerも一時停止し、復元後はそれぞれのProjectで再開します。

chat workflow list --archived --project <team>/<project>は未公開Draftも含めてアーカイブ済みWorkflowを表示します。アーカイブ中もDraftは同じpathに残りますが、編集・公開・新規Runはserverに拒否されます。ファイルを変更する前に復元してください。アーカイブと復元はそれ以前のDraft baselineを無効にします。復元後は最新ファイルを取得し、手元に残った編集を確認して保存し直してから公開してください。手元のディレクトリを削除しても、Workflowのアーカイブや削除にはなりません。