Related Pages

Related topics: Api

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). The entities package pins Zod 4, axios, immer, and supports React 18+ (Source: 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). 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). 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). 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).

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).

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). 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).

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). 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). Jupyter notebooks under examples/jupyter/ are converted to Markdown via nbconvert for the docs site (Source: 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

Related Pages

Related topics: Overview, Src

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.

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:

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:

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
• Environment Entity
• Infinite Virtual Table
• Shared Modal Utilities

Related Pages

Related topics: Api, Src

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:

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:

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:

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:

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.jsons) 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
• Entities Package
• Environment Entity
• Testcase Entity
• Agenta SDK
• RAG QA Chatbot Example

Doramagic Pitfall Log

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
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Agenta-AI/agenta

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Agenta-AI/agenta

3. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/Agenta-AI/agenta

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/Agenta-AI/agenta

5. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Agenta-AI/agenta

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Agenta-AI/agenta

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using agenta with real data or production workflows.

• v0.104.0 - github / github_release
• v0.103.5 - github / github_release
• v0.103.4 - github / github_release
• v0.103.3 - github / github_release
• v0.103.2 - github / github_release
• v0.103.1 - github / github_release
• v0.103.0 - github / github_release
• v0.102.0 - github / github_release
• v0.101.1 - github / github_release
• v0.101.0 - github / github_release
• Capability evidence risk requires verification - GitHub / issue