Azure Databricks'e dağıtılan sorgu aracıları

Bir ajanı sorgulama şekli ona hizmet veren ajan sunucusuna bağlıdır. Temsilcinizi aşağıdaki tabloda bulun, ardından ilgili bölümü takip edin. Ajan sunucuları hakkında bilgi edinmek için Agent Server'e bakınız.

Ajanınız	Barındırılan platform	Nasıl sorgulanır
Kullanımlar `DurableAgentServer`	Databricks Apps üzerinde Agent Runtime	`/api/invocations` konumundaki Çağırma API'si
MLflow `AgentServer` veya `LongRunningAgentServer` (eski sürüm) kullanır	Databricks Uygulamaları	Databricks OpenAI istemcisi veya `/responses` adresindeki OpenAI Responses API'si
Model Serving'e dağıtıldı (eski)	Model Sunum uçnoktası	Databricks OpenAI istemcisi, REST API, `ai_query`, veya AI Playground

Databricks Apps'te barındırılan ajanlar için bir Databricks OAuth tokenı gereklidir. Kişisel erişim tokenları Databricks Uygulamaları için çalışmaz. Bir betikten, bir hizmet sorumlusundan, başka bir uygulamadan veya bir notebook'tan OAuth token'ları oluşturmak için bkz. Token kimlik doğrulamasını kullanarak bir API Databricks uygulamasına bağlanma.

`DurableAgentServer` kullanan bir ajanı sorgulayın

DurableAgentServer kullanan ajanlar çağrı API'sine hizmet verir. Agent Bricks CLI ile oluşturduğunuz ajanlar DurableAgentServer kullanır ve agentbricks deploy bunları agent-bricks-<name> adlı bir uygulama olarak Agent Runtime'a dağıtır. API'ye yapılan her istek, ajanınızın bir çalıştırmasını başlatır; buna çağırma denir.

Bitiş noktası	Description
`POST /api/invocations`	Bir yürütme başlatır. Varsayılan olarak, istek bekler ve sonucu döndürür. Olayları gerçekleştikçe almak için `background` veya hemen dönmek için `stream` ayarlayın.
`GET /api/invocations/<id>`	Bir çağrının durumunu döndürür ve tamamlandıktan sonra çıktısını döndürür.
`GET /api/invocations/<id>/events?after=<event-id>`	`<event-id>` sonrasında gelen depolanmış olayları aktarır. Bu uç noktayı kullanarak bir akışa yeniden bağlanın.

İstek içeriği

POST /api/invocations için istek gövdesi aşağıdaki alanları kabul eder. Sunucu, diğer alanları içeren istekleri reddeder.

Alan	Description
`id`	Gerekli. Her çağrı için oluşturduğunuz bir UUID. Sunucu ID'yi bir idempotency anahtarı olarak ele alır: aynı isteği aynı ID ile yeniden göndermek, ajanı tekrar çalıştırmak yerine mevcut çalıştırmayı geri getirir. Farklı bir istek için bir kimliği yeniden kullanmak `409` hatası döndürür.
`session_id`	Çağrının ait olduğu konuşma. Oturum kimliğini paylaşan çağrılar sırayla, aynı anda değil, teker teker çalışır. CLI şablonlarından oluşturulan ajanlar bu alanı gerektirir.
`input`	Ajanınız için bu giriş. CLI şablonlarından oluşturulan ajanlar, mesaj listesini veya içinde `messages` listesi bulunan bir nesneyi kabul eder.
`stream`	Olayları Server-Sent Events (SSE) olarak almak için `true` olarak ayarlayın.
`background`	`true` olarak ayarlayın; böylece hemen durum URL'si içeren bir `202` yanıt döndürülür ve ardından sonuç için sorgulama yapın.

Ajanınızın işleyicisi, input yapısını tanımlar. CLI şablonlarından oluşturulan ajanlar, input bir nesne olduğunda aşağıdaki alanları okur:

Alan	Description
`messages`	Konuşma ajana gönderilmek üzere aktarılır.
`actor`	Ajanın uzun vadeli belleğini okuyup yazdığı kimlik. Eğer bir `actor` iletmezseniz, ajan oturum kimliğini kullanır, böylece anılar yeni bir oturuma aktarılmaz. `actor` öğesini, kullanıcının yazdığı metinden değil, uygulamanızda oturum açmış kullanıcıdan ayarlayın.
`model`	Ajan kodunda ayarlanan model yerine bu çağrı için kullanılacak model.
`resume`	İnsan girdisini beklemek için duraklayan bir ajana, örneğin bir araç çağrısının onayına verilen yanıt. Bir ajan durakladığında, çağırmanın `status` durumu `interrupted` olur. `session_id` öğesini, devam etmek için aynı `resume` ile yeni bir çağrıda gönderin.

Ajanın, kullanıcı hakkında öğrendiklerini oturumlar boyunca hatırlaması için kullanıcının kimliğini actor olarak iletin:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "support-case-123",
  "input": {
    "messages": [{ "role": "user", "content": "What does Databricks do?" }],
    "actor": "user-42"
  }
}

Ajan Tuğlalar

Terminalinizden konuşlandırılmış bir ajanı test etmek için agentbricks endpoint invoke. Komut uygulamayı bulur ve CLI profilinizle kimlik doğrulaması yapar.

agentbricks --profile <profile> endpoint invoke agent-bricks-<name> \
  --path /api/invocations \
  --json "{\"id\":\"$(uuidgen)\",\"session_id\":\"$(uuidgen)\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}]}"

Yanıtı akış olarak iletmek için JSON gövdesine "stream":true ekleyin ve --sse parametresini iletin. Ajanı agentbricks dev ile yerelde çalışırken test etmek için uygulama adını --url http://localhost:8000 ile değiştirin.

REST API

Uygulama URL'sini alın. Çıktıdaki URL alanı, invocations API'si için temel URL'dir.
```
agentbricks --profile <profile> deployments get agent-bricks-<name>
```
Profiliniz için bir OAuth tokenı alın. Çıktı, access_token alanında belirteç içerir.
```
databricks auth token --profile <profile>
```

İstek gönderin:

curl --request POST \
  --url <app-url>/api/invocations \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "session_id": "support-case-123",
    "input": [{ "role": "user", "content": "What does Databricks do?" }]
  }'

Yanıt, status çağırmayı, onun output ve aracınızın döndürdüğü değeri içeren bir id alanını içerir. Sunucu çıkış şeması gerektirmez: handler'ınız herhangi bir JSON serilenebilen değeri döndürebilir. CLI şablonlarından oluşturulan ajanlar aşağıdaki alanları içeren bir nesneyi döndürür:

output: bu çağrıda ajanın ürettiği mesajlar.
status: completed, ya interrupted, ya da ajan insan girdisi için durakladıysa.

Python

Aşağıdaki örnek, uygulama URL'sini bulmak ve bir OAuth tokenı oluşturmak için Databricks SDK'yı kullanır ve ardından invocations API'sini çağırır. WorkspaceClient OAuth kimlik doğrulaması kullanmalıdır.

import uuid

import requests
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
app_url = w.apps.get("agent-bricks-<name>").url
session_id = str(uuid.uuid4())

response = requests.post(
    f"{app_url}/api/invocations",
    headers=w.config.authenticate(),
    json={
        "id": str(uuid.uuid4()),
        "session_id": session_id,
        "input": [{"role": "user", "content": "What does Databricks do?"}],
    },
)
response.raise_for_status()
print(response.json()["output"])

Konuşmaya devam etmek için, sonraki mesajı aynı id ve yeni bir session_id ile gönderin.

Akış gerçekleştirin, arka planda çalışın ve yeniden bağlanın

Akış: Ayarla "stream": true. Yanıt, run.failed ve run.started (veya run.completed) olaylarını içeren bir SSE akışıdır; ayrıca temsilcinizin yaydığı etkinlikleri de içerir; örneğin, akış halinde iletilen metin içeren delta olayları. Her etkinliğin bir kimliği vardır.
Arka planda çalıştır: "background": true ayarla. Sunucu, status_url ile bir 202 yanıt döndürür. completedDurum GET /api/invocations/<id> olana kadar sorgulayın. Ayrıca "stream": true ayarlarsanız, yanıt olayları okuyabileceğiniz bir events_url içerir.
Yeniden bağlanın: Bir akış kesilirse, GET /api/invocations/<id>/events?after=<event-id> öğesini aldığınız son olayın kimliğiyle çağırın.

Aşağıdaki Python örneği bir yanıtı akış olarak iletir:

with requests.post(
    f"{app_url}/api/invocations",
    headers=w.config.authenticate(),
    json={
        "id": str(uuid.uuid4()),
        "session_id": session_id,
        "input": [{"role": "user", "content": "Summarize our last conversation."}],
        "stream": True,
    },
    stream=True,
) as response:
    response.raise_for_status()
    for line in response.iter_lines(decode_unicode=True):
        if line.startswith("data: "):
            print(line[len("data: "):])

Ajanı birden fazla örnekle dağıtırsanız, bir oturumdaki tüm istekleri aynı instance'a yönlendirmek için oturum kimliğini X-Routing-Key başlığında gönderin.

Eski MLflow'u kullanan bir ajanı sorgulayın `AgentServer`

Bu bölümü, eski ajan sunucusuyla Databricks Apps'te dağıttığınız ajanlar için kullanın: MLflow AgentServer veya LongRunningAgentServer, ResponsesAgent arayüzü ile. Bu ajanlar, OpenAI Responses API'sine hizmet verir./responses

LongRunningAgentServer aynı API'yi sunar, bu yüzden aşağıdaki örnekler de geçerlidir. Ayrıca arka plan çalıştırmalarını destekler: istekte background değerini true olarak ayarlayın ve ardından yanıtı GET /responses/<response-id>?stream=true&starting_after=<sequence-number> ile alın; bu da bu sıra numarasından sonraki olayları akış olarak iletir.

Databricks OpenAI istemcisi

Databricks, bu ajanlar için Databricks OpenAI istemcisini önermektedir. Model adında apps/ önekini ekleyin.

from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI

input_msgs = [{"role": "user", "content": "What does Databricks do?"}]
app_name = "<agent-app-name>"

# The WorkspaceClient must use OAuth authentication.
w = WorkspaceClient()
client = DatabricksOpenAI(workspace_client=w)

# Non-streaming request
response = client.responses.create(model=f"apps/{app_name}", input=input_msgs)
print(response)

# Streaming request
streaming_response = client.responses.create(
    model=f"apps/{app_name}", input=input_msgs, stream=True
)
for chunk in streaming_response:
    print(chunk)

custom_inputs geçirmek için extra_body parametresini kullanın:

response = client.responses.create(
    model=f"apps/{app_name}",
    input=input_msgs,
    extra_body={"custom_inputs": {"id": 5}},
)

Bir isteğin iz ID'sini almak için x-mlflow-return-trace-id başlığını ekleyin. Ardından tam izlemeyi almak için MLflow get_trace kullanın.

response = client.responses.create(
    model=f"apps/{app_name}",
    input=input_msgs,
    extra_headers={"x-mlflow-return-trace-id": "true"},
)
trace_id = response.metadata["trace_id"]
trace = client.get_trace(trace_id)

REST API

İstekleri uygulama URL'sinin /responses yoluna gönderin. İstek gövdesi OpenAI Responses API'sini takip eder, yani onu destekleyen herhangi bir HTTP istemcisi veya aracını kullanabilirsiniz.

curl --request POST \
  --url <app-url>/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true
  }'

custom_inputs geçmek için, onları istek gövdesine ekleyin:

curl --request POST \
  --url <app-url>/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "input": [{ "role": "user", "content": "hi" }],
    "custom_inputs": { "id": 5 }
  }'

İzleme kimliğini almak için x-mlflow-return-trace-id: true başlığını ekleyin. Yanıt gövdesi, metadata.trace_id alanında iz kimliğini içerir. Akış istekleri için, iz kimliği yayının sonuna yakın ayrı bir SSE olayı (data: {"trace_id": "tr-..."}) olarak gelir.

Model Serving'de eski bir ajanı sorgulama

Model Servis uç noktalarına dağıtılmış eski ajanlar için bu bölümü kullanın. Databricks OAuth tokenı veya kişisel erişim tokenı ile kimlik doğrulaması yapabilirsiniz. Bu ajanları Databricks Apps'e taşımak için, Model Serving'den Databricks Apps'a bir ajanı taşıma bölümüne bakınız.

Databricks OpenAI istemcisi

ResponsesAgent arayüzünü kullanan ajanlar için, model olarak uç nokta adını kullanarak responses.create çağırın:

from databricks_openai import DatabricksOpenAI

input_msgs = [{"role": "user", "content": "What does Databricks do?"}]
endpoint = "<agent-endpoint-name>"

client = DatabricksOpenAI()

# Non-streaming request. Calls predict.
response = client.responses.create(model=endpoint, input=input_msgs)
print(response)

# Streaming request. Calls predict_stream.
streaming_response = client.responses.create(model=endpoint, input=input_msgs, stream=True)
for chunk in streaming_response:
    print(chunk)

Eski ChatAgent veya ChatModel arayüzleri kullanan ajanlar için, sohbet tamamlama istemcisini kullanın:

from databricks.sdk import WorkspaceClient

messages = [{"role": "user", "content": "What does Databricks do?"}]
endpoint = "<agent-endpoint-name>"

client = WorkspaceClient().serving_endpoints.get_open_ai_client()
response = client.chat.completions.create(model=endpoint, messages=messages)
print(response)

Her iki istemcide de custom_inputs veya databricks_options değerini extra_body parametresiyle iletin. Örneğin, extra_body={"databricks_options": {"return_trace": True}} izi yanıtla birlikte döndürür.

REST API

ResponsesAgent arayüzünü kullanan ajanlar için, uç nokta adını model olarak kullanarak /serving-endpoints/responses konumuna bir istek gönderin:

curl --request POST \
  --url https://<workspace-url>/serving-endpoints/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "<agent-endpoint-name>",
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true
  }'

ChatModel veya ChatAgent arayüzlerini kullanan ajanlar için, input yerine messages listesiyle /serving-endpoints/chat/completions'ye bir istek gönderin. custom_inputs veya databricks_options iletmek için, bunları istek gövdesine ekleyin. Ayrıca isteği uç noktanın /serving-endpoints/<agent-endpoint-name>/invocations URL'sine gönderebilirsiniz. Bkz.: Bir uç noktanın arkasındaki tek tek modelleri sorgulama.

AI Oyun Alanı

Model Serving'de kod yazmadan bir ajanla sohbet etmek için AI Playground'u açın ve ajanın servis uç noktasını seçin. AI Playground'dan temsilciye custom_inputs iletmek için AI Playground ve gözden geçirme uygulamasında Provide custom_inputs konusuna bakın.

SQL ile

SQL'den Model Serving'deki bir ajanı sorgulamak için ai_query kullanın. Sözdizimi ve parametreler için ai_query işlev bölümüne bakın.

SELECT ai_query(
  "<agent-endpoint-name>", question
) FROM (VALUES ('what is MLflow?'), ('how does MLflow work?')) AS t(question);

Ek kaynaklar

Agent Server
Aracı Çalışma Zamanı
Üretim izlemeyi ayarlayın
Temel ve gömme modellerini sorgulama: Temel modelleri ve diğer modelleri bir aracı yerine doğrudan sorgulayın.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-10-08

Azure Databricks'e dağıtılan sorgu aracıları

DurableAgentServer kullanan bir ajanı sorgulayın

İstek içeriği

Ajan Tuğlalar

REST API

Python

Akış gerçekleştirin, arka planda çalışın ve yeniden bağlanın

Eski MLflow'u kullanan bir ajanı sorgulayın AgentServer

Databricks OpenAI istemcisi

REST API

Model Serving'de eski bir ajanı sorgulama

Databricks OpenAI istemcisi

REST API

AI Oyun Alanı

SQL ile

Ek kaynaklar

Geri Bildirim

Ek kaynaklar

`DurableAgentServer` kullanan bir ajanı sorgulayın

Eski MLflow'u kullanan bir ajanı sorgulayın `AgentServer`