Aller au contenu principal
Dernière mise à jour le

Interroger des agents déployés sur Databricks

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

Votre agent

Hébergé sur

How to query

Utilisations DurableAgentServer

Runtime d’agent sur Databricks Apps

API d’invocation sur /api/invocations

Utilise MLflow AgentServer ou LongRunningAgentServer (hérité)

Databricks Apps

client Databricks OpenAI ou OpenAI Responses API sur /responses

Déployé sur Model Serving (hérité)

Endpoint Model Serving

Databricks OpenAI client, REST API, ai_query, or AI Playground

Votre agent

Hébergé sur

How to query

Utilisations DurableAgentServer

Runtime d’agent sur Databricks Apps

API d’invocation sur /api/invocations

Utilise MLflow AgentServer ou LongRunningAgentServer (hérité)

Databricks Apps

client Databricks OpenAI ou OpenAI Responses API sur /responses

Déployé sur Model Serving (hérité)

Endpoint Model Serving

Databricks OpenAI client, REST API, ai_query, or AI Playground

Les agents hébergés sur Databricks Apps nécessitent un jeton OAuth Databricks. Les jetons d'accès personnels ne fonctionnent pas pour Databricks Apps. Pour générer des jetons OAuth à partir d'un script, d'un Service Principal, d'une autre application ou d'un Notebook, consultez Se connecter à une application API Databricks à l'aide de l'authentification par jeton.

Query un agent qui utilise DurableAgentServer​

Les agents qui utilisent DurableAgentServer exposent l’API d’invocation. Les agents que vous créez avec le CLI Agent Bricks utilisent DurableAgentServer, et agentbricks deploy les déploie vers Agent Runtime en tant qu’application appelée agent-bricks-<name>. Chaque requête adressée à l’API démarre une exécution de votre agent, appelée invocation.

Point de terminaison

Description

POST /api/invocations

start une invocation. Par default, la requête attend et renvoie le résultat. Définissez stream pour recevoir les événements au moment où ils se produisent, ou background pour renvoyer immédiatement.

GET /api/invocations/<id>

Renvoie le statut d'une invocation et, une fois celle-ci terminée, son résultat.

GET /api/invocations/<id>/events?after=<event-id>

Diffuse en flux (stream) les événements stockés qui suivent <event-id>. Utilisez cet endpoint pour vous reconnecter à un flux (stream).

Point de terminaison

Description

POST /api/invocations

start une invocation. Par default, la requête attend et renvoie le résultat. Définissez stream pour recevoir les événements au moment où ils se produisent, ou background pour renvoyer immédiatement.

GET /api/invocations/<id>

Renvoie le statut d'une invocation et, une fois celle-ci terminée, son résultat.

GET /api/invocations/<id>/events?after=<event-id>

Diffuse en flux (stream) les événements stockés qui suivent <event-id>. Utilisez cet endpoint pour vous reconnecter à un flux (stream).

Corps de la requête​

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

Field

Description

id

Obligatoire. Un UUID que vous générez pour chaque appel. Le serveur traite l'ID comme une clé d'idempotence : le renvoi de la même requête avec le même ID renvoie l'invocation existante au lieu de réexécuter l'agent. La réutilisation d'un ID pour une requête différente renvoie une erreur 409.

session_id

La conversation à laquelle appartient l'invocation. Les invocations qui partagent un ID de session s'exécutent l'une après l'autre, dans l'ordre. Les agents générés à partir des Template de la CLI requièrent ce champ.

input

L’entrée pour votre agent. Les agents générés à partir des Template de la CLI acceptent une liste de messages ou un objet avec une liste messages.

stream

Défini sur true pour recevoir des événements sous forme de Server-Sent Events (SSE).

background

Définir sur true pour renvoyer immédiatement une réponse 202 avec une URL de statut, puis interroger pour obtenir le résultat.

Field

Description

id

Obligatoire. Un UUID que vous générez pour chaque appel. Le serveur traite l'ID comme une clé d'idempotence : le renvoi de la même requête avec le même ID renvoie l'invocation existante au lieu de réexécuter l'agent. La réutilisation d'un ID pour une requête différente renvoie une erreur 409.

session_id

La conversation à laquelle appartient l'invocation. Les invocations qui partagent un ID de session s'exécutent l'une après l'autre, dans l'ordre. Les agents générés à partir des Template de la CLI requièrent ce champ.

input

L’entrée pour votre agent. Les agents générés à partir des Template de la CLI acceptent une liste de messages ou un objet avec une liste messages.

stream

Défini sur true pour recevoir des événements sous forme de Server-Sent Events (SSE).

background

Définir sur true pour renvoyer immédiatement une réponse 202 avec une URL de statut, puis interroger pour obtenir le résultat.

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

Field

Description

messages

Les tours de conversation à envoyer à l'agent.

actor

L’identité dont l’agent lit et écrit la mémoire à long terme. Si vous ne transmettez pas d’ actor, l’agent utilise l’ID de session ; les mémoires ne sont donc pas conservées dans une nouvelle session. Définissez actor à partir de l’utilisateur connecté à votre application, et non du texte saisi par l’utilisateur.

model

Le modèle à utiliser pour cette invocation, à la place du modèle défini dans le code de l'agent.

resume

Réponse à un agent qui s'est mis en pause pour obtenir une saisie humaine, telle que l'approbation d'un appel d'outil. Lorsqu'un agent se met en pause, le status de l'invocation est interrupted. Envoyez resume lors d'une nouvelle invocation avec le même session_id pour continuer.

Field

Description

messages

Les tours de conversation à envoyer à l'agent.

actor

L’identité dont l’agent lit et écrit la mémoire à long terme. Si vous ne transmettez pas d’ actor, l’agent utilise l’ID de session ; les mémoires ne sont donc pas conservées dans une nouvelle session. Définissez actor à partir de l’utilisateur connecté à votre application, et non du texte saisi par l’utilisateur.

model

Le modèle à utiliser pour cette invocation, à la place du modèle défini dans le code de l'agent.

resume

Réponse à un agent qui s'est mis en pause pour obtenir une saisie humaine, telle que l'approbation d'un appel d'outil. Lorsqu'un agent se met en pause, le status de l'invocation est interrupted. Envoyez resume lors d'une nouvelle invocation avec le même session_id pour continuer.

Pour permettre à l'agent de se souvenir de ce qu'il a appris sur un utilisateur d'une session à l'autre, transmettez l'ID de l'utilisateur sous la forme actor:

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

Pour tester un agent déployé depuis votre terminal, utilisez agentbricks endpoint invoke. La commande recherche l'application et s'authentifie avec votre profil CLI.

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

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

Stream, exécutez en tâche de fond et reconnectez-vous​

  • Stream : Set "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 émis par votre agent, tels que les événements delta avec du texte diffusé en continu. Chaque événement a un ID.
  • Exécuter en arrière-plan : définir "background": true. Le serveur renvoie une réponse 202 avec un status_url. Interroger GET /api/invocations/<id> jusqu’à ce que l’état soit completed. Si vous définissez également "stream": true, la réponse inclut un events_url à partir duquel vous pouvez lire des événements.
  • Reconnect : If a stream disconnects, call GET /api/invocations/<id>/events?after=<event-id> with the ID of the last event that you received.

L'exemple Python suivant Stream une réponse :

Python
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 plusieurs instances, 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.

Query un agent qui utilise le MLflow existant AgentServer​

Use this section for agents that you deploy on Databricks Apps with the legacy agent server: the MLflow AgentServer or LongRunningAgentServer, with the ResponsesAgent interface. These agents serve the OpenAI Responses API at /responses.

LongRunningAgentServer serves the same API, so the following examples also apply to it. It also supports background runs: set background to true in the request, and then retrieve the response with GET /responses/<response-id>?stream=true&starting_after=<sequence-number>, which Stream the events after that sequence number.

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

Python
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)

To pass custom_inputs, use the extra_body parameter :

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

Pour obtenir l'ID 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.

Python
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)

Query un agent hérité sur Model Serving​

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

Pour les agents qui utilisent l’interface ResponsesAgent, appelez responses.create en spécifiant le nom de l’Endpoint comme modèle :

Python
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 de complétion de chat :

Python
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)

With either client, pass custom_inputs or databricks_options through the extra_body parameter. Par exemple, extra_body={"databricks_options": {"return_trace": True}} renvoie la trace avec la réponse.

Ressources supplémentaires​

Sur cette page