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

[micheleRP]

Summary

Syncs one user-facing ADP (AI Agents / A2A) change from cloudv2 into the docs.

The A2A discovery agent card is now served without authentication. Per the A2A spec, the discovery card (/.well-known/agent-card.json) must be publicly reachable, because a caller fetches it precisely to learn how to authenticate. Previously the card was routed through the authenticated catch-all, so every fetch returned a 401 and discovery was impossible without already holding a token. The fix mounts the card path on a tenancy-only handler ahead of the authenticated catch-all; every other /a2a/v1/* path still requires a valid token.

The existing a2a-concepts.adoc page stated only that "A2A-compliant agents require authentication" and did not note that the discovery card is the exception. This contradicted the new (and spec-correct) behavior, so the change is documented as a clarification.

Changes

• modules/connect/pages/a2a-concepts.adoc:
  • Agent card location: added a paragraph noting the agent card is served without authentication and that agent invocation still requires a token.
  • Authentication: added an explicit [#authentication] anchor and a paragraph describing the discovery-card exception (card is served unauthenticated at /.well-known/agent-card.json; every other request, including invocation, requires a valid access token).

Preview

Netlify deploy preview (404s until the preview build finishes):
https://deploy-preview-56--redpanda-agentic-data-plane.netlify.app/agentic-data-plane/connect/a2a-concepts/

Source commits

• redpanda-data/cloudv2@782f557375 — aigw: serve A2A agent card without authentication (Refs AI-1313), author @birdayz. https://github.com/redpanda-data/cloudv2/commit/782f5573753b99605dd19a43b57ed3c85d617cdf

Reviewers

I've added @birdayz (author of the source cloudv2 commit) as an optional reviewer for a source-accuracy check. This review is a courtesy and is not required to merge.

Changes considered but not documented

Other ADP-related commits in the window were reviewed and intentionally excluded as not user-facing documentation changes:

• 3542314636 — feat(aigw): add provider filter to ListGuardrails: adds an internal provider filter to the ListGuardrails API to back an unshipped UI list control. No user-facing guardrails API reference exists to update, and the UI is still being built. TODO (human review): revisit if/when the guardrails "filter by provider" control ships and warrants a UI doc note.
• 54e089f1e2 — proto(adp): constrain agent_uid to UUIDv4: an internal buf.validate constraint on the SpendingEvent/SpendingFilter agent_uid field (spending/budgets API internals). Not surfaced to users.
• A large set of adp-ui commits (guardrails create/edit/list pages, secret store UX, brand icons, transcripts list pagination, visual-regression baselines): front-end/UI work with no documented behavior, config, API, or CLI change.

[netlify]

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

Name	Link
🔨 Latest commit	b7bdf70
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-agentic-data-plane/deploys/6a216c386d8abc0008273885
😎 Deploy Preview	https://deploy-preview-56--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. The documented behavior matches the cloudv2 source, the anchor/xref is correct, and the AsciiDoc builds cleanly.

Source accuracy (verified against cloudv2)

• Checked apps/aigw/internal/server/server.go in commit 782f5573753b99605dd19a43b57ed3c85d617cdf (the source commit cited in the PR). It mounts GET /a2a/v1/{agent}/.well-known/agent-card.json on a tenancy-only handler (injectIDPPublicIdentity + tenancyMid, no JWT check) on topMux ahead of /, while every other path stays on the authenticated catch-all. This confirms both new claims:
  • "The agent card is served without authentication." ✓
  • "Every other request to the agent, including agent invocation, requires a valid access token." ✓
• The rationale ("a caller fetches it to learn how to authenticate") matches the commit message and the A2A spec.

Correctness

• The [#authentication] anchor was added on the == Authentication section, and the new cross-link xref:connect:a2a-concepts.adoc#authentication[Authentication] resolves to it. Fully module-qualified, consistent with the docs-team-standards antora-conventions guideline (skills/antora-conventions/SKILL.md, "always use fully qualified xrefs").

Minor (optional, no action needed)

• The source commit also serves the legacy /.well-known/agent.json path unauthenticated alongside agent-card.json. Since the docs only document agent-card.json as the agent card location (existing scope), omitting the legacy path here is consistent and fine.

No critical or blocking issues found.

---

Generated by Claude Code