Skip to main content
Agent Evolution continuously improves an agent’s prompts, policies, rules, and domain capabilities based on real business execution. It turns runtime feedback into verifiable candidate versions, then evaluates and progressively releases them in isolated environments.
Agent Evolution does not allow an Agent to directly modify production prompts, rules, code, or business tables. An Agent can only generate proposals and Candidates. A Candidate becomes a new immutable Production Capability Version only after evaluation, approval, and release governance.

​
When to use Agent Evolution

You can integrate a capability with Agent Evolution when its behavior can be declared, versioned, and replayed. Examples include:
  • Field mappings, aliases, and extraction policies
  • Normalization rules, unit mappings, and dictionaries
  • Routing weights, thresholds, and retrieval policies
  • Prompt, Skill, or model selection policies
The domain plugin defines what can evolve. The platform provides generic learning, evaluation, approval, release, versioning, and audit capabilities without interpreting domain semantics.

​
Before you begin

Make sure that:
  • A plugin that provides an Evolution Target is installed in the current tenant and organization.
  • You have permission to view Agent Evolution. Creating Candidates, running evaluations, and releasing versions also require management permission.
  • The domain runtime is reporting Learning Events and runtime observations.
  • The plugin has synchronized at least one Target and its current production baseline.
When you open Agent Evolution, the page automatically uses the currently selected tenant and organization scope. You do not need to select a scope again, and you cannot mix events, evaluation datasets, or release packages across scopes.

​
Page structure

Agent Evolution contains four fixed tabs: The Target selector in the page header only filters Targets within the current tenant and organization. A Target’s risk level and capability flags determine which actions are available.

​
Complete lifecycle

Every stage retains its inputs, versions, actors, and results. A failed Candidate is never modified in place. Update the Change Set and create a new Candidate instead.

​
1. Review learning signals

In Learning & Proposals, select a Target and review signals awaiting attribution. A Learning Event includes at least:
  • The Target and Decision Point where the decision occurred
  • References to the execution, subject, and capability version bundle
  • A prediction summary and final outcome summary
  • Confidence, reason codes, trust level, and redaction status
You can:
  • Mark as golden evidence: Allow the event to serve as evidence for later proposals and datasets.
  • Remove from golden evidence: Retain the event but stop using it as golden evidence.
  • Ignore signal: Remove it from the pending queue without deleting its audit record.
  • Generate proposal: Aggregate evidence with the same Target, scope, and correction signature.
By default, a Proposal requires at least three L2-or-higher events from the last 90 days across two distinct business subjects. All evidence must belong to the same Target and exactly the same scope.

​
2. Build a Candidate

A Proposal only describes why a change is needed and what should change. When you build a Candidate, the domain Provider uses the current production baseline and the structured Change Set to generate an executable candidate artifact. A Candidate permanently references:
  • The baseline capability version
  • The Proposal ID and revision
  • Evidence events
  • Applicable scope
  • The Provider and Provider version
  • The Artifact Schema, URI, and hash
  • Dependent capability versions
Candidate Artifacts and Production Artifacts use separate version references. Creating a Candidate does not change the production capability or switch the Active Pointer.
The domain Provider declares the form fields. The platform renders them without interpreting field semantics or embedding domain rules in Evolution Core.

​
3. Create a Golden Dataset and evaluate

In Candidates & Evaluation, select a Ready Candidate and a dataset with the same Target and scope, then freeze a Golden Dataset Snapshot. The Snapshot fixes case revisions, evaluator versions, metric definitions, and hashes so that the production baseline and Candidate use exactly the same inputs, random seed, and evaluation conditions. Default Golden Replay gates are: The evaluation page shows:
  • Production and Candidate metric comparisons
  • Both version outputs and the expected result for each case
  • Slice metrics, blocking reasons, latency, and cost
  • Auditable Trace references
Passing Golden Replay only means that the Candidate may enter governance. It does not mean the Candidate has been released.

​
4. Submit for approval

After the evaluation passes, enter an approval comment and submit the Candidate for approval. Standard users follow a multi-user, multi-role gate: Users with the SUPER_ADMIN or ADMIN role have administrator approval permission, so one administrator can satisfy the approval gate. The system still freezes the Candidate hash, evaluation run, approval comment, administrator identity, and time. The subsequent release package must reference this approval evidence. You can create a Release Package only after approval. The Release Package freezes the Candidate, target version, rollback version, artifact hash, approval records, and the release gate policy that was active at that time.

​
5. Install and run Shadow

Clicking Install immutable version only instructs the Provider to install a new Capability Version. It does not change the production Active Pointer. After installation, start Shadow:
  • Production requests continue to use the current production version for returned results and side effects.
  • The Candidate runs in parallel with the same input, but its output is not written back to business results.
  • Success rate, severe errors, latency, and cost are recorded separately for Production and Candidate.
The standard gate requires Shadow to run for at least 72 hours, collect 100 valid observations, and report zero severe errors.

​
6. Canary rollout

After Shadow passes, start Canary at 5%, then expand to 25% and 50%. Every expansion requires a human action. Canary uses deploymentId + subjectKey for deterministic assignment:
  • The same subject remains assigned to the same version within the same deployment stage.
  • 5% means 5% of the hash space; it does not guarantee exactly one match in the first 20 requests.
  • Only requests assigned to the Candidate count toward the current Canary stage sample total.
  • A severe error triggers an automatic pause. The system can perform a pre-authorized rollback, but it cannot expand traffic automatically.
The standard gate requires each Canary stage to run for at least 24 hours, collect 30 valid observations, and report zero severe errors. Production activation also requires the 50% Canary stage to satisfy the same gate.

​
Administrator-only one-time Candidate assignment

When using the manual_test gate in a non-production environment, an administrator can create a one-time Candidate assignment for an exact subjectKey to quickly verify the real domain runtime. This capability is constrained as follows:
  • Only SUPER_ADMIN or ADMIN can create it.
  • It only applies to the current manual_test Release Package and an active Canary deployment.
  • You must enter an exact subjectKey, an audit reason, and a validity period from 1 to 120 minutes.
  • It is consumed immediately after one exact match and cannot be reused.
  • The execution plan is marked manual_test_override; both creation and consumption are written to the audit log.
  • It is unavailable in production and cannot replace normal deterministic assignment testing.
The domain runtime supplies subjectKey. A plugin may use a Case ID, for example, but Evolution Core does not understand Case semantics and does not depend on BOM logic.

​
7. Activate production and roll back

Production activation performs two operations:
  1. The Provider activates the installed immutable Capability Version.
  2. Evolution Core validates and switches the production Active Pointer using compare-and-swap (CAS).
Historical versions are never overwritten. New requests resolve to the new version, while an Execution that has already started continues to use the Capability Version Bundle pinned at startup. If an issue occurs, an administrator can roll back to the rollback version frozen in the Release Package. Rollback also switches the Active Pointer through CAS and retains a complete audit record.

​
Standard and manual test gates

The gate policy is frozen when the Release Package is created. If manual_test is configured in a production environment, the platform forces the policy back to standard.
manual_test shortens waiting time during manual acceptance. It does not relax the zero-severe-error requirement, human-controlled expansion, permissions, audit, Candidate isolation, or Active Pointer CAS safeguards.

​
Permissions and data isolation

  • Viewing the page requires EVOLUTION_VIEW or a compatible agent editing permission.
  • Creating Proposals, Candidates, evaluations, and release operations requires EVOLUTION_MANAGE.
  • Data is isolated by tenant and organization. Targets, events, datasets, Candidates, and Release Packages cannot be mixed across scopes.
  • Confidential events must be redacted before ingestion. Do not put customer names, contract text, raw attachment content, or secrets in summaries.
  • An Agent never receives tools for production activation, Canary expansion, or proactive production rollback.

​
Troubleshooting

​
Domain plugin example

BOM Lifecycle is one example of a domain integration with Agent Evolution. Feature Binding and Normalization can complete the evaluation and release lifecycle, PBOM Matching can stop at Replay according to plugin capabilities, and OCR Routing can collect events only. These Targets are not built-in definitions in Evolution Core. Other plugins can use the same mechanism for their own declarative capabilities. For implementation details, see Integrate Agent Evolution into a plugin.