`enterprise_ai.tools`

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

A Python function exposed as a tool, with its manifest and OpenAI tool definition.

Attributes:

Name	Required	Description
`action`	yes	Kind of action of the tool, such as `read`.
`data_classification`	yes	Highest classification of the data the tool handles.
`description`	yes	Description shown to the model.
`fn`	yes	Wrapped Python function.
`idempotent`	yes	Repeating a call has no further effect.
`input_schema`	yes	JSON Schema of the arguments, built from the type hints and the `:param` lines of the docstring.
`is_async`	yes	True when the wrapped function is a coroutine function.
`name`	yes	Tool name used in tool calls and in the manifest.
`owner`	yes	Owner written in the manifest metadata.
`requires_approval`	yes	Every call needs a human approval.
`risk_level`	yes	Risk level written in the manifest.
`scopes`	yes	Scopes the caller needs to invoke the tool.
`side_effects`	yes	The tool changes something outside the agent.
`version`	yes	Version written in the manifest metadata.

Constructor `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

Wrap a function as a tool; the input schema comes from its type hints and the description from its docstring.

Name	Type	Default	Required	Description
`fn`	`Callable[..., Any]`		yes	Python function to expose; called with the decoded arguments.
`name`	`str \| None`	`None`	no	Tool name; defaults to the function name in DNS form (`search_orders` gives `search-orders`).
`description`	`str \| None`	`None`	no	Description shown to the model; defaults to the first paragraph of the docstring, else the name.
`action`	`str`	`'read'`	no	Kind of action of the tool (default `read`); it sets the defaults of `side_effects` and `idempotent`.
`scopes`	`list[str] \| None`	`None`	no	Scopes the caller needs to invoke the tool, written as `scopes_required`.
`data_classification`	`str`	`'internal'`	no	Highest classification of the data the tool handles (default `internal`).
`requires_approval`	`bool`	`False`	no	Every call needs a human approval (default `False`).
`side_effects`	`bool \| None`	`None`	no	The tool changes something; defaults to `True` for any action other than `read`.
`idempotent`	`bool \| None`	`None`	no	Repeating a call has no further effect; defaults to `True` only for `read` tools.
`version`	`str`	`'0.1.0'`	no	Version written in the manifest metadata (default `0.1.0`).
`owner`	`str`	`'team@example.com'`	no	Owner written in the manifest metadata (default `team@example.com`).
`risk_level`	`str`	`'minimal'`	no	Risk level written in the manifest (default `minimal`).

`LocalTool.invoke`

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

Call with JSON (string or dict) arguments, as produced by a model tool call.

Name	Type	Default	Required	Description
`arguments`	`dict[str, Any] \| str`		yes	Arguments as a dict or a JSON string; empty means no argument.

Returns: Any. Return value of the function (a coroutine for an async function).

`LocalTool.manifest`

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

A Tool Manifest (kind: Tool) for this function.

Name	Type	Default	Required	Description
`endpoint`	`dict[str, Any] \| None`	`None`	no	Endpoint of the tool; by default a local HTTP `POST /tools/<name>` with a 30 second timeout.
`**metadata`	`Any`		no	Extra fields merged into `metadata` (after `name`, `version`, `owner`).

Returns: dict[str, Any]. Tool Manifest dict (apiVersion enterprise-ai.io/v1) with the schema, scopes, classification and approval settings.

`LocalTool.openai_tool`

openai_tool() -> dict[str, Any]

The tools entry for an OpenAI compatible chat request.

This element takes no parameter.

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

Class `ToolsClient`

/v1/tools: registry and Tool Gateway (scopes, policy, DLP, approval, cost).

Resource

`ToolsClient.create`

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

Register a tool. Applies a Tool manifest: creates or updates the tool (apply_status: created, updated or unchanged). Checked: valid JSON Schemas for input and output, an http endpoint needs an http(s) URL allowed by the egress policy, an mcp endpoint needs mcp_server, a builtin handler must be echo or time.now, risk level unacceptable is refused (422 invalid_manifest). Needs tenant_admin, developer or application_owner; the caller becomes ReBAC owner. Audited as tool.apply.

Route: /v1/tools (POST).

Name	Type	Default	Required	Description
`manifest`	`dict[str, Any]`		yes	Tool Manifest sent as the request body.

Returns: Any. Decoded JSON answer of the operation "Register a tool".

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

`ToolsClient.delete`

delete(name: str) -> Any

Delete a tool. Removes the tool from the registry. Needs tenant_admin and the ReBAC relation owner. 404 tool_not_found. Audited as tool.delete.

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

Name	Type	Default	Required	Description
`name`	`str`		yes	Name of the tool.

Returns: Any. Decoded JSON answer of the operation "Delete a tool".

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

`ToolsClient.discover`

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

List the tools. Tools of the tenant in name order, optionally with one status. One page only.

Route: /v1/tools (GET).

Name	Type	Default	Required	Description
`status`	`str \| None`	`'approved'`	no	Only this status: `draft`, `approved`, `restricted`, `deprecated` or `blocked`.
`**page`	`Any`		no	Pagination options: `limit` (maximum number of tools per page) and `cursor` (cursor of the page to read).

Returns: Any. Decoded JSON answer of the operation "List the tools".

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

`ToolsClient.get`

get(name: str) -> Any

Get a tool. Returns the tool with its manifest, risk level, owner and status. Needs the ReBAC relation viewer. 404 tool_not_found.

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

Name	Type	Default	Required	Description
`name`	`str`		yes	Name of the tool.

Returns: Any. Decoded JSON answer of the operation "Get a tool".

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

`ToolsClient.invocations`

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

List the tool invocations. Invocations recorded by the Tool Gateway, newest first, paginated with cursor: tool and version, actor, run, agent, status, decision, approval, redacted arguments and result, DLP findings, HTTP status, error and duration. Arguments and results are stored redacted only.

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

Name	Type	Default	Required	Description
`tool`	`str \| None`	`None`	no	Only the invocations of this tool name.
`run_id`	`str \| None`	`None`	no	Only the invocations made by this run.
`**page`	`Any`		no	Pagination options: `limit` (maximum number of invocations per page) and `cursor` (cursor of the page to read).

Returns: Any. Decoded JSON answer of the operation "List the tool invocations".

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

`ToolsClient.invoke`

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

Invoke a tool through the gateway. Runs the gateway pipeline described in the tag introduction and returns the invocation: status, masked result, error, duration_ms, decision_id, DLP findings, usage event and cost. Needs tenant_admin, developer or agent and the ReBAC relation can_invoke. Answers: 200 when executed (also when the upstream failed, see status and error); 202 pending_approval with approval_id when a human approval is needed (call again with the approved approval_id and the same arguments); 202 for a sandbox tool, with the sandbox execution id. Errors: 403 tool_blocked, insufficient_scope, tool_not_granted, classification_exceeded, policy_denied, dlp_blocked; 422 invalid_arguments; 409 approval_consumed (an approval serves one successful call); 429 rate_limited with Retry-After: 60 or quota_exceeded.

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

Name	Type	Default	Required	Description
`name`	`str`		yes	Name of the tool.
`arguments`	`dict[str, Any]`		yes	Arguments, validated against the tool `input_schema`. Sent as JSON body (query string for GET and DELETE endpoints).
`run_id`	`str \| None`	`None`	no	Run the call belongs to; sent to an HTTP endpoint as `X-EAI-Run-Id` and used for metering.
`idempotency_key`	`str \| None`	`None`	no	Idempotency-Key header: a retry with the same key replays the first answer.
`**extra`	`Any`		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Invoke a tool through the gateway".

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

`ToolsClient.list`

list(**page: Any) -> Any

List the tools. Tools of the tenant in name order, optionally with one status. One page only.

Route: /v1/tools (GET).

Name	Type	Default	Required	Description
`**page`	`Any`		no	Pagination options: `limit` (maximum number of tools per page) and `cursor` (cursor of the page to read).

Returns: Any. Decoded JSON answer of the operation "List the tools".

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

`ToolsClient.register`

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

Route: /v1/tools (POST).

Name	Type	Default	Required	Description
`local`	`LocalTool`		yes	Decorated function whose manifest is registered.
`endpoint`	`dict[str, Any] \| None`	`None`	no	Endpoint written in the manifest; the default local endpoint of `LocalTool.manifest` when omitted.

Returns: Any. Decoded JSON answer of the operation "Register a tool".

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

`ToolsClient.update`

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

Update a tool. Changes the owner, the description or the status. A status change needs tenant_admin or security_officer, other fields tenant_admin, developer or application_owner; the ReBAC relation editor is checked. approved goes through a promotion (202 with approval_id); other statuses apply at once (200). Audited as tool.update.

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

Name	Type	Default	Required	Description
`name`	`str`		yes	Name of the tool.
`**changes`	`Any`		no	Fields of the tool to change, sent as the `PATCH` body.

Returns: Any. Decoded JSON answer of the operation "Update a tool".

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

`ToolsClient.validate`

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

Validate a document against a contract. Validates the body against the contract, formats included, without storing anything. The answer gives contract, valid and errors, each with the JSON path of the faulty value and a message. Open to any authenticated caller. An unknown contract answers 404 unknown_contract.

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

Name	Type	Default	Required	Description
`manifest`	`dict[str, Any]`		yes	Tool Manifest to validate on the server.

Returns: Any. Decoded JSON answer of the operation "Validate a document against a contract".

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

Functions

`schema_for`

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

JSON Schema for a Python type hint (builtins, Optional, Literal, Enum, list, dict, dataclass, pydantic).

Name	Type	Default	Required	Description
`annotation`	`Any`		yes	Python type hint to convert.

Returns: dict[str, Any]. JSON Schema dict; empty for Any, a missing hint or an unknown type.

`input_schema`

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

Object schema of the parameters of fn (self, *args and **kwargs skipped).

Name	Type	Default	Required	Description
`fn`	`Callable[..., Any]`		yes	Function whose signature, type hints and `:param` docstring lines are read.

Returns: dict[str, Any]. JSON Schema {type: object, properties, required} without extra properties; simple defaults are copied as default.

`tool_name`

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

DNS-like tool name from a function name (search_orders -> search-orders).

Name	Type	Default	Required	Description
`fn`	`Callable[..., Any]`		yes	Function whose `__name__` is converted.

Returns: str. Lower case name with - instead of _ and of any character other than letters, digits, . and -; tool when empty.

`tool`

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

Decorator turning a function into a :class:LocalTool (usable with or without arguments).

Name	Type	Default	Required	Description
`fn`	`Callable[..., Any] \| None`	`None`	no	Function to wrap; when omitted, the call returns a decorator that applies the given options.
`**options`	`Any`		no	Per call options (idempotency key, traceparent, headers, abort signal).

Returns: Any. A LocalTool when fn is given, otherwise a decorator that returns one.

Class LocalTool​

Constructor LocalTool​

LocalTool.invoke​

LocalTool.manifest​

LocalTool.openai_tool​

Class ToolsClient​

ToolsClient.create​

ToolsClient.delete​

ToolsClient.discover​

ToolsClient.get​

ToolsClient.invocations​

ToolsClient.invoke​

ToolsClient.list​

ToolsClient.register​

ToolsClient.update​

ToolsClient.validate​

Functions​

schema_for​

input_schema​

tool_name​

tool​

Class `LocalTool`

Constructor `LocalTool`

`LocalTool.invoke`

`LocalTool.manifest`

`LocalTool.openai_tool`

Class `ToolsClient`

`ToolsClient.create`

`ToolsClient.delete`

`ToolsClient.discover`

`ToolsClient.get`

`ToolsClient.invocations`

`ToolsClient.invoke`

`ToolsClient.list`

`ToolsClient.register`

`ToolsClient.update`

`ToolsClient.validate`

Functions

`schema_for`

`input_schema`

`tool_name`

`tool`