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_CONNECTIONMANAGE_CONNECTION の特権を使用して、接続を使用または管理できるユーザーをきめ細かく制御できます。

  • ホスト固有のトークンの強制: トークンは、接続の作成時に指定された host_name に制限されるため、承認されていないホストでは使用できません。

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

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

Catalog Explorer UIを使用して接続を作成します。

  1. Databricks ワークスペースで、[カタログアイコン カタログ] をクリックします。

  2. [カタログ] ウィンドウの上部にある [追加またはプラスアイコン 追加] アイコンをクリックし、メニューから [ 接続の追加] を選択します。

    または、クイックアクセスページから外部データ > ボタンをクリックし、[接続]タブに移動して[接続を作成]をクリックします。

  3. [接続の作成]をクリックします。

  4. ユーザーフレンドリーな接続名を入力します。

  5. [ 接続タイプ ] で [HTTP] を選択します。

  6. 次のオプションから 認証タイプ を選択します。

    • ベアラートークン

    • OAuthによるマシン間通信

    • マシンに共有されたOAuthユーザー

  7. [ 認証 ] ページで、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 でサインインするように求められます。

  8. [接続の作成]をクリックします。

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 要求メソッド。 例: GETPOSTPUTDELETE

  • 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 要求メソッド。 例: GETPOSTPUTDELETE

  • path: サービス・リソースを呼び出す base_path の後に連結するパス。

  • json: リクエストと共に送信する JSON 本文。

  • headers: リクエストヘッダーを指定するマップ。

ノートブックの例

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

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

ノートブックを新しいタブで開く

OpenAI AIエージェントツール

ノートブックを新しいタブで開く

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

ノートブックを新しいタブで開く