감독자 API(베타)를 사용하여 사용자 지정 에이전트 빌드

Important

이 기능은 베타 버전으로 제공됩니다. 계정 관리자는 미리 보기 페이지에서 이 기능에 대한 액세스를 제어할 수 있습니다. Azure Databricks 미리 보기 관리를 참조하세요.

사용자 고유의 코드에서 에이전트 루프를 관리하는 대신 오케스트레이션에 오케스트레이터 API(베타)를 사용하는 Azure Databricks Apps 에이전트를 빌드할 수 있습니다. 결과는 채팅 UI, 엔드포인트 및 인증을 사용하여 배포된 앱인 사용자 지정 에이전트를 /invocations 작성하는 것과 동일합니다. 차이점은 Azure Databricks가 에이전트 루프를 대신 실행해 준다는 점입니다. agent.py 단일 API 호출을 수행하고 Azure Databricks 도구 선택, 실행 및 응답 합성을 처리합니다.

감독자 API는 지원되는 모든 기본 모델에서 작동합니다. model 도구 정의 또는 처리기 논리를 건드리지 않고 공급자를 전환하도록 필드를 변경합니다.

감독자 API를 사용하는 경우

에이전트가 Azure Databricks 호스팅된 도구만 사용하고 도구 호출 간에 사용자 지정 논리가 필요하지 않은 경우 감독자 API가 잘 작동합니다. 에이전트에 다음 중 하나가 필요하면 사용자 지정 에이전트 루프를 대신 사용합니다.

  • 클라이언트 쪽 함수 도구(감독자 API는 호스트된 도구와 클라이언트 쪽 도구를 한 번의 요청으로 혼합할 수 없음)
  • 에이전트 Bricks Knowledge Assistant 엔드포인트 이외의 에이전트 엔드포인트
  • 사용자 지정 검색기, 사용자 지정 입력/출력 또는 세분화된 스트리밍 컨트롤
  • 조건부 분기 또는 상태 관리와 같은 도구 호출 간의 사용자 지정 Python 논리
  • 다음과 같은 유추 매개 변수 제어 temperature

전체 API 참조 및 지원되는 매개 변수는 감독자 API(베타)를 참조하세요.

Requirements

감독자 API를 사용하여 사용자 지정 에이전트 빌드

권장되는 시작점은 최신 Databricks 앱 템플릿에서 새 앱을 만드는 것입니다. 최신 템플릿에는 AI 코딩 도우미를 위한 기본 제공 use-supervisor-api 기술과 호스트된 add-tools 도구를 추가하는 기술이 포함됩니다.

템플릿에서 새 앱을 만들려면 AI 에이전트 작성 및 Databricks 앱에 배포를 참조하세요.

앱이 최신 템플릿에서 설정되면 AI 코딩 도우미에서 프로젝트를 열고 다음을 실행합니다.

Use the Supervisor API skill to update this agent to use the Databricks Supervisor API.

기술은 수동 에이전트 루프를 대체하기 위해 호스트된 도구로 agent_server/agent.py을(를) 호출하도록 DatabricksOpenAI().responses.create()을(를) 업데이트합니다. 또한 종속성을 추가하고 databricks-openai 베타 제한 사항을 적어 줍니다.

동일한 채팅 UI, 인증, /invocations 엔드포인트가 포함된 배포된 앱이지만 더 간단한 에이전트 코드를 갖춘 결과입니다. 전체 배포 워크플로(앱에 배포, 도구 추가, 평가)는 AI 에이전트 작성 및 Databricks 앱에 배포를 참조하세요.

지원되는 도구 및 매개 변수

지원되는 도구 유형, 요청 매개 변수 및 코드 예제의 전체 목록은 감독자 API(베타)를 참조하세요.

추가하는 각 도구에 대해 해당 리소스 사용 권한도 부여합니다 databricks.yml. 예제에 대한 add-tools 기술을 .claude/skills/에서 보세요.

호스팅된 도구에 대한 권한 부여

감독자 API는 에이전트 루프를 실행하면 앱의 ID 또는 요청 중인 사용자의 ID를 사용하여 호스트된 도구를 실행합니다. 앱의 모든 사용자가 도구에 대해 동일한 액세스를 공유해야 하는지, 아니면 각 사용자가 자신의 사용 권한이 허용하는 것에만 액세스해야 하는지에 따라 선택합니다.

  • 앱 권한 부여 (기본값): 도구는 앱의 서비스 주체로 실행됩니다. 에이전트에서 사용하는 각 도구에 대한 서비스 주체 권한을 부여합니다. 앱 권한 부여를 참조하세요.
  • 사용자 권한 부여: 도구를 요청을 보낸 사용자로 실행되므로 Unity 카탈로그 권한, 행 필터 및 열 마스크가 사용자별로 적용됩니다. 다음 섹션을 참조하세요.

요청하는 사용자로 도구 실행

Important

사용자 권한 부여는 공개 미리 보기로 제공됩니다. 앱에 범위를 추가하려면 먼저 작업 영역 관리자가 사용하도록 설정해야 합니다. 앱에 범위 추가를 참조하세요.

요청 중인 사용자를 대신하여 호스트된 도구를 실행하려면 사용자의 토큰을 클라이언트에 DatabricksOpenAI 전달하고 도구에 필요한 사용자 권한 부여 범위를 추가합니다.

  1. 앱에 필요한 사용자 권한 부여 범위를 추가합니다. ai-gateway 는 모든 감독자 API 액세스에 필요합니다. 에이전트에서 사용하는 각 도구 유형에 대한 도구별 범위를 추가합니다.

    도구 유형 필수 범위
    모든 도구 ai-gateway
    genie_space genie
    uc_function mcp.functions
    knowledge_assistant model-serving
    uc_connection catalog.connections

    app 도구 유형은 사용자 권한 부여에서 지원되지 않습니다. 앱 엔드포인트를 도구로 호출하려면 대신 앱 권한 부여를 사용합니다. 작업 영역 UI 또는 선언적 자동화 번들을 통해 범위를 추가하는 방법은 사용자 권한 부여를 참조하세요.

  2. agent.py 처리기에서 사용자 워크스페이스 클라이언트를 DatabricksOpenAI에 전달합니다. 이것이 유일한 감독자별 배선입니다. 사용자 클라이언트를 사용하여 리소스를 직접 호출하는 대신 에이전트 루프를 실행하는 클라이언트에 전달합니다.

    from databricks_openai import DatabricksOpenAI
from agent_server.utils import get_user_workspace_client

# Inside your invoke or stream handler, not at app startup
client = DatabricksOpenAI(
  workspace_client=get_user_workspace_client(),
  use_ai_gateway=True,
)

    get_user_workspace_client() 는 쿼리 시간에만 채워진 요청 헤더에서 전달된 사용자 토큰을 읽습니다. invoke 및 stream 핸들러 내부에서 호출하고, __init__ 또는 앱 시작 시에는 절대 호출하지 마세요. 전달된 토큰이 누락된 경우 결과 클라이언트는 요청 사용자로 인증되지 않습니다. 에이전트가 앱의 서비스 주체가 아닌 호출자로 실행되는지 확인하는 방법은 사용자 권한 부여를 참조하세요.

  3. 에이전트를 실행하는 각 사용자에게 각 도구에 대해 필요한 권한(예: Genie Space의 CAN_RUN 또는 지식 도우미 엔드포인트의 CAN_QUERY)을 부여하세요.

추가 리소스

  • Last updated on