Prompt templates
A Prompt template is the Agent layer of the model request as a versioned resource, in place of the inline instructions of an Agent draft. Vocal composes each model request from layers: the platform base, the Organization layer, the Agent layer, then the directives and context of the Turn.
On the Phase 0 host. Served since contracts 1.55.0 (deploy #61).
Write and publish a template
| Step | Operation |
|---|---|
Create a draft from variants, or as a fork of a library template | POST /v1/prompt-templates |
| Change the draft at its revision | PATCH /v1/prompt-templates/{prompt_template_id} |
| Render the draft or a version with synthetic values; writes nothing | POST /v1/prompt-templates/{prompt_template_id}/render |
| Compare two versions, or a version and the draft | GET /v1/prompt-templates/{prompt_template_id}/diff |
| Publish the draft as the next version | POST /v1/prompt-templates/{prompt_template_id}/versions |
| Activate a version | POST /v1/prompt-templates/{prompt_template_id}/versions/{version}/activate |
| See which Agent versions pin it | GET /v1/prompt-templates/{prompt_template_id}/pins |
Every save answers the lint findings of the draft and none refuses it. A publish refuses each error finding, and each warning that needs an acknowledgement and is not listed in acknowledged_warnings, in one 422 validation_failed. A render answers the section with a token estimate, the stable prefix and the names of missing values.
A variant other than default is refused with capability_not_available for now. Writing the Organization layer needs prompts:admin.
Use a template in an Agent
prompt on the Agent draft names the template, and then the draft sets no instructions. Publishing the Agent lints the template against the Agent and freezes it into the version; list the warnings it asks you to acknowledge in acknowledged_warnings of the publish. POST /v1/agents/{agent_id}/publish-check shows them first.
POST /v1/agents/{agent_id}/versions/{version}/render composes the whole request an Agent version sends, every layer with its token estimate, from synthetic directives and context, and writes nothing.
Bases, the library and evaluations
The platform bases (GET /v1/prompt-bases) and the library of templates to fork (GET /v1/prompt-library) are read-only. Evaluation suites, their runs and experiments on an Agent are in Prompt evaluations and experiments; each operation page says what it runs and what it refuses.