Skip to content
Optima docs
Concepts

Optima Agents

Background AI workers that read your data, then email your team or write events and attributes, within a budget you set.

An agent is a background AI worker. You describe a job in plain language, such as "every Friday, summarise last week's campaigns and email me", and Optima runs it for you on a schedule or when an event happens. The agent reads your data with a fixed set of read-only tools, decides what to do, and can only do what its definition declares. You choose the model that does the thinking, and you cap what it may spend.

Definition, instance and run

Three words cover everything:

  • A definition says what the agent does: the prompt, what starts it (its triggers), the read tools it may call, the actions it may take, and the parameters whoever uses it fills in. Every save creates a new numbered version.
  • An instance runs one version of a definition with a model, a budget and an owner. You can run the same definition many times with different parameters, for example one weekly digest per team.
  • A run is one go: a trigger fires, the agent reads, thinks and acts, and everything it did is written to the run log.

An instance keeps the definition version it was created from. Saving a new version does not change running instances; create a new instance to use it. Once created, an instance cannot be edited: its model, parameters and budget stay as they were. To change them, create another instance.

The owner

The person who creates an instance becomes its owner, and the instance acts with that person's access for as long as it exists: their roles, their purposes and their personal-data level. The agent can never read or write more than its owner could. Other people with the right role can start, stop or switch the mode of an instance without becoming its owner. Only console users with the agents_editor role or an administrator role can create instances; an API key cannot.

If the owner loses access, for example they are removed from the environment, deactivated or lose the agents role, the instance is cancelled by the system and the run log says why.

States

StateMeaning
DraftCreated but never started.
Dry runRunning, but nothing is sent or written. The log records what the agent would have done.
LiveRunning for real.
StoppedNot running. A person stopped it, or the system did (the licence no longer includes agents, its model was removed, or five runs in a row failed; runs fail when the model is deactivated, unreachable or cleared for less personal data than the owner). A stopped instance can be started again.
CancelledEnded for good because the owner lost access: the owner was deleted, disabled or locked by an administrator, removed from the environment, or lost the agents role. A temporary lock, such as after failed sign-ins, or an inactive environment only skips or fails runs until it lifts. It cannot be started again; create a new instance.

A draft or stopped instance can be started in dry run or live. A running instance can be switched between dry run and live, or stopped. Stopping and starting never reset the budget.

Dry run

In dry run the agent does its whole job except the last step. It reads, reasons and decides, and each action it proposes is recorded as a Would have entry in the log instead of being carried out. The agent itself is not told which mode it is in, so a dry run shows what it would really do. Always start a new instance in dry run, read the log, and switch to live when you are happy.

Budget

Each instance has a budget counted in tokens, the units a model charges for:

  • A lifetime budget for the instance's whole life.
  • A budget per period (hourly, daily, weekly or monthly) that cannot exceed the lifetime budget.

When either runs out, runs stop with the status Budget used up until the next period begins, or for good when the lifetime budget is spent. If your model provider has prices set under AI models, you can enter the budget as money and Optima converts it to tokens, and the screens show the cost so far. Stopping and restarting an instance never resets its budget.

What an agent can do

Reading is limited to the read tools a definition lists, and only data its owner may see. Results leave the agent in three ways, and each must be declared in the definition:

  • Email people on your team. The recipients are the owner and any users chosen in a parameter, never customers. The email is plain text and ends with a line marking it as AI-generated, naming the instance, the model and the run. A recipient whose personal-data clearance is below the owner's is left out, and the log counts how many were dropped. The log says an email was queued, because the mail system delivers it afterwards.
  • Create events of a type the definition names, on a customer's profile. Events and attribute updates an agent writes are marked as coming from an agent, and the run log links each write to its run and model.
  • Update attributes of a customer's profile, optionally limited to a list of allowed values. Like events, they are marked as agent writes.

An agent cannot send anything to customers directly. It reaches customers only through your existing journeys: an event it writes can start a journey or enter a segment, with every consent and contact policy check that journey already applies. Events and attribute updates run with the owner's roles, so the owner needs a role that can write customer data (data_editor, engineer or an administrator role). An owner with only agents_editor can create the instance, but its event and attribute actions are refused and the system stops the instance after its failure threshold of failed runs in a row (5 by default).

Built-in agents

Besides the agents you write, Optima ships built-in agents: ready-made definitions it maintains and versions, for recurring jobs such as reports and checks. You create an instance from the Built-in tab, fill in a few parameters and choose a model and a budget. You cannot edit a built-in definition, and an existing instance stays on its version when a new one appears. Numbers in a built-in agent's emails are checked against the data it read (a guard against invented figures, not proof), and a run that cites numbers it cannot back up fails instead of sending. See built-in agents.

Continuous agents

A scheduled or event-triggered agent reacts to one moment. A continuous agent works through a whole population and keeps it up to date: for example it scores every customer in a segment, or classifies every event of one type. It processes items, which are either the profiles of a segment or the events of one type. Setup is in continuous agents in the console, and a worked example is in score customers with a continuous agent.

  • First pass, then sweeps. After you start it, the agent makes a first pass over everything in scope. From then on it sweeps on the schedule in its definition. A sweep covers items that changed since the last one, profiles that joined the segment without any change of their own (found by a check that runs at most once a day), and, if the definition sets a refresh period, items whose last result is older than that period. A change to data the agent does not read (outside its item view, or only the agent's own attributes and events) is not re-scored and does not appear in the run log; a refresh period still re-scores the item.
  • One result per item, with an explanation. For each profile or event the agent writes its attributes or events and records an explanation in the run log. An events agent reads only events that arrived after its latest start.
  • Consent. Only profiles that consented to the definition's purpose are processed; the others are left out of the scope. A profile whose objection is found right before scoring is counted as skipped.
  • Rights are checked first. Before spending anything on the model, Optima checks that the owner may read and write what the definition needs. If not, the run fails with a message naming what is missing.
  • Cost. Starting needs a cost preview: the agent processes a sample of 20 items and Optima estimates the tokens for a full pass. If the scope has grown by more than 25 % since the last preview, run a new preview before you start. The estimate covers one pass and is a guide, not a cap; your budget still decides what is spent.
  • Going live redoes the dry run. A dry run saves nothing, so when a continuous agent goes live (by switching or by starting live after a dry-run sweep) Optima forgets what the dry run processed and processes those profiles or events again, live. Work a live sweep did is not repeated. An events agent redoes the events since the start of its oldest dry-run sweep, at most 30 days back. That costs the tokens of the dry-run part again. Switching back to dry run, previews, and starting live after only live sweeps do not restart anything.
  • Budget pauses keep progress. When the budget window is used up, the sweep pauses and carries on from where it stopped when the budget resets. A pause is not a failure and does not count towards the failed runs in a row that stop an instance.
  • Failures. An item that fails gets its own Item failed entry in the log. A failed profile is retried within a day. A failed event is not retried. Some of an item's writes may already be saved when a later one fails.
  • Leaving the segment. A profile that leaves the segment keeps its last result; the agent simply stops looking at it. A segment's active switch is ignored by agents: the agent sweeps the segment's members even when the segment is switched off.
  • Summary email. If the definition asks for it, the owner gets one email when a pass finishes, and only when the pass processed at least one item.

Any definition can name a purpose. Customer data that the privacy settings protect (profiles, events, dataset records) is then read only under that purpose, and writes of events and attributes are recorded under it. A definition that writes must name a purpose. One that only reads and emails may name one, which narrows what the agent reads. The purpose must be one the owner holds: if the owner does not hold it, those reads are refused, and a model that asks for a different purpose is refused as well. Analytics results (reports, queries, metrics, campaign performance and attribution) still use all of the owner's purposes. With a purpose, the agent may see less than before. The usual consent rules apply: a profile whose consent does not allow it is skipped, and the log says so. See consent and purposes.

Who sees what

The agents_editor role builds definitions, creates instances and starts, stops or switches them. It does not read runs or the log. The agents_auditor role reads definitions, instances, runs and the log and changes nothing. Administrators and the general auditor role have access too. See licences and roles.

On this page