Setup

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 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:

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:

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:

The gateway argument
The VIJIL_GATEWAY environment variable
The gateway.url value in ~/.vijil/config.toml
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

Get Started

Evaluate Agents

Protect Agents

Reference

Installation

The `Vijil` Client

Authentication

Bearer Token

Gateway Configuration

Agent Aliases

Next Steps

Lifecycle Methods

Resources

Models and Errors

Quickstart

​Installation

​The Vijil Client

​Authentication

​Bearer Token

​Gateway Configuration

​Agent Aliases

​Next Steps

Lifecycle Methods

Resources

Models and Errors

Quickstart

Installation

The `Vijil` Client

Authentication

Bearer Token

Gateway Configuration

Agent Aliases

Next Steps