Agenta-AI/agenta · 上手攻略

仓库：Agenta-AI/agenta
链接：https://github.com/Agenta-AI/agenta
分类：evaluation（LLMOps / 评估 / 可观测性）
作者：spark
更新：2026-07-17

是什么

Agenta 是一个开源的 LLMOps 平台，把 LLM 应用从原型到生产所需的四件事压在一个工作流里：Prompt Playground（交互式调试）、Prompt/Cofig 管理（带版本和分支）、LLM 评估（人评 + 自动评估 + LLM-as-judge）、可观测性（Tracing、成本、延迟）。代码以 TypeScript 为主、许可 NOASSERTION（实际为 MIT，README 显示 MIT 徽章），stars 约 4.3k，最近一次采集为 2026-07-17，最近提交 2026-07-16，维护活跃。

它不是 LangChain 那种 agent 框架，也不是 LiteLLM 那种纯路由网关，而是"prompt + eval + observability"三件套，定位与 Langfuse、Helicone、PromptLayer、Portkey 都重合，但 agenta 把 playground 和评估做成了 UI 优先的协作工具，面向工程师之外的 SME（业务、运营、产品）也能直接上手。

解决什么问题

LLM 应用落地时，反复出现的痛点是：

prompt 改了一行就翻车——某个 prompt 在 100 条用例上 90% 准确，改了一句话掉到 60%，没体系化对比看不出来。
prompt 版本和代码版本脱节——产品改了一段 prompt，没人记得对应哪个版本、哪个分支、哪个线上实验。
评估靠人肉——每次发版都要 QA 跑几百条，效率低且不一致。
线上可观测性差——一次调用到底走了哪些 prompt、用了哪个模型、花了多少 token、为什么超时，几乎不可见。

Agenta 把这几件事收成一个工作台：UI 里调 prompt → 自动入库成版本 → 用 testset 跑评估 → 接入 OpenTelemetry 拿到线上 trace。SME 可以用 Web 改 prompt 不碰代码，工程师可以通过 SDK 把整套流程接入 CI/CD。

快速安装

官方推荐两种路径：Agenta Cloud（免费层，无需绑卡）和 Docker Compose 自托管。

路径 A：Agenta Cloud（最快）

# 1) 注册并拿到 API key
#    https://cloud.agenta.ai

# 2) 安装 Python SDK
pip install agenta

# 3) 在 SDK 中配置 API key
export AGENTA_API_KEY="your-api-key"

路径 B：Docker Compose 自托管（开源版）

git clone https://github.com/Agenta-AI/agenta && cd agenta

cp hosting/docker-compose/oss/env.oss.gh.example \
   hosting/docker-compose/oss/.env.oss.gh

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml \
  --env-file hosting/docker-compose/oss/.env.oss.gh \
  --profile with-web --profile with-traefik up -d

# 浏览器访问 http://localhost

自托管默认会把 Web UI、API、Postgres、对象存储都拉起来，远程部署 / 改端口参见 self-host 文档。准备至少 4GB 内存和 Docker 24+。

核心用法

1. 创建一个 prompt 应用

Agenta 的核心抽象是 "app"——一段 prompt 模板 + 输入变量 + 模型配置。SDK 用装饰器风格：

import agenta as ag
from openai import OpenAI

client = OpenAI()

@ag.entrypoint
def generate_article(topic: str, tone: str = "neutral") -> str:
    prompt = f"写一篇关于 {topic} 的短文，风格 {tone}。"
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}],
    )
    return resp.choices[0].message.content

启动后，Agenta 会把这个函数注册成一个可配置应用，UI 里能直接看到 topic/tone 两个变量和模型选择。

2. Playground 调试

Web UI 里点开 app，能并排对比不同 prompt、不同模型对同一组输入的输出；改完点"Save as variant"会自动入库一个版本。

3. 评估：testset + evaluator

先用 testset（CSV 上传、从 playground 抓取、或从生产 trace 抽样）覆盖若干用例，再选 evaluator：

import agenta as ag

# 20+ 内置 evaluator，例如 exact_match、levenshtein、llm_as_judge 等
evaluator_config = {
    "prompt_template": (
        "请判断以下回答是否回答了用户问题。\n"
        "问题：{question}\n回答：{answer}\n"
        "回复 PASS 或 FAIL。"
    ),
    "llm": "gpt-4o-mini",
}

testset = [
    {"question": "法国的首都是？", "answer": "巴黎"},
    {"question": "1+1=?", "answer": "2"},
]

result = ag.evaluate(
    app_slug="generate-article",
    testset=testset,
    evaluators={"correctness": evaluator_config},
)
print(result.summary)

4. 可观测性：OpenTelemetry 接入

agenta 的 tracing 走 OpenTelemetry 原生协议，跟 OpenLLMetry / OpenInference 兼容：

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(
    endpoint="http://localhost:4318/v1/traces"
)))
trace.set_tracer_provider(provider)

之后所有 ag.entrypoint 调用都会自动上报 span，Web UI 里能看到 prompt 模板、变量值、模型、token、延迟、错误。

5. 自定义 provider / BYO 模型

支持 50+ LLM（OpenAI、Anthropic、Cohere、Mistral、Azure、Vertex、Bedrock…），也支持自带的网关协议接入私有部署。

典型适用场景

RAG / Agent 团队的内部平台：多个 prompt 变体要 A/B、要回归，研发 + 产品 + QA 都要参与迭代。
多语言 / 多地区产品的 prompt 矩阵：一份 prompt 衍生出 10 个语言变体，UI 上批量对比和管理。
LLM-as-judge 评估流水线：CI 里跑评测集，自动判断是否回滚。
业务团队"零代码"调 prompt：让运营在 Playground 上调营销话术，不动代码仓库。

坑与注意

许可写的是 NOASSERTION，但 README 徽章是 MIT——公司用之前自己 git log 一下确认，尤其是私有部署。
自托管体积不小：默认 compose 会拉起 Web、API、Postgres、对象存储、Traefik，初次启动 5–10 分钟属正常。
Evaluator 模板质量决定评测质量：内置 LLM-as-judge 的 prompt 是英文示例，做中文任务需要改写。
BYO 模型走 OpenAI-compatible API：如果用自研推理网关（vLLM / TGI / SGLang 等），需要确保它支持 /v1/chat/completions，否则要走 custom provider 适配。
trace 采样率要设：默认全量上报，高 QPS 场景会爆 OTLP collector，记得在 SDK 侧加 sampler。
2026 年版本迭代频繁：API/SDK 在 0.x → 1.x 期间可能有破坏性变更，跟随官方 changelog。

与同类对比

项目	强项	弱项	适合
Agenta	Playground + eval + observability 三合一；SME 友好	自托管略重；社区规模小于 Langfuse	中小团队、需要业务参与 prompt 调优
Langfuse	Tracing / 评估成熟，Python/JS 双 SDK，社区大	Playground 偏弱，更多是 devtool	偏工程师、需要和 LangChain 深度集成
Helicone	极简代理层接入，1 行代码接 observability	评估能力弱	只想要可观测性、不想自建
PromptLayer	老牌 prompt log，可视化好	eval / observability 功能单一	早期 prompt 版本管理
Portkey	路由 + 缓存 + fallback 强	prompt eval 不是主战场	多模型路由 + 成本优化

Agenta 的差异化是把 prompt 实验 → 版本管理 → 自动评估 → 线上 trace 串成一条流，而不是每段单独买。

一句话推荐结论

如果你的团队已经有 5+ 个 prompt 在跑、且业务方要参与调优，Agenta 是把"协作 + 评估 + 可观测"压在一个工作台里最务实的开源选择；个人小项目用 Cloud 免费层就够，重度自托管先评估 Docker 资源再上。