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`	Console API gateway URL. Overrides `gateway.url` in the configuration file
`api_key`	`str \| None`	`None`	Explicit bearer access token
`client_id`	`str \| None`	`None`	Client ID for an API credential pair
`client_secret`	`str \| None`	`None`	One-time secret paired with `client_id`
`config_dir`	`Path \| None`	`None`	Directory containing `config.toml` and `credentials.json`. Defaults to `~/.vijil/`

The constructor raises VijilAuthError if no API key can be resolved from any source. If you use client credentials, provide both client_id and client_secret.

Authentication

Create API credentials under Settings > API Keys in your Vijil Console deployment. Each credential consists of a client ID (vk_…) and a secret that the Console shows only once. Provide the pair through environment variables or constructor arguments:

export VIJIL_CLIENT_ID="<client-id>"
export VIJIL_CLIENT_SECRET="<client-secret>"

from vijil import Vijil

client = Vijil(
    client_id="<client-id>",
    client_secret="<client-secret>",
)

When you provide no authentication arguments, Vijil() reads VIJIL_CLIENT_ID and VIJIL_CLIENT_SECRET from the environment. The SDK exchanges the pair for a bearer access token when it constructs the client. It does not store the client ID or secret.

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

Use one authentication method per client. The SDK resolves credentials in this order:

A complete client_id and client_secret pair passed to Vijil()
An api_key passed to Vijil()
VIJIL_CLIENT_ID and VIJIL_CLIENT_SECRET, when you pass no authentication arguments
VIJIL_API_KEY
The token in ~/.vijil/credentials.json

The gateway determines the access token lifetime. The SDK does not store a client credential pair after its initial exchange. If that token expires, construct a new client or call client.authenticate(client_id="<client-id>", client_secret="<client-secret>"). Your application must replace bearer tokens supplied through api_key or VIJIL_API_KEY; tokens loaded from the saved credentials file can use the SDK’s refresh flow.

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://console-api.vijil.ai. Point it at another Console deployment with the gateway argument or save the URL in ~/.vijil/config.toml:

from vijil import Vijil

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

vijil config set gateway.url https://console-api.example.com

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

The gateway argument
The gateway.url value in ~/.vijil/config.toml
The built-in default, https://console-api.vijil.ai

Agent Aliases

Methods that support Agent aliases read them from ~/.vijil/config.toml, 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

Red Team

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