외부 서비스에 AI 에이전트 도구 연결

아티클
02/10/2025

중요하다

HTTP 요청을 사용하여 API를 사용하여 AI 에이전트 도구를 Slack, Google Calendar 또는 모든 서비스와 같은 외부 애플리케이션에 연결하는 방법을 알아봅니다. 에이전트는 외부에 연결된 도구를 사용하여 작업을 자동화하고, 메시지를 보내고, 타사 플랫폼에서 데이터를 검색할 수 있습니다.

에이전트 도구에 대한 자세한 내용은 AI 에이전트 도구참조하세요.

요구 사항

에이전트 도구를 외부 서비스에 연결하려면 다음 요구 사항을 충족해야 합니다.

다음 방법 중 하나를 사용하여 외부 서비스에 대한 인증을 설정합니다.
- 전달자 토큰: 간단한 토큰 기반 인증을 위해 전달자 토큰을 가져옵니다.
- OAuth 2.0 Machine-to-Machine: 머신-컴퓨터 인증을 사용하도록 앱을 만들고 구성합니다.
- OAuth 2.0 사용자 간 공유: 사용자 상호 작용을 사용하여 인증하여 서비스 ID와 컴퓨터 간에 액세스를 공유합니다.
작업 영역은 Unity 카탈로그를 사용하도록 설정해야 합니다.
Databricks 컴퓨팅 리소스에서 외부 서비스로의 네트워크 연결이 있어야 합니다. Lakehouse Federation 대한네트워킹 권장 사항을 참조하세요.
Databricks Runtime 15.4 이상에서 단일 사용자 액세스 모드로 컴퓨팅을 사용해야 합니다.
PRO 또는 서버리스 SQL 웨어하우스가 있어야 합니다. SQL 웨어하우스 유형참조하세요.

외부 서비스에 대한 인증 방법

전달자 토큰: 전달자 토큰은 토큰이 클라이언트에 발급되고 추가 자격 증명 없이 리소스에 액세스하는 데 사용되는 간단한 토큰 기반 인증 메커니즘입니다. 토큰은 요청 헤더에 포함되며 유효한 한 액세스 권한을 부여합니다.

OAuth Machine to Machine(M2M) 간 (권장): 두 시스템 또는 애플리케이션이 직접 사용자의 개입 없이 통신할 때 OAuth Machine to Machine(M2M) 인증이 사용됩니다. 토큰은 자체 자격 증명을 사용하여 인증하는 등록된 컴퓨터 클라이언트에 발급됩니다. 이는 사용자 컨텍스트가 필요하지 않은 서버 간 통신, 마이크로 서비스 및 자동화 작업에 적합합니다. Databricks는 사용 가능한 경우 OAuth Machine-to-Machine을 사용하는 것이 좋습니다.

OAuth 사용자를 컴퓨터 공유로 : OAuth 사용자 간 공유 인증을 사용하면 단일 사용자 ID가 여러 클라이언트 또는 사용자 간에 동일한 자격 증명 집합을 인증하고 공유할 수 있습니다. 모든 사용자는 동일한 액세스 토큰을 공유합니다. 이 방법은 일관된 사용자 ID가 충분한 공유 디바이스 또는 환경에 적합하지만 개별 책임 및 추적을 줄입니다. ID 로그인이 필요한 경우 사용자-컴퓨터 공유를 선택합니다.

외부 서비스에 대한 연결 만들기

먼저 서비스에 액세스할 경로 및 자격 증명을 지정하는 외부 서비스에 대한 Unity 카탈로그 연결을 만듭니다.

Unity 카탈로그 연결을 사용할 경우의 이점은 다음과 같습니다.

보안 자격 증명 관리: 비밀 및 토큰은 Unity 카탈로그에 안전하게 저장되고 관리되므로 사용자에게 노출되지 않습니다.
세분화된 액세스 제어: Unity 카탈로그를 사용하면 USE_CONNECTION 및 MANAGE_CONNECTION 권한으로 연결을 사용하거나 관리할 수 있는 사용자를 세밀하게 제어할 수 있습니다.
호스트별 토큰 적용: 토큰은 연결 생성 중에 지정된 host_name 제한되므로 권한이 없는 호스트와 함께 사용할 수 없습니다.

필요한 Metastore 관리자 또는 사용자입니다.

다음 방법 중 하나를 사용하여 연결을 만듭니다.

카탈로그 탐색기 UI를 사용합니다.
Azure Databricks Notebook 또는 Databricks SQL 쿼리 편집기에서 CREATE CONNECTION SQL 명령을 실행합니다.
Databricks REST API 또는 Databricks CLI를 사용하여 연결을 만듭니다. POST /api/2.1/unity-catalog/connections 및 Unity Catalog 명령참조하세요.

카탈로그 탐색기

카탈로그 탐색기 UI를 사용하여 연결을 만듭니다.

Azure Databricks 작업 영역에서 카탈로그를 클릭합니다.
카탈로그 창 위쪽에서 추가 아이콘을 클릭하고 메뉴에서 연결 추가를 선택합니다.

또는 빠른 액세스 페이지에서 외부 데이터 > 단추를 클릭하고 연결 탭으로 이동한 다음 연결만들기를 클릭합니다.
연결을 만들기 위해을 클릭합니다.
사용자에게 친숙한 연결 이름입력합니다.
연결 유형 중에서 HTTP을 선택합니다.
다음 옵션에서 인증 유형 선택합니다.
- 전달자 토큰
- OAuth 기계 간
- OAuth 사용자를 컴퓨터 공유
인증 페이지에서 HTTP 연결에 대해 다음 연결 속성을 입력합니다.

전달자 토큰의 경우:
- 호스트: 예를 들어 https://databricks.com
- 포트: 예를 들어 443
- 전달자 토큰: 예를 들어 bearer-token
- 기본 경로: 예를 들어 /api/
OAuth Machine to Machine 토큰의 경우:
- 클라이언트 ID: 만든 애플리케이션에 대한 고유 식별자입니다.
- 클라이언트 비밀: 만든 애플리케이션에 대해 생성된 비밀 또는 암호입니다.
- OAuth 범위: 사용자 권한 부여 중에 부여할 범위입니다. 범위 매개 변수는 공백으로 구분된 대/소문자를 구분하는 문자열 목록으로 표현됩니다. 예를 들어 channels:read channels:history chat:write
- 토큰 엔드포인트: 클라이언트에서 권한 부여 또는 새로 고침 토큰을 제공하여 액세스 토큰을 가져오는 데 사용됩니다. 일반적으로 형식은 https://authorization-server.com/oauth/token
OAuth 사용자와 컴퓨터 간에 공유된 토큰:
- 클라이언트 ID: 만든 애플리케이션에 대한 고유 식별자입니다.
- 클라이언트 비밀: 만든 애플리케이션에 대해 생성된 비밀 또는 암호입니다.
- OAuth 범위: 사용자 권한 부여 중에 부여할 범위입니다. 범위 매개 변수는 공백으로 구분된 대/소문자를 구분하는 문자열 목록으로 표현됩니다. 예를 들어 channels:read channels:history chat:write
- 권한 부여 엔드포인트: 일반적으로 https://authorization-server.com/oauth/authorize 형식으로 사용자 에이전트 리디렉션을 통해 리소스 소유자와 인증하려면
- 토큰 엔드포인트: 클라이언트에서 권한 부여 또는 새로 고침 토큰을 제공하여 액세스 토큰을 가져오는 데 사용됩니다. 일반적으로 형식은 https://authorization-server.com/oauth/token
메모

OAuth 사용자-기계 공유를 위해, OAuth 자격 증명을 사용하여 HTTP를 통해 로그인하라는 메시지가 표시됩니다.
연결을 만들기 위해을 클릭합니다.

SQL

CREATE CONNECTION SQL 명령을 사용하여 연결을 만듭니다.

메모

SQL 명령으로 OAuth 머신 대 사용자 공유 를 사용하는 연결을 만들 수 없습니다. 대신 카탈로그 탐색기 UI 지침을 참조하세요.

전달자 토큰사용하여 새 연결을 만들려면 Notebook 또는 Databricks SQL 쿼리 편집기에서 다음 명령을 실행합니다.

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

Databricks는 자격 증명과 같은 중요한 값에 일반 텍스트 문자열 대신 비밀을 사용하는 것이 좋습니다. 예를 들어:

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

OAuth Machine에서 Machine사용하여 새 연결을 만들려면 Notebook 또는 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>'
)

외부 시스템에 HTTP 요청 보내기

이제 연결했으므로 http_request 기본 제공 SQL 함수를 사용하여 서비스에 HTTP 요청을 보내는 방법을 알아봅니다.

권한이 필요합니다. 연결 개체에 대한USE CONNECTION.

Notebook 또는 Databricks SQL 편집기에서 다음 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: 호스트, 포트, base_path 및 액세스 자격 증명을 지정하는 연결 개체.
http-method: 호출하는 데 사용되는 HTTP 요청 메서드입니다. 예: GET, POST, PUT, DELETE
path: 서비스 리소스를 호출할 base_path 후 연결할 경로입니다.
json: 요청과 함께 보낼 JSON 본문입니다.
headers: 요청 헤더를 지정하는 맵입니다.

Unity 카탈로그 함수 도구 만들기

연결이 제대로 작동하는지 유효성을 검사한 후 연결을 사용하는 Unity 카탈로그 함수를 만듭니다. 다음 예제에서는 에이전트가 Slack에 메시지를 게시하는 데 사용할 수 있는 Unity 카탈로그 함수 도구를 만듭니다.

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

에이전트 코드에서 도구 만들기

Python을 사용하여 외부 서비스에 HTTP 요청을 보내려면 라이브러리의 databricks-sdk 함수를 사용합니다. 이 함수는 인증을 위해 Unity 카탈로그 연결을 사용하여 외부 서비스에 HTTP 요청을 보냅니다.

권한이 필요합니다. 연결 개체에 대한USE CONNECTION.

다음 예제에서는 에이전트 코드 내부에서 외부 HTTP 요청을 수행합니다.

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: 호스트, 포트, base_path 및 액세스 자격 증명을 지정하는 연결 개체입니다.
method: 호출하는 데 사용되는 HTTP 요청 메서드입니다. 예: GET, POST, PUT, DELETE
path: 서비스 리소스를 호출할 base_path 후 연결할 경로입니다.
json: 요청과 함께 보낼 JSON 본문입니다.
headers: 요청 헤더를 지정하는 맵입니다.

예제 Notebook

다음 Notebook에서는 Slack, OpenAI 및 Azure AI 검색에 연결하는 AI 에이전트 도구를 만드는 방법을 보여 줍니다.

다음을 통해 공유

외부 서비스에 AI 에이전트 도구 연결

요구 사항

외부 서비스에 대한 인증 방법

외부 서비스에 대한 연결 만들기

카탈로그 탐색기

SQL

외부 시스템에 HTTP 요청 보내기

Unity 카탈로그 함수 도구 만들기

에이전트 코드에서 도구 만들기

예제 Notebook

Slack 메시징 에이전트 도구

Microsoft Graph API 에이전트 도구

Azure AI Search 에이전트 도구

피드백

추가 리소스