AI エージェントワークフローを作成するためのベストプラクティスSummary<!-- /*NS Branding Styles*/ --> .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: #000000; } span { font-size: 12pt; font-family: Lato; color: #000000; } h2 { font-size: 24pt; font-family: Lato; color: black; } h3 { font-size: 18pt; font-family: Lato; color: black; } h4 { font-size: 14pt; font-family: Lato; color: black; } a { font-size: 12pt; font-family: Lato; color: #00718F; } a:hover { font-size: 12pt; color: #024F69; } a:target { font-size: 12pt; color: #032D42; } a:visited { font-size: 12pt; color: #00718f; } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } 1.ユースケース名と説明はユーザーの発言に基づいてスキルディスカバリーに使用されるため、明確に説明して定義することが重要です。 - 誤り: o ユースケース名: License Processing o ユースケースの説明: Software License Allocation is used to allocate a software license. - 正解: o ユースケース名: Software License Allocation o ユースケースの説明: The Software License Allocation process involves verifying the details of the requesting user and checking the availability of the requested software license. If the user meets the eligibility criteria, the system proceeds with assigning the license, ensuring seamless access to the required software. 2.明確で文法的に正しい英語で指示を記述します。言語品質が低いと、誤解や実行エラーにつながる可能性があります。 - 誤り: "Run toolA and then show result, dont do confusions," - 正解: "Run Tool A to fetch the required data and then display the result to the user." 3.セクションとサブセクションを使用してユースケースの手順を構造化し、論理的なワークフローを作成します。これは、予想されるフローをシームレスに理解し、ナビゲートするのに役立ちます。 - 誤り: ユーザーとライセンスの詳細を取得します。ユーザーが適格である場合は、ライセンスを割り当てます。 - 正解: 1.インシデントを作成したユーザーの詳細をフェッチします。 2.要求されたソフトウェアライセンスの詳細を確認します。 3.ユーザーが要求されたソフトウェアライセンスにアクセスする資格があるかどうかを確認します。 3.a.ユーザーが適格である場合は、ソフトウェアライセンスを割り当てます。 3.b.ユーザーが対象外の場合は、対象外であることをユーザーに通知します。 4.想定されるエージェントが正しく選択されるように、エージェント名/エージェントの説明で使用されている類似の用語で指示を調整します。 -文脈： o エージェント名:通知エージェント o エージェントの説明:このエージェントは、指定されたユーザーのリストに通知を送信できます。 - 誤り: 問題が発生したことをユーザーに伝えます。[これによりオーケストレーターが混乱し、通知エージェントではなくコミュニケーター エージェントが選択される可能性があります。 - 正解: 問題が発生したことを通知する通知をユーザーに送信します。[これは、オーケストレーターが通知エージェントを選択する必要があることを理解するのに役立ちます] 5.各指示には、アクション可能な操作を 1 つだけ含める必要があります。これにより、誤解を防ぎ、ステップをスキップすることなく各ステップが独立して実行されるようになります。 - 誤り: ユーザーが要求されたソフトウェアライセンスの資格があるかどうかを確認し、資格がある場合はライセンスを割り当てます。 - 正解: 1.ソフトウェアライセンスにアクセスするユーザーの適格性を確認します。 2.ユーザーが適格かどうかに基づいて、次の手順に従います。 2.a.ユーザーが適格である場合は、そのユーザーに割り当てます。 2.b.ユーザーが該当しない場合は、その旨をユーザーに通知します。 6.指示に内部システム用語 (short_term_memory、スクラッチパッド、xml タグ内の変数など) を含めないでください。これは指示に価値を付加するものではなく、むしろエージェントを混乱させます。 - 誤り: ユーザーアカウントのロックステータスを取得し、後で処理するために情報をメモリに保存します。 - 正解: 1.ユーザーアカウントのロックステータスを取得します。 2.ユーザーアカウントがロックされている場合は、ユーザーアカウントのロックを解除します。[データを直接参照します。エージェントのメモリで利用可能になります。] - 正しくない: ユーザーアカウントの状態を変数 に格納します。 - 正しい: ユーザーアカウントがロックされている場合は、ユーザーアカウントのロックを解除します。 7.指示にエンドユーザーとの通信が含まれる場合は、「エージェント」、「あなたと話しているエンティティ」などのあいまいな用語を使用するのではなく、明示的に「ユーザー」と呼びます。 - ユーザーに何かを表示するには: - 誤り: 欠落しているユーザーのリストをエージェントに表示します。 - 正解: 欠落しているユーザーのリストをユーザーに表示します。 - ユーザーに何かを尋ねるには: - 誤り: レコード番号を見つけます。 - 正解: ユーザーにレコード番号を尋ねます。 8.明確な構造的な連続した手順でエージェントに指示を書き込みます。 - 誤ったエージェント指示: ソフトウェアライセンスを確認して割り当てるには、次の手順を実行します。 ステップ1:ライセンスIDがある場合は、ステップ2に進みます。 指定されていない場合は、手順 7 に進みます。 [ステップ 1 の問題: 説明書にライセンス ID の確認方法が指定されていません。記憶からですか?ユーザー入力ですか?明確化が必要です。] ステップ 2: 次の手順に従います。[これは不要です。実行可能なタスクを記述するだけです] これがマネージャーユーザーである場合は、手順 5 に進みます。 これが通常のユーザーである場合は、手順 4 に進みます。 これがゲストユーザーである場合は、手順 2 に進みます。 [ステップ 2 の問題: ゲスト ユーザーはループに陥り、ステップ 2 に延々と戻ってしまいます。] ステップ 3:ゲストユーザーライセンスの割り当て: - 適切なツールを使用して、ユーザーライセンスをゲストユーザーに割り当てることができるかどうかを確認します。 [ステップ 3 の問題点:] [1: 「適切なツール」とは何ですか?定義されていません。] [2:「ユーザーライセンスを割り当てることができるかどうかを確認する」 - ライセンス割り当ての適格基準を確認する手順は何ですか?] - ゲスト・ユーザーを割り当てることができる場合は、ゲスト・ユーザーに割り当てていることをユーザーに伝えます。 - 手順 6 に進みます。 ステップ 4:マネージャー ユーザー ライセンスの割り当て: - マネージャーがライセンスの取得を許可されている場合は、ライセンスが存在するかどうかを確認します。 - 存在する場合は、それを割り当ててユーザーに知らせます。 - それ以外の場合は、別のことをしてください。 - 手順 6 に進みます。 [ステップ 4 の問題:] [1: 「allowed」とはどういう意味ですか?基準は示されていません。 [2: 「他のことをする」 - 正確には何ですか? ステップ 5: 通常のユーザー ライセンスの割り当て: - 要求されたソフトウェアライセンスがあるかどうかを確認します。 - 利用可能な場合、ユーザーはそれを取得する必要があります。 - そうでない場合は、ステップ 6 に進みます。 [ステップ 5 の問題:] [1: 「そこ」――どこ?データベースチェックまたは特定の場所が必要です。] [2: 「それを手に入れるべきだ」—どうやって?割り当て方法がありません。] ステップ 6: 何かを処理する (目的が不明瞭) - すべてがうまくいけば、先に進みます。 - 何か問題が発生した場合は、それが何であるかを把握して修正します。 [ステップ 6 の問題:] [1: 「何かを扱う」 - 正確には何ですか? [2: 「前進する」――どこへ?方向性が指定されていません。 [3: 何が問題なのかをどのように「理解」しますか?トラブルシューティングの手順がありません。] ステップ 7:ライセンス ID がない場合:ユーザーがライセンス ID を指定しなかった場合は、ライセンス ID が必要かどうかを確認します。- 必要な場合は、入手するように伝えてください。 - 必要ない場合は、続行します。[ステップ 7 の問題:][1. 彼らが「必要」かどうかを確認するにはどうすればよいですか?方法が与えられていません。[2: 「彼らにそれを手に入れるように言ってください」—どこで/誰から?明瞭さが欠けています。[3: continue」とはどういう意味ですか?プロセスは保留されたままです。 - 正しいエージェント指示: 適格基準を確認し、ソフトウェアライセンスを割り当てるには、以下の手順に従ってください。 ステップ 1: ライセンス ID が利用可能かどうかを確認します。ライセンス ID がない場合は、ユーザーにライセンス ID の入力を求めます。 ステップ 2:ユーザーの詳細をフェッチして、ユーザータイプを特定します。 ステップ3:ユーザータイプが「マネージャー」の場合は、次の手順に従います。 ステップ 3.1: 要求されたソフトウェア ライセンスが利用可能かどうかを確認します。 ステップ3.2:利用可能な場合は、ユーザーに割り当てます。 ステップ3.2.1:ライセンスが正常に割り当てられたら、ユーザーに同じことを通知します。 ステップ 3.3:ライセンスが利用できない場合は、要求されたライセンスが利用できないことをユーザーに通知します。 ステップ4:ユーザータイプが「正社員」の場合は、次の手順に従います。 ステップ 4.1:ユーザーのライセンス割り当てタスクを作成します。 ステップ4.2:タスクが作成されたら、ライセンス割り当てタスクが作成され、マネージャーの承認を待っていることをユーザーに通知します。ライセンスの割り当ては、マネージャーの承認に基づいて処理されます。 ステップ5:ユーザータイプが「ゲスト」の場合は、以下の手順に従ってください。 ステップ 5.1:ゲストユーザーのロールを確認します。 ステップ 5.2:要求されたソフトウェアライセンスの対象となるロールのリストを取得します。 ステップ 5.3:ゲストユーザーのロールとソフトウェアライセンス適格性ロールを比較して、ゲストユーザーが要求されたライセンスの対象かどうかを判断します。 ステップ 5.4:ゲストユーザーが要求されたライセンスの対象である場合は、一時的なライセンス割り当てタスクを作成します。 ステップ 5.4.1:ゲストユーザーに対して一時的なライセンス割り当てタスクが作成されたことをユーザーに通知します。 ステップ 5.5:ゲストユーザーが要求されたライセンスの資格を持たない場合は、ロールがないためゲストユーザーが要求されたソフトウェアライセンスにアクセスする資格がないことをユーザーに通知します。 9.指示書にツール情報を重複して記載しないでください。「これらのツールが提供されました」や「以下のツールが提供されました」などの指示を追加しないでください。 エージェントにマッピングされたツールとその説明は、既にエージェントで利用可能です。したがって、これらの指示を指示書に繰り返し記載しないでください。 - 誤り: o ABC 機能を備えたツール X が提供されます。 - 正解: o ツール X を使用してデータを抽出します。 o XYZ の詳細をフェッチします。 10.単一の命令に複数のアクションを組み合わせると、実行中にいくつかのステップがスキップされる可能性があります。各指示は、単一の実行可能なタスクに焦点を当てる必要があります。 - 誤り: レコードを要約してユーザーに表示し、同じデータでレコードメモを更新します。 - 正解: 1.レコードの詳細を要約します。 2.要約されたレコードの詳細をユーザーに表示します。 3.レコードサマリーでレコードを更新します。 11.混乱を防ぐために、チーム内の複数のエージェント間でツールに一意の入力を使用します。 - 誤り: 両方のツール入力に sys_id という名前を付けます。 1.エージェント 1: o 名前:インシデントアナライザーエージェント o ツール名:インシデントの詳細を取得 § ツール入力名:sys_id 2.エージェント 2: o 名前:ユーザーアナライザー o ツール名:ユーザーの詳細を取得 § ツール入力名:sys_id - 正解: さまざまなツールの入力を区別するための意味のある名前を提供します。 1.エージェント 1: o 名前:インシデントアナライザーエージェント o ツール名:インシデントの詳細を取得 § ツール入力名: incident_sys_id 2.エージェント 2: o 名前:ユーザーアナライザー o ツール名:ユーザーの詳細を取得 § ツール入力名: user_sys_id 12.エージェントの一意の名前と明確な説明により、オーケストレーターは各タスクに適切なエージェントを選択できます。 - 誤り: チーム内に「Analyzer」という名前の複数のエージェントが、類似した説明を持っています。 1.エージェント 1: o 名前:データアナライザーエージェント o 説明:このエージェントはデータを分析します。 2.エージェント 2: o 名前:コンテンツアナライザーエージェント o 説明:このエージェントはコンテンツを分析します。 - 正解: 1.エージェント 1: o 名前:データアナライザーエージェント o 説明: トランザクションデータの抽出と分析を担当します。結果を表示し、ユーザーからのフィードバックを受け取ります。 2.エージェント 2: o 名前:ログアナライザーエージェント o 説明:システムログを確認し、異常にフラグを立ててユーザーに伝達する責任があります。 13.ツールの一意の名前と明確な説明により、エージェントは各タスクに適したツールを選択するのに役立ちます。 - 誤り: 目的が異なる 2 つのツールの名前は似ており、ツールの説明も明確に定義されていません。 1.エージェント 1:インシデントアナライザー o ツール名:ユーザーの詳細を取得 o 説明:ユーザーの詳細を取得 2.エージェント 2:ユーザーアナライザー o ツール名:ユーザーの詳細を取得 o 説明:ユーザーの詳細を取得 - 正解: ツールの名前と説明は、ツールの機能を明確に示しています。 1.エージェント 1:インシデントアナライザー o ツール名:ユーザーステータスを取得 o 説明:ユーザーアカウントがアクティブかどうかを確認します。 2.エージェント 2:ユーザーアナライザー o ツール名:ユーザーの詳細を取得 o 説明:名前、部門、マネージャー、その他の個人情報やチーム情報などのユーザーの詳細をフェッチします。 14.各操作 (データの要約、収集、連結) には、独自の専用命令が必要です。 - 誤り: ユーザーに表示する前に、データを要約して連結します。 - 正解: 1.インシデントの類似のインシデントを取得 2.類似のインシデントからインシデント番号を収集します。 3.インシデント番号をユーザーに表示します。 15.ツールで特定の入力が常に存在する必要がある場合、その機能 (フローアクション、サブフローなど) がツールで使用できる場合は、必ず必須としてマークします。ない場合は、ツール入力の説明に記載してください。 - 誤り: o ツール名:インシデントの詳細を取得 o 入力名:incident_number o 入力説明:インシデント番号 - 正解: o ツール名:インシデントの詳細を取得 o 入力名:incident_number o 入力説明:インシデントレコードの一意の識別子。これは必須入力です。インシデント番号はパターン「INCXXXXXX」に従います。 UI 16でも利用できますツールの実行パターンに一貫性を持たせるために、ツールの設計中は常に入力を明確に記述してください。 - 誤り: o 入力名:user_id o 入力説明:ユーザーの ID。 - 正解: o 入力名:user_id o 入力説明:ユーザーの 32 文字の英数字で構成される一意の識別子。 - 説明: user_idには、sys_id、フルネーム、ユーザー名、email_idなどがあり、LLMがツールを実行するためにどのようなタイプの入力を選択する必要があるかを明確に理解できるようにすることが重要です。 17. 大きな出力を処理するための適切な変換戦略を選択します。たとえば、「検索結果のサマリー」などの出力変換を使用すると、特に RAG をツールとして使用する場合に、関連情報のみをフィルタリングして保持するのに役立ちます。 - 誤り: 完全な検索結果をエージェントに直接渡します。 - 正解: 出力変換: 「検索結果のサマリー」を使用して、実行に必要なコンテキスト情報のみをフィルタリングして渡します。 - 例: 類似のインシデントをフェッチする場合、RAG ツールは検索クエリと意味的に類似したすべてのインシデントを取得します。「検索用サマリー」の適用 results」の変換戦略により、最も関連性の高いコンテキスト情報のみが選択され、転送されます。 18. モデルのトークン制限を超えるツール出力は切り捨てられることに注意してください。データ損失を防ぐために、データを適切に処理または要約するためのツールコードの後処理ロジックを確認します。 - 誤り: トークン制限を考慮せずにツールから大量のデータを生成し、それをエージェントに渡します。 - 正解: 必要で意味のあるデータのみを取得し、必要に応じて要約します。 - 例: チームに割り当てられたすべてのインシデントを取得すると、過剰なデータが生成される可能性があります。理想的なアプローチは、すべてのインシデントを取得し、インシデントレコードから必要な属性のみを抽出し、必要に応じてデータを要約することです。 19.アクションステートメントを使用して、エージェントの名前または他のエージェントにマッピングされているツールの名前を使用せずに、実行フローをチーム内の別のエージェントに転送します。 - 誤り: 「インシデントアナライザーエージェント」から「インシデントの詳細を取得」を呼び出し、値を INCxxxxxx としてincident_numberします(Call “Get incident details” from “Incident analyzer agent” with value incident_number as INCxxxxxx) - 正解: 1.取得したインシデント番号を使用してインシデントの詳細をフェッチします。(Fetch incident details with the the retrieved incident number.) 2.取得したインシデントの詳細から、アサインされたユーザーのユーザーの詳細をフェッチします。(Fetch user details for the assigned user from the retrieved incident details.) 20.大規模なデータセットの処理、特定の制約の下での構造化コンテンツの生成、または決定論的な結果を伴う複数ステップのロジックの実行を伴うエージェントワークフローの場合は、organize_general_knowledgeや数学などの組み込みツールに依存するのではなく、専用のスキルツールを実装することをお勧めします。 o 組み込みツールは、軽量のメモリ内操作をサポートするように設計されており、メモリへの出力を永続化したり、エージェント間の共有を有効にしたりすることなく、エージェントに一時的な推論スペースを提供します。これらのツールは、迅速なデータ構造化と基本的な推論タスクに最適です。 o 出力 (コンテンツ、形式、構造など) を正確に制御する必要があるユースケースでは、カスタムスキルツールの柔軟性と信頼性が向上します。 o 例 1:ネクストベストアクションエージェント:計画を生成する場合、スキルツールを使用すると、書式設定、スタイリング、構造の一貫性が確保されますが、これは、出力を明示的にガイドまたは保持できない組み込みツールでは簡単に実現できません。 o 例 2: HTML 応答の生成、特定のルールが設定された項目別リストの作成、大きなドキュメントの詳細に対する検証などのタスク 基準はスキルツールによってより適切に処理されます。そうしないと、エージェントに必要な指示の複雑さが大幅に増し、実行中にあいまいになったり、ステップが見落とされたりする可能性があります。 o このようなケースにカスタムスキルツールを使用することで、エージェントの動作が予測可能、再利用可能、保守可能であることを確認できます。 デバッグ 1.意思決定ログ (エージェントプレイグラウンドの右ペイン) は、ユースケース、エージェント、ツールの詳細における指示が LLM によってどのように分析されるかについての詳細を提供する上で、非常に重要な役割を果たします。 2.すべての「オーケストレーター」ログは、ユースケースで定義された指示に基づいて生成されます。このログには、生成されたサブタスクと、それが委任するエージェントが記載されています。 3.すべての ログは、エージェントで定義された指示に基づいて生成されます。 4.エージェントログ: a.思考は、実行フローでこれまでに起こったことと、次に実行するアクションについて説明します。エージェントの指示は、この思考を生成し、エージェントのフローを制御する責任があります。それに応じて指示を調整します。 b. アクションの推論は、エージェントがツールとその入力を実行することを選択した理由を記述します。間違ったツールが選択された場合は、名前、説明、入力、入力説明などのツールの詳細を確認してください。 c.[アクションの入力] には、ツールを実行するために選択されたデータが表示されます。このデータは、エージェントのメモリから選択されます。間違った入力が選択された場合は、メモリに保存されている入力の詳細に合わせて入力の説明を調整します。 d. アクションの出力は、ツールの実行が成功したかどうか、およびツールから返された出力を理解するのに役立ちます。 5.ツール実行出力を含む現在の会話で生成されたすべてのデータは、メモリに格納されます (メモリはsn_aia_messageテーブルの「メッセージ」列に保持されます)。 FAQ 1.スキルが検出されません。 Ø インスタンスでスキルディスカバリーが機能しているかどうかを確認し、機能していない場合は、それぞれのチームに連絡してサポートを受けてください。 Ø スキル検出が機能していて、ユースケース/エージェントが検出されていない場合は、ユースケース名と説明/エージェント名と説明を確認してください。 2.実行はすぐに「申し訳ありません。この要求を完了しようとしてこちら側で問題が発生しました。後でもう一度質問してみてください。(Try again ask later)」というエラーが表示されます。 Ø まず、「sys_generative_ai_log」テーブルに移動し、インスタンスで LLM 呼び出しが成功しているかどうかを確認します。 Ø エラーが発生した場合は、インスタンスの生成 AI コントローラーのセットアップを確認します。 Ø Planner/ReAct LLM 呼び出しが成功した場合は、特定のタスクに適したエージェントを選択できなかったことを示します。タスクの専門用語がエージェントの名前、説明、ロール、指示、習熟度と一致しているかどうかを確認します。 3.実行中に誤ったエージェントが選択されました。 Ø エージェントの名前とチーム内のエージェントの説明が一意であることを確認します。チーム内にコンテキストが重複するエージェントが複数存在し、どのエージェントがタスクに最も適しているかについてオーケストレーターが混乱する場合。 4.メモリを参照するための命令を記述する方法は? Ø エージェントのメモリを参照するために特定の用語を使用する必要はありません。「抽出されたインシデントの詳細についてユーザーにメッセージを表示する」などの指示を直接書き込みます。 5.別のエージェントに引き渡すための指示を書く方法は? Ø 実行フローを別のエージェントに引き継ぐために、別のエージェントの名前や別のエージェントにマッピングされたツールの名前を決して言及しないでください。現在のエージェントは他のエージェントのツールやチーム内の他のエージェントの名前を認識しないため、混乱します。 Ø これを達成するために、タスクを説明する実用的なステートメントを使用します。 Ø 例 1:インシデントの詳細をフェッチします (ここでは、「インシデントの詳細を取得」は別のエージェントのツールです)。 Ø 例 2:インシデントの詳細からアサインされたユーザーのユーザー情報をフェッチします。(ここでの「ユーザーの詳細を取得」は、別のエージェントにマッピングされたツールです) 6.ユーザーに質問したり、ユーザーに何かを表示したりするための指示を書く方法は? Ø 指示には、エージェントに関連するものを含めないでください。例:エージェントにインシデント番号の入力を依頼します。(これは不正解です) Ø ステートメントはユーザーに宛てる必要があります。例:ユーザーにインシデント番号の入力を求めます。 Ø 入力を求めずにユーザーに何かを表示するには、表示/表示などの用語でユーザーに対処します。例:インシデントの詳細を取得できなかったことをユーザーに通知します。 7.複数のエージェント間でメモリを共有するにはどうすればよいですか? Ø ツールからの値をに保存するなどの用語や、「メモリに保存する」などの用語は使用しないでください。エージェントには「何かをメモリに保存する」という概念がないため、エージェントはこれを理解できません。 Ø メモリは内部で維持され、すべてのツール出力とユーザーに伝えられた情報が保存され、すべてのエージェント間で共有されます。 Ø 指示内のデータを参照するには、ツール出力から返された用語に合わせた実用的なステートメントを使用して、参照されるデータのコンテキストがエージェントに明確にわかるようにします。 Ø 例:取得したインシデントの詳細から、アサインされたユーザーのユーザーの詳細をフェッチします。 8.エージェントの実行を終了するための指示を記述するには? Ø 「会話を終了する」/「実行を停止する」/「フローを終了する」/「実行を終了する」などのステートメントは使用しないでください。 Øこれには特別な指示は必要ありません。指定されたアクションアイテムが指示に従ってエージェントによって実行されると、完了します。 Related Links<!-- /*NS Branding Styles*/ --> .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: #000000; } span { font-size: 12pt; font-family: Lato; color: #000000; } h2 { font-size: 24pt; font-family: Lato; color: black; } h3 { font-size: 18pt; font-family: Lato; color: black; } h4 { font-size: 14pt; font-family: Lato; color: black; } a { font-size: 12pt; font-family: Lato; color: #00718F; } a:hover { font-size: 12pt; color: #024F69; } a:target { font-size: 12pt; color: #032D42; } a:visited { font-size: 12pt; color: #00718f; } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } 「高度な AI エージェント説明ガイド:ServiceNow エディション」の詳細については、以下のコミュニティ記事を参照してください。 https://www.servicenow.com/community/now-assist-articles/advanced-ai-agent-instructions-guide-servicenow-edition/ta-p/3346578