io.enterpriseai.resources.AgentsClient
Source: sdks/java/enterprise-ai-java/src/main/java/io/enterpriseai/resources/AgentsClient.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 AgentsClient
Agent registry and lifecycle (suspend, resume, kill).
Constructor AgentsClient
AgentsClient(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. |
AgentsClient.create
JsonNode create(Object body)
Register an agent or a version. Applies an Agent manifest: creates the agent, or adds a version to an existing one and makes it current. The manifest is validated against the v1 contract (422 invalid_manifest); risk level unacceptable is refused (422 agent_risk_unacceptable); the same version with other content is refused (409 version_immutable). apply_status in the answer is created, version_added or unchanged. Needs tenant_admin, developer or application_owner; the caller becomes ReBAC owner. Audited as agent.apply.
Route: /v1/agents (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
body | Object | yes | Agent manifest (kind: Agent, metadata with name, version and owner, spec). |
Returns: JsonNode. Decoded JSON answer of the operation "Register an agent or a version".
Raises: the typed errors of the transport (Errors).
AgentsClient.create
JsonNode create(Object body, RequestOptions options)
Register an agent or a version. Applies an Agent manifest: creates the agent, or adds a version to an existing one and makes it current. The manifest is validated against the v1 contract (422 invalid_manifest); risk level unacceptable is refused (422 agent_risk_unacceptable); the same version with other content is refused (409 version_immutable). apply_status in the answer is created, version_added or unchanged. Needs tenant_admin, developer or application_owner; the caller becomes ReBAC owner. Audited as agent.apply.
Route: /v1/agents (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
body | Object | yes | Agent manifest (kind: Agent, metadata with name, version and owner, spec). | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Register an agent or a version".
Raises: the typed errors of the transport (Errors).
AgentsClient.delete
void delete(String id)
Delete an agent. Deletes the agent and its versions. Needs the role tenant_admin and the ReBAC relation owner on the agent. Refused with 409 agent_has_active_runs while a run of the agent is still active (pending, running, waiting or suspended); 404 agent_not_found for an unknown agent. Audited as agent.delete.
Route: /v1/agents/{agent_id} (DELETE).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) or name of the agent. |
Returns: void.
Raises: the typed errors of the transport (Errors).
AgentsClient.get
JsonNode get(String id)
Get an agent. Returns the agent, the manifest of its current version and runs, the number of its runs per state. Needs the ReBAC relation viewer on the agent. 404 agent_not_found.
Route: /v1/agents/{agent_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) or name of the agent. |
Returns: JsonNode. Decoded JSON answer of the operation "Get an agent".
Raises: the typed errors of the transport (Errors).
AgentsClient.kill
JsonNode kill(String id)
Kill an agent. Kill switch: every active run of the agent is cancelled with the error killed and the agent status becomes killed for good (it can never be resumed). Needs tenant_admin or security_officer. 409 agent_killed if already killed. The answer lists affected_runs. Audited as agent.kill.
Route: /v1/agents/{agent_id}/kill (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) or name of the agent. |
Returns: JsonNode. Decoded JSON answer of the operation "Kill an agent".
Raises: the typed errors of the transport (Errors).
AgentsClient.kill
JsonNode kill(String id, Object body)
Kill an agent. Kill switch: every active run of the agent is cancelled with the error killed and the agent status becomes killed for good (it can never be resumed). Needs tenant_admin or security_officer. 409 agent_killed if already killed. The answer lists affected_runs. Audited as agent.kill.
Route: /v1/agents/{agent_id}/kill (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) or name of the agent. | |
body | Object | yes | Optional reason, kept on the agent and in the audit trail. |
Returns: JsonNode. Decoded JSON answer of the operation "Kill an agent".
Raises: the typed errors of the transport (Errors).
AgentsClient.list
Page<JsonNode> list()
List the agents. Agents of the tenant, in name order, paginated with cursor. Any tenant principal may call it.
Route: /v1/agents (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).
AgentsClient.list
Page<JsonNode> list(Map<String, ?> query)
List the agents. Agents of the tenant, in name order, paginated with cursor. Any tenant principal may call it.
Route: /v1/agents (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).
AgentsClient.resume
JsonNode resume(String id)
Request the resumption of an agent. Opens a promotion approval to bring a suspended agent back to active and answers 202 with approval_id and status: pending_approval; approvers are tenant_admin or security_officer. Once approved, the runs suspended by the agent suspension resume. Needs tenant_admin or security_officer. Refused with 409 agent_killed, or 409 kill_switch_active while a SOC containment holds the agent (lifted only through POST /v1/soc/recoveries).
Route: /v1/agents/{agent_id}/resume (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) or name of the agent. |
Returns: JsonNode. Decoded JSON answer of the operation "Request the resumption of an agent".
Raises: the typed errors of the transport (Errors).
AgentsClient.resume
JsonNode resume(String id, Object body)
Request the resumption of an agent. Opens a promotion approval to bring a suspended agent back to active and answers 202 with approval_id and status: pending_approval; approvers are tenant_admin or security_officer. Once approved, the runs suspended by the agent suspension resume. Needs tenant_admin or security_officer. Refused with 409 agent_killed, or 409 kill_switch_active while a SOC containment holds the agent (lifted only through POST /v1/soc/recoveries).
Route: /v1/agents/{agent_id}/resume (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) or name of the agent. | |
body | Object | yes | Optional reason, shown to the approvers. |
Returns: JsonNode. Decoded JSON answer of the operation "Request the resumption of an agent".
Raises: the typed errors of the transport (Errors).
AgentsClient.suspend
JsonNode suspend(String id)
Suspend an agent. Kill switch, reversible: the agent status becomes suspended, its active runs move to suspended and new runs are refused. Needs tenant_admin or security_officer. 409 agent_killed for a killed agent. The answer lists affected_runs. Audited as agent.suspend.
Route: /v1/agents/{agent_id}/suspend (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) or name of the agent. |
Returns: JsonNode. Decoded JSON answer of the operation "Suspend an agent".
Raises: the typed errors of the transport (Errors).
AgentsClient.suspend
JsonNode suspend(String id, Object body)
Suspend an agent. Kill switch, reversible: the agent status becomes suspended, its active runs move to suspended and new runs are refused. Needs tenant_admin or security_officer. 409 agent_killed for a killed agent. The answer lists affected_runs. Audited as agent.suspend.
Route: /v1/agents/{agent_id}/suspend (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) or name of the agent. | |
body | Object | yes | Optional reason, kept on the agent and in the audit trail. |
Returns: JsonNode. Decoded JSON answer of the operation "Suspend an agent".
Raises: the typed errors of the transport (Errors).
AgentsClient.update
JsonNode update(String id, Object body)
Update an agent. Changes the registry fields of the agent (owner, risk level, description, labels) without creating a version. Needs tenant_admin, developer or application_owner and the ReBAC relation editor. Invalid values answer 400 invalid_request. Audited as agent.update with the changed field names.
Route: /v1/agents/{agent_id} (PATCH).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) or name of the agent. | |
body | Object | yes | Fields to change; the omitted ones are kept. |
Returns: JsonNode. Decoded JSON answer of the operation "Update an agent".
Raises: the typed errors of the transport (Errors).
AgentsClient.update
JsonNode update(String id, Object body, RequestOptions options)
Update an agent. Changes the registry fields of the agent (owner, risk level, description, labels) without creating a version. Needs tenant_admin, developer or application_owner and the ReBAC relation editor. Invalid values answer 400 invalid_request. Audited as agent.update with the changed field names.
Route: /v1/agents/{agent_id} (PATCH).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) or name of the agent. | |
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 an agent".
Raises: the typed errors of the transport (Errors).
AgentsClient.versions
JsonNode versions(String id)
List the versions of an agent. Every registered version of the agent, newest first, with its manifest, digest, author and current (true for the version in use). Needs the ReBAC relation viewer. One page only.
Route: /v1/agents/{agent_id}/versions (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
id | String | yes | Identifier (UUID) or name of the agent. |
Returns: JsonNode. Decoded JSON answer of the operation "List the versions of an agent".
Raises: the typed errors of the transport (Errors).