Documentation — Veltrix

Quickstart

Five minutes from install to a traced run. You need Python 3.10+ and an API key from the console.

1. Install the SDK

terminal

pip install veltrix
export VELTRIX_API_KEY="vx_live_..."
veltrix login --verify

2. Define an agent

agent.py

from veltrix import Agent, tool

@tool(scopes=["kb:read"])
def search_kb(query: str) -> list[dict]:
    # Your implementation; Veltrix handles retries and audit
    return kb.search(query, limit=5)

agent = Agent(
    name="docs-helper",
    model="claude-sonnet",
    tools=[search_kb],
    instructions="Answer from the knowledge base only.",
)

3. Run it locally, then deploy

terminal

# Local run with full trace output
veltrix run agent.py "How do I rotate an API key?" --trace

# Promote through evals to production
veltrix eval run --suite docs-golden --agent docs-helper
veltrix deploy --agent docs-helper --env production

Tip: veltrix dev starts a local inspector with replay, cost breakdown and policy simulation against recorded traces.

Core concepts

Four objects, no magic

Agent

A versioned definition: model, tools, instructions and policy reference.

Tool

A typed function with declared scopes, timeouts and an idempotency contract.

Run

One execution with a durable step log, cost, latency and outcome.

Policy

Versioned rules that decide whether a tool call is allowed, denied or paused.

API reference

REST over HTTPS, JSON everywhere

Base URL https://api.veltrix.com/v1. Authentication uses a bearer key; all endpoints are scoped to a workspace.

Method	Endpoint	Purpose
POST	`/runs`	Start a run for an agent version
GET	`/runs/{id}`	Fetch status, steps and cost
POST	`/runs/{id}/approve`	Grant or deny a paused action
POST	`/runs/{id}/cancel`	Stop a run, refund unused budget
GET	`/agents`	List agents and their deployed versions
POST	`/agents/{id}/deploy`	Promote a version to an environment
POST	`/evals`	Run an evaluation suite against a version
GET	`/audit/events`	Cursor-paginated audit stream
GET	`/usage`	Steps, tokens and spend by dimension

curl

curl -X POST https://api.veltrix.com/v1/runs \
  -H "Authorization: Bearer $VELTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "docs-helper",
    "version": "2026-11-04",
    "input": "How do I rotate an API key?",
    "idempotency_key": "req_8f21c"
  }'

Evaluation gates

Block the merge, not the incident

Suites run in CI on every prompt or tool change. Each case is scored on task success, groundedness, cost and latency; thresholds are per suite, not global.

Golden datasets versioned alongside the agent
LLM judges with calibration against human labels
Paired comparison against the currently deployed version
Failures attached to the pull request with replay links

.github/workflows/eval.yml

- name: Agent eval gate
  run: veltrix eval run --suite support-golden
       --min-success 0.94
       --max-cost 0.35
       --compare deployed
  env:
    VELTRIX_API_KEY: ${{ secrets.VELTRIX_API_KEY }}

CLI

The commands you will actually type

Command	What it does
`veltrix init`	Scaffold an agent project with CI and policy files
`veltrix dev`	Local inspector with replay and trace search
`veltrix run`	Execute a single run, optionally with a trace
`veltrix eval run`	Score a suite and compare to deployed
`veltrix deploy`	Promote a version through environments
`veltrix logs`	Stream run events in the terminal
`veltrix policy test`	Simulate a policy against recorded runs
`veltrix rollback`	Restore the previous deployed version

Changelog

Recent releases

2026-11-06 · v4.2
Approval delegation, per-tool cost ceilings, and Go SDK 1.0.
2026-09-18 · v4.1
EU region GA, customer-managed keys, audit export to Splunk.
2026-07-29 · v4.0
New runtime with durable checkpoints; 3x throughput on parallel tools.
2026-05-12 · v3.8
Eval gates in GitHub Actions, human review queues, TypeScript SDK 2.0.