※本記事は2026年3月3日に米国で公開された Agent Script Decoded: How to Debug Agent Scriptの抄訳です。本記事の正式言語は英語であり、その内容および解釈については英語が優先されます。
Agent ScriptでAIエージェントを構築したものの、テストをしてみると、思ったように動作しない、ということもあるでしょう。AIエージェントが誤ったトピックに振り分けられているのか、実行すべきアクションをスキップしているのか、あるいは指示とは異なる形で応答しているのかもしれません。
そんなときには、会話の各ターンで生成されるトレースが役立ちます。トレースを見れば、確実な根拠にもとづいてデバッグできます。選択されたトピック、実行可能だったアクションや実行されたアクション、変更された変数、推論ループが時間を費やした箇所がわかるのです。
この記事では、まずAgent Scriptの実行フローについて説明します。次に、Agentforce BuilderとAgentforce DX（英語）を使ってAgent Scriptをデバッグする方法を見ていきます。最後に、Agentforce Vibesを使ったバイブデバッグのワークフローを紹介します。バイブデバッグでは、JSON形式の実行トレースをAgentforce Vibesに貼り付けて、期待していた結果と実際の結果を言葉で説明し、Agentforceの提案を利用してAgent Scriptを改善します。
Agent Scriptの実行フロー
Agent Scriptで構築したAIエージェントを効果的にデバッグするには、まず、実行の流れを理解しておく必要があります。以下に、実行フローがわかる図を用意しました。Agent Scriptのデバッグは、スクリプトを上から下へと直線的にチェックするというよりも、決定論的な命令の実行と非決定論的な推論という異なる2つの実行モードからなるループをたどっていくイメージです。
では、この実行フローをステップごとに見ていきましょう。
ステップ1 – すべての会話ターンは、必ずstart_agent（英語）が起点になります。ユーザーが何を発言したか、前のターンがどこで終了したかにかかわらず、AIエージェントのエントリーポイントとして最初に実行されます。このエントリーポイントで、現在の会話の状態が評価され、AIエージェントが適切なトピックに振り分けられます。
デバッグでまず確認すべき点は、「想定したトピックにAIエージェントが振り分けられたかどうか」です。答えが「ノー」なら、問題の原因はトピックの説明か会話の状態にあります。
ステップ2 – トピックに入ると、reasoning.instructions（英語）は上から順番に、決定論的に実行されます。ここは通常のコードのように動作する部分です。すべてのif条件が評価され、runブロックが実行され、想定どおりに変数が代入されます。一方、プロンプトテキストの行（|で始まる行）は実行されず、プロンプトバッファーに蓄積されていきます。ここが重要な違いです。ロジックは直ちに実行されますが、プロンプトテキストは蓄積されるだけです。instructionsでは、一般的な命令型プログラムでステップ実行を進めるようにバグをトレースできます。
ステップ3 – 組み立てられたプロンプトと利用可能なツールが、Einstein Trust Layerによって保護された大規模言語モデル（LLM）に渡されます。ここで、決定論的な処理から非決定論的な推論に実行が切り替わります。Einstein Trust Layerによって保護されたLLMは、instructionsフェーズで蓄積されたプロンプトテキスト、会話履歴、reasoning.actions（英語）のツール一覧を受け取り、その情報をもとに推論を行います。LLMは直接応答することもあれば、ツールを呼び出すこともあります。このフェーズを確実に予測することはできませんが、入力された情報（組み立てられたプロンプト）を確認することで、LLMがなぜそう推論したかを理解できます。ツールが実行されるたびに、システムはステップ2に戻ってプロンプトを再評価します。LLMがツールを使わずに直接応答するまで、このサイクルが繰り返されます。
ステップ4 – after_reasoning（英語）（定義されている場合）が実行され、ユーザーに応答が返されます。後処理のロジックが実行され、AIエージェントが応答を返し、待機します。サイクルは一時停止しているだけで、終了したわけではありません。
ステップ5 – ユーザーが別のメッセージを送り、ステップ1からループが再開されます。各ターンの切れ目で、どの変数が変わったのか、会話の状態はどう変化したのか、start_agentの振り分け先が変わっていないかを確認してください。複数のターンにまたがるバグは、ほとんどがこのような遷移に潜んでいます。更新されていない変数や、トピックの振り分け条件が当てはまらなくなっている箇所があれば、それがバグの原因かもしれません。AIエージェントの変数はグローバルな状態として扱われ、ターンをまたいで保持されることに注意しましょう。
Agentforce Builderを使ったAgent Scriptのデバッグ
新しいAgentforce Builderを使うと、AIエージェントの実行フローをデバッグし、トレースできます。Agentforce Builderでは、実際のデータに変更を加えずにテストできるシミュレーションモードと、実際のアクションをテストできるライブテストモードを利用できます。どちらにも［Interaction Summary（インタラクション概要）］パネルが用意されており、AIエージェントの会話ロジック、トピックの遷移、トリガーされたアクションを追跡できます。
［Interaction Summary（インタラクション概要）］パネルには、入力、推論、トピックの遷移、アクション、出力の評価という各ステップが、視覚的なわかりやすいタイムラインで表示されます。このパネルは、会話の流れを把握するのにとても便利で、問題が発生している箇所の特定にも役立ちます。
もっと詳しく確認したい場合は、Agentforce Builderの下部にある［Trace（トレース）］タブ（以下のスクリーンショットを参照）を展開します。このタブでは、ミリ秒単位でインタラクションの内訳が表示され、時間がかかっている箇所をタイミングバーで確認できます。各インタラクションをクリックすると、動的に生成されてLLMに送信されたプロンプトなどの詳細を確認できます。
変数を調べたい場合は、［Variables（変数）］サブタブに切り替えると、各ステップの変数の値を確認できます。
Agentforce DXを使ったAgent Scriptのデバッグ
Visual Studio CodeのようなIDEで作業したい場合は、Agentforce DX拡張機能を使って、エディターの［Agent Tracer（エージェントトレーサー）］タブ（下図を参照）で同じトレース機能を利用できます。
左側のパネルでは、ユーザーの入力、選択されたトピック、変数の更新、有効化されたツール、推論ステップ、トピックの遷移など、実行プランの全体を確認できます。
任意のテスト会話をクリックし、ファイルを開くアイコン（赤線で囲んだ部分）をクリックすると、会話ターンについてプランの生の応答を確認できます。このJSONファイルが、判断基準となる情報です。このファイルには、内部のAgent Script変数を含む、実行中の各時点におけるすべての状態変数の値が記載されているため、見つけにくいロジックの問題を調べるうえで非常に役立ちます。
Agent Scriptのバイブデバッグ
Agentforce BuilderとAgentforce DXの拡張機能では、きわめて詳細な実行トレースが可能です。しかし、こうしたツールでステップごとにデータを調べるのは、根気のいる作業です。そうした手間を解消する新しいワークフローが、バイブデバッグです。
ビルダーのUIを操作して問題を調べるのではなく、Agentforce Vibesをペアプログラミングの相棒として活用すれば、トレースを任せることができます。やり方は簡単です。Visual Studio Codeで会話のターンをシミュレーションし、［Agent Tracer（エージェントトレーサー）］タブからJSON形式の実行トレースをコピーしてAgentforce Vibesに貼り付け、期待していた応答をプロンプトで伝えるだけです。Agentforce Vibesは、意図していなかったトピックの振り分け、上書きされた変数、LLMが本来の流れから外れるきっかけになったプロンプトをすぐに見つけ出し、具体的なAgent Scriptの修正コードを提案します。
AIを活用したこのワークフローを活用するには、コンテキストが何より重要です。Agent Scriptの構文と推論ループを理解できるように、Agentforce Vibesに正確な構成図を与える必要があります。そのために、リポジトリに2つの軽量なファイルを追加します。1つは.airules/AGENT_SCRIPT.mdなどのルールファイル、もう1つはルートに配置するインデックスファイル、AGENTS.mdです。すぐに設定できるように、agent-script-recipesレポジトリに、そのまま使えるサンプルが用意されています。
ルールファイルを用意すれば、孤独で地道な作業だったデバッグが、会話しながら進められるワークフローに進化します。Agentforce Vibesで仮説をすばやく検証して、Agent Scriptをレビューしながら繰り返し改善できます。普遍的なコンテキスト基盤を利用したアプローチなので、このワークフローはClaude CodeやCursorといったAIコーディングエージェントやその他のツールにも適用できます。これで、Agent Scriptのデバッグや改善を自由自在に進められるようになります。
まとめ
Agent Scriptのデバッグは、ときにブラックボックスとの闘いのように思えるかもしれません。しかし、Agentforce BuilderとAgentforce DXの拡張機能で実行トレースを活用すれば、勘に頼ることなく原因を突き止められます。
AIエージェントの開発をマスターするうえで重要なのは、直感ではなく、データを信じることです。常に、実行ループの流れを念頭に置いておきましょう。最初に必ずstart_agentがAIエージェントをトピックに振り分けること、ステップごとに実行されるコードとプロンプトテキストはまったく別のものであることを忘れないでください。厳密なロジックとプロンプトを切り分け、LLMに渡される正確なコンテキストを検証することで、問題をすばやく解決できます。手作業で変数値のずれをたどる場合でも、複雑なJSON形式のトレースをAgentforce Vibesで解読する場合でも、信頼できるインテリジェントなAIエージェントを構築できるツールが一式そろっています。次にAIエージェントが想定どおりに動かなくなったときは、トレースログを掘り下げ、データを追ってみてください。
関連情報
執筆者について
Mohith ShrivastavaはSalesforceのプリンシパルデベロッパーアドボケイトです。15年にわたってAgentforce 360 Platform（旧Salesforce Platform）でエンタープライズ規模の製品を開発してきました。Salesforce開発者が質問し合い、知識を共有できる開発者向けフォーラムのSalesforce Stack Exchangeでも積極的に活動しています。LinkedInのプロフィールはこちら。