AI 에이전트에 대한 인증

AI 에이전트는 작업을 완료하기 위해 다른 리소스에 인증해야 하는 경우가 많습니다. 예를 들어 배포된 에이전트는 구조화되지 않은 데이터를 쿼리하기 위해 Vector Search 인덱스에 액세스하거나 프롬프트 레지스트리를 사용하여 동적 프롬프트를 로드해야 할 수 있습니다.

이 페이지에서는 Mosaic AI 에이전트 프레임워크를 사용하여 에이전트를 개발하고 배포할 때 사용할 수 있는 인증 방법을 설명합니다.

인증 방법

다음 표에서는 사용 가능한 인증 방법을 비교합니다. 다음 방법 중 하나라도 혼합하고 일치시킬 수 있습니다.

외부 시스템 및 MCP 서버에 인증

에이전트에서 외부 API 및 MCP 서버에 인증하는 방법에 대한 지침은 AI 에이전트 도구를 외부 서비스에 연결하세요. 인증 방법에 설명된 대로 에이전트 또는 사용자를 대신하여 이러한 리소스를 쿼리할 수도 있습니다.

리소스에 적합한 인증 방법 선택

이 순서도를 사용하여 각 리소스에 적합한 인증 방법을 선택합니다. 필요에 따라 메서드를 결합할 수 있으며 에이전트는 사용 사례에 따라 각 리소스에 대해 다른 메서드를 사용할 수 있습니다.

1. 사용자별 액세스 제어 또는 사용자 특성 감사가 필요한가요?

   • 예 → 사용자 대리 인증 사용
   • → 2단계로 계속하지 않음

2. 모든 리소스가 자동 인증을 지원합니까?

   • 예 → 자동 인증 통과 사용(권장)
   • 수동 인증을 사용할 → 없음

자동 인증 통과

자동 인증 통과는 Databricks 관리 리소스에 액세스하는 가장 간단한 방법입니다. 에이전트를 로깅할 때 리소스 종속성을 선언하고, Databricks는 에이전트가 배포될 때 수명이 짧은 자격 증명을 자동으로 프로비전, 회전 및 관리합니다.

이 인증 동작은 Databricks 대시보드의 "소유자 권한으로 실행" 동작과 유사합니다. Unity 카탈로그 테이블과 같은 다운스트림 리소스는 에이전트에 필요한 리소스에 대한 최소 권한 액세스 권한이 있는 서비스 주체의 자격 증명을 사용하여 액세스합니다.

자동 인증 통과의 작동 방식

자동 인증 통과를 사용하여 엔드포인트 뒤에서 에이전트를 제공하는 경우 Databricks는 다음 단계를 수행합니다.

1. 권한 확인: Databricks는 엔드포인트 작성자가 에이전트 로깅 중에 지정된 모든 종속성에 액세스할 수 있음을 확인합니다.

2. 서비스 주체 만들기 및부여: 에이전트 모델 버전에 대한 서비스 주체가 생성되고 에이전트 리소스에 대한 읽기 권한이 자동으로 부여됩니다.

   비고

   시스템 생성 서비스 주체는 API 또는 UI 목록에 표시되지 않습니다. 에이전트 모델 버전이 엔드포인트에서 제거되면 서비스 주체도 삭제됩니다.

3. 자격 증명 프로비전 및 회전: 서비스 주체에 대한 수명이 짧은 자격 증명(M2M OAuth 토큰)이 엔드포인트에 삽입되어 에이전트 코드가 Databricks 리소스에 액세스할 수 있도록 합니다. 또한 Databricks는 자격 증명을 회전하여 에이전트가 종속 리소스에 계속 안전하게 액세스할 수 있도록 합니다.

자동 인증 통과에 지원되는 리소스

다음 표에서는 자동 인증 통과를 지원하는 Databricks 리소스와 에이전트를 배포할 때 엔드포인트 작성자가 가져야 하는 사용 권한을 나열합니다.

자동 인증 통과 구현

자동 인증 통과를 사용하도록 설정하려면 에이전트를 기록할 때 종속 리소스를 지정합니다. resources API의 log_model() 매개 변수를 사용합니다.

import mlflow
from mlflow.models.resources import (
  DatabricksVectorSearchIndex,
  DatabricksServingEndpoint,
  DatabricksSQLWarehouse,
  DatabricksFunction,
  DatabricksGenieSpace,
  DatabricksTable,
  DatabricksUCConnection,
  DatabricksApp,
  DatabricksLakebase
)

with mlflow.start_run():
  logged_agent_info = mlflow.pyfunc.log_model(
    python_model="agent.py",
    artifact_path="agent",
    input_example=input_example,
    example_no_conversion=True,
    # Specify resources for automatic authentication passthrough
    resources=[
      DatabricksVectorSearchIndex(index_name="prod.agents.databricks_docs_index"),
      DatabricksServingEndpoint(endpoint_name="databricks-meta-llama-3-3-70b-instruct"),
      DatabricksServingEndpoint(endpoint_name="databricks-bge-large-en"),
      DatabricksSQLWarehouse(warehouse_id="your_warehouse_id"),
      DatabricksFunction(function_name="ml.tools.python_exec"),
      DatabricksGenieSpace(genie_space_id="your_genie_space_id"),
      DatabricksTable(table_name="your_table_name"),
      DatabricksUCConnection(connection_name="your_connection_name"),
      DatabricksApp(app_name="app_name"),
      DatabricksLakebase(database_instance_name="lakebase_instance_name"),
    ]
  )

사용자 대리 인증

OBO(사용자 대신) 인증을 사용하면 에이전트가 쿼리를 실행하는 Databricks 사용자 역할을 할 수 있습니다. 다음을 제공합니다.

• 중요한 데이터에 대한 사용자별 액세스
• Unity 카탈로그에 의해 적용되는 세분화된 데이터 컨트롤
• 보안 토큰은 에이전트가 선언하는 API로만 제한("다운스코프")되어 오용 위험을 줄입니다.

요구 사항

• 사용자를 대신하여 인증하려면 MLflow 2.22.1 이상이 필요합니다.
• 사용자 대신 인증은 기본적으로 사용하지 않도록 설정되며 작업 영역 관리자가 사용하도록 설정해야 합니다. 이 기능을 사용하도록 설정하기 전에 보안 고려 사항을 검토합니다 .

OBO 지원 리소스

OBO 인증을 사용하는 에이전트는 다음 Databricks 리소스에 액세스할 수 있습니다.

OBO 인증 구현

사용자 대신 인증을 사용하도록 설정하려면 다음 단계를 완료합니다.

1. 최종 사용자를 대신하여 리소스에 액세스하도록 지정하도록 SDK 호출을 업데이트합니다.
2. 사용자 ID는 런타임에만 알려지므로 에이전트 코드를 업데이트하여 함수가 아닌 predict함수 내에서 __init__ OBO 액세스를 초기화합니다.
3. 배포를 위해 에이전트를 로깅할 때 에이전트에 필요한 Databricks REST API 범위를 선언합니다.

다음 코드 조각에서는 다른 Databricks 리소스에 대한 사용자 대신 액세스를 구성하는 방법을 보여 줍니다. 도구를 초기화할 때 초기화 과정을 try-except 블록으로 래핑하여 권한 오류를 우아하게 처리합니다.

벡터 검색기 도구

from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_langchain import VectorSearchRetrieverTool

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy = ModelServingUserCredentials())

vector_search_tools = []
# Exclude exception handling if the agent should fail
# when users lack access to all required Databricks resources
try:
  tool = VectorSearchRetrieverTool(
    index_name="<index_name>",
    description="...",
    tool_name="...",
    workspace_client=user_client # Specify the user authorized client
    )
    vector_search_tools.append(tool)
except Exception as e:
    _logger.debug("Skipping adding tool as user does not have permissions")

Vector Search 클라이언트

from databricks.vector_search.client import VectorSearchClient
from databricks.vector_search.utils import CredentialStrategy

# Configure a VectorSearch Client to use on behalf of end
# user authentication
user_authenticated_vsc = VectorSearchClient(credential_strategy=CredentialStrategy.MODEL_SERVING_USER_CREDENTIALS)
# Exclude exception handling if the agent should fail when
# users lack access to all required Databricks resources
try:
  vs_index = user_authenticated_vsc.get_index(endpoint_name="endpoint_name", index_name="index_name")
  ...
except Exception as e:
  _logger.debug("Skipping Vector Index because user does not have permissions")

MCP

from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_mcp import DatabricksMCPClient

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

mcp_client = DatabricksMCPClient(
    server_url="<mcp_server_url>",
    workspace_client=user_client, # Specify the user client here
  )

엔드포인트를 제공하는 모델

from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

# Exclude exception handling if the agent should fail
# when users lack access to all required Databricks resources
try:
  user_client.serving_endpoints.query("endpoint_name", input="")
except Exception as e:
  _logger.debug("Skipping Model Serving Endpoint due to no permissions")

UC 연결

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

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

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

지니 공간(WorkspaceClient)

from databricks_langchain.genie import GenieAgent
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials


# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())


genie_agent = GenieAgent(
    genie_space_id="space-id",
    genie_agent_name="Genie",
    description="This Genie space has access to sales data in Europe"
    client=user_client
)

# Use the Genie SDK methods available through WorkspaceClient
try:
    response = agent.invoke("Your query here")
except Exception as e:
    _logger.debug("Skipping Genie due to no permissions")

지니 공간(랭체인)

from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_langchain.genie import GenieAgent

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

genie_agent = GenieAgent(
    genie_space_id="<genie_space_id>",
    genie_agent_name="Genie",
    description="Genie_description",
    client=user_client, # Specify the user client here
  )

예측 함수에서 에이전트 초기화

사용자의 ID는 쿼리 시간에만 알려지므로 에이전트 predict 의 메서드가 아닌 내부 또는 predict_stream내부 __init__ OBO 리소스에 액세스해야 합니다. 이렇게 하면 리소스가 호출 간에 격리됩니다.

from mlflow.pyfunc import ResponsesAgent

class OBOResponsesAgent(ResponsesAgent):
  def initialize_agent():
    user_client = WorkspaceClient(
      credentials_strategy=ModelServingUserCredentials()
    )
    system_authorized_client = WorkspaceClient()
    ### Use the clients above to access resources with either system or user authentication

  def predict(
    self, request
  ) -> ResponsesAgentResponse:
    agent = initialize_agent() # Initialize the Agent in Predict

    agent.predict(request)
    ...

에이전트를 로깅할 때 REST API 범위 선언

배포를 위해 OBO 에이전트를 기록할 때 에이전트가 사용자를 대신하여 호출하는 Databricks REST API 범위를 나열해야 합니다. 이렇게 하면 에이전트가 최소 권한 원칙을 따릅니다. 토큰은 에이전트에 필요한 API로만 제한되어 무단 작업 또는 토큰 오용 가능성이 줄어듭니다.

다음은 몇 가지 일반적인 유형의 Databricks 리소스에 액세스하는 데 필요한 범위 목록입니다.

사용자 대신 인증을 사용하도록 설정하려면 MLflow AuthPolicy 를 다음으로 전달합니다 log_model().

import mlflow
from mlflow.models.auth_policy import AuthPolicy, SystemAuthPolicy, UserAuthPolicy
from mlflow.models.resources import DatabricksServingEndpoint

# System policy: resources accessed with system credentials
system_policy = SystemAuthPolicy(
    resources=[DatabricksServingEndpoint(endpoint_name="my_endpoint")]
)

# User policy: API scopes for OBO access
user_policy = UserAuthPolicy(api_scopes=[
    "serving.serving-endpoints",
    "vectorsearch.vector-search-endpoints",
    "vectorsearch.vector-search-indexes"
])

# Log the agent with both policies
with mlflow.start_run():
    mlflow.pyfunc.log_model(
        name="agent",
        python_model="agent.py",
        auth_policy=AuthPolicy(
            system_auth_policy=system_policy,
            user_auth_policy=user_policy
        )
    )

OpenAI 클라이언트에 대한 OBO 인증

OpenAI 클라이언트를 사용하는 에이전트의 경우 Databricks SDK를 사용하여 배포 중에 자동으로 인증합니다. Databricks SDK에는 인증이 자동으로 구성된 OpenAI 클라이언트를 생성하기 위한 래퍼가 get_open_ai_client()있습니다.

% pip install databricks-sdk[openai]

from databricks.sdk import WorkspaceClient
def openai_client(self):
  w = WorkspaceClient()
  return w.serving_endpoints.get_open_ai_client()

그런 다음 배포 시 자동으로 인증할 resources 일부로 모델 서비스 엔드포인트를 지정합니다.

OBO 보안 고려 사항

에이전트에서 사용자 대신 인증을 사용하도록 설정하기 전에 다음 보안 고려 사항을 고려합니다.

확장된 리소스 액세스: 에이전트는 사용자를 대신하여 중요한 리소스에 액세스할 수 있습니다. 범위는 API를 제한하지만 엔드포인트는 에이전트가 명시적으로 요청하는 것보다 더 많은 작업을 허용할 수 있습니다. 예를 들어 API 범위는 serving.serving-endpoints 사용자를 대신하여 서비스 엔드포인트를 실행할 수 있는 에이전트 권한을 부여합니다. 그러나 서비스 엔드포인트는 원래 에이전트에서 사용할 수 있는 권한이 없는 추가 API 범위에 액세스할 수 있습니다.

OBO 예제 노트북

다음 노트북에서는 사용자 대신 권한 부여를 사용하여 Vector Search를 통해 에이전트를 만드는 방법을 보여줍니다.

벡터 검색을 사용하여 사용자 권한 부여 대신

노트북 받기

다음 Notebook에서는 사용자 대신 권한 부여를 사용하여 SQL Warehouse에서 SQL 실행을 지원하는 에이전트를 만드는 방법을 보여 줍니다. 이렇게 하면 에이전트가 사용자 자격 증명을 사용하여 Unity 카탈로그 함수를 안전하게 호출할 수 있습니다. 참고: OBO를 사용한 서버리스 Spark 실행은 아직 지원되지 않으므로 OBO를 사용하여 UC Functions를 실행하는 것이 좋습니다.

SQL 실행을 사용하여 사용자 권한 부여 대신

노트북 받기

수동 인증

수동 인증을 사용하면 에이전트 배포 중에 자격 증명을 명시적으로 지정할 수 있습니다. 이 메서드는 유연성이 가장 뛰어나지만 더 많은 설정과 지속적인 자격 증명 관리가 필요합니다. 다음 경우에 이 메서드를 사용합니다.

• 종속 리소스는 자동 인증 통과를 지원하지 않습니다.
• 에이전트는 에이전트 배포자 이외의 자격 증명을 사용해야 합니다.
• 에이전트는 Databricks 외부의 외부 리소스 또는 API에 액세스합니다.
• 배포된 에이전트가 프롬프트 레지스트리에 액세스합니다.

OAuth 인증(권장)

OAuth는 자동 토큰 새로 고침 기능을 사용하는 서비스 주체에 대한 안전한 토큰 기반 인증을 가지고 있으므로 수동 인증에 권장되는 방법입니다.

1. 서비스 주체를 만들고OAuth 자격 증명을 생성합니다.

2. 에이전트가 액세스할 수 있는 모든 Databricks 리소스에 대해 서비스 주체에 권한을 부여합니다. 프롬프트 레지스트리에 액세스하려면 프롬프트를 저장하기 위해 Unity 카탈로그 스키마에 CREATE FUNCTION, EXECUTE, 및 MANAGE 권한을 부여합니다.

3. OAuth 자격 증명에 대한 Databricks 시크릿을 생성하십시오.

4. 에이전트 코드에서 OAuth 자격 증명을 구성합니다.

   import os
   
   # Configure OAuth authentication for Prompt Registry access
   # Replace with actual secret scope and key names
   secret_scope_name = "your-secret-scope"
   client_id_key = "oauth-client-id"
   client_secret_key = "oauth-client-secret"
   
   os.environ["DATABRICKS_HOST"] = "https://<your-workspace-url>"
   os.environ["DATABRICKS_CLIENT_ID"] = dbutils.secrets.get(scope=secret_scope_name, key=client_id_key)
   os.environ["DATABRICKS_CLIENT_SECRET"] = dbutils.secrets.get(scope=secret_scope_name, key=client_secret_key)
   

5. 비밀 키를 사용하여 작업 공간에 연결하세요.

   w = WorkspaceClient(
     host=os.environ["DATABRICKS_HOST"],
     client_id=os.environ["DATABRICKS_CLIENT_ID"],
     client_secret = os.environ["DATABRICKS_CLIENT_SECRET"]
   )
   

6. 배포할 agents.deploy()때 OAuth 자격 증명을 환경 변수로 포함합니다.

   agents.deploy(
       UC_MODEL_NAME,
       uc_registered_model_info.version,
       environment_vars={
           "DATABRICKS_HOST": "https://<your-workspace-url>",
           "DATABRICKS_CLIENT_ID": f"{{{{secrets/{secret_scope_name}/{client_id_key}}}}}",
           "DATABRICKS_CLIENT_SECRET": f"{{{{secrets/{secret_scope_name}/{client_secret_key}}}}}"
       },
   )
   

PAT 인증

PAT(개인용 액세스 토큰) 인증은 더 많은 수동 자격 증명 관리가 필요하지만 개발 및 테스트 환경을 보다 간단하게 설정할 수 있습니다.

1. 서비스 주체 또는 개인 계정을 이용하여 PAT를 얻는 방법.

   서비스 주체(보안에 권장):

   1. 서비스 주체만듭니다.
   2. 에이전트가 액세스할 수 있는 모든 Databricks 리소스에 대해 서비스 주체에 권한을 부여합니다. Unity 카탈로그 스키마에서 프롬프트를 저장하는 데 사용되는 [매개변수]에 액세스하려면 CREATE FUNCTION, EXECUTE, MANAGE에 대한 권한을 부여합니다.
   3. 서비스 주체에 대한 PAT를 만듭니다.

   개인 계정:

   1. 개인 계정에 대한 PAT를 만듭니다.

2. PAT에 대한 Databricks 비밀을 만들어 PAT를 안전하게 저장합니다.

3. 에이전트 코드에서 PAT 인증을 구성합니다.

   import os
   
   # Configure PAT authentication for Prompt Registry access
   # Replace with your actual secret scope and key names
   secret_scope_name = "your-secret-scope"
   secret_key_name = "your-pat-key"
   
   os.environ["DATABRICKS_HOST"] = "https://<your-workspace-url>"
   os.environ["DATABRICKS_TOKEN"] = dbutils.secrets.get(scope=secret_scope_name, key=secret_key_name)
   
   # Validate configuration
   assert os.environ["DATABRICKS_HOST"], "DATABRICKS_HOST must be set"
   assert os.environ["DATABRICKS_TOKEN"], "DATABRICKS_TOKEN must be set"
   

4. 에이전트를 사용하여 agents.deploy()배포할 때 PAT를 환경 변수로 포함합니다.

   agents.deploy(
       UC_MODEL_NAME,
       uc_registered_model_info.version,
       environment_vars={
           "DATABRICKS_HOST": "https://<your-workspace-url>",
           "DATABRICKS_TOKEN": f"{{{{secrets/{secret_scope_name}/{secret_key_name}}}}}"
       },
   )