Conecte as ferramentas do agente AI ao serviço externo

Prévia

Esse recurso está em Pré-lançamento público.

Saiba como conectar as ferramentas do agente AI a aplicativos externos como Slack, Google Calendar ou qualquer serviço com um API usando solicitações HTTP. Os agentes podem usar ferramentas conectadas externamente para automatizar a tarefa, enviar mensagens e recuperar dados de plataformas de terceiros.

Para saber mais sobre as ferramentas do agente, consulte AI agent tools.

Requisitos

Para conectar ferramentas de agente a um serviço externo, o senhor deve atender aos seguintes requisitos:

Configure a autenticação para o serviço externo, usando um dos seguintes métodos:
- Tokens de portador: Obter tokens de portador para autenticação simples baseada em tokens.
- OAuth 2.0 Máquina a máquina: Crie um aplicativo e configure-o para habilitar a autenticação máquina a máquina.
- OAuth 2.0 Compartilhado de usuário para máquina: Autenticação com interação do usuário para compartilhar o acesso entre a identidade do serviço e a máquina.
Seu site workspace deve estar habilitado para Unity Catalog.
O senhor deve ter conectividade de rede de um Databricks compute recurso para o serviço externo. Veja as recomendações do Networking para a Lakehouse Federation.
O senhor deve usar um compute com modo de acesso de usuário único no Databricks Runtime 15.4 e acima.
O senhor deve ter um profissional ou serverless SQL warehouse. Consulte SQL warehouse types.

Métodos de autenticação para serviço externo

Tokens de portador: Um token de portador é um mecanismo de autenticação simples baseado em tokens, em que um token é emitido para um cliente e usado para acessar o recurso sem exigir credenciais adicionais. Os tokens são incluídos no cabeçalho da solicitação e concedem acesso desde que sejam válidos.

OAuth Máquina a Máquina: A autenticação OAuth Machine-to-Machine (M2M) é usada quando dois sistemas ou aplicativos precisam se comunicar sem o envolvimento direto do usuário. Os tokens são emitidos para um cliente de máquina registrado, que usa suas próprias credenciais para se autenticar. Isso é ideal para comunicação de servidor para servidor, microsserviços e tarefas de automação em que não é necessário nenhum contexto de usuário.

OAuth de usuário para máquina compartilhada: A autenticação OAuth User-to-Machine Shared permite que uma única identidade de usuário autentique e compartilhe o mesmo conjunto de credenciais entre vários clientes ou usuários. Todos os usuários compartilham os mesmos tokens de acesso. Essa abordagem é adequada para dispositivos ou ambientes compartilhados em que uma identidade de usuário consistente é suficiente, mas reduz a responsabilidade individual e o acompanhamento.

Criar uma conexão com o serviço externo

Primeiro, crie uma conexão do Unity Catalog com o serviço externo que especifique um caminho e as credenciais para acessar o serviço.

As vantagens de usar uma conexão do Unity Catalog incluem o seguinte:

Gerenciamento seguro de credenciais: Segredos e tokens são armazenados e gerenciados com segurança em Unity Catalog, garantindo que nunca sejam expostos aos usuários.
Controle de acesso granular: O Unity Catalog permite um controle refinado sobre quem pode usar ou gerenciar conexões com os privilégios USE_CONNECTION e MANAGE_CONNECTION.
Aplicação de tokens específicos do host: os tokens são restritos ao host_name especificado durante a criação da conexão, garantindo que não possam ser usados com hosts não autorizados.

Permissões necessárias: Administrador do Metastore ou usuário com o privilégio CREATE CONNECTION.

Crie uma conexão usando um dos seguintes métodos:

Use a interface do usuário do Catalog Explorer.
Execute o comando CREATE CONNECTION SQL em um notebook Databricks ou no editor de consultas Databricks SQL.
Use a API REST da Databricks ou a CLI da Databricks para criar uma conexão. Veja POST /api/2.1/unity-catalog/connections e Unity Catalog comando.

Use a interface do usuário do Catalog Explorer para criar uma conexão.

Em seu site Databricks workspace, clique em Catalog.
Na parte superior do painel Catálogo , clique no ícone Adicionar e selecione Adicionar uma conexão no menu.

Como alternativa, na página de acesso rápido, clique no botão Dados externos >, acesse a tab Conexões e clique em Criar conexão.
Clique em Criar conexão.
Insira um nome de conexão fácil de lembrar.
Selecione um tipo de conexão HTTP.
Selecione um tipo de autenticação entre as seguintes opções:
- Tokens de portador
- OAuth máquina a máquina
- Usuário OAuth para máquina compartilhada
Na página Autenticação, insira as seguintes propriedades de conexão para a conexão HTTP.

Para tokens ao portador:
- Anfitrião: Por exemplo, https://databricks.com
- Porto: Por exemplo, 443
- Tokens de portador: Por exemplo, bearer-token
- Caminho base: Por exemplo, /api/
Para OAuth tokens Machine to Machine:
- ID do cliente: identificador exclusivo para o aplicativo que você criou.
- Segredo do cliente: segredo ou senha gerada para o aplicativo que você criou.
- Escopo do OAuth: Escopo a ser concedido durante a autorização do usuário. O parâmetro de escopo é expresso como uma lista de espaços delimitados, com distinção entre maiúsculas e minúsculas strings. Por exemplo, channels:read channels:history chat:write
- tokens endpoint: Usado pelo cliente para obter tokens de acesso apresentando sua concessão de autorização ou tokens refresh. Normalmente no formato https://authorization-server.com/oauth/token
Para OAuth tokens compartilhados de usuário para máquina:
- ID do cliente: identificador exclusivo para o aplicativo que você criou.
- Segredo do cliente: segredo ou senha gerada para o aplicativo que você criou.
- Escopo do OAuth: Escopo a ser concedido durante a autorização do usuário. O parâmetro de escopo é expresso como uma lista de espaços delimitados, com distinção entre maiúsculas e minúsculas strings. Por exemplo, channels:read channels:history chat:write
- Autorização endpoint: Para autenticar com o proprietário do recurso por meio do redirecionamento do agente do usuário, geralmente no formato https://authorization-server.com/oauth/authorize
- tokens endpoint: Usado pelo cliente para obter tokens de acesso apresentando sua concessão de autorização ou tokens refresh. Normalmente no formato https://authorization-server.com/oauth/token
Observação

Para o OAuth User to Machine Shared, o usuário é solicitado a fazer login com HTTP usando suas credenciais OAuth.
Clique em Criar conexão.

Use o comando SQL CREATE CONNECTION para criar uma conexão.

Observação

O senhor não pode usar o comando SQL para criar uma conexão que use o OAuth Machine to User Shared. Em vez disso, consulte as instruções da interface do usuário do Catalog Explorer.

Para criar uma nova conexão usando tokens de portador, execute o seguinte comando em um notebook ou no editor de consultas Databricks SQL:

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  bearer_token '<bearer-token>'
);

Databricks recomenda o uso de segredos em vez de texto simples strings para valores confidenciais, como credenciais. Por exemplo:

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  bearer_token secret ('<secret-scope>','<secret-key-password>')
)

Para criar uma nova conexão usando OAuth Machine to Machine, execute o seguinte comando em um Notebook ou no editor de consultas Databricks SQL:

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  client_id '<client-id>'
  client_secret '<client-secret>'
  oauth_scope '<oauth-scope1> <oauth-scope-2>'
  token_endpoint '<token-endpoint>'
)

Enviar uma solicitação HTTP para o sistema externo

Agora que o senhor tem uma conexão, aprenda a enviar solicitações HTTP para o serviço usando a função SQL integrada http_request.

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

Execute o seguinte comando SQL em um notebook ou no editor Databricks SQL. Substitua os valores temporários:

SELECT http_request(
  conn => <connection-name>,
  method => <http-method>,
  path => <path>,
  json => to_json(named_struct(
    'text', text
  )),
  headers => map(
    'Accept', "application/vnd.github+json"
  )
);

connection-name: o objeto de conexão que especifica o host, a porta, o base_path e as credenciais de acesso.
http-method: o método de solicitação HTTP usado para fazer a chamada. Por exemplo: GET, POST, PUT, DELETE
path: O caminho a ser concatenado após o base_path para invocar o recurso de serviço.
json: O corpo JSON a ser enviado com a solicitação.
headers: Um mapa para especificar os cabeçalhos da solicitação.

Criar uma ferramenta de função do Unity Catalog

Depois de validar se a conexão funciona corretamente, crie uma função do Unity Catalog que use a conexão. O exemplo a seguir cria uma ferramenta de função do Unity Catalog que um agente pode usar para publicar uma mensagem no Slack:

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

Crie uma ferramenta no código do agente

Para enviar solicitações HTTP a um serviço externo com Python, use a função http_request da biblioteca databricks-sdk. Essa função envia uma solicitação HTTP a um serviço externo usando uma conexão do Unity Catalog para autenticação.

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

O exemplo a seguir faz uma solicitação HTTP externa a partir do código interno do agente.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ExternalFunctionRequestHttpMethod


WorkspaceClient().serving_endpoints.http_request(
  conn="connection_name",
  method=ExternalFunctionRequestHttpMethod.POST,
  path="/api/v1/resource",
  json={"key": "value"},
  headers={"extra_header_key": "extra_header_value"},
)

conn: o objeto de conexão que especifica o host, a porta, o base_path e as credenciais de acesso.
method: o método de solicitação HTTP usado para fazer a chamada. Por exemplo: GET, POST, PUT, DELETE
path: O caminho a ser concatenado após o base_path para invocar o recurso de serviço.
json: O corpo JSON a ser enviado com a solicitação.
headers: Um mapa para especificar os cabeçalhos da solicitação.

Notebooks de Exemplo

O seguinte Notebook demonstra como criar ferramentas de agente AI que se conectam ao Slack, OpenAI e Azure AI search.