Gözetmen API'si (Beta)

Gözetmen API'si, uzun süre çalışan görevler için arka plan modu desteğiyle Azure Databricks üzerinde özel ajanlar oluşturmayı basitleştirir. Modeli, araçları ve yönergeleri bir OpenResponses uyumlu uç nokta () için tek bir istekte tanımlarsınız ve Azure Databricks aracı döngüsünü sizin için çalıştırır: modeli tekrar tekrar çağırma, araçları seçme ve yürütme ve son yanıtı sentezleme.

Azure Databricks üzerinde özelleştirilmiş bir araç çağırma aracısı oluşturmaya yönelik üç yaklaşım vardır:

• Temsilci Bricks Denetçi Temsilcisi (önerilir): En yüksek kalite için insan geri bildirim optimizasyonu ile tamamen deklaratif.
• Gözetmen API'si: Program aracılığıyla özel bir aracı oluşturun; çalışma zamanında modelleri seçin, istek başına hangi araçların kullanılacağını denetleyin veya geliştirme sırasında yineleyin. Model seçimi üzerinde denetime ihtiyacınız olduğunda ve aracı döngüsü yönetimini Azure Databricks'e devrettiğinizde de doğru tercih olabilir.
• AI Gateway birleşik veya yerel API'ler: Kendi aracı döngünüzü yazın. Azure Databricks yalnızca LLM çıkarım katmanını sağlar. Mümkün olduğunca modeller arasında geçişi etkinleştirmek için birleşik API'ler kullanın; mevcut kodu Azure Databricks'e taşırken veya sağlayıcıya özgü özellikleri kullanırken sağlayıcıya özgü yerel API'leri (/openai, /anthropic, /gemini) tercih edin.

Gereksinimler

• Hesabınız için Unity AI Gateway'in etkinleştirildiği yapay zeka idaresi. Bkz. Azure Databricks önizlemelerini yönetme.
  • Gözetmen API'si Unity AI Gateway aracılığıyla çalıştığından çıkarım tabloları, hız sınırları ve geri dönüşler gibi AI Gateway özellikleri uygulanır. Kullanım izleme bu beta sürümünde desteklenmiyor.
• OpenTelemetry izlemelerini, hesabınız için etkinleştirilmiş Unity Kataloğu'nda depolayın . Bkz. Azure Databricks önizlemelerini yönetme.
  • Gözetmen API aracısı döngüsündeki izlemeleri Unity Kataloğu tablolarında depolar.
• Desteklenen bir bölgedeki Azure Databricks çalışma alanı.
• Çalışma alanınız için Unity Kataloğu etkinleştirildi. Bkz. Unity Kataloğu için bir çalışma alanını etkinleştirme.
• Geçirdiğiniz araçlar (Genie Agents, Unity Catalog işlevleri, MCP sunucuları, bilgi yardımcıları, Uygulamalar) zaten yapılandırılmış ve erişilebilir olmalıdır.
• Yüklenen databricks-openai paket: pip install databricks-openai

1. Adım: Tek dönüşlü LLM çağrısı oluştur

Araçlar olmadan temel bir çağrıyla başlayın. İstemci, DatabricksOpenAI çalışma alanınız için temel URL'yi ve kimlik doğrulamasını otomatik olarak yapılandırıyor:

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. Adım: Aracı döngüsünü çalıştırmak için barındırılan araçlar ekleme

İsteğe araçları eklediğinizde, Azure Databricks sizin adınıza çoklu dönüş döngüsünü yönetir: model hangi araçların çağrıleceğine karar verir, Azure Databricks bunları yürütür, sonuçları modele geri aktarır ve model son yanıtı verene kadar yineler.

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": "uc_mcp",
      "name": "Slack",
      "description": "Searches and reads from the team Slack workspace",
      "uc_mcp": {"name": "<catalog>.<schema>.<mcp_service>"}
    },
    {
      "type": "databricks_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. Adım (İsteğe bağlı): Sistem tarafından yönetilen bağlantılarla üçüncü taraf hizmetlere bağlanma

Azure Databricks Google Drive, GitHub, Atlassian, SharePoint ve Glean gibi popüler üçüncü taraf hizmetleri için sistem tarafından yönetilen bağlantılar sağlar. Bu bağlantılar, kendi dış MCP sunucunuzu ayarlamaya hızlı bir alternatiftir. Araç türünü kullanarak kendi yapılandırdığınız herhangi bir dış MCP sunucusuna bağlanabilirsiniz uc_connection .

Sistem tarafından yönetilen bağlantılar, çalışma alanınızda Aracılar için Üçüncü Taraf Bağlayıcıları Beta'nın etkinleştirilmesini gerektirir. Bkz. Azure Databricks önizlemelerini yönetme.

Aşağıdaki bağlayıcılar desteklenir:

tools dizisinde, uc_connection alanı bağlayıcı adı olarak ayarlanmış şekilde, name araç tipi kullanarak bir bağlayıcıyı geçirin.

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"
      }
    }
  ],
)

Kullanıcıdan makineye (U2M) kimlik doğrulaması

Her kullanıcı tek tek kimlik doğrulaması yapar. OAuth belirteçleri kullanıcılar arasında paylaşılmaz. Kullanıcının kimliğini doğrulamadığı bir bağlayıcı kullanan ilk talepte, yanıt status: "failed" ile tamamlanır ve oturum açma URL'si içeren bir oauth hatasıyla sonuçlanır.

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

URL'yi tarayıcıda açın, OAuth akışını tamamlayın ve aynı isteği yeniden çalıştırın.

4. Adım (İsteğe bağlı): İstemci tarafı işlev aracı ekleme

Uygulamanızın Azure Databricks barındırılan araçlarla birlikte özel mantık yürütmesini istediğinizde function araçlarını kullanın. type: "function", bir name, isteğe bağlı bir description ve bir JSON Şeması parameters nesnesi ile bir fonksiyon aracı bildirin:

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,
      },
    }
  ],
)

Gözetmen API'si istekler arasında konuşma durumunu depolamaz, bu nedenle istemci tarafı işlev çağrısı iki kez gerçekleştirilir:

1. 1'i açın. Model, nihai yanıt yerine bir function_call öğesi (örneğin, "get_weather ile location=Paris çağır") döndürür.
2. Kodunuz işlevi yerel olarak çalıştırır ve bir sonuç üretir.
3. 2. Dönüş. Özgün girdiyi, modelin responses.create() öğesini ve sonucunuzla birlikte yeni bir function_call öğesini ileterek function_call_output öğesini yeniden çağırın. Model, nihai yanıtı üretmek için sonucu kullanır.

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)

Daha fazla düzen (akış, barındırılan çözümler ve istemci araçları, MCP onayı, sorun giderme) için Supervisor API istemci taraflı işlev çağırma becerisine bkz.

5. Adım: İzlemeyi etkinleştirme

Aracı döngüsünden Unity Kataloğu tablolarına izleme göndermek için istek gövdesinde bir trace_destination geçirin. Her istek, model çağrılarının ve araç yürütmelerinin tam sırasını yakalayan bir izleme oluşturur. trace_destination ayarlamazsanız, hiçbir iz yazılmaz. Kurulum ayrıntıları için bkz. Unity Kataloğu'nda OpenTelemetry izlemelerini depolama.

databricks-openai Python istemcisini kullanarak extra_body aracılığıyla geçirin:

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>"
    }
  }
)

İzleme bilgisini doğrudan API yanıtında döndürmek için "databricks_options": {"return_trace": True}'ı extra_body'e geçirin.

MLflow dağıtılmış izlemeyi, uygulama kodunuz ve Gözetmen API aracısı döngüsündeki izlemeleri tek bir uçtan uca izlemede birleştirmek için de kullanabilirsiniz. extra_headers alanını kullanarak izleme bağlamı üst bilgilerini yayma.

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,
  )

Arka plan modu

Arka plan modu, birden çok araç çağrısı ve karmaşık mantık içeren uzun süre çalışan aracı iş akışlarını zaman uyumlu bir şekilde tamamlanmalarını beklemeden çalıştırmanızı sağlar. İsteğinizi background=True ile gönderin, hemen bir yanıt kimliği alın ve hazır olduğunda sonucu sorgulayın. Bu, özellikle birden çok veri kaynağını sorgulayan veya tek bir istekte birkaç aracıyı birbirine zincirleyen aracılar için kullanışlıdır.

Arka plan isteği oluşturma

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"

Sonuç için anket

Durumu terminal durumuna ulaşana kadar denetlemek için kullanın 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 ile arka plan modu

Güvenlik için Gözetmen API'sinin arka plan modunda herhangi bir MCP araç çağrısını yürütmeden önce açık kullanıcı onayı gerekir. Aracı döngüsü bir MCP aracı seçtiğinde, yanıt mcp_approval_request ile tamamlanır. Araç adı, sunucu etiketi ve modelin geçirmek istediği bağımsız değişkenleri inceleyebilirsiniz.

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

Araç çağrısını onaylamak ve aracı döngüsüne devam etmek için, tam konuşma geçmişiyle birlikte mcp_approval_response alanına input geri iletin.

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

Desteklenen araçlar

İsteğinizin tools dizisinde araçları tanımlarsınız. Her araç nesnesi üç üst düzey alanı paylaşır:

• type (dize, gerekli): Araç türünü seçen ayırıcı.
• name (dizge, isteğe bağlı): Modele gösterilen ad.
• description (dizge, isteğe bağlı): Bu aracın ne zaman çağırılacağı hakkında modele ipucu verir.

Ayrıca, her araç nesnesi, anahtarı type değeriyle eşleşen iç içe geçmiş bir yapılandırma nesnesi içerir. Aşağıdaki tabloda desteklenen her araç türü için iç içe yapılandırma belgelenmiştir.

için serving_endpointyalnızca ResponseAgent, ChatCompletions ve ChatAgent uç noktaları desteklenir.

app için yalnızca MCP uygulamaları (mcp- ön ekine sahip) ve özel ResponseAgent uygulamaları (agent- ön ekine sahip) desteklenir.

içinuc_connection, bir dış MCP sunucusu için oluşturduğunuz bağlantı adını veya sistem tarafından yönetilen bağlayıcıyı system_ai_agent_* kullanın (bkz. 3. Adım (İsteğe bağlı): Sistem tarafından yönetilen bağlantılarla üçüncü taraf hizmetlere bağlanma). Uygulamalar'da özel MCP sunucuları desteklenmez.

Kod yürütme

bir isteğin hesaplamaya ihtiyacı olduğunda Gözetmen verileri çözümlemek, dosyaları dönüştürmek veya hesaplamaları çalıştırmak için korumalı bir sunucusuz işlem oturumunda model tarafından oluşturulan kodu çalıştırır. Python (varsayılan), SQL ve kabuk komutlarını destekler. Gözetmen gerektiğinde kodun kendisini yazar ve çalıştırır, böylece kodu etkinleştirmez, yapılandırmaz veya sağlamazsınız.

Kod yürütme, şu şekilde kilitli bir korumalı alanda çalışır:

• İnternet erişimi yok. Çalışma alanınızın ağ ilkesinden bağımsız olarak tüm giden ağ çıkışlarını engeller, bu nedenle korumalı alanda çalışan kod dış uç noktalara ulaşamaz.
• Yalnızca kapsamlı Azure Databricks erişimi. Kendi veri erişimi yoktur. Araçla table bildirdiğiniz Unity Kataloğu tablolarını aynı istekte okuyabilir.

Desteklenen parametreler

Gözetmen API'sine yapılan her istek aşağıdaki parametreleri kabul eder.

• model: aşağıdaki desteklenen modellerden biri. Kodunuzun geri kalanını değiştirmeden sağlayıcılar arasında geçiş yapmak için bu alanı değiştirin.
  • Claude-Haiku-4.5 (databricks-claude-haiku-4-5)
  • Claude-Opus-4.1 (databricks-claude-opus-4-1)
  • Claude-Opus-4.5 (databricks-claude-opus-4-5)
  • Claude-Opus-4.6 (databricks-claude-opus-4-6)
  • Claude-Sonnet-4 (databricks-claude-sonnet-4)
  • Claude-Sonnet-4.5 (databricks-claude-sonnet-4-5)
  • Claude-Sonnet-4.6 (databricks-claude-sonnet-4-6)

• input: gönderilecek konuşma iletileri.
• tools: barındırılan araç tanımları (genie_space, dashboard, uc_function, table, knowledge_assistant, serving_endpoint, , databricks_web_search, vector_search_index, volumeappuc_connectionuc_mcp) ve istemci tarafı işlev araçları ().function Bkz . 4. Adım (İsteğe bağlı): İstemci tarafı işlev aracı ekleme.
• instructions: süpervizörün davranışına yol gösteren bir sistem istemi.
• stream: yanıtları akış olarak true ayarlayın.
• background: isteği eşzamanlı olmayan şekilde çalıştırmak için true ayarlayın. responses.retrieve() ile yokladığınız bir yanıt kimliği döndüren return. Bkz. Arka plan modu.
• trace_destination: , catalog_nameve schema_name alanları olan table_prefixisteğe bağlı nesne. Ayarlandığında, Supervisor API, belirtilen Unity Catalog tablolarına ajan döngüsünün tam izlemesini yazar. Python istemcisinde extra_body ile geçin.

API temperature gibi çıkarım parametrelerini desteklemez. Sunucu bunları dahili olarak yönetir.

Authorization

Supervisor API, ajan döngüsünü çağıranın kimlik bilgileriyle çalıştırır; böylece çağırdığı araçlar, çağıranın Unity Catalog izinlerine uygun davranır. API'yi doğrudan çağırdığınızda istemci DatabricksOpenAI sizin gibi kimlik doğrulaması yapar.

Bir Azure Databricks Uygulamasından Gözetmen API'sini çağırdığınızda, araçları uygulamanın hizmet sorumlusu (uygulama yetkilendirmesi) veya istekte bulunan kullanıcı (kullanıcı yetkilendirmesi) olarak çalıştırabilirsiniz. Uygulama yetkilendirmesi için uygulamanın hizmet sorumlusu izinlerini her araç üzerinde verin. Kullanıcı yetkilendirmesi için, kullanıcının belirtecini istemciye iletin DatabricksOpenAI ve gerekli kullanıcı yetkilendirme kapsamlarını ekleyin. Bkz. Araçları istekte bulunan kullanıcı olarak çalıştırma.

Limitations

Gözetmen API'sinde aşağıdaki sınırlamalar vardır:

• Arka plan modu çalışma zamanı: Arka plan modu isteklerinin yürütme süresi en fazla 30 dakikadır.
• Arka plan modunda akış: stream ve background ikisi de aynı istekte olamaz true .
• Dayanıklı yürütme: Aracı döngüsü için tam olarak bir kez yürütme garantileriyle hatalardan veya kesintilerden otomatik kurtarma desteklenmez.

• Web arama çalışma alanı uygunluğu: Yerel databricks_web_search Azure’da desteklenmez. İçeren databricks_web_search istekler reddedilir.

Ek kaynaklar

• Gözetmen API'sini (Beta) kullanarak özel bir aracı oluşturma
• Eşgüdümlü çok aracılı sistem oluşturmak için Gözetmen Aracısını kullanma
• Sorgu modeli hizmetleri
• Unity AI Gateway ile yapay zeka idaresi