Menyambungkan agen ke layanan eksternal

Important

Fitur ini ada di Pratinjau Umum.

Hubungkan agen AI Anda ke aplikasi eksternal seperti Slack, Google Kalender, atau layanan apa pun dengan API. Azure Databricks menyediakan beberapa pendekatan tergantung pada apakah layanan eksternal memiliki server MCP, apakah Anda memerlukan autentikasi per pengguna, atau apakah Anda lebih suka memanggil API langsung dari kode agen. Semua pendekatan mengandalkan koneksi HTTP Katalog Unity untuk mengelola kredensial dengan aman dan mengatur akses ke layanan eksternal.

Pendekatan Kasus penggunaan yang direkomendasikan
Server MCP eksternal Gunakan pendekatan ini untuk layanan yang menerbitkan server MCP. Ini menyediakan penemuan alat otomatis dan berfungsi dengan SDK standar.
OAuth Terkelola Gunakan pendekatan ini untuk integrasi Google Drive atau SharePoint. Azure Databricks mengelola kredensial OAuth, sehingga tidak diperlukan pendaftaran aplikasi.
Proksi koneksi UC Gunakan pendekatan ini untuk melakukan panggilan REST API langsung dari kode agen menggunakan SDK klien layanan eksternal sendiri.
Alat fungsi UC Gunakan pendekatan ini untuk definisi alat berbasis SQL yang membungkus http_request() fungsi.

Requirements

  • Sebuah koneksi HTTP untuk Katalog Unity aplikasi eksternal Anda. Koneksi Katalog Unity menyediakan manajemen kredensial yang aman dan diatur dan mengaktifkan beberapa metode autentikasi, termasuk autentikasi pengguna ke mesin OAuth 2.0 dan autentikasi komputer-ke-mesin.

Server MCP eksternal

Jika layanan eksternal memiliki server MCP yang tersedia, Azure Databricks merekomendasikan untuk terhubung melalui server MCP external. Server MCP menyediakan penemuan alat otomatis, integrasi yang disederhanakan, dan autentikasi per pengguna. Lihat Menggunakan server MCP eksternal untuk metode penginstalan, penggunaan terprogram, dan detail autentikasi.

Menambahkan server MCP eksternal ke agen Anda

Setelah Anda mendaftarkan server MCP eksternal sebagai koneksi Katalog Unity, sambungkan agen Anda ke server tersebut menggunakan URL MCP terkelola: https://<workspace-hostname>/api/2.0/mcp/external/{connection_name}. Ganti <connection-name> dengan nama koneksi Katalog Unity Anda.

OpenAI Agents SDK (Aplikasi)

from agents import Agent, Runner
from databricks.sdk import WorkspaceClient
from databricks_openai.agents import McpServer

workspace_client = WorkspaceClient()
host = workspace_client.config.host

async with McpServer(
    url=f"{host}/api/2.0/mcp/external/<connection-name>",
    name="external-service",
    workspace_client=workspace_client,
) as external_server:
    agent = Agent(
        name="Connected agent",
        instructions="You are a helpful assistant with access to external services.",
        model="databricks-claude-sonnet-4-5",
        mcp_servers=[external_server],
    )
    result = await Runner.run(agent, "Send a Slack message to the team about the deployment")
    print(result.final_output)

Berikan akses aplikasi ke koneksi Unity Catalog di databricks.yml:

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_connection'
          uc_securable:
            securable_full_name: '<connection-name>'
            securable_type: 'CONNECTION'
            permission: 'USE_CONNECTION'

LangGraph (Aplikasi)

from databricks.sdk import WorkspaceClient
from databricks_langchain import ChatDatabricks, DatabricksMCPServer, DatabricksMultiServerMCPClient
from langgraph.prebuilt import create_react_agent

workspace_client = WorkspaceClient()
host = workspace_client.config.host

mcp_client = DatabricksMultiServerMCPClient([
    DatabricksMCPServer(
        name="external-service",
        url=f"{host}/api/2.0/mcp/external/<connection-name>",
        workspace_client=workspace_client,
    ),
])

async with mcp_client:
    tools = await mcp_client.get_tools()
    agent = create_react_agent(
        ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
        tools=tools,
    )
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "Send a Slack message to the team about the deployment"}]}
    )
    print(result["messages"][-1].content)

Berikan akses aplikasi ke koneksi Unity Catalog di databricks.yml:

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_connection'
          uc_securable:
            securable_full_name: '<connection-name>'
            securable_type: 'CONNECTION'
            permission: 'USE_CONNECTION'

Model Serving

from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksMCPClient
import mlflow

workspace_client = WorkspaceClient()
host = workspace_client.config.host

mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/external/<connection-name>",
    workspace_client=workspace_client,
)

tools = mcp_client.list_tools()

mlflow.pyfunc.log_model(
    "agent",
    python_model=my_agent,
    resources=mcp_client.get_databricks_resources(),
)

Untuk menyebarkan agen, lihat Menyebarkan agen untuk aplikasi AI generatif (Model Melayani). Untuk detail tentang agen pengelogan dengan sumber daya MCP, lihat Menggunakan server MCP terkelola Databricks.

Terkelola OAuth

Azure Databricks menawarkan alur OAuth terkelola untuk penyedia alat API tertentu. Anda tidak perlu mendaftarkan aplikasi OAuth Anda sendiri atau mengelola kredensial. Azure Databricks merekomendasikan OAuth Terkelola untuk pengembangan dan pengujian. Jika kasus penggunaan produksi memerlukan pembuatan kredensial OAuth kustom, lihat dokumentasi penyedia untuk informasi selengkapnya.

Integrasi berikut menggunakan kredensial OAuth yang dikelola Azure Databricks disimpan dengan aman di backend.

Provider Catatan konfigurasi Cakupan yang didukung Deskripsi
Google Drive API Tidak https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/documents.readonly https://www.googleapis.com/auth/spreadsheets.readonly offline_access Akses baca-saja ke file Google Drive.
SharePoint API Tidak https://graph.microsoft.com/Sites.Read.All offline_access openid profile Akses baca-saja ke situs SharePoint.

Untuk menyiapkan OAuth terkelola, buat koneksi HTTP dengan jenis autentikasi Pengguna OAuth ke Mesin Per Pengguna dan pilih penyedia Anda dari menu drop-down Penyedia OAuth . Untuk langkah-langkah mendetail, lihat Menginstal server MCP eksternal.

Setiap pengguna diminta untuk mengotorisasi dengan penyedia pada penggunaan pertama.

Jika diperlukan, izinkan daftar URI pengalihan berikut yang digunakan oleh OAuth terkelola:

Cloud Pengalihan URI
AWS https://oregon.cloud.databricks.com/api/2.0/http/oauth/redirect
Azure https://westus.azuredatabricks.net/api/2.0/http/oauth/redirect
GCP https://us-central1.gcp.databricks.com/api/2.0/http/oauth/redirect

Titik akhir proksi untuk koneksi UC

Gunakan titik akhir proksi koneksi Unity Catalog bersama SDK klien dari layanan eksternal tersebut untuk mengakses API REST langsung dari kode agen. Arahkan URL dasar SDK ke titik akhir proksi dan gunakan token Azure Databricks Anda sebagai kunci API. Azure Databricks mengautentikasi permintaan dan secara otomatis menyuntikkan kredensial layanan eksternal dari koneksi Katalog Unity. Kode Anda tidak pernah menangani token layanan eksternal secara langsung.

Izin diperlukan:USE CONNECTION pada objek koneksi.

OpenAI

Gunakan DatabricksOpenAI untuk merutekan panggilan ke OpenAI eksternal melalui perantara koneksi Katalog Unity. Pertama, buat koneksi HTTP Unity Catalog menggunakan kunci API OpenAI Anda yang disimpan sebagai rahasia Databricks:

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

Kemudian instal paket databricks-openai dan gunakan URL proksi serta klien ruang kerja di dalam kode agen Anda.

pip install databricks-openai

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

Konfigurasikan SDK Slack untuk mengalihkan melalui proksi koneksi Katalog Unity. Buat koneksi HTTP Katalog Unity dengan host https://slack.com dan jalur dasar /api, lalu gunakan URL proksi sebagai URL dasar SDK:

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"])

HTTP Generik

Untuk layanan tanpa SDK yang didedikasikan, gunakan pustaka requests dengan URL proksi secara langsung:

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"},
)

Alat fungsi UC dengan koneksi HTTP

Note

Azure Databricks merekomendasikan penggunaan server MCP atau proksi koneksi UC untuk integrasi baru. Alat fungsi UC dengan http_request tetap didukung tetapi bukan lagi pendekatan yang direkomendasikan.

Anda dapat membuat fungsi Katalog Unity yang dibungkus http_request() untuk memanggil layanan eksternal. Pendekatan ini berguna untuk definisi alat berbasis SQL. Lihat Membuat alat agen AI menggunakan fungsi Unity Catalog untuk detail tentang membuat alat fungsi UC.

Contoh berikut membuat alat fungsi Unity Catalog yang memposting pesan ke Slack:

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

Lihat CREATE FUNCTION (SQL dan Python).

Note

Akses SQL dengan http_request diblokir untuk jenis koneksi Pengguna-ke-Mesin Per Pengguna dan Pendaftaran Klien Dinamis. Gunakan SDK Python Azure Databricks sebagai gantinya.

Contoh buku catatan

Menyambungkan agen ke Slack

Lihat Menyambungkan agen AI ke Slack.

Menyambungkan agen ke Microsoft Teams

Lihat Hubungkan agen AI ke Microsoft Teams.

Alat koneksi eksternal

Notebook berikut menunjukkan pembuatan alat agen AI yang terhubung dengan Slack, OpenAI, dan pencarian Azure AI.

Alat agen olahpesan Slack

Dapatkan buku catatan

Alat agen Microsoft Graph API

Dapatkan buku catatan

perangkat agen Azure AI Search

Dapatkan buku catatan

  • Last updated on