`enterprise_ai.tools`

Source : sdks/python/src/enterprise_ai/tools/__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 `LocalTool`

Une fonction Python exposée comme outil, avec son manifeste et sa définition d'outil OpenAI.

Attributs :

Nom	Requis	Description
`action`	oui	Type d'action de l'outil, par exemple `read`.
`data_classification`	oui	Classification la plus haute des données traitées par l'outil.
`description`	oui	Description montrée au modèle.
`fn`	oui	Fonction Python enveloppée.
`idempotent`	oui	Répéter un appel n'a pas d'effet supplémentaire.
`input_schema`	oui	Schéma JSON des arguments, construit à partir des annotations de type et des lignes `:param` de la docstring.
`is_async`	oui	Vrai quand la fonction enveloppée est une fonction coroutine.
`name`	oui	Nom de l'outil utilisé dans les appels d'outils et dans le manifeste.
`owner`	oui	Propriétaire inscrit dans les métadonnées du manifeste.
`requires_approval`	oui	Chaque appel demande une approbation humaine.
`risk_level`	oui	Niveau de risque inscrit dans le manifeste.
`scopes`	oui	Scopes requis pour invoquer l'outil.
`side_effects`	oui	L'outil modifie quelque chose en dehors de l'agent.
`version`	oui	Version inscrite dans les métadonnées du manifeste.

Constructeur `LocalTool`

LocalTool(fn: Callable[..., Any], name: str | None = None, description: str | None = None, action: str = 'read', scopes: list[str] | None = None, data_classification: str = 'internal', requires_approval: bool = False, side_effects: bool | None = None, idempotent: bool | None = None, version: str = '0.1.0', owner: str = 'team@example.com', risk_level: str = 'minimal') -> None

Enveloppe une fonction comme outil ; le schéma d'entrée vient de ses annotations de type et la description de sa docstring.

Nom	Type	Défaut	Requis	Description
`fn`	`Callable[..., Any]`		oui	Fonction Python à exposer ; appelée avec les arguments décodés.
`name`	`str \| None`	`None`	non	Nom de l'outil ; par défaut, le nom de la fonction au format DNS (`search_orders` donne `search-orders`).
`description`	`str \| None`	`None`	non	Description montrée au modèle ; par défaut, le premier paragraphe de la docstring, sinon le nom.
`action`	`str`	`'read'`	non	Type d'action de l'outil (`read` par défaut) ; il fixe les valeurs par défaut de `side_effects` et `idempotent`.
`scopes`	`list[str] \| None`	`None`	non	Scopes requis pour invoquer l'outil, inscrits dans `scopes_required`.
`data_classification`	`str`	`'internal'`	non	Classification la plus haute des données traitées par l'outil (`internal` par défaut).
`requires_approval`	`bool`	`False`	non	Chaque appel demande une approbation humaine (`False` par défaut).
`side_effects`	`bool \| None`	`None`	non	L'outil modifie quelque chose ; par défaut `True` pour toute action autre que `read`.
`idempotent`	`bool \| None`	`None`	non	Répéter un appel n'a pas d'effet supplémentaire ; par défaut `True` seulement pour les outils `read`.
`version`	`str`	`'0.1.0'`	non	Version inscrite dans les métadonnées du manifeste (`0.1.0` par défaut).
`owner`	`str`	`'team@example.com'`	non	Propriétaire inscrit dans les métadonnées du manifeste (`team@example.com` par défaut).
`risk_level`	`str`	`'minimal'`	non	Niveau de risque inscrit dans le manifeste (`minimal` par défaut).

`LocalTool.invoke`

invoke(arguments: dict[str, Any] | str) -> Any

Appelle la fonction avec des arguments JSON (chaîne ou dict), tels que produits par un appel d'outil du modèle.

Nom	Type	Défaut	Requis	Description
`arguments`	`dict[str, Any] \| str`		oui	Arguments sous forme de dict ou de chaîne JSON ; vide signifie aucun argument.

Retour : Any. Valeur renvoyée par la fonction (une coroutine pour une fonction asynchrone).

`LocalTool.manifest`

manifest(endpoint: dict[str, Any] | None = None, **metadata: Any) -> dict[str, Any]

Un Tool Manifest (kind: Tool) pour cette fonction.

Nom	Type	Défaut	Requis	Description
`endpoint`	`dict[str, Any] \| None`	`None`	non	Point d'accès de l'outil ; par défaut, un `POST /tools/<nom>` HTTP local avec un délai de 30 secondes.
`**metadata`	`Any`		non	Champs supplémentaires fusionnés dans `metadata` (après `name`, `version`, `owner`).

Retour : dict[str, Any]. Dict de Tool Manifest (apiVersion enterprise-ai.io/v1) avec le schéma, les scopes, la classification et les réglages d'approbation.

`LocalTool.openai_tool`

openai_tool() -> dict[str, Any]

L'entrée tools d'une requête de chat compatible OpenAI.

Cet élément ne prend aucun paramètre.

Retour : dict[str, Any]. Dict {type: function, function: {name, description, parameters}}.

Classe `ToolsClient`

/v1/tools : registre et Tool Gateway (scopes, politique, DLP, approbation, coût).

Resource

`ToolsClient.create`

create(manifest: dict[str, Any]) -> Any

Enregistrer un outil. Applique un manifeste Tool : crée ou met à jour l'outil (apply_status : created, updated ou unchanged). Contrôles : schémas JSON d'entrée et de sortie valides, un point d'accès http demande une URL http(s) permise par la politique de sortie réseau, un point d'accès mcp demande mcp_server, un gestionnaire builtin doit être echo ou time.now, le niveau de risque unacceptable est refusé (422 invalid_manifest). Demande tenant_admin, developer ou application_owner ; l'appelant devient propriétaire ReBAC. Audité sous tool.apply.

Route : /v1/tools (POST).

Nom	Type	Défaut	Requis	Description
`manifest`	`dict[str, Any]`		oui	Tool Manifest envoyé comme corps de la requête.

Retour : Any. Réponse JSON décodée de l'opération « Enregistrer un outil ».

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

`ToolsClient.delete`

delete(name: str) -> Any

Supprimer un outil. Retire l'outil du registre. Demande tenant_admin et la relation ReBAC owner. 404 tool_not_found. Audité sous tool.delete.

Route : /v1/tools/{name} (DELETE).

Nom	Type	Défaut	Requis	Description
`name`	`str`		oui	Nom de l'outil.

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

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

`ToolsClient.discover`

discover(status: str | None = 'approved', **page: Any) -> Any

Lister les outils. Outils du tenant dans l'ordre des noms, éventuellement d'un seul statut. Une seule page.

Route : /v1/tools (GET).

Nom	Type	Défaut	Requis	Description
`status`	`str \| None`	`'approved'`	non	Seulement ce statut : `draft`, `approved`, `restricted`, `deprecated` ou `blocked`.
`**page`	`Any`		non	Options de pagination : `limit` (nombre maximal d'outils par page) et `cursor` (curseur de la page à lire).

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

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

`ToolsClient.get`

get(name: str) -> Any

Lire un outil. Renvoie l'outil avec son manifeste, son niveau de risque, son propriétaire et son statut. Demande la relation ReBAC viewer. 404 tool_not_found.

Route : /v1/tools/{name} (GET).

Nom	Type	Défaut	Requis	Description
`name`	`str`		oui	Nom de l'outil.

Retour : Any. Réponse JSON décodée de l'opération « Lire un outil ».

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

`ToolsClient.invocations`

invocations(tool: str | None = None, run_id: str | None = None, **page: Any) -> Any

Lister les invocations d'outils. Invocations enregistrées par la Tool Gateway, de la plus récente à la plus ancienne, paginées avec cursor : outil et version, acteur, run, agent, statut, décision, approbation, arguments et résultat expurgés, détections DLP, statut HTTP, erreur et durée. Les arguments et résultats ne sont conservés qu'expurgés.

Route : /v1/tools/invocations (GET).

Nom	Type	Défaut	Requis	Description
`tool`	`str \| None`	`None`	non	Seulement les invocations de cet outil.
`run_id`	`str \| None`	`None`	non	Seulement les invocations faites par ce run.
`**page`	`Any`		non	Options de pagination : `limit` (nombre maximal d'invocations par page) et `cursor` (curseur de la page à lire).

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

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

`ToolsClient.invoke`

invoke(name: str, arguments: dict[str, Any], run_id: str | None = None, idempotency_key: str | None = None, **extra: Any) -> Any

Invoquer un outil via la passerelle. Exécute la chaîne de la passerelle décrite dans l'introduction du tag et renvoie l'invocation : status, result masqué, error, duration_ms, decision_id, détections DLP, événement d'usage et coût. Demande tenant_admin, developer ou agent et la relation ReBAC can_invoke. Réponses : 200 une fois exécuté (aussi quand l'amont a échoué, voir status et error) ; 202 pending_approval avec approval_id quand une validation humaine est requise (rappelez avec l'approval_id approuvé et les mêmes arguments) ; 202 pour un outil sandbox, avec l'identifiant de l'exécution en sandbox. Erreurs : 403 tool_blocked, insufficient_scope, tool_not_granted, classification_exceeded, policy_denied, dlp_blocked ; 422 invalid_arguments ; 409 approval_consumed (une approbation sert un seul appel réussi) ; 429 rate_limited avec Retry-After: 60 ou quota_exceeded.

Route : /v1/tools/{name}/invoke (POST).

Nom	Type	Défaut	Requis	Description
`name`	`str`		oui	Nom de l'outil.
`arguments`	`dict[str, Any]`		oui	Arguments, validés selon le `input_schema` de l'outil. Envoyés en corps JSON (chaîne de requête pour les points d'accès GET et DELETE).
`run_id`	`str \| None`	`None`	non	Run auquel appartient l'appel ; envoyé à un point d'accès HTTP en `X-EAI-Run-Id` et utilisé pour le comptage.
`idempotency_key`	`str \| None`	`None`	non	En-tête Idempotency-Key : une reprise avec la même clé rejoue la première réponse.
`**extra`	`Any`		non	Champs supplémentaires fusionnés dans le corps de la requête.

Retour : Any. Réponse JSON décodée de l'opération « Invoquer un outil via la passerelle ».

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

`ToolsClient.list`

list(**page: Any) -> Any

Lister les outils. Outils du tenant dans l'ordre des noms, éventuellement d'un seul statut. Une seule page.

Route : /v1/tools (GET).

Nom	Type	Défaut	Requis	Description
`**page`	`Any`		non	Options de pagination : `limit` (nombre maximal d'outils par page) et `cursor` (curseur de la page à lire).

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

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

`ToolsClient.register`

register(local: LocalTool, endpoint: dict[str, Any] | None = None) -> Any

Route : /v1/tools (POST).

Nom	Type	Défaut	Requis	Description
`local`	`LocalTool`		oui	Fonction décorée dont le manifeste est enregistré.
`endpoint`	`dict[str, Any] \| None`	`None`	non	Point d'accès inscrit dans le manifeste ; le point d'accès local par défaut de `LocalTool.manifest` s'il est omis.

Retour : Any. Réponse JSON décodée de l'opération « Enregistrer un outil ».

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

`ToolsClient.update`

update(name: str, **changes: Any) -> Any

Modifier un outil. Modifie le propriétaire, la description ou le statut. Un changement de statut demande tenant_admin ou security_officer, les autres champs tenant_admin, developer ou application_owner ; la relation ReBAC editor est vérifiée. approved passe par une promotion (202 avec approval_id) ; les autres statuts s'appliquent aussitôt (200). Audité sous tool.update.

Route : /v1/tools/{name} (PATCH).

Nom	Type	Défaut	Requis	Description
`name`	`str`		oui	Nom de l'outil.
`**changes`	`Any`		non	Champs de l'outil à modifier, envoyés comme corps du `PATCH`.

Retour : Any. Réponse JSON décodée de l'opération « Modifier un outil ».

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

`ToolsClient.validate`

validate(manifest: dict[str, Any]) -> Any

Valider un document avec un contrat. Valide le corps avec le contrat, formats compris, sans rien enregistrer. La réponse donne contract, valid et errors, chacune avec le path JSON de la valeur fautive et un message. Ouvert à tout appelant authentifié. Un contrat inconnu répond 404 unknown_contract.

Route : /v1/contracts/{name}/validate (POST).

Nom	Type	Défaut	Requis	Description
`manifest`	`dict[str, Any]`		oui	Tool Manifest à valider sur le serveur.

Retour : Any. Réponse JSON décodée de l'opération « Valider un document avec un contrat ».

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

Fonctions

`schema_for`

schema_for(annotation: Any) -> dict[str, Any]

Schéma JSON pour une annotation de type Python (types natifs, Optional, Literal, Enum, list, dict, dataclass, pydantic).

Nom	Type	Défaut	Requis	Description
`annotation`	`Any`		oui	Annotation de type Python à convertir.

Retour : dict[str, Any]. Dict de schéma JSON ; vide pour Any, une annotation absente ou un type inconnu.

`input_schema`

input_schema(fn: Callable[..., Any]) -> dict[str, Any]

Schéma objet des paramètres de fn (self, *args et **kwargs ignorés).

Nom	Type	Défaut	Requis	Description
`fn`	`Callable[..., Any]`		oui	Fonction dont la signature, les annotations de type et les lignes `:param` de la docstring sont lues.

Retour : dict[str, Any]. Schéma JSON {type: object, properties, required} sans propriétés supplémentaires ; les valeurs par défaut simples sont recopiées dans default.

`tool_name`

tool_name(fn: Callable[..., Any]) -> str

Nom d'outil au format DNS tiré du nom d'une fonction (search_orders -> search-orders).

Nom	Type	Défaut	Requis	Description
`fn`	`Callable[..., Any]`		oui	Fonction dont le `__name__` est converti.

Retour : str. Nom en minuscules avec - à la place de _ et de tout caractère autre que lettres, chiffres, . et - ; tool s'il est vide.

`tool`

tool(fn: Callable[..., Any] | None = None, **options: Any) -> Any

Décorateur qui transforme une fonction en :class:LocalTool (utilisable avec ou sans arguments).

Nom	Type	Défaut	Requis	Description
`fn`	`Callable[..., Any] \| None`	`None`	non	Fonction à envelopper ; si elle est omise, l'appel renvoie un décorateur qui applique les options données.
`**options`	`Any`		non	Options de l'appel (clé d'idempotence, traceparent, en-têtes, signal d'annulation).

Retour : Any. Un LocalTool quand fn est fourni, sinon un décorateur qui en renvoie un.

Classe LocalTool​

Constructeur LocalTool​

LocalTool.invoke​

LocalTool.manifest​

LocalTool.openai_tool​

Classe ToolsClient​

ToolsClient.create​

ToolsClient.delete​

ToolsClient.discover​

ToolsClient.get​

ToolsClient.invocations​

ToolsClient.invoke​

ToolsClient.list​

ToolsClient.register​

ToolsClient.update​

ToolsClient.validate​

Fonctions​

schema_for​

input_schema​

tool_name​

tool​

Classe `LocalTool`

Constructeur `LocalTool`

`LocalTool.invoke`

`LocalTool.manifest`

`LocalTool.openai_tool`

Classe `ToolsClient`

`ToolsClient.create`

`ToolsClient.delete`

`ToolsClient.discover`

`ToolsClient.get`

`ToolsClient.invocations`

`ToolsClient.invoke`

`ToolsClient.list`

`ToolsClient.register`

`ToolsClient.update`

`ToolsClient.validate`

Fonctions

`schema_for`

`input_schema`

`tool_name`

`tool`