AI Agent を設計するとき、やってしまいがちな6つのこと

[Hiroyuki Kojima]

はじめに

ServiceNow の AI Agent は、設定画面を開けばすぐに動き始めます。 Role を書いて、Instructions を書いて、ツールをアサインすれば、会話が始まる。

「思ったより簡単だな」と感じる瞬間が、実は落とし穴の入り口です。

動くことと、正しく設計されていることは別の話です。 本番稼働後に「なぜかツールを呼ばない」「ループが止まらない」「Assistの消費が想定の3倍だった」という状況は、最初の設計の判断ミスから始まっていることがほとんどです。

AI Agent の設計に関わる Architect として、現場で繰り返し見てきた「やらかし」を6つにまとめました。

---

その1：Instructions に 8,000 文字以上書こうとする

AI Agent の Instructions には 8,000文字という上限があります（Role は 2,000文字）。 「詳しく書けば書くほど賢くなる」と思いがちですが、Instructions が長くなるほどエージェントの動作は不安定になります。

正しいアプローチ：Critical Instruction Anchoring

重要なルールは 3箇所に配置することで、エージェントの「迷走」を防げます。

## CRITICAL REQUIREMENT: [キーとなるルール — "must" を使う]  ← 冒頭に必ず置く

### Step 2: ...
...maintaining CRITICAL REQUIREMENT from above...            ← 中間で再参照

### Final Validation Gate
Confirm all CRITICAL REQUIREMENTS satisfied before ending    ← 最後に検証

「should」ではなく 「must」 を使うこと。LLMは "should" を推奨として読み、スキップすることがあります。

---

その2：組み込みツールの名前を Instructions に書いてしまう

AI Agent Studio には、Content Analysis、User Input、User Output などの組み込みツールが存在します。

これらをInstructionsの中で名指しすると、エージェントは「アサインされたカスタムツール」を探し始め、見つからずに失敗します。

❌ やってしまいがちな書き方

"Use the Content Analysis tool to evaluate the findings"

✅ 正しい書き方

"Analyze and evaluate findings systematically"

組み込みツールはアクションキーワードに反応して自動的に呼ばれます。 analyze / evaluate / assess → 分析ツール、fetch / retrieve → データツール、show / display → UIツール、といった具合です。名前を書く必要はありません。

---

その3：ツールに「全データ」を渡してエージェントに判断させる

こんな設計をしていませんか。

「直近のインシデントを全件取得して、対応が必要なものをエージェントに選ばせる」

これは、未整理の書類を500枚そのまま渡して「重要なものを選んで」と頼むようなものです。
人間でも混乱しますし、エージェントも同じです。

 

エージェントと Script の役割分担を間違えない

エージェント（LLM）が得意なのは判断・推論・文章生成です。大量データのフィルタリングや数値計算は不得意で、やらせると動作が不安定になります。

一方、Script ツール（GlideRecord）が得意なのはクエリ・フィルタリング・集計です。これは JavaScript で確実に、高速に処理できます。

つまり役割はこうです。

Script ツール → データを絞り込んで「判断できる形」に整える
エージェント  → 整理された情報をもとに判断・アクション

 

実装のイメージ

Script ツールの中で条件を絞り込み、エージェントには結論だけを返します。

// ❌ やりがちな設計：全件返してエージェントに選ばせる
// → 件数が多いほど遅く、不安定になる

// ✅ 正しい設計：Script 側で絞り込んで結論を返す
var gr = new GlideRecord('incident');
gr.addQuery('priority', '1');          // 最優先のみ
gr.addQuery('state', '1');             // 未対応のみ
gr.addQuery('assigned_to', 'NULL');    // 未割り当てのみ
gr.setLimit(5);                        // 上位5件に絞る
gr.query();

// エージェントには「判断済みの情報」だけを渡す
return JSON.stringify({
  critical_count: gr.getRowCount(),
  recommended_action: "ESCALATE",
  reason: "High priority incidents unassigned over 30 minutes"
});

エージェントはこの結果を受け取って「では担当者にエスカレーションします」と判断するだけです。「全件の中からどれが重要か」を考えさせる必要はありません。

エージェントに渡すのは、判断に必要な情報だけ。 それ以外は Script に任せるのが、安定した AI Agent 設計の基本です。

---

その4：Assist の消費量を設計段階で考慮していない

AI Agent は ツールのアクション実行数に応じて Assist を消費します（Small / Medium / Large にバケット分け）。

見落としがちなのは次のポイントです。

• ツールが ループする設計 になっていると、消費量が想定の何倍にもなる
• ループが止まらない場合は sn_aia.continuous_tool_execution_limit プロパティを確認する

本番前に sn_aia_execution_plan テーブルの "AI Usage Log (gen_ai_usage_log)" カラムを追加しておくと、1回の実行あたりの実際の消費量をトレースできます。ライセンスコストの見積もりにも役立ちます。

---

その5：「動いている」で満足して、ログを見ない

AI Agent が動いている状態でも、内部では意図しない動作をしていることがあります。 設計後に必ず確認すべきログテーブルを把握しておくことが、PA としての必須スキルです。以下は公式のプロンプトエンジニアリングガイドに記載されているテーブルです。

テーブル	何がわかるか
sn_aia_execution_plan	会話単位の実行プラン全体
sn_aia_execution_task	Thought / Action の各ステップの内容
sys_generative_ai_log	LLMへの全プロンプトと生レスポンス

「ツールが呼ばれていない」「途中で止まった」という症状は、まず sn_aia_execution_task を見て、次に sys_generative_ai_log の Thoughts フィールドを確認するのが最短ルートです。

---

その6：Instructions を日本語で書けば、そのまま動くと思っている

「日本語でプロンプトを書くと挙動が不安定になる気がするけど、気のせいですか？」

現場でよく聞かれます。気のせいではありません。ただし原因は「日本語だから」ではありません。

公式は何と言っているか

ServiceNow の AI Agent 作成ガイドライン（General guidelines for creating AI agents and agentic workflows）の冒頭には、こう書かれています。

"AI agents and agentic workflows rely on large language models (LLMs), so the language that you use for their instructions is important."

そして多言語サポートの記述はわずか3行です。

• Tune system prompts for native translations （ネイティブ翻訳のためにシステムプロンプトをチューニングせよ）
• Implement dynamic translation strategies when native support is unavailable （ネイティブサポートがない場合は動的翻訳戦略を実装せよ）
• Provide extensive testing via automated and manual evaluations （自動・手動評価による徹底したテストを行え）

3行すべてが「やるべきこと」の列挙です。英語でも同じです。どの言語で書こうとも、チューニングと徹底したテストは前提——これが公式の立場です。

本当の問題はプロンプティングの質

日本語 Instructions が不安定に見えるのは、日本語だからではなく、日本語で書くときにプロンプティングが雑になりやすいからです。

公式ガイドが求めているのは言語を問わず共通です。

• 曖昧な表現を避け、具体的なアクション動詞を使う
• 条件分岐は「もし〜なら〜する」と明示する
• 重要なルールは冒頭・中間・末尾の3箇所に置く（Critical Anchoring）
• ゲート条件を明示して、依存するステップを飛ばさせない

英語のサンプルをそのまま手本にできる分、英語のほうが始めやすいのは事実です。しかし日本語でも、同じ水準のスクリプティングを実現すれば同じことができます。

「言語を変える」より「スクリプティングの質を上げる」ことが先です。

 

日本語で書くなら、これを意識する

ただし日本語には、英語と比べて構造的に曖昧になりやすい特性があります。これはLLMにとって解釈の揺れに直結します。

① 主語が省略される

「確認して次に進む」——誰が何を確認するのか、文脈次第です。英語なら "Verify the incident number before proceeding" と主語・動詞・目的語が固定されます。日本語で書くなら主語を省かない意識が必要です。

② 述語が文末に来る

日本語は条件と結論が最後まで読まないと確定しません。「インシデントの優先度が高く、かつ未割り当ての場合は、担当チームに通知する」——LLMはこの文を最後まで読んで初めて何をすべきかわかります。英語の "If priority = High AND unassigned, notify the team" は冒頭から構造が明確です。

③ 「〜してください」は命令か依頼か

英語の命令形（"Fetch" "Analyze" "Validate"）はLLMにとって迷いなく行動を促します。日本語の「〜してください」「〜するようにしてください」は依頼のニュアンスが混じり、強度が曖昧になります。

日本語で Instructions を書くなら、これらを意識して補正することが「チューニング」の実体です。主語を省かない、条件を先に書く、命令形を統一する——それだけでプロンプティングの質は大きく変わります。

---

まとめ

AI Agent の設計で「やらかし」が起きやすいのは、プラットフォームの動作原理を知らないまま設計を進めてしまうからです。

• Instructions には文字数と設計パターンがある
• 組み込みツールは名前ではなくキーワードで動く
• ツールに処理を寄せる設計がエージェントを安定させる
• Assist消費はループ設計に特に注意して設計段階からカウントする
• ログを読む習慣がないと、本番で原因不明の問題に直面する

これらを知っているかどうかだけで、AI Agent の品質は大きく変わります。 「なぜか動かない」が「なぜ動いているかわかる」に変わったとき、設計者として一段階上がったと感じると思います。

---

本稿に記載されている内容は、執筆者個人の経験と見解に基づくものであり、ServiceNowの公式見解や製品方針を示すものではありません。