Connect AI agent tools to external services

Preview

This feature is in Public Preview.

Learn how to connect AI agent tools to external applications like Slack, Google Calendar, or any service with an API using HTTP requests. Agents can use externally connected tools to automate tasks, send messages, and retrieve data from third-party platforms.

To learn more about agent tools, see AI agent tools.

Requirements

To connect agent tools to external services, you must meet the following requirements:

• Setup authentication to the external service using one of the following methods:
  • Bearer token: Obtain a bearer token for simple token-based authentication.
  • OAuth 2.0 Machine-to-Machine: Create and configure an app to enable machine-to-machine authentication.
  • OAuth 2.0 User-to-Machine Shared: Authenticate with user interaction to share access between service identity and machine.
• Your workspace must be Unity Catalog enabled.
• You must have network connectivity from a Databricks compute resource to the external service. See Networking recommendations for Lakehouse Federation.
• You must use a compute with dedicated access mode (formerly single user access mode) on Databricks Runtime 15.4 and above.
• You must have a pro or serverless SQL warehouse. See SQL warehouse types.

Authentication methods for external services

Bearer token: A bearer token is a simple token-based authentication mechanism where a token is issued to a client and used to access resources without requiring additional credentials. The token is included in the request header and grants access as long as it is valid.

OAuth Machine to Machine (recommended): OAuth Machine-to-Machine (M2M) authentication is used when two systems or applications communicate without direct user involvement. Tokens are issued to a registered machine client, which uses its own credentials to authenticate. This is ideal for server-to-server communication, microservices, and automation tasks where no user context is needed. Databricks recommends using OAuth Machine-to-Machine when it is available.

OAuth User to Machine Shared: OAuth User-to-Machine Shared authentication allows a single user identity to authenticate and share the same set of credentials across multiple clients or users. All users share the same access token. This approach is suitable for shared devices or environments where a consistent user identity is sufficient, but it reduces individual accountability and tracking. In cases where identity login is required, select User to Machine Shared.

Create a connection to the external service

First, create a Unity Catalog Connection to the external service that specifies a path and credentials to access the service.

Benefits of using a Unity Catalog Connection include the following:

• Secure credential management: Secrets and tokens are securely stored and managed in Unity Catalog, ensuring they are never exposed to users.
• Granular access control: Unity Catalog allows fine-grained control over who can use or manage connections with the USE_CONNECTION and MANAGE_CONNECTION privileges.
• Host-specific token enforcement: Tokens are restricted to the host_name specified during connection creation, ensuring they cannot be used with unauthorized hosts.

Permissions required: Metastore admin or user with the CREATE CONNECTION privilege.

Create a connection using one of the following methods:

• Use the Catalog Explorer UI.
• Execute the CREATE CONNECTION SQL command in a Databricks notebook or the Databricks SQL query editor.
• Use the Databricks REST API or the Databricks CLI to create a connection. See POST /api/2.1/unity-catalog/connections and Unity Catalog commands.

Catalog Explorer

Use the Catalog Explorer UI to create a connection.

1. In your Databricks workspace, click Catalog.

2. 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.

3. Click Create connection.

4. Enter a user-friendly Connection name.

5. Select a Connection type of HTTP.

6. Select an Auth type from the following options:

   • Bearer token
   • OAuth Machine to Machine
   • OAuth User to Machine Shared

7. 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
   note

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

8. Click Create connection.

SQL

Use the CREATE CONNECTION SQL command to create a connection.

note

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>'
)

Send an HTTP request to the external system

Now that you have a connection, learn how to send HTTP requests to the service using the http_request built-in SQL function.

Permissions required: USE CONNECTION on the connection object.

Run the following SQL command in a notebook or the Databricks SQL editor. Replace the placeholder values:

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: The connection object that specifies the host, port, base_path, and access credentials.
• http-method: The HTTP request method used to make the call. For example: GET, POST, PUT, DELETE
• path: The path to concatenate after the base_path to invoke the service resource.
• json: The JSON body to send with the request.
• headers: A map to specify the request headers.

Create a Unity Catalog function tool

After validating that the connection works properly, create a Unity Catalog function that uses the connection. The following example creates a Unity Catalog function tool that an agent can use to post a message to Slack:

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

Create a tool in agent code

To send HTTP requests to external services with Python, use the http_request function from the databricks-sdk library. This function sends an HTTP request to an external service using a Unity Catalog connection to authenticate.

Permissions required: USE CONNECTION on the connection object.

The following example makes an external HTTP request from inside agent code.

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: The connection object that specifies the host, port, base_path, and access credentials.
• method: The HTTP request method used to make the call. For example: GET, POST, PUT, DELETE
• path: The path to concatenate after the base_path to invoke the service resource.
• json: The JSON body to send with the request.
• headers: A Map to specify the request headers.

Example notebooks

The following notebooks demonstrate creating AI agent tools that connect to Slack, OpenAI, and Azure AI search.

Slack messaging agent tool

Open notebook in new tab

Microsoft Graph API agent tool

Open notebook in new tab

Azure AI Search agent tool

Open notebook in new tab