# https://github.com/Agenta-AI/agenta Project Manual

Generated at: 2026-06-21 13:07:59 UTC

## Table of Contents

- [Overview](#page-overview)
- [Api](#page-api)
- [Src](#page-api-oss-src)
- [Src](#page-api-ee-src)

<a id='page-overview'></a>

## Overview

### Related Pages

Related topics: [Api](#page-api)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [web/packages/agenta-ui/src/Editor/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-ui/src/Editor/README.md)
- [examples/python/RAG_QA_chatbot/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/RAG_QA_chatbot/README.md)
- [web/oss/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/oss/package.json)
- [web/packages/agenta-entities/src/environment/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md)
- [web/oss/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/oss/README.md)
- [web/packages/agenta-entities/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/package.json)
- [web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md)
- [web/packages/agenta-ui/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-ui/package.json)
- [web/_reference/agenta-sdk/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md)
- [web/packages/agenta-entity-ui/src/modals/shared/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entity-ui/src/modals/shared/README.md)
- [web/packages/agenta-entities/src/testcase/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/testcase/README.md)
</details>

# Overview

Agenta is an open-source platform for building, evaluating, deploying, and observing LLM-powered applications. The repository contains both a Python backend (FastAPI service with database migrations) and a TypeScript frontend (Next.js) split into a set of workspace packages, alongside reference SDKs and runnable example projects. The codebase supports prompt management, testset authoring, evaluation workflows, tracing/observability, and environment deployments under a unified entity model.

## Repository Layout

The repository is organized into several top-level concerns:

- `api/` – Python backend service (FastAPI, Pydantic v2, Alembic migrations for OSS and EE profiles).
- `web/` – Monorepo of TypeScript packages and apps:
  - `web/oss/` – the Next.js application shell, with module-per-feature folders, module-local stores, and a root-level shared store.
  - `web/packages/agenta-ui/` – generic UI primitives (Editor, table, tokens, diff view).
  - `web/packages/agenta-entities/` – domain entities (workflow, trace, environment, testset, testcase, queues, evaluation run).
  - `web/packages/agenta-entity-ui/` – entity-specific modals, pickers, and drill-in views.
  - `web/_reference/agenta-sdk/` – the public TypeScript SDK contract documented in `PARITY.md`.
- `examples/` – runnable Python examples (RAG chatbots, custom workflows) and a Jupyter notebook cookbook pipeline.
- `hosting/` – Docker Compose profiles for OSS/EE deployment.

The web workspace declares a Lexical-based editor stack, Ant Design, TanStack Query/Table/Virtual, Jotai family primitives, js-yaml, and Prismjs as core dependencies (Source: [web/oss/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/oss/package.json)). The entities package pins Zod 4, axios, immer, and supports React 18+ (Source: [web/packages/agenta-entities/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/package.json)).

## Frontend Architecture

### Module and Component Structure

The Next.js app follows a "module per page" convention. Each module is self-contained with its own components, hooks, assets, and constants. Code movement rules are explicit: module-specific code stays local, while cross-module utilities are promoted to root-level `/components`, `/hooks`, or `/assets` (Source: [web/oss/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/oss/README.md)). This separation is reinforced by the package split between `@agenta/ui` (generic primitives) and `@agenta/entity-ui` (entity-bound UI such as commit modals and drill-in pickers).

### Entity Controller Pattern

Domain entities (workflows, traces, environments, testsets, testcases, queues, evaluation runs) are implemented through a uniform controller pattern built on Jotai atoms and TanStack Query (Source: [web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md)). Every entity exposes:

- `entity.atoms.*` – reactive atom families for subscriptions.
- `entity.actions.*` – write atoms for `set()`-based compositions.
- `entity.get.*` / `entity.set.*` – imperative reads and writes for callbacks.
- `entity.useController` – a React hook bundling atoms and dispatch.
- `entity.cleanup.*` – memory management helpers.

Capability namespaces are layered on top: `runnable.*` for workflow/evaluator revision execution and `loadable.*` for testcase data sources. Data flows from the FastAPI backend through TanStack Query into Jotai atoms, then into components.

### Reusable Primitives

`@agenta/ui` ships a Lexical-based Editor supporting code mode (JSON/YAML with validation), rich-text markdown, form view, token highlighting (`{{variable}}`, f-string, Jinja2), and a side-by-side DiffView (Source: [web/packages/agenta-ui/src/Editor/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-ui/src/Editor/README.md)). Shared modal infrastructure lives in `@agenta/entity-ui` and provides an `EnhancedModal` wrapper with lazy rendering, auto-contained height, and consistent footer handling for commit/save/delete flows (Source: [web/packages/agenta-entity-ui/src/modals/shared/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entity-ui/src/modals/shared/README.md)).

## Backend & Domain Model

The Python backend exposes a versioned HTTP surface, with Alembic migrations split into core and tracing scopes for both OSS and EE database profiles. The frontend talks to the API through the public SDK documented in `web/_reference/agenta-sdk/README.md`, which lists resources such as `apps`, `appVariants`, `revisions`, `environments`, `testsets`, `evaluations`, `tracing`, `vault`, `apiKeys`, `profile`, and `projects/folders/organizations/workspaces` (Source: [web/_reference/agenta-sdk/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md)).

A notable abstraction is the **SimpleEnvironment API**, which collapses a 3-level git-based model (Environment → EnvironmentVariant → EnvironmentRevision) into a flat frontend-facing representation (Source: [web/packages/agenta-entities/src/environment/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md)). Revisions support both full snapshots and delta operations (`set`, `remove`), and guarded environments (`is_guarded: true`) require explicit approval before deployment.

Testcases, testsets, traces, queues, and evaluation runs follow the same molecule-style controller. The testcase module demonstrates the pattern end-to-end, with a `dataController` abstraction used by virtualized table components and a `paginatedStore` for infinite scrolling (Source: [web/packages/agenta-entities/src/testcase/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/testcase/README.md)).

## Examples, Tooling, and Community Topics

The `examples/python/` directory hosts runnable reference projects, including a full-stack RAG QA chatbot with Qdrant, dual embedding (OpenAI/Cohere), streaming responses, and Agenta observability tracing (Source: [examples/python/RAG_QA_chatbot/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/RAG_QA_chatbot/README.md)). A second example, `custom_workflows/rag-docs-qa`, shows a docs Q&A workflow using Qdrant, Cohere, and OpenAI with manual ingestion (Source: [examples/python/custom_workflows/rag-docs-qa/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/custom_workflows/rag-docs-qa/README.md)). Jupyter notebooks under `examples/jupyter/` are converted to Markdown via `nbconvert` for the docs site (Source: [examples/jupyter/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/jupyter/README.md)).

The latest release, v0.104.0, includes OSS/EE schema parity planning, shared membership tables, and account-table drift fixes – a recurring operational concern in community issue #2675, where new deployments failed to expose initial login credentials because the Alembic container exited early. Other notable community requests (table filtering for evaluation results in #4282, Azure OpenAI / LiteLLM integration in #2153) inform the direction of upcoming evaluation UI and provider-router work.

## See Also

- Editor Module
- Environment Entity
- Testcase Entity
- Agenta SDK Reference
- Entities Architecture
- Shared Modal Utilities

---

<a id='page-api'></a>

## Api

### Related Pages

Related topics: [Overview](#page-overview), [Src](#page-api-oss-src)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [web/_reference/agenta-sdk/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md)
- [web/packages/agenta-entities/src/environment/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md)
- [clients/README.md](https://github.com/Agenta-AI/agenta/blob/main/clients/README.md)
- [web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md)
- [web/oss/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/oss/README.md)
- [web/packages/agenta-entities/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/package.json)
</details>

# Api

## Overview

The Agenta API is the unified contract between the backend services and the front-end applications, the SDK, and the generated language clients. It is exposed both as HTTP endpoints (under the `/api` prefix in self-hosted deployments) and as typed wrappers through the `@agenta/sdk` package. The API is consumed by three primary surfaces: the `web/oss` Next.js application, the Python and TypeScript SDKs, and any external integrations that need to programmatically manage prompts, evaluations, traces, deployments, and observability data.

The API surface is intentionally resource-oriented, with consistent verbs (`query`, `get`, `create`, `archive`, `unarchive`, `commitRevision`) shared across revisioned entities such as apps, evaluators, testsets, testcases, environments, traces, and annotations. The latest published release, v0.104.0, continues the convergence between OSS and EE endpoints and adds shared membership tables to reduce account-table drift [Source: [web/_reference/agenta-sdk/README.md:1-40]()].

## Architecture and Data Flow

The API follows a layered architecture: a FastAPI/Python backend exposes OpenAPI-described HTTP endpoints; a generation script turns that OpenAPI document into per-language client packages; the SDK wraps the same endpoints with a more ergonomic, resource-grouped surface; and the front-end consumes both the raw endpoints and the SDK through the `@agenta/entities` molecule layer.

```mermaid
flowchart LR
    BE[FastAPI Backend] -->|OpenAPI| GEN[clients/scripts/generate.sh]
    GEN --> PY[clients/python/]
    GEN --> TS[clients/typescript/]
    BE -->|HTTP /api| SDK["@agenta/sdk"]
    SDK --> ENT["@agenta/entities"]
    ENT --> UI["web/oss (Next.js)"]
    UI --> USER[End user]
```

The generation entrypoint is `clients/scripts/generate.sh`, which fetches the OpenAPI document (defaulting to `http://localhost/api/openapi.json`) and produces Python and TypeScript packages. The script accepts `--language python`, `--language typescript`, or `--language all` [Source: [clients/README.md:1-25]()].

## SDK API Surface

The `@agenta/sdk` package exposes a flat, resource-grouped object (`ag.apps`, `ag.evaluations`, `ag.tracing`, `ag.vault`, `ag.apiKeys`, `ag.profile`, etc.). Each resource follows a consistent shape: `query(filters)` for searching, `get(id)` for single fetch, `archive`/`unarchive` for soft-delete lifecycle, and `commitRevision`/`logRevisions`/`retrieveRevision` for git-style version control on revisioned resources.

Notable resource namespaces include:

| Namespace | Example operations |
|-----------|--------------------|
| `apps` | `commitRevision`, `logRevisions`, `retrieveRevision`, `archiveRevision`, `createVariant`, `forkVariant`, `queryVariants`, `listTemplates`, `fetchInterfaceSchemas`, `fetchLatest`, `findBySlug` |
| `annotations` | `create`, `getByTrace`, `editByTrace`, `deleteByTrace`, `query`, `getForTraces`, `createHumanFeedback` |
| `tracing` | `querySpans`, `queryTraces`, `queryByApplication`, `getTrace`, `getSpan`, `deleteTrace`, `querySessions`, `queryUsers`, `queryAnalytics`, `spanAnalytics` |
| `vault` | `list`, `get`, `create`, `update`, `delete` |
| `apiKeys` | `list`, `create`, `delete` |
| `profile` | `get`, `getOrganizations` |

[Source: [web/_reference/agenta-sdk/README.md:1-50]()] The `PARITY.md` document in the SDK package tracks deferred endpoints (admin/billing/subscription, `/preview/invocations/*`) that are not yet covered by the typed SDK and must be reached via `ag.client.post(...)` raw calls.

## Entity-Level API Pattern

Within the front-end, every business entity (workflow, evaluator, environment, testset, testcase, trace) is encapsulated as a molecule that exposes a controller pattern with atom families, write atoms, imperative reads/writes, and a `useController` React hook. The molecule layer mediates between TanStack Query and Jotai state, while the underlying HTTP layer is implemented in `api/*.ts` files.

The Environment entity demonstrates the canonical revisioned-resource API. Internally the backend uses a three-level git-based model (`Environment → EnvironmentVariant → EnvironmentRevision`), but the front-end consumes the `SimpleEnvironment` API which flattens this hierarchy and exposes `variant_id` / `revision_id` fields as opaque identifiers [Source: [web/packages/agenta-entities/src/environment/README.md:1-40]()].

The Environment endpoints illustrate the pattern:

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/simple/environments/query` | List/query environments |
| `POST` | `/simple/environments/` | Create environment |
| `PUT` | `/simple/environments/{id}` | Edit environment |
| `POST` | `/simple/environments/{id}/archive` | Archive |
| `POST` | `/simple/environments/{id}/unarchive` | Unarchive |
| `POST` | `/simple/environments/{id}/guard` | Guard (requires explicit approval) |
| `POST` | `/simple/environments/{id}/unguard` | Unguard |
| `POST` | `/environments/revisions/query` | Query revisions |
| `POST` | `/environments/revisions/commit` | Commit revision |

Revisions accept either a full data snapshot (`data`) or delta operations (`delta.set` / `delta.remove`) for incremental updates. Guarded environments (`is_guarded: true`) require explicit approval before deployment, enforced by the `guardEnvironment` / `unguardEnvironment` mutations.

## Front-End Consumption

The `web/oss` application imports API bindings through the `@agenta/entities` package, which depends on `axios`, `zod` (^4.0.0), and `jotai-tanstack-query` for bridging server state into reactive atoms [Source: [web/packages/agenta-entities/package.json:1-50]()]. The molecule layer enforces a controller pattern (`entity.atoms.*`, `entity.actions.*`, `entity.get.*`, `entity.set.*`, `entity.useController`, `entity.cleanup.*`) so that components do not couple directly to HTTP or query details.

Module placement in `web/oss` follows a strict rule set: module-specific code stays within the module, components/hooks/utilities used across multiple modules are elevated to the appropriate root-level folder, and types shared across modules live in a root `types.d.ts`. State follows the same scoping rules — local for component-only, module store for intra-module sharing, root store for cross-module use — and the project strongly prefers Jotai atoms for reactive state [Source: [web/oss/README.md:1-50]()].

## Deployment Notes and Known Issues

Self-hosted deployments use `docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml` with the `--profile with-web` flag. Community issue #2675 reports that the `agenta-oss-gh-alembic-1` container can fail to start, blocking the discovery of initial login credentials. The recommended remedy is to inspect the alembic migration logs and ensure the database connection string in `hosting/docker-compose/oss/.env.oss.gh` matches a reachable Postgres instance before re-running the compose stack [Source: [community context #2675]()].

For SDK parity gaps and version-specific limitations, the SDK package ships a `PARITY.md` file that should be consulted before depending on newly introduced endpoints.

## See Also

- [Editor Module](./Editor.md)
- [Environment Entity](./Environment.md)
- [Infinite Virtual Table](./InfiniteVirtualTable.md)
- [Shared Modal Utilities](./SharedModalUtilities.md)

---

<a id='page-api-oss-src'></a>

## Src

### Related Pages

Related topics: [Api](#page-api), [Src](#page-api-ee-src)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [web/oss/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/oss/README.md)
- [web/oss/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/oss/package.json)
- [web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md)
- [web/packages/agenta-entities/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/package.json)
- [web/packages/agenta-ui/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-ui/package.json)
- [web/packages/agenta-ui/src/Editor/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-ui/src/Editor/README.md)
- [web/packages/agenta-entity-ui/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entity-ui/package.json)
- [web/packages/agenta-entities/src/environment/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md)
- [web/packages/agenta-entities/src/testcase/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/testcase/README.md)
- [web/packages/agenta-entity-ui/src/modals/shared/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entity-ui/src/modals/shared/README.md)
- [web/_reference/agenta-sdk/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md)
- [examples/python/RAG_QA_chatbot/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/RAG_QA_chatbot/README.md)
- [examples/python/custom_workflows/rag-docs-qa/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/custom_workflows/rag-docs-qa/README.md)
- [examples/jupyter/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/jupyter/README.md)
</details>

# Src

## Overview

The `Src` (source) of the Agenta repository contains the complete implementation of an open-source LLM engineering platform. The codebase is organized as a monorepo spanning three primary areas: a Python backend API for serving the platform, a TypeScript/React frontend for the web application, and shared packages that power both the OSS and EE distributions. As of the latest release `v0.104.0`, the team has been actively converging the OSS and EE schema parity, sharing membership tables, and fixing account-table drift (see community context for the release notes).

The repository follows a clear module-per-feature pattern, with each module being self-contained and exposing a consistent controller interface to consumers. State is primarily managed through Jotai atoms and TanStack Query on the frontend, while the backend exposes FastAPI routers under `api/oss/src/apis/fastapi/`.

Source: [web/oss/README.md:1-50]()
Source: [web/packages/agenta-entities/README.md:1-40]()

## Repository Layout

The monorepo is structured to keep the web app, shared packages, backend, and examples clearly separated:

```text
agenta/
├── api/oss/src/                  # Python backend (FastAPI, OSS)
│   ├── apis/fastapi/             # Routers (access, accounts, ...)
│   └── core/                     # Schemas, services, models
├── web/
│   ├── oss/                      # Main OSS web application
│   │   ├── src/                  # Feature modules
│   │   ├── package.json
│   │   └── README.md
│   ├── ee/                       # Enterprise Edition web app
│   └── packages/                 # Shared frontend libraries
│       ├── agenta-ui/            # Generic UI primitives (Editor, ...)
│       ├── agenta-entities/      # Domain molecules (workflow, trace, testset, ...)
│       ├── agenta-entity-ui/     # Entity-specific modals, pickers, drill-ins
│       └── ...
├── examples/                     # Sample applications and cookbooks
│   ├── python/                   # RAG chatbots, custom workflows
│   └── jupyter/                  # Notebook-to-docs converter
└── hosting/                      # Docker compose for self-hosting
```

Source: [web/oss/README.md:1-30]()
Source: [web/_reference/agenta-sdk/README.md:1-30]()

## Frontend Source (`web/oss` and `web/packages`)

### Web Application (`web/oss`)

The OSS web app is built on Next.js 15 (React 19) with the following key dependencies exposed in `package.json`:

| Dependency | Version | Purpose |
|------------|---------|---------|
| `next` | 15.5.18 | App framework with bundle analyzer |
| `react` / `react-dom` | ^19.x | UI runtime |
| `antd` | ^5.x | Component library |
| `@tanstack/react-query` | ^5.90.21 | Server-state cache |
| `jotai` | ^2.x | Atomic client state |
| `lexical` / `@lexical/*` | ^0.40.0 | Editor framework |
| `prismjs`, `shiki` | — | Syntax highlighting |
| `js-yaml`, `json5`, `jsonrepair` | — | Data parsing |
| `@scalar/openapi-parser` | ^0.24.x | OpenAPI tooling |

Source: [web/oss/package.json:1-80]()

The README describes a strict module architecture:

- **Modules** represent distinct feature areas, each self-contained with its own components, hooks, and assets.
- **Components** are organized by scope: `Component.tsx` for presentational logic, `assets/*.tsx` for subcomponents, `hooks/*.ts` for local hooks, and `types.d.ts` for local types.
- **Code Movement** rules dictate when to elevate code to the root (`/components`, `/hooks`, `/assets`) based on cross-module reuse.
- **State Management** uses Jotai atoms at module level, with a global store at the root for cross-module state. State location is chosen by scope, update frequency, and persistence requirements.

Source: [web/oss/README.md:1-50]()

### Shared Packages

The `web/packages/` directory hosts reusable libraries consumed by both `web/oss` and `web/ee`:

- **`@agenta/entities`** — Domain entity controllers built on the **molecule pattern**. Each entity (`workflow`, `trace`, `environment`, `testset`, `testcase`, `evaluationRun`, `annotation`, etc.) exposes `atoms`, `actions`, `get`, `set`, `useController`, and `cleanup` namespaces. Data flows `Server → TanStack Query → atoms → React components`.
- **`@agenta/ui`** — Generic UI primitives, including the Lexical-based `Editor` module supporting JSON/YAML code mode, rich text, form view, token highlighting (`{{variable}}`/`{fstring}`/`{jinja2}`), and diff visualization.
- **`@agenta/entity-ui`** — Entity-specific modals and views (e.g., `EnhancedModal` wrapper that lazy-renders content to avoid Ant Design's eager portal rendering, defaults to `maxHeight: 90vh`).
- **`agenta-sdk`** — TypeScript SDK mirroring the backend REST surface (resources for `apps`, `variants`, `revisions`, `annotations`, `tracing`, `vault`, `apiKeys`, `profile`, plus `projects`/`folders`/`organizations`/`workspaces` CRUD).

Source: [web/packages/agenta-entities/README.md:1-60]()
Source: [web/packages/agenta-entity-ui/src/modals/shared/README.md:1-30]()
Source: [web/_reference/agenta-sdk/README.md:1-40]()

### Entity Module Pattern

Every entity module follows the same internal structure:

```text
entity/
├── core/      # Zod schemas, TypeScript types, re-exports
├── api/       # HTTP fetch/mutation functions
└── state/     # Molecule + Jotai store
```

For example, `environment` adds `revision_id` and `variant_id` fields, exposes endpoints such as `POST /simple/environments/query`, `POST /simple/environments/`, `POST /simple/environments/{id}/archive`, `POST /simple/environments/{id}/guard`, and uses delta-based revision commits (`set`/`remove` operations). The `testcase` entity additionally provides a `dataController` and `paginatedStore` for use with `InfiniteVirtualTable`.

Source: [web/packages/agenta-entities/src/environment/README.md:1-50]()
Source: [web/packages/agenta-entities/src/testcase/README.md:1-30]()

## Editor Module

The `Editor` lives in `@agenta/ui/Editor` and is the canonical input surface for prompts, testset cells, and configuration JSON. Its architecture:

```text
Editor
├── LexicalComposer (Lexical core)
├── plugins/
│   ├── code/         # JSON/YAML highlighter + validator
│   ├── token/        # {{variable}} / {fstring} / {jinja2}
│   ├── markdown/     # Toolbar + formatting
│   ├── singleline/   # Restriction plugin
│   └── debug/        # Dev panel
├── state/            # Jotai provider
└── utils/            # Shared helpers
```

Notable props include `codeOnly`, `singleLine`, `showToolbar`, `enableTokens`, `templateFormat`, `validationSchema` (JSON Schema), `onPropertyClick` (for `DrillInView` navigation), `additionalCodePlugins`, and `disableLongText`. The editor integrates with the `DrillInView` to navigate nested JSON via Cmd+click on property paths.

Source: [web/packages/agenta-ui/src/Editor/README.md:1-50]()

## Examples and Tooling

The `examples/` directory showcases end-to-end usage:

- **`examples/python/RAG_QA_chatbot/`** — Full-stack RAG chatbot with Qdrant vector store, dual OpenAI/Cohere embedding support, streaming chat, source citations, and full Agenta tracing.
- **`examples/python/custom_workflows/rag-docs-qa/`** — RAG Q&A system reading MDX documentation, with `ingest.py` and `query.py` entry points, configured via `.env` (`DOCS_PATH`, `DOCS_BASE_URL`, `OPENAI_API_KEY`, `COHERE_API_KEY`, `QDRANT_URL`, `QDRANT_API_KEY`, `AGENTA_API_KEY`).
- **`examples/jupyter/`** — Tooling to convert `.ipynb` cookbook notebooks into Markdown docs via `nbconvert` and a `make` target, supporting single-file and bulk conversion with a `force=true` override.

Source: [examples/python/RAG_QA_chatbot/README.md:1-40]()
Source: [examples/python/custom_workflows/rag-docs-qa/README.md:1-30]()
Source: [examples/jupyter/README.md:1-20]()

## Community-Relevant Notes

Several open community issues map directly to `Src` areas:

- **Issue #4282** requests table filtering in evaluation results — relevant to the `testcase`/`evaluationRun` entity controllers and `InfiniteVirtualTable` in `@agenta/entity-ui`.
- **Issue #1712** requests removal of unused dependencies from `agenta-web`; the modular `web/oss` layout (with feature-level `package.json`s) supports incremental dependency cleanup.
- **Issue #637** requested upgrading Pydantic — relevant to `api/oss/src/` Python dependencies.
- **Issue #2153** requests full Azure OpenAI integration — relevant to the SDK (`web/_reference/agenta-sdk`) and backend router layer.
- **Issue #2675** reports that `agenta-oss-gh-alembic-1` fails to start after `docker compose ... --profile with-web up`, which prevents the initial superuser/login flow from completing — this lives in `hosting/docker-compose/oss/` and the backend migration scripts under `api/oss/src/`.

Source: community context (`#4282`, `#1712`, `#637`, `#2153`, `#2675`).

## See Also

- [Editor Module](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-ui/src/Editor/README.md)
- [Entities Package](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md)
- [Environment Entity](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md)
- [Testcase Entity](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/testcase/README.md)
- [Agenta SDK](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md)
- [RAG QA Chatbot Example](https://github.com/Agenta-AI/agenta/blob/main/examples/python/RAG_QA_chatbot/README.md)

---

<a id='page-api-ee-src'></a>

## Src

### Related Pages

Related topics: [Src](#page-api-oss-src)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [web/oss/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/oss/README.md)
- [web/oss/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/oss/package.json)
- [web/packages/agenta-ui/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-ui/package.json)
- [web/packages/agenta-entities/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/package.json)
- [web/packages/agenta-entity-ui/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entity-ui/package.json)
- [web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md)
- [web/packages/agenta-ui/src/Editor/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-ui/src/Editor/README.md)
- [web/packages/agenta-entities/src/environment/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md)
- [web/packages/agenta-entities/src/testcase/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/testcase/README.md)
- [web/packages/agenta-entity-ui/src/modals/shared/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entity-ui/src/modals/shared/README.md)
- [web/_reference/agenta-sdk/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md)
- [examples/python/RAG_QA_chatbot/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/RAG_QA_chatbot/README.md)
- [examples/python/custom_workflows/rag-docs-qa/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/custom_workflows/rag-docs-qa/README.md)
- [examples/jupyter/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/jupyter/README.md)
</details>

# Src

The `src/` (source) tree of Agenta's web monorepo hosts the entire frontend application plus reusable shared packages consumed across modules. The structure separates self-contained feature **modules** from cross-cutting **shared packages** (`@agenta/ui`, `@agenta/entities`, `@agenta/entity-ui`) so that components, hooks, and atoms can be promoted upward only when used in multiple modules ([web/oss/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/oss/README.md)).

## Repository Layout

The web workspace is organized under `web/`, with two main areas:

- **`web/oss/`** — the main OSS frontend application. Modules live as self-contained folders with their own components, hooks, and assets. Cross-module code is lifted to `/components`, `/hooks`, or `/assets` only when reused ([web/oss/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/oss/README.md)).
- **`web/packages/`** — shared npm packages (`@agenta/ui`, `@agenta/entities`, `@agenta/entity-ui`) consumed by the OSS app, EE features, and external examples ([web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md)).

State management is Jotai-based; each module may declare its own `store/` folder with atoms and providers, while truly global state sits at the root ([web/oss/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/oss/README.md)).

## Shared Packages

### `@agenta/ui` — Presentation Primitives

`@agenta/ui` ships reusable, framework-agnostic UI building blocks: the Lexical-based `Editor`, virtual tables, modals, pickers, and styling helpers. It depends on Lexical `^0.40.0`, Jotai, TanStack Query/Virtual, Prism.js for syntax highlighting, and `js-yaml` for YAML support ([web/packages/agenta-ui/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-ui/package.json)).

The **Editor module** is a flagship component supporting multiple modes ([web/packages/agenta-ui/src/Editor/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-ui/src/Editor/README.md)):

- **Code Mode** — JSON/YAML with validation and error indicators
- **Rich Text Mode** — Markdown editing with toolbar
- **Form View** — Structured editing for JSON objects
- **Token Mode** — Variable highlighting (`{{variable}}`, fstring, Jinja2)
- **Diff View** — Side-by-side comparison

Editors support controlled values for undo/redo, JSON Schema validation, and drill-in navigation for nested JSON properties.

### `@agenta/entities` — Domain State & Molecule Pattern

`@agenta/entities` centralizes domain models (workflow, trace, environment, testset, testcase, evaluation queues, annotations) using a uniform **molecule controller pattern** ([web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md)). Each entity exposes:

```typescript
entity.atoms.*         // Atom families for reactive subscriptions
entity.actions.*       // Write atoms for use with set()
entity.get.* / set.*   // Imperative reads/writes for callbacks
entity.useController   // React hook combining atoms + dispatch
entity.cleanup.*       // Memory management
```

Source: [web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md)

The `testcase` module follows this pattern with `core/` (Zod schemas), `api/` (HTTP functions), and `state/` (molecule + data controller for virtual tables) ([web/packages/agenta-entities/src/testcase/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/testcase/README.md)). The `environment` module wraps the git-based SimpleEnvironment API and exposes guard/unguard mutations and revision-commit endpoints ([web/packages/agenta-entities/src/environment/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md)).

### `@agenta/entity-ui` — Entity-Specific UI

UI components that are tightly coupled to entities (modals, pickers, drill-in views) live in `@agenta/entity-ui` ([web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md)). The package reuses Antd `>=5.0.0` and ships shared modal infrastructure via `EnhancedModal` ([web/packages/agenta-entity-ui/src/modals/shared/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entity-ui/src/modals/shared/README.md)):

| Feature | Behavior |
|---|---|
| Lazy rendering | Mounts content only after first open |
| Auto-contained height | Default `maxHeight: 90vh` |
| Smart style merging | Object or function `styles` prop |
| Cleanup on hide | Resets render state after `afterClose` |

Source: [web/packages/agenta-entity-ui/src/modals/shared/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entity-ui/src/modals/shared/README.md)

## SDK Reference

The SDK lives under `web/_reference/agenta-sdk/` and is the canonical JS/TS interface mirroring the backend REST API. It exposes namespaced clients for `apps`, `variants`, `revisions`, `annotations`, `tracing`, `vault`, `apiKeys`, `profile`, plus CRUD for `projects`/`folders`/`organizations`/`workspaces`. Most resources follow the shape `query(filters)`, `get(id)`, `archive`/`unarchive`, and git-style `commitRevision`/`logRevisions`/`retrieveRevision` ([web/_reference/agenta-sdk/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md)).

## Examples & Documentation Pipeline

Beyond the main web app, the repository contains runnable examples under `examples/`:

- **`examples/python/RAG_QA_chatbot/`** — FastAPI + Next.js chatbot with Qdrant vector search and Agenta tracing ([examples/python/RAG_QA_chatbot/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/RAG_QA_chatbot/README.md)).
- **`examples/python/custom_workflows/rag-docs-qa/`** — Docusaurus-based RAG with Qdrant, Cohere, and OpenAI ([examples/python/custom_workflows/rag-docs-qa/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/custom_workflows/rag-docs-qa/README.md)).
- **`examples/jupyter/`** — `nbconvert`-based pipeline that turns `.ipynb` cookbooks into Docusaurus markdown ([examples/jupyter/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/jupyter/README.md)).

## Community-Relevant Notes

The source-tree architecture directly affects issues raised by the community:

- **Evaluation filtering** (#4282) — the evaluation results table uses `@agenta/entities/evaluationQueue` and `InfiniteVirtualTable`, meaning new filter UIs must extend the `testcase` data controller and the entity's molecule atoms ([web/packages/agenta-entities/src/testcase/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/testcase/README.md)).
- **Provider integration (e.g., Azure OpenAI, #2153)** — the SDK at `web/_reference/agenta-sdk/` already uses generic `ag.client.post(...)` escape hatches for non-CRUD endpoints, so new providers typically need a thin SDK wrapper plus backend support ([web/_reference/agenta-sdk/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md)).
- **Deployment & dependency hygiene** (#2675, #1712) — the OSS frontend depends on `web/oss/package.json` with Lexical `^0.40.0`, Antd, Redux Toolkit, and Tremor, while shared packages keep stricter peer-dep ranges (`"lexical": ">=0.38.0"`) to avoid version lock-in ([web/oss/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/oss/package.json), [web/packages/agenta-entity-ui/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entity-ui/package.json)).

## See Also

- [Editor Module](./Editor.md)
- [Environment Entity](./Environment-Entity.md)
- [Testcase Entity](./Testcase-Entity.md)
- [Entity Architecture Pattern](./Entities-Architecture.md)
- [Agenta SDK Reference](./Agenta-SDK.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: Agenta-AI/agenta

Summary: Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

## 1. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/Agenta-AI/agenta

## 2. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Agenta-AI/agenta

## 3. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/Agenta-AI/agenta

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/Agenta-AI/agenta

## 5. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Agenta-AI/agenta

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Agenta-AI/agenta

<!-- canonical_name: Agenta-AI/agenta; human_manual_source: deepwiki_human_wiki -->