Interroger des agents déployés sur Azure Databricks

La manière dont vous interrogez un agent dépend du serveur d’agents qui l’héberge. Trouvez votre agent dans le tableau suivant, puis suivez la section correspondante. Pour en savoir plus sur les serveurs agents, consultez Agent Server.

Votre agent	Hébergé sur	Comment interroger
Utilise `DurableAgentServer`	Runtime d’agent sur Databricks Apps	API d’invocation sur `/api/invocations`
Utilise le MLflow `AgentServer` ou `LongRunningAgentServer` (ancienne version)	Databricks Apps	Databricks client OpenAI ou l’API OpenAI Responses à `/responses`
Déployé vers Model Serving (ancienne version)	Point de terminaison de mise en service de modèles	client OpenAI de Databricks, API REST, `ai_query` ou AI Playground

Les agents hébergés sur Databricks Apps nécessitent un jeton Databricks OAuth. Les jetons d’accès personnels ne fonctionnent pas pour les applications Databricks. Pour générer des jetons OAuth à partir d’un script, d’un principal de service, d’une autre application ou d’un notebook, voir Connecter une application Databricks à une API à l’aide de l’authentification par jeton.

Interroger un agent qui utilise `DurableAgentServer`

Les agents qui utilisent DurableAgentServer mettent en service l’API d’appel. Les agents que vous créez avec l’Agent Bricks CLI utilisent DurableAgentServer, et agentbricks deploy les déploient sur Agent Runtime sous forme d’application nommée agent-bricks-<name>. Chaque requête vers l’API lance une exécution de votre agent, appelée une invocation.

Endpoint	Description
`POST /api/invocations`	Lance une invocation. Par défaut, la requête est bloquante et renvoie le résultat. Définissez `stream` pour recevoir les événements au fur et à mesure qu’ils se produisent, ou `background` pour retourner immédiatement.
`GET /api/invocations/<id>`	Retourne le statut d’un appel et, après sa fin, sa sortie.
`GET /api/invocations/<id>/events?after=<event-id>`	Transmet en flux les événements stockés qui suivent `<event-id>`. Utilisez ce point de terminaison pour vous reconnecter à un flux.

Corps de la demande

Le corps de la requête pour POST /api/invocations accepte les champs suivants. Le serveur rejette les requêtes contenant d’autres champs.

Champ	Description
`id`	Required. Un UUID que vous générez pour chaque invocation. Le serveur considère l’ID comme une clé d’idempotence : renvoyer la même requête avec le même ID renvoie l’invocation existante au lieu de relancer l’agent. Réutiliser un ID pour une requête différente renvoie une erreur `409`.
`session_id`	La conversation à laquelle appartient l’invocation. Les invocations partageant un identifiant de session s’exécutent une à une, dans l’ordre. Les agents générés à partir des modèles CLI nécessitent ce champ.
`input`	L’entrée pour votre agent. Les agents générés à partir des modèles d’interface de ligne de commande acceptent une liste de messages, ou un objet avec une liste `messages`.
`stream`	Réglé sur `true` pour recevoir des événements en tant que Server-Sent Events (SSE).
`background`	Définissez sur `true` pour retourner immédiatement une réponse `202` avec une URL de statut, puis interrogez le résultat.

Le gestionnaire de votre agent définit la structure de input. Les agents générés à partir des modèles CLI lisent les champs suivants lorsque input est un objet :

Champ	Description
`messages`	La conversation est transférée à l’agent.
`actor`	L’identité dont l’agent lit et écrit la mémoire à long terme. Si vous ne fournissez pas un `actor`, l’agent utilise l’ID de session, donc les mémoires ne sont pas conservées dans une nouvelle session. Définissez `actor` depuis l’utilisateur connecté de votre application, pas depuis le texte que l’utilisateur tape.
`model`	Le modèle à utiliser pour cette invocation, au lieu du modèle défini dans le code de l’agent.
`resume`	La réponse à un agent qui a fait une pause pour une intervention humaine, comme l’approbation d’un appel d’outil. Lorsqu’un agent fait une pause, le `status` de l’appel est `interrupted`. Envoyez `resume` dans un nouvel appel avec le même `session_id` pour continuer.

Pour permettre à l’agent de se souvenir de ce qu’il a appris sur un utilisateur à travers les sessions, passez l’identifiant de l’utilisateur en tant que 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

Pour tester un agent déployé depuis votre terminal, utilisez agentbricks endpoint invoke. La commande localise l’application et s’authentifie avec votre profil d’interface de ligne de commande.

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

Pour diffuser en continu la réponse, ajoutez "stream":true au corps JSON et passez --sse. Pour tester l’agent pendant qu’il s’exécute localement avec agentbricks dev, remplacez le nom de l’application par --url http://localhost:8000.

REST API

Obtenez l’URL de l’application. Le champ URL dans la sortie est l’URL de base pour l’API d’invocations.
```
agentbricks --profile <profile> deployments get agent-bricks-<name>
```
Obtenez un jeton OAuth pour votre profil. La sortie contient le jeton dans le champ access_token.
```
databricks auth token --profile <profile>
```

Envoyez une requête :

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

La réponse contient l’invocation id, son status, et un champ output contenant la valeur que votre agent retourne. Le serveur ne nécessite pas de schéma de sortie : votre gestionnaire peut retourner n’importe quelle valeur sérialisable en JSON. Les agents générés à partir des modèles CLI renvoient un objet avec les champs suivants :

output: les messages que l’agent a produits dans cette invocation.
status: completed, ou interrupted si l’agent a été mis en pause en attente d’une intervention humaine.

Python

L’exemple suivant utilise le SDK Databricks pour rechercher l’URL de l’application et générer un jeton OAuth, puis appelle l’API d’invocations. WorkspaceClient doit utiliser l’authentification 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"])

Pour poursuivre la conversation, envoyez le message suivant avec le même session_id et un nouveau id.

Diffusez, exécutez en arrière-plan, puis reconnectez

Stream : Définir "stream": true. La réponse est un flux SSE qui inclut les événements run.started et run.completed (ou run.failed), ainsi que les événements que votre agent émet, comme les événements delta avec du texte diffusé. Chaque événement a un identifiant.
Exécuter en arrière-plan : définissez "background": true. Le serveur renvoie une réponse 202 avec un status_url. Interrogez GET /api/invocations/<id> jusqu’à ce que le statut soit completed. Si vous définissez aussi "stream": true, la réponse inclut un élément events_url à partir duquel vous pouvez lire des événements.
Reconnecter : Si un flux se déconnecte, appelez GET /api/invocations/<id>/events?after=<event-id> avec l’ID du dernier événement que vous avez reçu.

L’exemple Python suivant diffuse une réponse :

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

Si vous déployez l’agent avec plus d’une instance, envoyez l’ID de session dans un en-tête X-Routing-Key pour acheminer toutes les requêtes d’une session vers la même instance.

Interroger un agent qui utilise le MLflow hérité `AgentServer`

Utilisez cette section pour les agents que vous déployez sur les applications Databricks avec le serveur d’agent hérité : le MLflow AgentServer ou LongRunningAgentServer, avec l’interface ResponsesAgent. Ces agents servent l’API OpenAI Responses à /responses.

LongRunningAgentServer distribue la même API, donc les exemples suivants s’appliquent également à celle-ci. Il prend également en charge les exécutions en arrière-plan : définissez background sur true dans la requête, puis récupérer la réponse avec GET /responses/<response-id>?stream=true&starting_after=<sequence-number>, qui diffuse les événements après ce numéro de séquence.

Client OpenAI Databricks

Databricks recommande le client OpenAI Databricks pour ces agents. Incluez le apps/ préfixe dans le nom du modèle.

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)

Pour passer custom_inputs, utilisez le extra_body paramètre :

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

Pour obtenir l’identifiant de trace d’une requête, incluez l’en-tête x-mlflow-return-trace-id . Utilisez ensuite MLflow get_trace pour récupérer la trace complète.

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

Envoyez des requêtes au chemin /responses de l’URL de l’application. Le corps de la requête suit l’API OpenAI Responses, vous pouvez donc utiliser n’importe quel client HTTP ou outil qui le supporte.

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

Pour transmettre custom_inputs, ajoutez-les au corps de la requête :

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

Pour obtenir l’identifiant de la trace, incluez l’en-tête x-mlflow-return-trace-id: true . Le corps de la réponse inclut l’identifiant de trace dans un champ metadata.trace_id. Pour les requêtes en streaming, l’identifiant de trace arrive comme un événement SSE distinct (data: {"trace_id": "tr-..."}) vers la fin du flux.

Interroger un agent hérité sur Model Serving

Utilisez cette section pour les agents hérités déployés sur les points de terminaison Model Serving. Vous pouvez vous authentifier avec un jeton Databricks OAuth ou un jeton d’accès personnel. Pour transférer ces agents vers Databricks Apps, voir Migrer un agent de Model Serving vers Databricks Apps.

client OpenAI de Databricks

Pour les agents qui utilisent l’interface ResponsesAgent , appelez responses.create avec le nom du point de terminaison comme modèle :

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)

Pour les agents qui utilisent les interfaces héritées ChatAgent ou ChatModel, utilisez le client des achèvements de conversation :

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)

Avec l’un ou l’autre client, passe custom_inputs ou databricks_options via le paramètre extra_body. Par exemple, extra_body={"databricks_options": {"return_trace": True}} renvoie la trace avec la réponse.

REST API

Pour les agents qui utilisent l’interface ResponsesAgent , envoyez une requête à /serving-endpoints/responses avec le nom du point de terminaison comme modèle :

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

Pour les agents qui utilisent les interfaces ChatAgent ou ChatModel, envoyez une requête à /serving-endpoints/chat/completions avec une liste messages au lieu de input. Pour passer custom_inputs ou databricks_options, ajoutez-les au corps de la demande. Vous pouvez également envoyer des requêtes à l’URL du /serving-endpoints/<agent-endpoint-name>/invocations point de terminaison. Voir Interroger des modèles individuels derrière un point de terminaison.

AI Playground (Terrain de jeu IA)

Pour discuter avec un agent sur Model Serving sans écrire de code, ouvrez AI Playground et sélectionnez le point de terminaison de service de l’agent. Pour transmettre custom_inputs à l’agent depuis AI Playground, consultez Fournir custom_inputs dans l’application AI Playground et l’application de révision.

SQL avec

Utilisez ai_query pour interroger un agent sur Model Serving depuis SQL. Voir ai_query fonction pour la syntaxe et les paramètres.

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

Ressources additionnelles

Agent Server
Runtime de l’agent
Mettre en place la surveillance de la production
Interroger les modèles de fondation et d’embedding : Interroger directement les modèles de fondation et autres modèles, au lieu d’un agent.

Commentaires

Cette page a-t-elle été utile ?

Dernière mise à jour : 2026-10-12

Interroger des agents déployés sur Azure Databricks

Interroger un agent qui utilise DurableAgentServer

Corps de la demande

Agent Bricks

REST API

Python

Diffusez, exécutez en arrière-plan, puis reconnectez

Interroger un agent qui utilise le MLflow hérité AgentServer

Client OpenAI Databricks

REST API

Interroger un agent hérité sur Model Serving

client OpenAI de Databricks

REST API

AI Playground (Terrain de jeu IA)

SQL avec

Ressources additionnelles

Commentaires

Ressources supplémentaires

Interroger un agent qui utilise `DurableAgentServer`

Interroger un agent qui utilise le MLflow hérité `AgentServer`