Setup

Install the Vijil SDK, construct the client, and authenticate against your Vijil Console deployment.

The vijil Python SDK measures and improves Agent trustworthiness from your own code. Use it in scripts, notebooks, and pipelines to run Evaluations, configure protection, and read results programmatically.

This reference covers the Python SDK. For interactive, natural-language access from Claude Code, see MCP. For terminal commands, see the CLI Reference.

Installation

Install vijil-sdk with pip or add it to your project with Poetry:

pip

pip install vijil-sdk

poetry add vijil-sdk

The SDK requires Python 3.12 or later. Verify the import:

python -c "from vijil import Vijil; print('ok')"

The Vijil Client

Vijil is the entry point for every SDK operation. Construct it once and reuse it:

from vijil import Vijil

# Read the API key from VIJIL_API_KEY and settings from ~/.vijil/
client = Vijil()

Parameter	Type	Default	Description
gateway	str | None	None	Gateway URL. Falls back to config, then https://api.vijil.ai
api_key	str | None	None	API key. Falls back to the VIJIL_API_KEY environment variable, then ~/.vijil/credentials.json
config_dir	Path | None	None	Configuration directory. Defaults to ~/.vijil/

The constructor raises VijilAuthError if no API key can be resolved from any source.

Authentication

Create an API key in your Vijil Console deployment under Settings > API Keys — a client ID (vk_…) plus a one-time secret shown only at creation. Export the pair; the SDK exchanges it for a short-lived access token automatically:

export VIJIL_CLIENT_ID="vk_..."
export VIJIL_CLIENT_SECRET="..."   # shown once at creation

Vijil() reads these from the environment on construction.

Bearer Token

If you already have a bearer access token, provide it directly instead of the client ID and secret:

Environment variable

export VIJIL_API_KEY="<access-token>"

from vijil import Vijil

client = Vijil(api_key="<access-token>")

vijil auth login   # paste the token; saved to ~/.vijil/credentials.json

The api_key argument takes precedence over VIJIL_API_KEY, which takes precedence over the saved credentials file.

A bearer access token is a JWT that expires 24 hours after it is issued. For long-lived automation, authenticate with the client ID and secret instead — the SDK exchanges them for a fresh token automatically whenever the current one expires.

In CI/CD, set VIJIL_CLIENT_ID and VIJIL_CLIENT_SECRET as secrets rather than committing them or running an interactive login.

Gateway Configuration

By default the SDK connects to https://api.vijil.ai. Point it at your own Console deployment (enterprise or VPC) with the gateway argument or the VIJIL_GATEWAY environment variable:

Argument

from vijil import Vijil

client = Vijil(gateway="https://console-api.example.com")

export VIJIL_GATEWAY="https://console-api.example.com"

All SDK calls route through the gateway. Resolution order, highest priority first:

1. The gateway argument
2. The VIJIL_GATEWAY environment variable
3. The gateway.url value in ~/.vijil/config.toml
4. The built-in default, https://api.vijil.ai

Agent Aliases

The SDK resolves short aliases defined in ~/.vijil/config.toml anywhere an Agent ID is expected, so you can pass a memorable name instead of a UUID:

client = Vijil()
client.evaluate("travel-agent", baseline=True)   # resolves the alias via config

Next Steps

Lifecycle Methods

Evaluate, test, adapt, and protect Agents with high-level methods

Resources

Low-level CRUD accessors for Agents, Evaluations, Harnesses, and more

Models and Errors

Return types, the exception hierarchy, and error-handling patterns

Quickstart

Run your first Evaluation end to end