> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.jp/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> このチュートリアルに従って、エージェントツールを構築しましょう。エージェントツールとは、AIエージェントに合わせてカスタマイズされたワークフローアクションのことです。

<style>
  {`
    .table-key, .table-key div, .table-key p {
      margin: 0;
      font-size: 14px;
    }
    code {
      text-wrap:nowrap!important;
    }
    td code {
      text-wrap: wrap!important;
    }
    `}
</style>

HubSpotでは、ユーザーの指示に従ってさまざまなアクションを実行するAIエージェントを作成できます。例えば、毎朝その日に予定されているミーティングに関するメモを記載したEメールを送信するエージェントを作成できます。

エージェントはこうしたタスクを実行するために、エージェントツールを利用します。エージェントツールはプログラミング言語の関数のようなもので、ユーザーから渡されたパラメーターを取り、出力を返します。HubSpotでのエージェントツールは、MCP（モデル コンテキスト プロトコル）でのツールの概念に似ています。つまり、AIが特定のジョブを実行できるように、エージェントツールでAPI呼び出し、LLMステップ、およびその他のサポートコンテキストをパッケージ化します。これらのツールは特定の明確に定義されたタスクを実行するように設計され、それぞれに、データベースのクエリー、CRUD（作成、読み取り、更新、削除）操作の実行、生成AIを使用したコンテンツの要約といったタスクを実行します。

実装の観点からすると、エージェントツールはカスタム ワークフロー アクションの拡張バージョンであり、HubSpotの開発者プロジェクトフレームワークを使用して構築します。このチュートリアルでは、エージェントツールの構築を開始する方法を説明します。

## 前提条件

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

* `npm i -g @hubspot/cli@next`を実行して、HubSpot CLIの最新バージョンをインストールします。
* ベータ版にオプトインした開発者アカウント内で、[開発者テストアカウント](/getting-started/account-types#developer-test-accounts)を作成します。
* CLIを使用してテストアカウントを認証するために、ターミナルで[`hs auth`コマンド](/developer-tooling/local-development/hubspot-cli/reference#authenticate-an-account)を実行します。

<Steps>
  <Step title="プロジェクトを作成する">
    ゼロから作成する場合は、まず、新しいプロジェクトを作成する必要があります。既存のプロジェクトを使用する場合は、[次のセクションにスキップ](#2.-add-an-agent-tool-to-the-project)してかまいません（バージョン`2025.2`のプロジェクトが必要です）。

    新しいプロジェクトを作成する場合は、次の手順に従います。

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

    ```shell theme={null}
    hs project create --platform-version 2025.2
    ```

    2. ターミナルのプロンプトに従ってプロジェクトの名前と場所を設定し、テンプレートを選択します。予定しているアプリの[配布](/apps/developer-platform/build-apps/app-configuration#distribution)方法に応じて、複数のテンプレートオプションの中から選択できるようになっています。このチュートリアルでは、［Getting stated project with marketplace app（マーケットプレイスアプリを使用したプロジェクトの開始）］\*\*\*\*テンプレートを選択します。

    3. プロジェクトテンプレートが作業ディレクトリーにダウンロードされます。このディレクトリーで、その内容を確認できます。

    このプロジェクトテンプレートには、いくつかのサンプルアプリ機能を備えたアプリを含むプロジェクトをアップロードするために必要な全てのファイルが揃っています。サンプルアプリ機能には、ボイラープレート [アプリ カード](/apps/developer-platform/add-features/ui-extensibility/app-cards/create-an-app-card)、[Webhook](/apps/developer-platform/add-features/configure-webhooks)、[ワークフローアクション](/apps/developer-platform/add-features/custom-workflow-actions)などがあります。このチュートリアルには、これらのコンポーネントは必要ありませんが、後で試してみる場合に備えてコンポーネントを確認しておくと役立ちます。
  </Step>

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

    * `workflow-actions`ディレクトリー内に、ツールの設定ファイルとして新しいJSONファイルを作成します。ファイルには任意の名前を付けることができますが、名前の末尾は`-hsmeta.json`にする必要があります（例：`my-agent-tool-hsmeta.json`）。
    * [エージェントツールのリファレンスドキュメント](/apps/developer-platform/add-features/agent-tools/reference)に従って、アクション設定を作成します。以下のコード例に示されているように、必ず、`supportedClients`フィールドに`AGENTS`クライアントを含めてください。

    ```json theme={null}
    {
      "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"]
      }
    }
    ```

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

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

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

    <Warning>
      ### 注：

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