Agent Lifecycle Workflow

This guide takes an existing Agent from registration to a hardened, evidence-backed production release and ongoing monitoring. Use Diamond to evaluate the Agent, Dome to protect it at runtime, and your delivery pipeline to release it. Follow the Console or Python SDK path at each stage.

This workflow starts with registration and does not cover Discover or creating a new Agent through generative evolution. Automated Darwin adaptation is available only where enabled. The platform does not currently deploy your Agent application, so the final stage uses your existing delivery pipeline.

The Agent Trust Lifecycle

Stage	Goal	Evidence Produced
Register	Connect the Agent to the platform	Active Agent and Agent ID
Evaluate	Measure trustworthiness and search for deeper weaknesses	Trust Score, Trust Report, and Red Team findings
Harden	Add and test runtime Guardrails	Applied Dome configuration and staging telemetry
Improve	Remediate weaknesses found during Evaluate	Reviewed Agent, Policy, and Guard changes
Re-evaluate	Confirm that the changes worked	Improved Evaluation results and release decision
Deploy	Release through your delivery pipeline	Production Agent reconnected to the platform
Monitor	Observe production behavior	Dome Metrics, events, logs, and traces

The Console records Registered, Tested, and Protected Agent stages. If you use Darwin, accepting a proposal moves the Agent to the Adapted stage.

Before You Begin

You need:

A Console account and access to a team.
An existing Agent with a reachable HTTP endpoint.
Credentials and rate-limit information for the Agent endpoint.
Permission to configure and deploy the Agent.
Python 3.12 or later, the SDK, and the required Dome extras for the SDK path.
Client credentials for the SDK path.
Optional Policies and Personas for targeted Evaluations and Red Team campaigns.

Define your release criteria before you begin. Decide:

The Trust Score required for release.
Findings that block release.
Guardrail latency and error-rate limits.
How you will assess false positives.
Which reports or other evidence your reviewers need.

The Console presents Trust Scores on a 0–100 scale. The SDK returns scores on a 0.0–1.0 scale. For example, a Console score of 70 is an SDK score of 0.70.

1. Register the Agent

Registration tells the platform how to reach the Agent and how much context it can use during testing. Choose the access level that matches the information you can provide:

Access Level	What You Provide	When to Use It
Black Box	Endpoint and credentials	You want to test observable behavior
Grey Box	Prompts, model configuration, tools, MCP servers, and delegated Agents	You want findings tied to the Agent composition
White Box	Agent configuration and source code	You want static and dynamic analysis

Console
SDK

Open Agents.
Select + Register Agent.
Enter the required Black Box fields.
Add Grey Box or White Box context when available.
Register the Agent and save its ID.

Create a Vijil client.
Register the current Agent configuration with client.agents.create().
Save agent.id for the remaining stages.

Use client.agents.create() for this workflow. Do not use client.register(), which depends on a preview source-to-genome Console route.

Checkpoint

The Agent appears as Active.
The Console can reach its endpoint.
You saved the Agent ID.

If the Agent runs only on your workstation, follow Evaluate a Local Agent before continuing.

2. Evaluate the Agent

A Diamond Evaluation measures the Agent against known standards. Start with a baseline Trust Score Evaluation, then run adaptive Red Teaming to search for weaknesses that fixed tests might miss.

Establish the Trust Baseline

Console
SDK

Open Tests and create an Evaluation.
Select the registered Agent.
Choose Trust Score and Baseline.
Enable Reliability, Security, and Safety.
Run the Evaluation.

Run client.evaluate(agent_id, baseline=True).
Record the Trust Score and the Reliability, Security, and Safety scores.
Save the Evaluation ID.

Review the Evaluation results:

The Trust Score pass or fail result.
The lowest-scoring Dimension.
Critical and high-severity findings.
Failure patterns and recommended fixes.
Whether the Harness coverage matches the Agent’s actual risks.

Run an Adaptive Red Team Campaign

After the baseline Evaluation, run an adaptive Red Team campaign against the registered Agent. Red Teaming investigates tool misuse, data leakage, policy violations, and weaknesses that fixed Evaluation cases might not expose.

Console
SDK

Create a new test for the Agent.
Select the Adaptive Red Team configuration.
Add relevant Policies and Personas.
Start with conservative wave and concurrency settings.
Run the campaign.
Review the findings and successful attack strategies.

Use client.xteam() for the multi-wave seed, attack, judge, and reflect workflow.
Poll until the campaign reaches a terminal state.
Retrieve and review the findings.

Use client.test() only when the simpler campaign interface matches your deployment. Use the Red Team results to inspect:

FULL, PARTIAL, and NONE judgments.
Confirmed policy violations.
Leaked artifacts.
Successful attack strategies.
Which findings require runtime protection from Dome.
Degraded or failed attacker runs.

Checkpoint

The baseline Evaluation completed successfully.
You saved the Trust Report.
The adaptive Red Team campaign completed successfully.
You saved its findings, transcripts, and successful strategies.
You have a prioritized list of weaknesses.

3. Harden the Agent With Dome

Use the Trust Score findings and Red Team evidence to choose Dome runtime protection:

Finding	Likely Protection
Prompt injection or jailbreak	Security input Guard
Sensitive-data leakage	Privacy output Guard
Harmful user requests	Moderation input Guard
Harmful Agent responses	Moderation output Guard
Agent-specific policy violation	Policy or custom Guard

Policy Guards are available through programmatic Dome. In the Console, create a custom Guard using one of the available Security, Moderation, or Privacy Guard types.

Use the Console Guardrail guide for UI details and the Dome configuration reference for code-level options.

Console
SDK

Open the Agent and select Protect.
Review the predefined input and output Guards.
Enable or add the Detectors supported by the findings.
Choose Serial or Parallel execution.
Configure Early Exit.
Test representative safe and unsafe inputs.
Save and Apply the configuration.
Send staging traffic through the Agent and confirm that Dome Metrics receives it.

Use client.protect() to associate the Dome configuration with the Agent.
Where enabled, load the Guardrail configuration with Dome.create_from_vijil_agent(). Otherwise, use a reviewed, version-controlled Dome configuration.
Wrap both Agent inputs and Agent outputs with Guardrails.
Handle blocked and sanitized results explicitly.
Send staging traffic through the hardened Agent and confirm that telemetry reaches the platform.

Saving a Dome configuration does not protect runtime traffic by itself. Integrate Dome Guardrails into the Agent request path before relying on the configuration.

Hardening adds and validates runtime protection. It does not deploy the Agent application.

Checkpoint

Known attacks trigger the expected Guards.
Normal requests still work.
Staging telemetry is available for the hardened Agent.
The Agent reaches the Protected stage.

4. Improve the Agent

The platform provides Evaluation evidence and, where available, optional Darwin proposals. You are responsible for reviewing that evidence and applying remediation to the Agent. Manual remediation is the default path. Depending on the finding, you might:

Update the system prompt.
Reduce tool permissions.
Change the model or Agent configuration.
Fix vulnerable code.
Add or tune Dome Guards.
Update Policies or Personas.
Save representative successful attack inputs and transcripts as regression cases.

Console
SDK

Review the prioritized Trust Score and Red Team findings.
Apply prompt, code, model, or tool-permission changes through your development workflow.
Update the registered Agent configuration and Dome settings in the Console when needed.
Record which finding each change addresses.

Apply code and configuration fixes through the application repository.
Update the relevant Agent, Policy, or Dome configuration through the SDK when needed.
Where Darwin is available, run client.adapt().
Review the generated proposals with client.proposals.
Approve and apply only reviewed proposals.
Preserve genome versions for comparison and audit.

Darwin is in development and not yet generally available. If your deployment includes Darwin, review every generated proposal before applying it. Keep the manual remediation path complete when Darwin is unavailable.

Checkpoint

Critical and high-risk findings have an owner.
Successful attack transcripts are available as regression cases.
Every important finding maps to a reviewed change or documented exception.
If you used Darwin, you reviewed every automated proposal before applying it.
The improved Agent is ready for another Evaluation.

5. Re-evaluate the Agent

Repeat the tests that cover the changed behavior:

Run the complete baseline Evaluation.
Run targeted Harnesses for the changed areas.
Retest representative successful attacks through the Agent’s regression test process.
Run another adaptive campaign after changes to tools, prompts, permissions, or data access.
Compare the results with the original baseline.

Console
SDK

Create another baseline Trust Score Evaluation.
Run targeted Harnesses for the changed areas.
Manually retest representative attack inputs saved from the previous campaign.
Compare the new Trust Score, Dimension scores, and findings with the baseline.
Confirm that staging telemetry still reaches the correct Agent.

Run client.evaluate(agent_id, baseline=True).
After the baseline completes, use client.evaluate(agent_id, harness_id="<harness-id>") to run one targeted Harness. Repeat the call for each Harness you need.
Retest saved attack inputs through the Agent’s test suite.
Use client.xteam() to start a new adaptive campaign with the relevant Policies and Personas.
Compare the returned scores and findings with the saved baseline.
Check staging traces with client.monitor.traces().

A release gate should check that:

The Trust Score meets your agreed threshold.
No critical findings remain unresolved.
High-severity exceptions have explicit approval.
Targeted regression tests pass.
Dome blocks known attacks.
P99 latency and Guard error rates are acceptable.
Telemetry works in the release environment.

Checkpoint

The release has reproducible Evaluation evidence.
The Agent passes your deployment criteria.

6. Deploy Through Your Pipeline

Deploy the hardened Agent through your delivery pipeline of choice. The platform evaluates and protects the Agent, but it does not replace your application build, release, or infrastructure process.

Gate Deployment in CI/CD

Run a final baseline Evaluation before your pipeline pushes the release to production. Store VIJIL_CLIENT_ID and VIJIL_CLIENT_SECRET and VIJIL_AGENT_ID as CI/CD secrets or protected variables.

import os

from vijil import Vijil

agent_id = os.environ["VIJIL_AGENT_ID"]
threshold = float(os.getenv("VIJIL_TRUST_THRESHOLD", "0.70"))

client = Vijil()
evaluation = client.evaluate(agent_id, baseline=True)

successful_statuses = {"completed", "succeeded", "saved"}
if evaluation.status not in successful_statuses:
    raise SystemExit(f"Evaluation ended with status: {evaluation.status}")

if evaluation.trust_score is None:
    raise SystemExit("Evaluation returned no Trust Score")

if evaluation.trust_score < threshold:
    raise SystemExit(
        f"Trust Score {evaluation.trust_score:.2f} is below {threshold:.2f}"
    )

print(f"Trust Score gate passed: {evaluation.trust_score:.2f}")

Use 0.70 only as an example. Set VIJIL_TRUST_THRESHOLD to the threshold approved for your Agent and risk profile.

Release and Reconnect the Agent

Console
SDK

Confirm that the latest Evaluation meets the release criteria.
Deploy the hardened Agent through your delivery pipeline.
If the endpoint or credentials changed, open Agents, edit the registered Agent, and save the production configuration.
Reapply the reviewed Dome configuration.
Run a production smoke test.
Confirm that production traffic appears under the correct Agent.

Run the SDK release gate before the production deployment job.
Deploy the hardened Agent through your delivery pipeline.
If the endpoint or configuration changed, update the registered Agent with client.agents.update().
Reload or reapply the reviewed Dome configuration.
Run a production smoke test.
Confirm that production traces use the expected Agent ID.

Your deployment artifact should:

Include vijil-dome and the required extras in the deployment artifact.
Load the reviewed Dome configuration.
Keep credentials and other secrets outside source control.
Keep a rollback path for Agent and Guardrail changes.

Checkpoint

Production traffic passes through Dome.
Blocking and fallback behavior work.
The production Agent configuration points to the deployed endpoint.
The release links to its Evaluation and Red Team evidence.

7. Monitor and Continue the Lifecycle

Use Dome Metrics to investigate threats, tune protection, and catch behavior changes after deployment.

Console
SDK

Open the Agent and select Monitor.
Review traffic, inbound and outbound blocks, errors, and P99 latency.
Inspect Threat Breakdown, Guard Performance, Events, logs, and traces.
Confirm that production traffic appears under the expected Agent.

Read production traces with client.monitor.traces().
Read production logs with client.monitor.logs().

Do not use client.monitor.summary() or historical client.monitor.detections() until their backend routes are available.

Use the telemetry to answer:

Is a block a real threat or a false positive?
Are output Guards preventing leakage?
Are any Detectors failing?
Is Guardrail latency acceptable?
Has Agent behavior changed since the verified release?
Is the telemetry complete enough for an investigation?

New findings restart the lifecycle at Improve. Apply a reviewed change, re-evaluate the Agent, pass the deployment gate, and release the update through the same pipeline.

Checkpoint

Production telemetry is available.
Known attacks are visible and handled correctly.
False positives, Guard errors, and latency remain within the approved limits.
New findings have an owner and feed into the next improvement cycle.

Production Readiness Checklist

Register the Agent and verify that its endpoint is reachable.
Complete the baseline Evaluation and review the Trust Report.
Complete an adaptive Red Team campaign.
Configure input and output Guards and integrate Dome into the Agent runtime.
Confirm that staging telemetry reaches the correct Agent.
Address critical and high-risk findings.
Add successful attacks to regression testing.
Re-evaluate the Agent and confirm that it meets the release criteria.
Configure and pass the CI/CD Trust Score gate.
Deploy the hardened Agent and update its registered production configuration.
Verify production telemetry, Guardrail latency, and false-positive behavior.
Assign monitoring and rollback owners.

Troubleshooting

Problem	What to Check
The Evaluation cannot reach the Agent	Review Agent availability, endpoint compatibility, credentials, and rate limits
The Evaluation takes too long	Review Evaluation rate limits, use a small sample while iterating, then run full coverage before release
Red Team is too slow or expensive	Review Red Team runtime and cost, then reduce waves, seeds, or parallel attackers
Dome blocks normal traffic	Inspect Dome traces and tune the responsible Detector
The CI/CD gate fails	Check the Evaluation status, Trust Score, configured threshold, and SDK credentials
The platform uses the old Agent endpoint	Update the registered Agent after deployment
Dome Metrics is empty	Follow the empty-state checks for integration, traffic, Agent ID, and telemetry
Adaptation calls fail	Confirm Darwin availability for the deployment

Next Steps

Manage Agents

Run Evaluations

Start, monitor, and retrieve Diamond Evaluations.

Understand Results

Interpret Trust Scores and rank findings.

Configure Guardrails

Configure Guards, Detectors, and execution behavior.

Use Guardrails

Integrate Dome into the Agent request path.

Observability

Track Guardrail decisions, logs, and traces.

Get Started

Evaluate Agents

Red Team

Protect Agents

Reference

Agent Lifecycle Workflow

The Agent Trust Lifecycle

Before You Begin

1. Register the Agent

Checkpoint

2. Evaluate the Agent

Establish the Trust Baseline

Run an Adaptive Red Team Campaign

Checkpoint

3. Harden the Agent With Dome

Checkpoint

4. Improve the Agent

Checkpoint

5. Re-evaluate the Agent

Checkpoint

6. Deploy Through Your Pipeline

Gate Deployment in CI/CD

Release and Reconnect the Agent

Checkpoint

7. Monitor and Continue the Lifecycle

Checkpoint

Production Readiness Checklist

Troubleshooting

Next Steps

Manage Agents

Run Evaluations

Understand Results

Configure Guardrails

Use Guardrails

Observability

​The Agent Trust Lifecycle

​Before You Begin

​1. Register the Agent

​Checkpoint

​2. Evaluate the Agent

​Establish the Trust Baseline

​Run an Adaptive Red Team Campaign

​Checkpoint

​3. Harden the Agent With Dome

​Checkpoint

​4. Improve the Agent

​Checkpoint

​5. Re-evaluate the Agent

​Checkpoint

​6. Deploy Through Your Pipeline

​Gate Deployment in CI/CD

​Release and Reconnect the Agent

​Checkpoint

​7. Monitor and Continue the Lifecycle

​Checkpoint

​Production Readiness Checklist

​Troubleshooting

​Next Steps

Manage Agents

Run Evaluations

Understand Results

Configure Guardrails

Use Guardrails

Observability

The Agent Trust Lifecycle

Before You Begin

1. Register the Agent

Checkpoint

2. Evaluate the Agent

Establish the Trust Baseline

Run an Adaptive Red Team Campaign

Checkpoint

3. Harden the Agent With Dome

Checkpoint

4. Improve the Agent

Checkpoint

5. Re-evaluate the Agent

Checkpoint

6. Deploy Through Your Pipeline

Gate Deployment in CI/CD

Release and Reconnect the Agent

Checkpoint

7. Monitor and Continue the Lifecycle

Checkpoint

Production Readiness Checklist

Troubleshooting

Next Steps