agenta 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

agenta 项目

开源 LLMOps 平台，集提示词调试、提示词管理、LLM 评估与 LLM 可观测性于一体。

Project Overview and System Architecture

Agenta 是一个面向大语言模型（LLM）应用的全栈开发与观测平台，覆盖提示工程（prompt engineering）、评估（evaluation）、可观测性（tracing / observability）以及托管部署等关键环节。社区近期讨论集中在评估结果表格的 scenario 过滤（4282）、Azure OpenAI 集成诉求（2153）以及首次部署后默认凭据不...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 实体（Entity）层

继续阅读本节完整说明和来源证据。

章节 评估与可观测性

继续阅读本节完整说明和来源证据。

章节 编辑器与富交互

继续阅读本节完整说明和来源证据。

项目概览与系统架构

项目定位与核心能力

Agenta 是一个面向大语言模型（LLM）应用的全栈开发与观测平台，覆盖提示工程（prompt engineering）、评估（evaluation）、可观测性（tracing / observability）以及托管部署等关键环节。社区近期讨论集中在评估结果表格的 scenario 过滤（#4282）、Azure OpenAI 集成诉求（#2153）以及首次部署后默认凭据不可用的问题（#2675），这些议题共同指向平台"提示即代码 + 多人协作评估 + 一键自托管"的核心定位。

平台以 FastAPI 为后端基础，通过 Python SDK 提供调用入口，并以 Next.js 15 + React 19 构建管理控制台。前端核心交互——例如提示词编辑器——基于 Lexical 富文本与代码编辑框架，支持 JSON / YAML 语法高亮、模板变量（token）渲染、Diff 对比与表单化编辑。资料来源：web/packages/agenta-ui/src/Editor/README.md:1-15。

系统架构总览

Agenta 仓库采用「后端 API + 前端 Web + SDK + 示例应用」四层结构：

flowchart LR
    A["Next.js 前端 Web<br/>web/oss"]
    B["FastAPI 后端<br/>api/oss + api/ee"]
    C["TypeScript SDK<br/>web/_reference/agenta-sdk"]
    D[("Postgres / Alembic")]
    E[("向量库 / 第三方 LLM")]
    F["examples/python/*"]
    G["Python SDK<br/>agenta_client"]
    A --> B
    A --> C
    B --> D
    B --> E
    F --> B
    G --> B

后端同时提供 OSS 版与 EE 版入口，前端 web/oss 通过模块化（modules）+ Jotai 原子化状态分层组织代码，跨模块共享的 hooks、组件与类型逐级上提，从而平衡"模块自治"与"全局复用"。资料来源：web/oss/README.md:1-40。

核心模块构成

实体（Entity）层

@agenta/entities 包集中实现工作流（workflow）、追踪（trace）、环境（environment）、测试集（testset）、测试用例（testcase）等实体的"molecule"控制器，统一暴露 atoms / actions / get / set / useController / cleanup 接口。配套的 @agenta/entity-ui 提供模态、选择器与下钻视图等 UI 组件。环境实体额外抽象了 Git 三层模型 Environment → EnvironmentVariant → EnvironmentRevision，并通过 SimpleEnvironment API 在前端隐藏 git 细节，支持 is_guarded 守门提交与基于 delta（set / remove）的增量变更。资料来源：web/packages/agenta-entities/README.md:1-50、web/packages/agenta-entities/src/environment/README.md:1-30。

评估与可观测性

评估结果支持以 scenario 维度组织表格，社区在 #4282 中要求新增列内过滤以便横向对比多次运行。平台同步通过 tracing 模块聚合 span、trace、session 与人工标注（annotation），形成评估—观测—反馈闭环。资料来源：web/_reference/agenta-sdk/README.md:1-30。

编辑器与富交互

@agenta/ui 中的 Editor 组件支持 codeOnly、showToolbar、enableTokens、templateFormat 等十余项配置，可结合 JSON Schema 校验实现"prompt 即代码"的编辑体验，并通过 onPropertyClick 与下钻视图（DrillInView）联动。资料来源：web/packages/agenta-ui/src/Editor/README.md:15-50。

部署与开发工作流

仓库提供 hosting/docker-compose/oss/ 下的 Compose 文件用于一键部署；社区案例（#2675）显示 agenta-oss-gh-alembic-1 容器迁移失败会导致 Web 容器无法初始化，建议首次启动后立即修改默认账号密码并确认数据库迁移日志。examples/python/ 目录提供 RAG 问答等端到端样例（如 RAG_QA_chatbot、rag-docs-qa），使用 Qdrant、Cohere 与 OpenAI 演示"文档摄取 → 语义检索 → 流式回答 → 标注"全链路。资料来源：examples/python/RAG_QA_chatbot/README.md:1-20、examples/python/custom_workflows/rag-docs-qa/README.md:1-30。

在代码治理方面，agents/skills/ 定义了 scan-codebase / test-codebase / sync-findings / triage-findings / resolve-findings 五段式技能工作流，统一处理 GitHub 评论、文档与测试三方证据，确保 OSS/EE 收敛评估与 schema parity 设计（v0.104.0 引入）等关键变更可追溯。资料来源：agents/skills/README.md:1-30。

Evaluation System and Workflows

Agenta 的评估系统是一套用于对大语言模型（LLM）应用进行打分、对比与回放的前端数据层与工作流编排框架。它在 web/packages/agenta-entities 包内以 molecule（分子）架构组织，将"应用修订（app revision）"、"评估器修订（evaluator revision）"、"测试集（testset）"、"测试用例（testcase...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 实体控制器 API

继续阅读本节完整说明和来源证据。

章节 可执行实体（Runnable）

继续阅读本节完整说明和来源证据。

章节 测试集与测试用例

继续阅读本节完整说明和来源证据。

评估系统与工作流

概述

Agenta 的评估系统是一套用于对大语言模型（LLM）应用进行打分、对比与回放的前端数据层与工作流编排框架。它在 web/packages/agenta-entities 包内以 molecule（分子）架构 组织，将"应用修订（app revision）"、"评估器修订（evaluator revision）"、"测试集（testset）"、"测试用例（testcase）"、"环境（environment）"等核心实体统一抽象，并通过 runnable、evaluationQueue、evaluationRun 等专用模块提供执行、排队、结果回放能力。

评估系统的核心职责包括：

版本化执行单元：每一个被评估的对象都是一个 runnable（可执行实体），涵盖应用修订与评估器修订两类。资料来源：web/packages/agenta-entities/src/runnable/README.md:1-15
声明式状态管理：每个实体遵循一致的 controller 模式，提供 atoms（订阅）、actions（写入）、useController（React 钩子）与 cleanup（资源回收）。资料来源：web/packages/agenta-entities/README.md:30-50
能力命名空间：对于可执行与可加载实体，额外暴露 runnable.* 与 loadable.* 子命名空间，承载输入/输出端口、字段映射、调用桥接等职责。资料来源：web/packages/agenta-entities/README.md:50-58

核心实体与控制器模式

实体控制器 API

Agenta 前端在 agenta-entities 包内为每类实体提供统一的访问形态：

命名空间	用途
`entity.atoms.*`	通过 Jotai atom family 进行响应式订阅
`entity.actions.*`	写入型原子，配合 `set()` 进行组合
`entity.get.` / `entity.set.`	命令式读写，供回调函数使用
`entity.useController`	React 钩子，合并原子与派发
`entity.cleanup.*`	卸载与内存回收

资料来源：web/packages/agenta-entities/README.md:36-58

可执行实体（Runnable）

runnable 模块统一了"可被调用并产生输出"的实体，是评估系统中最核心的抽象。运行时的输入端口（inputPorts）、输出端口（outputPorts）以及运行时配置（configuration）都通过 workflowMolecule 的选择器暴露给 UI 层：

const data = useAtomValue(workflowMolecule.selectors.data(revisionId))
const inputPorts = useAtomValue(workflowMolecule.selectors.inputPorts(revisionId))
const outputPorts = useAtomValue(workflowMolecule.selectors.outputPorts(revisionId))

资料来源：web/packages/agenta-entities/src/runnable/README.md:9-25

模块内部按 types.ts（共享类型与端口定义）、状态管理与选择器等分层组织，明确划分职责。资料来源：web/packages/agenta-entities/src/runnable/README.md:30-45

测试集与测试用例

评估的输入来源由 testset / revision / testcase 三级关系描述：testset 拥有多个 revision，每个 revision 可挂载一批 testcase。资料来源：web/packages/agenta-entities/src/testset/README.md:1-20、资料来源：web/packages/agenta-entities/README.md:8-22

testcase 模块额外提供 testcaseDataController，作为分页表格的数据源抽象，支撑 InfiniteVirtualTable 这类大型结果集的渲染。资料来源：web/packages/agenta-entities/src/testcase/README.md:1-30

环境与部署

环境是评估执行的载体。后端使用三层的 git 模型（Environment → EnvironmentVariant → EnvironmentRevision），前端通过 SimpleEnvironment API 将其扁平化。修订提交支持"全量快照（data）"与"增量操作（delta，包含 set/remove）"两种模式。被守卫（is_guarded: true）的环境必须在部署前显式批准。资料来源：web/packages/agenta-entities/src/environment/README.md:1-30

flowchart LR
  TS[Testset] --> RV[Revision]
  RV --> TC[Testcase 列表]
  TC --> RN[runnable.workflowMolecule]
  RN --> EV[Environment Revision]
  EV --> Q[evaluationQueue]
  Q --> RUN[evaluationRun]
  RUN --> RES[结果 / 打分 / 回放]

数据流与状态管理

Server → Atom 链路

所有实体均采用一致的取数路径：HTTP 响应 → TanStack Query → Jotai atoms。资料来源：web/packages/agenta-entities/README.md:55-65。这意味着评估结果一旦从后端拉回，前端组件即可通过 useAtomValue 订阅，无需手动维护缓存同步逻辑。

模块化目录与状态归属

web/oss 工程将功能划分为"模块（module）"，每个模块自包含组件、钩子与静态资源。状态归属遵循三条原则：

仅在单个组件使用的状态保留为局部 useState；
模块内多个组件共享的状态下沉到模块 store/（Jotai atoms / Context）；
跨模块共享的状态提升到根 store/。资料来源：web/oss/README.md:1-40

这一约定直接影响评估页面：当筛选、对比、回放等状态仅用于评估模块时，应放置于模块内 store；如需跨页签保持选中态，则提升到全局。社区在 #4282 中提出的"评估结果表筛选"诉求，正是建立在 testcaseDataController 提供的分页数据源之上。

评估队列与执行协调

simpleQueue、evaluationQueue、queue 与 evaluationRun 四个模块共同承担评估任务的编排：

simpleQueue 提供最小可用的队列原子；
evaluationQueue 在其之上叠加评估场景所需的元数据；
queue 作为统一队列控制器整合两者；
evaluationRun 记录每一次评估运行的快照与结果。

资料来源：web/packages/agenta-entities/README.md:18-28

与 SDK、可观测性的集成

agenta-sdk 通过 annotations 命名空间提供基于 trace 的人工反馈与查询能力，使评估器可针对任意 trace/span 写入或读取标注；tracing 命名空间则暴露 querySpans、queryTraces、queryByApplication 等接口用于评估结果回溯。资料来源：web/_reference/agenta-sdk/README.md:1-40

在 examples/python/RAG_QA_chatbot 中，FastAPI 后端通过 Agenta Cloud 完成完整追踪（tracing），进而被用于评估与调试：响应流式输出、引用回显、链路可观测均通过这一通道闭环。资料来源：examples/python/RAG_QA_chatbot/README.md:1-30

需要注意的是，评估器修订通常通过 LiteLLM 调用上游模型，社区在 #2153 中提出的 Azure OpenAI 集成诉求，本质上需要在 SDK 与评估器层补齐相应的 provider 适配。在 #637 提出的 Pydantic 升级也直接关系到评估器输入/输出 schema 的校验能力。

常见问题与失败模式

登录与部署失败：使用 docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh --profile with-web up -d 部署后，agenta-oss-gh-alembic-1 容器可能因迁移失败无法启动（见 #2675），导致评估相关数据库表无法创建。
结果筛选缺口：评估结果表的列筛选尚未提供（见 #4282），需要结合 testcaseDataController 的分页能力手动实现。
依赖膨胀：agenta-web 中存在未使用的依赖与错位的 type dependencies（见 #1712），可能影响评估页面的构建产物尺寸与启动速度。

参见

来源：https://github.com/Agenta-AI/agenta / 项目说明书

Observability, Tracing, and Prompt Management

Agenta 平台围绕 LLM 应用的可观测性（Observability）、追踪（Tracing）和提示词（Prompt）版本管理构建核心能力。Python 与 Node.js 端的官方示例均通过 OpenTelemetry（OTel）协议把 span / trace 推送到 Agenta，使后端能够统一记录每一次 LLM 调用、检索与提示词渲染过程资料来源：exam...

章节 相关页面

继续阅读本节完整说明和来源证据。

可观测性、追踪与提示词管理

概述与目标

Agenta 平台围绕 LLM 应用的可观测性（Observability）、追踪（Tracing）和提示词（Prompt）版本管理 构建核心能力。Python 与 Node.js 端的官方示例均通过 OpenTelemetry（OTel）协议把 span / trace 推送到 Agenta，使后端能够统一记录每一次 LLM 调用、检索与提示词渲染过程资料来源：examples/node/observability-vercel-ai/README.md:30-50。

前端通过 @agenta/entities/trace 模块读取追踪数据，并将其与提示词、应用变体绑定展示，最终在评估、调试、对比与回滚场景中复用同一份 trace 上下文资料来源：web/packages/agenta-entities/src/trace/README.md:1-40。社区中关于评估结果过滤（issue #4282）与 Azure OpenAI 集成（issue #2153）的讨论均直接依赖追踪层提供的数据上下文——若缺失 span 归因，评估对比和模型替换都难以落地。

最新发布 v0.104.0 完成了 OSS/EE 共用 membership 表与 schema parity 的对齐，使自部署场景下的追踪与提示词租户隔离更加稳定（参见最新发布说明）。

追踪数据流与 SDK 接入

flowchart LR
    A[用户应用<br/>SDK / OTel] --> B[OTLP Exporter]
    B --> C[Agenta OTLP 接入]
    C --> D[规范化<br/>Normalizer / Adapter]
    D --> E[追踪服务<br/>tracing/service.py]
    E --> F[(数据库)]
    F --> G[@agenta/entities/trace<br/>前端 atom]
    G --> H[Trace 树 / 详情面板]

Node.js 端的最小接入示例：只需在 generateText 调用上启用 experimental_telemetry.isEnabled = true，SDK 便会自动创建并导出 span，无需手写 OTel 代码资料来源：examples/node/observability-vercel-ai/README.md:30-50。Python 端的 RAG 例子在 FastAPI 后端调用 Agenta SDK，把 Qdrant 检索、提示词拼接、模型推理都纳入追踪范围资料来源：examples/python/RAG_QA_chatbot/README.md:1-20。

官方 TypeScript SDK 在 tracing 命名空间下提供 querySpans / queryTraces / queryByApplication / getTrace / getSpan / deleteTrace / querySessions / queryUsers / queryAnalytics 等高级查询资料来源：web/_reference/agenta-sdk/README.md:1-30。@agenta/sdk/ai 在此之上进一步抽象 agent 循环与停止条件，把 applicationSlug 自动绑定到追踪中的 applicationId 资料来源：web/_reference/agenta-sdk-ai/src/README.md:30-70。

前端追踪实体模块

@agenta/entities/trace 是 Agenta 前端处理追踪的核心 entity，遵循统一的 Entity Controller Pattern：atoms 提供响应式订阅，actions 写入原子，get / set 暴露命令式 API 资料来源：web/packages/agenta-entities/README.md:40-70。

模块在两个抽象层级上工作：

层级	名称	用途	特性
Span	`molecule`	编辑单个 span、追踪详情面板	支持 draft 与 dirty 跟踪
Trace	`traceEntityAtomFamily`	拉取完整 trace	只读、自动填充 span 缓存

资料来源：web/packages/agenta-entities/src/trace/README.md:50-70。

文件夹结构遵循 core / api / state / utils 的分层约定，便于在不同 entity 之间复用 selector 与类型定义资料来源：web/packages/agenta-entities/src/trace/README.md:10-30。在引导（onboarding）流程中，"Annotate traces" 与 "Create a test set from traces" 两个引导步骤都以追踪事件（trace_annotated、testset_created_from_traces）作为完成判据，进一步佐证 trace 是连接调试、评估与测试集的枢纽资料来源：web/oss/src/lib/onboarding/widget/config.ts:1-50。

提示词与环境管理

提示词以 Environment 实体形式存储在 Git 风格的三层版本库中：Environment → EnvironmentVariant → EnvironmentRevision。前端通过 SimpleEnvironment API 将其扁平化为单一对象，variant_id 与 revision_id 内部对 git 层透明，使前端组件无需感知底层版本控制资料来源：web/packages/agenta-entities/src/environment/README.md:30-70。

每次提交既可以是完整快照（data）也可以是增量 delta（set / remove），实现轻量回滚与对比。生产环境可设置 is_guarded: true，必须显式调用 guardEnvironment / unguardEnvironment 才能覆盖资料来源：web/packages/agenta-entities/src/environment/README.md:60-90。

关键端点（来自同源 README）：POST /simple/environments/query、POST /simple/environments/、PUT /simple/environments/{id}、POST /simple/environments/{id}/archive|unarchive、POST /simple/environments/{id}/guard|unguard、POST /environments/revisions/commit、POST /environments/revisions/query。

常见故障：自部署 OSS 时若 alembic 容器（issue #2675）未正常启动，会导致用户/membership 表漂移，进而在写入 trace 时触发外键错误。建议先用 docker compose ps 确认 agenta-oss-gh-alembic-1 处于 healthy 状态后再进行追踪写入。

Self-hosting, Database Migrations, and LLM Provider Integration

Agenta 的自托管（self-hosting）面向希望在自有基础设施上运行平台的团队，配套提供基于 Alembic 的数据库迁移以及统一的 LLM Provider 接入层。社区中两类高频问题直接对应本页主题：部署后找不到初始登录凭据——多数由 Alembic 迁移容器启动失败引起（issue 2675）；以及希望接入 Azure OpenAI 等自定义 LLM 提供方...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

Agenta 的自托管（self-hosting）面向希望在自有基础设施上运行平台的团队，配套提供基于 Alembic 的数据库迁移以及统一的 LLM Provider 接入层。社区中两类高频问题直接对应本页主题：部署后找不到初始登录凭据——多数由 Alembic 迁移容器启动失败引起（issue #2675）；以及希望接入 Azure OpenAI 等自定义 LLM 提供方（issue #2153）。本页围绕三条主线展开：自托管快速开始与配置、Alembic 迁移机制、以及通过 Vault/Secret 实体接入 LLM Provider。

Self-hosting 快速开始与配置

OSS 版本通过 docker-compose.gh.yml 一键启动。该文件位于 hosting/docker-compose/oss/docker-compose.gh.yml，配套环境变量模板为 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 up -d

启动后，平台在第一次运行时会通过 Alembic 容器自动初始化数据库模式（schema），随后才能生成默认超级管理员账户。资料来源：docs/docs/self-host/01-quick-start.mdx:1-80 与 docs/docs/self-host/02-configuration.mdx:1-120。

关键配置项说明如下：

配置项	说明
`POSTGRES_*`	PostgreSQL 连接信息（主机、端口、库名、用户、密码）
`REDIS_*`	Redis 缓存与队列连接信息
`AGENTA_AUTH_KEY` 等 `AGENTA_*`	平台运行时鉴权与功能开关
`--profile with-web`	是否同时拉起前端 Web 容器

升级到新版本时，应参照 docs/docs/self-host/03-upgrading.mdx 中的步骤重新拉取镜像并执行迁移容器。

基于 Alembic 的数据库迁移

迁移容器启动失败是社区中的高频故障。issue #2675 报告 agenta-oss-gh-alembic-1 容器无法启动，进而无法生成初始登录凭据。Agenta 的迁移实现由三个核心模块组成：

api/oss/databases/postgres/migrations/runner.py：迁移入口与编排逻辑。资料来源：api/oss/databases/postgres/migrations/runner.py:1-60。
api/oss/databases/postgres/migrations/core/env.py：商业版（EE）数据库的环境配置。资料来源：api/oss/databases/postgres/migrations/core/env.py:1-40。
api/oss/databases/postgres/migrations/core_oss/env.py：OSS 版本的环境配置，与 EE 在表结构上分叉。资料来源：api/oss/databases/postgres/migrations/core_oss/env.py:1-40。

迁移流程示意：

flowchart LR
  A[alembic 容器启动] --> B[读取 env.py 配置]
  B --> C{数据库可达?}
  C -- 否 --> Z[容器退出: 登录失败]
  C -- 是 --> D[读取 alembic_version]
  D --> E{需要升级?}
  E -- 是 --> F[upgrade head]
  E -- 否 --> G[跳过迁移]
  F --> H[写入新 schema_version]
  H --> I[API 容器就绪]
  I --> J[生成初始管理员凭据]

常见的迁移失败原因包括：PostgreSQL 不可达、目标 schema 已存在但 alembic_version 表冲突、以及 .env.oss.gh 中密码含未转义字符。排查时建议先执行 docker logs agenta-oss-gh-alembic-1，再根据报错确认是否需要手工运行 alembic upgrade head 对齐版本。

LLM Provider 集成与 Vault 实体

LLM Provider 接入由 web/packages/agenta-entities/src/secret 模块统一管理。该模块是基于 Jotai 的"查询+变更"轻量实现，被设计为新实体迁移到 molecule 模式的最小可用参考模板。资料来源：web/packages/agenta-entities/src/secret/README.md:1-60。

核心项目括：

多 Provider 支持：通过 core/transforms.ts 中的 transformSecret 与 transformCustomProviderPayloadData 函数，将前端表单数据序列化为后端可识别的 Secret 实体。资料来源：web/packages/agenta-entities/src/secret/core/transforms.ts:1-80。
环境变量映射：getEnvNameMap 将不同提供方（OpenAI、Azure OpenAI、自定义 Endpoint）的字段映射到对应环境变量名（如 OPENAI_API_KEY、AZURE_OPENAI_API_KEY、OPENAI_API_BASE）。资料来源：web/packages/agenta-entities/src/secret/core/transforms.ts:40-90。
作用域隔离：Secret 按 Project 隔离，并受用户认证状态约束；该设计既满足多团队协作，也避免凭据泄漏到非授权成员。

社区中关于 Azure OpenAI 集成的诉求（issue #2153）正是通过该模块的 custom Provider 形态实现：用户在前端填入 api_base、deployment、api_version 等字段后，transformCustomProviderPayloadData 会将其封装为运行时环境变量注入到 LLM 调用栈。

常见失败模式

Alembic 容器无法启动：检查 POSTGRES_* 配置与 alembic_version 表的初始状态，参考 issue #2675 复现命令定位根因。
Azure OpenAI 调用失败：确认 api_base 形如 https://<resource>.openai.azure.com/，并选择 custom Provider 类型。
升级后 Pydantic 兼容性告警：项目历史中曾推动 Pydantic 升级（issue #637），升级时需同时检查 requirements.txt 与 Docker 基础镜像版本。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

medium 能力判断依赖假设

假设不成立时，用户拿不到承诺的能力。

medium 维护活跃度未知

新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。

medium 存在评分风险

风险会影响是否适合普通用户安装。

low issue/PR 响应质量未知

用户无法判断遇到问题后是否有人维护。

Pitfall Log / 踩坑日志

项目：Agenta-AI/agenta

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/Agenta-AI/agenta | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/Agenta-AI/agenta | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/Agenta-AI/agenta | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/Agenta-AI/agenta | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/Agenta-AI/agenta | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/Agenta-AI/agenta | release_recency=unknown

来源：Doramagic 发现、验证与编译记录

agenta 项目

Project Overview and System Architecture

项目概览与系统架构

项目定位与核心能力

系统架构总览

核心模块构成

实体（Entity）层

评估与可观测性

编辑器与富交互

部署与开发工作流

See Also

Evaluation System and Workflows

评估系统与工作流

概述

核心实体与控制器模式

实体控制器 API

可执行实体（Runnable）

测试集与测试用例

环境与部署

数据流与状态管理

Server → Atom 链路

模块化目录与状态归属

评估队列与执行协调

与 SDK、可观测性的集成

常见问题与失败模式

参见

Observability, Tracing, and Prompt Management

可观测性、追踪与提示词管理

概述与目标

追踪数据流与 SDK 接入

前端追踪实体模块

提示词与环境管理

See Also

Self-hosting, Database Migrations, and LLM Provider Integration

概述

Self-hosting 快速开始与配置

基于 Alembic 的数据库迁移

LLM Provider 集成与 Vault 实体

常见失败模式

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 能力坑 · 能力判断依赖假设

2. 维护坑 · 维护活跃度未知

4. 安全/权限坑 · 存在评分风险

5. 维护坑 · issue/PR 响应质量未知

6. 维护坑 · 发布节奏不明确