Tracely

这个 Agent 能做什么，适合哪些场景？

Tracely 是一个可自托管的 AI Agent 可观测与回归测试平台。它通过 OTLP/HTTP 接收任何语言产生的 trace，把 agent.id、conversation.id、turn、step 等语义提升为 ClickHouse 中的一级索引列，从而按会话线程而非扁平 span 展示运行。在线评测器会在 trace 落地时打分，失败再按结构与语义聚类成 issue，而非几百行待读记录。一键即可把失败 trace 冻结为 hermetic 回归用例，附带 fail-to-pass 契约，并在 CI 中以录制好的工具与 LLM fixture 回放——离线、无需 API Key、无模型花费。tracely gate 命令会以非零退出码、提交状态和 PR 评论拦截回归；整个栈由 FastAPI 后端、Celery/Redis worker、Next.js 前端、Postgres、ClickHouse 与 MinIO 组成，可用 Docker Compose、Railway、Coolify 或 EKS 部署。

数据从 SDK 或任意 OTLP/HTTP exporter 进入 POST /v1/traces，先写入 S3/MinIO 保证持久化，再进 Redis/Celery；worker 完成 OTel 映射、注册表 upsert 并写入 ClickHouse 事件表，随后执行 evaluate_run_task 生成分数与结构聚类，触发告警流。评测器是 trace 表上的列，支持无需模型的结构化检查和会话/运行/span 三级的 LLM-as-judge，分数通过 SSE 实时回填。失败聚类后可用一次点击把 trace 提升为回归用例（录制输入、工具与 LLM 输出作为 fixture），并附加 fail-to-pass 契约；多轮行为则用 scenarios（脚本化对话或红队模型追求对抗目标）表达。CI 侧提供 tracely simulate / replay / gate 三个命令与 GitHub Action：gate 失败时非零退出、写入 commit status、更新 PR 评论。告警以触发器加可视化流程表达，步骤包括 condition、Slack、email、webhook、LLM prompt 与 Python 表达式。

1. 生产环境的客服 Agent 偶发答错订单查询：用 Tracely 接收 OTLP trace，让 judge 在会话级别打分，把失败聚类成一个 issue，再提升成回归用例防止复发。
2. 多 Agent 系统的排障：需要按会话线程查看 agent → thinking → skill → generation → hand-off 的瀑布图，并借助 Fleet 像素视图向非工程同事解释 handoff。
3. 把 CI 门禁接进 GitHub Actions：用 tracely gate 在 PR 上拦截会重新引入已知失败模式的改动，并以 commit status 和 PR 评论呈现结果。
4. 无法在 CI 中调用真实模型的团队：用 hermetic replay 以录制的 fixture 复现失败输入，做到零 API 成本且完全确定。
5. 评测器校准：把 judge 判定与人工复核结果对齐，看每个评测器的一致率，避免过度告警的 judge 进入门禁。
6. 自托管合规场景：通过 docker compose --profile demo 或 Railway/Coolify/EKS 部署整套 API、worker、UI 与数据库，数据不出内网。
7. 让编码代理直接操作工作区：通过 /mcp 端点让 Claude Code 等客户端读取 trace、创建评测器与告警。

如何安装或部署这个 Agent？

整体栈最快的方式是 Docker Compose，会把 ClickHouse、Postgres、Redis、MinIO、API、worker 和前端一起拉起，并灌入演示数据：

git clone https://github.com/jwuthri-cloud/Tracely-ai && cd Tracely
docker compose --profile demo up -d --build --wait
open http://localhost:3001

本地开发需要 uv 与 Node 20+/pnpm：

cp .env.example .env
make infra-up      # clickhouse, postgres, redis, minio
make install       # uv sync + pnpm install
make migrate       # ClickHouse DDL + Alembic (Postgres)
make seed          # default project + ingest key → tracely_dev_key

采集 SDK：

pip install "tracelyai-sdk[openai]"     # 或 [anthropic], [langchain], [all]

托管部署可一键上 Railway；Coolify 用户可用 python3 deploy/coolify/setup.py --coolify-url … --app-domain … --api-domain …；Kubernetes 见 deploy/eks/README.md。部署时需设置 SESSION_SECRET 与 SECRETS_ENCRYPTION_KEY（各自 openssl rand -hex 32），AUTH_MODE 默认为 dev（免登录）。

如何使用这个 Agent？

初始化 SDK 后包裹一次运行，provider 调用会被自动捕获：

import tracely_sdk as tracely

tracely.init(
    endpoint="http://localhost:8000",
    api_key="tracely_dev_key",
    service_name="support-agent",
    env="prod",
    instrument="auto",
)

with tracely.trace(agent="support-agent", conversation="conv-1", user="u_42"):
    client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Where is order ORD-4471?"}],
    )

也可以让任意 OTLP/HTTP exporter 指向 POST {endpoint}/v1/traces，鉴权用 Authorization: Bearer tracely_dev_key。CI 门禁有三种方式，其中让 Tracely 主动调用你的 agent：

      - uses: jwuthri-cloud/Tracely-ai/.github/actions/tracely-gate@master
        with:
          api:   https://tracely.your-co.dev
          key:   ${{ secrets.TRACELY_KEY }}

或者对录制的用例做 hermetic 回放：

pip install tracelyai-sdk
tracely replay planner --entrypoint my_pkg.agent:run

接入 MCP 让编码代理直接读工作区：

claude mcp add --transport http tracely http://localhost:8000/mcp \
  --header "Authorization: Bearer tracely_dev_key"

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

常见问题