redpanda-data · micheleRP · May 8, 2026 · May 8, 2026
@@ -35,6 +35,7 @@
 *** xref:mcp:managed/slack.adoc[Slack]
 *** xref:mcp:managed/ironclad.adoc[Ironclad]
 *** xref:mcp:managed/jira.adoc[Jira]
+*** xref:mcp:managed/metabase.adoc[Metabase]
 *** xref:mcp:managed/openapi.adoc[OpenAPI]
 *** xref:mcp:managed/ramp.adoc[Ramp]
 *** xref:mcp:managed/workday.adoc[Workday]
@@ -54,8 +55,6 @@
 * xref:governance:index.adoc[Governance]
 ** xref:governance:dashboard/index.adoc[Governance dashboard]
 *** xref:governance:dashboard/overview.adoc[Read the governance overview]
-*** xref:governance:dashboard/agent-network.adoc[Agent network]
-*** xref:governance:dashboard/violations.adoc[Authorization denials and violations]
 ** xref:governance:guardrails/index.adoc[Guardrails]
 *** xref:governance:guardrails/overview.adoc[Overview]
 *** xref:governance:guardrails/create-guardrail.adoc[Create a guardrail]

@@ -1,4 +1,192 @@
 = Register Your Own Agent (BYOA)
-:description: Connect your existing AI agent to Redpanda ADP for observability and governance.
+:description: Register an agent you operate yourself with the Agentic Data Plane so it appears in the governance dashboard, emits transcripts, and can be called over A2A. Covers the registration model, A2A endpoint contract, service-account auth, and how BYOA differs from a managed agent.
+:page-topic-type: how-to
+:personas: agent_developer, platform_admin
+:learning-objective-1: Distinguish a BYOA (Bring Your Own Agent) from a Redpanda-managed agent and decide when each fits
+:learning-objective-2: Identify the A2A endpoint contract a BYOA agent must expose (well-known agent card and the `/.well-known/agent-card.json` discovery URL)
+:learning-objective-3: Identify the service-account auth model BYOA agents use to authenticate inbound calls and emit telemetry
 
-// TODO: Add content
+// TODO: this page describes BYOA registration as a model. The BYOA variant of `AgentCreate.agent_type` is not yet defined in the public proto (`AgentRegistryService.CreateAgent` itself is in place), and there is no UI surface yet. Re-anchor on the BYOA-arm proto definition (`SelfManagedAgentInput` or equivalent) once it lands in `proto/public/cloud/redpanda/api/adp/v1alpha1/agent.proto`. Add the click-by-click steps and CLI examples once the surface exists. Confirm with team-ai before drafting the step-by-step flow.
+
+A *BYOA* agent is an agent you operate yourself, in your own runtime, that participates in the Agentic Data Plane through three integration points:
+
+* *Registration*: Your agent has an entry in the agents registry, so it shows up on the governance dashboard alongside Redpanda-managed agents.
+* *A2A discovery*: Your agent exposes a standard https://a2aproject.org/[A2A protocol] endpoint that other agents (and AI Gateway) can discover and call.
+* *Telemetry*: Your agent emits OpenTelemetry traces that flow into the same `redpanda.otel_traces` topic as managed agents, so transcripts and cost rollups attribute its calls.
+
+BYOA is the right fit when you have an existing agent (Python LangGraph, Go runtime, in-house framework) you don't want to rewrite, but you want the observability and governance benefits of the Agentic Data Plane.
+
+After completing this guide, you will be able to:
+
+* [ ] {learning-objective-1}
+* [ ] {learning-objective-2}
+* [ ] {learning-objective-3}
+
+== When to use BYOA versus a managed agent
+
+The two models differ in who runs the agent, who owns scaling, and how the agent is defined. The following table compares the trade-offs across the most common decision points.
+
+[cols="1,2,2"]
+|===
+|Question |Choose BYOA when… |Choose a managed agent when…
+
+|Where does your agent run?
+|You have an existing runtime (LangGraph, custom Go, etc.) you want to keep.
+|You want Redpanda to host and operate the agent runtime for you.
+
+|How is the agent defined?
+|It's already coded; you don't want to translate it into the declarative agent format.
+|You want a YAML / declarative definition you edit in the ADP UI.
+
+|Who scales and operates it?
+|Your team owns scaling, deploys, and the failure model.
+|Redpanda owns the runtime; you reason about the agent definition only.
+
+|What are you optimizing for?
+|Maximum control over runtime, libraries, networking.
+|Time-to-first-running-agent and built-in observability without integration work.
+|===
+
+If you have a Redpanda-managed agent today and you're considering BYOA, you don't have to migrate; the two coexist in the same registry and the same dashboard.
+
+== What registration gives you
+
+When a BYOA agent is registered:
+
+* It appears in *AgentRegistryService.ListAgents*, which means it shows up on the governance dashboard's *Agents* list, in cost-attribution queries, and in cross-agent topology views.
+
+// TODO: cross-agent topology views are roadmap; remove the topology mention once those views ship publicly, or keep it once they exist.
+* AI Gateway can discover and call its A2A endpoint by name. Agents calling tools or sub-agents can target your BYOA agent the same way they target any other agent.
+* Service-account credentials are issued to the agent for authenticated inbound calls and for OTLP telemetry ingestion. (Service-account creation follows the same pattern as managed agents. See xref:agents:concepts.adoc#service-account-authorization[Service account authorization].)
+
+// TODO: confirm whether service-account creation is automatic on BYOA registration (as it is for managed agents) or whether the BYOA variant requires the operator to bring their own credentials. Open Q with team-ai.
+
+== Prerequisites
+
+Before you register a BYOA agent, make sure you have:
+
+* An agent running in your own infrastructure with a reachable HTTPS endpoint.
+* The ability to add an HTTPS route at `/.well-known/agent-card.json` (or equivalent) on that endpoint. See <<a2a-endpoint-contract>>.
+* The agent instrumented with OpenTelemetry, emitting the minimum required spans contract. See xref:observability:byoa-telemetry.adoc[BYOA telemetry (OpenTelemetry)].
+* The right permission to create agents (`dataplane_adp_agent_create`).
+* A name for the agent that follows DNS-1123 conventions (1–63 characters, lowercase letters / numbers / hyphens, starting with a letter). The name is immutable once the agent is registered.
+
+[[a2a-endpoint-contract]]
+== A2A endpoint contract
+
+Your BYOA agent must expose an A2A endpoint that AI Gateway and peer agents can discover and call. The contract has two parts: a well-known agent-card document and the A2A message endpoints.
+
+=== Well-known agent card
+
+A2A clients discover an agent's capabilities by fetching:
+
+[source,text]
+----
+GET https://<your-agent-host>/.well-known/agent-card.json
+----
+
+The response is a JSON document (the *agent card*) per the https://a2aproject.org/[A2A protocol specification], containing the agent's identity, supported skills, supported message formats, and the message endpoint URL. Per RFC 8615, the `/.well-known/agent-card.json` path is a standard discovery convention.
+
+For the agent-card schema and a sample document, see xref:agents:a2a-concepts.adoc[Agent-to-agent concepts].
+
+// TODO: link the canonical A2A spec version Redpanda's runtime is compatible with once team-ai confirms the pin (the spec is iterating; we should peg to a specific version in docs).
+
+=== Message endpoints
+
+The agent card declares one or more endpoints that accept A2A messages:
+
+* `POST /v1/message:stream`: Streaming responses over Server-Sent Events.
+* `POST /v1/message:send`: One-shot, blocks until the agent's response is complete.
+
+These are the standard A2A endpoints; your agent must expose at least the `:send` endpoint to be invokable. The streaming endpoint is required for callers that want to surface tool-call and model-call progress in the calling agent's transcript.
+
+For the wire shapes and request/response examples, see xref:agents:a2a-concepts.adoc[Agent-to-agent concepts].
+
+=== Authentication
+
+Your A2A endpoint authenticates inbound A2A calls with the same OAuth 2.0 client-credentials flow used elsewhere in ADP. The caller (typically AI Gateway) presents an OIDC access token, and your agent verifies it against the issuer.
+
+// TODO: confirm the exact issuer and audience BYOA agents must validate against, especially under the standalone-ADP product surface (the existing managed model uses Redpanda Cloud Organization IAM; standalone ADP may issue from a different IdP). Update once confirmed.
+
+== Register the agent
+
+// TODO: this section walks through the registration steps. The flow is described conceptually below; replace with click-by-click + CLI examples once the BYOA arm of `AgentCreate.agent_type` lands and a UI route exists.
+
+Conceptually, registration captures these pieces of data:
+
+[cols="1,3"]
+|===
+|Field |What it carries
+
+|*Name*
+|DNS-1123 identifier. Immutable. Used in `ListAgents`, in cost-attribution queries, and as the agent's resource identifier across A2A, governance, and transcripts.
+
+|*Display name*
+|Human-readable label shown in the UI. Editable later.
+
+|*Description*
+|Free-text description of what the agent does. Editable later.
+
+|*Tags*
+|Optional key/value labels (up to 50 pairs). Useful for filtering on the governance dashboard.
+
+|*Agent endpoint URL*
+|The HTTPS base URL where your agent's `/.well-known/agent-card.json` lives. AI Gateway uses this to fetch the agent card when callers reference your agent by registered name.
+
+// TODO: confirm whether the registration message carries the agent endpoint URL directly, or requires it via the agent card only. The proto will resolve this when the BYOA arm lands.
+
+|*Agent type / variant*
+|Set to the BYOA arm of `AgentCreate.agent_type`.
+
+// TODO: replace with the exact `oneof` variant name once it lands in the public proto.
+|===
+
+Once registered, your agent appears in the dashboard's Agents list and accepts A2A calls. The first time it serves a request, transcripts begin populating.
+
+== Verify the registration
+
+After registering, confirm three things end-to-end:
+
+. *Discovery*: The agent appears in *AgentRegistryService.ListAgents* and in the governance dashboard's Agents list. *Type* shows as *BYOA*.
+. *A2A reachability*: A test A2A call to `https://aigw.<cluster-id>.clusters.rdpa.co/agents/<your-agent-name>/v1/message:send` returns the expected response (or a `FAILED_PRECONDITION` if your agent isn't running, but no `404 Not Found`).
+. *Telemetry*: Open the transcripts list, filter by your agent's `service.name`, and confirm a recent execution shows up with non-zero token counts and a non-empty conversation ID. If it doesn't, see xref:observability:byoa-telemetry.adoc[BYOA telemetry (OpenTelemetry)] troubleshooting.
+
+== Troubleshooting
+
+The symptom-driven checks in this section cover the three observable parts of the contract: discovery, A2A reachability, and telemetry.
+
+// TODO: populate against the live BYOA registration flow once it ships.
+
+[cols="1,2"]
+|===
+|Symptom |What to check
+
+|Agent registered but doesn't appear in the dashboard's Agents list
+|Confirm `ListAgents` returns the agent (the dashboard reads from `AgentRegistryService.ListAgents`). If `ListAgents` is empty, the registration didn't persist; retry. If it's there but the dashboard is empty, refresh the dashboard or check the *Type* filter isn't excluding BYOA.
+
+|A2A call to the registered agent returns `404`
+|The agent endpoint URL on the registration record doesn't match where your agent is actually running, or the agent isn't serving `/.well-known/agent-card.json`. Update the registration with the correct URL, or fix the well-known route.
+
+|Transcripts list shows the agent column blank for your agent's runs
+|Your agent's OTel `service.name` resource attribute doesn't match the registered name (or isn't being emitted at all). See xref:observability:byoa-telemetry.adoc[BYOA telemetry (OpenTelemetry)].
+
+|Inbound A2A calls fail with `401 Unauthorized`
+|Your agent is rejecting the access token AI Gateway presents. Confirm your agent's token validator points at the right issuer and accepts the right audience.
+
+// TODO: replace once standalone-ADP issuer / audience values are confirmed.
+|===
+
+== Out of scope
+
+This page does not cover:
+
+* *Building the agent itself.* Bring whatever runtime, framework, and language you want. The contract (A2A endpoint + telemetry attributes) is what makes it visible in ADP.
+* *Tool use through MCP.* If your BYOA agent calls MCP servers hosted in AI Gateway, see xref:mcp:overview.adoc[MCP Servers] for the consumer-side flow. Tool calls automatically appear in your agent's transcript when MCP servers emit their own spans.
+* *Migration from a managed declarative agent to BYOA.* The two coexist; BYOA is for agents that already exist outside the managed runtime, not for re-platforming existing managed agents.
+
+== Related topics
+
+* xref:agents:a2a-concepts.adoc[Agent-to-agent concepts]
+* xref:observability:byoa-telemetry.adoc[BYOA telemetry (OpenTelemetry)]
+* xref:agents:concepts.adoc[Agent concepts]
+* xref:agents:create-agent.adoc[Create a declarative agent]
@@ -58,6 +58,7 @@ Process every event with AI reasoning at scale. Invoke agents automatically from
 
 * Agents are available only on ADP BYOC environments
 * MCP servers must be hosted in ADP
+// TODO(review-before-publish): forward-looking framing — "is not currently supported" implies it's coming. Confirm whether to keep this limitation note as-is, drop "currently" to make it a static limitation, or remove the bullet entirely if the workaround (internal subagents) is the durable answer.
 * Cross-agent calling between separate agents is not currently supported (use internal subagents for delegation within a single agent)
 
 == Next steps

@@ -84,6 +84,11 @@ rpk ai llm list
 
 If the cached cloud token has expired, `rpk ai` returns a 401 with a hint to rerun `rpk cloud login`.
 
+[NOTE]
+====
+`rpk ai help`, `rpk ai version`, and unknown subcommands run without prompting for authentication, so you can browse the CLI surface offline before signing in. Authentication is only required for commands that hit AI Gateway.
+====
+
 [TIP]
 ====
 To target a specific gateway URL for a single invocation (for example, when running against a staging gateway without switching profiles), pass `--rpai-endpoint`:
@@ -414,6 +419,7 @@ AI Gateway returns standard HTTP status codes. The upstream provider's error bod
 * Implement retry with exponential backoff for 5xx and timeout conditions.
 * Respect `Retry-After` on 429 responses.
 * Rotate service account credentials on a schedule your organization accepts.
+// TODO(review-before-publish): forward-looking framing — "is in development" and "today". Same wording duplicated in `ai-gateway/pages/overview.adoc`. Confirm whether the *Cost & usage* surface is shipped before merge; rephrase or drop the sentence based on the current state.
 * Observe usage through the ADP UI on each provider's detail page. A *Cost & usage* section is in development (the UI shows a "Coming soon" placeholder today).
 
 == Troubleshooting

@@ -50,6 +50,7 @@ Applications authenticate to ADP with OIDC service accounts instead of long-live
 
 === Per-provider observability
 
+// TODO(review-before-publish): forward-looking framing — "is in development" and "today". Confirm whether the *Cost & usage* surface is shipped before merge; if so, drop the development qualifier and describe what users see; if not, drop the sentence entirely or rephrase to describe the current "Coming soon" placeholder without the in-development claim.
 The provider's detail page in the ADP UI records request and token counts. A *Cost & usage* section is in development (the UI shows a "Coming soon" placeholder today).
 
 == What's in the UI
@@ -110,7 +111,7 @@ It is not the right fit when you:
 AI Gateway does not provide these capabilities. For current status, consult the ADP release notes.
 
 * *Multi-provider routing, failover, and retries.* A synthetic provider that fans requests to multiple upstreams is not part of AI Gateway.
-* *Spend limits.* Per-user, per-org, and global cost caps are not available. The provider detail page shows a *Cost & usage* placeholder labeled "Coming soon"; see xref:governance:budgets.adoc[Token budgets and limits] for the read-only spending visibility shipping at GA.
+* *Spend limits.* Per-user, per-org, and global cost caps are not available. The provider detail page shows a *Cost & usage* placeholder labeled "Coming soon"; see xref:governance:budgets.adoc[Token budgets and limits] for the read-only spending visibility.
 * *Rate limits.* Requests-per-second, per-minute, or per-day caps are not available.
 * *Managed MCP aggregation at the gateway.* Register MCP tool servers separately under *MCP Servers* in the ADP UI.