create_agent

ArtificialIntelligenceApi.create_agent(role_id, create_agent_request_body, content_type=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

Create a new custom agent

Creates a CUSTOM AgentCore agent. AgentId must be the value returned by GET /ai/agents?action=upload-script, and the zip package must already be uploaded to that presigned URL. Required body fields: AgentId, AgentName, ModelId, Description, PythonVersion, EntryPoint, AgentType (CUSTOM). The API writes CREATING metadata, grants the caller owner access, and triggers asynchronous AgentCore runtime creation. Poll GET /ai/agents/{id} for AgentStatus READY or CREATE_FAILED. Caller must have a valid role_id and AICore enabled. AgentName must be 3-48 alphanumeric and underscore characters starting with a letter (IPV-1004; hyphens are not allowed). Duplicate AgentName returns IPV-1018.

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)

• create_agent_request_body (CreateAgentRequestBody) – (required)

• content_type (str)

• _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:

CreateAgentResponse

Returns:

Returns the result object.

Request and Response Examples

HTTP: POST /ai/agents

Request

Create a CUSTOM agent after package upload

{
  "AgentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "AgentName": "sales_assistant",
  "DisplayName": "Sales Assistant",
  "Description": "Answers questions about sales datasets",
  "ModelId": "anthropic.claude-sonnet-4-6",
  "PythonVersion": "PYTHON_3_12",
  "EntryPoint": "agent.py",
  "AgentType": "CUSTOM",
  "SessionSettings": {
    "IdleTimeout": 900,
    "MaxLifetime": 1800
  },
  "ResourceAccessMetadata": {
    "KnowledgebaseAccess": [
      {
        "KnowledgebaseId": "kb-11111111-2222-3333-4444-555555555555",
        "KnowledgebaseName": "sales_kb"
      }
    ],
    "GuardRails": [
      {
        "Id": "gr-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "Version": "1",
        "Name": "default-guardrail"
      }
    ],
    "ParameterAccess": [
      "my-ssm-parameter"
    ]
  }
}

Success (HTTP 200)

Agent metadata created and asynchronous AgentCore creation triggered.

Async creation started

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

Errors

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

HTTP 400

Validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. IPV-1008 missing/invalid fields (AgentName, ModelId, PythonVersion, EntryPoint, SessionSettings bounds, Description length, CostTags shape). IPV-1040 unknown body keys. IPV-1004 invalid AgentName format. IPV-1018 duplicate AgentName. AUTH-1001 missing role_id. AI-1004 when AICore is not enabled.

Required field missing

{
  "Message": "IPV-1008 - AgentId is required"
}

PythonVersion not in allowed set

{
  "Message": "IPV-1008 - PythonVersion must be one of: PYTHON_3_10, PYTHON_3_11, PYTHON_3_12, PYTHON_3_13, PYTHON_3_14"
}

Unknown fields in body

{
  "Message": "IPV-1040 - Invalid elements found in input fields - '{'LifecycleConfiguration'}'"
}

AgentName fails format rules

{
  "Message": "IPV-1004 - AgentName must be 3-48 alphanumeric and underscore characters only (no hyphens allowed)."
}

AgentName already exists

{
  "Message": "IPV-1018 - Invalid parameter - Agent Name, parameter value already exists, use different value."
}

Missing role_id header

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

HTTP 500

Backend failure. Body is {“Message”: “<CODE> - <text>”}. AI-1003 when ModelId is not assigned to the agents component. GE-1044 for unexpected errors.

Model not available for agents

{
  "Message": "AI-1003 - Model anthropic.claude-sonnet-4-6 is not available for agents"
}