감독자 API(베타)

중요합니다

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

감독자 API는 Azure Databricks에서 사용자 지정 에이전트를 빌드하는 작업을 간소화하고, 장기 실행 작업을 위해 백그라운드 모드를 지원합니다. OpenResponses 호환 엔드포인트(POST /mlflow/v1/responses)에 대한 한 요청에서 모델, 도구 및 지침을 정의하고, Azure Databricks 모델 호출, 도구 선택 및 실행, 최종 응답 합성 등 에이전트 루프를 실행합니다.

Azure Databricks 사용자 지정된 도구 호출 에이전트를 빌드하는 세 가지 방법이 있습니다.

에이전트 브릭스 관리자 에이전트 (권장): 인간 피드백 최적화를 통한 완전히 선언형입니다.
감독자 API: 프로그래밍 방식으로 사용자 지정 에이전트를 빌드합니다. 런타임에 모델을 선택하거나, 요청당 사용할 도구를 제어하거나, 개발 중에 반복합니다. 또한 Azure Databricks 위해 에이전트 루프 관리를 오프로드하는 동안 모델 선택에 대한 제어가 필요한 경우 적합한 선택입니다.
AI Gateway 통합 또는 네이티브 API: 사용자 고유의 에이전트 루프를 작성합니다. Azure Databricks LLM 유추 계층만 제공합니다. 기존 코드를 Azure Databricks 포팅하거나 공급자별 기능을 사용할 때 가능한 경우 통합 API를 사용하여 모델을 전환하거나 공급자별 네이티브 API(/openai, /anthropic, /gemini)를 사용하도록 설정합니다.

Requirements

계정에 사용하도록 설정된 Unity AI 게이트웨이는 에이전트 및 LLM을 위한 것입니다. Azure Databricks 미리 보기 관리를 참조하세요.
- 감독자 API는 Unity AI 게이트웨이를 통해 실행되므로 유추 테이블, 속도 제한 및 대체와 같은 AI 게이트웨이 기능이 적용됩니다. 이 베타에서는 사용량 추적이 지원되지 않습니다.
계정에서 Unity 카탈로그에 OpenTelemetry 추적을 저장하는 기능이 활성화되었습니다. Azure Databricks 미리 보기 관리를 참조하세요.
- Unity 카탈로그 테이블에 감독자 API 에이전트 루프의 추적을 저장합니다.
Azure Databricks 작업 영역은 지원되는 지역에 있습니다.
작업 영역에서 Unity 카탈로그가 사용하도록 설정되었습니다. Unity 카탈로그에 작업 영역 사용을 참조하세요.
전달하는 도구(Genie Spaces, Unity 카탈로그 함수, MCP 서버, 기술 도우미, 앱)는 이미 구성되고 액세스할 수 있어야 합니다.
databricks-openai 설치된 패키지:pip install databricks-openai

1단계: 단일 턴 LLM 호출 만들기

도구 없이 기본 호출로 시작합니다. 클라이언트는 DatabricksOpenAI 작업 영역에 대한 기본 URL 및 인증을 자동으로 구성합니다.

from databricks_openai import DatabricksOpenAI

client = DatabricksOpenAI(use_ai_gateway=True)

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  stream=False
)

print(response.output_text)

2단계: 호스트된 도구를 추가하여 에이전트 루프 실행

요청에 도구를 포함하면 Azure Databricks 사용자를 대신하여 멀티 턴 루프를 관리합니다. 모델은 호출할 도구를 결정하고, 실행할 Azure Databricks, 결과를 모델에 다시 공급하고, 모델이 최종 답변을 생성할 때까지 반복합니다.

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Summarize recent customer reviews and flag any urgent issues."}],
  tools=[
    {
      "type": "genie_space",
      "genie_space": {
        "id": "<genie-space-id>",
        "description": "Answers customer review questions using SQL"
      }
    },
    {
      "type": "uc_function",
      "uc_function": {
        "name": "<catalog>.<schema>.<function_name>",
        "description": "Flags a review as requiring urgent attention"
      }
    },
    {
      "type": "knowledge_assistant",
      "knowledge_assistant": {
        "knowledge_assistant_id": "<knowledge-assistant-id>",
        "description": "Answers questions from internal documentation"
      }
    },
    {
      "type": "app",
      "app": {
        "name": "<app-name>",
        "description": "Custom application endpoint"
      }
    },
    {
      "type": "uc_connection",
      "uc_connection": {
        "name": "<uc-connection-name>",
        "description": "Searches the web for current information"
      }
    },
  ],
  stream=True
)

for event in response:
  print(event)

3단계(선택 사항): 시스템 관리형 연결을 사용하여 타사 서비스에 연결

Azure Databricks Google Drive, GitHub, Atlassian 및 SharePoint 같은 인기 있는 타사 서비스에 대한 시스템 관리형 연결을 제공합니다. 직접 외부 MCP 서버를 설정하는 대신 이러한 연결을 사용할 수 있습니다. 하지만 도구 유형을 사용하면 직접 구성한 외부 MCP 서버에 여전히 연결할 수 있습니다.

시스템 관리형 연결을 사용하려면 작업 영역에서 에이전트 베타용 타사 커넥터 를 사용하도록 설정해야 합니다. Azure Databricks 미리 보기 관리를 참조하세요.

지원되는 커넥터는 다음과 같습니다.

커넥터	설명
`system_ai_agent_google_drive`	Google Drive에서 파일을 검색하고 읽습니다.
`system_ai_agent_github_mcp`	GitHub 리포지토리, 문제 및 끌어오기 요청에 액세스합니다.
`system_ai_agent_atlassian_mcp`	Atlassian 리소스(Jira, Confluence)를 검색하고 관리합니다.
`system_ai_agent_sharepoint`	SharePoint 파일을 검색하고 읽습니다.

tools 배열의 커넥터를 uc_connection 도구 유형으로 전달하며, 해당 도구의 name 필드는 커넥터 이름으로 설정되어 있습니다.

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "List my open GitHub pull requests."}],
  tools=[
    {
      "type": "uc_connection",
      "uc_connection": {
        "name": "system_ai_agent_github_mcp"
      }
    }
  ],
)

U2M(사용자-컴퓨터) 인증

각 사용자는 개별적으로 인증합니다. OAuth 토큰은 사용자 간에 공유되지 않습니다. 사용자가 인증하지 않은 커넥터를 사용하는 첫 번째 요청에서 응답이 완료되고 status: "failed" 로그인 URL이 포함된 오류가 발생합니다oauth.

{
  "status": "failed",
  "error": {
    "code": "oauth",
    "message": "Failed request to <connector>. Please login first at <login-url>."
  }
}

브라우저에서 URL을 열고 OAuth 흐름을 완료한 다음 동일한 요청을 다시 실행합니다.

4단계: 추적 사용

trace_destination 요청 본문에 전달하여 에이전트 루프에서 Unity 카탈로그 테이블로 추적을 보냅니다. 각 요청은 모델 호출 및 도구 실행의 전체 시퀀스를 캡처하는 추적을 생성합니다. trace_destination을(를) 설정하지 않으면 추적이 기록되지 않습니다. 설치 세부 정보는 Unity 카탈로그에서 OpenTelemetry 추적 저장을 참조하세요.

databricks-openai Python 클라이언트를 사용하여 extra_body 통해 전달합니다.

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  tools=[...],
  extra_body={
    "trace_destination": {
      "catalog_name": "<catalog>",
      "schema_name": "<schema>",
      "table_prefix": "<table-prefix>"
    }
  }
)

API 응답에서 추적을 직접 반환하려면 "databricks_options": {"return_trace": True}를 extra_body에 전달하세요.

MLflow 분산 추적을 사용하여 애플리케이션 코드 및 감독자 API 에이전트 루프의 추적을 단일 엔드투엔드 추적으로 결합할 수도 있습니다. 추적 컨텍스트 헤더를 extra_headers 필드를 사용하여 전파합니다.

import mlflow
from mlflow.tracing import get_tracing_context_headers_for_http_request

with mlflow.start_span("client-root") as root_span:
  root_span.set_inputs({"input": "Tell me about Databricks"})

  trace_headers = get_tracing_context_headers_for_http_request()

  response = client.responses.create(
    model="databricks-claude-sonnet-4-5",
    input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
    tools=[...],
    extra_body={
      "trace_destination": {
        "catalog_name": "<catalog>",
        "schema_name": "<schema>",
        "table_prefix": "<table-prefix>"
      }
    },
    extra_headers=trace_headers,
  )

백그라운드 모드

백그라운드 모드를 사용하면 여러 도구 호출과 복잡한 추론이 포함된 장기 실행 에이전트 워크플로를 동기적으로 완료할 때까지 기다리지 않고 실행할 수 있습니다. 요청을 background=True와 함께 제출하면 응답 ID를 즉시 받고, 준비가 되었을 때 결과를 조회합니다. 이는 여러 데이터 원본을 쿼리하거나 여러 도구를 단일 요청으로 연결하는 에이전트에 특히 유용합니다.

백그라운드 요청 만들기

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  tools=[...],
  background=True,
)

print(response.id)     # Use this ID to poll for the result
print(response.status) # "queued" or "in_progress"

결과 확인을 위한 폴링

터미널 상태에 도달할 때까지 상태를 확인하는 데 사용합니다 responses.retrieve() .

from time import sleep

while response.status in {"queued", "in_progress"}:
  sleep(2)
  response = client.responses.retrieve(response.id)

print(response.output_text)

MCP를 사용하여 백그라운드 모드

보안을 위해 감독자 API는 백그라운드 모드에서 MCP 도구 호출을 실행하기 전에 명시적 사용자 승인이 필요합니다. 에이전트 루프가 MCP 도구를 선택하면 응답이 완료됩니다 mcp_approval_request. 모델에서 전달하려는 도구 이름, 서버 레이블 및 인수를 검토할 수 있습니다.

{
  "type": "mcp_approval_request",
  "id": "<tool-call-id>",
  "arguments": "{\"query\": \"what is Databricks\", \"count\": 5}",
  "name": "you-search",
  "server_label": "<server-label>",
  "status": "completed"
}

도구 호출을 승인하고 에이전트 루프를 계속하려면 전체 대화 기록과 함께 mcp_approval_response을 input 필드에 다시 전달하세요.

{
  "type": "mcp_approval_response",
  "id": "<tool-call-id>",
  "approval_request_id": "<tool-call-id>",
  "approve": true
}

메모

백그라운드 모드 응답은 최대 30일 동안 데이터베이스에 유지됩니다.

지원되는 도구

요청 배열에서 tools 도구를 정의합니다. 각 항목은 동일한 키를 가진 type 및 구성 개체를 지정합니다. 예를 들어, Genie Space 도구에는 "type": "genie_space" 및 "genie_space": {...} 개체가 있습니다. API는 다음 도구 유형을 지원합니다.

도구 유형	설명	Scope
`genie_space`	지니 공간을 쿼리하여 데이터에 대한 질문에 답변합니다. 매개 변수: `id`, `description`.	`genie`
`uc_function`	Unity 카탈로그 함수를 에이전트 도구로 호출합니다. 매개 변수: `name`, `description`.	`unity-catalog`
`uc_connection`	Unity 카탈로그 연결을 통해 외부 MCP 서버에 연결합니다. 매개 변수: `name`, `description`. Azure Databricks 관리되는 시스템 연결의 경우 `namesystem_ai_agent_*` 커넥터로 설정합니다(Ep 3(선택 사항): 시스템 관리형 연결을 사용하여 타사 서비스에 연결 참조). 참고: 앱의 사용자 지정 MCP 서버 는 아직 지원되지 않습니다.	`unity-catalog`
`app`	Azure Databricks 앱 엔드포인트를 호출합니다. 매개 변수: `name`, `description`.	`apps`
`knowledge_assistant`	지식 어시스턴트 엔드포인트를 호출합니다. 매개 변수: `knowledge_assistant_id`, `description`.	`model-serving`

지원되는 매개 변수

감독자 API에 대한 각 요청은 다음 매개 변수를 허용합니다.

model: 지원되는 다음 모델 중 하나입니다. 나머지 코드를 변경하지 않고 공급자를 전환하도록 이 필드를 변경합니다.
- 클로드 하이쿠-4.5 (databricks-claude-haiku-4-5)
- 클로드 오푸스-4.1 (databricks-claude-opus-4-1)
- 클로드 오푸스-4.5 (databricks-claude-opus-4-5)
- 클로드 오푸스-4.6 (databricks-claude-opus-4-6)
- 클로드 소네트-4 (databricks-claude-sonnet-4)
- 클로드 소넷-4.5 (databricks-claude-sonnet-4-5)
- 클로드 소넷-4.6 (databricks-claude-sonnet-4-6)

input: 보낼 대화 메시지입니다.
tools: 호스트된 도구 정의(genie_space, , uc_functionknowledge_assistant, appuc_connection).
instructions: 감독자의 동작을 안내하는 시스템 프롬프트입니다.
stream: 응답을 스트리밍하도록 true 설정합니다.
background: 요청을 비동기적으로 실행하도록 true 설정합니다. 응답 ID를 responses.retrieve()로 폴링하여 반환합니다. 배경 모드를 참조하세요.
trace_destination: , catalog_name및 schema_name 필드가 있는 table_prefix선택적 개체입니다. 설정되면 감독자 API는 전체 에이전트 루프의 추적을 지정된 Unity 카탈로그 테이블에 씁니다. Python 클라이언트에서 extra_body 통해 전달합니다.

API는 .와 같은 temperature유추 매개 변수를 지원하지 않습니다. 서버는 내부적으로 관리합니다.

제한점

감독자 API에는 다음과 같은 제한 사항이 있습니다.

백그라운드 모드 런타임: 백그라운드 모드 요청의 최대 실행 시간은 30분입니다.
클라이언트 쪽 함수 호출: 호스트된 도구만 지원됩니다. 클라이언트가 실행할 도구 정의를 전달할 function 수 없으며 호스트된 도구를 동일한 요청의 클라이언트 쪽 function 도구와 혼합할 수 없습니다.
백그라운드 모드에서 스트리밍: stream와 background 중 어느 하나도 동일한 요청에서 true 될 수 없습니다.
지속성 실행: 에이전트 루프에 대해 정확히 한 번 실행이 보장되는 오류 또는 중단으로부터의 자동 복구는 지원되지 않습니다.
Azure Databricks 앱 OBO는 지원되지 않습니다: 사용자 대신 권한 부여는 감독자 API에 대해 지원되지 않습니다. Azure Databricks 앱에서 감독자 API를 사용하려면 시스템 권한 부여를 사용하고 도구에 대한 권한을 부여합니다.

다음 단계

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-05-03