Operate Agents

The Agents workspace is the operating console for durable AI work. It combines the Agent definition, current health, runs, queued inbox items, workspace files, and execution evidence so operators can answer one question quickly: what is this Agent responsible for, and what happened to its work? The Agent Harness provides the shared execution boundary behind both interactive and autonomous work.

​

Operator flow

​

Workspace map

​

Choose the entry path

​

Start work from the conversation list

Open the Agent group menu and choose New conversation for direct work in the inline composer, or New Inbox message for queued work. Write the task in Instructions; a title is generated when omitted. For Inbox deliveries, Schedule adds a delay or date and Advanced exposes priority, structured input, and an optional Duplication key. Open Configure or Storage from the same Agent menu to manage the definition or workspace without losing the conversation list. A conversation’s options menu archives terminal conversations while preserving durable Runs. Complete or cancel active work first. Messages and tool activity use the live conversation stream, including reconnection from the last retained event. Respond to an approval, clarification, or plan in the conversation using the same controls as Assistant Threads. RevoEngine checks your Agent permissions and the current decision version, then queues a successor Run under the original execution principal. Repeating the same response returns that Run; a conflicting or outdated response requires refreshing the conversation. Tools execute in the durable worker, and their progress continues in the same conversation. Secure credential actions require their dedicated flow.

​

Inbox-first pattern

Inbox is the safest default for operational automation:

1. the producer persists an instruction and correlation payload;
2. non-terminal duplicates with the same key are rejected or reused rather than multiplied;
3. the highest-priority available item is claimed when the Agent has capacity;
4. the item links to the run that owns its execution;
5. terminal result or error remains inspectable with the original item.

Use DIRECT_RUN for latency-sensitive work only after concurrency, idempotency, and downstream limits are understood.

​

Run lifecycle

A normal run progresses through CREATED, PENDING, and PROCESSING to FINISHED. It can instead enter ACTION_REQUIRED, ERROR, or CANCELLED. Pending work is not necessarily unhealthy. It can be waiting for its availability time, Agent capacity, child work, reconciliation, or another durable condition. Inspect the wait reason before retrying.

​

Plans, approvals, and action required

Use review_required when the scope or proposed changes must be approved before execution. Tool-level approval still applies independently: a standard plan can reach an approval gate, and an approved plan does not authorize an unrelated or more dangerous operation. When a run reaches ACTION_REQUIRED:

• read the requested action and the operation it would authorize;
• confirm the target, scope, and reversibility;
• verify that the selected operator is allowed to approve it;
• approve, reject, or supply clarification through the run control;
• confirm the run resumes and records the outcome.

See Approvals and plans for the full safety model.

​

Delegated work

Delegation is useful when independent subtasks can run in parallel and their results can be verified before merge. A parent run owns the plan, child-run budget, concurrency, and merge behavior. Use child runs for independent evidence collection, separate systems, or naturally partitioned analysis. Keep work in the parent when steps share mutable state, must execute in strict order, or would create conflicting external actions. The two failure strategies are:

• fail_parent: stop the parent when a required child fails;
• merge_partial: continue only when partial results are useful and the final output can identify missing evidence explicitly.

Child runs inherit governed execution boundaries. Delegation does not grant the parent or child a different service-account identity, bypass approvals, or escape the Agent workspace.

​

Production use cases

​

Incident evidence coordinator

Use an Agent to collect alert context, inspect relevant platform traces, correlate recent changes, and prepare an escalation note. Recommended starting configuration:

• Operator work mode and a model/reasoning combination validated for incident analysis;
• Inbox delivery with an incident-id de-duplication key;
• one active root run and fail_parent for required evidence;
• Auto Review, with external notification actions still routed to the user when they require manual approval;
• a managed workspace for evidence and the final incident report.

Success means the Agent distinguishes verified evidence from hypotheses and names missing access instead of inventing a root cause.

​

Release readiness coordinator

Use an Agent to gather build, test, migration, security, and rollout evidence across a release.

• Trigger from a recurring schedule or release event;
• store check results and the final release record in the workspace;
• delegate independent evidence sources with bounded concurrency;
• use merge_partial only if the output must remain useful while clearly marking incomplete checks;
• require review before mutations or rollout actions.

​

Data-quality and reconciliation worker

Use an Agent to compare source totals, detect anomalies, and prepare an exception report.

• Use one Inbox item per period and data domain;
• use a deterministic period/source de-duplication key;
• keep source-of-truth rules in the structured definition or governed workspace instructions;
• grant read access broadly enough for reconciliation, but review corrections separately;
• continue a terminal run for operator questions rather than changing the historical result.

​

Agentic engineering worker

Use an Agent for bounded changes to RevoEngine application definitions such as Components, Endpoints, plugins, and other authorized platform resources.

• Coding work mode and a model/reasoning combination validated for the resource and task class;
• review_required for broad or high-risk modifications;
• explicit success criteria for validation, changed definitions, and operational evidence;
• conservative child concurrency to avoid overlapping changes;
• workspace-scoped artifact writes and approval for changes outside the assigned boundary.

An Autonomous Agent can use explicitly selected terminals within its service account permissions. An Interactive Agent can use a terminal approved by its owner, including one running in a virtual machine. Terminal access remains governed by the selected terminal and workspace controls. Use a repository-first coding agent when the task requires a workspace and toolchain that are not connected to RevoEngine.

​

Integration operations coordinator

Use an Agent to inspect integration health, prepare synchronization work, and call an approved MCP or component plugin.

• attach the active registry plugin rather than copying its definition;
• use the plugin’s declared mutation, reversibility, and target scope;
• keep external writes under Restricted or Auto Review until the operation is proven idempotent;
• preserve upstream correlation ids in the trigger payload and run trace;
• never place bearer tokens or secret values in instructions, Inbox payloads, or workspace files.

​

Change management

Before changing model, instructions, plugins, permissions, workspace, or concurrency:

1. inspect active runs and Inbox backlog;
2. pause the Agent if the change could alter in-flight behavior;
3. finish or cancel active runs before replacing the workspace;
4. read the latest Agent version and submit it with the update;
5. run a bounded validation task;
6. compare outcomes and traces before restoring wider trigger delivery.

Deleting an Agent is a lifecycle operation, not a cleanup shortcut. Active work is cancelled, and references from schedules or events can block deletion until the automation is updated. Restore is available for soft-deleted Agents; review workspace and trigger state before reactivation.

​

Operational checklist

• The mission has an accountable human or group owner.
• The service account is active and least privilege.
• Success criteria are measurable and do not depend on undocumented assumptions.
• Tool and plugin actions have correct approval and side-effect classifications.
• Inbox producers use correlation and de-duplication keys.
• Root, child, concurrent-child, and tick limits match downstream capacity.
• Required output is persisted before the run claims completion.
• Action-required and failed runs have an operator path.
• Retry behavior is safe for external side effects.
• Run events and workspace artifacts are sufficient to explain the outcome.