list_agents¶

ArtificialIntelligenceApi.list_agents(role_id, limit=None, offset=None, sortorder=None, sortby=None, projection_expression=None, filter_expression=None, action=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

List user-accessible AI agents and system agents

Returns AI agents the caller can access (owner, editor, or read-only), plus system agents that are always included. Listing is in-memory: results are filtered, sorted, and paginated in the Lambda. Caller must send a valid role_id. Requires AICore to be enabled (AI-1004 otherwise). Pagination: check next_available in the response. When “yes”, more pages exist; increment offset (1-based). When “next_available” is “no”, you have reached the last page. Default limit is 25; maximum is 1000 (IPV-1050 if exceeded). Default sort is LastModifiedTime descending. Query action=upload-script is a creation-only shortcut. It does not list agents. It returns a PUT presigned URL and a new AgentId. Upload the agent package zip to that URL, then POST /ai/agents with the same AgentId.

Parameters:

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)
limit (int) – Maximum number of agents to return per page. Defaults to 25. Maximum allowed is 1000 (returns IPV-1050 if exceeded). Ignored when action=upload-script.
offset (int) – 1-based page offset. offset=1 returns the first page. Ignored when action=upload-script.
sortorder (str) – Sort direction. Defaults to descending. Ignored when action=upload-script.
sortby (str) – Field to sort results by. Must be a listing key present on the agent items. Defaults to LastModifiedTime. Ignored when action=upload-script.
projection_expression (str) – Comma-separated list of fields to include in each agent item. Allowed keys are the listing keys (AgentId, AgentName, AgentType, IsEnabled, AgentStatus, CreationTime, CreatedBy, LastModifiedTime, LastModifiedBy, AccessType, DisplayName, Description, CostTags, UsableInChat, AgentResponseType). Invalid keys return IPV-1006. Ignored when action=upload-script.
filter_expression (str) – Comma-separated field:value pairs to filter results. AgentName and DisplayName use wildcard matching; other fields use exact match. Ignored when action=upload-script.
action (str) – Creation-only. Returns a PUT presigned URL and a new AgentId. Upload the package to the URL, then POST /ai/agents with this AgentId. Other listing query parameters are ignored.
_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:

ListAgents200Response

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: GET /ai/agents

Parameter examples¶

Name	In	Example
`projectionExpression`	query	`"AgentId,AgentName,AgentStatus,AccessType"`
`filterExpression`	query	`"AgentType:CUSTOM,AgentStatus:READY"`

Success (HTTP 200)¶

Successful response. (1) No action: paginated ListAgentsResponse with agents, count, total_count, and next_available. (2) action=upload-script: CreateAgentPackageUploadResponse with Message, PresignedUrl, and AgentId.

Paginated list of accessible agents

{
  "agents": [
    {
      "AgentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
      "AgentName": "sales_assistant",
      "DisplayName": "Sales Assistant",
      "Description": "Answers questions about sales datasets",
      "AgentType": "CUSTOM",
      "AgentStatus": "READY",
      "IsEnabled": true,
      "AccessType": "owner",
      "CreatedBy": "user1",
      "CreationTime": "2026-01-15 10:30:00",
      "LastModifiedBy": "user1",
      "LastModifiedTime": "2026-06-01 14:22:00",
      "UsableInChat": true,
      "AgentResponseType": "STREAM"
    },
    {
      "AgentId": "proj-env-DatalabellerAgent",
      "AgentName": "DatalabellerAgent",
      "DisplayName": "DatalabellerAgent",
      "Description": "System agent for dataset labelling",
      "AgentType": "SYSTEM",
      "AgentStatus": "READY",
      "IsEnabled": true,
      "AccessType": "read-only",
      "CreatedBy": "system-runner",
      "CreationTime": "2026-01-01 00:00:00",
      "LastModifiedBy": "system-runner",
      "LastModifiedTime": "2026-01-01 00:00:00",
      "UsableInChat": true
    }
  ],
  "next_available": "yes",
  "count": 2,
  "total_count": 12
}

Presigned URL and AgentId for package upload (creation)

{
  "Message": "Presigned URL generated successfully",
  "PresignedUrl": "https://ml-bucket.s3.amazonaws.com/agents/b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f/agent_package.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600",
  "AgentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"
}

Errors¶

Documented error codes: IPV-1006, IPV-1050, AUTH-1001, AI-1004, GE-1044.

HTTP 400

Validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. IPV-1006 invalid projectionExpression keys. IPV-1050 when limit exceeds 1000. AUTH-1001 missing role_id. AUTH-* when the role cannot call this API. AI-1004 when AICore is not enabled.

Invalid projectionExpression keys

{
  "Message": "IPV-1006 - Invalid input projection keys - {'InvalidField'}, valid keys are - {'AgentId', 'AgentName', 'AgentType', 'IsEnabled', 'AgentStatus', 'CreationTime', 'CreatedBy', 'LastModifiedTime', 'LastModifiedBy', 'AccessType', 'DisplayName', 'Description', 'CostTags', 'UsableInChat', 'AgentResponseType'}"
}

Limit exceeds maximum

{
  "Message": "IPV-1050 - Maximum allowed limit is 1000"
}

Missing role_id header

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

AICore not enabled

{
  "Message": "AI-1004 - AI services for feature: Agents - 'AICore' are not currently enabled in the application. Please contact the administrator to enable it."
}

HTTP 500

Backend failure. Body is {“Message”: “<CODE> - <text>”}. GE-1044 for unexpected errors.

Unexpected backend error

{
  "Message": "GE-1044 - Unexpected error - KeyError."
}