Ligue agentes a ferramentas

Ligar os seus agentes a ferramentas dá-lhes capacidades práticas para 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 o Azure Databricks recomenda para a maioria das integrações. O MCP é uma das várias formas de ligar agentes a serviços externos. Para além dos Serviços MCP, pode chamar APIs REST diretamente através de uma ligação HTTP do Unity Catalog. Selecione Managed OAuth para autenticação por utilizador, o proxy de ligações do Unity Catalog para chamar APIs a partir do código do agente, ou as ferramentas funcionais do Unity Catalog que envolvem http_request(). A tabela seguinte resume cada forma de ligar, desde dados do Azure Databricks até serviços externos:

Approach	Caso de uso recomendado
Servidores MCP geridos para dados do Azure Databricks	Use esta abordagem para consultar dados do Azure Databricks e executar funções governadas com os servidores MCP prontos a usar Genie, Databricks AI Search, Databricks SQL e Unity Catalog.
Servidores MCP externos	Use esta abordagem para serviços que publiquem um servidor MCP. Oferece descoberta automática de ferramentas e acesso governado através do Unity AI Gateway.
OAuth Gerido	Use esta abordagem para integrações com Google Drive ou SharePoint. O Azure Databricks gere as credenciais OAuth, por isso não é necessário registo de aplicações.
Proxy de ligações do Unity Catalog	Use esta abordagem para fazer chamadas diretas à API REST a partir do código do agente usando o próprio SDK cliente do serviço externo.
Ferramentas funcionais do Unity Catalog	Use esta abordagem para definições de ferramentas baseadas em SQL que envolvem a http_request() função.

Servidores MCP geridos para dados do Azure Databricks

O Azure Databricks oferece servidores MCP geridos prontos a usar que dão aos agentes acesso governado a dados e funções no seu espaço de trabalho, sem servidor para construir ou alojar. Cada servidor tem uma URL dedicada e um âmbito OAuth, e o Unity Catalog regula o acesso:

• Genie: Consultar dados estruturados em Agentes Genie e tabelas do Catálogo Unity com linguagem natural.
• Databricks AI Search (pesquisa vetorial): Pesquise documentos em índices de pesquisa vetorial.
• Databricks SQL: Executar consultas SQL em tabelas do Unity Catalog.
• Funções do Catálogo Unity: Chama funções personalizadas em Python e SQL registadas no Catálogo Unity.

Para os URLs dos servidores, os âmbitos do OAuth e o catálogo completo, consulte Azure Databricks managed MCP servers. Para chamar estes servidores a partir do código do agente, veja Usar servidores MCP nos agentes.

Servidores MCP externos

Ligue os seus agentes a aplicações externas como Slack, Google Calendar ou qualquer serviço com API. O Azure Databricks oferece várias abordagens dependendo se o serviço externo tem um servidor MCP, se precisa de autenticação por utilizador, ou se prefere chamar APIs diretamente a partir do código do agente. Todas as abordagens dependem de uma ligação HTTP do Unity Catalog, que fornece uma gestão segura e governada de credenciais e suporta múltiplos métodos de autenticação, incluindo autenticação OAuth 2.0 utilizador-para-máquina (U2M) e máquina para máquina (M2M).

Se o serviço externo tiver um servidor MCP disponível, o Azure Databricks recomenda registo-lo como um Serviço MCP no Unity Catalog. Os Serviços MCP fornecem descoberta automática de ferramentas, autenticação por utilizador e governação através do Unity AI Gateway , com subsídios, seleção de ferramentas e políticas de serviço.

• Veja Registar um servidor MCP externo para registar um servidor MCP externo como Serviço MCP e governá-lo. Para configuração de ligação e autenticação, veja Passo 1. Cria uma ligação.
• Consulte Use MCP servers in agents para exemplos de código por framework de agentes (OpenAI Agents SDK, LangGraph, Model Serving).

Para ferramentas comuns de software como serviço (SaaS) como Slack, GitHub e Google Drive, o Azure Databricks fornece Serviços MCP prontos a usar sem qualquer configuração. Consulte Serviços MCP fornecidos pela Databricks.

OAuth Gerido

O Azure Databricks oferece fluxos OAuth geridos para fornecedores selecionados de ferramentas API. Não precisas de registar a tua própria aplicação OAuth nem de gerir credenciais. O Azure Databricks recomenda o Managed OAuth para desenvolvimento e testes. Se casos de uso em produção exigirem a geração de credenciais OAuth personalizadas, consulte a documentação dos fornecedores para mais informações.

As seguintes integrações utilizam credenciais OAuth que o Azure Databricks gere e armazena de forma segura no backend.

Provider	Notas de configuração	Escopos suportados	Description
Google Drive API	None	https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/documents.readonly https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/drive.file offline_access	Leia o acesso a ficheiros do Google Drive, incluindo Google Docs e Google Sheets, além do acesso de escrita aos ficheiros criados ou abertos pela aplicação.
Gmail API	None	https://www.googleapis.com/auth/gmail.modify offline_access	Leia e escreva acesso a mensagens, tópicos, rascunhos e rótulos do Gmail.
Google Calendar API	None	https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events offline_access	Leia o acesso aos calendários do Google Calendar e informações gratuitas/ocupadas, além de acesso de leitura e escrita a eventos.
Microsoft 365 API	None	https://graph.microsoft.com/Sites.Read.All https://graph.microsoft.com/User.Read https://graph.microsoft.com/Files.Read.All https://graph.microsoft.com/Chat.Read https://graph.microsoft.com/Channel.ReadBasic.All https://graph.microsoft.com/ChannelMessage.Read.All https://graph.microsoft.com/Mail.Read https://graph.microsoft.com/Mail.Read.Shared https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Calendars.Read.Shared https://graph.microsoft.com/OnlineMeetingTranscript.Read.All https://graph.microsoft.com/OnlineMeetingAiInsight.Read.All https://graph.microsoft.com/OnlineMeetingArtifact.Read.All https://graph.microsoft.com/OnlineMeetingRecording.Read.All https://graph.microsoft.com/User.ReadBasic.All https://graph.microsoft.com/Team.ReadBasic.All https://graph.microsoft.com/Sites.ReadWrite.All https://graph.microsoft.com/ChatMessage.Send https://graph.microsoft.com/ChannelMessage.Send https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/Calendars.ReadWrite offline_access openid profile email	Leia e escreva acesso via Microsoft Graph a ficheiros SharePoint e OneDrive, correio e calendário do Outlook, e chats, canais e reuniões do Microsoft Teams.

Para configurar o OAuth gerido, crie uma ligação HTTP com o tipo de autenticação OAuth User to Machine Per User e selecione o seu fornecedor no menu suspenso de OAuth Provider. Para passos detalhados, consulte Criar uma ligação ao serviço externo.

O fornecedor solicita a cada utilizador que autorize à primeira utilização.

Se necessário, permita listar os seguintes URIs de redirecionamento que o OAuth gerido utiliza:

Nuvem	Redirecionar URL
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

Para fornecedores OAuth geridos com um servidor MCP publicado, como Glean, GitHub, Atlassian e Slack, o Azure Databricks pode gerir as credenciais OAuth quando regista o servidor como um Serviço MCP. Veja Fornecedores OAuth Geridos.

Endpoint de proxy das ligações do Unity Catalog

Utilize o endpoint proxy de ligações do Unity Catalog com o SDK de cliente do serviço externo para chamar diretamente as APIs REST a partir do código do agente. Direcione a URL base do SDK para o endpoint do proxy e use o seu token Azure Databricks como chave de API. O Azure Databricks autentica o pedido e injeta automaticamente as credenciais do serviço externo a partir da ligação ao Unity Catalog. O teu 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

Uso DatabricksOpenAI para encaminhar chamadas para OpenAI externo através do proxy de ligações do Unity Catalog. Primeiro, crie uma ligação HTTP ao Unity Catalog usando a sua chave API OpenAI armazenada como segredo Databricks:

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

Depois instala o pacote databricks-openai e usa a URL do proxy e o cliente de espaço de trabalho 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)

Slack

Configure o Slack SDK para fazer o encaminhamento através do proxy de conexões do Unity Catalog. Crie uma ligação HTTP do Unity Catalog com o anfitrião https://slack.com e o caminho base /api, depois use a URL do proxy como 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"])

HTTP genérico

Para serviços sem SDK dedicado, use a biblioteca requests com o URL proxy diretamente.

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 detalhes sobre o endpoint proxy, métodos de autenticação suportados e configuração de ligação, consulte Encaminhar pedidos através do proxy de ligação HTTP.

Ferramentas funcionais do Unity Catalog

Observação

O Azure Databricks recomenda usar os Serviços MCP ou o proxy de ligações do Unity Catalog para novas integrações. As ferramentas de função do Unity Catalog com http_request continuam a ser suportadas, mas deixaram de ser a abordagem recomendada.

Pode criar uma função do Unity Catalog que encapsula http_request() para efetuar chamadas a serviços externos. Esta abordagem é útil para definições de ferramentas baseadas em SQL, como uma função que publica uma mensagem no Slack. Para o guia completo, incluindo o exemplo do SQL e as limitações do tipo de ligação, veja Chamar APIs externas com http_request (legacy).

Exemplos de cadernos

Os cadernos seguintes demonstram como criar ferramentas de agentes que se ligam ao Slack, OpenAI e Pesquisa de IA do Azure.

Ferramenta de agente de mensagens do Slack

Obter caderno

Ferramenta de agente da API do Microsoft Graph

Obter caderno

Ferramenta de agente de pesquisa do Azure AI

Obter caderno

Para um guia sobre como ligar um agente ao Microsoft Teams, consulte Ligar um agente ao Microsoft Teams.

Recursos adicionais

• Ligue agentes a ferramentas de terceiros com Serviços MCP para registar e governar servidores MCP externos.
• Criar ferramentas de agente usando funções do Catálogo Unity para construir ferramentas de funções do Catálogo Unity, incluindo a abordagem legada http_request .
• Integrar as ferramentas do Unity Catalog com frameworks de IA de terceiros para usar as ferramentas do Unity Catalog com LangChain, LlamaIndex, OpenAI e Anthropic.
• Ligue-se a serviços HTTP externos para configurar as ligações HTTP e o proxy de ligações.