Skip to main content
HubSpotエージェントは、ユーザーがタスクを実行する際にチャットできるAI搭載アシスタントです。各エージェントには、ユーザーの指示に従ってエージェントが使用する一連のアクション(ツール)が含まれています。開発者はエージェントの目的に応じて、明確に定義された特定のタスクを実行するカスタム エージェント ツールを作成できます。 実際には、ツールはエージェントコンテキストで使用できるように設定されたカスタム ワークフロー アクションです。ツールは複数のエージェントで使用できます。また、エージェントとワークフローの両方で機能するように設定できます。 エージェントツールを作成する方法の概要を以下に示します。
  • ワークフロー アクション コンポーネントをアプリに追加します。このために、ツールの*-hsmeta.json設定ファイルを格納したworkflow-actionsディレクトリーをプロジェクトに含めます。作成する各ツールとワークフローアクションには、専用の*-hsmeta.json設定ファイルが必要です。
  • supportedClientsフィールドを介してAIエージェントでアクションが使用できるように設定します。
ツールを作成する際には、高品質のパフォーマンスを保証するための一連のベストプラクティスにも留意する必要があります。

プロジェクトの設定

ツールを作成するには、hsproject.jsonplatformVersion2025.2に設定されている必要があります。このバージョンは、すべてのクイックスタートテンプレートで自動的に設定されますが、以前のバージョンのプロジェクトでは手動で更新する必要があります。 プロジェクトをバージョン2025.2にアップグレードする場合は、アプリの設定とその機能について新しい*-hsmeta.json設定ファイルの標準に準拠する必要があることに注意してください。 エージェントツールとカスタム ワークフロー アクションは、どちらもアプリのworkflow-actionsディレクトリーに格納されています。

エージェントツールの定義

ツールが機能できるようにするには、ツールの設定ファイルをworkflow-actionsディレクトリー内に配置する必要があります。エージェントツールの設定オプションはカスタム ワークフロー アクションと同じですが、supportedClientsフィールドにAGENTSクライアントが含まれている必要があります。

*でマークされたフィールドは必須です。

ベストプラクティス

エージェントツールを作成する際には、次のベストプラクティスのチェックリストを念頭に置いてください。
  • 最初に任意のフィールドを使用し、その後安定した場合にのみこれらのフィールドを必須に設定します。
  • フィールドにラベルを付けて説明を作成する際には、人間とAIの両方を考慮します。
  • AIによってツールがどのように解釈されるかを理解するため、最初は少数のエージェント指示を使用してテストを行います。
  • ツールの焦点を維持し、フィールドの数に注意します。
  • フィールドの説明を使用して、エージェントの創造性をコントロールします。
それぞれのベストプラクティスについて、以下のセクションで詳しく説明します。
:以下のガイダンスの一部には、エージェントツールのテストに関する情報が含まれていますが、これらのテスト機能は現在開発段階です。エージェントツールのドキュメントは、テスト手法が利用可能になった時点で更新されます。

任意のフィールドを使用して開発を行う

アクティブな開発の際にアクションのフィールド(inputFields)を必須に設定しないでください。フィールドが必須に設定され、プロジェクトがアップロードされた後では、そのフィールドを削除または更新することができません。フィールドを必須に設定するのは、フィールドの詳細(nametypeなど)について確信できる場合のみにしてください。この制限の理由は、必須フィールドを変更すると、アクションを含むアクティブなワークフローが機能しなくなることにあります。

人間とAIの理解を促進する開発

actionNameinputFieldslabelsは、その用途と実用性を人間とエージェントの両方に明確に伝える必要があります。これらのフィールドは特に、アクションを呼び出すタイミングとツールにデータを渡す方法を理解する目的でエージェントにより使用されます。ツールを作成する際には、LLMでは人間のユーザーに対する場合よりも明確な説明が必要になる可能性があることに注意してください。例えば、人間であればDateというラベルの付いたフィールドを直感的に理解できるかもしれませんが、LLMではEvent start date (YYYY-MM-DD)の方が適切なことがあります。 理想的には、エージェントがツールを使用するために追加の指示を必要としないように、ツールを作成する必要があります。ただし、フィールドの詳細だけではエージェントにとって不十分な場合があります。例えば、他のツールの出力に依存するツールを実行する場合の意図的な操作順序をエージェントが理解できないことがあります(例:「Eメールを送信」ツールが、最初に実行される「連絡先情報を取得」ツールに依存している場合)。 ツールを作成する際には、エージェントがツールを理解する仕組みをより深く理解するため、最初にエージェントの指示を追加せずにエージェントでツールをテストします。テストを行うことで、推論エンジンが単独で正しく動作するかどうか、追加の指示が必要かどうかを判断できます。

入力フィールドの数に注意する

エージェントは、ツールごとに多数の入力フィールド(最大26の固有の入力)を処理できます。ただし、ツールの入力フィールドの数が多いほど、actionNameinputFieldlabelの値を割り当てるときにより明確にする必要があります。ツールの効果と信頼性が最も高くなるのは、ツールが特定のタスクを対象として、限定的なパラメーターセットを使用して設計されている場合です。複雑な操作の場合、入力の数が多すぎる単一のツールよりも、複数の単純なツールを作成する方が効果的であるかどうかを検討してください。
:将来的に、大量の入力を処理するエージェントの品質に関するフィードバックに基づいて、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キーを受け取る必要がある場合には特に、安全でなく、意図された認証パターンではないためです。
最終更新日 2026年2月10日