AI
Connections to AI providers and agents for all projects, activated per project - what they know and what never leaves the CMS.
Connections to providers and agents that use them are made once for all projects (Administration › AI, admins only), like storages. An agent is activated per project: the modules of a project - the schema builder, the import, creating records, the event step - only offer the agents of their purpose that are active there.
Connections
| Provider | Address (default) | Key |
|---|---|---|
| Anthropic (Claude) | https://api.anthropic.com |
required |
| OpenAI | https://api.openai.com/v1 - another one for Azure or a proxy |
required |
| Mistral | https://api.mistral.ai/v1 |
required |
| Ollama (own server) | http://localhost:11434 |
optional, for a proxy in front of it |
- A connection has a technical name, a provider, a model (e.g.
claude-sonnet-5-5,mistral-large-latest,llama3.1) and the key:$NAMEof a variable of the.env, or a value that is stored encrypted (APP_ENCRYPTION_KEY) and never returned. Sent back empty, a stored key stays. - Test asks a short question with the saved settings - a wrong key or model shows the answer of the provider.
- A connection that agents use cannot be deleted.
- Token limit: at most so many tokens (question and answer together, over all agents of the connection) per
hour, day (the default), week or month - empty: no limit. When they are used up, questions are refused until
the next period starts (
429,ai_limit, with the time). The list shows the tokens of the current period; every question is counted inai_usage.
Agents
An agent is a connection with a purpose and a prompt:
| Purpose (area) | Used by |
|---|---|
project |
Projects: plans a new project or extends the current one - entities, field groups and events |
schema |
Schema, field groups, blocks: creates and changes entities and field groups |
event |
Events: builds events on the schema (changing it only where an event needs it) |
step |
Working inside events: the step Ask AI - gets only the text of the step, no structures of the project |
import |
the import: maps the columns of a file, finds references and missing entities |
data |
creating records that fit the fields of an entity |
Every area uses the agent responsible for it - an agent of another purpose does not answer there.
- Active in: the projects that may use the agent. A new agent is active in the project it was made in. The agent always works with the structures of the project it is used in.
- Every purpose has a default prompt of the CMS. An agent without a prompt of its own follows it (and later improvements of it). A prompt of its own replaces it; Default prompt in the form goes back.
- Model: empty means the model of the connection - one connection can serve a fast model for events and a larger one for the schema builder.
- Where several agents fit, the user chooses; otherwise the first active agent of the purpose is used.
- Try it asks the agent a question with the saved settings.
Prompt caching and the log
- Caching: the system prompt - the rules and the structures of the project - is the same for every question of
a project and purpose, only the question changes. Anthropic caches it (
cache_controlon the system block, tools included): later questions read it at a tenth of the price. How long is a setting of the connection (Prompt cache): 5 minutes (default; writing costs 1.25 times) or 1 hour (writing costs 2 times - worth it when questions come more than 5 minutes apart, e.g. when you work with the assistant now and then). OpenAI caches long prompts on its own. The log shows how many input tokens came from the cache; they count for the token limit like all others. - Short requests: the structures leave out what the model does not need - field types by name (those of plugins with label and description), the length every text field has, labels that only repeat the name, empty values. The assistant for events gets field groups only by name and answers without the parts events do not use (field groups, settings of entities, removals). The step Ask AI gets no structures and no rules of building at all - only its prompt and its input, as it is asked for every record.
- Log (Administration › AI › Log): every question with exactly what was sent to the provider (the body - keys are headers and never part of it) and what came back, or the error, with tokens and duration. The newest 2,000 keep their content; older ones keep only their tokens.
Building with AI
The button with the sparkles at the bottom right (admins) opens the assistant of the area you are in - Projects, Schema (with field groups and blocks) or Events - with the agent responsible for it:
- Describe what you want to build - under Projects for this project or a new one. One entity ("a list of our locations"), a change ("orders need an e-mail address"), an event ("an e-mail to the customer for every new order") or a whole area ("a blog with authors, categories and SEO texts"). The schema is changed only where that needs it.
- The plan: the agent answers with what is there and is reused; new field groups and blocks, entities and fields; changes of existing entities and fields; fields to remove (not picked at first - they delete values); and events - each with a reason. Under Events the plan always holds at least one event (the agent is asked again otherwise); under Schema it holds no events.
- Pick and refine: untick what you do not want, or write what to change ("authors also need a photo") - the agent revises the plan.
- Create: field groups first, then the entities, the changes, the references between them and the fields for existing entities, then removals and last the events - all with the usual checks of the schema and events. An item that fails is reported; the others are created anyway.
For a new project the agent of the current project plans it - with name, technical name and languages, which can be changed before creating. The project is created, then the plan in it, and the admin app switches there. Nothing is created before Create.
POST /api/v1/admin/ai/schema/propose {"description": "…", "agent"?: "…", "new_project"?: true, "plan"?: {…}, "feedback"?: "…"}
POST /api/v1/admin/ai/schema/apply {"plan": {"field_groups": […], "entities": […], "fields": […]}}
In events
The event step Ask AI (ai) asks an agent of the purpose step (Working inside events) that is active in the
project:
{ "type": "ai", "input": "Is this message urgent, and what is it about? {{record.message}}", "as": "analysis",
"fields": [
{ "name": "urgent", "type": "boolean" },
{ "name": "topic", "type": "text", "description": "one of: order, invoice, other" },
{ "name": "tags", "type": "list" }
] }
- Only
inputgoes to the AI (with the structures of the project) - the placeholders filled in, nothing else of the record. - The answer: without
fieldsa text ({{analysis}}), withfieldsan object of exactly these fields - typestext,number,boolean,list- as{{analysis.urgent}}in the next steps,analysis.urgentin the plugin Script, e.g.if analysis.urgent… agentchooses one; empty: the first agent for events active in the project.- The test run shows the input that would be sent but does not ask the AI - nothing leaves the CMS.
What an agent knows - and what not
With every question the CMS sends the rules of the CMS, the prompt and the structures of the project: the entities with their fields (names, types, labels, required, references), the field groups and blocks, the field types (those of plugins too) and the languages - in the shape the admin API uses, so answers can be used as they are.
Agents for projects and events also get the existing events (names and triggers, not their steps), the event
sources of plugins and the steps of plugins with their label, description, fields and the plugin's own
prompt (see eventStep() in plugins.md). The rules tell them to prefer steps that work without
AI: with the plugin Script active, a value that can be computed (sums, formats, parts of a text) becomes a
script step instead of a step "Ask AI", which would cost tokens on every run.
Never sent: keys and other .env values, storages, project variables, preview addresses (they may contain
$SECRET), users, roles, API clients - and no records. Records reach the AI only where a module passes them on
on purpose: the sample rows of an import, the input of an event step (only what is written into it, e.g.
{{record.message}}).
Answers in a shape
The modules ask for an answer in a JSON schema. The CMS uses the provider's own way for it (a tool for
Anthropic - offered, not forced, as not every model allows forcing one; JSON as text is read too - response_format
for OpenAI and Mistral, format for Ollama), checks the answer against the schema
(type, properties, required, items, enum) and asks once more with the problems if it does not fit. A
second wrong answer is an error with the problems.
GET /api/v1/admin/ai providers, purposes with their default prompts
GET /api/v1/admin/ai/connections POST · PUT/DELETE …/{id} · POST …/{id}/test
GET /api/v1/admin/ai/agents?purpose=schema&active=1 POST · PUT/DELETE …/{id} · POST …/{id}/try {"question": "…"}
agents take "projects": ["shop", "blog"] - where they are active