multica/apps/docs/content/docs/tasks.ja.mdx

---
title: 実行タスク
description: エージェントの 1 回の実行がどのようにキューに入り、実行され、停止・リトライされるかを説明します。
---

import { Callout } from "fumadocs-ui/components/callout";

エージェントが作業を始めるたびに、Multica は**実行タスク**（task）を 1 件作成します。実行タスクには、この実行が何によってトリガーされ、どのエージェントに渡され、いまどこまで進んでいて、最終的に成功したかどうかが記録されます。

## イシューと実行タスク

イシューは 1 つの作業の目標、議論、担当者、最終ステータスを保持します。実行タスクは、その作業に対するエージェントの 1 回の実行を記録します。

| | イシュー | 実行タスク |
| --- | --- | --- |
| 記録する内容 | 継続的に進む 1 つの作業 | エージェントの 1 回の実行 |
| 続く期間 | 何度でも議論・追記・再割り当てできる | トリガーから、完了・失敗・キャンセルまで |
| 数の関係 | 1 つのイシューに複数の実行が積み重なる | 実行ごとに独立した記録が残る |

そのため、同じイシューを順番に別のエージェントへ渡すことも、失敗のあとにもう一度実行することもできます。実行のたびに新しいタスクが作成され、以前の記録が上書きされることはありません。

## トリガー元

次の操作はいずれも実行をトリガーできます。

- イシューをエージェントまたはスクワッドに割り当てる。
- コメントでエージェントをメンションする。
- チャットでエージェントにメッセージを送る。
- オートパイロットがスケジュールまたは外部イベントで発火する。

入口によって渡されるコンテキストは異なりますが、実行の仕組みは同じです。Multica がタスクを作成し、ランタイムがそれを取得して、エージェントに設定された AI コーディングツールを呼び出します。

## 実行の流れ

タスクは通常、次の状態を経ます。

| 状態 | 意味 |
| --- | --- |
| `deferred` | 後で発火するようスケジュール済み。指定時刻になるとキューに入る |
| `queued` | ランタイムによる取得を待っている |
| `dispatched` | ランタイムが取得し、AI コーディングツールを起動中 |
| `waiting_local_directory` | 対象のローカルディレクトリを別の実行が使用中で、ディレクトリロックの解放を待っている |
| `running` | AI コーディングツールが実行中 |
| `completed` | この実行は正常に終了した |
| `failed` | 実行がエラーになったか中断された |
| `cancelled` | 実行が手動で停止された |

ランタイムがオンラインなら、新しいタスクは通常すぐに始まります。キューに入ったあとでランタイムがオフラインになった場合、タスクは復帰までキューで待機します。2 時間を超えて取得されないタスクは失敗として終了します。

<Callout type="info">
トリガーの前の時点で対象ランタイムのオフラインが分かっている場合、一部の即時操作は、誰も取得できないタスクを作成する代わりに、いまは実行できない旨をその場で表示します。
</Callout>

ハートビートが正常なランタイムは長時間のタスクを実行できます。実行時間が長いという理由だけで、サーバーが実行を強制終了することはありません。プロセスが停滞しているかどうかは、ランタイムが実際のアクティビティに基づいて判断します。関連する設定は[環境変数](/environment-variables#デーモン設定)を参照してください。

## 実行履歴の確認

イシューを開くと、**実行ログ**でそのイシューが生んだすべてのタスクを確認できます。各行にはトリガー元、実行したエージェント、状態、時間が表示されます。

ここでは次の操作ができます。

- 実行記録を開き、エージェントのメッセージ、ツール呼び出し、エラー出力を確認する。
- 後で発火する予定・キュー待ち・起動中・ローカルディレクトリ待ち・実行中のタスクを停止する。
- 失敗またはキャンセルされたタスクをリトライする。

![実行記録: 状態のタイムライン、エージェントの要約、個々のツール呼び出し](/images/docs/task-transcript.png)

<Callout type="warning">
イシューの担当者やステータスを変更しても、すでに始まった実行は止まりません。中断したいときは、実行ログで該当する実行タスクを停止してください。アクティブなタスクがイシューと一緒にキャンセルされるのは、イシューを削除したときだけです。
</Callout>

## 失敗と自動リトライ

ランタイムの一時的なオフライン、デーモンの再起動、実行タイムアウト、AI コーディングツールのネットワーク中断といった一時的な障害は、自動リトライをトリガーできます。通常のタスクはデフォルトで最大 2 回まで、ツールのネットワーク中断は最大 3 回まで実行されます。

エージェント自身が返したエラーは、通常は自動リトライされません。認証の失効、クォータ不足、設定ミス、モデルがリクエストを完了できない場合などは、まず原因を解消してから手動でリトライしてください。

オートパイロットの**実行のみ**モードは、次のスケジュール実行と重ならないよう自動リトライしません。**イシューを作成**モードが生成するのは通常のイシュータスクなので、インフラ障害は上記のルールどおりリトライされます。どちらのモードも、最終結果はオートパイロットの実行履歴で確認できます。

イシュー上に他のアクティブなタスクがなく、実行を待つ新しいリトライもない場合、失敗によって `in_progress` のイシューは `todo` に戻ります。

## 失敗理由リファレンス

実行ログと使用量統計に表示される失敗理由は 2 つに分かれます。接頭辞のない理由コードはプラットフォームが記録するもの、`agent_error.*` は AI コーディングツール自身のエラーから分類されたものです。

**プラットフォーム側**

| 原因 | 意味 | 対処 |
| --- | --- | --- |
| `runtime_offline` | 実行中にランタイムがオフラインになった | ランタイムを復旧してからリトライ。[デーモンとランタイム](/daemon-runtimes)を参照 |
| `queued_expired` | ランタイムに取得されないまま 2 時間を超えてキューで待機した | ランタイムがオンラインであることを確認してからリトライ |
| `runtime_recovery` | デーモンが再起動後、中断された実行を回収した | そのままリトライ |
| `cancelled` | 手動で停止されたか、アーカイブ・削除に伴ってキャンセルされた | 対処不要 |
| `timeout` | デーモンに設定された実行時間の上限を超えた | イシューの範囲を狭めるか、デーモンの `agent_timeout` を調整する |
| `iteration_limit` | 実行の反復回数の上限に達した | イシューの範囲を狭める |
| `agent_blocked` | エージェントが続行できないと自ら報告した | エージェントがコメントで求めた情報を補う |
| `api_invalid_request` | プラットフォーム API が不正なリクエストを拒否した | リトライし、繰り返し発生する場合は問題を報告する |
| `codex_semantic_inactivity` | Codex が長時間有効な出力を出さず、停滞と判定された | リトライするか、Codex の停滞タイムアウトを調整する |

**ツール側（`agent_error.*`、接頭辞は省略）**

| 原因 | 意味 | 対処 |
| --- | --- | --- |
| `provider_auth_or_access` | モデルプロバイダーの認証に失敗したか、アクセス権がない（401/403） | その AI コーディングツールで再ログインするか、API キーを確認する |
| `provider_quota_limit` | クォータまたは残高を使い切った（402） | チャージするか、アカウントを切り替える |
| `provider_capacity_or_rate_limit` | レート制限または容量不足（429/529） | 時間をおいてリトライ |
| `provider_server_error` | モデルプロバイダー側のサーバーエラー（5xx） | 時間をおいてリトライ |
| `provider_network` | モデルプロバイダーへのネットワーク障害 | 自動でリトライされる。続く場合は実行マシンのネットワークを確認する |
| `model_not_found_or_unavailable` | モデルが存在しないか、現在利用できない | エージェント設定で利用可能なモデルを選び直す |
| `context_overflow` | コンテキストがモデルのウィンドウを超えた | イシューの範囲を狭めるか、入力を減らす |
| `missing_config` | API キーなどの必須設定が不足している | エージェントの環境変数またはツールの設定を補う |
| `runtime_missing_executable` | AI コーディングツールの実行ファイルが見つからない | ツールを再インストールする。[AI コーディングツールのインストール](/install-agent-runtime)を参照 |
| `runtime_version_unsupported` | AI コーディングツールのバージョンが古すぎる | ツールをアップグレードする |
| `process_failure` | ツールのプロセスが異常終了した | 実行記録で原因を特定してからリトライ |
| `empty_or_unparseable_output` | ツールが出力を返さなかったか、出力を解析できなかった | リトライし、繰り返す場合はツールのインストールを確認する |
| `agent_timeout` | ツールが長時間応答せず終了された | リトライするか、イシューの範囲を狭める |
| `unknown` | 分類できなかった失敗 | 実行記録の元のエラーを確認する |

## 手動リトライ

実行ログで行の再試行ボタンをクリックすると、**当時そのタスクを実行したエージェント**が再び呼び出されます。その後イシューの担当者が変わっていても、新しい担当者には切り替わりません。

リトライは、前回の実行がローカルディレクトリに書き込んだファイルをできる限り保持します。元のセッションがまだ安全で、同じランタイムが取得した場合は、前回のセッションも引き継ぎます。コンテキスト超過や不正なリクエストなど、セッションを汚染するエラーの場合は、元の作業ディレクトリの上で新しいセッションを開始します。元のディレクトリがすでに存在しない場合は、新しい作業ディレクトリを使います。

CLI から現在のイシューを再実行することもできます。

```bash
multica issue rerun <issue-id>
```

この方法は過去の特定のタスクを指さないため、イシューの現在のエージェント担当者を使い、新しいセッションと作業ディレクトリから開始します。

## 実行の完了とイシューの完了

`completed` は、この 1 回の実行が正常に終了したことだけを表し、イシューの目標が達成されたことを保証するものではありません。結果を確認し、議論を続け、要件を追加し、もう一度エージェントをトリガーできます。

イシューが完了したかどうかは、実際の作業の進み具合とイシューのステータスで判断してください。

## 状態とタイムアウトの早見表

以下の数値はサーバーのデフォルト設定に対応しており、トラブルシューティング時の照合に使えます。

| 状態 | 意味 | タイムアウトと結果 |
| --- | --- | --- |
| `deferred` | 後で発火するようスケジュール済み | 予定時刻になると `queued` に入り、以降は下のルールに従う |
| `queued` | ランタイムによる取得待ち | **2 時間**取得されないと失敗として終了し、自動リトライされない |
| `dispatched` | ランタイムが取得し、ツールを起動中 | **5 分**を超えてこの状態に留まると失敗として扱われる |
| `waiting_local_directory` | ローカルディレクトリロックの解放待ち | 独自のタイムアウトはなし。ディレクトリが解放されると起動フローに戻る |
| `running` | AI コーディングツールが実行中 | 固定の時間上限はなし。生存はランタイムのハートビート（15 秒ごと）で判定し、ハートビートを失ったランタイムは遅くとも約 3 分でオフラインと判定され、その上のタスクも失敗する |

自動リトライは以下の一時的な障害のみを対象とし、イシューまたはチャットに紐づくタスクにのみ適用されます（オートパイロットの**実行のみ**モードを除く）:

| 自動リトライされる失敗原因 | 実行回数の上限 |
| --- | --- |
| ランタイムのオフライン | デフォルト 2 回（初回実行 + リトライ 1 回） |
| デーモン再起動後の回収 | デフォルト 2 回 |
| プラットフォームが判定した実行タイムアウト | デフォルト 2 回 |
| Codex が長時間有効な出力を出さない | デフォルト 2 回 |
| スキルバンドルのダウンロード失敗 | デフォルト 2 回（この時点でエージェントのプロセスは未起動。ダウンロード済みのバンドルはローカルキャッシュから使われる） |
| ツールのネットワーク中断 | 最大 3 回。最後の 1 回は約 5 秒遅らせて開始 |

その他の失敗原因（認証、クォータ、設定、モデルなど）は自動リトライされません。先に原因を解消してから手動でリトライしてください。

## 次のステップ

- [デーモンとランタイム](/daemon-runtimes) — タスクがどのコンピュータで実行されるかを知る。
- [イシューをエージェントに割り当てる](/assigning-issues) — イシューから実行をトリガーする。
- [エージェントのメンション](/mentioning-agents) — コメントで要件を補足し、他のエージェントを参加させる。