Pular para o conteúdo principal

Conecte as ferramentas do agente AI ao serviço externo

info

Visualização

Esse recurso está em Public Preview.

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 e configure um aplicativo 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 dedicado (anteriormente, modo de acesso de usuário único) em 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 simples de autenticação 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 Machine to Machine (recomendado): A autenticação OAuth Machine-to-Machine (M2M) é usada quando dois sistemas ou aplicativos se comunicam 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. A Databricks recomenda o uso do OAuth Machine-to-Machine quando ele estiver disponível.

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. Nos casos em que o login de identidade é necessário, selecione Compartilhado de usuário para máquina.

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 com segurança e gerenciados 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 the Catalog Explorer UI to create a connection.

  1. In your Databricks workspace, click Catalog icon Catalog.

  2. At the top of the Catalog pane, click the Add or plus icon Add icon and select Add a connection from the menu.

    Alternatively, from the Quick access page, click the External data > button, go to the Connections tab, and click Create connection.

  3. Click Create connection.

  4. Enter a user-friendly Connection name.

  5. Select a Connection type of HTTP.

  6. Select an Auth type from the following options:

    • Bearer token
    • OAuth Machine to Machine
    • OAuth User to Machine Shared

  7. On the Authentication page, enter the following connection properties for the HTTP connection.

    For a bearer token:

    • Host: For example, https://databricks.com
    • Port: For example, 443
    • Bearer Token: For example, bearer-token
    • Base Path: For example, /api/

    For OAuth Machine to Machine token:

    • Client ID: Unique identifier for the application you created.
    • Client secret: Secret or password generated for the application that you created.
    • OAuth scope: Scope to grant during user authorization. The scope parameter is expressed as a list of space-delimited, case-sensitive strings. For example, channels:read channels:history chat:write
    • Token endpoint: Used by the client to obtain an access token by presenting its authorization grant or refresh token. Usually in the format https://authorization-server.com/oauth/token

    For OAuth User to Machine Shared token:

    • Client ID: Unique identifier for the application you created.

    • Client secret: Secret or password generated for the application that you created.

    • OAuth scope: Scope to grant during user authorization. The scope parameter is expressed as a list of space-delimited, case-sensitive strings. For example, channels:read channels:history chat:write

    • Authorization endpoint: To authenticate with the resource owner via user-agent redirection, usually in the format https://authorization-server.com/oauth/authorize

    • Token endpoint: Used by the client to obtain an access token by presenting its authorization grant or refresh token. Usually in the format https://authorization-server.com/oauth/token

nota

For OAuth User to Machine Shared, you are prompted to sign in with HTTP using your OAuth credentials.

  1. Click Create connection.

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:

SQL
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:

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

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.

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

Exemplo de notebook​

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

Open notebook in new tab

Microsoft gráfico API ferramenta de agente

Open notebook in new tab

Ferramenta de agente do Azure AI Search

Open notebook in new tab
Última atualização em