Skip to content
Guides2 min read

マルチエージェントの失敗をデバッグする：ウォークスルー

Potato を使ってマルチエージェント LLM システムが失敗した理由を見つける方法：相互作用グラフ、失敗の帰属、引き継ぎレビュー、エージェント別スコアカード、ツール競合タイムライン、創発的振る舞いのタグ付け。

Potato Team

エージェントのチームが失敗したとき、難しいのは失敗に気づくことではなく、どのエージェントが、どのステップでそれを引き起こしたのか、そして本当の問題は、それぞれ単体では問題のなかった 2 つのエージェント間の不適切な引き継ぎだったのかを見つけることです。このウォークスルーは、そのために作られた 6 つの Potato サーフェスを、壊れた実行に対して実際に使う順序で順に説明します。 ここで扱うすべては YAML で設定され、自分のサーバー上で動作します。完全なスキーマリファレンスは マルチエージェントチーム評価 です。

マルチエージェントシステム とは、明確な役割を持つ複数の LLM エージェント（プランナー、コーダー、レビュアー）が、メッセージをやり取りし制御を引き継ぐものです。これらのシステムが壊れる理由に関する研究、MAST タクソノミー（Why Do Multi-Agent LLM Systems Fail?）は、失敗の大半がエージェント間のものであることを見出しました：引き継ぎで落とされた制約、自らの作業を一度も検証しないチーム、互いにすれ違って話すエージェントです。フラットなチャットのトランスクリプトは、まさにそれらを隠します。なぜなら、うまくいかなかったものは、いずれか一方のメッセージの内部ではなく、2 つのメッセージの間の空間に存在するからです。

マルチエージェントの実行が実際にどこで失敗するか：相互作用グラフと帰属の三つ組失敗はエージェント間、引き継ぎの場面にあり、1 つのトランスクリプトの内部にはない

マルチエージェントの実行の構造を見るには？

テキストではなく、実行の形から始めます。agent_interaction_graph スキーマは、実行全体を有向グラフとして描画します：ノードはエージェント、エッジはそれらの間の引き継ぎで、太いエッジほどトラフィックが多いことを意味します。ノードをクリックしてクリティカルパス上にマークし、エッジをクリックして、通常からクリティカル、問題ありへと切り替えます。

クリティカルパスとフラグの立った引き継ぎを伴うクリック可能なエージェント相互作用グラフクリティカルパスをマークし、問題のある引き継ぎにフラグを立てる

yaml
annotation_schemes:
  - annotation_type: agent_interaction_graph
    name: graph
    description: "Mark the critical path and flag any problematic handoffs."
    steps_key: steps
    agent_key: agent

グラフはトレースから自動的にレイアウトされるため、何も描く必要はありません。すべてのノードとエッジはキーボードでフォーカス可能で、テキスト要約がクリティカルなノードとフラグの立ったエッジを列挙するため、意味が色だけに依存することはありません。このビューは、「何が何と話し、どこで経路が逸れたのか」に答える最も速い方法です。

マルチエージェントの失敗を 1 つのエージェントに帰属させるには？

実行が見えるようになったら、失敗を絞り込みます。failure_attribution スキーマは、失敗帰属の文献（Zhang ら、Which Agent Causes Task Failures and When?、ICML 2025、Who&When データセット）に由来する三つ組を求めます：責任を負うエージェント、決定的なステップ、理由です。エージェントのドロップダウンとステップのピッカーはトレース自身のターンから生成されるため、実際に起きたエージェントとステップにのみ失敗を帰属させることができます。

マルチエージェントの失敗を、エージェント、ステップ、理由に帰属させる失敗を、責任を負うエージェント、決定的なステップ、理由に帰属させる

yaml
annotation_schemes:
  - annotation_type: radio
    name: outcome
    description: "Did the system succeed?"
    labels: [success, failure]
  - annotation_type: failure_attribution
    name: attribution
    description: "If it failed: which agent, which step, and why?"
    steps_key: steps
    agent_key: agent

帰属を成功／失敗のラジオボタンと組み合わせると、三つ組は失敗した実行でのみ収集されるため、注釈者の時間はシグナルを持つケースに集中します。

引き継ぎそのものはどうか？

帰属は 1 つの決定的なステップを名指しします。引き継ぎレビューは、あらゆる制御の移譲を見ます。連続するターンの間で行動するエージェントが変わるところでは必ず、Potato が引き継ぎカード A → B を出力します。そして、そのパスで何が間違ったか（情報の損失、落とされた制約、文章の崩れ、目標のドリフト）にフラグを立て、品質を評価します。失敗モードは MAST のエージェント間カテゴリと「エコーイング」現象（Zhang ら、2025）に由来します。

不整合フラグと品質評価を伴う引き継ぎカードあらゆる引き継ぎでエージェント間の不整合にフラグを立て、品質を評価する

yaml
annotation_schemes:
  - annotation_type: handoff_review
    name: handoffs
    description: "For each handoff: flag any misalignment and rate the quality."
    steps_key: steps
    agent_key: agent
    flags: [info_loss, dropped_constraint, garbling, goal_drift]
    quality_scale: 5

引き継ぎはレンダリング時に導出されるため、手動のセットアップは不要です。「各エージェントは問題なく見えたのに、チームは失敗した」というケースが解決するのは、たいていここです：制約はエージェント A では生きていたのに、エージェント B では失われていたのです。

エージェントとチームをスコアリングするには？

失敗は、一度何が壊れたかを教えてくれます。スコアカードは、ある設計が多数の実行にわたって良いかどうかを教えてくれます。agent_scorecard スキーマは 2 つのレベルを同時にスコアリングします（MultiAgentBench、Zhou ら、ACL 2025）：各エージェントを役割忠実度、貢献、協調で、チームをそれ自身の共有次元で、オプションのマイルストーンとともにスコアリングします。エージェントの行はトレースから来るため、マトリクスは実際に参加した者と一致します。

マイルストーンを伴うエージェント別・チーム別のスコアカード各エージェントを役割忠実度、貢献、協調でスコアリングし、加えてチームも

yaml
annotation_schemes:
  - annotation_type: agent_scorecard
    name: scorecard
    description: "Score each agent, the team, and which milestones were reached."
    steps_key: steps
    agent_key: agent
    scale: 5
    agent_dimensions: [role fidelity, contribution, coordination]
    team_dimensions: [coordination, communication, efficiency]
    milestones: [plan produced, task delegated correctly, result verified]

協調の悪いチームの中で行き詰まった優秀なエージェントは、ここでは低いチーム次元の隣にある高いエージェントの行として現れます。これは、同じタスク上で逐次型、階層型、グループチャット型のオーケストレーションを比較しているときに欲しいパターンです。

並行性と集合的な失敗はどうか？

さらに 2 つのサーフェスが、ターンごとの読みでは捉えられない失敗を捕まえます。tool_contention タイムラインは、各エージェントを独自のレーンに配置し、2 つの呼び出しが重なる時間帯に同じリソースに触れる領域をハイライトします。これを、デッドロック、循環待機、競合状態、または無害として分類します（DPBench、2026）。

ハイライトされた競合領域を伴うエージェント別ツール呼び出しタイムラインエージェント別のツール呼び出しタイムライン上でデッドロックや競合状態を見つける

そして emergent_behavior は、1 つのステップに位置するのではなく集合的な失敗を扱います。結託、グループシンク、連鎖的なエラー、役割のドリフトです。創発的振る舞いは連続したスパンではなく、参加するターンの集合であり、異なるエージェントから来ることもあるため、参加するターンをチェックし、メモを追加します。

エージェントをまたぐ一連のターンを連鎖的なエラーとしてタグ付けするエージェントとターンをまたぐ結託、グループシンク、連鎖的なエラーをタグ付けする

yaml
annotation_schemes:
  - annotation_type: tool_contention
    name: contention
    description: "Classify each shared-resource contention region."
    calls_key: calls
    agent_key: agent
    resource_key: resource
    contention_labels: [deadlock, circular_wait, race_condition, benign]
  - annotation_type: emergent_behavior
    name: emergent
    description: "For each collective behavior, check the turns that participate."
    steps_key: steps
    agent_key: agent
    behaviors: [collusion, groupthink, cascading_error, role_drift]
    allow_note: true

順番に並べる

実際に壊れた実行では、手順はたいてい次のようになります：相互作用グラフを読んで形を把握し、失敗の帰属を使って決定的なステップを名指しし、決定的なステップが移譲であれば引き継ぎレビューを開き、失敗が 1 つのエージェントではなくタイミングやグループに関するものであれば競合タイムラインまたは創発的振る舞いのタグ付けに手を伸ばします。1 つの実行をデバッグするのではなく設計を比較する段階になったら、スコアカードでスコアリングします。帰属に関する一致度は、ほかの主観的なラベルと同じように測定します。アノテーター間一致度 を参照してください。

さらに読む