get_agent_details¶

ArtificialIntelligenceApi.get_agent_details(id, role_id, projection_expression=None, action=None, start_time=None, end_time=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Get AI agent details, package URLs, or logs

Default (no action): returns details for agent {id}. CUSTOM agents require at least read-only resource access. SYSTEM agents are returned with a reduced field set and AccessType read-only. ARN attributes are omitted. CUSTOM agents include ReferenceId when the AgentCore runtime exists. Query action selects an alternate 200 shape. Logs and package actions are CUSTOM-only (AI-1002 for SYSTEM). Time range for log actions is Unix milliseconds; omitted start-time/end-time default to the last hour; the range cannot exceed 30 days (IPV-1008). action=retrieve-script: presigned GET URL for agents/{id}/agent_package.zip (or PackageExists=false). action=upload-script: presigned PUT URL to replace the package (then PUT /ai/agents/{id} to apply). action=view-logs: processed CloudWatch logs. action=generate-logs: starts async S3 processing (poll download-logs). action=download-logs: presigned GET URLs for existing processed JSON files.

Parameters:

id (str) – AgentId of the agent to retrieve. (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)
projection_expression (str) – Reserved listing-style projection parameter. Not applied to the default details payload in the current handler.
action (str) – Alternate response. retrieve-script downloads the package. upload-script is the update-flow PUT URL. view-logs returns CloudWatch logs. generate-logs triggers async S3 storage. download-logs returns presigned URLs for existing processed files.
start_time (str) – Unix timestamp in milliseconds for view-logs, generate-logs, and download-logs. Defaults to one hour before the request. Must be a positive integer less than end-time. Range cannot exceed 30 days.
end_time (str) – Unix timestamp in milliseconds for view-logs, generate-logs, and download-logs. Defaults to the request time. Must be a positive integer greater than start-time.
_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:

GetAgentDetails200Response

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: GET /ai/agents/{id}

Success (HTTP 200)¶

Successful response. Shape depends on action: agent details; retrieve-script package download; upload-script package upload URL; view-logs; generate-logs trigger; or download-logs URLs.

CUSTOM agent details (no action)

{
  "AgentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "AgentName": "sales_assistant",
  "DisplayName": "Sales Assistant",
  "Description": "Answers questions about sales datasets",
  "AgentType": "CUSTOM",
  "AgentStatus": "READY",
  "AgentVersion": "1",
  "ModelId": "anthropic.claude-sonnet-4-6",
  "ReferenceId": "sales_assistant-abc123",
  "AccessType": "owner",
  "CreatedBy": "user1",
  "CreationTime": "2026-01-15 10:30:00",
  "LastModifiedBy": "user1",
  "LastModifiedTime": "2026-06-01 14:22:00",
  "IsEnabled": true,
  "UsableInChat": true,
  "AgentResponseType": "STREAM",
  "PythonVersion": "PYTHON_3_12",
  "EntryPoint": "agent.py",
  "SessionSettings": {
    "IdleTimeout": 900,
    "MaxLifetime": 1800
  },
  "ResourceAccessMetadata": {
    "KnowledgebaseAccess": [
      {
        "KnowledgebaseId": "kb-11111111-2222-3333-4444-555555555555",
        "KnowledgebaseName": "sales_kb"
      }
    ]
  }
}

Package download URL when the zip exists

{
  "Message": "Agent package download URL generated successfully",
  "DownloadUrl": "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",
  "PackageExists": true,
  "S3Location": "s3://ml-bucket/agents/b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f/agent_package.zip",
  "ExpiresIn": 3600
}

Package not found

{
  "Message": "Agent package not found",
  "AgentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "PackageExists": false
}

Package upload URL for an existing agent

{
  "Message": "Agent Package update 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"
}

Processed CloudWatch logs

{
  "Message": "Successfully retrieved and processed 1 log events from CloudWatch",
  "LogsCount": 1,
  "AgentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "TimeRange": {
    "StartTime": "1735689600000",
    "EndTime": "1735693200000"
  },
  "Logs": [
    {
      "timestamp": 1735690000000,
      "message": "Agent invocation completed",
      "logStream": "runtime/prod",
      "eventId": "evt-1",
      "ingestionTime": 1735690001000,
      "agentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
      "processedAt": "2026-01-15 10:30:00"
    }
  ]
}

Async log generation triggered

{
  "Message": "Agent logs generation triggered successfully.",
  "AgentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"
}

No CloudWatch logs in the time range

{
  "Message": "No logs found for the specified agent and time range",
  "LogsCount": 0,
  "AgentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "TimeRange": {
    "StartTime": "1735689600000",
    "EndTime": "1735693200000"
  },
  "Logs": []
}

Presigned URLs for processed log files

{
  "Message": "Successfully generated 1 download URLs for processed log files",
  "FilesFound": 1,
  "AgentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "TimeRange": {
    "StartTime": "1735689600000",
    "EndTime": "1735693200000"
  },
  "DownloadUrls": [
    {
      "filename": "processed-logs-1735690000.json",
      "s3Key": "agents/b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f/logs/2026-01-15/processed-logs-1735690000.json",
      "downloadUrl": "https://ml-bucket.s3.amazonaws.com/agents/b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f/logs/2026-01-15/processed-logs-1735690000.json?X-Amz-Expires=3600",
      "size": 2048,
      "lastModified": "2026-01-15T10:30:00+00:00"
    }
  ]
}

No processed log files in the time range

{
  "Message": "No processed log files found for the specified agent and time range",
  "FilesFound": 0,
  "DownloadUrls": [],
  "AgentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "TimeRange": {
    "StartTime": "1735689600000",
    "EndTime": "1735693200000"
  }
}

Errors¶

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

HTTP 400

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

start-time not less than end-time

{
  "Message": "IPV-1008 - StartTime must be less than EndTime"
}

Log window exceeds 30 days

{
  "Message": "IPV-1008 - Time range cannot exceed 30 days"
}

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 agents for log/package actions, CloudWatch errors. GE-1044 unexpected errors. Missing agents are not returned as 404.

Agent does not exist

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

Logs and package actions are CUSTOM-only

{
  "Message": "AI-1002 - System agents do not support logs-related requests"
}