- ワークフロー アクション コンポーネントをアプリに追加します。このために、ツールの
*-hsmeta.json設定ファイルを格納したworkflow-actionsディレクトリーをプロジェクトに含めます。作成する各ツールとワークフローアクションには、専用の*-hsmeta.json設定ファイルが必要です。 supportedClientsフィールドを介してAIエージェントでアクションが使用できるように設定します。
プロジェクトの設定
ツールを作成するには、hsproject.jsonでplatformVersionが2025.2に設定されている必要があります。このバージョンは、すべてのクイックスタートテンプレートで自動的に設定されますが、以前のバージョンのプロジェクトでは手動で更新する必要があります。
プロジェクトをバージョン2025.2にアップグレードする場合は、アプリの設定とその機能について新しい*-hsmeta.json設定ファイルの標準に準拠する必要があることに注意してください。
エージェントツールとカスタム ワークフロー アクションは、どちらもアプリのworkflow-actionsディレクトリーに格納されています。
エージェントツールの定義
ツールが機能できるようにするには、ツールの設定ファイルをworkflow-actionsディレクトリー内に配置する必要があります。エージェントツールの設定オプションはカスタム ワークフロー アクションと同じですが、supportedClientsフィールドにAGENTSクライアントが含まれている必要があります。
*でマークされたフィールドは必須です。
ベストプラクティス
エージェントツールを作成する際には、次のベストプラクティスのチェックリストを念頭に置いてください。- 最初に任意のフィールドを使用し、その後安定した場合にのみこれらのフィールドを必須に設定します。
- フィールドにラベルを付けて説明を作成する際には、人間とAIの両方を考慮します。
- AIによってツールがどのように解釈されるかを理解するため、最初は少数のエージェント指示を使用してテストを行います。
- ツールの焦点を維持し、フィールドの数に注意します。
- フィールドの説明を使用して、エージェントの創造性をコントロールします。
任意のフィールドを使用して開発を行う
アクティブな開発の際にアクションのフィールド(inputFields)を必須に設定しないでください。フィールドが必須に設定され、プロジェクトがアップロードされた後では、そのフィールドを削除または更新することができません。フィールドを必須に設定するのは、フィールドの詳細(nameやtypeなど)について確信できる場合のみにしてください。この制限の理由は、必須フィールドを変更すると、アクションを含むアクティブなワークフローが機能しなくなることにあります。
人間とAIの理解を促進する開発
actionName、inputFields、labelsは、その用途と実用性を人間とエージェントの両方に明確に伝える必要があります。これらのフィールドは特に、アクションを呼び出すタイミングとツールにデータを渡す方法を理解する目的でエージェントにより使用されます。ツールを作成する際には、LLMでは人間のユーザーに対する場合よりも明確な説明が必要になる可能性があることに注意してください。例えば、人間であればDateというラベルの付いたフィールドを直感的に理解できるかもしれませんが、LLMではEvent start date (YYYY-MM-DD)の方が適切なことがあります。
理想的には、エージェントがツールを使用するために追加の指示を必要としないように、ツールを作成する必要があります。ただし、フィールドの詳細だけではエージェントにとって不十分な場合があります。例えば、他のツールの出力に依存するツールを実行する場合の意図的な操作順序をエージェントが理解できないことがあります(例:「Eメールを送信」ツールが、最初に実行される「連絡先情報を取得」ツールに依存している場合)。
ツールを作成する際には、エージェントがツールを理解する仕組みをより深く理解するため、最初にエージェントの指示を追加せずにエージェントでツールをテストします。テストを行うことで、推論エンジンが単独で正しく動作するかどうか、追加の指示が必要かどうかを判断できます。
入力フィールドの数に注意する
エージェントは、ツールごとに多数の入力フィールド(最大26の固有の入力)を処理できます。ただし、ツールの入力フィールドの数が多いほど、actionName、inputField、labelの値を割り当てるときにより明確にする必要があります。ツールの効果と信頼性が最も高くなるのは、ツールが特定のタスクを対象として、限定的なパラメーターセットを使用して設計されている場合です。複雑な操作の場合、入力の数が多すぎる単一のツールよりも、複数の単純なツールを作成する方が効果的であるかどうかを検討してください。
エージェントの創造性と即興性をコントロールする
状況によっては、エージェントが創造的かつ即興的に対応するようにしたいことがあります。ただし、エージェントが即興的に対応しないことが必要な状況もあります。入力フィールド名、ラベル、説明を使用してLLMに指示することを試してみます。より厳密なガイダンスが必要な場合は、エージェントに対する指示を追加し、期待する内容を明確に設定します。 例えば、ブログ記事を生成し、1つのフィールドをブログ記事のタイトルにするというタスクをエージェントに与えるとします。エージェントにどの程度即興で対応してもらいたいかに応じて、フィールドに許容的なラベルを付けるか、またはより制限的なラベル付けることができます。- 許容的:
"Blog title" - 制限的:
"Blog title (must include the product name 'HubSpot CRM')"
- 許容的:
"Social post content" - 中程度:
"Social post content (keep under 280 characters)" - 制限的:
"Social post content (must mention our Q4 sale, include #HubSpot, and stay under 280 characters)"
エージェントツールのリクエストの発生元を確認する
エージェントがツールを使用してリクエストを行う際には、そのツールのactionUrlに対してPOSTリクエストを送信します。エージェントツールの呼び出しを認証するため、リクエストと共に送信されたX-HubSpot-Signatureヘッダーが検証されます。これは、HubSpotがWebhookリクエストの検証に使用するシステムと同じです。