experiential README

项目的 README,来自 github.com/experientiallabs/experiential。合并为一个 markdown 文件:README.md。

Experiential

gateway latency

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.

Experiential workspace usage dashboard showing model traffic, identities, and spend

🌐 Platform | 📚 Docs | Discord

Getting Started

Start a local OpenAI-compatible gateway. On first run, the setup wizard uses the shared provider, model, and reasoning-effort selectors, persists every selected provider connection, then shows defaults for the public alias, identity, and $50.00 command budget before printing a one-time key:

pip install experiential
exp

Choose a public alias such as opus-5, 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":"opus-5","messages":[{"role":"user","content":"Help me"}]}'

Setup / get started with the hosted gateway

Prefer a managed gateway to running one locally? The hosted platform at platform.experientiallabs.ai serves the same OpenAI-compatible (and Anthropic Messages) API at https://api.experientiallabs.ai/v1. See SETUP.md for copy-paste prompts you hand to your coding agent (Claude Code, Cursor, Codex, and similar); the agent runs the setup for you. It collects four prompts:

Using the API

Start the local gateway with exp (or exp run); the compiled native data plane serves every route on loopback. From Python, load a fitted project router as an official OpenAI client backed by its own private gateway:

import exp

with exp.load_router("my-project") as client:
    response = client.chat.completions.create(
        model="my-project",
        messages=[{"role": "user", "content": "hello"}],
    )

Coding Agent

exp code runs exp-code, Experiential's open-source coding and cowork agent built on Pi. It needs Node.js 22.19 or newer and uses your running local gateway, or the hosted gateway after exp login:

exp code                       # interactive terminal UI
exp code -p "Summarize sales.csv into report.docx"

Every argument goes to exp-code, so its print, JSON, and RPC modes work through exp code too.

Capture Traffic

Capture is designed to collect supported traces from the Codex and Claude Code desktop apps using your existing ChatGPT or Claude subscription, while requests go directly to OpenAI or Anthropic. It requires macOS, Python 3.13 or newer, and approval for its extension and certificate:

exp capture

Capture is experimental; macOS network reliability is still under investigation.

Use Experiential's gateway as middleware to control costs, enforce guardrails, and optimize quality, costs, and speed. Leave the terminal open while you work. Press Ctrl+C to stop capture. View your capture telemetry.

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.

experiential (experientiallabs/experiential)

正在搜索数据库…

这是什么?Experiential 是一个开源的网关和路由器,面向智能体工作流。你可以通过一个 OpenAI 兼容的 API 使用托管模型、自带密钥(BYOK)模型和本地模型,控制谁能在哪些模型上花多少钱,还能把生产环境的流量转化为定制的优化路由器,或你自己微调的模型。
这是我自己运行的网关,还是只能用托管服务?两者都可以:你可以通过 exp 命令行工具在本地运行 OpenAI 兼容网关,也可以使用托管平台 platform.experientiallabs.ai,它提供相同的 API,无需任何本地设置。
我该怎么把网关跑起来?运行 exp(或 exp run)启动本地网关。首次运行时,设置向导会引导你选择服务商、模型和推理力度,默认设置 50.00 美元的命令预算,并打印一个一次性 API 密钥,之后你就用它来发送请求。
使用它需要我自己的模型服务商 API 密钥吗?在 BYOK 模式下,你可以接入自己的 OpenAI、Anthropic、Gemini、Azure、Bedrock、Fireworks 或 OpenRouter 密钥,以免费直通方式使用。如果你不想自带密钥,它也支持托管模型和本地模型。
我可以把哪些编程智能体指向这个网关?设置文档介绍了如何把 Claude Code、Cursor、Codex、Aider 等类似的编程智能体(以及 Conductor)改为指向网关的 OpenAI/Anthropic 兼容端点。
它会追踪我的提示词或数据吗?默认会开启匿名的汇总 PostHog 遥测,但明确不包括提示词、追踪记录、操作、观察结果、路径、模型名称、凭据和原始客户内容;是否参与的偏好设置保存在本地。
它如何根据我的流量优化成本?它会接收你的智能体流量产生的 OpenTelemetry 追踪数据,通过构建向导引导你配置服务商、模型和预算,然后可以根据这些追踪数据,使用 Tinker 微调一个你拥有的开源模型。
这里的 Tinker 有什么用?在从你的路由器收集追踪数据之后,Experiential 会使用 Tinker 微调一个你拥有并掌控的开源模型,而不是依赖某家厂商的闭源模型。
我没有自己的流量,能先试用优化流程吗?可以,有一个公开的 terminal-tasks OTLP 数据集,你可以下载它,在上传自己的数据之前先测试基于追踪数据的优化流程。
它支持 Anthropic 的 API 格式,还是只支持 OpenAI 的?网关在同一个端点上同时提供 OpenAI 兼容的 API 和 Anthropic Messages 兼容的 API。
大小
113.3 MB
星标
17.6K
时长
4个月
提交 · 90 天