エージェントツールを作成する

HubSpotでは、ユーザーの指示に従ってさまざまなアクションを実行するAIエージェントを作成できます。例えば、毎朝その日に予定されているミーティングに関するメモを記載したEメールを送信するエージェントを作成できます。エージェントはこうしたタスクを実行するために、エージェントツールを利用します。エージェントツールはプログラミング言語の関数のようなもので、ユーザーから渡されたパラメーターを取り、出力を返します。HubSpotでのエージェントツールは、MCP（モデルコンテキストプロトコル）でのツールの概念に似ています。つまり、AIが特定のジョブを実行できるように、エージェントツールでAPI呼び出し、LLMステップ、およびその他のサポートコンテキストをパッケージ化します。これらのツールは特定の明確に定義されたタスクを実行するように設計され、それぞれに、データベースのクエリー、CRUD（作成、読み取り、更新、削除）操作の実行、生成AIを使用したコンテンツの要約といったタスクを実行します。実装の観点からすると、エージェントツールはカスタムワークフローアクションの拡張バージョンであり、HubSpotの開発者プロジェクトフレームワークを使用して構築します。このチュートリアルでは、エージェントツールの構築を開始する方法を説明します。

前提条件

開始する前に、次の準備作業を行う必要があります。

npm i -g @hubspot/cli@nextを実行して、HubSpot CLIの最新バージョンをインストールします。
ベータ版にオプトインした開発者アカウント内で、開発者テストアカウントを作成します。
CLIを使用してテストアカウントを認証するために、ターミナルでhs authコマンドを実行します。

プロジェクトを作成する

ゼロから作成する場合は、まず、新しいプロジェクトを作成する必要があります。既存のプロジェクトを使用する場合は、次のセクションにスキップしてかまいません（バージョン2025.2のプロジェクトが必要です）。新しいプロジェクトを作成する場合は、次の手順に従います。

ボイラープレートとなるクイックスタートテンプレートのいずれかを基に新しいプロジェクトを作成するには、ターミナルで以下のコマンドを実行します。

hs project create --platform-version 2025.2

ターミナルのプロンプトに従ってプロジェクトの名前と場所を設定し、テンプレートを選択します。予定しているアプリの配布方法に応じて、複数のテンプレートオプションの中から選択できるようになっています。このチュートリアルでは、［Getting stated project with marketplace app（マーケットプレイスアプリを使用したプロジェクトの開始）］****テンプレートを選択します。
プロジェクトテンプレートが作業ディレクトリーにダウンロードされます。このディレクトリーで、その内容を確認できます。

このプロジェクトテンプレートには、いくつかのサンプルアプリ機能を備えたアプリを含むプロジェクトをアップロードするために必要な全てのファイルが揃っています。サンプルアプリ機能には、ボイラープレートアプリカード、Webhook、ワークフローアクションなどがあります。このチュートリアルには、これらのコンポーネントは必要ありませんが、後で試してみる場合に備えてコンポーネントを確認しておくと役立ちます。

プロジェクトにエージェントツールを追加する

実際のところ、エージェントツールはエージェントのコンテキストに合わせて設定されたカスタムワークフローアクションです。エージェントがこれらのツールを実行できるようにするには、ワークフローでアクションを実行する仕組みと同様に、supportedClientsフィールドを使用してカスタムワークフローアクションを有効にし、エージェントで使用できるようにする必要があります。

workflow-actionsディレクトリー内に、ツールの設定ファイルとして新しいJSONファイルを作成します。ファイルには任意の名前を付けることができますが、名前の末尾は-hsmeta.jsonにする必要があります（例：my-agent-tool-hsmeta.json）。
エージェントツールのリファレンスドキュメントに従って、アクション設定を作成します。以下のコード例に示されているように、必ず、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": false
      }
    ],
    "labels": {
      "en": {
        "actionName": "My custom agent tool",
        "actionDescription": "A description of the tool.",
        "actionCardContent": "Send a notification",
        "inputFieldLabels": {
          "message": "Notification Message"
        },
        "inputFieldDescriptions": {
          "message": "Enter the message to be sent in the notification"
        }
      }
    },
    "objectTypes": ["CONTACT"]
  }
}

ツールを構築する際には、次の点に留意してください。

活発に開発を進めているときは、入力フィールドを必須に設定しないでください。必須フィールドは、アップロード後に更新または削除することができないためです。
公開エンドポイントに対するリクエストは、POSTリクエストとして送信されます。

テストアカウントにアップロードする準備ができたら、ファイルを保存し、hs project uploadを実行します。新しいプロジェクトを作成するところから始めた場合は、yを押してアカウント内にそのプロジェクトを作成するよう求められます。

注：

HubSpotでは現在も、エージェントツールのテストを可能にするための機能の開発を積極的に進めています。これらのテスト機能が利用可能になり次第、このページが更新されて手順が追加される予定です。

アプリを作成

機能を追加

HubSpotマーケットプレイスに公開

エージェントツールを作成する

前提条件

注：

​前提条件

​注：

前提条件

注：