ツール

ツールは「アクションレイヤー」です。エージェントがデータを取得したり、商談ステージを更新したり、メールを送信したりするたびに、許可された API を呼び出しています。

  

ツールがなければ、エージェントは質問に答えるだけです。ツールを使えば、実際の処理を実行できます。

システムツールとカスタムツール   

Zoho Zia Agents の［ツール］セクションは、システムツールとカスタムツールの 2 つのタブに分かれています。

システムツールは、サービスごとにあらかじめ用意され、整理されています。各サービスカード（CRM、Desk、Campaigns、Books など）には、利用可能なツールと、そのツールで何ができるかの簡単な説明が表示されます。任意のサービスをクリックすると、ツール名、説明、メソッド（GET、POST など）、API パスを含む、サポートされている API の一覧が表示されます。

これらはすぐに利用できます。設定やファイルのアップロードは不要です。ユースケースに関連するツールを探して、エージェントに追加するだけです。

カスタムツールは、あらかじめ用意されたオプションでは対応できない場合に使用します。特定の API エンドポイントを使いたい場合や、システムツール一覧にないサービスへ接続する必要がある場合などです。カスタムツールでは、OpenAPI 3.0 形式の YAML ファイルとして独自の API 定義を取り込み、検証し、エージェントで利用できるようにできます。

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

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

メソッドは、その API がどのような処理を行うかを示します。エンドポイントは、その処理がどこで実行されるかを示します。

代表的な 4 つのメソッドは次のとおりです。

メソッド	目的	CRM での例
GET	データを取得する	ID で商談を取得
POST	新規作成する	新しい連絡先を追加
PUT	更新する	商談ステージを変更
削除	削除する	チケットを削除

エンドポイントは次のような形式です。

GET /crm/v8/Leads/{record_id}

これは、特定のリードの ID を使って、その詳細を取得するようエージェントに指示するものです。{record_id} の部分は動的パラメーターであり、エージェントがコンテキストに基づいて値を埋め込みます。

カスタムツール用の YAML ファイルの作成   

YAML ファイルは、エージェントが利用できる API を定義します。エージェントが実行できるアクションの設計図と考えてください。データの取得、連絡先の作成、メール送信など、すべてのアクションをここで定義する必要があります。

Zoho Zia Agents 用の YAML ファイルは、OpenAPI 3.0形式に従います。大まかには、各ファイルで次の内容を定義します。

• メタデータ(openapi, info): 仕様バージョン、API タイトル、説明、バージョン番号

• サーバーとセキュリティ(servers, security): ベース URL と認証方式（通常は必要なスコープを指定した OAuth2）

• エンドポイント(paths): API パス、HTTP メソッド、および各オペレーションの概要、説明、一意の operationId（Zoho Zia Agents でツール名として表示される値）

• パラメーター: API が受け取る入力値、その所在（パス、クエリー、ヘッダー）、必須かどうか、データ型

• レスポンス: 期待される HTTP ステータスコード（200、400、401、404 など）。エージェントが成功と失敗をどのように処理するかを判断するために使用されます。

• セキュリティスキーム(components): security セクションから参照される、完全な OAuth2 設定

Zoho Zia Agents 固有のポイントが 1 つあります。 パラメーターに付与された x-Zoho Zia-agent-param-type: system タグは、その値を毎回ユーザーに入力させるのではなく、コンテキストに基づいて動的に解決するようエージェントに指示します。  

Zoho CRM からデータを取得するための YAML の例を次に示します。

openapi: 3.0.0
info:
title: Zoho CRM API
version: '1.0.0'
説明: Zoho CRM API v7 を使用して、指定したタブから 1 件のデータを取得します。
 
servers:
- url: https://www.zohoapis.com
 
paths:
'/crm/v7/{module_api_name}/{record_id}':
get:
summary: ID を指定して 1 件のデータを取得
説明: >
指定したタブから、データ ID を使用して 1 件のデータを取得します。
`fields` パラメーターを使用して、特定の項目のみを取得することもできます。
operationId: getRecordById
parameters:
- name: module_api_name
in: path
required: true
説明: タブの API 名（例：見込み客、Contacts、Deals）。
schema:
type: string
x-Zoho Zia-agent-param-type: system
 
- name: record_id
in: path
required: true
説明: データの一意の識別子。
schema:
type: string
x-Zoho Zia-agent-param-type: system
 
responses:
'200':
説明: データを含む正常なレスポンス。
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object（オブジェクト）
additionalProperties: true（追加プロパティを許可）
info:
type: object（オブジェクト）
additionalProperties: true（追加プロパティを許可）
'204':
説明: コンテンツなし。該当するデータがありません。
'400':
説明: 不正なリクエスト。パラメーターが無効です。
'401':
説明: 認証エラー。アクセストークンが無効か、指定されていません。
'403':
説明: アクセス拒否。ユーザーに権限がありません。
'404':
説明: 見つかりません。指定されたIDのデータがありません。
'429':
説明: リクエストが多すぎます。APIのレート制限を超えています。
'500':
説明: サーバー内部エラー。
 
security:
- OAuthToken: ['ZohoCRM.タブ.ALL']
 
components:
securitySchemes:
OAuthToken:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
tokenUrl: https://accounts.zoho.com/oauth/v2/token
scopes:
ZohoCRM.タブ.ALL: すべてのタブの読み取りアクセス

カスタムツールの作成

カスタムツールグループを作成するには、Toolsタブに移動し、右上の+ New Tool Groupをクリックします。作成フローはいくつかのステップで構成されています。

1. Toolsページで、+ New Tool Groupをクリックします。

2. 任意のTool Group Name（例：Lead Management や Event Creation など）と、必要に応じて説明を入力します。

3. + Add Schemaをクリックします。表示されるパネルで、Schema Service（例：Zoho CRM）を選択するか、Zoho のデフォルト一覧にない場合はCustom Serviceを選択します。YAML ファイル（.yaml、最大 500 KB）をアップロードします。ファイル内容のプレビューが表示されます。

4. Validateをクリックします。検証に成功すると、解析されたツールが右側のValidated Toolsパネルに表示され、ツール名、説明、メソッド、パスが確認できます。同じグループに複数のスキーマを追加する場合は、再度+ Add Schemaをクリックします。

5. Nextをクリックします。ツールの一覧が表示され、Tool Status列とTest Status列が表示されます（カスタムツールの場合、どちらも Draft から開始します）。エージェントがこれらのツールを使用する前にテストが必要であることを知らせるバナーが表示されます。

6. ツールを選択し、Test All Toolsをクリックします。すると、Test Your Toolsダイアログが開きます。

7. テストを実行する前に、接続の関連付けと必須パラメーターの入力という 2 つの作業を行う必要があります。

1. 接続の関連付け:ダイアログには、接続を選択ドロップダウンが表示されます。

2. 対象サービス（例：Zoho CRM）用の接続がすでに作成されている場合は、それを選択して関連付けをクリックします。
   まだない場合は、自動作成をクリックして自動生成するか、新規をクリックして手動で作成します。接続は認証を処理し、ツールがサービスと安全に通信できるようにします。
   ダイアログ右上付近には、必要なスコープ情報ボタンも表示されます。クリックすると、ツールに必要なOAuthスコープを確認できます。
   
   テストを実行するには、接続にこれらのスコープが含まれている必要があります。

3. パラメーターの入力:接続セクションの下には、APIが想定するパラメーターの一覧が表示され、それぞれに名前、データ型、値の項目が示されます。
   赤で表示されているパラメーターは必須です。たとえば、updateSingleLeadRecordツールをテストする場合は、有効なrecord_idと、更新したい項目（Last_Name、Email、Lead_Statusなど）を入力する必要があります。テスト結果が実際の動作を反映するよう、サービス上の実データを使用してください。

4. 入力が完了したら、テストをクリックして実行します。

8. テストが成功したら、テスト済みのツールを選択し、準備完了にするをクリックします。これでエージェントがそのツールを利用できるようになります。

9. 最後に、保存をクリックします。

ツールを整理する際のベストプラクティス   

ツールを設定する際に意識しておきたいポイントをいくつか紹介します。

接続

接続とは？

接続は、特定のサービスにアクセスする権限をツールに付与するための仕組みです。エージェントがAPIを呼び出す（たとえば、CRMから取引を取得したり、Deskでチケットを作成したりする）際には、まずそのサービスで認証を行う必要があります。その役割を担うのが接続です。

各接続は、接続先サービス、保持しているOAuthスコープ（権限）、認証に使用する認証情報という3つの要素で構成されます。ツールが動作するには、そのツールの接続が対象サービスと一致し、ツールに必要なスコープを持っている必要があります。この条件が揃っていないと、ツールは実行されません。

接続を作成できる場所

Zoho Zia Agentsで接続が関係するのは、次の3か所です。

• ［設定］>［接続］は、接続を管理するメイン画面です。ここで要件に応じて接続を事前に設定したり、既存の接続を確認したり、認証エラーをトラブルシューティングしたりできます。エージェントを作成する前に環境を整える場合は、まずここから始めるとよいでしょう。
• カスタムツールのテスト中:カスタムツールグループを利用可能にする前に、ツールをテストする必要があります。テスト用のポップアップでは、接続の関連付けが求められます。既存の接続を選択するか、自動作成をクリックして自動生成するか、新規をクリックしてその場で作成できます。
• エージェント設定も3つ目の入口です。エージェントをテストまたはデプロイする際に、その設定の一環としてツールをサービスに接続する必要が生じる場合があります。

これら3つの経路で作成される接続は、いずれも同じ種類のものです。違いは、いつ・どこで作成するかだけです。

接続の管理

［接続］ページは、左側サイドバーの［設定］の下にあります。いくつかのセクションに分かれて構成されています。

• My Connectionsには、あなた、または組織の管理者が作成したすべてのコネクションが表示されます。各コネクションには、サービス名とステータスが表示されます。有効なコネクションには緑色のドットが表示され、無効なコネクションはグレー表示になります。
  
• Shared Connectionsには、組織全体で共有されているコネクションが一覧表示されます。
• System Connectionsには、システムレベルで設定されたコネクションが表示されます。

[Services] では、Default Services（Zoho に組み込みのサービス）と、Custom Services（手動で追加したサービス）が表示されます。

コネクションの作成

設定ページからコネクションを作成する手順は次のとおりです。

コネクションの作成

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

1. サービスを選択: 2 つのタブが表示されます。[Default Services]（Zoho Voice、Zoho Payroll、Bigin、Zoho Bookings、Zoho Books、Zoho One など）と [Custom Services] です。ツールが接続する必要のあるサービスを選択します。サービスがデフォルトに表示されていない場合は、カスタムサービスを作成します。

2. コネクションの詳細:

1. Connection Name: わかりやすい名前を付けます（例:「データ取得」や「CRM リードアクセス」など）。コネクションリンク名は、入力内容に基づいて自動生成されます。
2. Use Credentials of Login User: このトグルはデフォルトでオンになっています。別の認証情報を使用してコネクションを作成したい場合はオフにします。
3. Choose Scopes: ツールに必要な OAuth スコープを選択します。これは重要です。選択するスコープは、ツールが必要とする権限と一致している必要があります。たとえば、ツールが CRM レコードを取得する場合は、ZohoCRM.タブ.ALL を選択します。必要な権限のみに絞って付与してください。

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

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

認可が完了すると、コネクションが作成されます。[My Connections] に、コネクション名、リンク名、サービス名、ステータス、スコープ、ログインユーザーの認証情報を使用しているかどうかを含むコネクションの概要が表示されます。

パネルには、エージェントがコネクションをどのように使用するかをテストするための Deluge および JSON のサンプルコードも表示されます。

適切なスコープの選択