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

プロジェクトの設定

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

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

ツールが機能できるようにするには、ツールの設定ファイルをworkflow-actionsディレクトリー内に配置する必要があります。エージェントツールの設定オプションはカスタム ワークフロー アクションと同じですが、supportedClientsフィールドにAGENTSクライアントが含まれている必要があります。
{
  "uid": "agent_tool_action",
  "type": "workflow-action",
  "config": {
    "actionUrl": "https://example.com",
    "toolType": "GET_DATA",
    "llmDescription": "A description that helps the LLM understand what this tool does.",
    "isPublished": false,
    "supportedClients": [
      {
        "client": "AGENTS"
      },
      {
        "client": "WORKFLOWS"
      }
    ],
    "inputFields": [
      {
        "typeDefinition": {
          "name": "message",
          "type": "string",
          "fieldType": "textarea"
        },
        "supportedValueTypes": ["STATIC_VALUE"],
        "isRequired": true
      },
      {
        "typeDefinition": {
          "name": "priority",
          "type": "enumeration",
          "fieldType": "select",
          "options": [
            {
              "value": "high",
              "label": "High Priority"
            },
            {
              "value": "normal",
              "label": "Normal Priority"
            },
            {
              "value": "low",
              "label": "Low Priority"
            }
          ]
        },
        "supportedValueTypes": ["STATIC_VALUE"],
        "isRequired": true
      }
    ],
    "labels": {
      "en": {
        "actionName": "My custom agent tool",
        "actionDescription": "A description of the tool.",
        "actionCardContent": "Send {{priority}} priority notification",
        "inputFieldLabels": {
          "message": "Notification Message",
          "priority": "Priority Level"
        },
        "inputFieldDescriptions": {
          "message": "Enter the message to be sent in the notification",
          "priority": "Select the priority level for this notification"
        }
      }
    },
    "objectTypes": ["CONTACT"]
  }
}

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

フィールド説明
uid*文字列ワークフローアクションの内部固有ID。
type*文字列コンポーネントのタイプ。この場合はworkflow-actionにする必要があります。
actionUrl*文字列ツールによるPOSTリクエストの送信先のURL。このURLは、一般公開されているエンドポイントである必要があります。また、開発者プロジェクト内で定義したサーバーレス関数は指定できません。
toolType*文字列ツール機能のカテゴリー。次のいずれかになります。
  • GET_DATA:HubSpotまたは外部ソースから情報を取得します。
  • GENERATE:入力された内容に基づいて、コンテンツ、要約、分析、提案を生成します。
  • TAKE_ACTION:メモの作成や担当者へのタスクの割り当てなどのCRMアクションを実行します。
llmDescription*文字列LLMがツールの機能を理解するのに役立つ説明。
isPublishedブール値アプリをインストールしたアカウントに定義が表示されるかどうかを決定します。既定では、falseに設定されています。
supportedClients*配列カスタム ワークフロー アクションがサポートするクライアントを指定するオブジェクトの配列。配列内の各オブジェクトには、クライアントのタイプを示す文字列値を持つclientキーを指定する必要があります。値には次のものがあります。
  • WORKFLOWS:ワークフローのアクションを有効にします。
  • AGENTS:エージェントのアクションを有効にします。
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)を必須に設定しないでください。フィールドが必須に設定され、プロジェクトがアップロードされた後では、そのフィールドを削除または更新することができません。フィールドを必須に設定するのは、フィールドの詳細(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キーを受け取る必要がある場合には特に、安全でなく、意図された認証パターンではないためです。