Agenti dotazů nasazení na Azure Databricks

Jak dotazujete agenta, závisí na serveru agenta, který ho obsluhuje. Najděte svého agenta v následující tabulce a poté postupujte podle odpovídající části. Pro informace o serverech agentů viz Agent Server.

Tvůj agent	Hostováno na	Jak zadat dotaz
Použití `DurableAgentServer`	Agent Runtime on Databricks Apps	Invocation API na `/api/invocations`
Používá MLflow `AgentServer` nebo `LongRunningAgentServer` (legacy)	Aplikace Databricks	klient Databricks OpenAI nebo rozhraní OpenAI Responses API na `/responses`
Nasazení do služby modelů (zastaralé)	Koncový bod pro obsluhu modelu	Databricks OpenAI klient, REST API, `ai_query`, nebo AI Playground

Agenti hostovaní v aplikacích Databricks vyžadují Databricks OAuth token. Osobní přístupové tokeny nefungují pro Databricks Apps. Pro generování OAuth tokenů ze skriptu, instančního objektu služby, jiné aplikace nebo notebooku viz Připojit se k aplikaci Databricks API pomocí tokenové autentizace.

Položit dotaz agentovi, který používá `DurableAgentServer`

Agenti, kteří používají DurableAgentServer, obsluhují rozhraní API pro vyvolání. Agenti, které vytvoříte pomocí Agent Bricks CLI, používají DurableAgentServer, a agentbricks deploy je nasazují do Agent Runtime jako aplikaci s názvem agent-bricks-<name>. Každý požadavek na API spouští jeden běh vašeho agenta, nazývaný vyvolání.

Endpoint	Description
`POST /api/invocations`	Spustí volání. Požadavek ve výchozím nastavení čeká na výsledek a vrátí jej. Nastavte `stream`, aby přijímal události tak, jak nastanou, nebo `background`, aby se odpověď okamžitě vrátila.
`GET /api/invocations/<id>`	Vrací stav vyvolání a po jeho dokončení i jeho výstup.
`GET /api/invocations/<id>/events?after=<event-id>`	Streamuje uložené události, které následují po `<event-id>`. Použijte tento endpoint k opětovnému připojení ke streamu.

Text požadavku

Tělo požadavku pro POST /api/invocations přijímá následující pole. Server odmítá požadavky obsahující jiná pole.

Pole	Description
`id`	Required. UUID, které generujete pro každé volání. Server považuje ID za klíč idempotence: opětovné odeslání stejného požadavku se stejným ID vrací existující volání místo opětovného spuštění agenta. Opětovné použití ID pro jiný požadavek vrátí chybu `409` .
`session_id`	Rozhovor, ke kterému invokace patří. Invokace, které sdílejí ID relace, se spouštějí po jedné, v daném pořadí. Agenti generovaní ze šablon CLI toto pole vyžadují.
`input`	Vstup pro vašeho agenta. Agenti generovaní z CLI šablon přijímají seznam zpráv nebo objekt se seznamem `messages`.
`stream`	Nastavte na `true`, aby se události přijímaly jako události Server-Sent Events (SSE).
`background`	Nastavte na `true` okamžité vrácení `202` odpovědi se statusovou URL a poté dotazujte na výsledek.

Handler vašeho agenta definuje strukturu input. Agenti generovaní ze šablon CLI čtou následující pole, když input je objekt:

Pole	Description
`messages`	Konverzace se přepne na agenta.
`actor`	Identita, jejíž dlouhodobou paměť agent čte a do ní zapisuje. Pokud nepředáte identifikátor `actor`, agent použije ID relace, takže vzpomínky se do nové relace nepřenášejí. Nastavte `actor` podle přihlášeného uživatele vaší aplikace, ne z textu, který uživatel zadává.
`model`	Model pro toto volání je použit místo modelu nastaveného v kódu agenta.
`resume`	Odpověď agentovi, který byl pozastaven kvůli lidskému vstupu, například schválení volání nástroje. Když se agent pozastaví, stav invokace je `statusinterrupted`. Odešlete novou invokaci s `resume` se stejnou `session_id`, abyste mohli pokračovat.

Aby si agent mohl vybavit, co se o uživateli dozvěděl napříč relacemi, předejte uživatelské ID jako actor:

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

Agentní cihly

Pro testování nasazeného agenta z vašeho terminálu použijte agentbricks endpoint invoke. Příkaz vyhledá aplikaci a ověří se pomocí vašeho profilu CLI.

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

Pro streamování odpovědi přidejte "stream":true do těla JSON a předejte --sse. Pro testování agenta, který běží lokálně s agentbricks dev, nahraďte název aplikace za --url http://localhost:8000.

REST API

Získejte adresu URL aplikace. pole URL ve výstupu je základní adresa URL pro invocations API.
```
agentbricks --profile <profile> deployments get agent-bricks-<name>
```
Získejte OAuth token pro svůj profil. Výstup obsahuje token v access_token poli.
```
databricks auth token --profile <profile>
```

Odeslání požadavku:

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?" }]
  }'

Odpověď obsahuje volání id, jeho status a pole output s hodnotou, kterou váš agent vrací. Server nepotřebuje výstupní schéma: váš handler může vrátit jakoukoli hodnotu serializovatelnou JSON. Agenti generovaní ze šablon CLI vracejí objekt s následujícími poli:

output: zprávy, které agent v této invokaci vytvořil.
status: completed, nebo interrupted, pokud agent čekal na zásah člověka.

Python

Následující příklad využívá Databricks SDK k vyhledání URL aplikace a generování OAuth tokenu, poté volá invocations API. Musí WorkspaceClient používat autentizaci OAuth.

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

Pro pokračování konverzace pošlete další zprávu se stejným session_id a novým id.

Streamujte, spouštějte na pozadí a znovu se připojte

Stream: Nastavení "stream": true. Odpověď je SSE stream, který zahrnuje události run.started a run.failed (nebo delta) plus události, které váš agent vysílá, například události run.completed se streamovaným textem. Každá událost má své ID.
Spouštět na pozadí: Nastavte "background": true. Server vrátí odpověď 202 s status_url. Dotazujte se GET /api/invocations/<id>, dokud není stav completed. Pokud také nastavíte "stream": true, odpověď obsahuje events_url, ze kterého můžete číst události.
Znovu se připojit: Pokud se stream odpojí, volejte GET /api/invocations/<id>/events?after=<event-id> s ID poslední události, kterou jste obdrželi.

Následující příklad v Python streamuje odpověď:

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: "):])

Pokud nasadíte agenta s více instancemi, pošlete ID relace v záhlaví X-Routing-Key, aby všechny požadavky v relaci směrovaly do stejné instance.

Dotazovat se agenta, který používá starší MLflow `AgentServer`

Použijte tuto sekci pro agenty, které nasadíte na Databricks Apps s legacy agentním serverem: MLflow AgentServer nebo LongRunningAgentServer, s ResponsesAgent rozhraním. Tito agenti obsluhují OpenAI Responses API na /responses.

LongRunningAgentServer obsluhuje stejné API, takže následující příklady se na něj vztahují. Podporuje také běhy na pozadí: nastavte background na true v požadavku a poté načtete odpověď s GET /responses/<response-id>?stream=true&starting_after=<sequence-number>, která streamuje události za tímto pořadovým číslem.

Klient OpenAI Databricks

Databricks doporučuje pro tyto agenty klienta Databricks OpenAI. Zahrňte předponu apps/ do názvu modelu.

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)

Chcete-li předat custom_inputs, použijte parametr extra_body:

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

Pro získání ID trasování pro požadavek přidejte hlavičku x-mlflow-return-trace-id. Nakonec použijte MLflow get_trace k načtení úplné stopy.

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

Odesílejte požadavky na cestu /responses URL aplikace. Tělo požadavku má formát podle OpenAI Responses API, takže můžete použít jakéhokoli klienta HTTP nebo nástroj, který je podporuje.

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
  }'

Chcete-li předat custom_inputs, přidejte je do těla požadavku:

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 }
  }'

Pro získání ID trasování uveďte hlavičku x-mlflow-return-trace-id: true. Tělo odpovědi obsahuje ID trasování v poli metadata.trace_id. Pro požadavky na streamování dorazí ID stopy jako samostatná SSE událost (data: {"trace_id": "tr-..."}) ke konci proudu.

Dotaz na staršího agenta v Model Serving

Použijte tuto sekci pro starší agenty nasazené na koncových bodech Model Serving. Můžete se autentizovat pomocí Databricks OAuth tokenu nebo osobního přístupového tokenu. Pro přesun těchto agentů do Databricks Apps viz Migrovat agenta ze Model Serving do Databricks Apps.

Databricks OpenAI klient

Pro agenty, kteří používají rozhraní ResponsesAgent, volejte responses.create s názvem koncového bodu jako modelem:

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)

Pro agenty, kteří používají starší rozhraní ChatAgent nebo ChatModel, použijte klienta pro dokončení chatu:

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)

V obou klientech předejte custom_inputs nebo databricks_options prostřednictvím parametru extra_body. Například extra_body={"databricks_options": {"return_trace": True}} vrací stopu s odpovědí.

REST API

Pro agenty, kteří používají rozhraní ResponsesAgent, odešlete požadavek do /serving-endpoints/responses a jako model uveďte název koncového bodu:

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
  }'

Pro agenty, kteří používají rozhraní ChatAgent nebo ChatModel, odešlete požadavek na /serving-endpoints/chat/completions se seznamem messages místo input. Chcete-li předat custom_inputs nebo databricks_options, přidejte je do těla požadavku. Můžete také posílat požadavky na URL endpointu /serving-endpoints/<agent-endpoint-name>/invocations . Viz Dotaz na jednotlivé modely za endpointem.

Dětské hřiště AI

Chcete-li chatovat s agentem ve službě Model Serving bez psaní kódu, otevřete AI Playground a vyberte serving endpoint agenta. Chcete-li předat custom_inputs agentovi z AI Playground, podívejte se na Poskytnutí custom_inputs v AI Playground a aplikaci pro kontrolu.

SQL s

Použijte ai_query k dotazování agenta na Model Serving ze SQL. Vizai_query funkce pro syntaxi a parametry.

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

Dodatečné zdroje

Agent Server
Agent runtime
Nastavte monitorování produkce
Dotazování základních a embeddingových modelů: Dotazujte se přímo na základní modely a další modely namísto použití agenta.

Váš názor

Byla tato stránka užitečná?

Poslední aktualizace v 2026-10-08

Agenti dotazů nasazení na Azure Databricks

Položit dotaz agentovi, který používá DurableAgentServer

Text požadavku

Agentní cihly

REST API

Python

Streamujte, spouštějte na pozadí a znovu se připojte

Dotazovat se agenta, který používá starší MLflow AgentServer

Klient OpenAI Databricks

REST API

Dotaz na staršího agenta v Model Serving

Databricks OpenAI klient

REST API

Dětské hřiště AI

SQL s

Dodatečné zdroje

Váš názor

Další materiály

Položit dotaz agentovi, který používá `DurableAgentServer`

Dotazovat se agenta, který používá starší MLflow `AgentServer`