Conectar agentes a serviços externos

info

Visualização

Esse recurso está em Public Preview.

Conecte seus agentesAI a aplicativos externos como Slack, Google Agenda ou qualquer serviço com uma API. O Databricks oferece diversas abordagens, dependendo se o serviço externo possui um servidor MCP, se você precisa de autenticação por usuário ou se prefere chamar APIs diretamente do código do agente. Todas as abordagens dependem de uma conexão HTTP Unity Catalog para gerenciar credenciais com segurança e controlar o acesso a serviços externos.

Abordagem	Caso de uso recomendado
Servidores MCP externos	Utilize esta abordagem para serviços que publicam um servidor MCP. Ele oferece descoberta automática de ferramentas e funciona com SDKs padrão.
OAuth	Utilize essa abordagem para integrações com o Google Drive ou SharePoint. Databricks gerencia as credenciais OAuth , portanto, não é necessário registrar o aplicativo.
proxy de conexões UC	Utilize essa abordagem para fazer chamadas diretas à API REST a partir do código do agente, usando o SDK do cliente do serviço externo.
ferramentas de função UC	Use esta abordagem para definições de ferramentas baseadas em SQL que envolvem a função http_request() .

Requisitos

• Uma conexão HTTP do Unity Catalog para sua aplicação externa. As conexões do Unity Catalog fornecem gerenciamento de credenciais seguro e controlado, além de habilitarem múltiplos métodos de autenticação, incluindo autenticação OAuth 2.0 de usuário para máquina e de máquina para máquina.

Servidores MCP externos

Se o serviço externo tiver um servidor MCP disponível, a Databricks recomenda a conexão por meio de servidores MCP externos. Os servidores MCP oferecem descoberta automática de ferramentas, integração simplificada e autenticação por usuário.

• Consulte Instalar um servidor MCP externo para obter informações sobre a instalação e a configuração de autenticação.
• Consulte Usar servidores MCP externos em agentes para exemplos de código por estrutura de agente (OpenAI Agents SDK, LangGraph, servindo modelo).

OAuth

Databricks oferece gerenciamento de fluxos OAuth para provedores de ferramentas API selecionados. Você não precisa registrar seu próprio aplicativo OAuth nem gerenciar credenciais. Databricks recomenda o gerenciamento OAuth para desenvolvimento e testes. Se os casos de uso em produção exigirem a geração de credenciais OAuth personalizadas, consulte a documentação dos provedores para obter mais informações.

As seguintes integrações utilizam credenciais OAuth Databricks-gerenciar armazenadas com segurança no backend.

Provedor	Notas de configuração	Escopos suportados	Descrição
API do Google Drive	Nenhuma	https://www.googleapis.com/auth/drive.readonly offline_access	Acesso somente leitura aos arquivos do Google Drive, incluindo Google Docs e Google Sheets.
API do SharePoint	Nenhuma	https://graph.microsoft.com/Sites.Read.All offline_access openid profile	Acesso somente leitura aos sites do SharePoint.

Para configurar o gerenciamento OAuth, crie uma conexão HTTP com o tipo de autenticação OAuth Usuário para Máquina por Usuário" e selecione seu provedor no menu suspenso "ProvedorOAuth . Para obter instruções detalhadas sobre os passos, consulte Métodos de instalação.

Cada usuário é solicitado a autorizar o acesso junto ao provedor no primeiro uso.

Caso necessário, adicione à lista de permissões os seguintes URIs de redirecionamento usados pelo gerenciamento OAuth:

Nuvem	URI de redirecionamento
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

endpoint proxy de conexões UC

Utilize o endpoint proxy de conexões do Unity Catalog com o SDK de cliente do serviço externo para chamar APIs REST diretamente do código do agente. Aponte o URL base do SDK para o endpoint do proxy e use seus tokens Databricks como key da API . O Databricks autentica a solicitação e injeta automaticamente as credenciais do serviço externo a partir da conexão do Unity Catalog. Seu código nunca manipula diretamente os tokens do serviço externo.

Permissões necessárias: USE CONNECTION no objeto de conexão.

OpenAI

Use DatabricksOpenAI para encaminhar chamadas para OpenAI externo através do proxy de conexões Unity Catalog . Primeiro, crie uma conexão HTTP com Unity Catalog usando sua key API OpenAI armazenada como um segredoDatabricks:

SQL

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

Em seguida, instale o pacote databricks-openai e use o URL do proxy e o cliente workspace no código do seu agente:

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 o SDK do Slack para rotear as conexões através do proxy Unity Catalog . Crie uma conexão HTTP Unity Catalog com o host https://slack.com e o caminho base /api e, em seguida, use a URL do proxy como a URL base SDK :

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

Para serviços sem um SDK dedicado, use a biblioteca requests com a URL do proxy diretamente:

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

Ferramentas de função UC com conexões HTTP

nota

A Databricks recomenda o uso de servidores MCP ou do proxy de conexões UC para novas integrações. As ferramentas de função UC com http_request continuam a ser suportadas, mas já não são a abordagem recomendada.

Você pode criar uma função Unity Catalog que encapsula http_request() para chamar um serviço externo. Essa abordagem é útil para definições de ferramentas baseadas em SQL. Consulte Criar ferramentas de agente AI usando funções Unity Catalog para obter detalhes sobre como criar ferramentas de função UC.

O exemplo a seguir cria uma ferramenta de função Unity Catalog que publica uma mensagem no 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

Consulte CREATE FUNCTION (SQL e Python).

nota

O acesso SQL com http_request é bloqueado para os tipos de conexão Usuário-para-Máquina Por Usuário e Registro Dinâmico de Cliente. Em vez disso, use o SDK do Databricks para Python.

Exemplo de notebook

Conectar um agente ao Slack

Consulte Conectar um agente do AI ao Slack.

Ferramentas de conexão externa

O seguinte Notebook demonstra a criação de ferramentas do agente AI que se conectam ao Slack, OpenAI e Azure AI search.

Ferramenta de agente de mensagens do Slack

Abrir notebook em uma nova aba

Microsoft gráfico API ferramenta de agente

Abrir notebook em uma nova aba

Ferramenta de agente do Azure AI Search

Abrir notebook em uma nova aba