Skip to main content
Last updated on

Call REST APIs directly from agent code

Use the Unity Catalog connections proxy endpoint with the external service's own client SDK to call REST APIs directly from agent code. Point the SDK's base URL to the proxy endpoint and use your Databricks token as the API key. Databricks authenticates the request and automatically injects the external service's credentials from the Unity Catalog connection. Your code doesn't handle the external service's tokens directly.

Requirements​

  • A Unity Catalog HTTP connection for the external service. The proxy endpoint uses this connection to authenticate and inject the service's credentials.
  • USE CONNECTION on the connection object.

OpenAI​

Use DatabricksOpenAI to route calls to external OpenAI through the Unity Catalog connections proxy. First, create a Unity Catalog HTTP connection using your OpenAI API key stored as a Databricks secret:

SQL
CREATE CONNECTION openai_connection TYPE HTTP
OPTIONS (
  host 'https://api.openai.com',
  base_path '/v1',
  bearer_token secret ('<secret-scope>', '<secret-key>')
);

Then install the databricks-openai package and use the proxy URL and workspace client in your agent code:

Bash
pip install databricks-openai
Python
from databricks_openai import DatabricksOpenAI
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

client = DatabricksOpenAI(
    workspace_client=w,
    base_url=f"{w.config.host}/api/2.0/unity-catalog/connections/openai_connection/proxy/",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

Slack​

Configure the Slack SDK to route through the Unity Catalog connections proxy. Create a Unity Catalog HTTP connection with host https://slack.com and base path /api, then use the proxy URL as the SDK base URL:

Python
from slack_sdk import WebClient
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

client = WebClient(
    token=w.config.authenticate()["Authorization"].split(" ")[1],
    base_url=f"{w.config.host}/api/2.0/unity-catalog/connections/slack_connection/proxy/",
)

result = client.chat_postMessage(channel="C123456", text="Hello from Databricks!")
print(result["message"]["text"])

Generic HTTP​

For services without a dedicated SDK, use the requests library with the proxy URL directly:

Python
import requests
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

response = requests.post(
    f"{w.config.host}/api/2.0/unity-catalog/connections/my_connection/proxy/api/v1/resource",
    headers={
        **w.config.authenticate(),
        "Content-Type": "application/json",
    },
    json={"key": "value"},
)

For details on the proxy endpoint, supported authentication methods, and connection setup, see Forward requests through the HTTP connection proxy.

Wrap http_request() in a Unity Catalog function​

note

Databricks recommends the connections proxy shown above or MCP Services for connecting agents to external services. Unity Catalog function tools that wrap http_request remain supported but are no longer the recommended approach.

You can also create a Unity Catalog function that wraps http_request() to call external services, which is useful for SQL-based tool definitions. The function uses the same Unity Catalog HTTP connection as the proxy approach, referenced by name in the conn parameter.

The following example creates a Unity Catalog function tool that posts 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

See CREATE FUNCTION (SQL, Python, Scala, and Java).

note

SQL access with http_request is blocked for the User-to-Machine Per User and Dynamic Client Registration connection types. Use the Python Databricks SDK instead.

On this page