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 つのシステムまたはアプリケーションが直接ユーザーの関与なしに通信する必要がある場合に使用されます。 トークンは、登録されたマシン クライアントに対して発行され、クライアントは独自の資格情報を使用して認証します。 これは、サーバー間通信、マイクロサービス、およびユーザーコンテキストが不要な自動化タスクに最適です。
OAuthユーザーからマシン共有: OAuth ユーザー間共有認証を使用すると、1 つのユーザー 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 UIを使用して接続を作成します。
Databricks ワークスペースで、[
カタログ] をクリックします。
[カタログ] ウィンドウの上部にある [
追加] アイコンをクリックし、メニューから [ 接続の追加] を選択します。
または、クイックアクセスページから外部データ > ボタンをクリックし、[接続]タブに移動して[接続を作成]をクリックします。
[接続の作成]をクリックします。
ユーザーフレンドリーな接続名を入力します。
[ 接続タイプ ] で [HTTP] を選択します。
次のオプションから 認証タイプ を選択します。
ベアラートークン
OAuthによるマシン間通信
マシンに共有されたOAuthユーザー
[ 認証 ] ページで、HTTP 接続の次の接続プロパティを入力します。
ベアラートークンの場合:
ホスト: たとえば、
https://databricks.com
ポート: たとえば、
443
ベアラートークン:たとえば、
bearer-token
ベースパス: たとえば、
/api/
OAuth Machine to Machine トークンの場合:
クライアント ID: 作成したアプリケーションの一意の識別子。
クライアントシークレット: 作成したアプリケーションに対して生成されたシークレットまたはパスワード。
OAuth スコープ: ユーザー認証中に付与するスコープ。 scope パラメーターは、スペース区切りで大文字と小文字が区別される文字列のリストとして表されます。 例えば
channels:read channels:history chat:write
トークン エンドポイント: クライアントが承認付与または更新トークンを提示してアクセス トークンを取得するために使用されます。 通常は次の形式です。
https://authorization-server.com/oauth/token
OAuth ユーザーからマシンへの共有トークンの場合:
クライアント ID: 作成したアプリケーションの一意の識別子。
クライアントシークレット: 作成したアプリケーションに対して生成されたシークレットまたはパスワード。
OAuth スコープ: ユーザー認証中に付与するスコープ。 scope パラメーターは、スペース区切りで大文字と小文字が区別される文字列のリストとして表されます。 例えば
channels:read channels:history chat:write
認証エンドポイント: ユーザーエージェントリダイレクトを介してリソース所有者と認証するため (通常は次の形式)
https://authorization-server.com/oauth/authorize
トークン エンドポイント: クライアントが承認付与または更新トークンを提示してアクセス トークンを取得するために使用されます。 通常は次の形式です。
https://authorization-server.com/oauth/token
注:
[OAuth User to Machine Shared] の場合、OAuth 資格情報を使用して HTTP でサインインするように求められます。
[接続の作成]をクリックします。
CREATE CONNECTION
SQL コマンドを使用して、接続を作成します。
注:
SQL コマンドを使用して、 OAuth マシンからユーザー共有への接続を作成することはできません。 代わりに、カタログ エクスプローラの UI の手順を参照してください。
Bearer トークンを使用して新しい接続を作成するには、ノートブックまたは Databricks SQL クエリ エディターで次のコマンドを実行します。
CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
host '<hostname>',
port '<port>',
base_path '<base-path>',
bearer_token '<bearer-token>'
);
Databricks では、 資格情報などの機密性の高い値には、プレーンテキスト文字列の代わりにシークレットを使用することをお勧めします。 例えば:
CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
host '<hostname>',
port '<port>',
base_path '<base-path>',
bearer_token secret ('<secret-scope>','<secret-key-password>')
)
OAuth Machine to Machine を使用して新しい接続を作成するには、ノートブックまたは Databricks 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コマンドを実行します。プレースホルダーの値を置き換えます。
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 関数ツールを作成します。
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 リクエストを作成します。
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
: リクエストヘッダーを指定するマップ。