enterprise_ai.rag_agent

Source: sdks/python/src/enterprise_ai/rag_agent/__init__.py. Back to the Python SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Class RagAgentClient

/v1/rag-agent/instances.

Resource

RagAgentClient.backup

backup(instance_id: str) -> Any

Back up an instance (not supported). Answers 501 rag_agent_backup_not_supported with parts and the reason of each one: the RAG runtime has no admin route to export the rag schema rows of an instance, the knowledge domain has no export of a knowledge base. Nothing is pretended; the refusal is audited.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.

Returns: Any. Decoded JSON answer of the operation "Back up an instance (not supported)".

Raises: the typed errors of the transport (Errors).

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

Create a draft RAG Agent instance. Creates the activation record in draft (201) with its immutable id (given, for example the id chosen by the RAG runtime, or generated). Needs a tenant administrator or an owner of the project (403 forbidden); unknown project: 404 rag_agent_project_not_found; a name or an id already used: 409 conflict. With Idempotency-Key a retry replays the first answer. Audited as rag_agent.create.

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

Name	Type	Default	Required	Description
name	str		yes	Name, unique in the tenant: lowercase letters, digits and -, 1 to 63 characters.
project	str		yes	Project of the instance (identifier or slug); the caller must be a tenant administrator or an owner of it.
deployment_model	str		yes	shared (the existing shared runtime) or dedicated (a runtime installed by the Navin Manager).
generation_model	str		yes	Generation model of the registry (capability chat).
embedding_model	str		yes	Embedding model of the registry (capability embeddings), used by the knowledge base of the instance.
id	str | None	None	no	Immutable identifier (UUID) of the instance; generated when absent.
description	str | None	None	no	Free description (up to 2000 characters).
organization_id	str | None	None	no	Organization of the instance (UUID), checked at validation.
business_unit_id	str | None	None	no	Business unit of the instance (UUID), checked at validation.
version	str | None	None	no	Version to deploy; default: the version the runtime reports at the smoke step.

Returns: Any. Decoded JSON answer of the operation "Create a draft RAG Agent instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.delete

delete(instance_id: str) -> Any

Delete an instance. Long operation (202, status deleting then deleted) from draft, stopped or failed (a ready instance is stopped first, else 409). Removes only what the instance owns, as recorded in resources: its knowledge base and its Qdrant points, the objects under its storage prefix, its agent memories and memory policy, its tuples, API key and secret, its agent; the governed application is retired. The shared runtime, a shared database, the Qdrant collection shared by the tenant knowledge bases and the storage profile are kept. Each step lists deleted and kept. Audited as rag_agent.delete and rag_agent.delete.completed.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.

Returns: Any. Decoded JSON answer of the operation "Delete an instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.delete_logo

delete_logo(instance_id: str) -> Any

Remove the logo of an instance. Back to the default logo of the runtime: the branding no longer points to an object, version is incremented and the stored object is removed. Without a logo, answers the branding unchanged. Same rights as the PUT; audited as rag_agent.branding.logo.remove.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.

Returns: Any. Decoded JSON answer of the operation "Remove the logo of an instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.get

get(instance_id: str) -> Any

Read a RAG Agent instance. The activation record with serving (true for ready and degraded), the current operation and run, validation, last_error and the steps of the current run in order (state, attempts, detail, logs, times). This is the route the RAG runtime reads at startup and on demand.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance, the same in the Control Plane and in the RAG runtime.

Returns: Any. Decoded JSON answer of the operation "Read a RAG Agent instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.get_branding

get_branding(instance_id: str) -> Any

Read the branding of an instance. The branding chosen in the activation journey, owned by the Control Plane: agent_name, sidebar_color, navbar_color, the text colours computed for them (sidebar_text_color, navbar_text_color, black or white, contrast 4.5:1 or more), logo (content_type, sha256, size_bytes, url) or null, version, updated_at, and app_url (the URL of the web application once known). A null field means the default of the runtime. The RAG runtime keeps a replica of it for its public login page and rewrites it when version is newer. Any principal of the tenant; another tenant's instance answers 404.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.

Returns: Any. Decoded JSON answer of the operation "Read the branding of an instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.get_logo

get_logo(instance_id: str) -> Any

Read the logo of an instance. The logo bytes, read from the storage domain and checked against the recorded sha256, with the Content-Type of the validated format (image/png or image/jpeg), X-Content-Type-Options: nosniff, a Content-Security-Policy starting with default-src 'none' and an ETag. 404 rag_agent_logo_not_found when the instance has no logo. Any principal of the tenant.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.

Returns: Any. Decoded JSON answer of the operation "Read the logo of an instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.health

health(instance_id: str) -> Any

Health of an instance. Real checks: readiness URL of the runtime (GET /readyz), knowledge base (row, vector store qdrant, Qdrant /readyz) and model gateway (generation and embedding models in the registry, usable). status is up, degraded or down (runtime down); instance_status is the lifecycle status. Each check has status, duration_ms and reason when not up.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.

Returns: Any. Decoded JSON answer of the operation "Health of an instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.list

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

List the RAG Agent instances. Activation records of the tenant, newest first, with status, deployment model, versions and owned resources (one page, next_cursor null). Filters: status, project.

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

Name	Type	Default	Required	Description
status	str | None	None	no	Only the instances in this status (draft, ready, failed, ...).
project	str | None	None	no	Only the instances of this project (identifier).
limit	int | None	None	no	Maximum number of instances returned (1 to 200, default 50).

Returns: Any. Decoded JSON answer of the operation "List the RAG Agent instances".

Raises: the typed errors of the transport (Errors).

RagAgentClient.provision

provision(instance_id: str) -> Any

Provision an instance. Long operation (202, Operation-Id): status provisioning then starting, steps from validation to activation run by the worker. From a validated draft (else 409 rag_agent_not_validated) or after a failed provisioning, which resumes from the failed step. Repeated while provisioning or once ready: changed: false. Audited as rag_agent.provision, each step as rag_agent.step.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.

Returns: Any. Decoded JSON answer of the operation "Provision an instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.restart

restart(instance_id: str) -> Any

Restart an instance. Long operation (202): from ready, degraded, stopped or after a failed restart, steps deployment (Navin Manager restart for a dedicated instance), health, smoke, activation. A restart in progress: changed: false.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.

Returns: Any. Decoded JSON answer of the operation "Restart an instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.restore

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

Restore an instance (not supported). Answers 501 rag_agent_backup_not_supported with the same parts as the backup: no backup of an instance can be made for real yet. Audited.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.
backup_id	str		yes	Identifier of the backup to restore.

Returns: Any. Decoded JSON answer of the operation "Restore an instance (not supported)".

Raises: the typed errors of the transport (Errors).

RagAgentClient.start

start(instance_id: str) -> Any

Start an instance. Long operation (202): from stopped (or after a failed start or stop), steps deployment (Navin Manager start for a dedicated instance, status only for a shared one), health, smoke, activation (governed application active). Already starting or ready: changed: false.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.

Returns: Any. Decoded JSON answer of the operation "Start an instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.stop

stop(instance_id: str) -> Any

Stop an instance. Long operation (202): from ready, degraded or after a failed start, restart, upgrade or stop, steps deployment (Navin Manager stop for a dedicated instance, status only for a shared one) and activation (governed application suspended, reason rag_instance_stopped); status stopped. Already stopping or stopped: changed: false.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.

Returns: Any. Decoded JSON answer of the operation "Stop an instance".

Raises: the typed errors of the transport (Errors).

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

Change the branding of an instance. Writes the fields given (an absent field is kept, null brings it back to the default of the runtime) and answers the branding. Colours are #RRGGBB (stored in upper case); the text drawn on them is black or white, whichever contrasts most (WCAG 2.2 relative luminance, the rule of the RAG frontend), and a colour whose text would stay under 4.5:1 answers 422 rag_agent_branding_contrast. app_url must be an https URL without credentials (422 rag_agent_app_url_invalid). A change of the name, the colours or the logo increments version; expected_version different from the current one answers 409 rag_agent_branding_version_conflict. With an Idempotency-Key, a retry with the same body replays the first answer (Idempotency-Replayed: true), another body answers 409 idempotency_conflict. Needs a tenant administrator or an owner of the project (403 forbidden); refused while the instance is deleting or deleted (409). Audited as rag_agent.branding.update.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.
agent_name	string | null	_UNSET	no	Name of the agent shown to the users, 1 to 80 characters, without <, > nor control characters.
sidebar_color	string | null	_UNSET	no	Colour of the sidebar, #RRGGBB; the text on it is black or white with a contrast of 4.5:1 or more.
navbar_color	string | null	_UNSET	no	Colour of the top bar, #RRGGBB; the text on it is black or white with a contrast of 4.5:1 or more.
app_url	string | null	_UNSET	no	URL of the web application of the instance once known, https only, without credentials (up to 2048 characters).
expected_version	int | None	None	no	Branding version the change is based on; another current version answers 409 rag_agent_branding_version_conflict.
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.

Returns: Any. Decoded JSON answer of the operation "Change the branding of an instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.upgrade

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

Upgrade an instance. Long operation (202), status updating: a shared instance follows the shared runtime, so the deployment step checks that the runtime runs the requested version (else shared_runtime_version_mismatch); a dedicated one is reinstalled by the Navin Manager. Then health, smoke, activation; deployed_version becomes the version. The same version already deployed or in progress: changed: false.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.
version	str		yes	Version to deploy (letters, digits, ., _, +, -, up to 64 characters).

Returns: Any. Decoded JSON answer of the operation "Upgrade an instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.upload_logo

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

Upload the logo of an instance. Multipart file (with the optional text fields filename and mime_type). PNG or JPEG only: SVG and any other format are refused. The real signature, the declared Content-Type and the file extension must match; 32 to 1024 pixels a side, 512 KiB at most; else 422 rag_agent_logo_invalid with details.reason (format_not_allowed, signature_invalid, signature_mismatch, extension_mismatch, dimensions_out_of_bounds, too_large, empty). The file is then scanned by the file security domain, fail closed: a blocked file answers 422 file_blocked, a scanner down 503 file_scan_unavailable. It is stored through the storage domain in the documents storage profile of the tenant under rag-agent/<tenant>/<instance>/branding/ (409 rag_agent_branding_storage_required without such a profile, 503 rag_agent_branding_storage_unavailable when it cannot be reached); the replaced object is removed. Increments version and answers the branding. Same rights as the PUT; audited as rag_agent.branding.logo.update (a refusal is audited as a denial).

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.
data	bytes		yes	Multipart form with the logo in the file part.
filename	str		yes	Name of the logo file; its extension must match the real format (.png, .jpg or .jpeg).
mime_type	str		yes	Media type of the content, for example application/pdf or image/png.

Returns: Any. Decoded JSON answer of the operation "Upload the logo of an instance".

Raises: the typed errors of the transport (Errors).

RagAgentClient.validate

validate(instance_id: str) -> Any

Validate an instance. Real checks before provisioning: the project exists and the caller may administer it, the generation model exists in the registry with the chat capability and a usable status, the embedding model resolves in the Model Gateway (capability embeddings), the quota of instances, Qdrant answers, the shared runtime answers (shared model) or the Navin Manager answers (dedicated model, an unpublished catalog service is a warning). From draft or after a failed validation. 200 with validation and status draft; 422 rag_agent_validation_failed with the failed checks (status failed, step validation). Audited as rag_agent.validate and rag_agent.validate.completed.

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

Name	Type	Default	Required	Description
instance_id	str		yes	Identifier (UUID) of the instance.

Returns: Any. Decoded JSON answer of the operation "Validate an instance".

Raises: the typed errors of the transport (Errors).