Pular para o conteúdo principal
Última atualização em

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 a seção "Usar servidores MCP externos" para obter informações sobre métodos de instalação, uso programático e detalhes de autenticação.

Adicione um servidor MCP externo ao seu agente.​

Depois de registrar o servidor MCP externo como uma conexão Unity Catalog , conecte seu agente a ele usando o URL de gerenciamento do MCP: https://<workspace-hostname>/api/2.0/mcp/external/{connection_name}. Substitua <connection-name> pelo nome da sua conexão Unity Catalog .

Python
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)

Conceda ao aplicativo acesso à conexão Unity Catalog em databricks.yml:

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

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 https://www.googleapis.com/auth/documents.readonly https://www.googleapis.com/auth/spreadsheets.readonly offline_access

Acesso somente leitura aos arquivos do Google Drive.

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 Instalar um servidor MCP externo.

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.

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)

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 está bloqueado para o tipo de conexão Usuário para máquina por usuário. Utilize o SDK Python Databricks em seu lugar.

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

Limitações​

  • As conexões MCP externas não suportam conectividade privada com o recurso em sua VPC usando o serviço privado Connect. Se seus agentes AI precisarem se conectar ao recurso em sua VPC, entre em contato com sua equipe de suporte.