> ## 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 {
      word-break:keep-all!important;
    }
    td code {
      text-wrap: wrap!important;
    }
    `}
</style>

HubSpotエージェントは、ユーザーがタスクを実行する際にチャットできるAI搭載アシスタントです。各エージェントには、ユーザーの指示に従ってエージェントが使用する一連のアクション（ツール）が含まれています。開発者はエージェントの目的に応じて、明確に定義された特定のタスクを実行するカスタム エージェント ツールを作成できます。

実際には、ツールはエージェントコンテキストで使用できるように設定されたカスタム ワークフロー アクションです。ツールは複数のエージェントで使用できます。また、エージェントとワークフローの両方で機能するように設定できます。

エージェントツールを作成する方法の概要を以下に示します。

* ワークフロー アクション コンポーネントをアプリに追加します。このために、ツールの`*-hsmeta.json`設定ファイルを格納した`workflow-actions`[ディレクトリーをプロジェクトに](#project-setup)含めます。作成する各ツールとワークフローアクションには、専用の`*-hsmeta.json`設定ファイルが必要です。
* `supportedClients`フィールドを介してAIエージェントで[アクションが使用できるように設定](#agent-tool-definition)します。

ツールを作成する際には、高品質のパフォーマンスを保証するための一連の[ベストプラクティス](#best-practices)にも留意する必要があります。

## プロジェクトの設定

ツールを作成するには、`hsproject.json`で`platformVersion`が`2025.2`に設定されている必要があります。このバージョンは、すべての[クイックスタートテンプレート](/apps/developer-platform/build-apps/create-an-app)で自動的に設定されますが、以前のバージョンのプロジェクトでは手動で更新する必要があります。

プロジェクトをバージョン`2025.2`にアップグレードする場合は、[アプリの設定](/apps/developer-platform/build-apps/app-configuration)とその機能について新しい`*-hsmeta.json`設定ファイルの標準に準拠する必要があることに注意してください。

エージェントツールとカスタム ワークフロー アクションは、どちらもアプリの`workflow-actions`ディレクトリーに格納されています。

```shell theme={null}
├──src
│   ├── hsproject.json
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── workflow-actions/
│   │     └── agent-tool-action-hsmeta.json
└──
```

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

ツールが機能できるようにするには、ツールの設定ファイルを`workflow-actions`ディレクトリー内に配置する必要があります。エージェントツールの設定オプションは[カスタム ワークフロー アクション](/apps/developer-platform/add-features/custom-workflow-actions#custom-workflow-action-definition)と同じですが、`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": 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"]
  }
}
```

<p className="table-key">
  <span style={{ color: 'red' }}>\*</span>でマークされたフィールドは必須です。
</p>

| フィールド                                                                 | 型      | 説明                                                                                                                                                                                                          |
| --------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uid`<span style={{color:"red"}}>\*</span>                            | 文字列    | ワークフローアクションの内部固有ID。                                                                                                                                                                                         |
| `type`<span style={{color:"red"}}>\*</span>                           | 文字列    | コンポーネントのタイプ。この場合は`workflow-action`にする必要があります。                                                                                                                                                               |
| `actionUrl`<span style={{color:"red"}}>\*</span>                      | 文字列    | ツールによる`POST`リクエストの送信先のURL。このURLは、一般公開されているエンドポイントである必要があります。また、開発者プロジェクト内で定義したサーバーレス関数は指定できません。                                                                                                             |
| `toolType`<span style={{color:"red"}}>\*</span>                       | 文字列    | ツール機能のカテゴリー。次のいずれかになります。<ul><li>`GET_DATA`：HubSpotまたは外部ソースから情報を取得します。</li><li>`GENERATE`：入力された内容に基づいて、コンテンツ、要約、分析、提案を生成します。</li><li>`TAKE_ACTION`：メモの作成や担当者へのタスクの割り当てなどのCRMアクションを実行します。</li></ul>           |
| `llmDescription`<span style={{color:"red"}}>\*</span>                 | 文字列    | LLMがツールの機能を理解するのに役立つ説明。                                                                                                                                                                                     |
| `isPublished`                                                         | ブール値   | アプリをインストールしたアカウントに定義が表示されるかどうかを決定します。既定では、`false`に設定されています。                                                                                                                                                 |
| `supportedClients`<span style={{color:"red"}}>\*</span>               | 配列     | カスタム ワークフロー アクションがサポートするクライアントを指定するオブジェクトの配列。配列内の各オブジェクトには、クライアントのタイプを示す文字列値を持つ`client`キーを指定する必要があります。値には次のものがあります。<ul><li>`WORKFLOWS`：ワークフローのアクションを有効にします。</li><li>`AGENTS`：エージェントのアクションを有効にします。</li></ul> |
| `inputFields`                                                         | 配列     | ユーザーが入力フィールドに入力した値。[フィールドの数に関するベストプラクティス](#be-mindful-of-the-number-of-input-fields)について詳細をご確認ください。                                                                                                         |
| `typeDefinition.name`                                                 | 文字列    | 入力フィールドの名前またはキー。                                                                                                                                                                                            |
| `typeDefinition.type`                                                 | 文字列    | 入力フィールドに入力される値のタイプ。                                                                                                                                                                                         |
| `typeDefinition.fieldType`                                            | 文字列    | ワークフローを作成するユーザーに対して表示されるフィールドのタイプ。                                                                                                                                                                          |
| `typeDefinition.options`                                              | 配列     | 列挙型の場合、このフィールドでオプションのリストを指定します。各オプションには、ユーザーが入力した情報に基づく`value`と、ワークフローツール内でオプションを識別する`label`が必要です。                                                                                                          |
| `inputFieldDependencies`                                              | 配列     | `dependencyType`に基づいて2つ以上の入力間の関係を定義するルールのリスト。[こちらの例](/api-reference/automation-actions-v4-v4/guide#example-%233)で詳細をご確認ください。                                                                                |
| `labels.<locale>`<span style={{color:"red"}}>\*</span>                | 文字列    | ロケール定義にマッピングされるロケールキー。少なくとも、英語のラベル（`en`）とその定義を定義する必要があります。                                                                                                                                                  |
| `labels.<locale>.inputFieldDescriptions`                              | オブジェクト | アクションに関する入力内容の詳細を定義するオブジェクト。上記の例では、このオブジェクトに`message`フィールドと`priority`フィールドが含まれています。                                                                                                                         |
| `labels.<locale>.inputFieldOptionLabels`                              | オブジェクト | 入力フィールドにオプションがある場合に必要となるオブジェクト。オプションの値またはラベルをキーとして使用して、入力フィールドのオプションラベルのマップを提供します。                                                                                                                          |
| `labels.<locale>.outputFieldLabels`                                   | オブジェクト | `outputFields`の定義を、ワークフローツールに表示される、該当するラベルにマッピングするオブジェクト。                                                                                                                                                   |
| `labels.<locale>.actionName`<span style={{color:"red"}}>\*</span>     | 文字列    | ワークフローエディターの［アクションを選択］\_\_パネルに表示するアクションの名前。                                                                                                                                                                 |
| `labels.<locale>.appDisplayName`<span style={{color:"red"}}>\*</span> | 文字列    | アプリの全てのアクションが表示される、［アクションを選択］\_\_パネルのセクションの名前。複数のアクションで`appDisplayName`が定義されている場合、最初に見つかった名前が使用されます。                                                                                                        |
| `labels.<locale>.actionCardContent`                                   | 文字列    | アクションのカードに表示する説明の要約。                                                                                                                                                                                        |
| `labels.<locale>.executionRules`                                      | オブジェクト | `executionRules`の定義を、ワークフローの履歴に実行結果として表示されるメッセージにマッピングするオブジェクト。                                                                                                                                             |
| `objectTypes`                                                         | 配列     | このアクションで処理できるCRMオブジェクトタイプ。空白の場合、全てのオブジェクトタイプで当該アクションを使用できます。                                                                                                                                                |
| `outputFields`                                                        | 配列     | アクションによって出力される値。この値は、エージェントまたはワークフローの後続アクションで使用できます。カスタムアクションの出力はゼロにすることも、1つまたは複数にすることもできます。                                                                                                                |
| `executionRules`                                                      | オブジェクト | ワークフローを作成するユーザーに対し、貴社のサービスからのエラーを示すために指定できる定義のリスト。                                                                                                                                                          |

## ベストプラクティス

エージェントツールを作成する際には、次のベストプラクティスのチェックリストを念頭に置いてください。

* 最初に任意のフィールドを使用し、その後安定した場合にのみこれらのフィールドを必須に設定します。
* フィールドにラベルを付けて説明を作成する際には、人間とAIの両方を考慮します。
* AIによってツールがどのように解釈されるかを理解するため、最初は少数のエージェント指示を使用してテストを行います。
* ツールの焦点を維持し、フィールドの数に注意します。
* フィールドの説明を使用して、エージェントの創造性をコントロールします。

それぞれのベストプラクティスについて、以下のセクションで詳しく説明します。

<Warning>
  **注**:

  以下のガイダンスの一部には、エージェントツールのテストに関する情報が含まれていますが、これらのテスト機能は現在開発段階です。エージェントツールのドキュメントは、テスト手法が利用可能になった時点で更新されます。
</Warning>

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

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

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

`actionName`、`inputFields`、`labels`は、その用途と実用性を人間とエージェントの両方に明確に伝える必要があります。これらのフィールドは特に、アクションを呼び出すタイミングとツールにデータを渡す方法を理解する目的でエージェントにより使用されます。ツールを作成する際には、LLMでは人間のユーザーに対する場合よりも明確な説明が必要になる可能性があることに注意してください。例えば、人間であれば`Date`というラベルの付いたフィールドを直感的に理解できるかもしれませんが、LLMでは`Event start date (YYYY-MM-DD)`の方が適切なことがあります。

理想的には、エージェントがツールを使用するために追加の指示を必要としないように、ツールを作成する必要があります。ただし、フィールドの詳細だけではエージェントにとって不十分な場合があります。例えば、他のツールの出力に依存するツールを実行する場合の意図的な操作順序をエージェントが理解できないことがあります（例：「Eメールを送信」ツールが、最初に実行される「連絡先情報を取得」ツールに依存している場合）。

ツールを作成する際には、エージェントがツールを理解する仕組みをより深く理解するため、最初にエージェントの指示を追加せずにエージェントでツールをテストします。テストを行うことで、推論エンジンが単独で正しく動作するかどうか、追加の指示が必要かどうかを判断できます。

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

エージェントは、ツールごとに多数の入力フィールド（最大26の固有の入力）を処理できます。ただし、ツールの入力フィールドの数が多いほど、`actionName`、`inputField`、`label`の値を割り当てるときにより明確にする必要があります。ツールの効果と信頼性が最も高くなるのは、ツールが特定のタスクを対象として、限定的なパラメーターセットを使用して設計されている場合です。複雑な操作の場合、入力の数が多すぎる単一のツールよりも、複数の単純なツールを作成する方が効果的であるかどうかを検討してください。

<Warning>
  **注**:

  将来的に、大量の入力を処理するエージェントの品質に関するフィードバックに基づいて、HubSpotが入力の数を制限する可能性があります。
</Warning>

### エージェントの創造性と即興性をコントロールする

状況によっては、エージェントが創造的かつ即興的に対応するようにしたいことがあります。ただし、エージェントが即興的に対応しないことが必要な状況もあります。入力フィールド名、ラベル、説明を使用して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リクエストの検証](/apps/legacy-apps/authentication/validating-requests#validate-the-v3-request-signature)に使用するシステムと同じです。

<Warning>
  **注**:

  シークレットやAPIキーの入力フィールドは<u>作成しないでください</u>。これは、LLMに対する指示でシークレット/APIキーを与える必要があるか、またはLLMが別のツールからシークレット/APIキーを受け取る必要がある場合には特に、安全でなく、意図された認証パターンではないためです。
</Warning>