docs: sync ADP changes from cloudv2 (2026-06-16)

[micheleRP]

Summary

Syncs two user-facing ADP behaviors from cloudv2 main (merged in the last 24h) into the docs.

1. Conversation-grouping header is required for transcripts

For self-managed agents and apps that route their LLM and MCP tool calls through AI Gateway, the X-Redpanda-Genai-Conversation request header is what groups a session's spans into one transcript. cloudv2 corrected its own framing of this header from "optional / purely additive" to required for the Transcripts tab to populate: without it, the gateway drops the spans (no gen_ai.conversation.id) and the tab stays empty. It still doesn't affect auth or whether requests succeed.

The gateway/connect-agent.adoc page (Connect Your App to AI Gateway) had no mention of this header at all, so this fills a real gap. Added a Group requests into transcripts section.

• Based on: redpanda-data/cloudv2@50f7e408e (adp self-managed agent: conversation header is required for transcripts)
• Grounded in source: apps/aigw/internal/spanidentity/spanidentity.go (HeaderGenaiConversation = "X-Redpanda-Genai-Conversation", mapped to gen_ai.conversation.id).

2. Triggers are a managed-agent-only feature

cloudv2 gated the agent Triggers tab to managed agents only ("Triggers are a managed-agent concept"); self-managed (BYOA) agents have no Triggers tab. The connect/triggers/overview.adoc page didn't state this restriction. Added a NOTE clarifying that triggers apply to managed agents only and pointing self-managed agents at BYOA registration.

• Based on: redpanda-data/cloudv2@9b68045c3 (fix(adp-ui): hide Triggers tab for self-managed agents)

Changed pages

• modules/gateway/pages/connect-agent.adoc
• modules/connect/pages/triggers/overview.adoc

Preview

• Connect-agent (new section): https://deploy-preview-103--redpanda-agentic-data-plane.netlify.app/agentic-data-plane/gateway/connect-agent/

(The link 404s until Netlify finishes the preview build.)

Reviewers

Added @birdayz (Johannes Brüderl), the author of both source commits, as an optional reviewer for a source-accuracy check. This review is a courtesy and is not required to merge.

Notes

• Verified locally with npm run build: no xref/target errors on the changed pages or their link targets. (The build also emits pre-existing, unrelated GitHub rate-limit and auto-generated rpk-reference table warnings.)
• I considered but did not document: the httphost wildcard-allowlist tightening (96bce7e65, internal code-sandbox egress helper, not surfaced in docs), the LLMProvider.guardrail nullable refactor (5881d4202, no change in user-visible behavior — empty value still means "no guardrail"), and the in-progress Cedar/agent-permissions and per-framework SDK example work (LaunchDarkly-flag-gated and still churning).

[netlify]

✅ Deploy Preview for redpanda-agentic-data-plane ready!

Name	Link
🔨 Latest commit	d7070ef
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-agentic-data-plane/deploys/6a325a5385852300083174f1
😎 Deploy Preview	https://deploy-preview-103--redpanda-agentic-data-plane.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[micheleRP]

[adp-docs PR critic] Verdict: looks accurate against source. Both behavioral claims check out against cloudv2 main, the code example is consistent with the rest of the page, and both new xrefs resolve to existing files. No critical or correctness issues found.

Source accuracy (verified):

• X-Redpanda-Genai-Conversation is the real header name and maps to gen_ai.conversation.id — confirmed in apps/aigw/internal/spanidentity/spanidentity.go (HeaderGenaiConversation = "X-Redpanda-Genai-Conversation") and apps/aigw/internal/a2a/proxy.go.
• "Required for the Transcripts tab to populate; without it the gateway drops the spans and the tab stays empty; doesn't affect auth or whether requests succeed" — matches examples/self-managed-agent/README.md ("required for transcripts: without the header the gateway drops the spans and the agent's Transcripts tab stays empty. It does not affect auth...") and apps/adp-ui/src/components/agents/setup-tab.tsx ("Stamp the conversation id (required for transcripts)").
• "Triggers are available for Redpanda-managed agents only; self-managed agents have no Triggers tab" — confirmed by 9b68045c3 ("hide Triggers tab for self-managed agents"), which gates the Triggers tab behind type === 'managed' and adds 'triggers' to MANAGED_ONLY so a ?tab=triggers deep link on a self-managed agent normalizes back to overview. Commit message: "Triggers are a managed-agent concept."

Correctness (verified):

• xref:connect:byoa-register.adoc[] → modules/connect/pages/byoa-register.adoc exists. ✅
• xref:monitor:transcripts.adoc[] → modules/monitor/pages/transcripts.adoc exists. ✅
• Code example uses PROXY_URL / AUTH_TOKEN env vars and default_headers, consistent with the existing OpenAI/Anthropic/Google examples on the same page. ✅

Minor (heads-up, not a blocker):

• The new Triggers NOTE uses "self-managed (BYOA)" wording and links to byoa-register.adoc ("Register your own agent (BYOA)"). This is correct against current main, but a separate open PR (docs: replace BYOA pages with a self-managed agent guide #102) replaces that page with a "Set Up a Self-Managed Agent" guide and drops the BYOA wording. If docs: replace BYOA pages with a self-managed agent guide #102 merges first, this xref target is renamed (it adds a page-alias, so the link won't break, but the "(BYOA)" phrasing would be re-introducing terminology that PR is removing). Worth a rebase check on whichever lands second so the two PRs stay consistent on the self-managed vs. BYOA naming.

Reviewed against cloudv2 main. No source-accuracy or build/xref problems.

---

Generated by Claude Code