Create an agent (or get-or-create by name)

Changed on

Creates a cloud agent owned by the authenticated account. With if_exists: "return" this is get-or-create: if an agent with the same name exists, it is returned (200, existing: true) instead of creating a duplicate. Prefer this and one long-lived agent. The owner is always the credential's account; a user_id in the body is ignored.

post/v1/agents

Request

  • Base URL: https://api.plori.ai
  • URL: https://api.plori.ai/v1/agents
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Required with kind independent (nonempty, at most 255 bytes). For that kind, if_exists is forbidden.

Request body

namestring required
modelstring

Model slug; omit for the Plori Router default.

configobject

Opaque agent config; defaults to {}.

if_exists'return' | 'error'

"return" = get-or-create by name; "error" (default) = always create.

kind'compatibility' | 'independent'

Independent identities run only as Workspace members. Omit for a compatibility Agent.

Response

Existing agent returned (get-or-create hit).

idstring uuid
user_idstring uuid
namestring
backendstring
modelstring
configobject
entity_disk_idstring
statusstring

Warm-session state when known: warming, ready, or sleeping.

deletingboolean

True while this agent's disk is still being erased. The agent offers no actions except deletion itself, which is idempotent and the only way to finish a stuck one.

deleting_sincestring date-time nullable

When the erasure was first asked for. Absent when the agent is not being deleted.

created_atstring date-time
existingboolean

Changes

  • 2234a20f0150Revision changes
    • warning

      removed the optional property //// from the response with the status

    • warning

      removed the optional property from the response with the status