[feat] Extend loadables

[jp-agenta]

PR: Loadables Retrieval Alignment

Summary

This PR aligns loadables retrieval behavior across testsets/queries, removes stale design drift in docs, and makes the traces router a first-class traces API (no tracing-shaped response types in traces endpoints).

Change Inventory

API: Testsets

1. Fixed _populate_testcases(...) call-site argument binding bugs by switching to keyword arguments.
2. Added deterministic ID-level windowing support for testset revision retrieval (order, next, limit) when enumerating testcase_ids.
3. Kept revision retrieval semantics where include_testcases=true returns both testcases and testcase_ids.
4. Updated /preview/testsets/revisions/retrieve caching policy to cache only when include_testcases=false.

API: Queries

1. Extended query revision population to merge request pagination (next, limit) into stored windowing.
2. Kept revision retrieval semantics where trace expansion can return both traces and trace_ids.
3. Updated /preview/queries/revisions/retrieve caching policy to cache only when both include_trace_ids=false and include_traces=false.
4. Added permission coupling: query revision retrieve with trace expansion requires trace-view permission in addition to query-view permission.

API: Traces Router

1. Introduced traces-specific DTOs:
   • TraceResponse
   • TracesResponse
   • TracesQueryRequest
2. Removed formatting from TracesQueryRequest.
3. Forced /preview/traces/query to always return Agenta trace trees (never spans/opentelemetry formatting).
4. Removed external TracingQuery request contract from TracesRouter.query_traces; traces endpoint now consumes only TracesQueryRequest.
5. Added query permission coupling for ref-dereferenced traces query (query_ref, query_variant_ref, query_revision_ref).
6. Added native traces router fetch handler (GET /preview/traces/{trace_id}) returning TraceResponse.

Docs

1. Updated docs/designs/loadables/loadables.querying.strategies.md to include:
   • include-flag defaults
   • conditional caching behavior
   • permission coupling notes
   • windowing.next terminology
2. Updated docs/designs/loadables/loadables.initial.specs.md examples from cursor to next.
3. Removed redundant docs/designs/loadables/loadables.querying.gap-analysis.md after consolidating its useful content into the strategies document.

Behavior Summary

1. Revision endpoints remain the control surface for ID/item expansion.
2. Record endpoints (/preview/testcases, /preview/traces) remain record-returning endpoints without extra top-level ID arrays.
3. Traces router now has a clean traces-only contract and response types.

Validation

1. Formatting/lint:
   • cd api && ruff format && ruff check --fix
2. Targeted e2e:
   • pytest -q oss/tests/pytest/e2e/tracing/test_traces_basics.py oss/tests/pytest/e2e/loadables/test_loadable_strategies.py
   • Result: 27 passed
3. Broader e2e:
   • pytest -q oss/tests/pytest/e2e/testsets/test_testsets_basics.py oss/tests/pytest/e2e/testsets/test_testsets_queries.py oss/tests/pytest/e2e/testsets/test_testcases_basics.py oss/tests/pytest/e2e/tracing/test_spans_basics.py oss/tests/pytest/e2e/tracing/test_spans_queries.py
   • Result: 17 passed, 3 skipped (existing flaky skips)
4. Full e2e suite:
   • pytest -q oss/tests/pytest/e2e
   • Result: 175 passed, 3 skipped

---

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Mar 6, 2026 10:09am

[jp-agenta]

@ardaerzin the files that matters most:

• docs/designs/loadables/loadables.querying.strategies.md
• docs/designs/loadables/loadables.endpoints.specs.md

[github-actions]

Railway Preview Environment

Preview URL	https://gateway-production-9aa8.up.railway.app/w
Image tag	pr-3811-73022fa
Status	Failed
Railway logs	Open logs
Logs	View workflow run
Updated at 2026-03-06T10:23:14.125Z

[mmabrouk]

Thanks @jp-agenta lgtm

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 43 additional findings in Devin Review.

[CLAassistant]

All committers have signed the CLA.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 43 additional findings in Devin Review.

[devin-ai-integration]

🔴 ingest_spans silently drops list-typed spans from trace trees, causing data loss

When ingest_spans processes spans from the traces parameter (trace tree format), it skips list-typed span values at line 185: if not isinstance(span, list). In the OTelNestedSpans type (Dict[str, Union[SpansNode, List[SpansNode]]]), spans with duplicate names within a trace are stored as List[SpansNode]. These are valid spans that the downstream parse_spans_from_request (api/oss/src/core/tracing/utils/parsing.py:346-365) correctly handles (it extends raw_span_dtos for list-typed values). However, the pre-filtering at line 185 silently discards them before they reach that parser.

This affects all trace ingestion flows that use the traces parameter: TracesRouter.create_trace, TracesRouter.ingest_traces, and the legacy TracingRouter.create_trace / edit_trace. Any trace containing two or more spans with the same name will have those duplicate-named spans silently dropped.

Suggested change

	elif traces:
	for spans_tree in traces.values():
	if spans_tree.spans:
	for span in spans_tree.spans.values():
	if not isinstance(span, list):
	_spans[span.span_id] = OTelSpan(
	**span.model_dump(
	mode="json",
	exclude_none=True,
	exclude_unset=True,
	)
	)
	elif traces:
	for spans_tree in traces.values():
	if spans_tree.spans:
	for span in spans_tree.spans.values():
	if isinstance(span, list):
	for s in span:
	_spans[s.span_id] = OTelSpan(
	**s.model_dump(
	mode="json",
	exclude_none=True,
	exclude_unset=True,
	)
	)
	else:
	_spans[span.span_id] = OTelSpan(
	**span.model_dump(
	mode="json",
	exclude_none=True,
	exclude_unset=True,
	)
	)

---

Was this helpful? React with 👍 or 👎 to provide feedback.