ツール

Zoho Zia Agents において、ツールはエージェントが実際に処理を実行するための機能です。Zoho Zia エージェントは問い合わせ内容を理解し、何をすべきか判断できますが、ツールがなければお客様の業務システムに対して直接アクションを実行することはできません。

ツールはエージェントのアクションレイヤーです。エージェントがデータを取得したり、レコードを更新したり、アクションをトリガーしたりするたびに、許可された API を呼び出して処理を行います。

たとえば、Zoho CRM 用の営業アシスタントを構築する場合、エージェントには案件レコードの取得、案件ステージの更新、連絡先情報の取得などを行うためのツールが必要になります。これらのツールは本質的に API ベースのアクションであり、CRM、Desk、Projects など、どのサービスであってもエージェントがそれらと連携できるようにします。

ツールがなければ、エージェントは質問に回答するだけで、実際に意味のあるアクションを実行することはできません。

ツールグループ：ツールの整理

ツールグループは、エージェントがアクションを実行するために使用できるツールの集合です。1 つまたは複数の Zoho サービスから API を同じグループに追加できます。これにより、製品をまたいだワークフローを設計できます。たとえば次のようなケースです：

• Zoho CRM から案件データを読み取る
• Zoho Desk にチケットを作成する

ツールをグループ化して整理することで、管理しやすくなり、エージェントが目的に合った適切な API を使用できるようになります。

ツールグループの作成方法：

ツールグループは、次の 2 通りの方法で作成できます。

API メソッドとエンドポイントの理解

すべてのツールは API を基盤としており、各 API には次の 2 つの重要な要素があります。

• メソッド：API が実行するアクションの種類。
• エンドポイント：そのアクションが実行される場所（URL）。

エンドポイントの例:

1. GET /crm/v8/Leads/{record_id}

これは、API が指定した ID を使って特定の見込み客の詳細を取得することを意味します。

ベストプラクティス:

• 同じワークフローに属するツールをまとめてグループ化します（例：「リードからチケットへの引き継ぎ」）し、無関係なアクションは追加しないでください。
• ツールに必要なスコープだけを選択します。
• 識別しやすいように、ツール名やツールグループ名は内容がわかる説明的な名前にします。
• 公開前にテストする: 各ツールがサンプルデータで正しく動作することを確認します。
• サービス側で API が更新された場合は、再テストして設定を調整します。

YAML ファイル

YAML ファイルでは、エージェントが使用する API の構造を定義します。エージェントに対して、実行できるアクションの設計図を渡すイメージです。

エージェントが動作するには、取引レコードの取得、連絡先の更新、チケットの作成など、エージェントが行うすべてのアクションをこの YAML に定義しておく必要があります。エージェントが対応すべきアクションに応じて、1 つのファイルに複数の API を含めることができます。

たとえば、エージェントが Zoho CRM からレコードを取得する必要があるとします。YAML ファイルでは次の内容を定義します。

• エージェントがアクセスできる API エンドポイント。
• それらのエンドポイントに必要なパラメーター（対象とするモジュールやレコードなど）。
• 呼び出しに必要な認証方式（安全なアクセスを確保するため）。
• 呼び出しが成功または失敗したときにエージェントが受け取るレスポンスの内容（返信をどのように処理すべきかを判断できるようにするため）。

これらはすべて OpenAPI 3.0 形式で記述します。

OpenAPI 3.0は、REST API を定義・文書化するためのオープンな仕様であり、ソースコードやドキュメント、ネットワークトラフィックの解析に頼らずに、人間とマシンの両方が API を理解し操作できるようにします。言語に依存しないインターフェイスであり、通常 YAML または JSON の標準フォーマットを使用して、利用可能なエンドポイント、操作、パラメーター、データモデルなどの API の詳細を記述します。

YAML に表示される module_api_name や record_id などのシステムパラメーターは、エージェントがさまざまなモジュールやレコードを動的に扱えるようにするためのものです。これらがないと、エージェントはどのレコードやどのモジュールを対象にすべきか判断できません。

新しいツールグループを作成する

新しいツールグループを作成するには、次の手順に従います。

1. Zoho Zia Agents アカウントで、左側の Tools タブに移動します。
2. [New Tool Group] をクリックします。
3. ツールグループ名を入力します。
   
4. 作成方法を選択します。

1. Predefined:あらかじめ用意された API セットを選択して、ツールグループを作成します。
   
2. Create from scratch（独自の YAML ファイルで作成）:独自の YAML ファイルを使用して、新しい API ツールを作成します。
   
   

Predefined

Zoho Zia Agents Studio には、各種 Zoho サービス向けの事前定義ツールが用意されています。

1. 要件に応じて、対象のサービスをクリックします。
2. そのサービスでサポートされている API の一覧と、それぞれの説明が表示されます。
   また、API で使用される Method（GET/POST）や Path などの詳細も確認できます。
3. 必要な API に対して、[Add] をクリックします。
   

Create From Scratch

ツールグループを一から作成するには、次の操作を行います。

1. アップロードアイコンをクリックし、YAML ファイルをアップロードします。
2. [Schema] でサービス名（例: Zoho CRM）を選択します。
3. [Validate] をクリックします。
   YAML ファイルから選択された API が一覧表示されます。検証が正常に完了したら、[Next] をクリックします。
   

5. [Description] で、参照用に Tools Group の説明を追加します。
   

事前定義 API は「Ready」と表示され、アップロードした YAML ファイル由来の API は「Draft」として追加され、Ready にする前にテストが必要です。

6. API を選択し、[Test API] をクリックします。
   

1. 既存のコネクションを関連付けるか、新しいコネクションを作成してから関連付けることができます。
   
2. ご利用のサービスで使用するパラメーター値を入力します。
   たとえば、この例で選択している getRecordById API の場合、モジュールパラメーターの値を Leads に設定し、テスト用リードのレコード ID を指定します。
3. ［Test］をクリックします。
   

7. テストが正常に完了すると、API の テストステータスが Success と表示されます。
   
   
   
   テスト済みの API を選択し、［Mark as Ready］をクリックできます。
   これでエージェントに関連付けられるようになります。
8. ［Save］をクリックして、ツールグループを保存します。
   
   

これでツールグループが作成されます。同じ手順を繰り返すことで、複数のツールグループを作成できます。

コネクション

コネクションは、ツールの実行時に CRM や Desk などの特定のサービスへの認証とアクセスを有効にするために使用されます。コネクションを有効にするには、そのコネクションに関連付けられたサービスと OAuth スコープが、ツールグループのサービスおよび選択したツールに必要なスコープと一致している必要があります。この整合性が取れている場合にのみ、そのコネクションをツールに関連付けることができます。ツールは、有効なコネクションに正しくリンクされて初めて実行できます。

コネクションは、［設定］ページの［Connections］タブに一覧表示されます。［My Connections］タブでは、自分または組織の管理者が作成したコネクションを確認できます。有効なサービスには緑色のドットが表示され、無効なサービスはグレー表示になります。

コネクションを作成するには

1. ［Settings］>［Connections］に移動します。
2. ［My Connection］スライドアウトパネルで、［Create Connection］ボタンをクリックし、次の操作を行います。

1. Pick Your Service: デフォルトサービスとカスタムサービスが表示されます。API に接続したいサービスを選択するか、新しいカスタムサービスを作成します。
   
2. Connection Details:

1. Connection name: コネクションに一意の名前を設定します。コネクションリンク名は自動的に更新されます。
2. ログインユーザーの認証情報を使用したくない場合は、［Yes］トグルを［Use Credentials of Login User］の下でオフにします。
3. 要件に応じてスコープを選択します。
   
   

CRM 用の適切なスコープの選び方については こちらを参照してください。

3. [Create and Connect] をクリックします。
   これで、ご自身の認証情報を使って接続できるようになります。次のページで、選択したサービスとスコープを持つ既存の接続を再利用するか、新しい接続を作成するかを選択できます。
   
4. 新しい接続を作成する場合は、使用したい組織を 1 つ選択し、Submit をクリックします。
   
5. Deluge から表示される認可プロンプトを確認し、Deluge に CRUD 操作の実行を許可することに同意するため、[Accept] をクリックします。
   
   
   

認証が完了すると、接続が作成されます。

パネルには、エージェントが接続をどのように使用するかをテストできるよう、Deluge と JSON のサンプルコードが表示されます。