delete_agent

ArtificialIntelligenceApi.delete_agent(id, role_id, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

Delete a custom AI agent

Starts deletion of a CUSTOM agent. Caller must be owner. SYSTEM agents cannot be deleted (AI-1002). Agents whose AgentStatus ends with ING (CREATING, UPDATING, DELETING) cannot be deleted (AI-1002). Agents attached to AI projects must be detached first (AI-1003). On success the API sets AgentStatus to DELETING, returns 200, and continues IAM/runtime/S3 cleanup asynchronously. Caller must send a valid role_id. Requires AICore enabled.

Parameters:

  • id (str) – AgentId of the agent to delete. (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)

  • _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: DELETE /ai/agents/{id}

Success (HTTP 200)

Deletion started; cleanup continues asynchronously.

Async deletion started

{
  "Message": "Deletion started for agent 'sales_assistant'. The agent is being removed in the background and will no longer be available."
}

Errors

Documented error codes: AUTH-1001, AI-1004, AI-1002, AI-1003, GE-1044.

HTTP 400

Validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. AUTH-1001 missing role_id. AUTH-* insufficient API or owner permission. AI-1004 when AICore is not enabled.

Missing role_id header

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

HTTP 500

Backend failure. Body is {“Message”: “<CODE> - <text>”}. AI-1002 agent not found, SYSTEM agent, or in-progress status. AI-1003 agent still attached to projects. GE-1044 unexpected errors.

Agent does not exist

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

SYSTEM agents cannot be deleted

{
  "Message": "AI-1002 - System agents cannot be deleted"
}

Agent is in a transitional status

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

Agent is still linked to AI projects

{
  "Message": "AI-1003 - The agent is attached to the following projects: ['sales_project']. Please detach the agent from the projects first to continue deletion."
}