Conecte agentes a ferramentas
Conectar seus agentes a ferramentas lhes dá 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. Além dos serviços MCP, você pode 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 ferramentas de função do Unity Catalog que envolvem http_request(). A tabela a seguir resume cada forma de conectar, de dados do Databricks a 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ção do Genie, Databricks AI Search, Databricks SQL e Unity Catalog prontos para uso. | |
Use esta abordagem para serviços que publicam um Servidor MCP. Oferece descoberta automática de ferramentas e acesso governado por meio do Unity AI Gateway. | |
Use esta abordagem para integrações com Google Drive ou SharePoint. A Databricks gerencia as credenciais OAuth, portanto nenhum registro do aplicativo é necessário. | |
Use esta abordagem para fazer chamadas diretas da API REST do código do agente usando o SDK do cliente do serviço externo. | |
Use essa abordagem para definições de ferramentas baseadas em SQL que envolvem a função |
Servidores MCP gerenciados para dados do Databricks
A Databricks oferece servidores MCP gerenciados prontos para uso que concedem aos agentes acesso governado a dados e funções em seu Workspace, sem a necessidade de criar ou hospedar um servidor. Cada servidor tem um URL e um escopo OAuth dedicados, e o Unity Catalog governa o acesso:
- **Genie**: Faça query de 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 queries SQL em tabelas do Unity Catalog.
- Funções do Unity Catalog : chame funções personalizadas em Python e SQL registradas no Unity Catalog.
Para URLs de servidor, escopos OAuth e o catálogo completo, consulte servidores MCP gerenciados da Databricks. Para chamar esses servidores do código do agente, consulte Usar servidores MCP em agentes.
Servidores MCP externos
Conecte seus agentes a aplicativos externos como Slack, Google Agenda ou qualquer serviço com uma API. A Databricks oferece diversas abordagens dependendo se o serviço externo tem 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 do Unity Catalog, que fornece gerenciamento de credenciais seguro e governado e suporta 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, o 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 por meio 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 governá-lo. Para configuração de conexão e autenticação, consulte Etapa 1: Criar uma conexão.
- Consulte 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 usar com configuração zero. Consulte Serviços MCP fornecidos pela Databricks.
OAuth Gerenciado
A Databricks oferece fluxos OAuth gerenciados para provedores de ferramentas de API selecionados. Você não precisa registrar seu próprio aplicativo OAuth ou gerenciar credenciais. A Databricks recomenda o OAuth Gerenciado para desenvolvimento e teste. 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 usam credenciais OAuth que a Databricks gerencia e armazena de forma segura no backend.
Provedor | Observações da configuração. | Escopos suportados | Descrição |
|---|---|---|---|
Google Drive API | Nenhuma |
| Acesso somente leitura aos arquivos do Google Drive, incluindo o Google Docs e o Planilhas do Google. |
API do Gmail | Nenhuma |
| Acesso somente para leitura a mensagens, conversas, rascunhos e rótulos do Gmail. |
API do Google Calendar | Nenhuma |
| Acesso somente leitura a eventos do Google Agenda, calendários e informações de disponibilidade/ocupação. |
API do SharePoint | Nenhuma |
| Acesso somente leitura via Microsoft gráfico a arquivos do SharePoint e do 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 Usuário para Máquina por Usuário** e selecione seu provedor no menu suspenso **Provedor OAuth**. Para obter passos detalhados, consulte Criar uma conexão com o serviço externo.
O provedor solicita que cada usuário autorize no primeiro uso.
Se necessário, coloque na lista de permissões os seguintes URIs de redirecionamento usados pelo OAuth gerenciado:
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 quando você registra o servidor como um Serviço MCP. Consulte provedores OAuth gerenciados.
Endpoint proxy de conexões do Unity Catalog
Use o Endpoint proxy de conexões do Unity Catalog com o SDK de cliente próprio do serviço externo para chamar APIs REST diretamente do código do agente. Aponte a URL base do SDK para o Endpoint proxy e use seu token Databricks como a chave da API. 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 rotear 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 de proxy e o cliente do workspace no código do seu 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 através do proxy de conexões do Unity Catalog. Crie uma conexão HTTP do Unity Catalog com host https://slack.com e caminho base /api; em seguida, 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 a 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 compatíveis e configuração de conexão, consulte Encaminhar solicitações por meio do proxy de conexão HTTP.
Ferramentas de função do Unity Catalog
A Databricks recomenda o uso de 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 continuam suportadas, 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 ferramentas baseadas em SQL, como uma função que publica uma mensagem no Slack. Para obter o passo a passo completo, incluindo o exemplo de SQL e as limitações do 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 Microsoft Graph
Ferramenta de agente do Azure AI Search
Recursos adicionais
- Conecte agentes a ferramentas de terceiros com os Serviços MCP para registrar e governar 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 as ferramentas do Unity Catalog com frameworks de AI generativa de terceiros para usar as ferramentas do Unity Catalog com LangChain, LlamaIndex, OpenAI e Anthropic.
- Conectar a serviços HTTP externos para configurar conexões HTTP e o proxy de conexões.