Skip to content
Optima docs
ConsoleAgents

Agent instances

List running agents and create an instance of a definition with a model, a budget and parameters.

An instance runs one version of a definition with a model, a budget and an owner. The Instances tab of the Agents screen lists them all and is where you create new ones.

Who uses it

Campaign managers and tenant administrators. Reading the list needs agents_editor, agents_auditor or an administrator role. New instance appears only for console users with agents_editor or an administrator role, and the person who creates an instance becomes its owner, which it keeps for life. See Optima Agents.

The Instances tab listing agents with their definition, state, owner, model and budget used this period

Fields

The list shows:

ColumnMeaning
NameOpens the instance detail.
DefinitionThe definition and its version, for example Weekly digest@2.
StateDraft, Dry run, Live, Stopped or Cancelled.
OwnerThe person whose access the instance uses.
ModelThe model it thinks with, or Model removed if the provider was deleted.
This periodA bar of the tokens used out of this period's budget.

New instance opens a dialog:

FieldMeaningValid valuesDefault
NameA name for this instance.Text, up to 200 charactersEmpty
DefinitionWhich definition to run. Archived ones are not offered.A definitionNone
Definition versionWhich version to run. The instance keeps it.A version numberThe current version
ModelThe text model provider. Shows its prices when it has them.One of your active text modelsYour default text model
ParametersOne input for each parameter the definition declares: text, number, duration, users, a segment, a campaign, and for built-in agents also switches, schedules, lists of campaigns, metrics or forms, and lists of values. See built-in agents.Per parameterEmpty
Lifetime budgetThe most the instance may use in its whole life. In Tokens, or in Money when the model has prices (with the token equivalent shown).Above zero1,000,000 tokens
Budget periodThe window for the periodic budget.Hourly, Daily, Weekly, MonthlyDaily
Budget per periodThe most it may use per window; not above the lifetime budget.Above zero100,000 tokens
Time zoneWhere schedule triggers and period windows are counted.A time zoneYour own
Run limitsOptional bounds for each run, in a collapsed section. See Run limits.Per limitThe defaults

The model, the parameters, the budget and the run limits cannot be changed after creation. To change any of them, create a new instance.

Run limits

Every run of an instance is bounded by seven limits. Open the collapsed Run limits section of the New instance dialog to change any of them. Each field shows its default as a placeholder; leave a field empty to use the default. A value equal to the default is not stored, so the instance keeps following the default if Optima changes it later.

LimitWhat it boundsDefaultAllowed range
TurnsHow many times the agent calls the model in one run.241 to 64
Tool callsHow many tools it may call in one run. A run that finishes needs one turn for its final answer, so it makes at most one tool call fewer than the turn limit. Keep this below the turn limit.201 to 60
Run deadlineHow long an event or schedule run may take, in seconds. A run past it fails as a deadline overrun.600 s60 to 1,800 s
Tool results per runThe total size of the tool results the agent may collect in one run, in KiB. Once it is reached, further tool calls are refused and the agent has to finish with what it has.192 KiB16 to 512 KiB
One tool resultThe largest single tool result shown to the model, in KiB. Longer results are cut. A single record larger than this comes back empty, so very small values starve the agent. It cannot be larger than the tool results per run.32 KiB4 to 128 KiB
RepairsHow many times the agent may be asked to correct an answer that fails the checks.20 to 5
Failures before stopHow many failed runs in a row stop the instance.51 to 20

Things to weigh before changing a limit:

  • Cost. Every turn resends the whole conversation, so more turns and larger tool results raise the worst-case cost of a run. The budget still applies, and a period budget may refuse runs earlier.
  • Context window. Above about 384 KiB of tool results per run, a model with a 200,000-token context window can fail the run. Raise this limit only for models with a large context window.
  • Continuous agents. The run deadline does not apply to continuous agents; a sweep runs for up to 55 minutes. The tool-result budget applies to every chunk of the sweep, and each chunk resends the first chunk's results, so a larger value raises the cost of every model call in the sweep.
  • Short deadlines. A 60-second deadline with a slow model ends runs as failures, and failures count toward the stop. A long deadline occupies one of the shared agent workers for that long.
  • Stopping on the first failure. With 1, a single temporary error, such as a model timeout, stops the instance.
  • Built-in agents. They are tuned for the default limits. Lowering turns, tool calls, the deadline or the tool results per run can make their runs fail. The dialog says so when you choose a built-in definition.

Limits are set when the instance is created and cannot be changed later. To use other limits, create a new instance. The instance detail shows the limits in force, and the run log shows the limits each run ran with.

Actions

  • New instance creates a draft. Open it and start it in dry run.
  • Choose a row's name to open it.

Examples

A weekly digest for the marketing team: definition Weekly digest, the Users parameter set to the three managers, a lifetime budget of 2,000,000 tokens and a weekly period of 100,000.

Common problems

  • No New instance button. You lack the agents_editor role, or are signed in with an API key.
  • Add an AI model first. Agents need a text model; add one in AI models.
  • Create a definition. There is nothing to run yet; see definitions.
  • The create dialog says the period budget cannot exceed the lifetime budget. Lower the period budget.
  • A run limit is flagged in red. Enter a whole number inside the allowed range. One tool result cannot be larger than the tool results per run.
  • I need to change a run limit. Limits cannot be edited. Create a new instance with the limits you want.
  • Model removed. The provider was deleted. The instance stops; create a new one with another model.

On this page