Agenci zapytań wdrożeni na platformie Azure Databricks

Sposób zapytania do agenta zależy od serwera agenta, który go obsługuje. Znajdź swojego agenta w poniższej tabeli, a następnie przejdź do odpowiedniej sekcji. Aby dowiedzieć się więcej o serwerach agentów, zobacz Agent Server.

Twój agent Hostowane przez Jak zapytać
Użycia DurableAgentServer Środowisko uruchomieniowe agentów w aplikacjach Databricks API wywołania w /api/invocations
Wykorzystuje MLflow AgentServer lub LongRunningAgentServer (legacy) Aplikacje usługi Databricks klient Databricks OpenAI lub interfejs API OpenAI Responses pod adresem /responses
Wdrożono do Model Serving (starsze) Punkt końcowy serwisowania modelu klient Databricks OpenAI, REST API, ai_query, lub AI Playground

Agenty uruchomione w aplikacjach Databricks wymagają tokenu OAuth Databricks. Osobiste tokeny dostępu nie działają w aplikacjach Databricks. Aby wygenerować tokeny OAuth ze skryptu, jednostki usługi, innej aplikacji lub notatnika, zobacz Połącz się z aplikacją API Databricks za pomocą uwierzytelniania tokenami.

Wykonaj zapytanie do agenta, który używa DurableAgentServer

Agenci, którzy korzystają z DurableAgentServer, udostępniają interfejs API wywołań. Agenci utworzeni za pomocą Agent Bricks CLI używają DurableAgentServer, a agentbricks deploy wdraża je do środowiska Agent Runtime jako aplikację o nazwie agent-bricks-<name>. Każde żądanie do API uruchamia jedno uruchomienie agenta, zwane wywołaniem.

Endpoint Opis
POST /api/invocations Rozpoczyna wywołanie. Domyślnie żądanie czeka i zwraca wynik. Ustaw stream, aby otrzymywać zdarzenia na bieżąco, lub background, aby natychmiast zwrócić wynik.
GET /api/invocations/<id> Zwraca status wywołania, a po jego zakończeniu także jego wyjście.
GET /api/invocations/<id>/events?after=<event-id> Streamuje zapisane zdarzenia, które następują po <event-id>. Użyj tego punktu końcowego, aby ponownie połączyć się ze strumieniem.

Treść żądania

Ciało żądania dla POST /api/invocations akceptuje następujące pola. Serwer odrzuca żądania zawierające pola inne niż dozwolone.

Pole Opis
id Required. UUID, który generujesz dla każdej inwokacji. Serwer traktuje ID jako klucz idempotencji: ponowne wysłanie tego samego żądania z tym samym ID zwraca istniejące wywołanie zamiast ponownie uruchomić agenta. Ponowne użycie ID dla innego żądania powoduje błąd 409 .
session_id Rozmowę, do której należy wywołanie. Wywołania o tym samym identyfikatorze sesji uruchamiane są pojedynczo, w kolejności. Agenci generowani z szablonów CLI wymagają tego pola.
input To są dane wejściowe dla twojego agenta. Agenty generowane z szablonów CLI akceptują listę wiadomości lub obiekt z listą messages.
stream Ustaw true, aby otrzymywać zdarzenia jako Server-Sent Events (SSE).
background Ustaw tak, aby true natychmiast zwracała 202 odpowiedź ze statusowym URL, a następnie odpytywać o wynik.

Program obsługi twojego agenta definiuje strukturę input. Agenty generowane z szablonów CLI odczytują następujące pola, gdy input jest obiektem:

Pole Opis
messages Rozmowa zostaje przekazana agentowi.
actor Tożsamość, której pamięć długoterminową agent odczytuje i zapisuje. Jeśli nie przekażesz elementu actor, agent używa identyfikatora sesji, więc wspomnienia nie przechodzą do nowej sesji. Ustaw actor na podstawie zalogowanego użytkownika aplikacji, a nie tekstu wpisywanego przez użytkownika.
model Model używany dla tego wywołania, zamiast modelu ustawionego w kodzie agenta.
resume Odpowiedź dla agenta, który wstrzymał się, oczekując danych od człowieka, na przykład zatwierdzenia wywołania narzędzia. Gdy agent wstrzymuje działanie, stan wywołania to statusinterrupted. Wyślij resume w nowym wywołaniu z tym samym session_id, aby kontynuować.

Aby agent mógł przypomnieć sobie, czego dowiedział się o użytkowniku w różnych sesjach, należy podać ID użytkownika 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"
  }
}

Agent Bricks

Aby przetestować wdrożonego agenta z terminala, użyj agentbricks endpoint invoke. Polecenie wyszukuje aplikację i uwierzytelnia przy użyciu Twojego profilu CLI.

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

Aby streamować odpowiedź, dodaj "stream":true do treści JSON i przekaż --sse. Aby przetestować agenta podczas działania lokalnego za pomocą agentbricks dev, zastąp nazwę aplikacji na --url http://localhost:8000.

interfejs API REST

  1. Uzyskaj adres URL aplikacji. Pole URL w wyjściu to podstawowy URL API wywołań.

    agentbricks --profile <profile> deployments get agent-bricks-<name>

  2. Zdobądź token OAuth do swojego profilu. Wyjście zawiera token w polu access_token.

    databricks auth token --profile <profile>

  3. Wyślij żądanie:

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

Odpowiedź zawiera wywołanie id, jego status oraz pole output o wartości, którą zwraca Twój agent. Serwer nie wymaga schematu wyjściowego: twój handler może zwracać dowolną wartość serializowalną w JSON. Agenty generowane z szablonów CLI zwracają obiekt z następującymi polami:

  • output: wiadomości, które agent wygenerował podczas tej inwokacji.
  • status: completed, lub interrupted, jeśli agent wstrzymał działanie w oczekiwaniu na interwencję człowieka.

Python

Poniższy przykład wykorzystuje Databricks SDK do wyszukania adresu URL aplikacji i wygenerowania tokena OAuth, a następnie wywołuje API wywołań. WorkspaceClient musi korzystać z uwierzytelniania 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"])

Aby kontynuować rozmowę, wyślij kolejną wiadomość z tym samym session_id i nowym id.

Przesyłaj strumieniowo, uruchamiaj w tle i łącz się ponownie

  • Strumień: Ustaw "stream": true. Odpowiedź to strumień SSE, który zawiera run.started i ( run.completed lub run.failed) zdarzenia, plus zdarzenia generowane przez agenta, takie jak zdarzenia delta z tekstem strumieniowym. Każde wydarzenie ma swój identyfikator.
  • Uruchamianie w tle: Ustaw "background": true. Serwer zwraca odpowiedź 202 z elementem status_url. Odpytuj GET /api/invocations/<id>, aż status będzie completed. Jeśli ustawisz również "stream": true, odpowiedź zawiera events_url, z którego możesz czytać zdarzenia.
  • Połącz ponownie: Jeśli strumień się rozłączy, wywołaj GET /api/invocations/<id>/events?after=<event-id> z ID ostatniego zdarzenia, które otrzymałeś.

Poniższy przykład w Pythonie przesyła odpowiedź strumieniowo:

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

Jeśli wdrożysz agenta z więcej niż jedną instancją, wyślij identyfikator sesji w nagłówku X-Routing-Key, aby kierować wszystkie żądania w sesji do tej samej instancji.

Zapytaj agenta, który korzysta z legacy MLflow AgentServer

Użyj tej sekcji dla agentów, których wdrażasz w aplikacjach Databricks ze starszym serwerem agenta: MLflow AgentServer lub LongRunningAgentServer, z interfejsem ResponsesAgent. Ci agenci obsługują interfejs API OpenAI Responses pod adresem /responses.

LongRunningAgentServer obsługuje to samo API, więc poniższe przykłady również go dotyczą. Obsługuje także uruchomienia w tle: ustaw w żądaniu background na true, a następnie pobierz odpowiedź za pomocą GET /responses/<response-id>?stream=true&starting_after=<sequence-number>, które przesyła strumieniowo zdarzenia po tym numerze sekwencji.

Klient OpenAI Databricks

Databricks poleca klienta Databricks OpenAI dla tych agentów. Dołącz przedrostek apps/ do nazwy 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)

Aby przejść custom_inputs, użyj parametru extra_body :

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

Aby uzyskać identyfikator śledzenia dla żądania, dołącz nagłówek x-mlflow-return-trace-id . Następnie użyj biblioteki MLflow get_trace , aby pobrać pełny ślad.

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)

interfejs API REST

Wyślij żądania na ścieżkę /responses w adresie URL aplikacji. Treść żądania jest zgodna z API OpenAI Responses, więc możesz korzystać z dowolnego klienta lub narzędzia HTTP, które je obsługuje.

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

Aby przejść custom_inputs, dodaj je do treści żądania:

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

Aby uzyskać identyfikator śledzenia, dołącz nagłówek x-mlflow-return-trace-id: true . Ciało odpowiedzi zawiera identyfikator śledzenia w polu metadata.trace_id. W przypadku żądań strumieniowych, identyfikator śledzenia dociera jako osobne zdarzenie SSE (data: {"trace_id": "tr-..."}) pod koniec strumienia.

Zapytanie do agenta legacy o Model Serving

Użyj tej sekcji dla przestarzałych agentów wdrożonych na endpointach Model Serving. Możesz uwierzytelnić się tokenem Databricks OAuth lub osobistym tokenem dostępu. Aby przenieść tych agentów do aplikacji Databricks, zobacz Migracja agenta z Model Serving do Databricks Apps.

Klient OpenAI Databricks

Dla agentów korzystających z interfejsu ResponsesAgent wywołaj responses.create, przekazując nazwę punktu końcowego jako model:

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)

Dla agentów korzystających ze starszych interfejsów ChatAgent lub ChatModel użyj klienta Chat Completions:

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)

W przypadku dowolnego klienta przekaż databricks_options lub custom_inputs przez parametr extra_body. Na przykład extra_body={"databricks_options": {"return_trace": True}} zwraca ślad wraz z odpowiedzią.

interfejs API REST

Dla agentów korzystających z interfejsu ResponsesAgent wyślij żądanie do /serving-endpoints/responses z nazwą punktu końcowego jako modelem:

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

Dla agentów korzystających z interfejsów ChatAgent lub ChatModel wyślijcie żądanie do /serving-endpoints/chat/completions z listą messages zamiast input. Aby przekazać custom_inputs lub databricks_options, dodaj je do ciała żądania. Możesz także wysyłać żądania na adres URL endpointu /serving-endpoints/<agent-endpoint-name>/invocations . Zobacz Wyświetl informacje o poszczególnych modelach obsługiwanych przez punkt końcowy.

Plac zabaw dla sztucznej inteligencji

Aby rozmawiać z agentem w usłudze Model Serving bez pisania kodu, otwórz AI Playground i wybierz endpoint serwowania agenta. Aby przekazać custom_inputs do agenta z AI Playground, zobacz Provide custom_inputs w AI Playground oraz w aplikacji do recenzji.

SQL z

Użyj ai_query, aby wysłać zapytanie do agenta w Model Serving z poziomu SQL. Zobacz ai_query funkcję dla składni i parametrów.

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

Dodatkowe zasoby

  • Ostatnia aktualizacja o