docs(ai-agents): rewrite Transcripts pages for ADP GA#560
Open
docs(ai-agents): rewrite Transcripts pages for ADP GA#560
Conversation
- transcripts.adoc: rewrite around the TranscriptService turn/tool-call model (was span hierarchy); add USD cost, reconstructed-turn handling, standalone-ADP prereqs wording with // TODO: markers. - concepts.adoc: add USD-cost attributes and a reconstructed-transcript- history section; drop cluster-centric topic-ACL wording (// TODO: for the standalone-ADP permission model). - transcripts-ui-guide.adoc: expand Summary panel fields (USD cost, turn count, tool calls, reconstructed marker, status). - nav.adoc: rename "View Transcripts" -> "Read a transcript" to match ADP Docs Plan Workflow #7. - ingest-custom-traces.adoc: light standalone-ADP wording pass + a page-top // TODO: flagging the full rewrite under Workflow #11 (BYOA telemetry). Plan: https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1867153415 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
📝 WalkthroughWalkthroughThis PR updates documentation for Redpanda's AI Agents observability feature, specifically the transcripts functionality. Changes include: updating the navigation label from "View Transcripts" to "Read a Transcript"; adding two new SDK semantic convention attributes for USD-based token costs; restructuring the transcripts page to emphasize reading conversation turns over span hierarchy inspection; documenting transcript history reconstruction when spans are evicted; and adding clarifications and TODOs regarding standalone ADP vs. Redpanda Cloud deployment contexts across setup and ingestion documentation. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@modules/ai-agents/pages/observability/concepts.adoc`:
- Around line 346-347: Clarify the terminology by explicitly stating in this
paragraph that the UI shows a badge labeled _reconstructed_ (UI/display text)
while the underlying record/field is named is_reconstructed (backing data
marker); update the sentence to distinguish the display badge from the boolean
field so readers know one is the visible label and the other is the data flag.
In `@modules/ai-agents/pages/observability/transcripts.adoc`:
- Around line 173-179: Update the wording to match the Concepts page by stating
that cost is derived from per-model pricing and the gen_ai.usage.* attributes or
the explicit USD-cost fields; specifically mention the explicit attributes
gen_ai.usage.input_tokens_cost_usd and gen_ai.usage.output_tokens_cost_usd as
valid sources of cost. Instruct readers checking zero-cost transcripts to verify
the model is in the pricing table and that either gen_ai.usage.input_tokens and
gen_ai.usage.output_tokens are present on ASSISTANT-turn spans or the USD cost
fields (gen_ai.usage.input_tokens_cost_usd, gen_ai.usage.output_tokens_cost_usd)
exist, and that the cost-reporting pipeline is enabled.
In `@modules/ai-agents/partials/transcripts-ui-guide.adoc`:
- Around line 80-95: This partial mixes turn-based metrics with span/hierarchy
guidance; update it to consistently use the transcript-turn model: remove or
rewrite any references to hierarchical trace/span views (e.g., the
"Reconstructed transcript history" sentence and any xref to span-hierarchy),
ensure all descriptions refer to turns and turn-level metadata (Status, Turn
count, Token Usage, USD cost, LLM Calls, Tool Calls, Service, Conversation ID)
and change the "reconstructed" marker explanation to say turns reconstructed
from evicted LLM message context rather than spans; keep the list items (Turn
count, Token Usage, etc.) and adjust any conditional blocks (ifeval context
text) to use turn-based terminology throughout.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8b85f75d-45f1-4a4c-89f3-e0c545e562ac
📒 Files selected for processing (5)
modules/ROOT/nav.adocmodules/ai-agents/pages/observability/concepts.adocmodules/ai-agents/pages/observability/ingest-custom-traces.adocmodules/ai-agents/pages/observability/transcripts.adocmodules/ai-agents/partials/transcripts-ui-guide.adoc
Comment on lines
+80
to
+95
| * Status: `RUNNING`, `COMPLETED`, or `ERROR` | ||
| * Turn count: Number of conversation turns (SYSTEM, USER, ASSISTANT, TOOL) | ||
| ifeval::["{context}" == "agent"] | ||
| * Token Usage: Input tokens, output tokens, and total (critical for cost tracking) | ||
| * Token Usage: Input tokens, output tokens, and total | ||
| * USD cost: Total cost for the execution, derived from per-model pricing | ||
| * LLM Calls: How many times the agent called the language model | ||
| * Tool Calls: How many tools the agent invoked | ||
| * Service: The agent identifier | ||
| * Conversation ID: Links to session data topics | ||
| * Conversation ID: The `gen_ai.conversation.id` shared by related invocations in the same user session | ||
| endif::[] | ||
| ifeval::["{context}" == "mcp"] | ||
| * Service: The MCP server identifier | ||
| endif::[] | ||
|
|
||
| If any turns were rebuilt from LLM message context after their original spans were evicted, the panel shows a _reconstructed_ marker on those turns. For the mechanics, see xref:ai-agents:observability/concepts.adoc#history-reconstruction[Reconstructed transcript history]. | ||
|
|
Contributor
There was a problem hiding this comment.
Resolve model mismatch in this partial (turn-based vs span-hierarchy guidance).
This updated summary is turn/tool-call based, but this same partial still instructs users to use a hierarchical trace/span view (earlier sections). The mixed mental models will confuse readers in included pages. Please align this partial end-to-end to the transcript-turn model in this PR.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@modules/ai-agents/partials/transcripts-ui-guide.adoc` around lines 80 - 95,
This partial mixes turn-based metrics with span/hierarchy guidance; update it to
consistently use the transcript-turn model: remove or rewrite any references to
hierarchical trace/span views (e.g., the "Reconstructed transcript history"
sentence and any xref to span-hierarchy), ensure all descriptions refer to turns
and turn-level metadata (Status, Turn count, Token Usage, USD cost, LLM Calls,
Tool Calls, Service, Conversation ID) and change the "reconstructed" marker
explanation to say turns reconstructed from evicted LLM message context rather
than spans; keep the list items (Turn count, Token Usage, etc.) and adjust any
conditional blocks (ifeval context text) to use turn-based terminology
throughout.
- concepts.adoc: clarify that `is_reconstructed` is the backing data field and "Reconstructed" is the UI badge (CodeRabbit: minor). - transcripts.adoc: align "USD cost shows 0" troubleshooting with the Concepts page attribute list; xref rather than duplicate attribute names so the two pages can't drift (CodeRabbit: major). Deferred: - transcripts-ui-guide.adoc mixed-model feedback needs live-UI verification before the full partial rewrite; the existing `// TODO:` already flags it for the Weeks 3-4 walkthrough. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
4 tasks
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
1 participant
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.
Tracks: DOC-2115 — Read and understand a transcript (ADP Docs Plan Workflow #7)
Summary
observability/transcripts.adocaround theTranscriptServiceturn / tool-call model (was span hierarchy) — adds USD cost, reconstructed-turn handling, and ADP-UI-generic prereqs.observability/concepts.adocwith USD-cost attributes and a reconstructed-transcript-history section; drops cluster-centric topic-ACL wording.transcripts-ui-guide.adocSummary panel (USD cost, turn count, tool calls, status, reconstructed marker) — propagates intomonitor-agents.adocandmonitor-mcp-servers.adocvia the include.View Transcripts→Read a transcriptto match ADP Docs Plan Workflow finalize cloud-docs #7.ingest-custom-traces.adocwith a page-top// TODO:flagging the full rewrite as pending under Workflow Cloud Terraform provider beta #11 (BYOA telemetry).Every area that depends on the (TBD) standalone-ADP surface carries a
// TODO:marker — sign-in URL, IAM model, USD-cost coverage, filter-chip labels, export. These will be resolved after a live walkthrough againstadp-production.Plan (Confluence): https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1867153415/Transcripts+docs+rewrite+ADP+GA+2026-06-15+plan
Parent workstream: https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1845461009 (Workflow #7)
Preview pages
Test plan
npm run build && npm run serve— locally verified; nav renders "Read a transcript", no new unresolved xrefs, no regressions inmonitor-agents.adoc/monitor-mcp-servers.adoc(both include the updated partial).adp-production(flagenableTranscriptsInConsoleon) — verify every filter chip, detail-panel field, and column matches the draft. Resolve the// TODO:markers in-branch.TranscriptService/TranscriptSummary/TranscriptTurncomments.docs-team-standards:revieweditorial pass.🤖 Generated with Claude Code