Agent configuration

An Agent definition combines a stable operational identity with an execution principal, runtime defaults, capabilities, and safety policy. This page documents the configuration accepted by the current Platform API and explains how it maps to the General, Identity, Runtime, Tools, Plugins, Memory, and Terminals sections in the Agents workspace.

Configuration model

Agent settings are intentionally split into three layers:

Layer	Purpose	Typical fields
Agent record	Identity, ownership, availability, and audit metadata	`name`, `desc`, `status`, owner, service account, metadata
`config`	Normal runtime behavior and Agent-owned capability attachments	model, reasoning, definition, instructions, automation, memory instructions, plugins, terminals, limits
`policy`	Operator-enforced permissions and ceilings	default and per-tool access, policy plugins, concurrency and delegation limits

The effective runtime behavior is derived from platform policy, the Agent policy, the Agent configuration, and the current trigger. A configuration value cannot broaden a permission denied by the service account, tenant policy, or a more restrictive Agent policy. The current Agents UI covers the common operating settings. Top-level metadata, the structured definition, and advanced automation policy are API-managed fields.

Updating config or policy replaces that complete nested object. Read the current Agent, preserve unchanged sibling fields, and submit its current version to prevent overwriting a newer edit.

Identity, ownership, and profile

Agent record

Field	Required	Behavior
`name`	Yes	Stable operator-facing name. The UI limits it to 160 characters.
`desc`	No	Short responsibility and outcome summary. The UI limits it to 500 characters.
`serviceAccountUserId`	Yes	Active service-account user used as the execution principal. Runs do not inherit the owner’s permissions.
`ownerId`	No	User or group that owns visibility and management. Defaults to the current user when omitted.
`ownerType`	No	Normally `USER` or `GROUP`.
`metadata`	No	Customer metadata, up to 16 KiB and 64 top-level keys. Keys beginning with `__` are reserved.
`status`	Update only	`ACTIVE`, `PAUSED`, or `DISABLED`. New Agents are active.
`version`	Update only	Optimistic-lock value returned by the latest read.

The Agent avatar is managed separately from the Agent update payload. Upload or clear it from the Agent detail rather than embedding image data in metadata.

Structured definition

Use config.definition for the stable, operator-owned role contract that is applied to autonomous work:

Field	Limit	Use
`identity`	500 characters	What the Agent is and the boundary of its role
`mission`	2,000 characters	The durable outcome it owns
`responsibilities`	24 items, 500 characters each	Work the Agent is expected to perform
`operatingPrinciples`	24 items, 500 characters each	Rules for evidence, escalation, quality, and communication
`successCriteria`	24 items, 500 characters each	Observable conditions for a successful outcome

Keep the definition focused on durable identity and policy. Put detailed procedures, examples, and large reference material in the governed Agent workspace so operators can review and maintain them independently. config.systemInstructions adds Agent-specific operating guidance. It is subordinate to platform safety policy and does not bypass approvals or access control.

Work mode and persona

The Agents UI also stores two profile presets:

workMode: balanced, coding, business, analyst, operator, or creative;
persona: friendly, pragmatic, professional, concise, calm, mentor, or assertive.

Use them to describe the intended working style and operator-facing tone. Put requirements that must consistently govern autonomous execution in definition and systemInstructions; profile presets are not security or completion policy.

Do not send the removed profile or meta objects. Use config.definition, workMode, persona, and top-level metadata instead.

Model, reasoning, and planning

Supported values

Setting	Accepted values	Notes
`config.model`	A model enabled for the current RevoEngine release and instance	Availability can differ by instance configuration.
`config.reasoningEffort`	`low`, `medium`, `high`, `xhigh`	Higher effort is useful for ambiguous, multi-system, or high-risk work.
`config.executionMode`	`interactive`, `execute`, `background`, `automation`	The UI offers interactive, background, and automation. Durable unattended work normally uses background or automation.
`config.planningPolicy`	`standard`, `review_required`	`review_required` creates a review gate before executing the plan.

Choose the model and reasoning effort from task risk, ambiguity, latency, and cost requirements. Validate the selected combination with a representative bounded run before enabling recurring work.

Choose explicit operating defaults

For production Agents, set the intended model, reasoning effort, execution mode, planning policy, and limits explicitly. This makes reviews and environment promotion predictable without relying on release-specific UI defaults.

Permissions and tools

Choose the Agent’s default permission level in the Tools section:

Permission	Behavior
Restricted	Read-only work and actions explicitly permitted without approval can proceed. Approval-sensitive changes, side-effecting code, and external actions wait for the user.
Auto Review	When an action would otherwise need approval, RevoEngine checks it against the user’s explicit request and available authorized context. Clearly matching actions can continue automatically; uncertain or higher-risk actions wait for the user.
Full Access	Normal per-action approval prompts are skipped. Service-account permissions, tenant rules, target access, plugin restrictions, and validation still apply.

Capability-specific overrides can narrow or expand the level for a selected capability. Enabling a capability is not an access grant: execution still depends on the service account, instance policy, target access, and the capability’s own restrictions. See Approvals and plans for the decision model and Tools and skills for capability discovery.

Plugins

There are two attachment layers:

config.pluginIds contains the Agent-owned default plugin attachments;
policy.pluginIds contains governance-managed attachments applied to Agent work.

Both accept up to 64 plugin UUIDs. A direct run can add up to 32 registry plugins for that run without changing the Agent definition. Normal product configuration should reference active, reviewed registry plugins rather than embedding private integration configuration in the Agent payload. The Plugins tab shows explicit attachments and inherited active instance defaults. Autonomous Agents discover and execute only plugins in their effective attachment set; they do not automatically discover unrelated installed plugins. config.eagerPluginIds selects up to 64 attached or inherited plugin UUIDs to load at the start of work. Loading a plugin does not grant additional permissions. Plugin safety metadata, approval mode, side-effect classification, and operating limits remain enforceable after attachment. See Plugins.

Inbox and trigger delivery

config.automation.defaultDeliveryMode decides how Events, Schedules, and Agent handoffs enter the Agent when the trigger does not override it:

Mode	Behavior	Best for
`INBOX`	Persists queued work before a run claims it	Auditable workloads, prioritization, delays, and de-duplication
`DIRECT_RUN`	Creates a run immediately	Bounded, latency-sensitive work with controlled concurrency

The create form defaults to INBOX.

Inbox item fields

Field	Required	Contract
`instruction`	Yes	Non-empty task instruction passed to the run when claimed
`type`	No	Logical type, up to 128 characters
`payload`	No	JSON object copied into run state
`priority`	No	Integer from 0 to 1,000; higher values are claimed first
`scheduleFor`	No	ISO timestamp with timezone or Unix milliseconds, from request acceptance through 30 days ahead. The item is recorded immediately and becomes claimable at this time.
`dedupeKey`	No	Up to 255 characters; unique per Agent among non-terminal items

Use a deterministic de-duplication key for retried webhooks and recurring producers, for example invoice:2026-09:customer-42.

Direct run fields

A direct run requires instruction and can include:

triggerType, triggerRefType, and triggerRefId for correlation;
scheduleFor as an ISO timestamp with timezone or Unix milliseconds, up to 30 days ahead;
a JSON state object for run-scoped context;
up to 32 additional pluginIds.

Do not use run state for secrets or durable files. Keep secrets in Secrets and persistent output in the Agent workspace. A delayed direct run is visible immediately as CREATED, with scheduledFor in its details. It does not occupy an execution slot while waiting for its initial time. Once due, it must pass the Agent’s concurrency gate; waiting for capacity is PENDING with a capacity wait reason. Later continuation wake times are separate from the original accepted schedule.

Use scheduleFor for both Inbox and direct runs. A past public timestamp or one more than 30 days ahead is rejected. An already accepted request that reaches dispatch after its time becomes immediately eligible; eligibility is not a promise of an exact start time.

Delegation and limits

Setting	Accepted range	Effective behavior
`maxActiveRootRuns`	1–32	Concurrent admitted root runs; excess work waits for capacity
`maxChildRuns`	1–128	Total delegated child runs available to one parent plan
`maxConcurrentChildRuns`	1–32	Children started in parallel, never greater than the effective child-run total
`maxTicks`	1–1,000	Explicit execution-tick ceiling; omit it when the Agent should not have a fixed tick budget
`childFailureMode`	`fail_parent`, `merge_partial`	Stop the parent on child failure or merge verified partial results

Limits can be present in both config and policy. For concurrency and child limits, the lower configured or policy value wins. policy.maxTicks overrides config.maxTicks. merge_partial is effective when selected in either layer; otherwise failure mode is fail_parent. Start with one root run and two concurrent children. Increase concurrency only after the service account, downstream rate limits, idempotency, and output-merge behavior have been tested.

Memory configuration

The Memory tab edits one Agent-owned text value, config.memory, with a live counter and a 20,000-token limit. The current value is included in the Agent instructions for every model request, including after a memory update during a run. An empty value adds no memory instructions. Agent memory tools read and update this same text. Updates are version-aware: a concurrent configuration or memory change requires a fresh read rather than silently overwriting newer content. Existing typed Agent memory records remain historical evidence and are not automatically recalled into Autonomous Agent requests. Interactive Assistant user memory keeps its existing behavior. Use Agent memory for durable operating knowledge, session checkpoints for in-progress continuity, and workspace files for large or exact content. See Memory and workspaces.

Terminal access

The Terminals tab searches terminals available to the Agent’s selected service account. config.agentTerminalIds selects up to 64 terminal UUIDs; an empty selection grants no terminal access. Unrestricted terminals and restricted terminals accessible through the account’s permissions or group membership can appear in this list. Selection narrows access; it cannot expand the service account’s authorization. Terminal execution checks the current account access again before dispatch. Changing the service account requires reviewing its terminal selections. See Terminals for execution and workspace controls.

Workspace configuration

Every successfully created Agent receives a managed workspace. Workspace assignment is changed through its dedicated operation rather than generic Agent configuration:

Mode	Required values	Behavior
`MANAGED`	Current `version`	Creates and links a new managed Agent workspace
`EXISTING`	`storageEntryId`, current `version`	Links an authorized regular Storage folder

Workspace replacement is blocked while the Agent has active runs. An existing folder must be accessible under the applicable Agent and operator authorization; another Agent’s managed workspace cannot be attached as a shared folder.

Managed automation settings

Automation policy can define how approval-required work is escalated and how managed notifications are delivered. These settings record operator intent; they do not bypass runtime approval policy, identity, or target access. Treat advanced automation fields as managed configuration and validate the current OpenAPI schema before generating them programmatically.

Complete example

The following creation payload uses registry plugins and keeps policy separate from Agent-owned defaults:

{
  "name": "Release evidence coordinator",
  "desc": "Collects release evidence, verifies required checks, and prepares an operator-ready summary.",
  "serviceAccountUserId": "11111111-1111-4111-8111-111111111111",
  "ownerType": "GROUP",
  "ownerId": "22222222-2222-4222-8222-222222222222",
  "metadata": {
    "costCenter": "platform-operations"
  },
  "config": {
    "reasoningEffort": "high",
    "executionMode": "automation",
    "planningPolicy": "standard",
    "workMode": "operator",
    "persona": "professional",
    "systemInstructions": "Report only verified release evidence and identify missing checks explicitly.",
    "definition": {
      "identity": "Release evidence coordinator for production services.",
      "mission": "Produce a complete, verifiable release readiness record.",
      "responsibilities": [
        "Collect build, test, migration, and release evidence.",
        "Escalate missing or contradictory evidence."
      ],
      "operatingPrinciples": [
        "Distinguish verified facts from recommendations.",
        "Never expose secret values in reports."
      ],
      "successCriteria": [
        "Every required check has a result or a named blocker.",
        "The final summary links to durable workspace artifacts."
      ]
    },
    "memory": "Release summaries lead with validation and rollback status.",
    "automation": {
      "defaultDeliveryMode": "INBOX"
    },
    "pluginIds": ["33333333-3333-4333-8333-333333333333"],
    "maxActiveRootRuns": 1,
    "maxChildRuns": 4,
    "maxConcurrentChildRuns": 2,
    "maxTicks": 48,
    "childFailureMode": "fail_parent"
  },
  "policy": {
    "maxActiveRootRuns": 1,
    "maxChildRuns": 4,
    "maxConcurrentChildRuns": 2,
    "maxTicks": 48
  }
}

Operate Agents

Run, inspect, recover, and scale durable Agent work.

Autonomous Agents

Return to the Agent product overview.

Start here

Interactive Agents

Autonomous Agents

Extend Agents

Configuration model

Identity, ownership, and profile

Agent record

Structured definition

Work mode and persona

Model, reasoning, and planning

Supported values

Choose explicit operating defaults

Permissions and tools

Plugins

Inbox and trigger delivery

Inbox item fields

Direct run fields

Delegation and limits

Memory configuration

Terminal access

Workspace configuration

Managed automation settings

Complete example

Operate Agents

Autonomous Agents

​Configuration model

​Identity, ownership, and profile

​Agent record

​Structured definition

​Work mode and persona

​Model, reasoning, and planning

​Supported values

​Choose explicit operating defaults

​Permissions and tools

​Plugins

​Inbox and trigger delivery

​Inbox item fields

​Direct run fields

​Delegation and limits

​Memory configuration

​Terminal access

​Workspace configuration

​Managed automation settings

​Complete example

Operate Agents

Autonomous Agents

Configuration model

Identity, ownership, and profile

Agent record

Structured definition

Work mode and persona

Model, reasoning, and planning

Supported values

Choose explicit operating defaults

Permissions and tools

Plugins

Inbox and trigger delivery

Inbox item fields

Direct run fields

Delegation and limits

Memory configuration

Terminal access

Workspace configuration

Managed automation settings

Complete example