Experiential

Experiential is an open source gateway and router for agent workflows:

1. Use hosted, BYOK, and local models through one OpenAI-compatible API.
2. Control which users and agents can use which models, for which use cases, and how much they can spend.
3. Turn production traffic into a custom router or model optimized for quality, speed, and cost.

🌐 Platform | 📚 Docs | Discord

Getting Started

Start a local OpenAI-compatible gateway. On first run, the setup wizard asks for a provider, model, and public alias, then prints a one-time virtual key:

pip install experiential
exp run

Choose a public alias such as support-agent, capture the issued key, and send a request:

export EXP_GATEWAY_KEY=...
curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $EXP_GATEWAY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"support-agent","messages":[{"role":"user","content":"Help me"}]}'

Using the API

Create a local gateway programmatically:

import uvicorn

from exp.runtime.gateway.lifecycle import load_local_gateway

gateway = load_local_gateway()
uvicorn.run(gateway.app, lifespan="on")

For hosted workers with their own storage and provider services, use the lower-level exp.create_gateway_runtime(...) composition API.

Optimize from Traffic

First, collect OpenTelemetry traces from your current agent. If you just want to try it out, grab the public terminal-tasks OTLP dataset:

curl -L -o traces.otel.jsonl \
  https://huggingface.co/datasets/experiential-labs/wmo-terminal-tasks-traces/resolve/540883e451dc13d34fb50fdd36b143cb0f1fb0db/traces.otel.jsonl

Then build a project. The build command walks you through providers, models, and budget, and asks for your trace file:

# Build simulation from your agent traces and optimize a router against it
exp build support-agent

After collecting traces from your router, fine-tune an open source model you own using Tinker.

exp optimize model support-agent

Telemetry

Anonymous aggregate PostHog product telemetry is enabled by default. It never includes prompts, traces, actions, observations, paths, model names, credentials, or raw customer content.

exp config telemetry status
exp config telemetry disable
exp config telemetry enable

The preference is stored locally in .exp/settings.toml.

Development

uv sync --extra dev
uv run ruff format --check .
uv run ruff check .
uv run ty check
uv run pytest -q

Repository and documentation conventions live in AGENTS.md.