最終更新日: 2025年9月11日
HubSpotエージェントは、ユーザーがタスクを実行する際にチャットできるAI搭載アシスタントです。各エージェントには、ユーザーの指示に従ってエージェントが使用する一連のアクション(ツール)が含まれています。開発者はエージェントの目的に応じて、明確に定義された特定のタスクを実行するカスタム エージェント ツールを作成できます。
実際には、ツールはエージェントコンテキストで使用できるように設定されたカスタム ワークフロー アクションです。ツールは複数のエージェントで使用できます。また、エージェントとワークフローの両方で機能するように設定できます。
エージェントツールを作成する方法の概要を以下に示します。
- ワークフロー アクション コンポーネントをアプリに追加します。このために、ツールの
*-hsmeta.json
設定ファイルを格納したworkflow-actions
ディレクトリーをプロジェクトに含めます。作成する各ツールとワークフローアクションには、専用の*-hsmeta.json
設定ファイルが必要です。 supportedClients
フィールドを介してAIエージェントでアクションが使用できるように設定します。
プロジェクトの設定
ツールを作成するには、hsproject.json
でplatformVersion
が2025.2
に設定されている必要があります。このバージョンは、すべてのクイックスタートテンプレートで自動的に設定されますが、以前のバージョンのプロジェクトでは手動で更新する必要があります。
プロジェクトをバージョン2025.2
にアップグレードする場合は、アプリの設定とその機能について新しい*-hsmeta.json
設定ファイルの標準に準拠する必要があることに注意してください。
エージェントツールとカスタム ワークフロー アクションは、どちらもアプリのworkflow-actions
ディレクトリーに格納されています。
エージェントツールの定義
ツールが機能できるようにするには、ツールの設定ファイルをworkflow-actions
ディレクトリー内に配置する必要があります。エージェントツールの設定オプションはカスタム ワークフロー アクションと同じですが、supportedClients
フィールドにAGENTS
クライアントが含まれている必要があります。
*でマークされたフィールドは必須です。
フィールド | 型 | 説明 |
---|---|---|
uid * | 文字列 | ワークフローアクションの内部固有ID。 |
type * | 文字列 | コンポーネントのタイプ。この場合はworkflow-action にする必要があります。 |
actionUrl * | 文字列 | ツールによるPOST リクエストの送信先のURL。このURLは、一般公開されているエンドポイントである必要があります。また、開発者プロジェクト内で定義したサーバーレス関数は指定できません。 |
toolType * | 文字列 | ツール機能のカテゴリー。次のいずれかになります。
|
llmDescription * | 文字列 | LLMがツールの機能を理解するのに役立つ説明。 |
isPublished | ブール値 | アプリをインストールしたアカウントに定義が表示されるかどうかを決定します。既定では、false に設定されています。 |
supportedClients * | 配列 | カスタム ワークフロー アクションがサポートするクライアントを指定するオブジェクトの配列。配列内の各オブジェクトには、クライアントのタイプを示す文字列値を持つclient キーを指定する必要があります。値には次のものがあります。
|
inputFields | 配列 | ユーザーが入力フィールドに入力した値。フィールドの数に関するベストプラクティスについて詳細をご確認ください。 |
typeDefinition.name | 文字列 | 入力フィールドの名前またはキー。 |
typeDefinition.type | 文字列 | 入力フィールドに入力される値のタイプ。 |
typeDefinition.fieldType | 文字列 | ワークフローを作成するユーザーに対して表示されるフィールドのタイプ。 |
typeDefinition.options | 配列 | 列挙型の場合、このフィールドでオプションのリストを指定します。各オプションには、ユーザーが入力した情報に基づくvalue と、ワークフローツール内でオプションを識別するlabel が必要です。 |
inputFieldDependencies | 配列 | dependencyType に基づいて2つ以上の入力間の関係を定義するルールのリスト。こちらの例で詳細をご確認ください。 |
labels.<locale> * | 文字列 | ロケール定義にマッピングされるロケールキー。少なくとも、英語のラベル(en )とその定義を定義する必要があります。 |
labels.<locale>.inputFieldDescriptions | オブジェクト | アクションに関する入力内容の詳細を定義するオブジェクト。上記の例では、このオブジェクトにmessage フィールドとpriority フィールドが含まれています。 |
labels.<locale>.inputFieldOptionLabels | オブジェクト | 入力フィールドにオプションがある場合に必要となるオブジェクト。オプションの値またはラベルをキーとして使用して、入力フィールドのオプションラベルのマップを提供します。 |
labels.<locale>.outputFieldLabels | オブジェクト | outputFields の定義を、ワークフローツールに表示される、該当するラベルにマッピングするオブジェクト。 |
labels.<locale>.actionName * | 文字列 | ワークフローエディターの[アクションを選択]__パネルに表示するアクションの名前。 |
labels.<locale>.appDisplayName * | 文字列 | アプリの全てのアクションが表示される、[アクションを選択]__パネルのセクションの名前。複数のアクションでappDisplayName が定義されている場合、最初に見つかった名前が使用されます。 |
labels.<locale>.actionCardContent | 文字列 | アクションのカードに表示する説明の要約。 |
labels.<locale>.executionRules | オブジェクト | executionRules の定義を、ワークフローの履歴に実行結果として表示されるメッセージにマッピングするオブジェクト。 |
objectTypes | 配列 | このアクションで処理できるCRMオブジェクトタイプ。空白の場合、全てのオブジェクトタイプで当該アクションを使用できます。 |
outputFields | 配列 | アクションによって出力される値。この値は、エージェントまたはワークフローの後続アクションで使用できます。カスタムアクションの出力はゼロにすることも、1つまたは複数にすることもできます。 |
executionRules | オブジェクト | ワークフローを作成するユーザーに対し、貴社のサービスからのエラーを示すために指定できる定義のリスト。 |
ベストプラクティス
エージェントツールを作成する際には、次のベストプラクティスのチェックリストを念頭に置いてください。- 最初に任意のフィールドを使用し、その後安定した場合にのみこれらのフィールドを必須に設定します。
- フィールドにラベルを付けて説明を作成する際には、人間とAIの両方を考慮します。
- AIによってツールがどのように解釈されるかを理解するため、最初は少数のエージェント指示を使用してテストを行います。
- ツールの焦点を維持し、フィールドの数に注意します。
- フィールドの説明を使用して、エージェントの創造性をコントロールします。
注:以下のガイダンスの一部には、エージェントツールのテストに関する情報が含まれていますが、これらのテスト機能は現在開発段階です。エージェントツールのドキュメントは、テスト手法が利用可能になった時点で更新されます。
任意のフィールドを使用して開発を行う
アクティブな開発の際にアクションのフィールド(inputFields
)を必須に設定しないでください。フィールドが必須に設定され、プロジェクトがアップロードされた後では、そのフィールドを削除または更新することができません。フィールドを必須に設定するのは、フィールドの詳細(name
やtype
など)について確信できる場合のみにしてください。この制限の理由は、必須フィールドを変更すると、アクションを含むアクティブなワークフローが機能しなくなることにあります。
人間とAIの理解を促進する開発
actionName
、inputFields
、labels
は、その用途と実用性を人間とエージェントの両方に明確に伝える必要があります。これらのフィールドは特に、アクションを呼び出すタイミングとツールにデータを渡す方法を理解する目的でエージェントにより使用されます。ツールを作成する際には、LLMでは人間のユーザーに対する場合よりも明確な説明が必要になる可能性があることに注意してください。例えば、人間であればDate
というラベルの付いたフィールドを直感的に理解できるかもしれませんが、LLMではEvent start date (YYYY-MM-DD)
の方が適切なことがあります。
理想的には、エージェントがツールを使用するために追加の指示を必要としないように、ツールを作成する必要があります。ただし、フィールドの詳細だけではエージェントにとって不十分な場合があります。例えば、他のツールの出力に依存するツールを実行する場合の意図的な操作順序をエージェントが理解できないことがあります(例:「Eメールを送信」ツールが、最初に実行される「連絡先情報を取得」ツールに依存している場合)。
ツールを作成する際には、エージェントがツールを理解する仕組みをより深く理解するため、最初にエージェントの指示を追加せずにエージェントでツールをテストします。テストを行うことで、推論エンジンが単独で正しく動作するかどうか、追加の指示が必要かどうかを判断できます。
入力フィールドの数に注意する
エージェントは、ツールごとに多数の入力フィールド(最大26の固有の入力)を処理できます。ただし、ツールの入力フィールドの数が多いほど、actionName
、inputField
、label
の値を割り当てるときにより明確にする必要があります。ツールの効果と信頼性が最も高くなるのは、ツールが特定のタスクを対象として、限定的なパラメーターセットを使用して設計されている場合です。複雑な操作の場合、入力の数が多すぎる単一のツールよりも、複数の単純なツールを作成する方が効果的であるかどうかを検討してください。
注:将来的に、大量の入力を処理するエージェントの品質に関するフィードバックに基づいて、HubSpotが入力の数を制限する可能性があります。
エージェントの創造性と即興性をコントロールする
状況によっては、エージェントが創造的かつ即興的に対応するようにしたいことがあります。ただし、エージェントが即興的に対応しないことが必要な状況もあります。入力フィールド名、ラベル、説明を使用して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リクエストの検証に使用するシステムと同じです。
注:シークレットやAPIキーの入力フィールドは作成しないでください。これは、LLMに対する指示でシークレット/APIキーを与える必要があるか、またはLLMが別のツールからシークレット/APIキーを受け取る必要がある場合には特に、安全でなく、意図された認証パターンではないためです。