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?

​

Operator flow

​

Workspace map

​

Choose the entry path

​

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 permissions, with external notification actions reviewed;
• 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 repository analysis, code changes, focused tests, and a review-ready handoff.

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

​

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 default 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.