API en mode Agent dans Les agents Genie

Les API en mode Agent vous permettent d’exécuter le mode Agent par programmation au lieu de l’interface utilisateur Azure Databricks. Utilisez-les pour intégrer le mode Agent dans vos propres applications, telles que les chatbots, les rapports planifiés et les outils internes.

Important

Cette fonctionnalité est en version bêta. Pour l’utiliser, un administrateur d’espace de travail doit activer les API en mode Agent pour les agents Genie à partir de la page Aperçus . Consultez Gérer les préversions d’Azure Databricks.

Note

Le mode Agent était anciennement appelé Agent de recherche. Les agents génie étaient anciennement appelés Génie Spaces.

Fonctionnement des API en mode Agent

Avec les API en mode Agent, vous envoyez une question en langage naturel à un Agent Génie. Il crée et affine un plan de recherche, exécute des requêtes SQL, itère en fonction de chaque résultat et retourne un rapport avec des citations et des tables de prise en charge. Flux de résultats vers votre client en tant qu’événements Server-Sent (SSE).

Les API couvrent les points de terminaison, les formats de demande et de réponse, ainsi que les types d’événements de diffusion en continu nécessaires pour communiquer directement avec le mode Agent. Pour obtenir la vue d’ensemble du concept, consultez le mode Agent. Pour connaître l’expérience de l’interface utilisateur, consultez Utiliser le mode Agent.

Exigences

Pour utiliser les API en mode Agent, votre espace de travail doit répondre aux exigences suivantes :

Le catalogue Unity est activé. Consultez Qu’est-ce que Unity Catalog ?.
Les fonctionnalités IA optimisées par les partenaires sont activées. Consultez les fonctionnalités d’IA optimisées par les partenaires.
Vous disposez d’un Agent Genie avec des instructions claires et des métadonnées de table. Le mode Agent s’appuie sur ce contexte pour raisonner vos données. Consultez Curate un agent Génie efficace.

Get started

Les exemples suivants montrent comment envoyer une invite et lire la réponse diffusée en continu.

Envoyer votre première invite avec curl

La requête suivante envoie une question en langage naturel à un Agent Génie et diffuse la réponse sous la forme d’une SSE :

curl -N --no-buffer \
  -X POST "https://${DATABRICKS_HOST}/api/2.0/genie/agents/${AGENT_ID}/responses" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [{"type": "input_text", "text": "What were our top 10 customers by revenue last quarter?"}]
      }
    ]
  }'

Les événements arrivent en tant que event: paires data: :

event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"object":"response","id":"01f14fe4e34b...","model":"genie-agent","status":"in_progress","output":[],"conversation_id":"01f14fe4e338..."}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"sequence_number":1,"item":{"type":"reasoning","id":"01f14fe4f248...","status":"in_progress","content":[{"type":"reasoning_text","text":"I need to find revenue data..."}],"summary":[]}}

event: response.completed
data: {"type":"response.completed","sequence_number":42,"response":{"object":"response","id":"01f14fe4e34b...","model":"genie-agent","status":"completed","output":[...],"conversation_id":"01f14fe4e338...","created_at":1748383200}}

Lire le flux avec le client Databricks OpenAI (Python)

Installez le client :

pip install databricks-openai

Créez une réponse et gérez chaque événement à mesure qu’il arrive :

from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI

AGENT_ID = "<your-agent-id>"  # Same as your Genie Agent ID

w = WorkspaceClient()
host = f"https://{w.config.host}" if not w.config.host.startswith("http") else w.config.host

client = DatabricksOpenAI(workspace_client=w)
client.base_url = f"{host}/api/2.0/genie/agents/{AGENT_ID}"

stream = client.responses.create(
    model="genie-agent",
    input=[
        {
            "type": "message",
            "role": "user",
            "content": [{"type": "input_text", "text": "What were our top 10 customers by revenue last quarter?"}],
        }
    ],
    stream=True,
)

conversation_id = None
for event in stream:
    if event.type == "response.created":
        conversation_id = event.response.conversation_id
    elif event.type == "response.output_item.done":
        print(f"Output item: {event.item.type}")
    elif event.type == "response.completed":
        print(f"Done: {event.response.status}")
    elif event.type == "response.failed":
        print(f"Failed: {event.response.error}")

Envoyer une invite de suivi

Pour poursuivre une conversation, passez la conversation_id première réponse :

stream = client.responses.create(
    model="genie-agent",
    input=[
        {
            "type": "message",
            "role": "user",
            "content": [{"type": "input_text", "text": "Break that down by region"}],
        }
    ],
    stream=True,
    extra_body={"conversation_id": conversation_id},
)

L’agent conserve le contexte des tours précédents et peut référencer des requêtes et des résultats antérieurs.

Référence d’API

Les API en mode Agent couvrent les points de terminaison disponibles, les formats de demande et de réponse, le cycle de vie des événements SSE, les modèles de données et les codes d’erreur.

URL de base

Tous les points de terminaison sont relatifs à l’URL de base suivante :

https://<workspace-url>/api/2.0/genie/agents

Note

Dans agent_id chaque chemin est l’ID de l’agent Genie, le même identificateur hexadécimal de 32 caractères qui apparaît dans l’URL de l’agent Génie.

Endpoints

Les API fournissent les points de terminaison suivants :

Méthode	Chemin	Description
`POST`	`/{agent_id}/responses`	Créez une réponse en tant que flux SSE.
`GET`	`/{agent_id}/conversations/{conversation_id}/items`	Répertorier tous les éléments d’une conversation.

Créer une réponse

Crée une réponse en mode Agent. Retourne un flux SSE qui fournit des éléments de sortie en temps réel en tant que mode Agent s’exécute.

POST /{agent_id}/responses

Paramètres de chemin d’accès

Le point de terminaison accepte le paramètre de chemin d’accès suivant :

Paramètre	Type	Obligatoire	Description
`agent_id`	`string`	Oui	ID de l’agent Génie. Chaîne hexadécimale en minuscules de 32 caractères.

Corps de la demande

Le corps de la demande accepte les champs suivants :

Champ	Type	Obligatoire	Default	Description
`input`	`array<InputItem>`	Oui	None	Éléments d’entrée. Le tableau doit contenir exactement un `message` élément contenant `role: "user"` la question. Le contexte à plusieurs tour est géré côté serveur, donc utilisez-les `conversation_id` pour les suivis au lieu de transmettre des messages antérieurs dans `input`.
`conversation_id`	`string`	Non	`null`	ID d’une conversation existante à poursuivre. En cas d’omission, une nouvelle conversation est créée.
`enable_viz`	`boolean`	Non	`false`	Quand la valeur est true, Genie peut générer des visualisations. Genie génère des visualisations le cas échéant, et toutes les réponses peuvent inclure des visualisations.

Cycle de vie des événements SSE

Le flux s’ouvre avec un response.created événement, diffuse des éléments de sortie, puis se ferme avec un événement terminal :

response.created                    (once, stream opened)
  -> response.output_item.added     (0..N, new item appears)
  -> response.output_item.updated   (0..N, item content changed)
  -> response.output_item.done      (0..N, item finalized)
  -> response.completed             (once, terminal success)
     OR response.failed             (once, terminal failure)

Chaque événement porte une augmentation sequence_number monotonique que vous pouvez utiliser pour commander.

Types d’événements SSE

Le flux émet les types d’événements suivants.

response.created

Émis une fois au début. Contient un Response objet avec status: "in_progress" et un tableau vide output .

event: response.created
data: {
  "type": "response.created",
  "sequence_number": 0,
  "response": {
    "object": "response",
    "id": "01f15a22a7a816299374da7bc4264025",
    "model": "genie-agent",
    "status": "in_progress",
    "output": [],
    "conversation_id": "01f15a22a79a1699ab5e7f59563c5655",
    "created_at": 1748383200
  }
}

response.output_item.added

Émis lorsqu’un nouvel élément de sortie apparaît en premier. L’élément peut toujours être in_progress.

event: response.output_item.added
data: {
  "type": "response.output_item.added",
  "output_index": 0,
  "sequence_number": 1,
  "item": {
    "type": "reasoning",
    "id": "01f14fe4f24818d79f3e5963c31ec151",
    "status": "in_progress",
    "content": [
      {"type": "reasoning_text", "text": "I need to find the revenue data..."}
    ],
    "summary": []
  }
}

response.output_item.updated

Émis lorsque le contenu d’un élément existant change, par exemple lorsque les résultats de la requête arrivent pour un function_call_output. Utilise la même forme de charge utile que response.output_item.added.

response.output_item.done

Émis lorsqu’un élément de sortie atteint son état final. Utilise la même forme de charge utile que response.output_item.added. Si un élément arrive déjà terminé, les événements et added les done événements sont émis dans la séquence.

response.completed

Événement de réussite de terminal. Encapsule la finale Response avec tous les éléments de sortie.

event: response.completed
data: {
  "type": "response.completed",
  "sequence_number": 42,
  "response": {
    "object": "response",
    "id": "01f14fe4e34b1b2293908bcece575499",
    "model": "genie-agent",
    "status": "completed",
    "output": [ ... ],
    "conversation_id": "01f14fe4e33816c6aa264b4661f998ea",
    "created_at": 1748383200
  }
}

response.failed

Événement d’échec de terminal. Response Has status: "failed" et un error objet. Un élément de message d’erreur système est émis comme response.output_item.added juste avant cet événement. Pour obtenir la liste complète des codes, consultez les codes d’erreur de streaming.

event: response.failed
data: {
  "type": "response.failed",
  "sequence_number": 5,
  "response": {
    "object": "response",
    "id": "01f14fe4e34b1b2293908bcece575499",
    "model": "genie-agent",
    "status": "failed",
    "output": [ ... ],
    "error": {
      "type": "server_error",
      "code": "sql_execution_error",
      "message": "Table 'sales' does not exist"
    },
    "conversation_id": "01f14fe4e33816c6aa264b4661f998ea",
    "created_at": 1748383200
  }
}

Concurrency

Une seule réponse peut être générée par conversation à la fois. Une deuxième requête à une conversation qui a déjà une réponse en cours retourne un HTTP 409 :

HTTP 409
{"error": {"type": "RESOURCE_CONFLICT", "message": "A response is already being generated for conversation <id>"}}

Délais d’expiration

Le flux SSE a un délai d’expiration côté serveur de 90 minutes. Étant donné que le mode Agent exécute le raisonnement en plusieurs étapes et l’exécution SQL, maintenez votre connexion HTTP ouverte pendant toute la durée.

Répertorier les éléments de conversation

Récupère les éléments de sortie d’une conversation sous forme de liste plate. Les éléments de tous les tours sont combinés par ordre chronologique, notamment les messages utilisateur, le raisonnement, les requêtes, les résultats et les rapports. Ce point de terminaison prend en charge la pagination basée sur le curseur via les paramètres de requête et after de limit requête.

GET /{agent_id}/conversations/{conversation_id}/items

Utilisez ce point de terminaison pour :

Affichez l’historique complet des conversations dans votre application.
Récupérez les résultats après une déconnexion d’un flux SSE. Appelez ce point de terminaison une fois la réponse terminée.
Récupérez les conversations volumineuses de manière incrémentielle au lieu de charger tous les éléments en même temps.

Paramètres de chemin d’accès

Le point de terminaison accepte les paramètres de chemin d’accès suivants :

Paramètre	Type	Obligatoire	Description
`agent_id`	`string`	Oui	ID de l’agent Génie. Chaîne hexadécimale en minuscules de 32 caractères.
`conversation_id`	`string`	Oui	ID de la conversation.

Paramètres de la requête

Le point de terminaison accepte les paramètres de requête suivants :

Paramètre	Type	Obligatoire	Default	Description
`limit`	`integer`	Non	100	Nombre maximal d’éléments à retourner. Plage : 1 à 100.
`after`	`string`	Non	None	Curseur de pagination. `last_id` Passez à partir d’une réponse précédente pour récupérer la page suivante.
`order`	`string`	Non	`asc`	Ordre de tri. Utiliser `asc` pour l’ordre chronologique (premier le plus ancien) ou `desc` pour l’ordre chronologique inverse (le plus récent en premier).

Exemples de requêtes

Récupérez tous les éléments d’une conversation :

GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items

Limitez la taille de la page :

GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items?limit=5

Retournez d’abord les éléments les plus récents :

GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items?order=desc&limit=5

Récupérez la page suivante :

GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items?limit=5&after=01f14fe4f24e10beacaa1720d4b79b59_output

Response

La réponse a Content-Type: application/json et est une enveloppe de liste paginé avec "object": "list":

{
  "data": [
    {
      "type": "message",
      "role": "user",
      "content": [{ "type": "input_text", "text": "What were our top 10 customers by revenue last quarter?" }],
      "id": "01f14fe4e34b1b2293908bcece575499_input",
      "status": "completed"
    },
    {
      "type": "reasoning",
      "id": "01f14fe4f24818d79f3e5963c31ec151",
      "status": "completed",
      "content": [{ "type": "reasoning_text", "text": "I'll query the revenue table grouped by customer..." }],
      "summary": []
    },
    {
      "type": "function_call",
      "id": "01f14fe4f24e10beacaa1720d4b79b59",
      "call_id": "01f14fe4f24e10beacaa1720d4b79b59",
      "status": "completed",
      "name": "execute_sql",
      "arguments": "{\"title\": \"Top 10 Customers\", \"sql\": \"SELECT customer, SUM(revenue) AS total FROM sales GROUP BY customer ORDER BY total DESC LIMIT 10\"}"
    },
    {
      "type": "function_call_output",
      "id": "01f14fe4f24e10beacaa1720d4b79b59_output",
      "call_id": "01f14fe4f24e10beacaa1720d4b79b59",
      "status": "completed",
      "output": "Top 10 Customers\n\n| customer | total |\n| --- | --- |\n| Acme Corp | 1500000 |\n| Globex | 1200000 |"
    },
    {
      "type": "message",
      "id": "01f14fe5383f184a97ca1178af0d9356",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Here are your top 10 customers by revenue last quarter [1](https://host/genie/rooms/01f14fe4e338.../chats/01f14fe4e338...?o=12345&gra_focus=01f14fe4f24e...)."
        },
        {
          "type": "output_text",
          "text": "| customer | total |\n| --- | --- |\n| Acme Corp | 1500000 |\n| Globex | 1200000 |",
          "metadata": {
            "columns": [
              { "name": "customer", "type": "STRING" },
              { "name": "total", "type": "DOUBLE" }
            ],
            "preview_rows": [
              ["Acme Corp", "1500000"],
              ["Globex", "1200000"]
            ],
            "total_row_count": 10,
            "status": "available",
            "sql": "SELECT customer, SUM(revenue) AS total FROM sales GROUP BY customer ORDER BY total DESC LIMIT 10"
          }
        },
        {
          "type": "output_text",
          "text": "Acme Corp leads with $1.5M [1](https://host/genie/rooms/01f14fe4e338.../chats/01f14fe4e338...?o=12345&gra_focus=01f14fe4f24e...), followed by Globex at $1.2M [1](https://host/genie/rooms/01f14fe4e338.../chats/01f14fe4e338...?o=12345&gra_focus=01f14fe4f24e...)..."
        }
      ]
    }
  ],
  "first_id": "01f14fe4e34b1b2293908bcece575499_input",
  "last_id": "01f14fe5383f184a97ca1178af0d9356",
  "has_more": false,
  "status": "completed",
  "object": "list"
}

Le champ de niveau status supérieur reflète l’état de la dernière réponse dans la conversation. Il s’agit "in_progress" d’une réponse en streaming ou "completed""failed" après sa fin. Interrogez ce champ pour détecter la fin d’une réponse.

Pagination

La réponse comprend trois champs de pagination :

Champ	Type	Description
`first_id`	`string`	ID du premier élément de la page active. Absent lorsqu’il `data` est vide.
`last_id`	`string`	ID du dernier élément de la page active. Transmettez-le pour `after` récupérer la page suivante. Absent lorsqu’il `data` est vide.
`has_more`	`boolean`	`true` lorsque d’autres éléments suivent cette page.

Pour paginer tous les éléments, demandez des pages jusqu’à ce que has_more :false

items = []
after = None
while True:
    params = {"limit": 10}
    if after:
        params["after"] = after
    page = client.get(f"/conversations/{conv_id}/items", params=params)
    items.extend(page["data"])
    if not page["has_more"]:
        break
    after = page["last_id"]

Le data tableau contient des éléments de sortie dans l’ordre chronologique. Les messages d’entrée utilisateur apparaissent sous forme message d’éléments avec un _input suffixe sur l’ID.

Comprendre la réponse

Cette section explique comment les éléments de sortie s’adaptent ensemble pour former une réponse complète en mode Agent.

Flux d’élément de sortie

Une réponse en mode Agent classique produit des éléments de sortie dans l’ordre suivant :

reasoning              The agent's plan and analysis
    |
function_call          A SQL query the agent runs
    |
function_call_output   The query results, paired with the function_call above
    |
  ... (reasoning, function_call, and function_call_output repeat for each query) ...
    |
message                The final report, with structured text and inline tables

L’agent peut exécuter plusieurs requêtes dans la séquence, en affinant son analyse en fonction de chaque résultat. Une seule réponse peut contenir de nombreux cycles de raisonnement, de requête et de résultats avant le rapport final.

Comment function_call et function_call_output paire

Chaque requête SQL produit une paire d’éléments de sortie liés par call_id:

function_call est la requête exécutée par l’agent. Le arguments champ est une chaîne encodée JSON qui décrit l’appel de l’outil.
function_call_output est le résultat. Une fois l’élément terminé, le output champ contient le titre de la requête suivi d’une table markdown des données.

La call_id valeur est identique sur les deux éléments. C’est function_call_output.id toujours {call_id}_output.

Analyser le rapport

L’élément de sortie final est un message avec role: "assistant". Son content tableau contient plusieurs output_text blocs de deux types :

Les blocs de texte contiennent une analyse narrative avec des liens de citation inline.
Les blocs de table contiennent les résultats de requête inline affichés sous forme de tables Markdown. Chaque segment de table porte avec les données de résultat de requête structurée, afin que votre client puisse afficher des tables ou des graphiques enrichis metadata par programmation.

Le bloc de tableau suivant inclut à la fois le markdown rendu et la structure metadata:

{
  "type": "output_text",
  "text": "| customer | total |\n| --- | --- |\n| Acme Corp | 1500000 |\n| Globex | 1200000 |",
  "metadata": {
    "columns": [
      { "name": "customer", "type": "STRING" },
      { "name": "total", "type": "DOUBLE" }
    ],
    "preview_rows": [
      ["Acme Corp", "1500000"],
      ["Globex", "1200000"]
    ],
    "total_row_count": 10,
    "status": "available",
    "sql": "SELECT customer, SUM(revenue) AS total FROM sales GROUP BY customer ORDER BY total DESC LIMIT 10"
  }
}

Un objet de bloc metadata de table contient les champs suivants :

Champ	Type	Description
`columns`	`array<ColumnInfo>`	Définitions de colonne.
`preview_rows`	`array<array<string>>`	Lignes de résultat tronquées.
`total_row_count`	`integer`	Nombre total de lignes, lorsqu’il est connu.
`status`	`string`	`"available"` ou `"fetch_failed"`.
`sql`	`string`	Requête SQL qui a produit les résultats.

Références

Les blocs de texte du rapport contiennent des citations inline qui lient chaque revendication à la requête SQL qui la prend en charge. Chaque citation est un lien markdown du formulaire [N](url), où N se trouve un numéro de note de bas de page séquentiel et url pointe vers l’interface utilisateur de l’agent Genie avec le focus de requête approprié.

L’URL de citation a le format suivant :

https://<workspace-url>/genie/rooms/<space_id>/chats/<conversation_id>?o=<workspace_id>&gra_focus=<attachment_id>

L’URL contient les composants suivants :

Composant	Description
`space_id`	L’ID de l’agent Genie, la même valeur que `agent_id`.
`conversation_id`	Conversation qui contient la requête citée.
`workspace_id`	ID d’espace de travail numérique.
`attachment_id`	ID de pièce jointe de requête, qui identifie le résultat de la requête SQL spécifique.

Pour afficher des citations, suivez ces instructions en fonction de votre client :

Les renderers Markdown affichent automatiquement les citations sous forme de liens de note de bas de page cliquables.
Pour le texte brut, réduisez ou supprimez [N](url)[N] la citation.
Pour une interface utilisateur personnalisée, analysez le gra_focus paramètre de requête à partir de l’URL pour identifier la requête citée, puis faites-la correspondre aux function_call_output éléments de la conversation.

Les citations sont dédupliquées. Si la même requête est citée plusieurs fois, chaque référence utilise le même numéro d’index et la même URL.

Modèles de données

Cette section décrit les objets retournés par les API.

Response

L’objet Response est retourné dans les response.createdévénements , response.completedet response.failed SSE.

Champ	Type	Description
`object`	`string`	A toujours la valeur `"response"`.
`id`	`string`	ID de réponse unique.
`model`	`string`	A toujours la valeur `"genie-agent"`.
`status`	`string`	`"in_progress"`, `"completed"` ou `"failed"`.
`output`	`array<OutputItem>`	Éléments de sortie générés par la réponse.
`conversation_id`	`string`	La conversation à laquelle appartient la réponse.
`created_at`	`integer`	Heure d’époque Unix en secondes lors de la création de la réponse.
`error`	`ErrorInfo`	Présent quand `status` est `"failed"`.

Informations sur l'erreur

L’objet ErrorInfo décrit un échec :

Champ	Type	Description
`type`	`string`	L’un des suivants : `server_error`, `invalid_request`, `not_found`, `model_error`, ou `too_many_requests`.
`message`	`string`	Description lisible par l’homme. Pour les erreurs internes, il s’agit toujours `"An internal error occurred"`.
`code`	`string`	Code d’erreur facultatif avec plus de détails, tel que `"sql_execution_error"` ou `"warehouse_access_denied"`. Consultez les codes d’erreur de streaming.

Éléments de sortie

Les éléments de sortie sont polymorphes sur le type champ. Les types suivants sont disponibles.

reasoning

Le raisonnement interne de l’agent en tant que mode Agent s’exécute.

Champ	Type	Description
`type`	`string`	`"reasoning"`.
`id`	`string`	ID d’élément unique.
`status`	`string`	`"in_progress"` ou `"completed"`.
`content`	`array<ContentItem>`	Contient des `reasoning_text` éléments.
`summary`	`array<string>`	A toujours la valeur `[]`. Réservé pour une utilisation ultérieure.

function_call

Appel d’outil, qui est une exécution de requête SQL.

Champ	Type	Description
`type`	`string`	`"function_call"`.
`id`	`string`	ID d’élément unique.
`call_id`	`string`	ID de corrélation qui lie à la paire `function_call_output`.
`status`	`string`	`"completed"`.
`name`	`string`	`"execute_sql"`.
`arguments`	`string`	Chaîne JSON, par exemple `{"title": "Human-readable query title", "sql": "SELECT ..."}`. L’ensemble de clés peut changer, de sorte que votre client ne doit pas dépendre d’un schéma fixe.

function_call_output

Résultat d’un appel d’outil, associé à un function_call via call_id.

Champ	Type	Description
`type`	`string`	`"function_call_output"`.
`id`	`string`	A toujours la valeur `{call_id}_output`.
`call_id`	`string`	Correspond au `function_call`.
`status`	`string`	`"in_progress"` ou `"completed"`.
`output`	`string`	Résultat de la requête. Consultez le tableau de cycle de vie suivant.

Le output champ évolue à mesure que l’élément progresse :

Status	`output` Contenu
`in_progress`	Titre de la requête uniquement.
`completed`	Titre de la requête, ligne vide, puis table de résultats markdown.

Note

Les données de résultat de requête structurées, telles que les colonnes, les lignes et SQL, sont disponibles sur les blocs de table du rapport, et non sur l’élément function_call_output . Consultez Analyser le rapport.

message

Message texte. Un message s’affiche dans l’un des trois rôles suivants :

Role	Quand	Description
`"user"`	Input	Question de l’utilisateur. Apparaît dans `GET` les réponses avec un `_input` suffixe sur l’ID.
`"assistant"`	Rapport	Rapport structuré final avec des blocs de texte et de tableau inline.
`"system"`	Erreur ou annulation	Émis lorsqu’une réponse échoue ou est annulée.

L’objet message contient les champs suivants :

Champ	Type	Description
`type`	`string`	`"message"`.
`role`	`string`	`"user"`, `"assistant"` ou `"system"`.
`content`	`array<ContentItem>`	Contenu du message. Consultez Analyser le rapport pour les messages de l’Assistant.
`id`	`string`	ID d’élément unique. Les messages système utilisent `{responseId}_error` ou `{responseId}_cancelled`.
`status`	`string`	`"completed"`, `"failed"` ou `"cancelled"`.

En cas d’échec d’une réponse, l’erreur structurée est remise sur le champ de Response l’objet error (voir ErrorInfo) et dans l’événementresponse.failed, et non sur l’élément systèmemessage.

Éléments de contenu

Les API utilisent les types d’éléments de contenu suivants :

Type	Champs	Utilisé dans
`input_text`	`text`	Messages utilisateur (entrée).
`output_text`	`text`, `metadata`	Messages d’assistant (blocs de rapport). Les blocs de texte contiennent des `[N](url)` liens de citation. Les blocs de table portent `metadata` sur des données de résultat de requête structurées.
`reasoning_text`	`text`	Éléments de raisonnement.

ColumnInfo

L’objet ColumnInfo décrit une colonne :

Champ	Type	Description
`name`	`string`	Nom de la colonne.
`type`	`string`	Type de données de colonne, tel que `"STRING"`, `"DOUBLE"`ou `"BIGINT"`.

Gestion des erreurs

Les API retournent deux types d’erreurs : les erreurs HTTP avant le démarrage du flux et les erreurs de diffusion en continu qui terminent un flux ouvert.

Erreurs HTTP

Les erreurs HTTP sont retournées en tant que réponses JSON standard avant le démarrage du flux SSE :

{ "error": { "type": "ERROR_CODE", "message": "Human-readable description" } }

Les erreurs HTTP suivantes peuvent se produire :

État HTTP	Code d'erreur	Pathologie
`400`	`INVALID_PARAMETER_VALUE`	Un paramètre de chemin d’accès est manquant, les éléments d’entrée sont manquants ou non valides, ou la dernière entrée n’est pas un message utilisateur.
`404`	`FEATURE_DISABLED`	L’espace de travail n’est pas inscrit dans la préversion, ou un administrateur d’espace de travail n’a pas activé la préversion.
`403`	`PERMISSION_DENIED`	L’appelant ne dispose pas de l’autorisation CAN VIEW sur l’agent Genie.
`404`	`NOT_FOUND`	L’Agent génie ou la conversation n’existe pas.
`409`	`RESOURCE_CONFLICT`	Une réponse est déjà générée pour la conversation.
`500`	`INTERNAL_ERROR`	Une erreur de serveur inattendue s’est produite.

Codes d’erreur de streaming

Lorsqu’une défaillance se produit au milieu du flux, un message d’erreur système (role: "system", status: "failed") est émis sous response.output_item.addedla forme , suivi de l’événement response.failed . L’objet error sur l’objet Response porte un type et un code.

Le type champ est l’un des types de spécifications suivants :

`type`	Description
`server_error`	Une défaillance interne du serveur que le client n’a pas cause.
`invalid_request`	Une demande incorrecte ou sémantiquement non valide, ou un problème d’autorisation sur lequel l’utilisateur peut agir.
`not_found`	Une ressource référencée n’existe pas.
`model_error`	Le modèle n’a pas pu traiter une autre requête valide.
`too_many_requests`	La demande était soumise à une limitation de débit.

Le code champ fournit plus de détails :

`code`	`type`	Description
`internal_error`	`server_error`	Erreur inattendue du serveur. Le message est toujours `"An internal error occurred"`.
`sql_execution_error`	`server_error`	Une requête SQL n’a pas pu s’exécuter.
`upstream_unavailable`	`server_error`	Une dépendance en amont est temporairement indisponible.
`timeout`	`server_error`	La requête ou un appel en amont a expiré.
`model_unavailable`	`model_error`	Le modèle n’est pas disponible temporairement.
`context_length_exceeded`	`model_error`	L’historique des conversations a dépassé la fenêtre de contexte du modèle.
`content_filtered`	`model_error`	Un filtre de contenu a bloqué la réponse.
`rate_limit_exceeded`	`too_many_requests`	Trop de requêtes simultanées ou une limite de débit en amont a été atteinte.
`budget_exceeded`	`too_many_requests`	L’espace de travail a dépassé son budget d’utilisation pour le mode Agent.
`warehouse_access_denied`	`invalid_request`	L’appelant n’est pas autorisé à utiliser l’entrepôt SQL configuré.
`no_tables_available`	`invalid_request`	Aucune table interrogeable n’est disponible dans l’agent Genie.
`invalid_request`	`invalid_request`	La requête a été incorrecte ou manquante.
`permission_denied`	`invalid_request`	L’appelant a perdu l’autorisation ou la délégation a échoué pendant l’exécution.
`conflict`	`invalid_request`	Une opération simultanée est en conflit avec la requête.
`warehouse_not_found`	`not_found`	L’entrepôt SQL configuré n’existe pas ou a été supprimé.
`not_found`	`not_found`	Une ressource référencée n’a pas été trouvée pendant l’exécution.

Questions fréquemment posées

Les questions suivantes traitent des rubriques courantes pour les API en mode Agent.

Combien de temps les réponses prennent-ils ?

Le temps de réponse dépend de la complexité de la question. Les questions à requête unique peuvent se terminer en moins d’une minute. La recherche à plusieurs requêtes peut prendre plusieurs minutes. Le flux a un délai d’expiration côté serveur de 90 minutes.

Puis-je interroger au lieu de diffuser en continu ?

Yes. Envoyez la requête pour créer une réponse, puis utilisez l’ID de conversation de l’événement response.created pour récupérer les éléments de conversation. Le point de terminaison d’éléments retourne l’historique complet des conversations, y compris les réponses en cours. Interrogez le champ de niveau status supérieur sur la réponse de liste d’éléments jusqu’à ce qu’elle soit completed ou failed.

Comment fonctionne une conversation multitour ?

Transmettez l’ID de conversation d’une réponse précédente dans votre requête suivante. L’agent a accès à toutes les requêtes et résultats précédents dans la conversation et peut les référencer dans le rapport.

Le format de sortie markdown est-il stable ?

Le contenu texte, y compris les blocs de rapport, le texte de raisonnement et la sortie du résultat de la requête, est retourné dans markdown. La structure markdown exacte, telle que les niveaux de titre et la mise en forme de table, est générée par le modèle et n’est pas garantie d’être stable entre les requêtes ou les versions d’API. Traitez la sortie markdown comme du texte mis en forme le mieux effort et utilisez les champs structurés, tels que les colonnes et les lignes d’aperçu, comme la représentation stable et lisible par l’ordinateur des données.

Puis-je récupérer des visualisations ?

Yes. Récupérer des visualisations avec le point de terminaison de visualisation de la pièce jointe de téléchargement. Consultez GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-result/visualization la référence de l’API REST.

Les résultats des requêtes expirent-ils ?

Yes. Les résultats de la requête SQL suivent la même stratégie d’expiration que l’API d’exécution d’instruction. Une fois les résultats expirés, l’ID d’instruction ne les retourne plus. Les lignes d’aperçu des métadonnées de réponse restent disponibles à partir du point de terminaison des éléments de conversation.

Comment savoir quelles tables l’agent peut interroger ?

L’agent ne peut interroger que des tables que vous ajoutez à l’agent Genie. Il ne peut pas accéder à votre catalogue complet. Pour obtenir les meilleurs résultats, ajoutez des descriptions de colonne, des exemples de requêtes et des instructions de jointure. Consultez Curate un agent Génie efficace.

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2026-07-24

API en mode Agent dans Les agents Genie

Fonctionnement des API en mode Agent

Exigences

Get started

Envoyer votre première invite avec curl

Lire le flux avec le client Databricks OpenAI (Python)

Envoyer une invite de suivi

Référence d’API

URL de base

Endpoints

Créer une réponse

Paramètres de chemin d’accès

Corps de la demande

Cycle de vie des événements SSE

Types d’événements SSE

Concurrency

Délais d’expiration

Répertorier les éléments de conversation

Paramètres de chemin d’accès

Paramètres de la requête

Exemples de requêtes

Response

Pagination

Comprendre la réponse

Flux d’élément de sortie

Comment function_call et function_call_output paire

Analyser le rapport

Références

Modèles de données

Response

Informations sur l'erreur

Éléments de sortie

Éléments de contenu

ColumnInfo

Gestion des erreurs

Erreurs HTTP

Codes d’erreur de streaming

Questions fréquemment posées

Combien de temps les réponses prennent-ils ?

Puis-je interroger au lieu de diffuser en continu ?

Comment fonctionne une conversation multitour ?

Le format de sortie markdown est-il stable ?

Puis-je récupérer des visualisations ?

Les résultats des requêtes expirent-ils ?

Comment savoir quelles tables l’agent peut interroger ?

Commentaires

Ressources supplémentaires