감독자 API(베타)

감독자 API는 Azure Databricks에서 사용자 지정 에이전트를 빌드하는 작업을 간소화하고, 장기 실행 작업을 위해 백그라운드 모드를 지원합니다. OpenResponses 호환 엔드포인트(POST ai-gateway/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 Gateway를 사용하는 AI 거버넌스가 활성화되었습니다. 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",
      "name": "Customer reviews",
      "description": "Answers customer review questions using SQL",
      "genie_space": {"space_id": "<genie-space-id>"}
    },
    {
      "type": "dashboard",
      "name": "Customer reviews dashboard",
      "description": "Answers questions about the customer reviews dashboard",
      "dashboard": {"dashboard_id": "<dashboard-id>"}
    },
    {
      "type": "uc_function",
      "name": "Flag urgent review",
      "description": "Flags a review as requiring urgent attention",
      "uc_function": {"name": "<catalog>.<schema>.<function_name>"}
    },
    {
      "type": "table",
      "table": {
        "name": "<catalog>.<schema>.<table_name>",
        "description": "Reads from the customer reviews table"
      }
    },
    {
      "type": "vector_search_index",
      "vector_search_index": {
        "name": "<catalog>.<schema>.<index_name>",
        "description": "Searches the product documentation index for relevant passages"
      }
    },
    {
      "type": "knowledge_assistant",
      "name": "Internal docs",
      "description": "Answers questions from internal documentation",
      "knowledge_assistant": {"knowledge_assistant_id": "<knowledge-assistant-id>"}
    },
    {
      "type": "serving_endpoint",
      "name": "Custom agent",
      "description": "Calls a custom agent served from a Databricks model serving endpoint",
      "serving_endpoint": {"name": "<serving-endpoint-name>"}
    },
    {
      "type": "vector_search_index",
      "name": "Product docs",
      "description": "Looks up product documentation by semantic search",
      "vector_search_index": {
        "name": "<catalog>.<schema>.<index>",
        "columns": ["title", "content"]
      }
    },
    {
      "type": "app",
      "name": "Support agent",
      "description": "Custom application endpoint",
      "app": {"name": "<app-name>"}
    },
    {
      "type": "uc_connection",
      "name": "GitHub",
      "description": "Searches GitHub for issues and pull requests",
      "uc_connection": {"name": "<uc-connection-name>"}
    },
    {
      "type": "web_search",
      "name": "Web search",
      "description": "Searches the public web for current information and returns a synthesized answer with citations",
      "web_search": {}
    },
    {
      "type": "volume",
      "volume": {
        "name": "<catalog>.<schema>.<volume>",
        "description": "Searches files in a Unity Catalog volume"
      }
    },
  ],
  stream=True
)

for event in response:
  print(event)

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

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

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

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

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단계(선택 사항): 클라이언트 쪽 함수 도구 추가

애플리케이션이 Azure Databricks 호스팅된 도구와 함께 사용자 지정 논리를 실행하도록 하려면 function 도구를 사용합니다. type: "function", name, 선택적 description, 그리고 JSON 스키마 parameters 개체로 함수 도구를 선언합니다:

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "<user prompt>"}],
  tools=[
    {
      "type": "function",
      "name": "<client-side-function-name>",
      "description": "<description of what this function does>",
      "parameters": {
        "type": "object",
        "properties": {"<param-name>": {"type": "string"}},
        "required": ["<param-names>"],
        "additionalProperties": False,
      },
    }
  ],
)

감독자 API는 요청 간에 대화 상태를 저장하지 않으므로 클라이언트 쪽 함수 호출은 다음 두 번 수행됩니다.

1. 1회전. 모델은 최종 답변 대신 function_call 항목(예: "call get_weather with location=Paris")을 반환합니다.
2. 코드 는 함수를 로컬로 실행하고 결과를 생성합니다.
3. 2턴. responses.create()를 다시 호출하고, 원래 입력, 모델의 function_call, 그리고 결과를 담은 새 function_call_output를 전달하세요. 모델은 결과를 사용하여 최종 답변을 생성합니다.

import json
from databricks_openai import DatabricksOpenAI

client = DatabricksOpenAI(use_ai_gateway=True)
MODEL = "databricks-claude-sonnet-4-5"

GET_WEATHER = {
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather for a location.",
    "parameters": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
        "additionalProperties": False,
    },
}

def run_get_weather(args):
    return json.dumps({
        "location": args["location"],
        "temp_c": 18,
        "condition": "sunny",
    })

CLIENT_TOOLS = {"get_weather": run_get_weather}
TOOLS = [GET_WEATHER]

input_list = [{"role": "user", "content": "What's the weather in Paris?"}]

# Turn 1 — model emits a function_call
resp = client.responses.create(model=MODEL, input=input_list, tools=TOOLS)

# Echo the model's turn into history, then execute pending client function_calls
input_list += [item.model_dump() for item in resp.output]
for item in resp.output:
    if item.type == "function_call" and item.name in CLIENT_TOOLS:
        args = json.loads(item.arguments)
        # Execute the client-side function with the model's arguments
        # and append the result so the model can use it on the next turn.
        tool_output = CLIENT_TOOLS[item.name](args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": tool_output,
        })

# Turn 2 — model produces the final answer using the tool result
final = client.responses.create(model=MODEL, input=input_list, tools=TOOLS)
print(final.output_text)

더 많은 패턴(스트리밍, 호스팅 및 클라이언트 도구, MCP 승인, 문제 해결)은 감독자 API 클라이언트 쪽 함수 호출 기술을 참조하세요.

5단계: 추적 사용

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
}

지원되는 도구

요청 배열에서 tools 도구를 정의합니다. 모든 도구 개체는 세 개의 최상위 필드를 공유합니다.

• type (문자열, 필수): 도구 유형을 선택하는 판별자입니다.
• name (문자열, 선택 사항): 모델에 표시되는 표시 이름입니다.
• description (문자열, 선택 사항): 이 도구를 호출할 시기에 대한 모델에 대한 힌트입니다.

또한 모든 도구 객체에는 키가 type 값과 일치하는 중첩된 구성 객체가 포함됩니다. 아래 표에서는 지원되는 각 도구 유형에 대한 중첩된 구성을 설명합니다.

의 경우 serving_endpointResponseAgent, ChatCompletions 및 ChatAgent 엔드포인트만 지원됩니다.

app의 경우 mcp- 접두사가 있는 MCP 앱과 agent- 접두사가 있는 사용자 지정 ResponseAgent 앱만 지원됩니다.

의 경우 uc_connection외부 MCP 서버 또는 system_ai_agent_* 시스템 관리 커넥터에 대해 만든 연결 이름을 사용합니다(3단계(선택 사항): 시스템 관리형 연결을 사용하여 타사 서비스에 연결 참조). 앱의 사용자 지정 MCP 서버는 지원되지 않습니다.

코드 실행

요청에 계산이 필요한 경우 감독자는 샌드박스가 설치된 서버리스 컴퓨팅 세션에서 모델 생성 코드를 실행하여 데이터를 분석하거나 파일을 변환하거나 계산을 실행합니다. Python(기본값), SQL 및 셸 명령을 지원합니다. 감독자는 필요할 때 코드 자체를 작성하고 실행하므로 코드를 사용하도록 설정, 구성 또는 제공하지 않습니다.

코드 실행은 다음을 사용하여 잠긴 샌드박스에서 실행됩니다.

• 인터넷에 액세스할 수 없습니다. 작업 영역의 네트워크 정책에 관계없이 모든 아웃바운드 네트워크 송신을 차단하므로 샌드박스에서 실행되는 코드는 외부 엔드포인트에 연결할 수 없습니다.
• 범위가 지정된 Azure Databricks 액세스만 가능합니다. 자체 데이터 액세스 권한이 없습니다. 같은 요청에서 table 도구로 선언한 Unity Catalog 테이블을 읽을 수 있습니다.

지원되는 매개 변수

감독자 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,, dashboard,uc_function, table, knowledge_assistantserving_endpoint, web_search, vector_search_index, volume, appuc_connection) 및 클라이언트 쪽 함수 도구(function). 4단계(선택 사항): 클라이언트 쪽 함수 도구 추가를 참조하세요.
• instructions: 감독자의 동작을 안내하는 시스템 프롬프트입니다.
• stream: 응답을 스트리밍하도록 true 설정합니다.
• background: 요청을 비동기적으로 실행하도록 true 설정합니다. 응답 ID를 responses.retrieve()로 폴링하여 반환합니다. 배경 모드를 참조하세요.
• trace_destination: , catalog_name및 schema_name 필드가 있는 table_prefix선택적 개체입니다. 설정되면 감독자 API는 전체 에이전트 루프의 추적을 지정된 Unity 카탈로그 테이블에 씁니다. Python 클라이언트에서 extra_body 통해 전달합니다.

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

Authorization

감독자 API는 호출자의 자격 증명을 사용하여 에이전트 루프를 실행하므로 호출하는 도구는 호출자의 Unity 카탈로그 권한을 준수합니다. API를 직접 호출하면 클라이언트가 DatabricksOpenAI 사용자와 마찬가지로 인증됩니다.

Azure Databricks 앱에서 감독자 API를 호출하는 경우 도구를 앱의 서비스 주체(앱 권한 부여) 또는 요청 사용자(사용자 권한 부여)로 실행할 수 있습니다. 앱 권한 부여의 경우 각 도구에 대한 앱의 서비스 주체 권한을 부여합니다. 사용자 권한 부여의 경우 사용자의 토큰을 클라이언트에 DatabricksOpenAI 전달하고 필요한 사용자 권한 부여 범위를 추가합니다. 요청하는 사용자로 도구 실행을 참조하세요.

Limitations

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

• 백그라운드 모드 런타임: 백그라운드 모드 요청의 최대 실행 시간은 30분입니다.
• 백그라운드 모드에서 스트리밍: stream와 background 중 어느 하나도 동일한 요청에서 true 될 수 없습니다.
• 지속성 실행: 에이전트 루프에 대해 정확히 한 번 실행이 보장되는 오류 또는 중단으로부터의 자동 복구는 지원되지 않습니다.
• 웹 검색 작업 영역 자격: HIPAA/BAA 규정 준수를 사용하도록 설정된 작업 영역에서는 web_search 이 도구를 사용할 수 없습니다. 웹 검색 가능 네이티브 모델 또는 지리 간 처리를 사용하도록 설정된 지역에서만 사용할 수 있습니다. 부적격 작업 영역에서 포함된 web_search 요청은 거부됩니다.

추가 리소스

• 감독자 API(베타)를 사용하여 사용자 지정 에이전트 빌드
• 감독자 에이전트를 사용하여 조정된 다중 에이전트 시스템 만들기
• 모델 서비스 쿼리
• Unity AI 게이트웨이를 사용한 AI 거버넌스