enterprise_ai.rag_agent

Source : sdks/python/src/enterprise_ai/rag_agent/__init__.py. Retour à l'index de la référence du SDK Python.

remarque

Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.

Classe RagAgentClient

Instances de l'agent RAG. Activation et cycle de vie des instances du Navin Enterprise RAG Agent. Le Control Plane porte l'enregistrement d'activation de chaque instance (son statut, son modèle de déploiement, ses versions et les ressources qu'elle possède), car dans le modèle dédié le runtime du RAG n'existe pas encore au moment de l'activation. Le runtime du RAG lit son activation avec GET /v1/rag-agent/instances/{instance_id} et refuse de servir des conversations tant que le statut n'est pas ready ou degraded (instance_not_ready).

Resource

RagAgentClient.backup

backup(instance_id: str) -> Any

Sauvegarder une instance (non pris en charge). Répond 501 rag_agent_backup_not_supported avec parts et la raison de chacune : le runtime du RAG n'a pas de route d'administration pour exporter les lignes du schéma rag d'une instance, le domaine des connaissances n'a pas d'export de base de connaissances. Rien n'est simulé ; le refus est audité.

Route : /v1/rag-agent/instances/{instance_id}/backup (POST).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.

Retour : Any. Réponse JSON décodée de l'opération « Sauvegarder une instance (non pris en charge) ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.create

create(name: str, project: str, deployment_model: str, generation_model: str, embedding_model: str, id: str | None = None, description: str | None = None, organization_id: str | None = None, business_unit_id: str | None = None, version: str | None = None) -> Any

Créer une instance brouillon de l'agent RAG. Crée l'enregistrement d'activation en draft (201) avec son id immuable (fourni, par exemple l'identifiant choisi par le runtime du RAG, ou généré). Demande un administrateur du tenant ou un propriétaire du projet (403 forbidden) ; projet inconnu : 404 rag_agent_project_not_found ; un nom ou un identifiant déjà pris : 409 conflict. Avec Idempotency-Key, une nouvelle tentative rejoue la première réponse. Audité sous rag_agent.create.

Route : /v1/rag-agent/instances (POST).

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom, unique dans le tenant : minuscules, chiffres et -, 1 à 63 caractères.
project	str		oui	Projet de l'instance (identifiant ou slug) ; l'appelant doit en être propriétaire ou être administrateur du tenant.
deployment_model	str		oui	shared (le runtime partagé existant) ou dedicated (un runtime installé par le Navin Manager).
generation_model	str		oui	Modèle de génération du registre (capacité chat).
embedding_model	str		oui	Modèle d'embeddings du registre (capacité embeddings), utilisé par la base de connaissances de l'instance.
id	str | None	None	non	Identifiant immuable (UUID) de l'instance ; généré s'il est absent.
description	str | None	None	non	Description libre (2000 caractères au plus).
organization_id	str | None	None	non	Organisation de l'instance (UUID), contrôlée à la validation.
business_unit_id	str | None	None	non	Unité métier de l'instance (UUID), contrôlée à la validation.
version	str | None	None	non	Version à déployer ; par défaut : la version que le runtime annonce à l'étape smoke.

Retour : Any. Réponse JSON décodée de l'opération « Créer une instance brouillon de l'agent RAG ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.delete

delete(instance_id: str) -> Any

Supprimer une instance. Opération longue (202, statut deleting puis deleted) depuis draft, stopped ou failed (une instance prête est d'abord arrêtée, sinon 409). Ne supprime que ce que l'instance possède, tel qu'enregistré dans resources : sa base de connaissances et ses points Qdrant, les objets sous son préfixe de stockage, les mémoires et la politique de mémoire de son agent, ses tuples, sa clé d'API et son secret, son agent ; l'application gouvernée est retirée. Le runtime partagé, une base de données partagée, la collection Qdrant partagée par les bases du tenant et le profil de stockage sont conservés. Chaque étape liste deleted et kept. Audité sous rag_agent.delete et rag_agent.delete.completed.

Route : /v1/rag-agent/instances/{instance_id} (DELETE).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.

Retour : Any. Réponse JSON décodée de l'opération « Supprimer une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.delete_logo

delete_logo(instance_id: str) -> Any

Retirer le logo d'une instance. Retour au logo par défaut du runtime : l'image de marque ne pointe plus vers un objet, version est incrémentée et l'objet stocké est supprimé. Sans logo, renvoie l'image de marque inchangée. Mêmes droits que le PUT ; audité sous rag_agent.branding.logo.remove.

Route : /v1/rag-agent/instances/{instance_id}/branding/logo (DELETE).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.

Retour : Any. Réponse JSON décodée de l'opération « Retirer le logo d'une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.get

get(instance_id: str) -> Any

Lire une instance de l'agent RAG. L'enregistrement d'activation avec serving (vrai pour ready et degraded), l'operation et le run courants, validation, last_error et les steps de l'exécution courante dans l'ordre (état, tentatives, détail, journaux, horaires). C'est la route que le runtime du RAG lit au démarrage et à la demande.

Route : /v1/rag-agent/instances/{instance_id} (GET).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance, le même dans le Control Plane et dans le runtime du RAG.

Retour : Any. Réponse JSON décodée de l'opération « Lire une instance de l'agent RAG ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.get_branding

get_branding(instance_id: str) -> Any

Lire l'image de marque d'une instance. L'image de marque choisie dans le parcours d'activation, portée par le Control Plane : agent_name, sidebar_color, navbar_color, les couleurs de texte calculées pour elles (sidebar_text_color, navbar_text_color, noir ou blanc, contraste de 4,5:1 ou plus), logo (content_type, sha256, size_bytes, url) ou null, version, updated_at, et app_url (l'URL de l'application web une fois connue). Un champ null signifie la valeur par défaut du runtime. Le runtime du RAG en garde une réplique pour sa page de connexion publique et la réécrit quand version est plus récente. Tout principal du tenant ; l'instance d'un autre tenant répond 404.

Route : /v1/rag-agent/instances/{instance_id}/branding (GET).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.

Retour : Any. Réponse JSON décodée de l'opération « Lire l'image de marque d'une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.get_logo

get_logo(instance_id: str) -> Any

Lire le logo d'une instance. Les octets du logo, lus par le domaine de stockage et contrôlés avec le sha256 enregistré, avec le Content-Type du format validé (image/png ou image/jpeg), X-Content-Type-Options: nosniff, une Content-Security-Policy commençant par default-src 'none' et un ETag. 404 rag_agent_logo_not_found quand l'instance n'a pas de logo. Tout principal du tenant.

Route : /v1/rag-agent/instances/{instance_id}/branding/logo (GET).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.

Retour : Any. Réponse JSON décodée de l'opération « Lire le logo d'une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.health

health(instance_id: str) -> Any

Santé d'une instance. Contrôles réels : URL de disponibilité du runtime (GET /readyz), base de connaissances (ligne, vector store qdrant, /readyz de Qdrant) et passerelle de modèles (modèles de génération et d'embeddings dans le registre, utilisables). status vaut up, degraded ou down (runtime hors service) ; instance_status est le statut du cycle de vie. Chaque contrôle a status, duration_ms et reason quand il n'est pas up.

Route : /v1/rag-agent/instances/{instance_id}/health (GET).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.

Retour : Any. Réponse JSON décodée de l'opération « Santé d'une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.list

list(status: str | None = None, project: str | None = None, limit: int | None = None) -> Any

Lister les instances de l'agent RAG. Enregistrements d'activation du tenant, du plus récent au plus ancien, avec statut, modèle de déploiement, versions et ressources possédées (une page, next_cursor nul). Filtres : status, project.

Route : /v1/rag-agent/instances (GET).

Nom	Type	Défaut	Requis	Description
status	str | None	None	non	Seulement les instances dans ce statut (draft, ready, failed, ...).
project	str | None	None	non	Seulement les instances de ce projet (identifiant).
limit	int | None	None	non	Nombre maximal d'instances renvoyées (1 à 200, 50 par défaut).

Retour : Any. Réponse JSON décodée de l'opération « Lister les instances de l'agent RAG ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.provision

provision(instance_id: str) -> Any

Provisionner une instance. Opération longue (202, Operation-Id) : statut provisioning puis starting, étapes de validation à activation exécutées par le worker. Depuis un draft validé (sinon 409 rag_agent_not_validated) ou après un provisionnement en échec, qui reprend à l'étape en échec. Répété pendant le provisionnement ou une fois prête : changed: false. Audité sous rag_agent.provision, chaque étape sous rag_agent.step.

Route : /v1/rag-agent/instances/{instance_id}/provision (POST).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.

Retour : Any. Réponse JSON décodée de l'opération « Provisionner une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.restart

restart(instance_id: str) -> Any

Redémarrer une instance. Opération longue (202) : depuis ready, degraded, stopped ou après un redémarrage en échec, étapes deployment (redémarrage par le Navin Manager pour une instance dédiée), health, smoke, activation. Un redémarrage en cours : changed: false.

Route : /v1/rag-agent/instances/{instance_id}/restart (POST).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.

Retour : Any. Réponse JSON décodée de l'opération « Redémarrer une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.restore

restore(instance_id: str, backup_id: str) -> Any

Restaurer une instance (non pris en charge). Répond 501 rag_agent_backup_not_supported avec les mêmes parts que la sauvegarde : aucune sauvegarde d'instance ne peut encore être faite réellement. Audité.

Route : /v1/rag-agent/instances/{instance_id}/restore (POST).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.
backup_id	str		oui	Identifiant de la sauvegarde à restaurer.

Retour : Any. Réponse JSON décodée de l'opération « Restaurer une instance (non pris en charge) ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.start

start(instance_id: str) -> Any

Démarrer une instance. Opération longue (202) : depuis stopped (ou après un démarrage ou un arrêt en échec), étapes deployment (démarrage par le Navin Manager pour une instance dédiée, statut seulement pour une partagée), health, smoke, activation (application gouvernée active). Déjà en démarrage ou prête : changed: false.

Route : /v1/rag-agent/instances/{instance_id}/start (POST).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.

Retour : Any. Réponse JSON décodée de l'opération « Démarrer une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.stop

stop(instance_id: str) -> Any

Arrêter une instance. Opération longue (202) : depuis ready, degraded ou après un démarrage, un redémarrage, une mise à niveau ou un arrêt en échec, étapes deployment (arrêt par le Navin Manager pour une instance dédiée, statut seulement pour une partagée) et activation (application gouvernée suspendue, raison rag_instance_stopped) ; statut stopped. Déjà en arrêt ou arrêtée : changed: false.

Route : /v1/rag-agent/instances/{instance_id}/stop (POST).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.

Retour : Any. Réponse JSON décodée de l'opération « Arrêter une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.update_branding

update_branding(instance_id: str, agent_name: string | null = _UNSET, sidebar_color: string | null = _UNSET, navbar_color: string | null = _UNSET, app_url: string | null = _UNSET, expected_version: int | None = None, idempotency_key: str | None = None) -> Any

Modifier l'image de marque d'une instance. Écrit les champs fournis (un champ absent est conservé, null le ramène à la valeur par défaut du runtime) et renvoie l'image de marque. Les couleurs sont au format #RRGGBB (enregistrées en majuscules) ; le texte affiché dessus est noir ou blanc, selon le meilleur contraste (luminance relative WCAG 2.2, la règle du frontend du RAG), et une couleur dont le texte resterait sous 4,5:1 répond 422 rag_agent_branding_contrast. app_url doit être une URL https sans identifiants (422 rag_agent_app_url_invalid). Un changement du nom, des couleurs ou du logo incrémente version ; un expected_version différent de la version courante répond 409 rag_agent_branding_version_conflict. Avec une Idempotency-Key, une nouvelle tentative avec le même corps rejoue la première réponse (Idempotency-Replayed: true), un autre corps répond 409 idempotency_conflict. Demande un administrateur du tenant ou un propriétaire du projet (403 forbidden) ; refusé quand l'instance est deleting ou deleted (409). Audité sous rag_agent.branding.update.

Route : /v1/rag-agent/instances/{instance_id}/branding (PUT).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.
agent_name	string | null	_UNSET	non	Nom de l'agent affiché aux utilisateurs, 1 à 80 caractères, sans <, > ni caractère de contrôle.
sidebar_color	string | null	_UNSET	non	Couleur de la barre latérale, #RRGGBB ; le texte dessus est noir ou blanc avec un contraste de 4,5:1 ou plus.
navbar_color	string | null	_UNSET	non	Couleur de la barre supérieure, #RRGGBB ; le texte dessus est noir ou blanc avec un contraste de 4,5:1 ou plus.
app_url	string | null	_UNSET	non	URL de l'application web de l'instance une fois connue, https uniquement, sans identifiants (2048 caractères au plus).
expected_version	int | None	None	non	Version de l'image de marque sur laquelle porte la modification ; une autre version courante répond 409 rag_agent_branding_version_conflict.
idempotency_key	str | None	None	non	En-tête Idempotency-Key : une reprise avec la même clé rejoue la première réponse.

Retour : Any. Réponse JSON décodée de l'opération « Modifier l'image de marque d'une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.upgrade

upgrade(instance_id: str, version: str) -> Any

Mettre à niveau une instance. Opération longue (202), statut updating : une instance partagée suit le runtime partagé, donc l'étape de déploiement vérifie que le runtime exécute la version demandée (sinon shared_runtime_version_mismatch) ; une instance dédiée est réinstallée par le Navin Manager. Puis health, smoke, activation ; deployed_version devient la version. La même version déjà déployée ou en cours : changed: false.

Route : /v1/rag-agent/instances/{instance_id}/upgrade (POST).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.
version	str		oui	Version à déployer (lettres, chiffres, ., _, +, -, 64 caractères au plus).

Retour : Any. Réponse JSON décodée de l'opération « Mettre à niveau une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.upload_logo

upload_logo(instance_id: str, data: bytes, filename: str, mime_type: str) -> Any

Téléverser le logo d'une instance. Multipart file (avec les champs texte facultatifs filename et mime_type). PNG ou JPEG uniquement : le SVG et tout autre format sont refusés. La signature réelle, le Content-Type déclaré et l'extension du fichier doivent concorder ; 32 à 1024 pixels de côté, 512 Kio au plus ; sinon 422 rag_agent_logo_invalid avec details.reason (format_not_allowed, signature_invalid, signature_mismatch, extension_mismatch, dimensions_out_of_bounds, too_large, empty). Le fichier est ensuite analysé par le domaine de sécurité des fichiers, en échec fermé : un fichier bloqué répond 422 file_blocked, un analyseur indisponible 503 file_scan_unavailable. Il est stocké par le domaine de stockage dans le profil de stockage des documents du tenant sous rag-agent/<tenant>/<instance>/branding/ (409 rag_agent_branding_storage_required sans un tel profil, 503 rag_agent_branding_storage_unavailable quand il est injoignable) ; l'objet remplacé est supprimé. Incrémente version et renvoie l'image de marque. Mêmes droits que le PUT ; audité sous rag_agent.branding.logo.update (un refus est audité comme refus).

Route : /v1/rag-agent/instances/{instance_id}/branding/logo (POST).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.
data	bytes		oui	Formulaire multipart avec le logo dans la partie file.
filename	str		oui	Nom du fichier du logo ; son extension doit correspondre au format réel (.png, .jpg ou .jpeg).
mime_type	str		oui	Type de média du contenu, par exemple application/pdf ou image/png.

Retour : Any. Réponse JSON décodée de l'opération « Téléverser le logo d'une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).

RagAgentClient.validate

validate(instance_id: str) -> Any

Valider une instance. Contrôles réels avant le provisionnement : le projet existe et l'appelant peut l'administrer, le modèle de génération existe dans le registre avec la capacité chat et un statut utilisable, le modèle d'embeddings se résout dans la Model Gateway (capacité embeddings), le quota d'instances, Qdrant répond, le runtime partagé répond (modèle partagé) ou le Navin Manager répond (modèle dédié, un service du catalogue non publié est un avertissement). Depuis draft ou après une validation en échec. 200 avec validation et le statut draft ; 422 rag_agent_validation_failed avec les contrôles en échec (statut failed, étape validation). Audité sous rag_agent.validate et rag_agent.validate.completed.

Route : /v1/rag-agent/instances/{instance_id}/validate (POST).

Nom	Type	Défaut	Requis	Description
instance_id	str		oui	Identifiant (UUID) de l'instance.

Retour : Any. Réponse JSON décodée de l'opération « Valider une instance ».

Erreurs levées : les erreurs typées du transport (Erreurs).