AI エージェントツールを外部サービスに接続する

備考

プレビュー

AIエージェントツールをSlack、Googleカレンダー、またはHTTPリクエストを使用してAPIを使用する任意のサービスなどの外部アプリケーションに接続する方法を学びます。エージェントは、外部に接続されたツールを使用して、タスクの自動化、メッセージの送信、およびサードパーティプラットフォームからのデータの取得を行うことができます。

エージェントツールの詳細については、「 AI エージェントツール」を参照してください。

必要条件

エージェントツールを外部サービスに接続するには、次の要件を満たす必要があります。

次のいずれかの方法を使用して、外部サービスへの認証を設定します。
- ベアラートークン:単純なトークンベースの認証のためにベアラートークンを取得します。
- OAuth 2.0 Machine-to-Machine: マシン間認証を有効にするアプリを作成して構成します。
- OAuth 2.0 User-to-Machine Shared: ユーザー操作で認証し、サービス ID とマシン間でアクセスを共有します。
ワークスペースで Unity Catalog が有効になっている必要があります。
Databricks コンピュートリソースから外部サービスへのネットワーク接続が必要です。「レイクハウスフェデレーションのネットワーキングに関する推奨事項」を参照してください。
Databricks Runtime 15.4 以降では、専用アクセスモード (旧シングルユーザーアクセスモード) のコンピュートを使用する必要があります。
Pro またはサーバレス SQLウェアハウスが必要です。ウェアハウスタイプSQLを参照してください。

外部サービスの認証方法

ベアラートークン: ベアラートークンは、トークンがクライアントに発行され、追加の資格情報を必要とせずにリソースにアクセスするために使用される単純なトークンベースの認証メカニズムです。トークンはリクエストヘッダーに含まれ、有効である限りアクセスを許可します。

OAuth マシン間 (推奨): OAuth Machine-to-Machine (M2M) 認証は、2 つのシステムまたはアプリケーションが直接ユーザーの関与なしに通信する場合に使用されます。トークンは、登録されたマシンクライアントに対して発行され、クライアントは独自の資格情報を使用して認証します。これは、サーバー間通信、マイクロサービス、およびユーザーコンテキストが不要な自動化タスクに最適です。 Databricks では、OAuth Machine-to-Machine が使用可能な場合は、それを使用することをお勧めします。

OAuthユーザーからマシン共有: OAuth ユーザー間共有認証を使用すると、1 つのユーザー ID で認証を行い、複数のクライアントまたはユーザー間で同じ資格情報セットを共有できます。すべてのユーザーが同じアクセストークンを共有します。このアプローチは、一貫したユーザー ID で十分な共有デバイスや環境に適していますが、個々の説明責任と追跡は減少します。 IDログインが必要な場合は、[ユーザーからマシン共有]を選択します。

外部サービスへの接続を作成する

まず、外部サービスへの Unity Catalog Connection を作成し、サービスにアクセスするためのパスと資格情報を指定します。

Unity Catalog Connection を使用する利点は次のとおりです。

安全な認証情報管理: シークレットとトークンは Unity Catalog に安全に保管され、管理されるため、ユーザーに公開されることはありません。
きめ細かなアクセス制御: Unity Catalog では、 USE_CONNECTION と MANAGE_CONNECTION の特権を使用して、接続を使用または管理できるユーザーをきめ細かく制御できます。
ホスト固有のトークンの強制: トークンは、接続の作成時に指定された host_name に制限されるため、承認されていないホストでは使用できません。

必要な権限： メタストア管理者またはCREATE CONNECTION権限を持つユーザー。

次のいずれかの方法を使用して接続を作成します。

Catalog Explorer UI を使用します。
CREATE CONNECTION SQL コマンドは、Databricks ノートブックまたは Databricks SQL クエリエディターで実行します。
Databricks REST API または Databricks CLI を使用して接続を作成します。 POST /api/2.1/unity-catalog/connections を参照してください。および Unity Catalog コマンド。

Catalog Explorer
SQL

Use the Catalog Explorer UI to create a connection.

In your Databricks workspace, click Catalog.
At the top of the Catalog pane, click the Add icon and select Add a connection from the menu.

Alternatively, from the Quick access page, click the External data > button, go to the Connections tab, and click Create connection.
Click Create connection.
Enter a user-friendly Connection name.
Select a Connection type of HTTP.
Select an Auth type from the following options:
- Bearer token
- OAuth Machine to Machine
- OAuth User to Machine Shared
On the Authentication page, enter the following connection properties for the HTTP connection.

For a bearer token:
- Host: For example, https://databricks.com
- Port: For example, 443
- Bearer Token: For example, bearer-token
- Base Path: For example, /api/
For OAuth Machine to Machine token:
- Client ID: Unique identifier for the application you created.
- Client secret: Secret or password generated for the application that you created.
- OAuth scope: Scope to grant during user authorization. The scope parameter is expressed as a list of space-delimited, case-sensitive strings. For example, channels:read channels:history chat:write
- Token endpoint: Used by the client to obtain an access token by presenting its authorization grant or refresh token. Usually in the format https://authorization-server.com/oauth/token
For OAuth User to Machine Shared token:
- Client ID: Unique identifier for the application you created.
- Client secret: Secret or password generated for the application that you created.
- OAuth scope: Scope to grant during user authorization. The scope parameter is expressed as a list of space-delimited, case-sensitive strings. For example, channels:read channels:history chat:write
- Authorization endpoint: To authenticate with the resource owner via user-agent redirection, usually in the format https://authorization-server.com/oauth/authorize
- Token endpoint: Used by the client to obtain an access token by presenting its authorization grant or refresh token. Usually in the format https://authorization-server.com/oauth/token

注記

For OAuth User to Machine Shared, you are prompted to sign in with HTTP using your OAuth credentials.

Click Create connection.

Use the CREATE CONNECTION SQL command to create a connection.

注記

You cannot use the SQL command to create a connection that uses OAuth Machine to User Shared. Instead, see the Catalog Explorer UI instructions.

To create a new connection using a Bearer token, run the following command in a notebook or the Databricks SQL query editor:

SQL
CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  bearer_token '<bearer-token>'
);

Databricks recommends using secrets instead of plaintext strings for sensitive values like credentials. For example:

SQL
CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  bearer_token secret ('<secret-scope>','<secret-key-password>')
)

To create a new connection using OAuth Machine to Machine, run the following command in a notebook or the Databricks SQL query editor:

SQL
CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  client_id '<client-id>'
  client_secret '<client-secret>'
  oauth_scope '<oauth-scope1> <oauth-scope-2>'
  token_endpoint '<token-endpoint>'
)

HTTP 要求を外部システムに送信する

接続が確立されたので、 http_request 組み込み SQL 関数を使用して HTTP 要求をサービスに送信する方法を学習します。

必要な権限: 接続オブジェクトに対する USE CONNECTION 。

ノートブックまたはDatabricks SQLエディタで次のSQLコマンドを実行します。プレースホルダーの値を置き換えます。

SQL
SELECT http_request(
  conn => <connection-name>,
  method => <http-method>,
  path => <path>,
  json => to_json(named_struct(
    'text', text
  )),
  headers => map(
    'Accept', "application/vnd.github+json"
  )
);

connection-name: ホスト、ポート、base_path、およびアクセス資格情報を指定する接続オブジェクト。
http-method: 呼び出しを行うために使用される HTTP 要求メソッド。例: GET、 POST、 PUT、 DELETE
path: サービス・リソースを呼び出す base_path の後に連結するパス。
json: リクエストと共に送信する JSON 本文。
headers: リクエストヘッダーを指定するマップ。

Unity Catalog 関数ツールを作成する

接続が正しく機能することを検証した後、接続を使用する Unity Catalog 関数を作成します。次の例では、エージェントが Slack にメッセージを投稿するために使用できる Unity Catalog 関数ツールを作成します。

SQL
CREATE OR REPLACE FUNCTION main.default.slack_post_message(
  text STRING COMMENT 'message content'
)
RETURNS STRING
COMMENT 'Sends a Slack message by passing in the message and returns the response received from the external service.'
RETURN (http_request(
  conn => 'test_sql_slack',
  method => 'POST',
  path => '/api/chat.postMessage',
  json => to_json(named_struct(
    'channel', "C032G2DAH3",
    'text', text
  ))
)).text

エージェントコードでツールを作成する

Python を使用して外部サービスに HTTP リクエストを送信するには、databricks-sdk ライブラリの http_request 関数を使用します。この関数は、Unity Catalog 接続を使用して外部サービスに HTTP 要求を送信し、認証を行います。

必要な権限: 接続オブジェクトに対する USE CONNECTION 。

次の例では、エージェントコード内から外部 HTTP リクエストを作成します。

Python
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ExternalFunctionRequestHttpMethod

WorkspaceClient().serving_endpoints.http_request(
  conn="connection_name",
  method=ExternalFunctionRequestHttpMethod.POST,
  path="/api/v1/resource",
  json={"key": "value"},
  headers={"extra_header_key": "extra_header_value"},
)

conn: ホスト、ポート、base_path、およびアクセス資格情報を指定する接続オブジェクト。
method: 呼び出しを行うために使用される HTTP 要求メソッド。例: GET、 POST、 PUT、 DELETE
path: サービス・リソースを呼び出す base_path の後に連結するパス。
json: リクエストと共に送信する JSON 本文。
headers: リクエストヘッダーを指定するマップ。

ノートブックの例

次のノートブックは、Slack、OpenAI、Azure AI 検索に接続する AI エージェントツールの作成を示しています。

必要条件​

外部サービスの認証方法​

外部サービスへの接続を作成する​

HTTP 要求を外部システムに送信する​

Unity Catalog 関数ツールを作成する​

エージェント コードでツールを作成する​

ノートブックの例​

Slackメッセージングエージェントツール

Microsoft Graph API エージェント ツール

Azure AI Search エージェント ツール