Create a new custom agent

POST 
/ai/agents

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.

Request

Responses

200

Agent metadata created and asynchronous AgentCore creation triggered.

Response Headers

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers

400

Validation or authorization failure. Body is {"Message": " - "}. 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.

Response Headers

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers

500

Backend failure. Body is {"Message": " - "}. AI-1003 when ModelId is not assigned to the agents component. GE-1044 for unexpected errors.

Response Headers

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers