APIs en mode Agent dans les Agents Genie
Les APIs du mode Agent vous permettent d'exécuter le mode Agent par programmation plutôt que via l'interface utilisateur de Databricks. Utilisez-les pour intégrer le mode Agent dans vos propres applications, tels que les chatbots, les rapports planifiés et les outils internes.
Bêta
Les APIs en mode Agent des agents Genie sont en version bêta.
Le mode Agent était anciennement appelé Research Agent. Les Agents Genie étaient anciennement appelés Genie Spaces.
Fonctionnement des APIs du mode Agent
Avec les APIs en mode Agent, vous envoyez une question en langage naturel à un Genie Agent. Il crée et affine un plan de recherche, exécute des requêtes SQL, itère en fonction de chaque résultat et renvoie un rapport avec des citations et des tableaux justificatifs. Les résultats stream vers votre client sous forme d'événements envoyés par le serveur (SSE).
Les APIs couvrent les endpoints, les formats de requête et de réponse, ainsi que les types d'événements de streaming nécessaires pour communiquer directement avec le mode Agent. Pour un aperçu conceptuel, consultez le mode Agent. Pour l'expérience de l'interface utilisateur, consultez Utiliser le mode Agent.
Exigences
Pour utiliser les APIs du mode Agent, votre workspace doit répondre aux exigences suivantes :
- Unity Catalog est activé. Voir Qu'est-ce que Unity Catalog ?
- Les fonctionnalités d’IA optimisées par des partenaires sont activées. Voir les fonctionnalités d’IA optimisées par des partenaires.
- Vous disposez d'un Genie Agent avec des instructions claires et des métadonnées de table. Le mode Agent s'appuie sur ce contexte pour raisonner sur vos données. Veuillez consulter Curate an effective Genie Agent.
Pour activer les APIs pour votre workspace, contactez votre équipe de compte Databricks avec les IDs des workspaces où vous souhaitez la fonctionnalité. Une fois la demande approuvée, un administrateur de workspace active l' API du Mode Agent des Agents Genie à partir du menu Aperçus .
Get start
Les exemples suivants montrent comment envoyer une invite et lire la réponse Stream.
Envoyez votre première invite avec curl
La requête suivante envoie une question en langage naturel à un Genie Agent et diffuse la réponse sous forme de 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 sous forme de paires event: et 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}}
Lisez le Stream 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 un message de suivi.
Pour poursuivre une conversation, transmettez le conversation_id de la 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 faire référence à des query et des résultats antérieurs.
Référence de l'API
Les APIs en mode Agent couvrent les Endpoint disponibles, les formats de requête 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 Endpoint sont relatifs à l'URL de base suivante :
https://<workspace-url>/api/2.0/genie/agents
Le agent_id dans chaque chemin d'accès est l'ID du Genie Agent, le même identifiant hexadécimal de 32 caractères qui apparaît dans l'URL du Genie Agent.
Endpoint
Les APIs fournissent les Endpoint suivants :
Méthode | Chemin d'accès | Description |
|---|---|---|
|
| Créer une réponse en tant que Stream SSE. |
|
| Lister tous les éléments d'une conversation. |
Créer une réponse
Crée une nouvelle réponse en mode Agent. Renvoie un SSE Stream qui fournit des éléments de sortie en temps réel lorsque le mode Agent est en cours d'exécution.
POST /{agent_id}/responses
Paramètres de chemin
L'endpoint accepte le paramètre de chemin suivant :
parameter | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | L'ID du Genie Agent. Une chaîne hexadécimale en minuscules de 32 caractères. |
Corps de la requête
Le corps de la requête accepte les champs suivants :
Champ | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
|
| Oui | Aucun | Les éléments d'entrée. Le tableau doit contenir exactement un élément |
|
| Non |
| L'ID d'une conversation existante à poursuivre. Lorsqu'elle est omise, une nouvelle conversation est créée. |
|
| Non |
| Lorsque vrai, Genie peut générer des visualisations. Genie générera des visualisations le cas échéant, et toutes les réponses n'incluront pas nécessairement des visualisations. |
Cycle de vie des événements SSE
Le Stream s’ouvre avec un événement response.created, transmet les é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 est associé à un sequence_number qui augmente de manière monotone que vous pouvez utiliser pour le classement.
Types d’événements SSE
Le stream émet les types d'événements suivants.
response.created
Émis une fois au start. Contient un objet Response avec status: "in_progress" et un tableau output vide.
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 pour la première fois. L’élément peut encore ê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 lorsqu'un élément existant est modifié, par exemple lorsque des résultats de query 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 la charge utile que response.output_item.added. Si un élément arrive déjà terminé, les événements added et done sont émis en séquence.
response.completed
Événement de réussite du terminal. Encapsule le Response final 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 terminal. Response a status: "failed" et un objet error. Un élément de message d'erreur système est émis en tant que response.output_item.added immédiatement avant cet événement. Pour la liste complète des codes, consultez 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
}
}
Simultanéité
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 renvoie un HTTP 409 :
HTTP 409
{"error": {"type": "RESOURCE_CONFLICT", "message": "A response is already being generated for conversation <id>"}}
Délais d'expiration
Le Stream SSE a un délai d'expiration côté serveur de 90 minutes. Étant donné que le mode Agent exécute un raisonnement multi-étapes et l'exécution SQL, maintenez votre connexion HTTP ouverte pendant toute la durée.
Liste des é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, y compris les messages utilisateur, le raisonnement, les queries, les résultats et les rapports. Cet Endpoint prend en charge la pagination basée sur le curseur via les after et limit paramètres de query.
GET /{agent_id}/conversations/{conversation_id}/items
Utiliser cet Endpoint :
- Affichez l’historique complet de la conversation dans votre application.
- Récupérez les résultats après la déconnexion d'un Stream SSE. Appeler cet endpoint une fois la réponse terminée.
- Récupérez les grandes conversations progressivement au lieu de charger tous les éléments en une seule fois.
Paramètres de chemin
L’endpoint accepte les paramètres de chemin suivants :
parameter | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | L'ID du Genie Agent. Une chaîne hexadécimale en minuscules de 32 caractères. |
|
| Oui | L'ID de la conversation. |
Paramètres de query
L'Endpoint accepte les query parameters suivants :
parameter | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
|
| Non | 100 | Le nombre maximal d'éléments à renvoyer. Plage : de 1 à 100. |
|
| Non | Aucun | Le curseur de pagination. Transmettez |
|
| Non |
| L'ordre de tri. Utilisez |
Exemples de requêtes
Récupérer tous les éléments d'une conversation :
GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items
Limiter la taille de la page :
GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items?limit=5
Renvoie les éléments les plus récents en premier :
GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items?order=desc&limit=5
Récupérer la page suivante :
GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items?limit=5&after=01f14fe4f24e10beacaa1720d4b79b59_output
Réponse
La réponse contient Content-Type: application/json et est une enveloppe de liste paginée 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 status de premier niveau reflète l'état de la dernière réponse dans la conversation. Il est "in_progress" pendant qu'une réponse est en streaming, et "completed" ou "failed" après qu'elle se termine. Interrogez ce champ pour détecter quand une réponse est terminée.
Pagination
La réponse inclut trois champs de pagination :
Champ | Type | Description |
|---|---|---|
|
| L'ID du premier élément de la page actuelle. Absent lorsque |
|
| L'ID du dernier élément de la page actuelle. Transmettez-le en tant que |
|
|
|
Pour paginer tous les éléments, demandez des pages jusqu'à ce que has_more soit 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 tableau data contient des éléments de sortie par ordre chronologique. Les messages d'entrée utilisateur apparaissent sous forme de message éléments avec un suffixe _input sur l'ID.
Comprenez la réponse
Cette section explique comment les éléments de sortie s’assemblent pour former une réponse complète en mode Agent.
Flux d'éléments de sortie
Une réponse typique du mode Agent 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 query en séquence, en affinant son analyse en fonction de chaque résultat. Une seule réponse peut contenir de nombreux cycles de raisonnement, de query et de résultat avant le rapport final.
Fonctionnement de la paire function_call et function_call_output
Chaque query SQL produit une paire d'éléments de sortie liés par call_id:
function_callis the query the agent runs. Le champargumentsest une chaîne encodée en JSON qui décrit l'invocation de l'outil.function_call_outputest le résultat. Une fois l'élément terminé, le champoutputcontient le titre de la query suivi d'un tableau markdown des données.
Le call_id est identique sur les deux éléments. Le function_call_output.id est toujours {call_id}_output.
Analyser le rapport
L’élément de sortie final est un message avec role: "assistant". Son tableau content contient plusieurs segments output_text de deux types :
- Les blocs de texte contiennent une analyse narrative avec des Link de citation en ligne.
- Les morceaux de tableau contiennent les résultats de query en ligne rendus sous forme de tableaux Markdown. Chaque fragment de table contient
metadataavec les données de résultat de query structurées, afin que votre client puisse rendre des tables ou des graphiques riches par programmation.
Le bloc de tableau suivant inclut à la fois le Markdown rendu et le metadata structuré :
{
"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 segment de table metadata contient les champs suivants :
Champ | Type | Description |
|---|---|---|
|
| Les définitions de colonne. |
|
| Les lignes de résultat tronquées. |
|
| Le nombre total de lignes, lorsqu'il est connu. |
|
| Soit |
|
| La requête SQL qui a produit les résultats. |
Citations
Les blocs de texte dans le rapport contiennent des citations en ligne qui lient chaque affirmation à la query SQL qui la prend en charge. Chaque citation est un Link Markdown de la forme [N](url), où N est un numéro de note de bas de page séquentiel et url pointe vers l'interface utilisateur de Genie Agent avec la query pertinente ciblée.
L'URL de la 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 |
|---|---|
| L'ID Genie Agent, la même valeur que |
| La conversation qui contient la query citée. |
| L'identifiant numérique du workspace. |
| L'ID de pièce jointe de la requête, qui identifie le résultat spécifique de la requête SQL. |
Pour afficher les citations, suivez ces directives en fonction de votre client :
- Le rendu Markdown affiche automatiquement les citations sous forme de Link de notes de bas de page cliquables.
- Pour le texte brut, réduisez
[N](url)à[N]ou supprimez la citation. - Pour une interface utilisateur personnalisée, analysez le
gra_focusparamètre de requête de l'URL pour identifier la requête citée, puis comparez-le auxfunction_call_outputéléments de la conversation.
Les citations sont dédupliquées. Si la même query 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 que les APIs renvoient.
Réponse
L'objet Response est renvoyé dans les événements SSE response.created, response.completed et response.failed.
Champ | Type | Description |
|---|---|---|
|
| Toujours |
|
| L'ID de réponse unique. |
|
| Toujours |
|
| Soit |
|
| Les éléments de sortie produits par la réponse. |
|
| La conversation à laquelle appartient la réponse. |
|
| L'heure d'époque Unix en secondes lorsque la réponse a été créée. |
|
| Présent lorsque |
Informations d'erreur
L'objet ErrorInfo décrit un échec :
Champ | Type | Description |
|---|---|---|
|
| Un des éléments suivants : |
|
| Une description lisible par un humain. Pour les erreurs internes, il s'agit toujours de |
|
| Un code d'erreur facultatif avec plus de détails, comme |
Éléments de sortie
Les éléments de sortie sont polymorphes sur le champ type. Les types suivants sont disponibles.
reasoning
Le raisonnement interne de l'agent lorsque le mode Agent s'exécute.
Champ | Type | Description |
|---|---|---|
|
|
|
|
| L’ID d’article unique. |
|
| Soit |
|
| Contient |
|
| Toujours |
function_call
Une invocation d’outil, qui est une exécution de query SQL.
Champ | Type | Description |
|---|---|---|
|
|
|
|
| L’ID d’article unique. |
|
| L'ID de corrélation qui Link le |
|
|
|
|
|
|
|
| Une chaîne JSON, par exemple |
function_call_output
Le résultat d'une invocation d'outil, associé à un function_call à travers call_id.
Champ | Type | Description |
|---|---|---|
|
|
|
|
| Toujours |
|
| Correspond au |
|
| Soit |
|
| Le résultat de la requête. Voir la table de cycle de vie suivante. |
Le champ output évolue à mesure que l'élément progresse :
Statut |
|
|---|---|
| Le titre de la query uniquement. |
| Le titre de la query, une ligne vide, puis le tableau de résultats markdown. |
Les données de résultats de query structurées, telles que les colonnes, les lignes et le SQL, sont disponibles sur les blocs de table du rapport, et non sur l'élément function_call_output. Consultez Analyser le rapport.
message
Un message texte. Un message s’affiche dans l’un des trois rôles suivants :
Rôle | Lorsque | Description |
|---|---|---|
| Entrée | La question de l'utilisateur. Apparaît dans |
| Rapport | Le rapport structuré final avec des morceaux de texte et de tableaux intégrés. |
| Erreur ou annulation | Émis lorsqu'une réponse échoue ou est annulée. |
L'objet message contient les champs suivants :
Champ | Type | Description |
|---|---|---|
|
|
|
|
| Soit |
|
| Le contenu du message. Consultez Analyser le rapport pour les messages de l'assistant. |
|
| L'identifiant unique de l'élément. Les messages système utilisent |
|
| Soit |
Lorsqu'une réponse échoue, l'erreur structurée est fournie sur le champ error de l'objet Response (voir ErrorInfo) et dans l'événement response.failed, et non sur l'élément message du système.
Éléments de contenu
Les APIs utilisent les types d'éléments de contenu suivants :
Type | Champs | Utilisé dans |
|---|---|---|
|
| Messages utilisateur (entrée). |
|
| Messages de l'assistant (segments de rapport). Les segments de texte contiennent |
|
| Éléments de raisonnement. |
Informations sur les colonnes
L'objet ColumnInfo décrit une colonne :
Champ | Type | Description |
|---|---|---|
|
| Le nom de la colonne. |
|
| Le type de données de colonne, tel que |
Gestion des erreurs
Les APIs renvoient deux types d’erreurs : les erreurs HTTP avant le start du Stream, et les erreurs de streaming qui mettent fin à un Stream ouvert.
Erreurs HTTP
Les erreurs HTTP sont renvoyées en tant que réponses JSON standard avant le démarrage du Stream SSE :
{ "error": { "type": "ERROR_CODE", "message": "Human-readable description" } }
Les erreurs HTTP suivantes peuvent se produire :
Statut HTTP | Code d'erreur | État |
|---|---|---|
|
| Un paramètre de chemin 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. |
|
| Le Workspace n'est pas inscrit à l'aperçu, ou un administrateur du Workspace n'a pas activé l'aperçu. |
|
| L'appelant n'a pas la permission CAN VIEW sur le Genie Agent. |
|
| L’agent Genie ou la conversation n’existe pas. |
|
| Une réponse est déjà en cours de génération pour la conversation. |
|
| Une erreur de serveur inattendue s'est produite. |
Codes d'erreur de streaming
Lorsqu'une défaillance se produit en cours de Stream, un message d'erreur système (role: "system", status: "failed") est émis en tant que response.output_item.added, suivi de l'événement response.failed. L'objet error sur le Response porte un type et un code.
Le champ type est l'un des types de spécification suivants :
| Description |
|---|---|
| Une défaillance interne du serveur que le client n’a pas provoquée. |
| Une requête mal formée ou sémantiquement invalide, ou un problème de permissions sur lequel l'utilisateur peut agir. |
| Une ressource référencée n'existe pas. |
| Le modèle n'a pas pu traiter une demande par ailleurs valide. |
| La requête a été limitée en débit. |
Le champ code fournit plus de détails :
|
| Description |
|---|---|---|
|
| Une erreur inattendue du serveur. Le message est toujours |
|
| Une query SQL n'a pas pu être exécutée. |
|
| Une dépendance en amont est temporairement indisponible. |
|
| La demande ou un appel en amont a expiré. |
|
| Le modèle est temporairement indisponible. |
|
| L'historique de la conversation a dépassé la fenêtre contextuelle du modèle. |
|
| Un filtre de contenu a bloqué la réponse. |
|
| Trop de requêtes simultanées, ou une limite de débit en amont a été atteinte. |
|
| Le Workspace a dépassé son budget d'utilisation pour le mode Agent. |
|
| L'appelant ne dispose pas de l'autorisation d'utiliser le SQL Warehouse configuré. |
|
| Aucune table interrogeable n'est disponible dans le Genie Agent. |
|
| La requête était mal formée ou des champs obligatoires étaient manquants. |
|
| L'appelant a perdu l'autorisation ou la délégation a échoué pendant l'exécution. |
|
| Une opération concurrente est entrée en conflit avec la requête. |
|
| Le SQL Warehouse configuré n'existe pas ou a été supprimé. |
|
| Une ressource référencée n'a pas été trouvée lors de l'exécution. |
Questions fréquemment posées
Les questions suivantes couvrent les sujets courants pour les APIs du mode Agent.
Combien de temps les réponses prennent-elles ?
Le temps de réponse dépend de la complexité de la question. Les questions à requête unique peuvent être terminées en moins d'une minute. La recherche multi-requêtes peut prendre plusieurs minutes. Le Stream a un délai d'expiration côté serveur de 90 minutes.
Puis-je interroger au lieu de streaming ?
Oui. 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. L’Endpoint des éléments renvoie l’historique complet de la conversation, y compris les réponses en cours. Interrogez le champ status de niveau supérieur de la réponse de la liste d'éléments jusqu'à ce qu'il soit completed ou failed.
Comment fonctionne une conversation multi-tours ?
Transmettez l'ID de conversation d'une réponse précédente dans votre prochaine requête. L'agent a accès à toutes les queries et tous les résultats précédents de la conversation, et peut les référencer dans le rapport.
Le format de sortie Markdown est-il stable ?
Le contenu textuel, y compris les fragments de rapport, le texte de raisonnement et la sortie des résultats de query, est renvoyé en markdown. La structure Markdown exacte, telle que les niveaux de titre et la mise en forme des tableaux, 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 un texte formaté au mieux de nos capacités, et utilisez les champs structurés, tels que les colonnes et les lignes d'aperçu, comme représentation stable et lisible par machine des données.
Puis-je récupérer les visualisations ?
Oui. Récupérez les visualisations avec le Endpoint de visualisation des pièces jointes de message de download. Voir GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-result/visualization dans la référence de l’API REST.
Les résultats de la requête expirent-ils ?
Oui. Les résultats des query SQL suivent la même politique d'expiration que l'API d'exécution de déclaration. Une fois les résultats expirés, l'identifiant de l'instruction ne les renvoie plus. Les lignes d'aperçu dans les métadonnées de la réponse restent disponibles à partir de l'endpoint d'éléments de conversation.
Comment savoir quelles tables l'agent peut query ?
L'agent peut seulement query les tables que vous ajoutez au Genie Agent. Il ne peut pas accéder à l'intégralité de votre catalogue. Pour de meilleurs résultats, ajoutez des descriptions de colonnes, des exemples de queries et des instructions de jointure. Voir Élaborer un Genie Agent efficace.