Conectar agentes a ferramentas
Conectar os seus agentes a ferramentas confere a eles capacidades práticas que vão além da geração de texto, como pesquisar documentos, consultar tabelas, chamar APIs externas ou executar código personalizado.
O diagrama mostra a rota MCP, que a Databricks recomenda para a maioria das integrações. MCP é uma das várias formas de conectar agentes a serviços externos. Juntamente com os Serviços MCP, é possível chamar APIs REST diretamente por meio de uma conexão HTTP do Unity Catalog. Selecione OAuth Gerenciado para autenticação por usuário, o proxy de conexões do Unity Catalog para chamar APIs do código do agente ou as ferramentas de função do Unity Catalog que encapsulam http_request(). A tabela a seguir resume cada forma de conexão, dos dados do Databricks para serviços externos:
Abordagem | Caso de uso recomendado |
|---|---|
Use esta abordagem para consultar dados do Databricks e executar funções governadas com os servidores MCP de funções prontos para uso: Genie, Databricks AI Search, Databricks SQL e Unity Catalog. | |
Use esta abordagem para serviços que publicam um servidor MCP. Ele oferece descoberta automática de ferramentas e acesso governado através do Unity AI Gateway. | |
Use esta abordagem para integrações com Google Drive ou SharePoint. A Databricks gerencia as credenciais do OAuth, portanto, nenhum registro de aplicativo é necessário. | |
Use esta abordagem para fazer chamadas diretas à API REST a partir do código do agente usando o SDK do cliente do serviço externo. | |
Use esta abordagem para definições de ferramentas baseadas em SQL que encapsulam a função |
Servidores MCP gerenciados para dados do Databricks
A Databricks oferece servidores MCP gerenciados prontos para usar que dão aos agentes acesso governado a dados e funções no seu workspace, sem servidor para construir ou hospedar. Cada servidor tem uma URL e um escopo OAuth dedicados, e o Unity Catalog governa o acesso:
- Genie : Consulte dados estruturados em agentes Genie e tabelas do Unity Catalog com linguagem natural.
- **Databricks AI Search (pesquisa vetorial)**: Pesquise documentos em índices de pesquisa vetorial.
- Databricks SQL : Execute consultas SQL em tabelas do Unity Catalog.
- Funções do Unity Catalog : chame funções personalizadas de Python e SQL registradas no Unity Catalog.
Para URLs de servidor, escopos de OAuth e o catálogo completo, consulte servidores MCP gerenciados do Databricks. Para chamar esses servidores do código do agente, consulte Use servidores MCP em agentes.
Servidores MCP externos
Conecte seus agentes a aplicativos externos como Slack, Google Calendar ou qualquer serviço com uma API. A Databricks oferece várias abordagens, dependendo se o serviço externo tem um servidor MCP, se é necessária autenticação por usuário ou se há preferência por chamar APIs diretamente do código do agente. Todas as abordagens dependem de uma conexão HTTP do Unity Catalog, que fornece gerenciamento de credenciais seguro e governado e oferece suporte a vários métodos de autenticação, incluindo autenticação OAuth 2.0 de usuário para máquina (U2M) e de máquina para máquina (M2M).
Se o serviço externo tiver um servidor MCP disponível, a Databricks recomenda registrá-lo como um Serviço MCP no Unity Catalog. Os Serviços MCP fornecem descoberta automática de ferramentas, autenticação por usuário e governança através do Unity AI Gateway com concessões, seleção de ferramentas e políticas de serviço.
- Consulte Registrar um servidor MCP externo para registrar um servidor MCP externo como um Serviço MCP e gerenciá-lo. Para a configuração de conexão e autenticação, consulte Etapa 1: Criar uma conexão.
- Veja Usar servidores MCP em agentes para exemplos de código por framework de agente (OpenAI Agents SDK, LangGraph, Model Serving).
Para ferramentas comuns de software como serviço (SaaS), como Slack, GitHub e Google Drive, a Databricks oferece Serviços MCP prontos para uso com configuração zero. Consulte Serviços MCP fornecidos pela Databricks.
OAuth Gerenciado
O Databricks oferece fluxos de OAuth gerenciados para provedores de ferramentas de API selecionados. Você não precisa registrar seu próprio aplicativo OAuth ou gerenciar credenciais. O Databricks recomenda o OAuth Gerenciado para desenvolvimento e teste. Se os casos de uso de 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 usam credenciais OAuth que a Databricks gerencia e armazena com segurança no backend.
Provedor | Notas de configuração | Escopos compatíveis | Descrição |
|---|---|---|---|
API do Google Drive | Nenhuma |
| Acesso somente para leitura a arquivos do Google Drive, incluindo Google Docs e Google Sheets. |
API do Gmail | Nenhuma |
| Acesso somente para leitura a mensagens do Gmail, conversas, rascunhos e rótulos. |
API do Google Calendar | Nenhuma |
| Acesso somente para leitura a eventos do Google Agenda, calendários e informações de disponibilidade. |
API do SharePoint | Nenhuma |
| Acesso somente leitura via Microsoft Graph a arquivos do SharePoint e OneDrive, e-mail e calendário do Outlook, e chats, canais e reuniões do Microsoft Teams. |
Para configurar o OAuth gerenciado, crie uma conexão HTTP com o tipo de autenticação **OAuth User to Machine Per User** e selecione seu provedor no menu suspenso **OAuth Provider**. Para obter os passos detalhados, consulte Criar uma conexão com o serviço externo.
O provedor solicita a cada usuário que autorize no primeiro uso.
Se necessário, adicione à lista de permissões os seguintes URIs de redirecionamento que o OAuth gerenciado usa:
Nuvem | URI de redirecionamento |
|---|---|
AWS |
|
Azure |
|
GCP |
|
Para provedores OAuth gerenciados com um servidor MCP publicado, como Glean, GitHub, Atlassian e Slack, o Databricks pode gerenciar as credenciais OAuth ao registrar o servidor como um Serviço MCP. Consulte Provedores de OAuth gerenciados.
Endpoint de proxy de conexões do Unity Catalog
Use o endpoint de proxy de conexões do Unity Catalog com o SDK do cliente próprio do serviço externo para chamar as APIs REST diretamente do código do agente. Aponte a URL base do SDK para o endpoint de proxy e use seu token do Databricks como a API key. O Databricks autentica a solicitação e injeta automaticamente as credenciais do serviço externo da conexão do Unity Catalog. Seu código não lida diretamente com os tokens do serviço externo.
Permissões necessárias: USE CONNECTION no objeto de conexão.
- OpenAI
- Slack
- Generic HTTP
Use DatabricksOpenAI para encaminhar chamadas para o OpenAI externo por meio do proxy de conexões do Unity Catalog. Primeiro, crie uma conexão HTTP do Unity Catalog usando sua chave de API do OpenAI armazenada como um segredo do Databricks:
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 a URL proxy e o cliente do workspace em seu código de agente:
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)
Configure o SDK do Slack para rotear pelo proxy de conexões do Unity Catalog. Crie uma conexão HTTP do Unity Catalog com o host https://slack.com e o caminho base /api; depois, use a URL de proxy como a URL base do 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"])
Para serviços sem um SDK dedicado, use a biblioteca requests diretamente com o URL de proxy:
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"},
)
Para obter detalhes sobre o endpoint de proxy, métodos de autenticação suportados e configuração de conexão, veja Encaminhar solicitações através do proxy de conexão HTTP.
Ferramentas de função do Unity Catalog
A Databricks recomenda usar Serviços MCP ou o proxy de conexões do Unity Catalog para novas integrações. As ferramentas de função do Unity Catalog com http_request permanecem compatíveis, mas não são mais a abordagem recomendada.
Você pode criar uma função do Unity Catalog que encapsula http_request() para chamar serviços externos. Essa abordagem é útil para definições de ferramenta baseadas em SQL, como uma função que publica uma mensagem no Slack. Para o passo a passo completo, incluindo o exemplo de SQL e as limitações de tipo de conexão, consulte Chamar APIs externas com http_request (legado).
Notebooks de exemplo
Os seguintes notebooks demonstram a criação de ferramentas de agente de AI que se conectam ao Slack, OpenAI e Azure AI Search.
Ferramenta de agente de mensagens do Slack
Ferramenta de agente da API do gráfico da Microsoft
Ferramenta de agente do Azure AI Search
Limitações
- As conexões MCP externas não oferecem suporte a conectividade privada a recursos em sua nuvem privada virtual (VPC) usando o Private Service Connect. Se seus agentes de AI precisarem se conectar a recursos em sua VPC, entre em contato com sua equipe de suporte.
Recursos adicionais
- Conecte agentes a ferramentas de terceiros com serviços MCP para registrar e gerenciar servidores MCP externos.
- Crie ferramentas de agente de AI usando funções do Unity Catalog para construir ferramentas de função do Unity Catalog, incluindo a abordagem herdada
http_request. - Integre ferramentas do Unity Catalog com frameworks de AI generativa de terceiros para usar ferramentas do Unity Catalog com LangChain, LlamaIndex, OpenAI e Anthropic.
- Conecte-se a serviços HTTP externos para configurar conexões HTTP e o proxy de conexões.