SDK Migration Guide

Who This Guide Is For

Use this guide if you installed the legacy vijil PyPI package with pip install vijil. That package targets a previous API contract. This guide gets you onto vijil-sdk, the current SDK and CLI distribution.

Why Migrate

The legacy vijil package cannot reach current platform endpoints. If a recent legacy install returns authentication failures or 404 responses, the package is likely using the old API contract. Key changes:

Authentication moved from a username and token flow against /tokens/verify to bearer API keys.
The current CLI replaces generic CRUD commands such as vijil create, vijil list, and vijil describe with workflow verbs and resource commands.
The current SDK includes generated models for stronger type checking and IDE completion.
Red Team now runs as a Diamond evaluation, alongside behavioral evaluations, and uses an evaluation ID for status and results.

Install

Uninstall the legacy package, then install the current SDK:

# Old
pip uninstall vijil

# New
pip install vijil-sdk

The vijil-sdk package installs both the vijil Python SDK and the vijil CLI under one distribution. It requires Python 3.12 or later.

Authentication Changes

The legacy package prompted for a username and token:

# Old
vijil login <your-username>
# Enter your token: ****

The current SDK uses bearer API keys generated from your Console deployment under Profile > Personal Information > API Auth Token:

# New
vijil auth login
# Enter your Vijil API key: ****
# Authenticated. Token saved to ~/.vijil/credentials.json

You can also set VIJIL_API_KEY in your environment. The environment variable takes precedence over the token stored by vijil auth login.

Command Map

The legacy package exposed top-level commands for generic operations. The current CLI splits those commands into:

Porcelain commands for the high-level agent trust workflow
Plumbing commands for low-level CRUD operations on platform resources (scripting, automation, and direct resource management)

Legacy Command	Current Command	Notes
`vijil login`	`vijil auth login`	Uses an API key instead of username and token authentication
`vijil logout`	`vijil auth logout`	Clears stored credentials
`vijil create <X>`	Porcelain verbs such as `vijil evaluate`, `vijil adapt`, `vijil protect`, `vijil register`, `vijil evolve`, or `vijil deploy`	Choose the command by intent instead of using a generic `create` action
`vijil list <X>`	`vijil <resource> list`	Resources include `agents`, `evaluations`, `harnesses`, `genomes`, `jobs`, `scores`, `reports`, `proposals`, `policies`, and `personas`
`vijil describe <X>`	`vijil <resource> describe <id>`	Uses the same resource set as `list`
`vijil delete <X>`	`vijil <resource> delete <id>`	Uses the same resource set as `list`
`vijil download <X>`	`vijil reports download <id>`	Reports are the only downloadable artifact today
`vijil start <X>`	Porcelain verbs such as `vijil evaluate`	Start a behavioral evaluation by default, or add `--type redteam` for Red Team
`vijil stop <X>`	`vijil jobs cancel <id>`	Job cancellation is a plumbing command

See the CLI evaluation reference for evaluation options.

Former Red Team Workflow

If you used the former standalone Red Team workflow, create a Red Team evaluation instead. The evaluation ID identifies the run and its results across the SDK, CLI, and REST API.

Former workflow	Current interface
Start a standalone Red Team run	`client.evaluate(agent_id="...", type="redteam")` or `vijil evaluate <agent> --type redteam`
Create a run without waiting	`client.evaluations.create(agent_id="...", type="redteam")` or `vijil evaluate <agent> --type redteam --no-wait`
Create a run through REST	`POST /v1/evaluations/` with `type: "redteam"`
Check progress and results	`client.evaluations.redteam_status(evaluation_id)`, `vijil evaluations redteam-status <evaluation-id>`, or `/v1/evaluations/{evaluation_id}/redteam/*`
Retrieve the report	`client.evaluations.redteam_report(evaluation_id)` or `vijil evaluations redteam-report <evaluation-id>`

Red Team evaluations do not use baseline, Harness, sample_size, or local mode settings. See the Red Team CLI guide and SDK evaluation resources for the status, artifact, and report methods.

Python SDK Changes

The legacy package did not expose a stable Python API beyond CLI invocation. The current package provides the Vijil client:

from vijil import Vijil

client = Vijil()

behavioral = client.evaluate(agent_id="...", baseline=True)
print(behavioral.trust_score)

redteam = client.evaluate(agent_id="...", type="redteam")
print(redteam.evaluation_id)

By default, Vijil() reads VIJIL_API_KEY or the credentials saved by vijil auth login. See lifecycle methods for the full client.evaluate() workflow.

When to Use MCP Instead

Use vijil-mcp when you need to run Vijil capabilities inside MCP-aware agent framework such as Claude Desktop, Cursor, LangGraph, ADK, or Strands. The vijil-mcp package runs as a separate stdio MCP server that exposes Vijil platform capabilities as tools an agent can call. You can install both vijil-sdk and vijil-mcp in the same environment. They are independent and do not share runtime state.

Get Started

Evaluate Agents

Red Team

Protect Agents

Reference

SDK Migration Guide

Who This Guide Is For

Why Migrate

Install

Authentication Changes

Command Map

Former Red Team Workflow

Python SDK Changes

When to Use MCP Instead

​Who This Guide Is For

​Why Migrate

​Install

​Authentication Changes

​Command Map

​Former Red Team Workflow

​Python SDK Changes

​When to Use MCP Instead

Who This Guide Is For

Why Migrate

Install

Authentication Changes

Command Map

Former Red Team Workflow

Python SDK Changes

When to Use MCP Instead