[release] v0.99.7#4316
Merged
Merged
Conversation
Introduce a shared concept page documenting the artifact / variant / revision pattern used by applications, workflows, evaluators, and testsets. Covers commit semantics, retrieval references, revision log, and archive/unarchive. Factors out a pattern that would otherwise have to be repeated in every per-resource reference page. The applications, workflows, evaluators, and testsets concept pages (landing in parallel PRs) link to this page instead of redefining the model.
Adds the Evaluators concept page under the REST API guide and annotates every evaluators endpoint and request/response model with docstrings plus Field(description=...). - New: docs/docs/reference/api-guide/07-evaluators.mdx - Adds handler docstrings to EvaluatorsRouter and SimpleEvaluatorsRouter (catalog, artifact, variant, revision, deploy, resolve, simple CRUD, templates) - Adds Field descriptions to every request/response schema in api/oss/src/apis/fastapi/evaluators/models.py No behavior changes; no openapi_extra; no marketing words. Cross-links to Versioning and Query Pattern guides.
- Add `docs/docs/reference/api-guide/05-applications.mdx` covering what an application is, versioning, invocation, deployment, simple vs structured endpoints, catalog, lifecycle, and an end-to-end worked example. - Add docstrings to all 35 Applications FastAPI handlers (29 structured + 6 simple), explaining what each endpoint does and when to pick it over a similar one. - Add `Field(description=...)` to every field on the applications request and response models, including the catalog and simple-application models. - Every endpoint was exercised against `eu.cloud.agenta.ai` before its docstring was written. - Hooks skipped in sandbox; will be run locally before merge. No secrets in this PR (docs + docstrings only).
- Adds 08-testsets.mdx — concept page covering immutable testcases, the versioned-bag model, dedup paths (testcase_dedup_id / __dedup_id__ legacy), import/export, simple testsets, and pinning in evaluations. - Adds Field descriptions on testsets/testcases models and docstrings on every router handler.
- Adds 06-workflows.mdx — concept page covering workflows as the versioned-logic primitive, when to pick workflows vs applications vs evaluators, the artifact/variant/revision model, and the shared shape with applications and evaluators. - Adds Field descriptions on workflows models and docstrings on every router handler.
- Adds 10-tracing.mdx — concept page covering spans/traces, the invocation vs annotation trace types, span types, references vs links, the four ingestion paths with a decision tree, the async 202 contract, the ag.* namespace (both wire formats), the ag.unsupported fallback, and the query focus mode. - Adds Field descriptions across tracing/, traces/, otlp/ models and docstrings on every handler beyond the PR #4174 baseline.
…d-feat/workflow-app-pages
…d-feat/workflow-app-pages
…d-feat/workflow-app-pages
…ebar Replace the apps-only dropdown with a unified workflow entity card that displays both apps and evaluators. The new component shows the active workflow's name, type tag, and provides a grouped switcher for all workflows plus a close button to exit the entity context. On collapsed sidebars, only the type tag and compact switcher remain visible.
…and adjusting workspace ID resolution
…d-feat/workflow-app-pages
…nd email generation
…tor workflows - Hide "Deploy" and "Use API" buttons in variants dashboard when viewing evaluator workflows - Hide "Deploy" button in playground header for evaluator entities - Remove registry header tabs (deployments) when viewing evaluator workflows - Update evaluator drawer callback to use `onWorkflowCreated` with parent workflow id (`newAppId`) instead of deprecated `onEvaluatorCreated` with revision id - Fix navigation after
Calling ag.callbacks.litellm_handler() before ag.init() silently produced no-op spans with no indication of the problem. Add a RuntimeWarning so developers get an actionable message pointing them to call ag.init() first. The @ag.instrument() decorator already emits this warning at function call time. This change closes the gap for the litellm callback path. Adds unit tests covering both the warning (tracing=None) and the no-warning (tracing initialized) cases for both code paths. Closes #3171
- Note that revisions carry the payload, not just commit metadata. - Add environments as a deployment pointer alongside artifact/variant/revision. - Reference the existing /concepts/concepts overview page. - Replace temperature-only example with a realistic application revision payload (prompt, messages, llm_config). - Explain what a reference is (id, slug, slug+version) before describing retrieve precedence. - Spell out "most specific wins" as revision > variant > environment. - Rename "Revision log" to "Listing revision history" so the heading matches the verb pattern used by the other sections. - Clarify the fork verb ties to POST /variants/fork.
Aggregates the 8 sub-PRs that add concept pages and endpoint docstrings for the REST API reference. Sub-PRs base off this branch so forward links (versioning <-> applications, workflows, evaluators, testsets, tracing, folders, evaluations) resolve during docs build. When all sub-PRs are merged into this branch, this PR merges into main.
The ag_config wrapper was removed by migration 91d3b4a8c27f_fix_ag_config
(2025-04-24); revision payloads now live under data.parameters directly.
Verified against eu.cloud.agenta.ai: posting with the old ag_config
envelope returns HTTP 200 but stores data: {} because extra fields are
silently dropped. The corrected shape (data.parameters.prompt.*) stores
the payload correctly.
docs(docs): add versioning concept page
Address coderabbitai review: bare except swallowed real failures in the @Instrument before-init test. The warning fires before the subsequent AttributeError (ag.tracing is None), so retain the bare except only for the before-init path where the failure is expected, and add an explicit message to both assertions for clarity. The no-warning (after-init) path now fails loudly via pytest.fail if my_fn() raises unexpectedly.
…plications-endpoints Resolve conflict in api/oss/src/apis/fastapi/applications/models.py: response envelopes now extend the new Support base class (from oss.src.utils.exceptions) while keeping the documentation docstrings and Field(description=...) introduced on this branch. No conflicts elsewhere. Router and concept page pick up cleanly from main.
…lders-endpoints Bring in main + the landed versioning concept page so the folders PR can ship on top of the umbrella branch. Conflict resolution: - api/oss/src/apis/fastapi/folders/models.py: the umbrella switched the three response models (FolderResponse, FoldersResponse, FolderIdResponse) to inherit from `Support` so they carry support_id / support_ts. Combined with the Field(description=...) annotations from this branch.
Documentation: - 04-versioning.mdx: include environments in the shared versioning model per JP's note on the intro. - 05-applications.mdx: replace the JS-style placeholder comment in the final invoke example with valid JSON plus an inline note (CodeRabbit). - 10-tracing.mdx: rewrite the trace-types table so annotations are evaluator-produced as well as human-produced; add an :::info block showing the fields that identify each type (JP + mmabrouk on L93). - 10-tracing.mdx: mark `/tracing/spans/ingest`, `/tracing/traces/query`, `/tracing/spans/query`, and `/traces/ingest` as deprecated; point callers to `/otlp/v1/traces`, `/simple/traces/`, `/spans/query`, and `/traces/query`. Drop the deprecated nested-trace curl example and point to the SDK / OTel collector setup instead (JP on L108). API metadata (no behaviour change): - applications/models.py: reword the edit Field descriptions on ApplicationVariantEditRequest and ApplicationRevisionEditRequest. Edit is a full PUT; documenting it as "fields to update" is misleading (JP on models.py:197 and 287). - evaluators/models.py, workflows/models.py, testsets/models.py: drop the "Defaults to false" wording on the `include_archived` Field descriptions. The schema default is null, not false (CodeRabbit on evaluators/models.py:85 and the same pattern across the three domains). - tracing/router.py: apply `deprecated=True` to the remaining TracingRouter routes (`/spans/query`, `/analytics/query`, `/traces/*`, `/sessions/query`, `/users/query`). The pattern was already in place for `/spans/ingest`; this just propagates it. Out of scope here: - The count-semantics bug at tracing/router.py:296 (CodeRabbit) is a business-logic change. Filed as AGE-3758 and intentionally left untouched in this docs PR.
Drop the "deprecated" framing on `__dedup_id__`. Per @jp-agenta on #4314 (08-testsets.mdx:35), the `legacy_` prefix in the input normalisation code is unfortunate naming; the field is not deprecated. - `data.testcase_dedup_id` is the JSON-payload key (commits, SDK). - `__dedup_id__` is the metadata-column key, alongside `__id__`, `__flags__`, `__tags__`, and `__meta__`, used by CSV uploads and downloads. Both round-trip through the server's normalisation, so callers can commit through one path and download through the other and the dedup ID stays consistent. Also add `__dedup_id__` to the metadata-column list in the Import and export section so the family of `__X__` columns is documented in one place.
docs(api): API reference docs umbrella (AGE-3734)
dosubot
Bot
added
size:XXL
[chore] Bump py deps and resolve client/sdk dependencies
…eference-20260514
…pi-reference-20260514 [chore] Regenerate clients and api references
[Frontend feat] Enable "app" workflow navigation structure for evaluators
jp-agenta
approved these changes
May 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
New version v0.99.7 in