Query agents deployed on Azure Databricks

Hoe je een agent raadpleegt, hangt af van de agent server die hem bedient. Zoek je makelaar in de volgende tabel en volg vervolgens het overeenkomstige gedeelte. Om meer te leren over agent-servers, zie Agent Server.

Jouw agent Wordt gehost op Een query uitvoeren
Gebruiken DurableAgentServer Agent Runtime op Databricks-apps Aanroep-API op /api/invocations
Gebruikt de MLflow AgentServer of LongRunningAgentServer (legacy) Apps van Databricks Databricks OpenAI-client of de OpenAI Responses API op /responses
Ingezet naar Model Serving (legacy) Eindpunt voor modelservice Databricks OpenAI-client, REST API, ai_query, ofwel AI Playground

Agents die op Databricks Apps worden gehost, vereisen een Databricks OAuth-token. Persoonlijke toegangstokens werken niet voor Databricks-apps. Om OAuth-tokens te genereren vanuit een script, een serviceprincipal, een andere app of een notebook, zie Maak verbinding met een API-Databricks-app met tokenauthenticatie.

Doorzoek een agent die DurableAgentServer gebruikt

Agenten die DurableAgentServer gebruiken, bedienen de aanroep-API. Agents die je maakt met de Agent Bricks CLI gebruiken DurableAgentServer, en agentbricks deploy deployen ze naar Agent Runtime als een app genaamd agent-bricks-<name>. Elk verzoek aan de API start één run van je agent, een zogenaamde invocation.

Endpoint Description
POST /api/invocations Start een aanroep. Standaard wacht het verzoek en geeft het resultaat terug. Stel stream in om gebeurtenissen te ontvangen zodra ze gebeuren, of background om direct terug te keren.
GET /api/invocations/<id> Geeft de status van een aanroep terug en, nadat deze is voltooid, de uitvoer.
GET /api/invocations/<id>/events?after=<event-id> Streamt de opgeslagen gebeurtenissen die na <event-id> volgen. Gebruik dit endpoint om opnieuw verbinding te maken met een stream.

aanvraaginhoud

Het verzoeklichaam voor POST /api/invocations accepteert de volgende velden. De server wijst verzoeken af die andere velden bevatten.

Veld Description
id Required. Een UUID die je genereert voor elke invocation. De server behandelt de ID als een idempotentiesleutel: het opnieuw verzenden van hetzelfde verzoek met dezelfde ID geeft de bestaande aanroep terug in plaats van de agent opnieuw uit te voeren. Het hergebruiken van een ID voor een ander verzoek levert een 409 foutmelding op.
session_id Het gesprek waar de aanroep bij hoort. Aanroepen die een sessie-ID delen, draaien één voor één, in volgorde. Agenten die uit de CLI-sjablonen worden gegenereerd, hebben dit veld nodig.
input De input voor je agent. Agenten die uit de CLI-sjablonen zijn gegenereerd, accepteren een lijst met berichten, of een object met een lijst messages.
stream Stel in op true om gebeurtenissen te ontvangen als Server-Sent Events (SSE).
background Stel in op true om direct een 202 antwoord terug te geven met een status-URL, en poll vervolgens naar het resultaat.

De handler van je agent definieert de structuur van input. Agenten die zijn gegenereerd uit de CLI-sjablonen lezen de volgende velden wanneer input een object is:

Veld Description
messages Het gesprek wordt doorgestuurd naar de agent.
actor De identiteit van wie de agent het langetermijngeheugen leest en beschrijft. Als je geen actor meegeeft, gebruikt de agent de sessie-ID, zodat herinneringen niet worden meegenomen naar een nieuwe sessie. Stel actor in op basis van de ingelogde gebruiker van je applicatie, niet op basis van tekst die de gebruiker typt.
model Het model dat voor deze aanroep wordt gebruikt, in plaats van het model dat in de agentcode is gezet.
resume De reactie op een agent die heeft gepauzeerd voor menselijke input, zoals goedkeuring van een tooloproep. Wanneer een agent pauzeert, is de interrupted van de aanroeping status. Stuur resume in een nieuwe aanroeping met dezelfde session_id om door te gaan.

Om de agent te laten herinneren wat hij over een gebruiker heeft geleerd tussen sessies, geef je de gebruikers-ID door als 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

Om een deployed agent vanaf je terminal te testen, gebruik agentbricks endpoint invoke. Het commando zoekt de app op en authenticeert met je CLI-profiel.

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

Om het antwoord te streamen, voeg "stream":true toe aan het JSON-lichaam en geef --sse door. Om de agent te testen terwijl deze lokaal draait met agentbricks dev, vervang je de appnaam door --url http://localhost:8000.

REST API

  1. Haal de app URL op. Het URL-veld in de output is de basis-URL voor de aanroep-API.

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

  2. Zorg voor een OAuth-token voor je profiel. De uitvoer bevat het token in het access_token veld.

    databricks auth token --profile <profile>

  3. Een aanvraag verzenden:

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

Het antwoord bevat de aanroep id, de status ervan, en een output-veld met de waarde die je agent teruggeeft. De server heeft geen outputschema nodig: je handler kan elke JSON-serialiseerbare waarde teruggeven. Agenten die zijn gegenereerd uit de CLI-sjablonen geven een object met de volgende velden terug:

  • output: de berichten die de agent in deze aanroep produceerde.
  • status: completed, of interrupted als de agent pauzeerde voor menselijke input.

Python

Het volgende voorbeeld gebruikt de Databricks SDK om de app-URL op te zoeken en een OAuth-token te genereren, waarna vervolgens de invocations-API wordt aangeroepen. De WorkspaceClient moet OAuth-authenticatie gebruiken.

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

Om het gesprek voort te zetten, stuur je het volgende bericht met hetzelfde session_id en een nieuw id.

Stream, op de achtergrond uitvoeren en opnieuw verbinden

  • Stream: "stream": true instellen. De reactie is een SSE-stream die run.failed- en run.completed-gebeurtenissen bevat (of run.started-gebeurtenissen), plus de gebeurtenissen die je agent uitzendt, zoals delta-gebeurtenissen met gestreamde tekst. Elk evenement heeft een ID.
  • Op de achtergrond uitvoeren: Stel "background": true in. De server geeft een 202 antwoord terug met een status_url. Controleer periodiek GET /api/invocations/<id> totdat de status is completed. Als je ook stelt "stream": true, bevat de response een events_url waaruit je gebeurtenissen kunt lezen.
  • Opnieuw verbinden: Als een stream wordt verbroken, roep GET /api/invocations/<id>/events?after=<event-id> dan aan met de ID van de laatste gebeurtenis die je hebt ontvangen.

Het volgende Python-voorbeeld streamt een antwoord:

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

Als je de agent met meer dan één instantie deployt, stuur dan de sessie-ID in een X-Routing-Key header om alle verzoeken in een sessie naar dezelfde instantie te routeren.

Voer een query uit op een agent die de legacy MLflow gebruikt AgentServer

Gebruik deze sectie voor agenten die je deployt op Databricks-apps met de legacy agent-server: de MLflow AgentServer of LongRunningAgentServer, met de ResponsesAgent interface. Deze agenten bedienen de OpenAI Responses API op /responses.

LongRunningAgentServer bedient dezelfde API, dus de volgende voorbeelden zijn ook daarop van toepassing. Het ondersteunt ook achtergrondruns: zet background in het verzoek op true en haal vervolgens het antwoord op met GET /responses/<response-id>?stream=true&starting_after=<sequence-number>, wat de gebeurtenissen na dat sequentienummer streamt.

Databricks OpenAI client

Databricks raadt de OpenAI-client van Databricks aan voor deze agenten. Voeg het apps/ voorvoegsel toe aan de modelnaam.

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)

Om custom_inputs door te geven, gebruikt u de parameter extra_body:

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

Om de trace-ID van een verzoek te krijgen, voeg je de x-mlflow-return-trace-id header toe. Gebruik vervolgens MLflow get_trace om de volledige tracering op te halen.

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

Stuur verzoeken naar het /responses pad van de app-URL. De request body volgt de OpenAI Responses API, dus je kunt elke HTTP-client of tool gebruiken die het ondersteunt.

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

Om deze mee te sturen custom_inputs, voeg ze toe aan het verzoeklichaam:

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

Om de trace-ID te krijgen, voeg je de x-mlflow-return-trace-id: true header toe. De responsbody bevat de trace-ID in een metadata.trace_id veld. Voor streamingverzoeken arriveert de trace-ID als een aparte SSE-gebeurtenis (data: {"trace_id": "tr-..."}) nabij het einde van de stream.

Bevraag een legacy-agent op Model Serving

Gebruik deze sectie voor legacy agenten die zijn ingezet op Model Serving endpoints. Je kunt authenticeren met een Databricks OAuth-token of een persoonlijke toegangstoken. Om deze agenten naar Databricks Apps te verplaatsen, zie Een agent migreren van Model Serving naar Databricks Apps.

Databricks OpenAI client

Voor agenten die de ResponsesAgent interface gebruiken, roep responses.create aan met de endpointnaam als 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)

Voor agenten die de legacy ChatAgent of ChatModel interfaces gebruiken, gebruik de chat completions-client:

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)

Met een van beide clients geef je custom_inputs of databricks_options door via de parameter extra_body. Bijvoorbeeld, extra_body={"databricks_options": {"return_trace": True}} retourneert de trace met de respons.

REST API

Voor agenten die de ResponsesAgent interface gebruiken, stuur een verzoek naar /serving-endpoints/responses met de endpointnaam als model:

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

Voor agenten die de ChatAgent of ChatModel interfaces gebruiken, stuur een verzoek naar /serving-endpoints/chat/completions met een messages lijst in plaats van input. Om custom_inputs of databricks_options door te geven, voeg ze toe aan het verzoekgedeelte. Je kunt ook verzoeken sturen naar de /serving-endpoints/<agent-endpoint-name>/invocations URL van het eindpunt. Zie Individuele modellen achter een eindpunt opvragen.

AI-speeltuin

Om met een agent te chatten op Model Serving zonder code te schrijven, open AI Playground en selecteer het serving-endpoint van de agent. Om custom_inputs vanuit AI Playground aan de medewerker door te geven, zie custom_inputs verstrekken in de AI Playground en review-app.

SQL met

Gebruik ai_query om een agent op Model Serving vanuit SQL te bevragen. Zie ai_query function voor syntaxis en parameters.

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

Aanvullende bronnen

  • Laatst bijgewerkt om