> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vijil.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle Methods

> Manage the Agent lifecycle with high-level Vijil SDK workflows.

Lifecycle methods are high-level workflows on the `Vijil` client. Each method maps to a stage of the Agent lifecycle. Long-running operations poll until they reach a terminal state unless the method provides a `no_wait` option.

| Method | What It Does | Returns |
| - | - | - |
| `client.evaluate()` | Run a behavioral or red-team Evaluation | `Evaluation \| RedteamStatusResponse` |
| `client.adapt()` | Improve an Agent through corrective evolution | `Job` |
| `client.protect()` | Configure Dome runtime Guardrails | `DomeConfig` |
| `client.discover()` | Find Agents in GitHub repositories or cloud infrastructure | `Page[DiscoveredAgent]` |
| `client.register()` | Register Agent source from a local directory | `dict[str, Any]` |
| `client.evolve()` | Create an Agent through generative evolution | `Job` |
| `client.deploy()` | Deploy an Agent to a production runtime | `Deployment` |

## `client.evaluate()`

Run an [Evaluation](https://docs.vijil.ai/developer-guide/evaluate/overview.md) and poll until it reaches a terminal state. The default `type="behavioral"` path uses Harnesses and returns an `Evaluation` with the finalized scores.

```python theme={null}
evaluation = client.evaluate(
    "agent-id",
    baseline=True,
    sample_size=50,
)

print(evaluation.status)
print(evaluation.trust_score)
print(evaluation.dimensions)
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `agent_id` | `str` | — | Agent ID or alias |
| `baseline` | `bool` | `False` | Run the standard reliability, security, and safety Harnesses |
| `harness_id` | `str \| None` | `None` | Run a specific [Harness](https://docs.vijil.ai/concepts/evaluation-components/harness.md) instead of the baseline |
| `sample_size` | `int \| None` | `None` | Number of Probes to run per Harness; must be at least `1` |
| `type` | `str` | `"behavioral"` | Evaluation type: `"behavioral"` or `"redteam"` |
| `redteam` | `Mapping[str, Any] \| None` | `None` | Red-team configuration overrides, such as `max_waves` or `advanced` |
| `_poll_interval` | `float` | `5.0` | Seconds between status checks |
| `on_poll` | `Callable \| None` | `None` | Callback invoked with the current state after each status check |

For a behavioral Evaluation, pass either `baseline=True` or `harness_id`, not both. To start a behavioral Evaluation without waiting, use `client.evaluations.create()` and poll the Evaluation resource yourself. See [Run Evaluations](https://docs.vijil.ai/developer-guide/evaluate/running-evaluations.md) for the lower-level workflow.

### Run a Red-Team Evaluation

Set `type="redteam"` to challenge an Agent with adaptive adversarial waves. This replaces the removed `client.test()` workflow.

```python theme={null}
status = client.evaluate(
    "agent-id",
    type="redteam",
    redteam={"max_waves": 3},
)

print(status.evaluation_id)
print(status.status)
print(status.current_wave)
```

This path returns a `RedteamStatusResponse` and polls until the status is `succeeded`, `failed`, `cancelled`, or `degraded`. Do not combine `type="redteam"` with `baseline`, `harness_id`, or `sample_size`; the SDK rejects those behavioral-only arguments.

## `client.adapt()`

Create a corrective evolution job for an existing Agent. By default, the method polls until the job reaches a terminal status: `completed`, `failed`, or `cancelled`.

```python theme={null}
job = client.adapt("agent-id", mode="config")
print(job.status)
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `agent_id` | `str` | — | Agent ID or alias |
| `mode` | `str` | `"config"` | `"config"` for GEPA or `"code"` for ADAS/SourceEngine |
| `no_wait` | `bool` | `False` | Return the initial `Job` without polling |

Returns a [`Job`](https://docs.vijil.ai/developer-guide/sdk/models-errors#job). After adaptation completes, review and apply the resulting [proposals](https://docs.vijil.ai/developer-guide/sdk/resources.md#client-proposals).

## `client.protect()`

Configure [Dome](https://docs.vijil.ai/developer-guide/protect/overview.md) runtime Guardrails for an Agent.

```python theme={null}
dome = client.protect(
    "agent-id",
    guards=["prompt_injection", "pii"],
    mode="enforce",
)

print(dome.mode)
print(dome.guards)
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `agent_id` | `str` | — | Agent ID or alias |
| `policy_id` | `str \| None` | `None` | Policy to apply |
| `guards` | `list[str] \| None` | `None` | [Guard](https://docs.vijil.ai/concepts/defense/guard.md) names |
| `mode` | `str` | `"enforce"` | `"enforce"` blocks threats, `"monitor"` logs them, and `"disabled"` turns Guardrails off |

Returns a [`DomeConfig`](https://docs.vijil.ai/developer-guide/sdk/models-errors#domeconfig). For local Dome configuration, see [Configure Guardrails](https://docs.vijil.ai/developer-guide/protect/configuring-guardrails.md).

## `client.discover()`

Find Agents in GitHub repositories or supported cloud infrastructure. Provide at least one GitHub selector or a provider.

```python theme={null}
# Discover repositories in a GitHub organization.
github_agents = client.discover(github_org="acme-corp")

# Discover Agents in a Kubernetes namespace.
cloud_agents = client.discover(
    provider="k8s",
    namespace="production",
)
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `github_org` | `str \| None` | `None` | GitHub organization to scan |
| `github_repo` | `str \| None` | `None` | GitHub repository to scan |
| `provider` | `str \| None` | `None` | Infrastructure provider, such as `"aws"` or `"k8s"` |
| `region` | `str \| None` | `None` | Cloud region filter used with `provider` |
| `namespace` | `str \| None` | `None` | Kubernetes namespace filter used with `provider` |

Returns a [`Page[DiscoveredAgent]`](https://docs.vijil.ai/developer-guide/sdk/models-errors#paget).

## `client.register()`

Register Agent source from a local directory. The SDK uploads text source files to the Console import route and returns the response as a dictionary.

```python theme={null}
result = client.register("./my-agent")
print(result["id"])
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path_or_url` | `str` | — | Path to a local directory containing the Agent source |
| `discover_id` | `str \| None` | `None` | Reserved parameter; discovery ID registration is not supported |

Despite the parameter name, `path_or_url` does not accept a GitHub URL. Clone the repository first, then pass its local directory. The SDK excludes common dependency, cache, version-control, binary, and secret files. It rejects source trees larger than 5 MiB or 500 files instead of uploading a partial tree.

## `client.evolve()`

Create an Agent from a specification, a local YAML or JSON specification file, or a natural-language description. The method polls the evolution job unless you set `no_wait=True`.

```python theme={null}
job = client.evolve(
    description="A travel booking Agent for flights and hotels",
)
print(job.status)
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `spec` | `dict[str, Any] \| None` | `None` | Evolution specification |
| `spec_path` | `str \| None` | `None` | Path to a YAML or JSON specification file |
| `description` | `str \| None` | `None` | Natural-language description lowered to a specification |
| `no_wait` | `bool` | `False` | Return the initial `Job` without polling |

Provide one of `spec`, `spec_path`, or `description`. Returns a [`Job`](https://docs.vijil.ai/developer-guide/sdk/models-errors#job).

## `client.deploy()`

Deploy an Agent to a production runtime. The method polls while the deployment status is `deploying` unless you set `no_wait=True`.

```python theme={null}
deployment = client.deploy(
    "agent-id",
    runtime="agentcore",
)

print(deployment.status)
print(deployment.url)
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `agent_id` | `str` | — | Agent ID or alias |
| `runtime` | `str` | — | Target runtime, such as `"agentcore"`, `"do-gradient"`, or `"k8s"` |
| `namespace` | `str \| None` | `None` | Kubernetes namespace used with the `"k8s"` runtime |
| `no_wait` | `bool` | `False` | Return the initial `Deployment` without polling |

Returns a [`Deployment`](https://docs.vijil.ai/developer-guide/sdk/models-errors#other-models). Discovery, evolution, and deployment availability depends on the capabilities enabled in your Console deployment.

## Next Steps

> [card] [SDK Resources](https://docs.vijil.ai/developer-guide/sdk/resources.md)
>
> Use lower-level resource operations and pagination.

> [card] [Models and Errors](https://docs.vijil.ai/developer-guide/sdk/models-errors.md)
>
> Inspect return types and handle SDK exceptions.

> [card] [Run Evaluations](https://docs.vijil.ai/developer-guide/evaluate/running-evaluations.md)
>
> Start Evaluations and retrieve detailed results.

> [card] [Protect Agents](https://docs.vijil.ai/developer-guide/protect/overview.md)
>
> Add runtime Guardrails with Dome.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.