io.enterpriseai.resources.ToolsClient
Source: sdks/java/enterprise-ai-java/src/main/java/io/enterpriseai/resources/ToolsClient.java. Back to the Java SDK reference index.
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 ToolsClient
Tool registry and Tool Gateway invocations.
Constructor ToolsClient
ToolsClient(Transport transport)
Creates the client on the shared transport; EnterpriseAIClient builds it and exposes it through the accessor of the same name.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
transport | Transport | yes | Transport shared by the sub-clients of one client. |
ToolsClient.create
JsonNode create(Object body)
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 |
|---|---|---|---|---|
body | Object | yes | Tool manifest (kind: Tool, metadata, spec with description, action, input schema, endpoint, data classification and options). |
Returns: JsonNode. Decoded JSON answer of the operation "Register a tool".
Raises: the typed errors of the transport (Errors).
ToolsClient.create
JsonNode create(Object body, RequestOptions options)
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 |
|---|---|---|---|---|
body | Object | yes | Tool manifest (kind: Tool, metadata, spec with description, action, input schema, endpoint, data classification and options). | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Register a tool".
Raises: the typed errors of the transport (Errors).
ToolsClient.delete
void delete(String name)
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 | String | yes | Name of the tool. |
Returns: void.
Raises: the typed errors of the transport (Errors).
ToolsClient.get
JsonNode get(String name)
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 | String | yes | Name of the tool. |
Returns: JsonNode. Decoded JSON answer of the operation "Get a tool".
Raises: the typed errors of the transport (Errors).
ToolsClient.invocations
Page<JsonNode> invocations()
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).
This element takes no parameter.
Returns: Page<JsonNode>. A Page: One page of a cursor paginated collection ({"items": [...], "next_cursor": "..."|null}).
Raises: the typed errors of the transport (Errors).
ToolsClient.invocations
Page<JsonNode> invocations(Map<String, ?> query)
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 |
|---|---|---|---|---|
query | Map<String, ?> | yes | Query string parameters of the route. |
Returns: Page<JsonNode>. A Page: One page of a cursor paginated collection ({"items": [...], "next_cursor": "..."|null}).
Raises: the typed errors of the transport (Errors).
ToolsClient.invoke
JsonNode invoke(String name, Object body)
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 | String | yes | Name of the tool. | |
body | Object | yes | Arguments of the call and its context (run, agent, approval, purpose, classification). |
Returns: JsonNode. Decoded JSON answer of the operation "Invoke a tool through the gateway".
Raises: the typed errors of the transport (Errors).
ToolsClient.invoke
JsonNode invoke(String name, Object body, RequestOptions options)
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 | String | yes | Name of the tool. | |
body | Object | yes | Arguments of the call and its context (run, agent, approval, purpose, classification). | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Invoke a tool through the gateway".
Raises: the typed errors of the transport (Errors).
ToolsClient.list
Page<JsonNode> list()
List the tools. Tools of the tenant in name order, optionally with one status. One page only.
Route: /v1/tools (GET).
This element takes no parameter.
Returns: Page<JsonNode>. A Page: One page of a cursor paginated collection ({"items": [...], "next_cursor": "..."|null}).
Raises: the typed errors of the transport (Errors).
ToolsClient.list
Page<JsonNode> list(Map<String, ?> query)
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 |
|---|---|---|---|---|
query | Map<String, ?> | yes | Query string parameters of the route. |
Returns: Page<JsonNode>. A Page: One page of a cursor paginated collection ({"items": [...], "next_cursor": "..."|null}).
Raises: the typed errors of the transport (Errors).
ToolsClient.update
JsonNode update(String name, Object body)
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 | String | yes | Name of the tool. | |
body | Object | yes | Fields to change; the omitted ones are kept. |
Returns: JsonNode. Decoded JSON answer of the operation "Update a tool".
Raises: the typed errors of the transport (Errors).
ToolsClient.update
JsonNode update(String name, Object body, RequestOptions options)
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 | String | yes | Name of the tool. | |
body | Object | yes | Fields to change; the omitted ones are kept. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Update a tool".
Raises: the typed errors of the transport (Errors).