# EMQXエージェントをDatabricksに接続する

Databricksコネクターを使用すると、EMQXエージェントがUnity Catalog、SQLウェアハウスとステートメント、ジョブ、モデルサービングエンドポイント、およびVector Searchと連携できます。このコネクターを使って、運用データのクエリ実行、データワークフローの実行、Databricksの結果を用いた自動化された意思決定を行うエージェントを構築できます。

## よくあるユースケース

- SQLワークフローを生成する前にカタログ、スキーマ、テーブルを確認する。
- SQLステートメントを実行し、その結果をアラートやレポートに利用する。
- エージェントワークフローからDatabricksジョブを開始または確認する。
- Vector Searchインデックスをクエリして、エージェントに企業データのコンテキストを追加する。

チャットプロンプトの例：

```text
analytics-databricksコネクターを使用してください。利用可能なカタログとスキーマを一覧表示し、telemetryテーブルを見つけて、最新の20件の異常レコードをクエリしてください。
```

## 前提条件

コネクターを追加する前に、以下を準備してください：

- DatabricksワークスペースのWebアドレス。ブラウザに表示されるURLを末尾のスラッシュなしで使用します。例：`https://dbc-abc123.cloud.databricks.com`
- 同じワークスペースで生成されたDatabricksのパーソナルアクセストークン。
- ワークフローで必要なUnity Catalogオブジェクト、SQLウェアハウス、ジョブ、サービングエンドポイント、またはVector Searchリソースへのアクセス権。
- 選択したツールで必要なDatabricksのエンタイトルメントまたはワークスペースロール。

## Databricksコネクターを追加する

1. 左側のナビゲーションメニューで **Connectors** をクリックします。
2. **Available** タブで **Databricks** を見つけて **Add** をクリックします。
3. 分かりやすいコネクター名を入力します。
4. **Confirm** をクリックします。EMQXエージェントが認可ダイアログでDatabricks接続フォームを開きます。
5. 以下の情報を入力します：
   - **Workspace URL**：末尾のスラッシュなしでDatabricksワークスペースのWebアドレスを入力します。URLはアクセストークンが生成されたワークスペースを特定する必要があります。
   - **Access Token**：`dapi`で始まるDatabricksのパーソナルアクセストークンを入力します。トークンはDatabricksのユーザー名をクリックし、**Settings** -> **Developer** -> **Access tokens** -> **Generate new token** から生成できます。
6. **Connect Account** をクリックします。
7. Composioが接続を確認し、EMQXエージェントに戻るまで待ちます。
8. **Added** タブで **Authorization successful** メッセージが表示され、コネクターのステータスが **Authorized** になっていることを確認します。

## サポートされているツール

### ユーザーとUnity Catalog

| ツール | アクセス | 説明 |
|---|---|---|
| `DATABRICKS_IAM_CURRENT_USER_ME` | 読み取り | 現在のDatabricksユーザー情報を取得します。 |
| `DATABRICKS_LIST_CATALOGS` | 読み取り | Unity Catalogのカタログを一覧表示します。 |
| `DATABRICKS_LIST_SCHEMAS` | 読み取り | カタログ内のスキーマを一覧表示します。 |
| `DATABRICKS_LIST_TABLES` | 読み取り | カタログとスキーマ内のテーブルを一覧表示します。 |

### SQLウェアハウスとステートメント

| ツール | アクセス | 説明 |
|---|---|---|
| `DATABRICKS_LIST_SQL_WAREHOUSES` | 読み取り | Databricks SQLウェアハウスを一覧表示します。 |
| `DATABRICKS_SQL_QUERIES_GET` | 読み取り | SQLクエリの詳細を取得します。 |
| `DATABRICKS_SQL_QUERY_HISTORY_LIST` | 読み取り | SQLクエリ履歴を一覧表示します。 |
| `DATABRICKS_SQL_STATEMENT_EXEC_CANCEL_EXEC` | 書き込み | 実行中のSQLステートメントをキャンセルします。 |
| `DATABRICKS_SQL_STATEMENT_EXEC_EXECUTE_STATEMENT` | 書き込み | SQLウェアハウスでSQLステートメントを実行します。 |
| `DATABRICKS_SQL_STATEMENT_EXEC_GET_RESULT_CHUNK` | 読み取り | SQLステートメントの結果チャンクを取得します。 |
| `DATABRICKS_SQL_STATEMENT_EXEC_GET_STATEMENT` | 読み取り | SQLステートメントのステータスと結果メタデータを取得します。 |
| `DATABRICKS_SQL_WAREHOUSES_DELETE` | 破壊的 | SQLウェアハウスを削除します。 |
| `DATABRICKS_SQL_WAREHOUSES_EDIT` | 書き込み | SQLウェアハウスの設定を更新します。 |
| `DATABRICKS_SQL_WAREHOUSES_GET` | 読み取り | SQLウェアハウスの詳細を取得します。 |
| `DATABRICKS_SQL_WAREHOUSES_START` | 書き込み | SQLウェアハウスを起動します。 |

### ジョブと実行

| ツール | アクセス | 説明 |
|---|---|---|
| `DATABRICKS_CREATE_JOB` | 書き込み | Databricksジョブを作成します。 |
| `DATABRICKS_JOBS_JOBS_CANCEL_ALL_RUNS` | 書き込み | ジョブのすべてのアクティブな実行をキャンセルします。 |
| `DATABRICKS_JOBS_JOBS_CANCEL_RUN` | 書き込み | ジョブ実行をキャンセルします。 |
| `DATABRICKS_JOBS_JOBS_DELETE_RUN` | 破壊的 | ジョブ実行レコードを削除します。 |
| `DATABRICKS_JOBS_JOBS_GET` | 読み取り | ジョブの詳細を取得します。 |
| `DATABRICKS_JOBS_JOBS_SET_PERMISSIONS` | 書き込み | ジョブのアクセス権を設定します。 |
| `DATABRICKS_JOB_RUN_BY_ID` | 読み取り | 実行IDによるジョブ実行の詳細を取得します。 |
| `DATABRICKS_LIST_JOBS` | 読み取り | Databricksジョブを一覧表示します。 |
| `DATABRICKS_LIST_RUNS` | 読み取り | Databricksジョブ実行を一覧表示します。 |
| `DATABRICKS_SUBMIT_RUN` | 書き込み | 一回限りのDatabricks実行を送信します。 |
| `DATABRICKS_UPDATE_JOB_BY_ID` | 書き込み | ジョブIDによるジョブの更新を行います。 |

### モデルサービング

| ツール | アクセス | 説明 |
|---|---|---|
| `DATABRICKS_LIST_MODEL_SERVING_ENDPOINTS` | 読み取り | モデルサービングエンドポイントを一覧表示します。 |
| `DATABRICKS_SERVING_SERVING_ENDPOINTS_CREATE_PROV_THPUT` | 書き込み | プロビジョンドスループットのモデルサービングエンドポイントを作成します。 |
| `DATABRICKS_SERVING_SERVING_ENDPOINTS_DELETE` | 破壊的 | モデルサービングエンドポイントを削除します。 |
| `DATABRICKS_SERVING_SERVING_ENDPOINTS_GET` | 読み取り | モデルサービングエンドポイントの詳細を取得します。 |

### Vector Search

| ツール | アクセス | 説明 |
|---|---|---|
| `DATABRICKS_LIST_VECTOR_SEARCH_ENDPOINTS` | 読み取り | Vector Searchエンドポイントを一覧表示します。 |
| `DATABRICKS_VECTORSEARCH_VECTOR_SEARCH_ENDPOINTS_CREATE` | 書き込み | Vector Searchエンドポイントを作成します。 |
| `DATABRICKS_VECTORSEARCH_VECTOR_SEARCH_INDEXES_DELETE_INDEX` | 破壊的 | Vector Searchインデックスを削除します。 |
| `DATABRICKS_VECTORSEARCH_VECTOR_SEARCH_INDEXES_QUERY_INDEX` | 読み取り | Vector Searchインデックスをクエリします。 |
| `DATABRICKS_VECTORSEARCH_VECTOR_SEARCH_INDEXES_UPSERT_DATA` | 書き込み | Vector Searchインデックスにデータを挿入または更新します。 |

::: warning 重要なお知らせ
SQLウェアハウス、ジョブ実行、モデルサービングエンドポイント、またはVector Searchインデックスを削除するツールは、リソースや運用履歴を削除する可能性があります。これらのツールを許可する前に対象リソースを必ず確認してください。
:::

## チャットでコネクターを使用する

1. チャット入力欄でコネクターアイコンをクリックします。
2. 認可済みの **Databricks** コネクターを選択します。
3. プロンプトでエージェントが使用する外部リソースと操作を指定します。
4. 生成されたエージェント定義を確認し、必要なツールのみが含まれていることを確認します。

## 権限とデータアクセス

コネクターは認可されたDatabricksアカウントの権限を使用します。そのアカウントは必要なカタログ、ウェアハウス、ジョブ、サービングエンドポイント、およびVector Searchリソースに限定してください。

チャットプロンプトやエージェントの指示に外部サービスの認証情報やアクセストークンを含めないでください。

## 制限事項

- Databricks APIのクォータ、ワークスペースポリシー、計算リソースの可用性がコネクター操作に適用されます。
- SQLステートメントは利用可能なSQLウェアハウスと必要なデータ権限が必要です。
- ジョブ、サービングエンドポイント、Vector Searchの操作には追加のワークスペースエンタイトルメントが必要な場合があります。

<!-- TODO: サービス固有の結果サイズ制限、ファイル制限、APIレート制限、プラン制限、非対応リソースタイプを確認する。 -->

## トラブルシューティング

| 症状 | 解決策 |
|---|---|
| コネクターが **Unauthorized** のまま変わらない。 | Workspace URLに末尾のスラッシュがないか、アクセストークンが同じワークスペースのもので有効かつ必要な権限を持っているかを確認し、再接続してください。 |
| ツールが権限エラーを返す。 | 認可されたアカウントが対象リソースと操作にアクセスできるか確認してください。 |
| 必要なツールが利用できない。 | ツールがこのコネクターでサポートされているか、承認されているかを確認し、チャットで再度コネクターを選択してください。 |
| リクエストが断続的に拒否される。 | 外部サービスのステータス、APIクォータ、レート制限、アカウントプランを確認してください。 |

## 関連リンク

- [Connectors](../connectors.md)
- [Start a Chat](../chats.md)
- [Manage Agents](../agents.md)