スキル設計のベストプラクティス ​

Genieの信頼性は、アクセスできるスキルの信頼性に左右されます。 適切に設計されたスキルは正しく呼び出され、適切な入力を受け取り、確実に実行され、Genieが会話を続行するために必要なものだけを返します。 設計が不十分なスキルは一貫性なく呼び出され、誤った入力や不足した入力を受け取り、診断が難しい形で失敗し、Genieが効果的に使用できないデータを返します。

ほとんどのスキル障害はLLMの障害ではありません。 誤った抽象化や、過剰なデータを返す誤った入力モデルを中心にスキルが構築されていることによる設計上の障害です。 このページでは、信頼性の高いスキルを設計するためのベストプラクティスについて説明します。

ユーザーの意図を中心に設計する ​

最も一般的なスキル設計の誤りは、ユーザーの意図ではなくAPIエンドポイントを反映したスキルを構築することです。 APIには作成、読み取り、更新、削除のエンドポイントがあるため、ビルダーはエンドポイントごとに1つ、合計4つのスキルを作成します。 これは論理的に見えますが、ビジネス成果ではなくAPI操作の観点で考えることをユーザーに強いるGenieを生み出します。

ユーザーはcall the GET /accounts/{id} endpointを望んでいるわけではありません。 ユーザーはget an account summary before a callを望んでいます。

各スキルは、基盤となるAPIが公開する内容ではなく、ユーザーが達成しようとしていることを中心に設計してください。 アカウントサマリーを取得スキルは内部で集約し、レシピ内で複数のSalesforceオブジェクトを呼び出し、Genieが必要とするすべてを含む単一のクリーンなオブジェクトを返す必要があります。 ユーザーとGenieには、1つのことを実行する1つのスキルとして表示されます。 APIの複雑さはレシピが内部で処理します。

このベストプラクティスには、次の3つの実践的な意味があります:

• API呼び出しごとに1つのスキルではなく、ユーザーの意図ごとに1つのスキル: 3つのAPIを呼び出す必要があるユーザーの目標は、Genieが3つのスキルを連鎖させるのではなく、1つのスキル内で処理する必要があります。
• スキルには、APIに対して実行する内容ではなく、ユーザーに対して実行する内容に基づいて名前を付ける: Salesforceでアカウントサマリーを取得は適切な名前のスキルです。 GET accounts id opportunities contactsは適切ではありません。 スキル名は、LLMがそのスキルを呼び出すかどうかを判断するときに読み取る情報の一部です。
• APIが返すものではなく、Genieが必要とするものを返す: 未加工のAPI応答は、ほとんどの場合、適切なスキル出力ではありません。 結果をGenieに返す前に、レシピ内でフィルタリング、変換、および集約します。

入力にはビジネス識別子を使用する ​

入力には内部IDではなくビジネス識別子を使用します。 LLMは内部システムIDを作り出すことはできず、SalesforceアカウントAcme Corpの内部IDが001Hs00000KlMnOPQであることも認識していません。 Genieは、ユーザーがget the Acme Corp accountをリクエストしたときにビジネス名を認識しますが、内部IDは認識しません。

スキル入力には、アカウント名、メールアドレス、チケットの概要、製品名など、ユーザーが会話の中で自然に提供できる識別子を使用する必要があります。 基盤となるAPIで内部IDが必要な場合、スキルはAPIを呼び出す前に、ビジネス識別子を内部で内部IDに解決する必要があります。

推奨 ✅

入力: account_name (string)
ヒント: Salesforceに表示されるアカウント名。
      例: "Acme Corp"。
      ユーザーのメッセージまたは
      会話の前の部分にある
      アカウント名を使用します。

次に、レシピはSalesforceでアカウントを名前で検索し、内部IDを取得して、後続のAPI呼び出しに使用します。 Genieとユーザーに内部IDが表示されることはありません。

この原則はすべての識別子タイプに適用されます。 ユーザーIDはメールアドレスから解決する必要があります。 チケットIDはチケットの概要またはキーから解決する必要があります。 製品IDは製品名から解決する必要があります。 解決ロジックをスキルに組み込み、Genieへの入力はAPIの言語ではなくビジネスの言語に保ちます。

非推奨 ❌

入力: account_id (string)
ヒント: Salesforce内部アカウントID
      （18文字の英数字文字列）

スキル出力をフィルタリングする ​

出力は簡潔でフィルタリングされたものにする必要があります。 LLMのコンテキストウィンドウには限りがあります。 スキルが返すすべてのフィールドは、コンテキストウィンドウの領域を消費します。 すべてのフィールド、ネストされたオブジェクト、メタデータ、システムフィールドを含む完全なAPI応答オブジェクトを返すスキルは、Genieがまったく使用しないデータでコンテキストを浪費し、会話履歴や他のスキル出力に使用できる領域を減らし、応答品質を低下させる可能性があります。

すべてのスキルで、Return responseステップの前に、特定のユースケースでGenieが必要とするフィールドだけを含めるよう出力を明示的にフィルタリングします。

Genieが推論するため、またはユーザーに提示するために必要なフィールドを一覧にします。 出力にはそれらのフィールドのみを含めます。 確信が持てないフィールドは除外します。 テストで不足が判明した場合は、フィールドを追加できます。

常に除外する3つのフィールドカテゴリ:

• 内部システムフィールド: ID、チェックサム、APIバージョンマーカー、およびシステム操作に使用される内部タイムスタンプ。 Genieはこれらを必要としません。
• ユーザーに表示されないフィールド: 設定フィールド、システムフラグ、および監査メタデータ。 Genieがユーザーへの応答に含めない値は、出力に含めるべきではありません。
• 冗長なフィールド: 出力にpriority_label: Highとpriority_code: 3のように、同じデータのフォーマット済みラベルと未加工値の両方が含まれている場合は、Genieが必要とする値のみを含めます。 通常、Genieが必要とするのはラベルです。

ナレッジを引用する場合はソースURLを返す ​

ナレッジベース記事、Confluenceページ、ポリシードキュメント、サポートチケットなど、Genieがユーザーの質問に回答するために使用する可能性のある情報をスキルが取得する場合は、出力にソースURLを含めます。 Genieは、ユーザーに情報を提示するときに、このURLを使用してソースを引用します。

according to the Annual Leave Policy (link)と述べるGenieは、出典を示さずに事実を述べるものより信頼できます。 ソースを確認できるユーザーは、回答を信頼する可能性が高く、不必要に人間へエスカレーションする可能性が低くなります。

ソースURLは、テキストフィールドに埋め込むのではなく、スキル出力内の専用フィールドとして含めます。 専用フィールドにすると、Genieが一貫して参照しやすくなり、スキル説明の出力要件でその使用方法を指定しやすくなります。

ダウンストリームアプリイベント用の識別子をログに記録する ​

一部のスキルは、作成されたチケット、送信された承認、更新された商談など、将来の会話で参照が必要になる可能性のあるレコードを作成または取得します。 これらのスキルでは、スキルが結果を返す前に、レコードの識別子と現在の会話IDをData tablesに保存します。

このログ記録ステップにより、アプリイベントをトリガーとするフォローアップが可能になります。 チケットのステータスが変更され、レシピがアプリイベントを発火してユーザーに通知する場合、正しいスレッドを再開するために会話IDが必要です。 ログ記録ステップがなければ、外部イベントを、そのレコードが作成されたGenie会話に結び付ける方法はありません。

ログ記録ステップは、API呼び出しと応答を返すステップの間にあるスキル内に配置します。 少なくとも次の情報を保存する必要があります:

• 外部レコード識別子: チケットIDまたは商談ID
• Workato会話ID: Start workflow（ワークフローを開始）トリガーから生成
• リクエスターのメールまたはユーザーID
• 作成タイムスタンプ

これはどのスキルにも小さな追加ですが、Genieを通じて作成されたレコードに対するフォローアップイベントを伴うユースケースでは、ダウンストリームで大きな価値があります。

スキルをアトミックに保つ ​

アトミックスキルは1つのことを実行します。 1つの主要なアクションで1つのユーザー意図を達成し、1つの一貫した結果を返します。 レコードの作成、通知の送信、結果のログ記録など、複数のことを実行しようとするスキルは、テスト、デバッグ、正しい呼び出しが難しくなります。

ユースケースで複数のアクションが必要な場合は、それらのアクションを1つのスキルに含めるか、スキルのチェーンに含めるかを判断します。 適切な選択は、各アクションに独立した価値があるかどうかによって決まります:

• アクションが常に一緒に実行され、個別には意味を持たない: たとえば、作成アクションの直後に通知を行う場合は、1つのスキルとして内部で処理する必要があります。
• アクションに独立した価値がある: たとえば、レコードを作成し、その後必要に応じて通知を送信する場合は、ユーザー入力に基づいてGenieが連鎖させる個別のスキルにする必要があります。

アトミックの原則は、スキルが単純でなければならないという意味ではありません。 5つのSalesforceオブジェクトを呼び出して集約結果を返すアカウントサマリーを取得スキルは、内部的には複雑ですが、Genieの観点ではアトミックです。 実行することは1つです。 複雑さはレシピ内に閉じ込められています。

Genie間で再利用できるように設計する ​

スキルは任意のプロジェクト内の複数のGenieに割り当てることができます。 IT Genie向けに構築されたJiraでチケットを作成スキルは、従業員に代わってITチケットを作成する必要があるHR Genieにも割り当てることができます。 営業Genie向けに構築されたSalesforceでアカウントサマリーを取得スキルは、カスタマーサクセスGenieでも使用できます。

再利用を目的としたスキルを構築する場合は、次の点に留意してください:

• 可能な場合は汎用的な入力を使用する: ユーザーのメールを入力として受け取るスキルは、特定のユーザーのデータを取得するようハードコードされたスキルよりも再利用しやすくなります。 Genieやユースケースによって変わる可能性があるものは、すべてパラメーター化します。
• スキル内でGenie固有のロジックを避ける: 1つのGenieのユースケースにのみ適用されるロジックは、レシピにハードコードするのではなく、スキルの説明またはジョブの説明に含める必要があります。 フィルターがハードコードされたレシピは、フィルターパラメーターを受け取るレシピよりも再利用しにくくなります。
• スキルに汎用的な名前を付ける: Jiraでチケットを作成は再利用可能です。 IT Genie向けにJiraでITヘルプデスクチケットを作成は再利用可能ではありません。 名前は、そのスキルがどのGenie向けに構築されたかではなく、そのスキルが実行する内容を説明する必要があります。

外部システムを呼び出す前に入力を検証する ​

明らかなエラーを早期に検出するため、外部API呼び出しの前に、スキルの冒頭で入力検証ステップを追加します。 Workatoで実行される検証ステップは、外部システムからエラーを返すAPI呼び出しよりも高速で低コストです。

一般的な検証には次のものがあります:

• 必須フィールドの存在: 続行する前に、すべての必須フィールドが提供されていることを確認します。 必須フィールドが不足している場合は、Genieがユーザーに伝えられるエラーメッセージを返します。 例: I need the start date to submit the leave request. Could you provide that?
• 形式の検証: 日付フィールドが想定される形式であること、メールアドレスが有効なパターンに一致すること、および数値フィールドが想定範囲内であることを確認します。 日付が2026-04-14ではなくnext Mondayとして渡されると、API呼び出しが失敗する可能性があります。 API呼び出しの前にレシピ内でこれを検出すると、より明確なエラーメッセージを生成できます。
• ビジネスルールの検証: 書き込み操作を伴うスキルでは、APIを呼び出す前にビジネスルールを検証する必要があります。 開始日が過去の日付である休暇申請は、HRシステムによって拒否される前にフラグを付ける必要があります。 承認しきい値を超える割引は、直接適用するのではなく、承認ワークフローをトリガーする必要があります。

検証に失敗した場合は、Genieが意味のある形で解釈できない未加工のAPIエラーではなく、Genieが会話を続行してユーザーに入力の修正を求めるために使用できる、構造化されたエラーメッセージを返す必要があります。

Verified user access向けのスキル設計 ​

Verified user accessは、スキルの設計方法にいくつかの実践的な影響を与えます:

• 会話でユーザーにメールまたはIDを尋ねない: Verified user accessが有効な場合、ユーザーのIDはスキルトリガーコンテキストから利用できます。 ID関連の入力に関するフィールドヒントでは、次のように指定する必要があります: Use the authenticated user email from the Skill trigger context - don't ask the user for their email address。 会話内でユーザーに自身のIDを提供するよう求めることは、Verified user accessがある場合は不要であり、ない場合はセキュリティリスクになります。

• 初回認証エクスペリエンスを考慮して設計する: Verified user accessが有効なスキルをユーザーが初めてトリガーすると、認証を求められます。 これは想定された動作ですが、会話の途中でコネクションプロンプトが表示されると思っていなかったユーザーを驚かせる可能性があります。 ジョブの説明には、Genieがユーザーに事前に伝えるためのメモを含めることができます: Before using any skills that require your personal credentials, you may be asked to connect your account. This is a one-time step。

• Verified user accessを使用するスキルは非ビルダーユーザーアカウントでテストする: テストモードではビルダーのIDと認証情報が使用されます。 コネクションプロンプト、子コネクションの作成、スコープ付きデータ取得を含むVerified user accessの動作は、チャットインターフェイスから実際のエンドユーザーとしてGenieを操作することでのみ、完全にテストできます。 プロダクションユーザーにデプロイする前に、Verified user accessを使用するスキルを、非ビルダーのテストアカウントで必ずテストしてください。