update_agent_details

ArtificialIntelligenceApi.update_agent_details(id, role_id, content_type=None, action=None, update_agent_request_body=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

Update a custom agent, enable or disable it, or change a system agent model

CUSTOM agents require editor access. Default (no action): validates the body against UpdateAgentRequestBody, sets AgentStatus to UPDATING, and triggers async AgentCore update. If the agent is CREATE_FAILED, async recreate uses the POST creation path. Allowed statuses for update are READY, UPDATE_FAILED, and CREATE_FAILED (AI-1002 otherwise). Query action=enable or action=disable toggles IsEnabled synchronously for CUSTOM agents only. Enable is allowed from READY or UPDATE_FAILED. Disable is also allowed from CREATE_FAILED. SYSTEM agents reject enable/disable with IPV-1040. SYSTEM agents with no action: only ModelId may be sent (UpdateSystemAgentModelRequestBody). Requires ai-admin.fullaccess (AUTH-1030). Unchanged ModelId returns 200 without writing. Cost inference profile is recreated when cost management is enabled. HTTP 202 is not returned by the current handler.

Parameters:

  • id (str) – AgentId of the agent to update. (required)

  • role_id (str) – Amorphic role ID the request is authorized against. Must be a role the user belongs to. Returns AUTH-1001 if missing. (required)

  • content_type (str)

  • action (str) – CUSTOM-only synchronous enable or disable. Other values return IPV-1040. SYSTEM agents cannot use this parameter.

  • update_agent_request_body (UpdateAgentRequestBody)

  • _request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.

  • _request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.

  • _content_type (str, Optional) – force content-type for the request.

  • _headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.

  • _host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

MessageResponse

Returns:

Returns the result object.

Request and Response Examples

HTTP: PUT /ai/agents/{id}

Request

Update CUSTOM agent metadata

{
  "DisplayName": "Sales Assistant v2",
  "Description": "Updated sales assistant",
  "ModelId": "anthropic.claude-sonnet-4-6",
  "PythonVersion": "PYTHON_3_12",
  "EntryPoint": "agent.py",
  "SessionSettings": {
    "IdleTimeout": 900,
    "MaxLifetime": 1800
  }
}

SYSTEM agent model change (no action query param)

{
  "ModelId": "anthropic.claude-sonnet-4-6"
}

Success (HTTP 200)

Successful response. CUSTOM update returns Message only (async). enable/disable returns “Agent enabled successfully” or “Agent disabled successfully”. SYSTEM model update returns a model-updated or already-set Message.

Async CUSTOM update triggered

{
  "Message": "Agent update triggered successfully"
}

CUSTOM agent enabled

{
  "Message": "Agent enabled successfully"
}

CUSTOM agent disabled

{
  "Message": "Agent disabled successfully"
}

SYSTEM agent ModelId changed

{
  "Message": "System agent model updated successfully"
}

SYSTEM agent already on the requested model

{
  "Message": "System agent model is already set to the requested model"
}

Errors

Documented error codes: IPV-1040, IPV-1008, AUTH-1001, AUTH-1030, AI-1004, AI-1002, GE-1044.

HTTP 400

Validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. IPV-1040 invalid action, unknown body keys, SYSTEM enable/disable, or SYSTEM body fields other than ModelId. IPV-1008 invalid update fields. AUTH-1001 missing role_id. AUTH-1030 missing ai-admin.fullaccess for SYSTEM model updates. AI-1004 when AICore is not enabled.

action is not enable or disable

{
  "Message": "IPV-1040 - Invalid elements found in input fields - 'Invalid action passed in query params'"
}

SYSTEM agents reject enable/disable

{
  "Message": "IPV-1040 - Invalid elements found in input fields - 'System agents do not support enable or disable'"
}

SYSTEM update allows only ModelId

{
  "Message": "IPV-1040 - Invalid elements found in input fields - 'Only 'ModelId' can be updated for system agents'"
}

SYSTEM update missing ModelId

{
  "Message": "IPV-1040 - Invalid elements found in input fields - 'ModelId is required to update a system agent'"
}

Missing role_id header

{
  "Message": "AUTH-1001 - Missing role information in event header"
}

Caller lacks ai-admin.fullaccess

{
  "Message": "AUTH-1030 - User is not authorized to update system agent model due to the following missing permission(s) - {'Ai Admin': ['fullaccess']}"
}

HTTP 500

Backend failure. Body is {“Message”: “<CODE> - <text>”}. AI-1002 agent not found, already enabled/disabled, or invalid AgentStatus for the requested operation. GE-1044 unexpected errors.

Agent does not exist

{
  "Message": "AI-1002 - Agent not found: b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"
}

Enable called when already enabled

{
  "Message": "AI-1002 - Agent is already enabled"
}

Agent is CREATING, UPDATING, or DELETING

{
  "Message": "AI-1002 - Agent cannot be updated while it is in UPDATING state"
}