redpanda-data · micheleRP · May 29, 2026 · May 29, 2026
@@ -1,18 +1,21 @@
 = Register Your Own Agent (BYOA)
-: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.
+:description: Register a self-managed agent so it appears in the ADP registry and governance dashboard, with its telemetry and cost attributed alongside managed agents.
 :page-topic-type: how-to
 :personas: agent_builder, platform_engineer
-:learning-objective-1: Distinguish a BYOA (Bring Your Own Agent) from a Redpanda-managed agent and decide when each fits
-:learning-objective-2: pass:q[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
+:learning-objective-1: Distinguish a self-managed (BYOA) agent from a Redpanda-managed agent and decide when each fits
+:learning-objective-2: Register a self-managed agent so it appears in the agent registry and governance dashboard
+:learning-objective-3: Identify the telemetry and service-account model that attributes a self-managed agent's activity in ADP
 
-// 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* (bring-your-own-agent) agent is an agent you build and run yourself, in your own runtime. You register it with the Agentic Data Plane so it appears alongside Redpanda-managed agents for governance and observability.
 
-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 creates a *metadata record*. The Agentic Data Plane tracks the agent and attributes its telemetry and cost, but it does not host or run the agent, and it does not proxy calls to it. Your agent runs entirely in your own infrastructure.
 
-* *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.
+A self-managed agent participates in ADP through two integration points:
+
+* *Registration*: The agent has an entry in the agent registry, so it appears on the governance dashboard alongside managed agents and in cost-attribution queries.
+* *Telemetry*: The agent emits OpenTelemetry traces, with its registered name as the `service.name`, into the same pipeline as managed agents, so transcripts and cost rollups attribute its calls.
+
+To authenticate its calls to AI Gateway (the LLM proxy and any MCP servers) and its telemetry ingestion, the agent uses service-account credentials issued at registration.
 
 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.
 
@@ -31,7 +34,7 @@ The two models differ in who runs the agent, who owns scaling, and how the agent
 |Question |Choose BYOA when… |Choose a managed agent when…
 
 |Where does your agent run?
-|You have an existing runtime (LangGraph, custom Go, and so on) you want to keep.
+|You have an existing runtime (LangGraph, custom Go, and so on) you want to keep, and you run it yourself.
 |You want Redpanda to host and operate the agent runtime for you.
 
 |How is the agent defined?
@@ -43,145 +46,89 @@ The two models differ in who runs the agent, who owns scaling, and how the agent
 |Redpanda owns the runtime; you reason about the agent definition only.
 
 |What are you optimizing for?
-|Maximum control over runtime, libraries, networking.
+|Maximum control over runtime, libraries, networking, with governance and observability layered on.
 |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:
+When a self-managed 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.
+* It appears in the agent registry (`AgentRegistryService.ListAgents`), which means it shows up on the governance dashboard's *Agents* list and in cost-attribution queries.
+* A service-account identity is created for the agent at registration. Mint credentials for it to authenticate the agent's calls to AI Gateway and its telemetry ingestion. Credential issuance follows the same pattern as managed agents. See xref:connect:concepts.adoc#service-account-authorization[Service account authorization].
 
-// 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:connect: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.
+Registration does not make the Agentic Data Plane run your agent or route requests to it. The agent runs in your infrastructure, and any clients (including other agents) call it directly.
 
 == Prerequisites
 
-Before you register a BYOA agent, make sure you have:
+Before you register a self-managed 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:monitor:byoa-telemetry.adoc[BYOA telemetry].
+* An agent running in your own infrastructure.
+* The agent instrumented with OpenTelemetry, emitting the minimum required spans contract with its registered name as the `service.name`. See xref:monitor:byoa-telemetry.adoc[BYOA telemetry].
 * The `dataplane_adp_agent_create` permission, granted by the Writer built-in role. See xref:control:permissions-reference.adoc#agent-management-permissions[Agent management permissions].
-* 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:connect: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:connect: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.
+* A name for the agent that follows DNS-1123 conventions (1 to 63 characters, lowercase letters, numbers, and hyphens, starting with a letter). The name is immutable once the agent is registered.
 
 == 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:
+You register a self-managed agent through `AgentRegistryService.CreateAgent`. The registration carries the agent's metadata, and you leave the agent-type configuration unset:
 
 [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.
+|`name`
+|DNS-1123 identifier. Immutable. Used in the registry, in cost-attribution queries, and as the agent's resource identifier.
 
-|*Display name*
+|`display_name`
 |Human-readable label shown in the UI. Editable later.
 
-|*Description*
+|`description`
 |Free-text description of what the agent does. Editable later.
 
-|*Tags*
+|`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.
+|`agent_type`
+|Leave unset. Populating the `managed` arm creates a Redpanda-managed agent instead; leaving the whole field unset registers a self-managed (BYOA) metadata record.
+|===
 
-// TODO: confirm whether the registration message carries the agent endpoint URL directly, or requires it through the agent card only. The proto will resolve this when the BYOA arm lands.
+Once registered, your agent appears in the dashboard's *Agents* list. The first time it serves a request and emits telemetry, transcripts begin populating.
 
-|*Agent type / variant*
-|Set to the BYOA arm of `AgentCreate.agent_type`.
+== Make your agent callable by other agents (optional)
 
-// TODO: replace with the exact `oneof` variant name once it lands in the public proto.
-|===
+If you want other agents or clients to call your agent, expose a standard https://a2aproject.org/[A2A protocol] endpoint on your own infrastructure (an agent-card document at `/.well-known/agent-card.json`, plus the A2A message endpoints). Callers reach your agent directly at its own address. The Agentic Data Plane does not proxy A2A traffic to self-managed agents; its A2A reverse proxy serves Redpanda-managed agents only.
 
-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.
+For the agent-card schema and the A2A message-endpoint shapes, see xref:connect:a2a-concepts.adoc[Agent-to-agent concepts].
 
 == Verify the registration
 
-After registering, confirm three things end-to-end:
+After registering, confirm two 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`).
+. *Registry*: The agent appears in `AgentRegistryService.ListAgents` and in the governance dashboard's *Agents* list.
 . *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:monitor:byoa-telemetry.adoc[BYOA telemetry] 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.
+|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 that a column filter isn't excluding it.
 
 |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:monitor:byoa-telemetry.adoc[BYOA telemetry].
-
-|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.
+|Your agent's OpenTelemetry `service.name` resource attribute doesn't match the registered name, or isn't being emitted at all. See xref:monitor:byoa-telemetry.adoc[BYOA telemetry].
 |===
 
 == Limitations
 
 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:connect: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.
+* *Building the agent itself.* Bring whatever runtime, framework, and language you want. The integration points (telemetry attributes plus the registry record) are what make it visible in ADP.
+* *Tool use through MCP.* If your agent calls MCP servers hosted in AI Gateway, see xref:connect:mcp-overview.adoc[MCP Servers] for the consumer-side flow. Tool calls appear in your agent's transcript when MCP servers emit their own spans.
+* *Gateway-proxied A2A routing.* The Agentic Data Plane does not route A2A calls to self-managed agents; that is a managed-agent capability. Clients call your agent directly.
 * *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

@@ -111,15 +111,13 @@ Claude Code can call MCP servers for tool access. To use the MCP servers you alr
 
 [source,bash]
 ----
-claude mcp add <server-name> https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/servers/<server-name>
+claude mcp add <server-name> https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/<server-name>
 ----
 
 For OAuth-protected MCP servers (most managed types), Claude Code prompts the developer to complete the consent flow on first use. ADP stores the resulting token in the per-user xref:connect:user-delegated-oauth.adoc[token vault], so subsequent invocations reuse it.
 
 To front many MCP servers behind a single Claude Code endpoint, use xref:gateway:aggregation.adoc[MCP aggregation] and point Claude Code at the aggregated URL.
 
-// TODO: Confirm the exact MCP URL shape (`/mcp/v1/servers/<name>` vs. another path) against adp-production once the MCP servers detail page surfaces the canonical URL.
-
 == Verify the connection
 
 . Run a short prompt: