Create an agent from a template
Creates a draft agent from a template at the caller’s home. Requires permissions agents:manage and agents:write.
v2 compatibility notes
POST /api/v2/agents/createFromTemplate creates a draft agent from an agent template, with the template’s skills and tool sets granted, and answers 201 with { id, agentId, templateId }. The body is { templateId, agentId, name, orgUnitId? }: templateId from listAgentTemplates, agentId the new agent’s unused slug, and name its display name.
Where the agent lives
- An External App creates the agent at its owning org unit. An App with no owning org unit, or one that names another
orgUnitId, is403 forbidden. - A Personal key creates the agent at the
orgUnitIdit names, or at its owner’s home when it names none. - A platform key has no home and is
403 forbidden: create agents with a Personal key or an External App.
Authority
The credential’s scopes must includeagents:manage and agents:write. At the new agent’s home you need agents:manage, agents:write and agents:read; otherwise the answer is 403 permission_denied, recorded as a refused request, and nothing is written. An unknown orgUnitId gets the same 403.
Conflicts
An unknown template is404 resource_missing (Template not found). A slug already in use, a slug that cannot be reused yet, and a template with no definition are 409 conflict. The creation is audited as agent_created, naming the template, with the key’s owner or the App as the actor.
Replay
With anIdempotency-Key, a repeat of the same request within 24 hours returns the recorded answer only while the slug still names the same agent definition, you may still read the agent at its home, and you still hold the route’s permission there (the agent_write replay rule). Otherwise the repeat is 409 conflict and the write never runs twice.Authorizations
Headers
1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.
1 - 255
