vijil-sdk 0.0.1

Vijil SDK & CLI — measure and improve AI agent trustworthiness

Vijil SDK & CLI

Measure and improve AI agent trustworthiness from your terminal or Python code.

Vijil provides a unified trust layer for the entire agent lifecycle — from discovery through deployment. Evaluate your agent against known standards, test it under adversarial pressure, adapt it to fix weaknesses, and protect it with runtime Guardrails.

Install

pip install vijil-sdk

Requires Python 3.12+. Installs both the vijil CLI and the vijil Python SDK.

Using Vijil from Claude Desktop, Cursor, or other MCP-aware agent frameworks? See vijil-mcp — a separate package that exposes the Vijil platform as MCP tools. The SDK and the MCP server are independent: vijil-sdk runs in your Python process; vijil-mcp runs as a stdio server attached to your agent framework.

Migrating from the legacy vijil PyPI package (pre-2026)? See docs/migration-from-legacy-vijil.md for the install change, auth flow change, and command-by-command map.

Authenticate

Create an API key at console.vijil.ai > Settings > API Keys — a client ID (vk_…) plus a one-time secret. 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

Already have a bearer access token? Use it directly instead — vijil auth login saves one, or set it in the environment:

vijil auth login                   # paste an access token; saved to ~/.vijil/credentials.json
export VIJIL_API_KEY="<access-token>"

Quick start: CLI

# Evaluate against standard trust Harnesses
vijil evaluate <agent-id> --baseline

# Test under adversarial pressure (Swarm)
vijil test <agent-id> --adaptive

# View trust scores
vijil scores show <agent-id>

# Configure runtime Guardrails
vijil protect <agent-id> --guards prompt_injection,pii --mode enforce

# Improve the agent through corrective evolution
vijil adapt <agent-id> --mode config

Quick start: SDK

from vijil import Vijil

client = Vijil()

# Evaluate and wait for results
evaluation = client.evaluate("my-agent", baseline=True)
print(f"Trust score: {evaluation.trust_score}")
print(f"Reliability: {evaluation.dimensions.reliability}")
print(f"Security:    {evaluation.dimensions.security}")
print(f"Safety:      {evaluation.dimensions.safety}")

# Test under adversarial pressure
job = client.test("my-agent", mode="adaptive")
print(f"Test status: {job.status}")

# Configure Guardrails
dome = client.protect("my-agent", guards=["prompt_injection", "pii"])

# Improve the agent
job = client.adapt("my-agent", mode="config")

How it works

The CLI and SDK are organized into two tiers, inspired by Git:

Porcelain commands (lifecycle verbs)

High-level commands that map to stages of the agent trust lifecycle:

Command	What it does
vijil discover	Find agents in GitHub repos or cloud infrastructure
vijil register	Convert agent source into an A2A card and genome
vijil evaluate	Measure against known standards (criterion-referenced)
vijil test	Explore under adversarial pressure (Swarm)
vijil adapt	Improve through corrective evolution (prompt, config, code, Dome)
vijil protect	Configure Dome runtime Guardrails
vijil monitor	View Dome telemetry (detections, traces, logs)
vijil evolve	Create a new agent through generative evolution
vijil deploy	Deploy to a production runtime

Plumbing commands (resource nouns)

Low-level CRUD operations on platform resources:

Command	Subcommands
vijil agents	list, show, create, update, delete
vijil evaluations	list, show
vijil harnesses	list, show, create, update
vijil genomes	list, show, diff, history
vijil jobs	list, status, cancel
vijil scores	show, history
vijil reports	list, show, download
vijil proposals	list, show, approve, apply, reject
vijil policies	list, show, create, update, delete
vijil personas	list, show, create, update, delete

Setup commands

Command	What it does
vijil auth	login, logout, status
vijil config	show, get, set

Key concepts

Evaluate vs Test: evaluate measures against known standards (like a certification exam). test explores for unknown weaknesses through adversarial pressure (like a penetration test). Both produce trust scores.

Adapt vs Evolve: adapt improves an existing agent through corrective evolution, fixing weaknesses found by evaluation or testing. evolve creates an entirely new agent from a spec or natural-language description.

Trust dimensions: Every evaluation produces scores across three dimensions — reliability (does it work correctly?), security (can it resist exploitation?), and safety (does it behave responsibly?).

Global options

--output, -o    Output format: table, json, yaml, quiet (default: auto)
--gateway       Gateway URL override
--api-key       API key override (or set VIJIL_API_KEY)
--quiet, -q     Quiet mode — IDs only
--verbose, -v   Debug logging

Shell composability

The CLI supports shell scripting:

# JSON output for machine consumption
vijil evaluate my-agent --baseline -o json | jq '.trust_score'

# Quiet mode returns just the ID
EVAL_ID=$(vijil evaluate my-agent --baseline -q)
vijil reports download "$EVAL_ID"

# Pipe agent list to evaluation
vijil agents list -q | xargs -I{} vijil evaluate {} --baseline --no-wait

Exit codes follow Unix convention:

Code	Meaning
0	Success
1	General error
2	Authentication error
3	Resource not found
4	Validation error
5	Job failed

Agent aliases

Set short names for agent IDs you use often:

vijil config set aliases.travel-agent d0087de1-a032-49f7-9d28-3abf4a34404d

# Now use the alias anywhere
vijil evaluate travel-agent --baseline
vijil scores show travel-agent

Framework integrations

Coming soon — Guides for integrating Vijil into agent development frameworks:

• Google ADK — Evaluate and protect ADK agents
• LangGraph — Add trust checks to LangGraph workflows
• CrewAI — Monitor and adapt CrewAI agents

See docs/integrations/ for the roadmap.

Documentation

Document	Description
Configuration	Auth setup, config file, credentials, CI/CD
CLI Reference	All commands with flags and examples
SDK Reference	Python client, resources, models, errors
Lifecycle Guide	End-to-end workflows for existing and new agents
Testing Guide	Running unit and integration tests
Integrations	Framework integration guides

Requirements

• Python 3.12+
• A Vijil account (console.vijil.ai)

License

Proprietary. Copyright 2024-2026 Vijil AI, Inc.