# Agentic Data Plane - Full Markdown Export > This file contains all Agentic Data Plane documentation pages in markdown format for AI agent consumption. > Generated from 204 pages on 2026-08-11T15:28:37.380Z > Component: agentic-data-plane | Version: > Site: https://docs.redpanda.com ## About This Export This export includes the **latest version** () of the Agentic Data Plane documentation. ### AI-Friendly Documentation Formats We provide multiple formats optimized for AI consumption: - **https://docs.redpanda.com/llms.txt**: Curated overview of all Redpanda documentation - **https://docs.redpanda.com/llms-full.txt**: Complete documentation export with all components - **https://docs.redpanda.com/agentic-data-plane-full.txt**: This file - Agentic Data Plane documentation only - **Individual markdown pages**: Each HTML page has a corresponding .md file --- # Page 1: Use the Agentic Data Plane CLI **URL**: https://docs.redpanda.com/agentic-data-plane/cli.md --- # Use the Agentic Data Plane CLI > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Use the Agentic Data Plane CLI latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: index page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/cli/pages/index.adoc description: Manage Agentic Data Plane resources from the terminal with rpk ai. Install the CLI, connect it to an AI Gateway, and script LLM providers, MCP servers, OAuth, and agents. page-topic-type: how-to personas: platform_engineer, agent_builder learning-objective-1: Install the Agentic Data Plane CLI and connect it to an AI Gateway learning-objective-2: "Manage Agentic Data Plane resources from the terminal: LLM providers, MCP servers, OAuth providers and clients, and agents" learning-objective-3: Format command output for scripts and pipelines page-git-created-date: "2026-06-26" page-git-modified-date: "2026-08-10" --- The Agentic Data Plane command-line interface, `rpk ai`, manages [Agentic Data Plane](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#agentic-data-plane) resources from your terminal. It drives the same control surface as the Agentic Data Plane UI: [large language model (LLM)](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#large-language-model-llm) providers, Model Context Protocol (MCP) servers, OAuth providers and clients, and agents. Because every action is a command, you can script it and run it in continuous integration. The Agentic Data Plane CLI, also called the Redpanda AI CLI, runs as an [`rpk`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) plugin, so you install and run it through your existing `rpk` setup. After reading this page, you will be able to: - Install the Agentic Data Plane CLI and connect it to an AI Gateway - Manage Agentic Data Plane resources from the terminal: LLM providers, MCP servers, OAuth providers and clients, and agents - Format command output for scripts and pipelines ![rpk ai workflow. Install the rpk ai plugin, sign in and select an Agentic Data Plane environment, then manage LLM providers, MCP servers, OAuth resources, and agents; list or call MCP tools and send A2A messages; or launch supported coding agents through AI Gateway. These workflows share the selected identity and environment.](_images/rpk-ai-workflow.svg) Figure 1. `rpk ai` reuses one authenticated environment across resource, protocol, and agent workflows ## [](#install-the-cli)Install the CLI The Agentic Data Plane CLI is an `rpk` managed plugin. Install `rpk` first (see [Install or Update rpk](https://docs.redpanda.com/agentic-data-plane/reference/rpk-install/)), then install the plugin: ```bash rpk ai install ``` Update the plugin later with [`rpk ai upgrade`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-upgrade/), and remove it with [`rpk ai uninstall`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-uninstall/). > 📝 **NOTE** > > Upgrading `rpk` does not upgrade the plugin. The plugin is a separate binary that stays at its installed version, even across `rpk` upgrades, until you run `rpk ai upgrade`. New commands and flags in the reference marked "introduced in ai version X" require the plugin at that version or later. ## [](#connect-to-an-ai-gateway)Connect to an AI Gateway The `rpk ai` command is self-contained: it has its own login and its own environment selection, independent of any `rpk cloud` session. You sign in once, choose an Agentic Data Plane environment, and `rpk ai` targets that environment’s AI Gateway for every command. 1. Sign in to Agentic Data Plane. This runs an OAuth device-authorization flow in your browser, caches credentials in `~/.rpai/credentials` (readable only by you), then lists the Agentic Data Plane environments in your organization so you can pick one: ```bash rpk ai auth login ``` 2. List the environments available to you, and switch the active one by name or ID: ```bash rpk ai env list rpk ai env use ``` In these commands, `` is the name or ID of an Agentic Data Plane environment. `rpk ai env use` switches the active environment, pointing the CLI at that environment’s AI Gateway. Inspect the resolved environment and token state at any time with `rpk ai env show` and `rpk ai auth status`. 3. Verify the connection: ```bash rpk ai llm-provider list ``` For the full setup walkthrough, including token expiry behavior and the supported environment variables, see [Use `rpk ai` for local development](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/#authenticate-with-rpk-ai). To target a different AI Gateway URL for a single command without switching environments, pass `--rpai-endpoint`: ```bash rpk ai --rpai-endpoint https://aigw..clusters.rdpa.co llm-provider list ``` This overrides the selected environment’s AI Gateway URL for that one command; the flag is not bound to an environment variable. For a local or manual gateway you use repeatedly, define it once as an environment with `rpk ai env add`: ```bash rpk ai env add local --ai-gateway-url http://localhost:8090 --auth-mode none rpk ai env use local ``` ## [](#manage-resources)Manage resources Each Agentic Data Plane resource has its own command group, and each group supports the standard `create`, `get`, `list`, `update`, and `delete` actions. The model catalog is read-only. | Command | Manages | | --- | --- | | rpk ai llm-provider | LLM providers (OpenAI, Anthropic, Google, AWS Bedrock, and OpenAI-compatible endpoints) | | rpk ai mcp-server | MCP servers and their tools | | rpk ai oauth-provider | OAuth providers for user-delegated MCP connections | | rpk ai oauth-client | OAuth clients that external tools use to reach an MCP server | | rpk ai agent | Agents in the agent registry | | rpk ai model | The model catalog (read-only discovery) | For example, to create and inspect an LLM provider: ```bash rpk ai llm-provider create --name openai --type openai --api-key-ref OPENAI_API_KEY rpk ai llm-provider get openai ``` In this command, `--api-key-ref` names a secret already stored in Agentic Data Plane. The CLI never takes a raw API key, so secrets stay out of your shell history and out of any file you commit. To create, update, and delete resources declaratively from YAML manifests instead of imperative flags, see [Manage Resources with GitOps](gitops/). ## [](#format-command-output)Format command output Every `list` and `get` command honors `-o` (`--format`): | Format | Use | | --- | --- | | table | Default. Human-readable columns. | | wide | Table with extra columns. | | json | Machine-readable JSON for scripts and jq. | | yaml | YAML. A get -o yaml dump is a complete manifest you can edit and reapply. | | markdown | Pipe-friendly tables for documents. | Set a default for the session with the `RPAI_FORMAT` environment variable. The `-o` flag always wins when both are set. ## [](#next-steps)Next steps - [Manage Resources with GitOps](gitops/) - [Configure an LLM Provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/) - [rpk ai](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) --- # Page 2: Manage Resources with GitOps **URL**: https://docs.redpanda.com/agentic-data-plane/cli/gitops.md --- # Manage Resources with GitOps > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Manage Resources with GitOps latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: gitops page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: gitops.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/cli/pages/gitops.adoc description: "Keep Agentic Data Plane resources in Git and reconcile them with rpk ai apply and diff: declarative create-or-update, drift detection, and CI gating." page-topic-type: how-to personas: platform_engineer, agent_builder learning-objective-1: Export an Agentic Data Plane resource to a YAML manifest you can commit to Git learning-objective-2: Reconcile resources with apply, and preview changes with diff learning-objective-3: Gate continuous integration on configuration drift page-git-created-date: "2026-06-26" page-git-modified-date: "2026-07-30" --- GitOps keeps the definition of your [Agentic Data Plane](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#agentic-data-plane) resources in Git and reconciles the live environment toward those files, instead of running imperative `create`, `update`, and `delete` commands by hand. With the [Agentic Data Plane CLI](../), `rpk ai apply -f` creates what is missing and updates what has drifted, and `rpk ai diff -f` is a read-only dry-run that reports what `apply` would change. In these commands, `` is one of the resource command groups that support GitOps: - LLM providers (`rpk ai llm-provider`) - MCP servers (`rpk ai mcp-server`) - OAuth providers (`rpk ai oauth`) - OAuth clients (`rpk ai oauth-client`) - Agents (`rpk ai agent`) After reading this page, you will be able to: - Export an Agentic Data Plane resource to a YAML manifest you can commit to Git - Reconcile resources with apply, and preview changes with diff - Gate continuous integration on configuration drift ## [](#prerequisites)Prerequisites - The [Agentic Data Plane CLI installed and connected](../) to an Agentic Data Plane environment. - Permission to create and update the resources you manage. The reconcile commands call the same APIs as `create` and `update`. See [Roles and Permissions Reference](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/). - Any secrets your manifests reference already created in Agentic Data Plane. Manifests name secrets by reference, for example, `OPENAI_API_KEY`; the CLI does not create secrets. ## [](#how-apply-and-diff-reconcile)How apply and diff reconcile A manifest is plain resource YAML: the same shape a `get -o yaml` dump produces. The CLI compares each manifest against the live resource of the same name and resolves one of three outcomes: Create No resource of that name exists, so `apply` creates it. Update The resource exists and a field in the manifest differs from the live value, so `apply` updates the differing fields. Unchanged The resource exists and every field the manifest names already matches. The reconcile rules are deliberate, and they are not the same as a full-object replace: Presence drives updates A field that is present in the manifest and differs from the live resource is updated. A field you omit is left untouched. To clear a field, write it explicitly with an empty or zero value. Collections replace wholesale Lists, maps, and provider or backend variants are replaced as a unit, not merged element by element. Create-only fields are immutable A field that can be set only at creation time, such as an LLM provider’s `type`, an MCP server’s backend kind, an OAuth provider’s `client_id`, or an agent’s managed-or-self-managed kind, cannot change on an existing resource. Changing one is an error that tells you to delete and recreate the resource. Request-only fields are instructions, not state A few fields tell the gateway to do something rather than describe what a resource is. An MCP server’s `remote.user_oauth.automatic_setup` asks the gateway to set up OAuth for the server itself instead of attaching a provider by name. Set it in a manifest when you want automatic setup, and leave `provider_name` out: on an existing server an empty `provider_name` preserves the provider already attached, and setting both is an error. Omitting `automatic_setup` leaves an existing attachment untouched, so an unrelated edit such as a scopes change never re-runs OAuth setup. See [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). Secrets stay by reference Manifests reference secrets by name, for example, `api_key_ref` and `client_secret_ref`, and never contain secret values, so a manifest is safe to commit to Git. The `apply` command does not delete resources that are absent from your manifests; there is no prune. The `diff` command checks only the fields a manifest names, so it does not detect a resource that exists in the environment but is missing from your manifests, nor drift in a field a manifest omits. ## [](#export-a-resource-to-a-manifest)Export a resource to a manifest Start from a live resource so the manifest is complete. Dump it to YAML and redirect it to a file: ```bash rpk ai llm-provider get openai -o yaml > openai.yaml ``` A dumped OpenAI provider looks like this, ready to commit: ```yaml '@type': type.googleapis.com/redpanda.api.adp.v1alpha1.LLMProvider created_at: "2026-06-20T10:15:30Z" display_name: OpenAI enabled: true name: openai openai_config: api_key_ref: OPENAI_API_KEY provider_models: - name: gpt-4o - name: gpt-4o-mini type: LLM_PROVIDER_TYPE_OPENAI updated_at: "2026-06-20T10:15:30Z" url: https://openai.aigw.d0example1cluster234.clusters.rdpa.co/openai/v1 ``` The `@type` line records the resource kind. It is optional when you apply with a resource command, because `rpk ai llm-provider apply` already implies the kind, but keeping it lets a reader and any validator know what the file describes. > 📝 **NOTE** > > The `created_at`, `updated_at`, and `url` fields are server-managed and read-only. The `apply` command ignores them, so you can leave them in the file or strip them. The `api_key_ref` value is a reference to a secret, not the key itself. ## [](#preview-changes-with-diff)Preview changes with diff Edit the manifest, then preview the effect before you touch the environment. For example, change the display name: ```yaml display_name: OpenAI (production) ``` Run `diff` to see the plan: ```bash rpk ai llm-provider diff -f openai.yaml ``` ```text ~ openai (update: display_name) ``` The `diff` command marks each manifest with one of three symbols and changes nothing: | Symbol | Meaning | | --- | --- | | + | The apply command would create the resource. | | ~ | The apply command would update the resource. The changed fields follow in parentheses. | | = | The resource already matches; apply would leave it unchanged. | The `diff` command exits with a non-zero status when any change is pending, and zero when the environment already matches every manifest. That exit code is what lets continuous integration gate on drift. ## [](#apply-changes)Apply changes Reconcile the environment toward the manifest: ```bash rpk ai llm-provider apply -f openai.yaml ``` The `apply` command prints one line per manifest as it works: ```text updated openai (display_name) ``` A first-time apply of a resource that does not yet exist prints `created openai` instead, and a manifest that already matches the environment prints `unchanged openai`. The CLI plans every manifest before it changes anything, so a malformed manifest aborts the run before any write. If a later write fails, the lines already printed tell you exactly what was applied. ## [](#apply-many-manifests-at-once)Apply many manifests at once The `-f` flag is repeatable and accepts a file, a directory, or a stream: ```bash # A directory of manifests; the CLI reads every .yaml and .yml file, sorted by name. rpk ai mcp-server apply -f ./manifests/ # Several paths in one run. rpk ai llm-provider apply -f openai.yaml -f anthropic.yaml # Standard input, for piping a manifest from another tool. rpk ai oauth apply -f - ``` A single file can hold more than one manifest. Separate documents with a line containing only `---`. ## [](#gate-continuous-integration-on-drift)Gate continuous integration on drift Because `diff` exits non-zero when the environment differs from your manifests, a continuous-integration job can fail the build whenever the live environment has drifted from Git: ```bash # Fails the job if an apply would change anything. rpk ai llm-provider diff -f ./llm/ rpk ai mcp-server diff -f ./mcp/ ``` A common pipeline runs `diff` on a pull request to preview changes, then runs `apply` after the merge to roll them out: ```bash # Deploy step, after merge to the main branch. rpk ai llm-provider apply -f ./llm/ rpk ai mcp-server apply -f ./mcp/ ``` ## [](#manifests-are-declarative)Manifests are declarative A manifest describes the full intended state, so an omitted field means zero, not the convenience default that `create` fills in. A manifest that omits `enabled` creates a disabled resource, and `diff` then reports no drift, because the disabled state matches the manifest. To avoid surprises: - Start from a `get -o yaml` dump, which is already complete, rather than hand-writing a manifest from scratch. - Set `enabled: true` explicitly when you want an active resource. One subtlety follows from this: a dump of an already-disabled resource omits `enabled`, because `false` is the field’s zero value and the dump omits zero values. Reapplying that dump elsewhere also produces a disabled resource. ## [](#troubleshooting)Troubleshooting | Symptom | Resolution | | --- | --- | | The apply or diff command reports that a field is immutable and tells you to delete and recreate the resource. | You changed a create-only field, such as an LLM provider’s type or an OAuth provider’s client_id. Restore the original value, or delete the resource and recreate it from the new manifest. | | The apply or diff command fails to decode the manifest and mentions unknown or misspelled fields. | A key in the manifest is not a field of the resource. The CLI rejects unknown keys rather than dropping them silently. Fix the key. Start from a get -o yaml dump to get the exact field names. | | The diff command reports no drift, but you know the environment has extra resources. | The diff and apply commands never prune. They act only on the resources your manifests name. Delete unwanted resources with rpk ai delete. | | A field you changed in the environment keeps coming back after apply. | The apply command overwrites a field only when the manifest names it and the value differs. If the change is not in your manifest, add it, then reapply. | ## [](#next-steps)Next steps - [Use the Agentic Data Plane CLI](../) - [Configure an LLM Provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) --- # Page 3: Connect Data & Tools **URL**: https://docs.redpanda.com/agentic-data-plane/connect.md --- # Connect Data & Tools > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Connect Data & Tools latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: index page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/index.adoc description: Connect agents, MCP servers, and the apps and data sources behind them. page-git-created-date: "2026-05-28" page-git-modified-date: "2026-06-08" --- Bring your agents, tools, and data into the Agentic Data Plane. Build agents, connect MCP servers, set up authentication, and integrate with your existing stack. - [Connect Tools with MCP Servers](mcp-servers/) Learn how MCP servers expose tools and data to agents, then plug in a managed type or build, register, and test your own. - [Set Up Authentication](authentication/) Configure OAuth providers, user-delegated OAuth, and client connections so agents and tools authenticate securely. - [Integrate with Your Stack](integrations/) Choose an integration pattern and connect the Agentic Data Plane to your existing stack, Redpanda pipelines, and developer tools. --- # Page 4: Connect Agents with A2A **URL**: https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts.md --- # Connect Agents with A2A > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Connect Agents with A2A latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: a2a-concepts page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: a2a-concepts.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/a2a-concepts.adoc description: The A2A protocol enables agents to discover and call each other across platforms. Learn how agent cards, authentication, and protocol versioning work in Agentic Data Plane. page-topic-type: concepts personas: agent_builder learning-objective-1: Describe the A2A protocol and its role in agent communication learning-objective-2: Explain how agent cards enable discovery learning-objective-3: Identify how authentication secures agent communication page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-10" --- The Agent-to-Agent (A2A) protocol is an open standard that defines how agents discover, communicate with, and call each other across platforms. Each A2A-compliant agent exposes a machine-readable agent card at a well-known URL, describing its capabilities and how to authenticate with it. Callers fetch the card at runtime, so they reach any A2A agent without prior knowledge of its implementation, and agents can update their capabilities without breaking existing callers. In Redpanda Agentic Data Plane, A2A enables two integration paths: external applications and agents calling Agentic Data Plane agents over HTTP, and Redpanda Connect pipelines invoking agents for each event in a stream. After reading this page, you will be able to: - Describe the A2A protocol and its role in agent communication - Explain how agent cards enable discovery - Identify how authentication secures agent communication ## [](#what-is-the-a2a-protocol)What is the A2A protocol? The Agent-to-Agent (A2A) protocol is an open standard that defines how agents discover, communicate with, and invoke each other. Agents that implement A2A expose their capabilities through a standardized agent card. This allows other systems to interact with them without prior knowledge of their implementation. The protocol provides: - Standardized discovery: Agent cards describe capabilities in a machine-readable format. - Platform independence: Any system can call any A2A-compliant agent. - Version negotiation: Protocol versions ensure compatibility between agents. - Communication mode flexibility: Supports synchronous request/response and streaming. Current A2A versions make the interface and protocol version explicit during discovery and standardize how callers receive messages, task status, and artifacts. Callers can integrate with an agent without knowing which framework or runtime implements it. ![A2A lifecycle. An application, agent, or Redpanda Connect pipeline fetches an Agentic Data Plane agent card, chooses a supported interface and protocol version, obtains an access token, sends a message, and receives a direct response or streamed task status and artifacts.](https://docs.redpanda.com/agentic-data-plane/connect/_images/a2a-message-lifecycle.svg) Figure 1. A2A separates discovery from authenticated message and task exchange For the complete specification, see [A2A protocol specification](https://a2a-protocol.org/latest/specification/). ## [](#agent-cards)Agent cards Every A2A-compliant agent exposes an agent card at a well-known URL. The agent card is a JSON document that describes what the agent can do and how to interact with it. For the complete agent card specification, see [A2A Agent Card specification](https://a2a-protocol.org/latest/specification/#44-agent-card). ### [](#agent-card-location)Agent card location Agentic Data Plane agents expose their agent cards at the `/.well-known/agent-card.json` subpath of the agent URL. You can find the agent URL on the **Agents** page. For example, if your agent URL is `https://my-agent.ai-agents.abc123.clusters.rdpa.co`, your agent card URL is `https://my-agent.ai-agents.abc123.clusters.rdpa.co/.well-known/agent-card.json`. The `.well-known` path follows internet standards for service discovery, making agents discoverable without configuration. The agent card is served without authentication. The A2A protocol requires the discovery card to be publicly reachable, because a caller fetches it to learn how to authenticate with the agent. Invoking the agent still requires authentication. For details, see the [Authentication](#authentication) section. To configure the agent card, see [Configure A2A discovery metadata](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/#configure-a2a-discovery-metadata-optional). ## [](#where-a2a-is-used-in-agentic-data-plane)Where A2A is used in Agentic Data Plane Agentic Data Plane uses the A2A protocol in two contexts: ### [](#external-integration)External integration External applications and agents hosted outside Agentic Data Plane use A2A to call Agentic Data Plane agents. This includes backend services, CLI tools, custom UIs, and agents hosted on other platforms. For integration pattern guidance, see [Choose an Integration Pattern](https://docs.redpanda.com/agentic-data-plane/connect/integration-overview/). ### [](#internal-pipeline-to-agent-integration)Internal pipeline-to-agent integration Redpanda Connect pipelines use the [`a2a_message`](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/processors/a2a_message/) processor to invoke agents for each event in a stream. This enables real-time interaction between streaming data and AI agents, enabling use cases like: - Real-time fraud detection on every transaction. - Streaming data enrichment with AI-generated fields. - Event-driven agent invocation for automated processing. The `a2a_message` processor uses the A2A protocol internally to discover and call agents. For pipeline patterns, see [Integrate with Redpanda Pipelines](https://docs.redpanda.com/agentic-data-plane/connect/pipeline-integration-patterns/). ## [](#how-agents-discover-each-other)How agents discover each other A2A enables dynamic discovery without hardcoded configuration: 1. The caller fetches the agent card from the well-known URL. 2. The caller checks the supported interfaces, protocol versions, capabilities, and skills. 3. The caller formats message parts for the content types declared by the selected interface and skill. 4. The caller sends the request to the agent’s endpoint. This discovery model allows: - New agents to become available immediately after deployment - Existing agents to update their capabilities while callers adapt dynamically - Callers to understand exactly what agents do through self-describing agent cards ## [](#authentication)Authentication Agentic Data Plane agents require authentication to prevent unauthorized access. The agent card is the exception. Agentic Data Plane serves the card at the `/.well-known/agent-card.json` subpath without authentication, so that callers can discover how to authenticate before they hold a token. Every other request to the agent, including agent invocation, requires a valid access token. Callers authenticate as themselves, never as the agent they’re calling. Each caller needs its own service account and permission to invoke the agent. See [Service account authorization](https://docs.redpanda.com/agentic-data-plane/connect/concepts/#service-account-authorization) and [A2A runtime permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#a2a-runtime-permissions). Callers use OAuth2 client credentials to obtain access tokens: 1. The caller exchanges its client ID and secret for a time-limited access token through OAuth2. 2. The caller includes the access token in the Authorization header when calling the agent endpoint. 3. When the token expires, the caller exchanges credentials again for a new token. This flow ensures: - Credentials stay secure: Applications never send them directly to agents, only access tokens. - Exposure is limited: Tokens expire, reducing the window for compromised credentials. - Integration is standard: Applications can use existing OAuth2 libraries. ### [](#external-integration-2)External integration External applications and agents authenticate with their own service account credentials, not the target agent’s. Grant the caller permission to invoke the agent with an access policy or a custom role. See [Manage Access Policies](https://docs.redpanda.com/agentic-data-plane/control/access-policies/). ### [](#internal-integration)Internal integration The `a2a_message` processor handles authentication automatically. Pipelines don’t need to manage credentials explicitly because they run within Agentic Data Plane with appropriate permissions. ## [](#protocol-versions)Protocol versions The A2A specification uses semantic release versions, but protocol compatibility uses major.minor. Each supported interface in the agent card declares the `protocolVersion` it exposes. Clients select a compatible interface and send that version on requests; patch versions do not affect protocol compatibility. ## [](#next-steps)Next steps - [Choose an Integration Pattern](https://docs.redpanda.com/agentic-data-plane/connect/integration-overview/) - [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) --- # Page 5: How Agents Work **URL**: https://docs.redpanda.com/agentic-data-plane/connect/agents-overview.md --- # How Agents Work > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: How Agents Work latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: agents-overview page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: agents-overview.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/agents-overview.adoc description: Learn how Agentic Data Plane agents use a declarative approach backed by a broad library of prebuilt tools and integrations to replace custom agent code. page-topic-type: overview personas: agent_builder, platform_engineer learning-objective-1: Describe what AI agents are and their essential components learning-objective-2: Explain how Agentic Data Plane streaming infrastructure benefits agent architectures learning-objective-3: Identify use cases where Agentic Data Plane agents provide value page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-24" --- Redpanda Agentic Data Plane AI agents take a declarative approach: instead of writing Python or JavaScript agent code, you declare the behavior you want by selecting an LLM, writing a system prompt, and attaching prebuilt tools and integrations. The framework handles execution, tool orchestration, and scaling, backed by real-time streaming infrastructure and built-in filtering and data enrichment. After reading this page, you will be able to: - Describe what AI agents are and their essential components - Explain how Agentic Data Plane streaming infrastructure benefits agent architectures - Identify use cases where Agentic Data Plane agents provide value ## [](#what-is-an-ai-agent)What is an AI agent? An AI agent is a system built around a [large language model (LLM)](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#large-language-model-llm) that interprets user intent, selects the right tools, and chains multiple steps into a workflow. In Agentic Data Plane, agents are declarative: you configure the agent’s role, constraints, and available tools rather than writing imperative agent code. Agents reach tools through MCP servers, and Redpanda Connect provides the real-time streaming and data-processing capabilities the framework orchestrates for you. ## [](#declarative-agent-components)Declarative agent components When you create an agent, you configure the components through Agentic Data Plane rather than writing code: - **System prompt**: Defines the agent’s role, responsibilities, and constraints - **LLM**: Interprets user intent and decides which tools to invoke - **Tools**: External capabilities exposed through the [Model Context Protocol (MCP)](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) - **Context**: Conversation history, tool results, and real-time events from Redpanda topics Agents reach these tools through MCP servers. Redpanda Connect pipelines can also invoke agents for event-driven processing, so agents support both interactive workflows and automated streaming. When a user makes a request, the LLM receives the system prompt and context, decides which tools to invoke, and processes the results. This cycle repeats until the task completes. For a deeper understanding of how agents execute, manage context, and maintain state, see [Understand Agent Concepts](https://docs.redpanda.com/agentic-data-plane/connect/concepts/). ## [](#key-benefits)Key benefits Agentic Data Plane agents are designed to reduce the infrastructure and integration work of building production AI systems. - Declarative configuration: Configure agent behavior instead of coding it, with access to a broad library of prebuilt tools and integrations for data sources, APIs, and services. - Real-time streaming data: Agents access live events instead of batch snapshots. - [Remote MCP](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) support: Standardized tool access across any MCP-compatible server. - Managed infrastructure: Deployment, scaling, and security handled for you. - Low-latency execution: Tools run close to your data. - Integrated secrets management: API keys and credentials stored securely. ## [](#use-cases)Use cases Agentic Data Plane AI agents unlock new capabilities across multiple fields. ### [](#for-ai-agent-developers)For AI agent developers Build agents grounded in real-time data instead of static snapshots. Connect your agent to live order status, inventory levels, and customer history so responses reflect current business state, not stale training data. ### [](#for-application-developers)For application developers Add conversational AI to existing applications without rebuilding your backend. Expose your services as MCP tools and let agents orchestrate complex multi-step workflows through natural language. ### [](#for-streaming-developers)For streaming developers Process every event with AI reasoning at scale. Invoke agents automatically from pipelines for fraud detection, content moderation, or sentiment analysis. No batch jobs, no delayed insights. ## [](#limitations)Limitations - MCP servers must be hosted in Agentic Data Plane - Cross-agent calling between separate agents is not supported. Use internal subagents for delegation within a single agent. ## [](#next-steps)Next steps - [Agentic Data Plane Quickstart for Agent Builders](https://docs.redpanda.com/agentic-data-plane/get-started/agent-builder-quickstart/) - [Understand Agent Concepts](https://docs.redpanda.com/agentic-data-plane/connect/concepts/) - [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) --- # Page 6: Build Agents **URL**: https://docs.redpanda.com/agentic-data-plane/connect/agents.md --- # Build Agents > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Build Agents latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: agents page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: agents.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/agents.adoc description: Understand how AI agents work in the Agentic Data Plane, then create, register, and design them. page-git-created-date: "2026-06-01" page-git-modified-date: "2026-06-18" --- Agents are the workloads that call LLMs and tools through the Agentic Data Plane. Start with how agents work, then create a declarative agent, set up an agent you host yourself, and apply architecture and system-prompt best practices. - [How Agents Work](https://docs.redpanda.com/agentic-data-plane/connect/agents-overview/) Learn how Agentic Data Plane agents use a declarative approach backed by a broad library of prebuilt tools and integrations to replace custom agent code. - [Understand Agent Concepts](https://docs.redpanda.com/agentic-data-plane/connect/concepts/) Understand how declaratively configured agents execute reasoning loops, manage context, invoke tools, and handle errors. - [Connect Agents with A2A](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/) The A2A protocol enables agents to discover and call each other across platforms. Learn how agent cards, authentication, and protocol versioning work in Agentic Data Plane. - [Choose an Agent Architecture](https://docs.redpanda.com/agentic-data-plane/connect/architecture-patterns/) Design maintainable agent systems with single-agent and multi-agent patterns based on domain complexity. - [Write Effective System Prompts](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/) Write system prompts that produce reliable, predictable agent behavior through clear constraints and tool guidance. - [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) Configure a managed Agentic Data Plane agent declaratively on a single create canvas. No Python or JavaScript code required. - [Draw Charts from an Agent](https://docs.redpanda.com/agentic-data-plane/connect/draw-charts/) Make an agent render inline bar and line charts in the Playground by emitting a chart code block that follows the Agentic Data Plane chart contract. - [Set Up a Self-Managed Agent](https://docs.redpanda.com/agentic-data-plane/connect/self-managed-agents/) Register a self-managed agent, issue it a client credential, and route its LLM and tool calls through the AI Gateway so spend, traces, and transcripts attribute back to the agent. - [Trigger Agents](https://docs.redpanda.com/agentic-data-plane/connect/triggers/overview/) Triggers invoke a deployed agent without calling its API directly, from Microsoft Teams or on a schedule. --- # Page 7: Choose an Agent Architecture **URL**: https://docs.redpanda.com/agentic-data-plane/connect/architecture-patterns.md --- # Choose an Agent Architecture > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Choose an Agent Architecture latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: architecture-patterns page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: architecture-patterns.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/architecture-patterns.adoc description: Design maintainable agent systems with single-agent and multi-agent patterns based on domain complexity. page-topic-type: best-practices personas: agent_builder learning-objective-1: Evaluate single-agent versus multi-agent architectures for your use case learning-objective-2: Choose appropriate LLM models based on task requirements learning-objective-3: Apply agent boundary design principles for maintainability page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-02" --- Design agent systems that are maintainable, discoverable, and reliable by choosing the right architecture pattern and applying clear boundary principles. After reading this page, you will be able to: - Evaluate single-agent versus multi-agent architectures for your use case - Choose appropriate LLM models based on task requirements - Apply agent boundary design principles for maintainability ## [](#why-architecture-matters)Why architecture matters Agent architecture determines how you manage complexity as your system grows. The right pattern depends on your domain complexity, organizational structure, and how you expect requirements to evolve. Starting with a simple architecture is tempting, but can lead to unmaintainable systems as complexity increases. Planning for growth with clear boundaries prevents technical debt and costly refactoring later. Warning signs that you need architectural boundaries, not just better prompts: - System prompts exceeding 2000 words - Too many tools for the LLM to select correctly - Multiple teams modifying the same agent - Changes in one domain breaking others Match agent architecture to domain structure: | Domain Characteristics | Architecture | Pros | Cons | | --- | --- | --- | --- | | Single business area, stable requirements | Single agent | Simple to build and maintain, one deployment, lower latency | Limited flexibility, difficult to scale to multi-domain problems | | Multiple business areas, shared infrastructure | Root agent with internal subagents | Separation of concerns, easier debugging, shared resources reduce cost | Single point of failure, subagents share the parent’s credentials and budget | | Cross-organization workflows, independent evolution | External agent-to-agent | Independent deployment and scaling, security isolation, flexible infrastructure | Network latency, authentication complexity, harder to debug across boundaries | Every architecture pattern involves trade-offs. - **Latency versus isolation:** Internal subagents have lower latency because they avoid network calls, but they share a failure domain. External agents have higher latency due to network overhead, but they provide independent failure isolation. - **Shared state versus independence:** Single deployments share provider credentials, budget, and policies but offer less flexibility. Multiple deployments allow independent scaling and updates but add coordination complexity. - **Complexity now versus complexity later:** Starting simple means faster initial development but may require refactoring. Starting structured requires more upfront work but makes the system easier to extend. For foundational concepts on how agents execute and manage complexity, see [Understand Agent Concepts](https://docs.redpanda.com/agentic-data-plane/connect/concepts/). ## [](#single-agent-pattern)Single-agent pattern A single-agent architecture uses one agent with one system prompt and one tool set to handle all requests. This pattern works best for narrow domains with limited scope, single data sources, and tasks that don’t require specialized subsystems. ### [](#when-to-use-single-agents)When to use single agents Use single agents for focused problems that won’t expand significantly. Examples include order lookup agents that retrieve history from a single topic, weather agents that query APIs and return formatted data, and inventory checkers that report stock levels. ### [](#trade-offs)Trade-offs Single agents are simpler to build and maintain. You have one system prompt, one tool set, and one deployment. However, all capabilities must coexist in one agent. Adding features increases complexity rapidly, making single agents difficult to scale to multi-domain problems. > 💡 **TIP** > > You can migrate from a single agent to a root agent with subagents without starting over. Add subagents to an existing agent in Redpanda Agentic Data Plane, then gradually move tools and responsibilities to the new subagents. ## [](#root-agent-with-subagents-pattern)Root agent with subagents pattern A multi-agent architecture uses a root agent that delegates to specialized internal subagents. This pattern works for complex domains spanning multiple areas, multiple data sources with different access patterns, and tasks requiring specialized expertise within one deployment. > 📝 **NOTE** > > Subagents in Agentic Data Plane are internal specialists within a single agent. They share the parent agent’s provider credentials, budget, and policies, but each can have different names, descriptions, system prompts, and MCP tools. By default, a subagent uses the parent’s model and LLM provider, but each subagent can override either or both. ### [](#how-it-works)How it works The root agent interprets user requests and routes them to appropriate subagents. Each subagent owns a specific business area with focused expertise. Subagents access only the MCP tools they need. By default, subagents use the parent agent’s model and LLM provider, but each subagent can override either or both. All subagents share the parent agent’s provider credentials and budget. ### [](#example-e-commerce-platform)Example: E-commerce platform A typical e-commerce agent includes a root agent that interprets requests and delegates to specialists, an order subagent for processing, history, and status updates, an inventory subagent for stock checks and warehouse operations, and a customer subagent for profiles, preferences, and history. By default these subagents use the parent’s model, but each has its own system prompt and tool access, and can override the model or LLM provider when a specialist needs one. ### [](#why-choose-internal-subagents)Why choose internal subagents Internal subagents provide domain isolation, allowing you to update the order subagent without affecting inventory. Debugging is easier because each subagent has narrow scope and fewer potential failure points. All subagents share resources, reducing complexity and cost compared to separate deployments. Use internal subagents when you need domain separation within a single agent deployment. ## [](#external-agent-to-agent-pattern)External agent-to-agent pattern External A2A integration connects agents across organizational boundaries, platforms, or independent systems. > 📝 **NOTE** > > Cross-agent calling between separate Agentic Data Plane agents is not supported. This pattern only applies to connecting Agentic Data Plane agents with external agents you host elsewhere. ### [](#when-to-use-external-a2a)When to use external A2A Use external [Agent2Agent (A2A) protocol](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#agent2agent-a2a-protocol) for multi-organization workflows that coordinate agents across company boundaries, for platform integration connecting Agentic Data Plane agents with agents hosted elsewhere, and when agents require different deployment environments such as GPU clusters, air-gapped networks, or regional constraints. ### [](#how-it-works-2)How it works Agents communicate using the [A2A protocol](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/), a standard HTTP-based protocol for discovery and invocation. Each agent manages its own credentials and access control independently, and can deploy, scale, and update without coordinating with other agents. Agent cards define capabilities without exposing implementation details. ### [](#example-multi-platform-customer-service)Example: Multi-platform customer service A customer service workflow might span multiple platforms: - Agentic Data Plane agent accesses real-time order and inventory data - CRM agent hosted elsewhere manages customer profiles and support tickets - Payment agent from a third party handles transactions in a secure environment Each agent runs on its optimal infrastructure while coordinating through A2A. ### [](#why-choose-external-a2a)Why choose external A2A External A2A lets different teams own and deploy their agents independently, with each agent choosing its own LLM, tools, and infrastructure. Sensitive operations stay in controlled environments with security isolation, and you can add agents incrementally without rewriting existing systems. ### [](#trade-offs-2)Trade-offs External A2A adds network latency on every cross-agent call, and authentication complexity multiplies with each agent requiring credential management. Removing capabilities or changing contracts requires coordination across consuming systems, and debugging requires tracing requests across organizational boundaries. For implementation details on external A2A integration, see [Choose an Integration Pattern](https://docs.redpanda.com/agentic-data-plane/connect/integration-overview/). ## [](#common-anti-patterns)Common anti-patterns Avoid these architecture mistakes that lead to unmaintainable agent systems. ### [](#the-monolithic-prompt)The monolithic prompt A monolithic prompt is a single 3000+ word system prompt covering multiple domains. This pattern fails because: - LLM confusion increases with prompt length - Multiple teams modify the same prompt creating conflicts and unclear ownership - Changes to one domain risk breaking others Split into domain-specific subagents instead. Each subagent gets a focused prompt under 500 words. ### [](#the-tool-explosion)The tool explosion A tool explosion occurs when a single agent has too many tools from every MCP server in the environment. This pattern fails because: - The LLM struggles to choose correctly from large tool sets - Tool descriptions compete for limited prompt space - The agent invokes wrong tools with similar names, wasting iteration budget on selection mistakes Limit tools per agent to 10-15 for optimal performance. Agents with more than 20-25 tools often show degraded tool selection accuracy. Use subagents to partition tools by domain. For tool design patterns, see [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/). ### [](#premature-a2a-splitting)Premature A2A splitting Premature splitting creates three separate A2A agents when all logic could fit in one agent with internal subagents. This pattern fails because: - Network latency affects every cross-agent call - Authentication complexity multiplies with three sets of credentials - Debugging requires correlating logs across systems - You manage three deployments instead of one Start with internal subagents for domain separation. Split to external A2A only when you need organizational boundaries or different infrastructure. ### [](#unbounded-tool-chaining)Unbounded tool chaining Unbounded chaining sets max iterations to 100, returns hundreds of items from tools, and places no constraints on tool call frequency. This pattern fails because: - The context window fills with tool results - Requests time out before completion - Costs spiral with many iterations multiplied by large context - The agent loses track of the original goal For best results: - Design workflows to complete in 20-30 iterations - Return paginated results from tools - Add prompt constraints like "Never call the same tool more than 3 times per request" ## [](#model-selection-guide)Model selection guide Choose models based on task complexity, latency requirements, and cost constraints. Agentic Data Plane displays available models with descriptions when creating agents. ### [](#match-models-to-task-complexity)Match models to task complexity For simple queries, choose cost-effective models such as GPT-5 Mini. For balanced workloads, choose mid-tier models such as Claude Sonnet 4.5 or GPT-5.2. For complex reasoning, choose premium models such as Claude Opus 4.5 or GPT-5.2. ### [](#balance-latency-and-model-size)Balance latency and model size For real-time responses, choose smaller models. Use models optimized for speed, such as Mini or base tiers. For batch processing, optimize for accuracy over speed. Use larger models when users aren’t waiting for results. ### [](#optimize-for-cost-and-volume)Optimize for cost and volume For high volume, use cost-effective models. Smaller tiers reduce costs while maintaining acceptable quality. For critical accuracy, use premium models. Higher costs are justified when errors are costly. ### [](#model-provider-documentation)Model provider documentation For complete model specifications, capabilities, and pricing: - [OpenAI Models](https://platform.openai.com/docs/models) - [Anthropic Claude Models](https://docs.anthropic.com/claude/docs/models-overview) - [Google Gemini Models](https://ai.google.dev/gemini-api/docs/models) - [AWS Bedrock Models](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) ## [](#design-principles)Design principles Follow these principles to create maintainable agent systems. ### [](#explicit-agent-boundaries)Explicit agent boundaries Each agent should have clear scope and responsibilities. Define scope explicitly in the system prompt, assign a specific tool set for the agent’s domain, and specify well-defined inputs and outputs. Do not create agents with overlapping responsibilities. Overlapping domains create confusion about which agent handles which requests. ### [](#tool-scoping-per-agent)Tool scoping per agent Assign tools to the agent that needs them. Don’t give all agents access to all tools. Limit tool access based on agent purpose. Tool scoping reduces misuse risk and makes debugging easier. ### [](#error-handling-and-fallbacks)Error handling and fallbacks Design agents to handle failures gracefully. Use retry logic for transient failures like network timeouts. Report permanent failures like invalid parameters immediately. Provide clear error messages to users. Log errors for debugging. ## [](#next-steps)Next steps - [Choose an Integration Pattern](https://docs.redpanda.com/agentic-data-plane/connect/integration-overview/) - [Connect Agents with A2A](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/) - [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) --- # Page 8: Set Up Authentication **URL**: https://docs.redpanda.com/agentic-data-plane/connect/authentication.md --- # Set Up Authentication > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Set Up Authentication latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: authentication page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: authentication.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/authentication.adoc description: Configure OAuth providers, user-delegated OAuth, and client connections so agents and tools authenticate securely. page-git-created-date: "2026-06-01" page-git-modified-date: "2026-07-30" --- Agents and tools authenticate through OAuth. Enable user-delegated access so agents act as the signed-in user, register an OAuth provider when you want to manage one yourself, and connect remote MCP clients. - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) Register an OAuth provider in Agentic Data Plane so MCP servers can authenticate users (or service accounts) against an upstream system like Slack, Jira, GitHub, or Salesforce. - [Configure User-Delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) Have each end-user authenticate against the MCP server's upstream system with their own credentials. Redpanda stores their token in the vault and injects it at call time. - [Set Up GitHub OAuth Provider and MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/github-oauth-tutorial/) Complete walkthrough for configuring GitHub as an OAuth provider and creating a user-delegated GitHub MCP server. - [Connect Remote MCP Clients](https://docs.redpanda.com/agentic-data-plane/connect/remote-mcp-clients/) Connect external MCP clients to MCP servers in AI Gateway using client metadata documents, dynamic client registration, or manual registration. --- # Page 9: Run Claude Code and Codex through AI Gateway **URL**: https://docs.redpanda.com/agentic-data-plane/connect/coding-agents.md --- # Run Claude Code and Codex through AI Gateway > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Run Claude Code and Codex through AI Gateway latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: coding-agents page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: coding-agents.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/coding-agents.adoc description: Launch Claude Code or Codex with rpk ai run, routing their model traffic through a managed, enterprise-passthrough, or AWS Bedrock Agentic Data Plane provider. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Launch Claude Code through an Agentic Data Plane Anthropic or AWS Bedrock provider with rpk ai run claude learning-objective-2: Launch Codex through an Agentic Data Plane OpenAI provider with rpk ai run codex learning-objective-3: Choose between a managed (API-key) provider and an enterprise passthrough (subscription-seat) provider for Claude Code page-git-created-date: "2026-07-01" page-git-modified-date: "2026-08-10" --- Claude Code and Codex are command-line coding agents. The [`rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) command launches either one with its model traffic routed through an AI Gateway provider, reusing your `rpk ai` sign-in so you don’t set base URLs or mint tokens by hand. Your team’s coding-agent calls then flow through Agentic Data Plane: provider credentials stay in the dataplane secret store, usage rolls up on the **Cost & Usage** page, and no provider key or session token is written to disk. After completing this guide, you will be able to: - Launch Claude Code through an Agentic Data Plane Anthropic or AWS Bedrock provider with `rpk ai run claude` - Launch Codex through an Agentic Data Plane OpenAI provider with `rpk ai run codex` - Choose between a managed (API-key) provider and an enterprise passthrough (subscription-seat) provider for Claude Code ![Request flow from Claude Code or Codex through rpk ai run and AI Gateway to a compatible LLM provider. The coding agent receives model responses while provider credentials remain in the Agentic Data Plane secret store and usage flows to Cost and Usage.](https://docs.redpanda.com/agentic-data-plane/connect/_images/coding-agent-request-flow.svg) Figure 1. `rpk ai run` routes coding-agent model traffic through AI Gateway ## [](#prerequisites)Prerequisites - The `rpk ai` CLI, installed and signed in to the Agentic Data Plane environment whose gateway you want to target. See [Use the Agentic Data Plane CLI](https://docs.redpanda.com/agentic-data-plane/cli/). The `rpk ai run` command uses the credentials from `rpk ai auth login`, not a `rpk cloud` session. - An enabled [large language model (LLM)](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#large-language-model-llm) provider of the matching type. Claude Code needs an Anthropic or AWS Bedrock provider; Codex needs an OpenAI or OpenAI-compatible provider. To create one, see [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/). - The coding agent installed on your workstation: - Claude Code. See [Anthropic’s Claude Code documentation](https://code.claude.com/docs). - Codex. See [OpenAI’s Codex documentation](https://github.com/openai/codex). The `rpk ai run codex` command needs a recent Codex version and tells you when yours is too old. - A Redpanda service account or user with permission to invoke the provider (`dataplane_adp_llmprovider_invoke`). See [LLM provider permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#llm-provider-permissions). To let `rpk ai run claude` read the provider and auto-detect its type and auth mode, also grant `dataplane_adp_llmprovider_get`; without read access, pass `--passthrough` for a passthrough provider or `--bedrock` for a Bedrock provider. ## [](#run-claude-code)Run Claude Code Launch Claude Code with its traffic routed through an Anthropic provider: ```bash rpk ai run claude -L -m ``` In this command, `` is the name of your Anthropic provider (the segment after `/providers/` in its **Proxy URL**), and `` is a model the provider allows. The flags work as follows: - `-L`, `--llmprovider`: The provider to route through. Required, and it must be an Anthropic or Bedrock provider. - `-m`, `--model`: The model to use. Omit it to let Claude Code pick its default. Flags before a literal `--` configure `rpk ai run` itself. Everything after `--` is passed straight through to Claude Code, so you can set any of its own flags. For example, to start Claude Code in plan mode: ```bash rpk ai run claude -L -m claude-sonnet-4-6 -- --permission-mode plan ``` Claude Code starts in your real configuration home, so your workspace trust, onboarding, theme, and Model Context Protocol (MCP) servers all apply, and nothing is written into `~/.claude`. ### [](#choose-managed-or-enterprise-passthrough)Choose managed or enterprise passthrough For an Anthropic provider, the `rpk ai run claude` command reads its **Auth passthrough** setting and picks one of two auth modes. The choice determines who pays for the tokens. Managed (API key) The provider stores an Anthropic API key in the dataplane secret store, shown as **API key reference** on its **Connection** card. The gateway authenticates each request with your Redpanda token, injects the stored key, and forwards the call to Anthropic. Tokens are billed as API usage against the account that owns that key, and per-model spend appears on the provider’s **Overview** tab. You need no Anthropic credential of your own. Enterprise passthrough (subscription) The provider has **Auth passthrough** enabled and stores no API key. Claude Code signs in with your own Claude subscription (Max, Team, or Enterprise), and `rpk ai run claude` forwards that subscription login to Anthropic unchanged. Tokens are billed against your subscription seat, not as per-token API usage. Agentic Data Plane authenticates your organization with a separate gateway credential that `rpk ai run` sets for you, so the call is still observed on the **Cost & Usage** page while the subscription bears the cost. > 📝 **NOTE** > > When `rpk ai run claude` cannot read the provider (invoke-only access), it cannot detect the provider’s type or auth mode, and it launches in managed Anthropic mode by default. Pass `--passthrough` to force passthrough for a subscription provider, or pass `--bedrock` for a Bedrock provider. When the provider is readable, its own type and setting win: the launch ignores a contradicting `--passthrough` on a managed Anthropic provider, or a contradicting `--bedrock` on an Anthropic provider, with a warning. ### [](#use-an-aws-bedrock-provider)Use an AWS Bedrock provider Claude Code can also route through a Bedrock provider, running in its native Bedrock mode: ```bash rpk ai run claude -L -m us.anthropic.claude-sonnet-4-6 ``` In this command, `` is the name of your Bedrock provider. For `-m`, pass an inference-profile ID the provider allows: a model identifier with a region prefix such as `us.`, `eu.`, `apac.`, or `global.`. Bedrock requires an inference profile for Claude 4.6 and later models; older models also accept bare foundation-model IDs. For selection guidance, see [AWS Bedrock: Inference profiles and IAM](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/#bedrock-inference-profiles). AI Gateway signs each upstream call with the AWS credentials stored on the provider, so no AWS keys reach your machine. The session authenticates to the gateway with your Redpanda token, exactly like a managed Anthropic provider, and the token refreshes for the whole session. Enterprise passthrough does not apply to Bedrock: a Claude subscription has no Bedrock analog, so `--passthrough` fails with an error. In Bedrock mode, Claude Code runs background tasks on a Haiku-class model by default. If the provider’s allowlist does not include one, set `ANTHROPIC_SMALL_FAST_MODEL` to an allowlisted inference-profile ID before you launch. ## [](#run-codex)Run Codex Launch Codex with its traffic routed through an OpenAI or OpenAI-compatible provider: ```bash rpk ai run codex -L -m ``` In this command, `` is the name of your OpenAI or OpenAI-compatible provider, and `` is a model the provider allows. Only OpenAI and OpenAI-compatible providers work, because Codex speaks the OpenAI Responses API. Codex also takes a reasoning-effort flag, `-e` (`--effort`), which accepts `minimal`, `low`, `medium`, or `high`. Omit it to let Codex use its default. As with Claude Code, everything after a literal `--` is passed straight through to Codex. For example, to skip Codex’s approval prompts: ```bash rpk ai run codex -L -m gpt-5.3-codex -e high -- --ask-for-approval never ``` Codex runs against a throwaway configuration home, so your own `~/.codex` is never read or modified. The launch directory is auto-trusted under a `workspace-write` sandbox, so Codex does not prompt for trust on every run. Pass `--no-auto-trust` to keep Codex’s normal first-run trust prompt, for example, when you launch inside a freshly cloned repository. Codex has no passthrough mode. Every Codex session authenticates to the gateway with your Redpanda token, and the gateway injects the provider’s stored API key when one is configured. ## [](#make-it-a-shortcut)Make it a shortcut If you launch the same agent and provider often, define a shell alias so the launch becomes a short command. Anything after `--` is passed to the agent, so you can pin your own agent flags in the alias too. For example, to launch Claude Code through your provider with your preferred model every time: ### Bash or Zsh Add the alias to `~/.bashrc` or `~/.zshrc`: ```bash alias claude-gw='rpk ai run claude -L -m claude-sonnet-4-6' ``` ### fish Define a saved alias (fish persists it as a function): ```fish alias --save claude-gw 'rpk ai run claude -L -m claude-sonnet-4-6' ``` ## [](#attach-agentic-data-plane-hosted-mcp-servers-optional)Attach Agentic Data Plane-hosted MCP servers (optional) Claude Code can call MCP servers for tool access. To use the MCP servers you host in Agentic Data Plane (managed catalog types, self-managed proxied servers, or both), register each one with Claude Code: ```bash claude mcp add https://aigw..clusters.rdpa.co/mcp/v1/ ``` In this URL, `` is your dataplane’s cluster identifier, and `` is the MCP server’s name in Agentic Data Plane. For OAuth-protected MCP servers (most managed types), Claude Code prompts you to complete the consent flow on first use. Agentic Data Plane stores the resulting token in the per-user [token vault](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/), so later invocations reuse it. If a server exposes a large tool catalog, turn on [code mode](https://docs.redpanda.com/agentic-data-plane/gateway/code-mode/) and point Claude Code at the server’s code-mode endpoint to cut the token cost of loading every tool definition. ## [](#observe-usage)Observe usage Open **Cost & Usage** under **Governance** in the sidebar, then filter by your provider. Within a few seconds, the requests from your coding-agent session appear, and the provider’s **Overview** tab breaks spend down per model. Ad-hoc `rpk ai run` sessions are not registered agents, so they do not appear in the per-agent [Transcripts view](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/). Transcripts cover agents you create in Agentic Data Plane. ## [](#configure-the-agent-by-hand)Configure the agent by hand The `rpk ai run` command is for interactive command-line work. For CI runners, headless jobs, and application code, authenticate with the OIDC `client_credentials` grant and set the agent’s base URL and token yourself. For the full flow, with the Proxy URL anatomy, the token mint, and SDK examples, see [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/). For a managed Anthropic provider, set the variables and launch the agent directly: ```bash export ANTHROPIC_BASE_URL="https://aigw..clusters.rdpa.co/llm/v1/providers/" export ANTHROPIC_AUTH_TOKEN="" claude ``` In this example, `` is an access token minted with the `client_credentials` grant. It has a short lifetime, and AI Gateway does not refresh it for you, so re-mint it when it expires. The `rpk ai run` command avoids this by refreshing the token for the whole session. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | --llmprovider is required | The rpk ai run command needs the provider to route through. Pass -L , using the provider’s exact name. | | Provider is the wrong type for the agent | Claude Code needs an Anthropic or Bedrock provider, and Codex needs an OpenAI or OpenAI-compatible provider. Confirm the Type on the provider’s Connection card, and pass a provider of the matching type to -L. An older rpk ai plugin also rejects Bedrock providers for Claude Code; update it with rpk ai upgrade. | | Provider is disabled | The provider’s Status is not Active. Enable it with rpk ai llm-provider update --enabled, or from the provider detail page. | | no usable gateway token | The cached rpk ai credentials are missing or expired. Run rpk ai auth login to refresh them, then relaunch. The error’s rpai auth login hint refers to the same sign-in. | | The session hangs, or the agent reports that the model is not allowed for the provider (HTTP 403) | The model you passed to -m is not in the provider’s allowlist. Claude Code retries the rejected requests silently, so the session can appear to hang; when rpk ai run claude can read the provider, the launch warns you and names the allowed models. Open the provider detail page, confirm the model row appears, and pass that exact identifier. For a Bedrock provider, that identifier is an inference-profile ID. | | Missing claude or codex binary on the PATH | The agent binary is not installed or not on your PATH. Install it (see Prerequisites), then relaunch. | | Sign-in required before rpk ai starts | Run rpk ai auth login to sign in and select an Agentic Data Plane environment. | | Unknown command error from rpk ai run | Your rpk ai plugin predates rpk ai run. Update it with rpk ai upgrade, then relaunch. | | Passthrough session ends with an auth error partway through | A passthrough gateway token cannot refresh mid-session. When rpk ai run claude warns that the token expires soon, run rpk ai auth login for a full-length session before relaunching. | | MCP tool calls return OAuthConnectionRequired | You have not completed the consent flow for that MCP server. See User-delegated OAuth; Claude Code surfaces the authorization URL in the error so you can finish the handshake. | ## [](#next-steps)Next steps - [Use the Agentic Data Plane CLI](https://docs.redpanda.com/agentic-data-plane/cli/) - [Configure an LLM Provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/) - [Connect Your App to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/) --- # Page 10: Understand Agent Concepts **URL**: https://docs.redpanda.com/agentic-data-plane/connect/concepts.md --- # Understand Agent Concepts > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Understand Agent Concepts latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: concepts page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: concepts.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/concepts.adoc description: Understand how declaratively configured agents execute reasoning loops, manage context, invoke tools, and handle errors. page-topic-type: concepts personas: agent_builder learning-objective-1: Explain how agents execute reasoning loops and make tool invocation decisions learning-objective-2: Describe how agents manage context and state across interactions learning-objective-3: Identify error handling strategies for agent failures page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-24" --- When you configure an agent’s LLM, system prompt, and tools, Redpanda Agentic Data Plane manages execution through a reasoning loop: analyze context, invoke a tool, process the result, and repeat until the task completes. Each iteration adds tokens to the context window and runs against your iteration budget, so execution decisions directly shape cost, latency, and reliability. Understanding this model gives you the foundation to set effective iteration limits, design lean tool sets, and diagnose failures before they affect your users. After reading this page, you will be able to: - Explain how agents execute reasoning loops and make tool invocation decisions - Describe how agents manage context and state across interactions - Identify error handling strategies for agent failures ## [](#agent-execution-model)Agent execution model Every agent request follows a reasoning loop. The agent doesn’t execute all tool calls at once. Instead, it makes decisions iteratively. ### [](#the-reasoning-loop)The reasoning loop The following diagram shows how agents process requests through iterative reasoning: ![Diagram showing the agent reasoning loop: User Request flows to LLM Receives Context](https://docs.redpanda.com/agentic-data-plane/_images/agent-reasoning-loop.png) Figure 1. Agent reasoning loop with tool integration When an agent receives a request: 1. The LLM receives the context, including system prompt, conversation history, user request, and previous tool results. 2. The LLM chooses to invoke a tool, requests more information, or responds to user. 3. The tool runs and returns results if invoked. 4. The tool’s results are added to conversation history. 5. The LLM reasons again with an expanded context. The loop continues until one of these conditions is met: ![Diagram showing exit conditions: Task Complete returns response](https://docs.redpanda.com/agentic-data-plane/_images/agent-exit-conditions.png) Figure 2. Reasoning loop exit conditions - Agent completes the task and responds to the user - Agent reaches max iterations limit - Agent encounters an unrecoverable error > 📝 **NOTE** > > If the agent encounters an unrecoverable error on the first iteration, it returns an error immediately. Unrecoverable errors include authentication failures, invalid tool configurations, or LLM API failures. ### [](#why-iterations-matter)Why iterations matter Each iteration includes these phases: 1. **LLM reasoning**: The model processes the growing context to decide the next action. 2. **Tool invocation**: If the agent decides to call a tool, execution happens and waits for results. 3. **Context expansion**: Tool results are added to the conversation history for the next iteration. With higher iteration limits, agents can complete complex tasks but can cost more and take longer. With lower iteration limits, agents can respond faster and are cheaper but may fail on complex requests. #### [](#cost-calculation)Cost calculation Calculate the approximate cost per request by estimating average context tokens per iteration: Cost per request = (iterations x context tokens x model price per token) Example with 30 iterations at $0.000002 per token: Iteration 1: 500 tokens x $0.000002 = $0.001 Iteration 15: 2000 tokens x $0.000002 = $0.004 Iteration 30: 4000 tokens x $0.000002 = $0.008 Total: ~$0.013 per request Actual costs vary based on: - Tool result sizes (large results increase context) - Model pricing (varies by provider and model tier) - Task complexity (determines iteration count) Setting max iterations creates a cost/capability trade-off: | Limit | Range | Use Case | Cost | | --- | --- | --- | --- | | Low | 10-20 | Simple queries, single tool calls | Cost-effective | | Medium | 30-50 | Multi-step workflows, tool chaining | Balanced | | High | 50-100 | Complex analysis, exploratory tasks | Higher | Iteration limits prevent runaway costs when agents encounter complex or ambiguous requests. ## [](#mcp-tool-invocation-patterns)MCP tool invocation patterns MCP tools extend agent capabilities beyond text generation. Understanding when and how tools execute helps you design effective tool sets. ### [](#synchronous-tool-execution)Synchronous tool execution In Redpanda Agentic Data Plane, tool calls block the agent. When the agent decides to invoke a tool, it pauses and waits while the tool executes (querying a database, calling an API, or processing data). When the tool returns its result, the agent resumes reasoning. This synchronous model means latency adds up across multiple tool calls, the agent sees tool results sequentially rather than in parallel, and long-running tools can delay or fail agent requests due to timeouts. ### [](#tool-selection-decisions)Tool selection decisions The LLM decides which tool to invoke based on system prompt guidance (such as "Use get\_orders when customer asks about history"), tool descriptions from the MCP schema that define parameters and purpose, and conversation context where previous tool results influence the next tool choice. Agents can invoke the same tool multiple times with different parameters if the task requires it. ### [](#tool-chaining)Tool chaining Agents chain tools when one tool’s output feeds another tool’s input. For example, an agent might first call `get_customer_info(customer_id)` to retrieve details, then use that data to call `get_order_history(customer_email)`. Tool chaining requires sufficient max iterations because each step in the chain consumes one iteration. ### [](#tool-granularity-considerations)Tool granularity considerations Tool design affects agent behavior. Coarse-grained tools that do many things result in fewer tool calls but less flexibility and more complex implementation. Fine-grained tools that each do one thing require more tool calls but offer higher composability and simpler implementation. Choose granularity based on how often you’ll reuse tool logic across workflows, whether intermediate results help with debugging, and how much control you want over tool invocation order. For tool design guidance, see [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/). ## [](#context-and-state-management)Context and state management Agents handle two types of information: conversation context (what’s been discussed) and state (persistent data across sessions). ### [](#conversation-context)Conversation context The agent’s context includes the system prompt (always present), user messages, agent responses, tool invocation requests, and tool results. As the conversation progresses, context grows. Each tool result adds tokens to the context window, which the LLM uses for reasoning in subsequent iterations. ### [](#context-window-limits)Context window limits LLM context windows limit how much history fits. Small models support 8K-32K tokens, medium models support 32K-128K tokens, and large models support 128K-1M+ tokens. When context exceeds the limit, the oldest tool results get truncated, the agent loses access to early conversation details, and may ask for information it already retrieved. Design workflows to complete within context limits. Avoid unbounded tool chaining. ## [](#service-account-authorization)Service account authorization When you create an AI agent, Agentic Data Plane provisions a service account for it automatically. The service account is the agent’s own identity. You don’t create it, and you don’t manage it separately from the agent. - **Client ID**: Derived from the agent’s name, in the form `serviceaccounts/`. The principal is `@iam.serviceaccounts.`, where `` is your environment’s DNS zone. For example, an agent named `my-agent` gets the client ID `serviceaccounts/my-agent`. - **Authorized scope**: The credentials authenticate the agent’s LLM and MCP tool calls through AI Gateway, and they attribute spend, tokens, latency, and traces back to the agent. They also give you a single point of revocation, because revoking a leaked client secret ends the agent’s access with it. Use these credentials only inside the agent they belong to. A caller that invokes the agent from outside authenticates as its own principal, not as the agent. What the agent may do in Agentic Data Plane comes from [access policies](https://docs.redpanda.com/agentic-data-plane/control/access-policies/), not from the service account itself. For an agent, author those on its **Permissions** tab, where the principal is locked to the agent’s service account. For the permission names behind each action, see [Roles and Permissions Reference](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/). ### [](#manage-agent-credentials)Manage agent credentials On a self-managed agent, pair the client ID with a client secret to obtain access tokens. Manage secrets on the agent’s **Credentials** tab, or with the [`rpk ai agent credential`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-credential/) commands. To issue a secret, click **Create secret** and optionally name it. Copy the secret before you dismiss the dialog, because it’s shown once and can’t be retrieved again. Each secret in the list shows: | Column | Description | | --- | --- | | Name | The label you gave the secret when you created it. | | Created | When the secret was issued. | | Expires | 90 days after creation. | More than one secret can be active at a time, so you can roll credentials over without downtime: create the new secret, deploy it, then revoke the old one. To revoke a secret, click **Revoke** on its row. > 📝 **NOTE** > > Revoking a secret immediately breaks anything still using it. The agent’s service account and client ID stay in place, and only that secret stops working. ## [](#next-steps)Next steps - [Choose an Agent Architecture](https://docs.redpanda.com/agentic-data-plane/connect/architecture-patterns/) - [Agentic Data Plane Quickstart for Agent Builders](https://docs.redpanda.com/agentic-data-plane/get-started/agent-builder-quickstart/) - [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) --- # Page 11: Create an Agent **URL**: https://docs.redpanda.com/agentic-data-plane/connect/create-agent.md --- # Create an Agent > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Create an Agent latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: create-agent page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: create-agent.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/create-agent.adoc description: Configure a managed Agentic Data Plane agent declaratively on a single create canvas. No Python or JavaScript code required. page-topic-type: how-to personas: agent_builder learning-objective-1: Create a managed Agentic Data Plane agent through the create canvas learning-objective-2: Configure an LLM provider, model, and tools for an agent learning-objective-3: Connect to and test a running agent page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-10" --- Create a new [AI agent](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#ai-agent) declaratively through Redpanda Agentic Data Plane. No Python or JavaScript code required. This guide walks through the managed create canvas section by section, then covers how to connect to and test the running agent. After reading this page, you will be able to: - Create a managed Agentic Data Plane agent through the create canvas - Configure an LLM provider, model, and tools for an agent - Connect to and test a running agent ## [](#prerequisites)Prerequisites - At least one [LLM provider configured](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/) in Agentic Data Plane. - Optional: One or more [MCP servers](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) registered in Agentic Data Plane if you want the agent to call tools. - Optional: A system prompt prepared in advance (see [System prompt best practices](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/)). ## [](#open-the-create-canvas)Open the create canvas 1. Open **Agents** in the sidebar. 2. Click **Create agent**. 3. Choose how the agent runs. Click **Redpanda manages it**, so Redpanda deploys, runs, and observes the agent for you. (To run an agent you host yourself, see [Set Up a Self-Managed Agent](https://docs.redpanda.com/agentic-data-plane/connect/self-managed-agents/).) ![The runtime choice in the create-agent flow, with a Redpanda manages it card for the managed runtime and an I host it myself card for self-managed agents](https://docs.redpanda.com/agentic-data-plane/shared/_images/create-agent-runtime-choice.png) Agentic Data Plane opens the **New managed agent** canvas: a single page with sections for **Identity**, **Model**, **Instructions**, and **Tools**, plus a collapsible **Advanced** area for subagents and tags. Everything on the canvas is editable later from the agent’s **Overview** tab. Required fields are marked with an asterisk; the **Create agent** button stays disabled until you provide them, with helper text explaining what’s still missing. ## [](#identity)Identity In the **Identity** section, name the agent and optionally describe it. 1. Enter a **Name**. Required. Shown in the agent registry list and the detail header (for example, `Customer Support Agent`). Agentic Data Plane derives the agent’s resource ID from this name when you create the agent; you don’t enter the ID directly. The derived ID is a lowercase slug that starts with a letter, ends with a letter or digit, and can contain letters, digits, and hyphens (up to 63 characters). The ID is used in URLs and CLI commands and can’t be changed after creation. > 💡 **TIP** > > Click **Suggest a name** to generate a placeholder you can edit. 2. Optionally, add a **Description**. An internal note shown on the agent’s detail page. This is not the system prompt; write that under **Instructions**. ## [](#model)Model In the **Model** section, choose the [large language model (LLM)](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#large-language-model-llm) the agent uses to interpret user intent and decide which tools to invoke. The picker is a single searchable list of every model your configured LLM providers expose (for example, `us.anthropic.claude-haiku-4-5-20251001-v1:0`): search by name, select a model, and Agentic Data Plane routes to the provider that serves it. When the same model is served by more than one provider, the picker shows the provider next to the model so you can choose which one to use. To use a model the picker doesn’t list, select a provider’s **Custom model ID** entry and type the identifier. Calls to the model are proxied through the [AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/overview/). To add a new provider, see [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/). For model selection guidance, see [Model selection guide](https://docs.redpanda.com/agentic-data-plane/connect/architecture-patterns/#model-selection-guide). For external model specifications and pricing: - [OpenAI models](https://platform.openai.com/docs/models) - [Anthropic Claude models](https://docs.anthropic.com/claude/docs/models-overview) - [Google Gemini models](https://ai.google.dev/gemini-api/docs/models) - [AWS Bedrock models](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) > 📝 **NOTE** > > **Max iterations** is not on the create canvas. It’s the upper bound on agent reasoning loops per request, and you set it after creation from the agent’s **Overview** tab, in the **Model & runtime** section. Leave it unset (or `0`) to use the runtime default of 100. Each iteration consumes tokens and adds latency, so tune it to task complexity: simple queries (10-20), balanced workflows (20-40), complex analysis (40-100). For an AWS Bedrock provider, Agentic Data Plane validates the model when you create or update the agent. A model ID that isn’t a valid Bedrock model for the provider’s region is rejected at save time, with an error that points at the offending model field, instead of being accepted and then failing later when the agent deploys. A common mistake is the bare foundation-model ID: Claude 4.6 and later require the full inference-profile ID (for example, `us.anthropic.claude-opus-4-7` rather than `claude-opus-4-7`). To use a model the picker doesn’t list, select the provider’s **Custom model ID** entry and enter the full inference-profile ID. The same check applies to each subagent’s model override. See [AWS Bedrock: Inference profiles and IAM](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/#bedrock-inference-profiles). ## [](#instructions)Instructions In the **Instructions** section, write the system prompt that defines the agent’s role, responsibilities, constraints, and output format. The system prompt is optional but strongly recommended; when set, it’s sent on every invocation as the first message. To start from a template, select one of the starter cards above the editor. Each card fills in a complete system prompt that you can then edit. The field is a Markdown editor with three modes: - **Live**: The default. Styles the formatted Markdown as you type and reveals the raw syntax for the construct you’re editing. - **Markdown**: Always shows the exact source. - **Preview**: Renders the formatted result. In either editing mode, type the prompt directly and use the formatting toolbar, or select the upload icon to import a Markdown file. To edit in a larger surface, click **Expand editor**. A typical prompt defines: - Agent role and responsibilities - Available tools (matches the servers you select in the **Tools** section) - Safety rules and constraints - Expected output format Example structure: ```text You are an [agent role]. Responsibilities: - [Task 1] - [Task 2] Available tools: - [tool_name]: [description] Never: - [Constraint 1] - [Constraint 2] Response format: - [Format guideline] ``` For full guidance on writing effective prompts, see [System prompt best practices](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/). ## [](#tools)Tools In the **Tools** section, grant the agent access to the Model Context Protocol (MCP) servers that expose tools to it. This section is optional, and you can change the list at any time after creation. 1. In the server list, select the checkbox of each server you want the agent to call. If your organization runs many MCP servers, a **Search MCP servers** box appears above the list to help you find them. To create a new server instead of attaching an existing one, click **Add MCP server**, which opens the server-creation flow in a new tab. 2. The agent discovers each selected server’s tools at runtime; you don’t pre-select individual tools. The agent calls them based on the LLM’s interpretation of the system prompt and the user request. Keep the system prompt aligned with the servers you select so the model knows what’s available. > 💡 **TIP** > > Apply the principle of least privilege. Connect only the servers the agent needs. An agent can reference at most 32 MCP servers in total, counting the servers on the root agent plus every subagent’s servers. The limit counts references, not distinct servers, so a server referenced by both the root agent and a subagent counts twice. If the total exceeds 32, you can’t save the agent. For registering MCP servers, see [Create an MCP server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/). ## [](#advanced-subagents-and-tags)Advanced: subagents and tags Expand the **Advanced** area to add subagents and tags. Both are optional. ### [](#subagents)Subagents Subagents are internal specialists within the same agent. Each subagent has its own name, delegation hint, system prompt, and MCP tools. By default, a subagent inherits the parent agent’s model and LLM provider, but you can override both per subagent. All subagents share the parent agent’s provider credentials, gateway endpoint, and execution settings. The root agent orchestrates and delegates work to the appropriate subagent based on the request. To add a specialist, click **Add subagent** (or **Add a subagent**) and configure it in the panel that opens: - **Name**: Required. Must start with a lowercase letter, contain only lowercase letters, digits, and hyphens, and end with a letter or digit (for example, `researcher`). The name must be unique among the agent’s subagents. - **When should the parent use it?**: Required. The delegation hint the parent reads to decide when to route a task to this subagent. Be specific about inputs, outputs, and use cases. - **Model**: Optional. Defaults to the parent agent’s model. A subagent always uses the parent agent’s LLM provider, so you override only the model, choosing from the models that provider serves. Use **Reset to inherited** to go back to the parent’s model. - **Instructions**: Required. Domain-specific system prompt for what the subagent does. - **Tools**: Optional. Select the MCP servers this subagent can access. Click **Add subagent** to save it, or **Cancel** to discard. To keep the agent flat, leave the list empty. For multi-agent design patterns, see [Agent architecture patterns](https://docs.redpanda.com/agentic-data-plane/connect/architecture-patterns/). ### [](#tags)Tags Add **Tags** as key/value pairs to organize and filter agents in the registry and to break down [Cost & Usage](https://docs.redpanda.com/agentic-data-plane/control/budgets/) by team, environment, and more. ## [](#create-the-agent)Create the agent 1. Review the canvas. The **Create agent** button is disabled until you enter a name and pick a model; the helper text next to it tells you which is still missing. 2. Click **Create agent**. 3. Wait for the agent to reach the **Running** state. When the agent is running, open its detail page. A managed agent has these tabs: - **Overview**: The agent’s full configuration, organized into sections that you edit and save one at a time. The **Agent** section holds the display name, description, and tags (the agent ID is fixed). The **Model & runtime** section holds the LLM provider, model, and max iterations, along with the runtime status and endpoint. The **System prompt**, **MCP servers**, and **Subagents** sections hold the instructions, attached servers, and subagents. - **Triggers**: Schedules and event sources that invoke the agent. See [Trigger Agents](https://docs.redpanda.com/agentic-data-plane/connect/triggers/overview/). - **Playground**: An interactive test surface. See [Test your agent](#test-your-agent). - **Cost & Usage**: Spend, tokens, and latency for the agent. - **Transcripts**: A record of every conversation against the agent. - **Permissions**: The access policies that apply to the agent as a principal. See [Manage Access Policies](https://docs.redpanda.com/agentic-data-plane/control/access-policies/). ## [](#connect-to-the-agent)Connect to the agent A running managed agent exposes an [A2A](https://a2a-protocol.org/) endpoint that you can call programmatically or integrate with external systems. - **A2A endpoint**: The URL where the agent receives messages, provisioned after the agent starts. It is published in the agent’s card at `https:///.well-known/agent-card.json`, and you can fetch it with the [`rpk ai agent a2a card`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-a2a-card/) command. - **Authentication**: The agent card is public, but every other request to the endpoint requires an access token, sent as an `Authorization: Bearer` header. The caller also needs permission to invoke the agent. See [A2A runtime permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#a2a-runtime-permissions). - **Code examples**: Call the agent with an official A2A client SDK (Go, Node.js, Python, and Java), with `curl`, or with the [`rpk ai agent a2a send`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-a2a-send/) command. For more about calling agents and integrating them with other systems, see [Choose an Integration Pattern](https://docs.redpanda.com/agentic-data-plane/connect/integration-overview/). ## [](#update-a-managed-agent)Update a managed agent Change a managed agent’s configuration at any time after you create it, either in Agentic Data Plane or with the [`rpk ai agent update`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-update/) command. You can edit settings such as the model, system prompt, tools, and subagents. The agent ID is fixed and can’t change. Updates roll out without interrupting the agent. Redpanda starts the new version and waits for it to become ready before it stops the old one, so in-flight and new requests keep reaching a running instance throughout the change. ## [](#test-your-agent)Test your agent Two tabs on the agent detail page support testing and observability: - **Playground**: Send test prompts interactively and inspect each step of the agent’s reasoning, tool calls, and responses. Use Playground during development and tuning. The composer shows the agent’s provider and model as read-only, so a test run always uses the agent’s saved configuration. - **Transcripts**: Records every conversation against the agent (prompt, tool calls, tool outputs, final response). Use transcripts to audit production behavior. To test the agent in Playground: 1. Open the agent’s **Playground** tab. 2. Enter a test prompt. 3. Verify the agent: - Selects appropriate tools - Follows the system prompt’s constraints - Returns the expected output format 4. Iterate on the system prompt, MCP tool selection, or model choice as needed. For detailed observability strategies, see [Monitor Agent Activity](https://docs.redpanda.com/agentic-data-plane/monitor/monitor-agents/). ## [](#example-configurations)Example configurations ### [](#simple-query-agent)Simple query agent - **Model**: GPT-5 Mini (fast, cost-effective) - **Tools**: Single MCP server exposing a `get_orders` tool - **Use case**: Customer order lookups ### [](#complex-analytics-agent)Complex analytics agent - **Model**: Claude Sonnet 4.5 (balanced) - **Tools**: Multiple servers for data query, aggregation, and formatting - **Use case**: Multi-step data analysis ### [](#multi-agent-orchestrator)Multi-agent orchestrator - **Model**: Claude Opus 4.5 (advanced reasoning) - **Tools**: Tools the root agent delegates to subagents - **Subagents**: `order-agent`, `inventory-agent`, `customer-agent` - **Use case**: E-commerce operations ## [](#next-steps)Next steps - [Trigger Agents](https://docs.redpanda.com/agentic-data-plane/connect/triggers/overview/) - [Choose an Integration Pattern](https://docs.redpanda.com/agentic-data-plane/connect/integration-overview/) - [Write Effective System Prompts](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/) --- # Page 12: Create an MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/create-server.md --- # Create an MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Create an MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: create-server page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: create-server.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/create-server.adoc description: Create an MCP server in the Agentic Data Plane by picking a managed type from the marketplace or registering a self-managed server you host yourself, then configure authentication, code mode, and access. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Create a managed or self-managed MCP server in Agentic Data Plane learning-objective-2: Configure each authentication mode and pick the right one for your use case learning-objective-3: Save the server, verify the server URL, and confirm tools were discovered page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- Create MCP servers to give agents structured access to your databases, queues, CRMs, and other business systems. Each server exposes [tools](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#tool), [resources](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#resource), and [prompts](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#prompt) that an agent can discover and invoke. Choose managed types that Redpanda hosts for you, or register self-managed servers you host yourself. After completing this guide, you will be able to: - Create a managed or self-managed MCP server in Agentic Data Plane - Configure each authentication mode and pick the right one for your use case - Save the server, verify the server URL, and confirm tools were discovered ## [](#prerequisites)Prerequisites - For any authentication mode that uses upstream credentials: the credentials in hand and a secret already created in the Redpanda Agentic Data Plane secret store. Secret references must be `UPPER_SNAKE_CASE` (proto regex `^[A-Z][A-Z0-9_]*$`). For example: `MCP_API_KEY`, `OPENAI_API_KEY`. - For user-delegated OAuth on a managed server, or to attach an existing provider on a self-managed server: an [OAuth provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) resource already configured. See [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). - For automatic OAuth setup on a self-managed server: nothing, unless the server doesn’t support dynamic client registration. In that case, an OAuth app registered with the upstream vendor, its client ID, and a client-secret reference for a confidential app. ## [](#open-the-mcp-servers-page)Open the MCP Servers page 1. Open **MCP Servers** in the sidebar. 2. Click **Add MCP server**. ## [](#pick-a-backend)Pick a backend The marketplace picker lists every managed type as a card and includes a **Remote (Proxied)** option for self-managed servers. - **Managed**: Pick a card. Redpanda hosts the server in-process. The configuration form is rendered from the type’s protobuf schema; field labels and help text come straight from the proto. - **Self-managed**: Pick **Remote (Proxied)**. You provide a URL and a transport, and Redpanda proxies requests to your server. For a tour of every managed type and which one fits your use case, see [Managed catalog](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/). To go deep on the self-managed path (transport choices, TLS, multi-server aggregation), see [Register a self-managed server](https://docs.redpanda.com/agentic-data-plane/connect/register-remote/). ## [](#name-and-basic-fields)Name and basic fields Every server has the same identity fields. | Field | Required | Notes | | --- | --- | --- | | Name | Yes | Lowercase letters, numbers, and hyphens only (proto regex ^[a-z][a-z0-9-]*$); 1–63 characters; must start with a letter. Immutable after create. Used as the URL path segment. | | Description | No | Up to 256 characters. Shown in list and detail views. | | Enabled | Yes (toggle) | Disabled servers reject every tool call. | The `name` is the server’s identifier and is immutable. The update API preserves it: you can’t rename a server after create. To use a different name, delete the server and create a new one. ## [](#configure-the-managed-flow-managed-types-only)Configure the managed flow (managed types only) Each managed type ships its own configuration schema. The form on this page is rendered from the type’s `_config.proto`, so field labels and help text come directly from the proto definition. No per-type hand-written form code is required. For per-type fields, see the [Managed catalog](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/): a reference of every managed MCP type Redpanda hosts, grouped by category, with a description and a link to its setup guide where one exists. > 📝 **NOTE** > > MCP enforces a 64-character limit on tool names. For managed MCP types whose generated names exceed that limit, Agentic Data Plane truncates the prefix and replaces it with a hash, so the long-form name becomes something like `64ghux5adn_github_read_v1_GitHubReadService_GetAuthenticatedUser`. Agentic Data Plane always preserves the version, service, and method suffix, so the short tool name an agent sees (for example, `get_authenticated_user`) stays stable across truncations. > > You don’t configure the truncation. This detail matters only when you correlate tool calls in logs or transcripts against the generated proto names. ## [](#configure-the-self-managed-flow-remoteproxied-only)Configure the self-managed flow (Remote/Proxied only) Two fields on top of the identity fields: | Field | Required | Notes | | --- | --- | --- | | URL | Yes | Endpoint URL of your server. Must start with http:// or https://. HTTPS is required if you choose user-delegated OAuth (proto rule remote_mcp.user_oauth_requires_https). | | Transport | Yes | SSE (server-sent events) or Streamable HTTP (newer bidirectional protocol). Pick whichever your server speaks. See Register a self-managed server for how to test which transport your server uses. | ## [](#configure-authentication)Configure authentication Both managed and self-managed servers offer the same set of authentication modes. Managed types only show the modes that make sense for that type; for example, SQL never offers user-delegated OAuth. | Mode | Use when | | --- | --- | | None | The upstream server doesn’t need authentication, or the managed type wraps an in-process resource that needs no creds. | | Static key | Single shared API key. Provide a key_ref (secret reference, UPPER_SNAKE_CASE) and an optional header_name (defaults to Authorization). | | Token passthrough | Forward the caller’s Authorization header to the upstream server as-is. Use this mode when the upstream already validates upstream tokens. | | Service-account OAuth | 2-legged OAuth client credentials. One shared upstream identity for every caller. Provide client_id, client_secret_ref, token_url, and any required scopes. | | User-delegated OAuth | Each end-user authenticates against the upstream system with their own credentials, and Redpanda injects the user’s token at call time. For a self-managed server, Redpanda can set up OAuth automatically from the server URL, or you can attach an OAuth provider your organization already registered. A managed type that supports this mode attaches an OAuth provider in the type’s configuration. The first time a user calls a tool that needs this server, Redpanda surfaces a consent prompt; Redpanda stores the resulting connection in the token vault, where it shows up under My Connections. See User-delegated OAuth for the full flow. | > 📝 **NOTE** > > Choosing between `Service-account OAuth` and `User-delegated OAuth` is the credential-mode decision. Service-account authentication gives every caller the same identity at the upstream; user-delegated authentication gives each caller their own. ## [](#code-mode-optional)Code mode (optional) Toggle **Enable Code Mode** to add `{name}_search` and `{name}_execute` tools alongside the server’s own tools. Agents can use `_search` to discover available tools and `_execute` to run sandboxed Python or JavaScript that orchestrates them. This is useful when you’d rather have the agent generate a small program than call tools one at a time. When code mode is enabled, the **Connection** tab surfaces a second URL, the `Code Mode URL`, that clients can connect to instead of the standard one. > 📝 **NOTE** > > Defer advanced code-mode patterns (sandboxing limits, runtime selection, dependency management) to follow-up content; this page covers only enabling it. ## [](#output-format-optional)Output format (optional) By default, a server forwards each tool’s results to the agent as JSON. To reduce the number of tokens an agent spends reading large, tabular results, set the server’s **Output format** to a token-optimized encoding. In the **Output format** section, set **Encoding** to one of these values: | Encoding | Result | | --- | --- | | JSON (default) | Forwards results to the agent unchanged. | | TOON (token-optimized) | Re-encodes tabular and nested-object results into a denser TOON representation that uses fewer tokens than JSON. | | JTON (token-optimized) | Re-encodes tabular results into JTON, a compact superset of JSON. | The gateway re-encodes a result only when it can do so without losing data. When a result isn’t tabular, or can’t be converted losslessly, the gateway forwards the original JSON unchanged, so changing the encoding never drops or corrupts a result. To change the encoding later, edit the server. The selected encoding takes effect after token-optimized output is enabled for your gateway. Until then, results are forwarded as JSON. > 📝 **NOTE** > > Output format is a preview capability. ## [](#save-and-verify)Save and verify 1. Click **Create server**. The server appears in the list with a **Type** badge: **Managed** or **Self-managed**. 2. Open the detail page. The **Overview** tab summarizes the server, including its discovered tools, attached agents, and server metadata. 3. If your organization has the **Activity** tab enabled, open it to review how agents have used this server. The **Recent calls** table lists recent tool calls across the agents attached to this server over the last 7 days, showing each call’s time, tool, agent, caller, duration, and status. Click **Refresh** to reload the feed. If no traffic has run yet, the tab is empty. 4. Open the **Connection** tab to get the `Server URL` that clients use to connect. Copy it for use later. The tab also gives you ready-to-paste connection snippets, pre-filled with this server’s URL, for common MCP clients such as Claude Code, Claude Desktop, and Cursor, plus code examples in several languages. The code examples authenticate with the OAuth authorization-code flow and surface the OAuth client ID to use. 5. Open the **Inspector** tab. Redpanda performs a live `tools/list` against the server and lists every tool it discovered. See [Test a server’s tools](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) for how to call them. A populated tools list confirms that the connection works and credentials resolve correctly. If the list is empty or the tab shows an error, see [Troubleshooting](#troubleshooting). To mask, drop, or filter the data this server’s tools return before an agent sees it, open the **Data Policies** tab. See [Shape Tool Data with Data Policies](https://docs.redpanda.com/agentic-data-plane/connect/data-policies/). > 📝 **NOTE** > > Data policies are a preview capability. ## [](#create-from-the-cli)Create from the CLI Use [`rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) for a non-UI path through the same create flow, useful for scripting and CI. ```bash # Managed type (Workday example) rpk ai mcp-server create --name workday-hr \ --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.workday.v1.WorkdayMCPConfig", "tenant": "acme", "host": "wd2-impl-services1.workday.com", "oauth_refresh_token": { "username": "isu_user@acme", "password_secret_ref": "${secrets.WORKDAY_PASSWORD}", "refresh_token_secret_ref": "${secrets.WORKDAY_REFRESH_TOKEN}" } }' # Managed type with user-delegated OAuth inside the managed config # (NetSuite example) rpk ai mcp-server create --name netsuite \ --description "NetSuite ERP with user OAuth" \ --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.netsuite.v1.NetSuiteMCPConfig", "accountId": "1234567_SB1", "userOauth": { "providerName": "netsuite", "requiredScopes": ["rest_webservices"] } }' # Self-managed server with user-delegated OAuth rpk ai mcp-server create --name github-proxy \ --url https://mcp.example.com/sse \ --user-oauth-provider github \ --user-oauth-scopes repo,read:org # Update a self-managed server's user-delegated OAuth scopes rpk ai mcp-server update github-proxy \ --user-oauth-provider github \ --user-oauth-scopes repo,read:org,workflow ``` | Flag | Notes | | --- | --- | | --managed-config | JSON blob carrying the managed type’s _config.proto shape, including a @type URL. | | --user-oauth-provider | Self-managed servers only. Name of an OAuth provider already registered on the Outbound providers tab of Integrations setup. This flag is the attach-a-provider path; it doesn’t request automatic OAuth setup. See Configure an OAuth Provider. The principal needs dataplane_aigateway_oauthprovider_attach on the named provider. Managed servers that support user-delegated OAuth carry their auth shape inside --managed-config. | | --user-oauth-scopes | Self-managed servers only. Comma-separated scopes the server requires. Provide every scope any tool may need; user re-consent is required if scopes change later. | The command targets the AI Gateway of your selected Agentic Data Plane environment, using credentials from `rpk ai auth login`. ## [](#list-and-filter-servers-with-the-api)List and filter servers with the API To enumerate MCP servers programmatically, call `MCPServerService.ListMCPServers`. Beyond the `name_contains` substring match, the request accepts an AIP-160 `filter` expression and an AIP-132 `order_by`, so you can scope and sort the list on the server (for example, to page through only the managed servers, newest first) instead of filtering the loaded page. The list endpoint uses the same OIDC client-credentials authentication as the rest of AI Gateway. Mint a service-account access token using the flow in [Authenticate with OIDC client credentials](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/#authenticate-with-oidc-client-credentials), then pass it as a bearer token. The service account needs `dataplane_adp_mcpserver_list`. The request’s `filter` object carries two independent fields: | Field | Meaning | | --- | --- | | name_contains | Case-insensitive substring match on the server name. | | filter | AIP-160 expression (maximum 1024 characters) that the server ANDs with name_contains and the tenant scope. Filterable columns: name, type, enabled, description, created_at, and updated_at. Use it for multi-value OR semantics, for example type = "MCP_SERVER_TYPE_REMOTE" OR type = "MCP_SERVER_TYPE_MANAGED". The type column accepts the MCPServerType enum values MCP_SERVER_TYPE_REMOTE and MCP_SERVER_TYPE_MANAGED; enabled accepts true or false. | Set `order_by` (maximum 256 characters) to a comma-separated list of fields, each optionally suffixed with \` desc\` (ascending by default), for example `created_at desc`. Orderable fields are the keyset columns `name` and `created_at`. An unsupported field returns `InvalidArgument`. Leave `order_by` empty to use the server default (`created_at desc`). The order is encoded into the page token, so keep it stable across a paged walk. ```bash ACCESS_TOKEN="" # from the client_credentials flow DATAPLANE_BASE="https://aigw..clusters.rdpa.co" curl -s --request POST \ --url "${DATAPLANE_BASE}/redpanda.api.adp.v1alpha1.MCPServerService/ListMCPServers" \ --header "Authorization: Bearer ${ACCESS_TOKEN}" \ --header 'Content-Type: application/json' \ --data '{ "filter": { "filter": "type = \"MCP_SERVER_TYPE_MANAGED\"" }, "order_by": "created_at desc", "page_size": 50 }' | jq ``` The response carries the matching `mcp_servers`, a `next_page_token` for the next page, and an estimated `total_size` (AIP-158) of all servers matching the filter, ignoring pagination. ## [](#edit-disable-and-delete-a-server)Edit, disable, and delete a server - **Edit:** most fields can change. The `name` and `type` are immutable after create. - **Disable:** toggle **Enabled** off. The server stays in the list, but every tool call returns an error until you re-enable it. - **Delete:** permanently removes the server record. User OAuth connections are scoped to the OAuth Provider, not the server, so they stay in the token vault and keep working for other servers that use the same provider. If you re-create a server against the same provider, users don’t re-consent unless the new server requires additional scopes. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | Secret not found | The secret reference is case-sensitive and must be UPPER_SNAKE_CASE matching the proto regex ^[A-Z][A-Z0-9_]*$. Confirm the secret exists in the Agentic Data Plane secret store and is spelled identically. | | "HTTPS required" error on save (self-managed) | You picked user-delegated OAuth on a server with an http:// URL. Switch to https:// (proto rule remote_mcp.user_oauth_requires_https). | | Inspector / tools list empty after create | The connection or authentication might be failing. Check the Connection tab for upstream errors. For self-managed, confirm the transport (SSE vs. Streamable HTTP) matches what your server actually speaks. | | Tool calls return errors after disable/enable | Disabled servers reject all tool calls. Confirm the Enabled toggle is on. | ## [](#next-steps)Next steps - [Configure User-Delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) - [Shape Tool Data with Data Policies](https://docs.redpanda.com/agentic-data-plane/connect/data-policies/) - [Plug in an App, Database, or Tool](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/) --- # Page 13: Shape Tool Data with Data Policies **URL**: https://docs.redpanda.com/agentic-data-plane/connect/data-policies.md --- # Shape Tool Data with Data Policies > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Shape Tool Data with Data Policies latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: data-policies page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: data-policies.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/data-policies.adoc description: Add data policies to an MCP server to mask, drop, or filter the data its tools send and return, restrict argument values, and preview the effect before saving. page-topic-type: how-to personas: platform_engineer, agent_builder learning-objective-1: Create a data policy that masks, drops, or filters the data a tool returns learning-objective-2: Restrict the argument values that callers can send to a tool learning-objective-3: Preview the composed effect of a server's data policies before saving page-git-created-date: "2026-07-29" page-git-modified-date: "2026-08-10" --- Data policies shape the data an MCP server exposes. Use them to mask, drop, or hash sensitive fields in the results a [tool](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#tool) returns, restrict the argument values a caller can send, and filter whole records out of list results, all before the model sees the data. Sensitive data stays protected without turning tools off. After reading this page, you will be able to: - Create a data policy that masks, drops, or filters the data a tool returns - Restrict the argument values that callers can send to a tool - Preview the composed effect of a server’s data policies before saving ## [](#how-data-policies-work)How data policies work A data policy belongs to one MCP server. It binds a set of transforms to the tools they shape and the people they apply to: - **Tools**: The tools on this server the policy shapes. An empty list means every tool. - **Principals**: Who the policy applies to, as `User:` entries. An empty list means every caller. - **Transforms**: What the policy does to tool-call arguments on the way to the server and to results on the way back. Data policies complement permissions. Permissions decide _whether_ a caller can invoke a tool. A server’s data policies decide _what the data looks like_ for the callers they match. See [Control Who Can Do What](https://docs.redpanda.com/agentic-data-plane/control/permissions-overview/). The [AI Gateway](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#ai-gateway) enforces data policies on live traffic in both directions. A server can carry several data policies, and every policy that matches a call applies. Policies compose most-restrictively: adding a policy can only narrow what a caller sees, never widen it. Data policies fail closed. If a rule cannot be enforced, matching calls are denied rather than served unshaped data. ## [](#prerequisites)Prerequisites You need an MCP server with discovered tools. To create one, see [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/). ## [](#open-the-data-policies-tab)Open the Data Policies tab 1. Open **MCP Servers** in the sidebar. 2. Select a server. 3. Open the **Data Policies** tab. The **Tools** list shows every tool the server exposes. A colored dot marks each tool’s status: green when at least one data policy shapes it, yellow when the tool handles data but no policy covers it, and gray when there is nothing to protect. A legend at the bottom of the list counts the tools in each status. When a server exposes many tools, use the filter box to narrow the list by tool name, title, or description; the count next to **Tools** shows how many tools match. ## [](#create-a-data-policy)Create a data policy 1. In the **Tools** list, select the tool you want to shape. 2. Click **+** to start a new policy. The policy gets a suggested name, which you can edit. 3. On the **Configuration** tab, choose a treatment for each request or response field: - **Keep**: Preserve the field. In allowlist mode, only kept fields survive. - **Mask**: Replace the field’s value but keep the field present. Choose one of the [mask methods](#mask-methods). - **Drop**: Remove the field entirely. 4. Save the policy. A new policy applies only to the tool you created it from until you widen its targeting. See [Target tools and people](#target-tools-and-people). You can also edit the policy as YAML. The form and the YAML editor are two views of the same draft: switch between them at any time. ### [](#mask-methods)Mask methods | Method | What it does | | --- | --- | | Redact | Replaces the value with a fixed placeholder. The default placeholder is [REDACTED]. | | Partial | Keeps the first or last characters and masks the rest. For example, keeping the last four characters turns 123-45-6789 into *6789. | | Hash | Replaces the value with a salted SHA-256 digest. Equal inputs produce equal digests, so values stay correlatable without exposing the plaintext. The salt comes from a secret you reference by name, never from the policy itself. | | Pattern | Rewrites the value with an RE2 regular-expression substitution. The replacement text can reference capture groups, such as $1. | ### [](#select-fields)Select fields A rule selects fields with a JSONPath expression, such as `$.user.email` (you can omit the leading `$.`). To match a field wherever it appears, use a descendant selector such as `$..ssn` with mask and drop rules. Wildcard, index, and filter expressions are not supported: you can’t save a policy that uses them. For list results, selectors evaluate against each record. For single-object results, they evaluate against the whole payload. By default, a mask or drop rule whose selector matches nothing denies the call. This protects you when an upstream API renames a field: the renamed field fails the call instead of silently leaking. If a field is legitimately optional, mark its rule absence-safe so a missing field is acceptable. ### [](#allowlist-mode)Allowlist mode By default, fields you don’t select pass through unchanged, and only your mask and drop rules take effect. Switch a policy’s field rules to allowlist mode to invert this: only fields with an explicit **Keep** survive, and everything else is dropped. ## [](#restrict-argument-values)Restrict argument values A policy can tighten the allowed values of a tool-call argument. The AI Gateway rejects a call whose argument falls outside the limits, with an error that names the violated argument. Address the argument with a JSONPath into the tool’s arguments, such as `$.query.limit`, then apply any of these limits: | Limit | Applies to | | --- | --- | | Minimum and maximum value | Numbers | | Minimum and maximum length | Strings | | Pattern (RE2 regular expression) | Strings | | Format, such as email, date, or uuid | Strings | | Allowed values | Strings | | Minimum and maximum item count | Arrays | The gateway also merges these limits into the input schema the tool advertises, so agents see the tightened contract up front instead of discovering it through failed calls. ## [](#filter-records-out-of-results)Filter records out of results A row filter drops whole records from a list-shaped result. It names the record array and the condition a record must satisfy to survive: - **Path**: Where the record array is in the result, such as `$.body` for an OpenAPI server’s response envelope, `$.result` for a ServiceNow-style wrapper, or `$` when the result is a bare array. If the path is absent or not an array, the filter does nothing. - **Condition**: A comparison of a record field against a literal value, such as `@.priority >= 8`. Supported operators are `==`, `!=`, `<`, `<=`, `>`, and `>=`. The literal can be a string, number, boolean, or null. A record that doesn’t have the compared field never survives the filter. Conditions on the same array combine across rules and policies, so a record must satisfy all of them. ## [](#target-tools-and-people)Target tools and people By default, a saved policy applies to the tool you created it from. Widen or narrow its targeting on the **Configuration** tab: - **Tools**: List the tools the policy shapes. Clear the list to shape every tool on the server. - **Principals**: List the people the policy applies to, as `User:` entries with the caller’s full email address, for example `User:alice@example.com`. Clear the list to apply the policy to every caller. ## [](#preview-the-effect)Preview the effect Before you save, check what a policy actually does: - The **Configuration** tab shows the composed effect for the selected tool across all of the server’s policies, including your unsaved edits, with each field’s winning treatment and which policy contributed it. - The **Preview** tab runs sample arguments and a sample result through the same code that shapes live traffic and shows the shaped data an agent would receive. If matching calls would be denied, a banner explains why, for example an unenforceable rule or a strict selector that matches nothing. ## [](#limitations)Limitations Data policies are a preview capability with these limitations: - Principals accept individual users only. Group-based targeting is not supported. - Field selectors support named paths and descendant selectors only. Wildcard, index, and filter expressions are rejected. - On a self-managed server that uses the legacy Server-Sent Events (SSE) transport, results stream past response shaping. Calls that match a policy with response rules are denied on those servers. Request rules still work. - If your gateway does not enforce data policies, the tool header shows a **Not enforced here** badge: rules save but don’t apply to live traffic. To read a server’s data policies through the API, get the individual server. List responses omit data policies to keep payloads small. ## [](#next-steps)Next steps - [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) - [Control Who Can Do What](https://docs.redpanda.com/agentic-data-plane/control/permissions-overview/) - [See What Your Agent Did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/) --- # Page 14: Draw Charts from an Agent **URL**: https://docs.redpanda.com/agentic-data-plane/connect/draw-charts.md --- # Draw Charts from an Agent > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Draw Charts from an Agent latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: draw-charts page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: draw-charts.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/draw-charts.adoc description: Make an agent render inline bar and line charts in the Playground by emitting a chart code block that follows the Agentic Data Plane chart contract. page-topic-type: how-to personas: agent_builder learning-objective-1: Instruct an agent to draw a bar or line chart by emitting a chart code block learning-objective-2: Migrate an earlier chart prompt to the Agentic Data Plane chart contract learning-objective-3: Diagnose a chart that renders as an error or stays a placeholder page-git-created-date: "2026-06-30" page-git-modified-date: "2026-08-10" --- An agent draws a chart by emitting a fenced code block tagged `chart` whose body is strict JSON that follows the Agentic Data Plane chart contract. The Playground renders the data with the Agentic Data Plane chart components. The fence body contains data, not Recharts component code. The agent’s **Playground** tab renders that block with Chart, Data, and Code views. This is a rendering convention: the agent decides when a chart helps and writes the data, and the Playground draws it. No tool call or application setup is required. > ❗ **IMPORTANT** > > The chart contract supports `bar` and `line` charts. The renderer uses shadcn/Recharts, not Chart.js. Existing `bar` and `line` blocks written for the earlier Chart.js format still render. When a block has no top-level `title`, the renderer falls back to `options.plugins.title.text`, but it ignores every other legacy presentation option. Other legacy chart types show an error. Convert them to `bar` or `line`. See [Migrate from Chart.js](#migrate-chart-js-prompt) to update an existing prompt. After reading this page, you will be able to: - Instruct an agent to draw a bar or line chart by emitting a chart code block - Migrate an earlier chart prompt to the Agentic Data Plane chart contract - Diagnose a chart that renders as an error or stays a placeholder ## [](#prerequisites)Prerequisites - A deployed agent in Agentic Data Plane. To create one, see [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/). - An understanding of how to write an agent system prompt. See [Write Effective System Prompts](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/). ## [](#how-chart-rendering-works)How chart rendering works When the agent’s response contains a fenced code block tagged `chart`, the Playground parses the block body as a chart configuration and draws the chart in place of the code. Every other code block renders as plain code, so a `chart` block is the agent’s only departure from ordinary output. The renderer supplies the visual presentation. A valid configuration renders as a responsive SVG chart with the Redpanda theme, a tooltip, and a legend. The agent supplies the chart type, optional title, labels, series names, and numeric values. Agentic Data Plane draws a `chart` block wherever it shows the agent’s response: the agent’s **Playground** tab and the **Transcripts** tab. When an external application calls the agent, whether that application draws the chart depends on how it renders the agent’s output. ![Chart rendering flow. An agent response contains a strict JSON chart code block. The Playground validates the chart contract and produces Chart, Data, and Code views from the same configuration. Invalid configurations produce a visible inline error.](https://docs.redpanda.com/agentic-data-plane/connect/_images/agent-chart-rendering.svg) Figure 1. The Playground turns a chart code block into three synchronized views ## [](#write-the-chart-block)Write the chart block Use the fields below. Unsupported chart types or invalid values show an error. - Tag the fence `chart`. The opening fence is three backticks followed by the word `chart`, with no other language tag. - Write the body as strict JSON. The Playground parses the body with a JSON parser, not a JavaScript evaluator, so use double-quoted keys and strings, unquoted numbers, no trailing commas, no comments, and no JavaScript expressions, functions, or callbacks. - Set the top-level `type` to `bar` or `line`. - Add a top-level `data` object with `labels` and `datasets` arrays. Each dataset contains a `data` array and can include a `label`. Without a `label`, the Playground names the series `Series 1`, `Series 2`, and so on. Values in a dataset must be finite numbers or `null`. - To display a title, add a top-level `title` string. - Do not add renderer-specific `options`, plugins, scales, animations, or color properties. The Playground controls those presentation details. A bar chart: ````text ```chart { "type": "bar", "title": "Monthly orders", "data": { "labels": ["Jan", "Feb", "Mar"], "datasets": [ { "label": "Orders", "data": [120, 190, 140] } ] } } ``` ```` ### [](#supported-chart-types)Supported chart types | Type | Use for | | --- | --- | | bar | Comparisons across categories. | | line | Trends across an ordered axis, such as time. | ## [](#instruct-the-agent-through-its-system-prompt)Instruct the agent through its system prompt To render a chart, tell the agent to emit a valid `chart` block. Add the convention to the agent’s [system prompt](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/): name the fence tag, state the strict JSON rules, list the supported types, and include one worked example. The following snippet works as a standalone prompt or as a section added to an existing one: ````text You can draw charts inline. When a bar or line chart communicates better than text, emit one fenced code block tagged exactly `chart` whose body follows the chart contract as strict JSON. Rules for the chart block: - The fence language tag is exactly: chart - The body is valid JSON: double-quoted keys and strings, unquoted numbers, no trailing commas, no comments, and no JavaScript, functions, or callbacks. - The top level contains "type", optional "title", and "data". - Allowed "type" values: "bar" and "line". - "data" contains "labels" and "datasets". Each dataset contains a numeric "data" array and can include a "label". - Do not emit renderer-specific options, plugins, scales, animations, or colors. - Put a brief plain-text explanation (1 or 2 sentences) before the chart block. Do not also paste a data table; the Playground has a built-in Data view. Example response to "show last quarter's orders by month": Orders peaked in February: ```chart { "type": "bar", "title": "Last quarter's orders", "data": { "labels": ["Jan", "Feb", "Mar"], "datasets": [ { "label": "Orders", "data": [120, 190, 140] } ] } } ``` ```` For prompt-writing patterns that make this output reliable, see [Output formatting](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/#output-formatting). ## [](#test-the-chart-in-the-playground)Test the chart in the Playground 1. Open the agent and switch to the **Playground** tab. 2. Enter a prompt that calls for a chart, such as `Show the broker count for the demo cluster over the last 3 months as a bar chart`. 3. Wait for the agent to finish its response. The chart appears in place of the `chart` block. ![The Playground rendering a bar chart titled Broker count / demo cluster / 3 months, with a Chart, Data, and Code view selector above bars for January, February, and March.](https://docs.redpanda.com/agentic-data-plane/connect/_images/agent-chart-rendered.png) Use the view selector to switch between: - **Chart**: The responsive bar or line chart. Hover over the chart to inspect values. - **Data**: The chart’s values as a table, reconstructed from the configuration. - **Code**: The JSON configuration the Playground parsed. Zoom, pan, and PNG export are not available. ## [](#migrate-chart-js-prompt)Migrate from Chart.js Existing `bar` and `line` configurations keep their type, labels, datasets, and values. Move the title to the top level and remove legacy presentation options. Convert other chart types to `bar` or `line`. | Earlier Chart.js configuration | Current chart contract | | --- | --- | | "type": "bar" or "type": "line" | Keep the type. | | pie, doughnut, polarArea, or radar | Use bar to compare categories. | | scatter or bubble | Choose line for an ordered trend or bar for category comparisons, and convert each point to a numeric dataset value. | | options.plugins.title.text | Move the string to the top-level title field. | | options, plugins, scales, animations, or colors | Remove them. The Playground supplies the presentation. | | Zoom, pan, or PNG export instructions | Remove them. These controls are not available. | For example, replace: ```json { "type": "bar", "data": { "labels": ["Jan", "Feb", "Mar"], "datasets": [ { "label": "Orders", "data": [120, 190, 140], "backgroundColor": "#ea580c" } ] }, "options": { "plugins": { "title": { "display": true, "text": "Monthly orders" } } } } ``` With: ```json { "type": "bar", "title": "Monthly orders", "data": { "labels": ["Jan", "Feb", "Mar"], "datasets": [ { "label": "Orders", "data": [120, 190, 140] } ] } } ``` ## [](#troubleshooting)Troubleshooting A block that does not satisfy the contract shows an inline error that names the problem. Click **Error details** to inspect the body the agent sent. ![An inline Failed to render chart error that explains the JSON problem and provides an Error details button.](https://docs.redpanda.com/agentic-data-plane/connect/_images/agent-chart-error.png) | Symptom | Cause and fix | | --- | --- | | A Failed to render chart error appears in place of the chart | The block body does not satisfy the contract. The error description names the problem. Click Error details to inspect the body the agent sent. Common causes include invalid JSON, a missing type field, a missing data object, a type other than bar or line, or a non-numeric dataset value. | | The error description reads Unsupported chart type | Change the type to bar or line. For migration guidance, see Migrate from Chart.js. | | A Building chart… placeholder remains visible | The placeholder shows while the chart block streams in, because the Playground cannot parse the configuration until the closing fence arrives. The chart replaces the placeholder when the agent finishes the response. If the response finishes and the body cannot be parsed, the Failed to render chart error replaces the placeholder. If the placeholder remains after the agent stops responding, instruct the agent to emit one complete chart block with a closing fence. | | The agent pastes a table or raw JSON instead of a chart | The agent either did not tag the fence chart or wrote prose instead of a block. Add the fence rule and worked example to the system prompt. | ## [](#next-steps)Next steps - [Write Effective System Prompts](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/) - [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) - [See What Your Agent Did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/) --- # Page 15: Set Up GitHub OAuth Provider and MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/github-oauth-tutorial.md --- # Set Up GitHub OAuth Provider and MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Set Up GitHub OAuth Provider and MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: github-oauth-tutorial page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: github-oauth-tutorial.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/github-oauth-tutorial.adoc description: Complete walkthrough for configuring GitHub as an OAuth provider and creating a user-delegated GitHub MCP server. page-topic-type: tutorial personas: agent_builder, platform_engineer learning-objective-1: Create a GitHub OAuth app and register it as an OAuth provider in Agentic Data Plane learning-objective-2: Test the OAuth connection proactively on the My Connections page learning-objective-3: Configure a GitHub managed MCP server with user-delegated OAuth page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-13" --- This tutorial shows how to connect Redpanda Agentic Data Plane to GitHub using OAuth, so users can authenticate with their own GitHub credentials when calling GitHub MCP tools. After completing this tutorial, you will be able to: - Create a GitHub OAuth app and register it as an OAuth provider in Agentic Data Plane - Test the OAuth connection proactively on the My Connections page - Configure a GitHub managed MCP server with user-delegated OAuth ## [](#before-you-begin)Before you begin - You need a GitHub account with permission to create OAuth apps (personal account or organization with appropriate role). - You need Agentic Data Plane administrator permissions to create OAuth providers and MCP servers. - You should understand the difference between user-delegated OAuth (each user authenticates as themselves) and service-account OAuth (all users share one identity). This tutorial covers user-delegated OAuth. > 💡 **TIP** > > GitHub recommends considering GitHub Apps instead of OAuth Apps for production use, as they offer fine-grained permissions and short-lived tokens. However, OAuth Apps work well for getting started with Redpanda Agentic Data Plane’s AI Gateway integration. ## [](#create-a-github-oauth-app)Create a GitHub OAuth app Register an OAuth application in GitHub to obtain the client ID and client secret. > 📝 **NOTE** > > Throughout this tutorial, fields marked with \* are required. 1. Sign in to GitHub and navigate to **Settings → Developer settings → OAuth Apps**. 2. Click **New OAuth App** (or **Register a new application** if this is your first OAuth app). 3. Fill in the application details: | Field | Value | | --- | --- | | Application name | Agentic Data Plane AI Gateway (or your preferred name) | | Homepage URL | https://aigw..clusters.rdpa.co+ This must match exactly. Replace with your actual cluster ID, such as https://aigw.d6kjl4h19241bg3ek3t0.cluster.rdpa.co. | | Application description | Optional. For example: "Redpanda AI Gateway GitHub integration". | | Authorization callback URL | https://aigw..clusters.rdpa.co/oauth/v1/callbackThis must match exactly. Replace with your actual cluster ID, such as https://aigw.d6kjl4h19241bg3ek3t0.cluster.rdpa.co/oauth/v1/callback. | 4. Click **Register application**. 5. On the application page, note your **Client ID** (for example, `Iv1.abc123…​`). Copy it for later. 6. Click **Generate a new client secret** and copy it immediately (you won’t see it again). > ❗ **IMPORTANT** > > - GitHub OAuth apps support only **one** callback URL (unlike GitHub apps which support multiple). > > - Store your client secret securely. GitHub will not show it again after you navigate away. ## [](#create-the-github-oauth-provider-in-agentic-data-plane)Create the GitHub OAuth provider in Agentic Data Plane Register GitHub as an OAuth provider in Agentic Data Plane. 1. Open **Integrations setup** in the sidebar and select the **Outbound providers** tab. 2. Click **Create provider** and select **GitHub** from the catalog. 3. Fill in the provider details: ### [](#provider-details)Provider details | Field | Value | Notes | | --- | --- | --- | | Name * | A name for this OAuth provider, for example, github. | Lowercase letters, numbers, and hyphens only. This is the machine identifier used when attaching the provider to an MCP server. Immutable after creation. | | Client ID * | The client ID from your GitHub OAuth app, for example, Iv1.abc123…​ | This is found in GitHub Settings → Developer settings → OAuth Apps → [Your App]. | | Display name * | GitHub | Human-readable name shown in Agentic Data Plane. | | Authorization endpoint * | https://github.com/login/oauth/authorize | GitHub’s OAuth authorization URL where users are redirected to grant permission. | | Token endpoint * | https://github.com/login/oauth/access_token | GitHub’s OAuth token exchange endpoint where authorization codes are exchanged for access tokens. | | Revocation Endpoint | Leave empty | GitHub doesn’t provide a standard RFC 7009 token revocation endpoint. Agentic Data Plane will handle token lifecycle without this. | | Client secret ref * | GITHUB_CLIENT_SECRET | Click New. Enter GITHUB_CLIENT_SECRET as the key name, paste in your client secret from GitHub, and then click Create secret. This creates the secret in the Secrets Store and links it to this provider in Agentic Data Plane. If you already have a secret in Secrets Store, click Existing instead. | ### [](#scopes)Scopes Define the GitHub scopes your MCP servers will need. Click in the **Scopes** field and add the following scopes: - `repo` - Full control of private repositories (read and write) - `read:user` - Read user profile information - `read:org` - Read organization membership - `workflow` - Update GitHub Actions workflows > 💡 **TIP** > > **Common GitHub OAuth scopes:** > > - `repo` - Access to private repositories > > - `public_repo` - Access to public repositories only > > - `read:user`, `user:email` - Read user profile and email > > - `read:org` - Read organization membership > > - `workflow` - Manage GitHub Actions workflows > > - `gist` - Create and read gists > > > See the [GitHub OAuth scopes documentation](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) for the complete list. > > **Scope management**: Include every scope any MCP server attached to this provider might need. Users must re-consent when scopes are added later, so it’s better to include all necessary scopes upfront. ### [](#grant-types)Grant types - **Browser consent** ✓ (checked) - OAuth 2.0 Authorization Code flow. This is the standard flow for user-delegated OAuth. - **Token exchange** ☐ (unchecked) - RFC 8693 token exchange. Leave unchecked unless you’re implementing advanced token exchange scenarios. ### [](#token-endpoint-auth-method)Token endpoint auth method Select **Client Secret (Basic)** This sends credentials as `client_id:client_secret` in the HTTP Basic Authorization header, which is GitHub’s expected authentication method. | Method | When to use | | --- | --- | | Client Secret (Basic) | Most common. GitHub expects this method. Credentials sent in Authorization header. | | Client Secret (POST) | Credentials sent in the POST body. Use only if the provider requires it. | | None (PKCE only) | For public clients with no client secret. Not applicable for GitHub OAuth Apps. | ### [](#require-pkce)Require PKCE **Enabled** (toggle on) Proof Key for Code Exchange (PKCE) adds an extra layer of security to the OAuth flow. > 📝 **NOTE** > > PKCE (RFC 7636) protects against authorization code interception attacks. When enabled, the gateway generates a code challenge before redirecting the user to GitHub and verifies it when exchanging the authorization code for a token. ### [](#complete-creation)Complete creation 1. Review all fields to ensure they match the values above 2. Click **Create provider** The provider appears in the **Outbound providers** list with status "Enabled". ## [](#test-the-connection-on-the-my-connections-page)Test the connection on the My Connections page Before creating an MCP server, proactively test the OAuth flow to verify your provider configuration is correct. 1. Open **My Connections** in the sidebar. 2. Find **GitHub** in the connections rail, under **Available to connect**. 3. Click **Connect**. 4. You’ll be redirected to GitHub’s authorization page. 5. Review the requested permissions (scopes) and click **Authorize \[Your App Name\]**. 6. GitHub redirects you back to Agentic Data Plane. 7. GitHub now shows status "Connected". > 💡 **TIP** > > If the connection fails: > > - Check that the **Homepage URL** and **Authorization callback URL** in your GitHub OAuth app exactly match the expected URLs with your cluster ID. > > - Verify the **Client ID** and **Client secret ref** in the Agentic Data Plane OAuth provider are correct. > > - Check that the secret `GITHUB_CLIENT_SECRET` exists and contains the correct value. > > > See [Troubleshooting](#troubleshooting) for more debugging tips. ## [](#create-the-github-mcp-server)Create the GitHub MCP server Now create an MCP server that uses the GitHub OAuth provider for user-delegated authentication. 1. Open **MCP Servers** in the sidebar. 2. Click **Create server**. 3. The catalog shows managed MCP servers organized by category (AI, Databases, Streaming, Collaboration, AWS, Google, Utilities). 4. Use the search bar or browse to find and select **GitHub**. > 📝 **NOTE** > > GitHub is a managed MCP server, meaning Redpanda provides and maintains the implementation. You only need to configure authentication and select which tools to expose. ### [](#configure-the-github-mcp-server)Configure the GitHub MCP server Fill in the basic server details: | Field | Example value | Notes | | --- | --- | --- | | Name * | my-gh | Unique identifier. Lowercase letters, numbers, and hyphens only. | | Description | What this server does (shown in detail views) | Optional human-readable description. | | Code mode | Toggle on/off | Enable to add search and run tools that let agents run sandboxed code against this server’s tools. Typically enabled for development/testing. | | Restrict to org | redpanda-data | GitHub-specific field. If set, confines this MCP to the named GitHub org (for example, "redpanda-data"). Leave empty for unrestricted access to all repositories the user can access. | ### [](#configure-authentication)Configure authentication 1. In the **Auth** dropdown, select **User OAuth**. This enables user-delegated authentication where each user authenticates with their own GitHub credentials. 2. In the **User OAuth** section that appears: | Field | Value | Notes | | --- | --- | --- | | Provider name * | GitHub | Select the GitHub OAuth provider you created earlier from the dropdown. If "Not set" appears, you haven’t created a provider yet or it’s not visible. | | Required scopes | Click + Add required scopes | Add the same scopes you defined in the OAuth provider, adding each scope to a new line. If a user’s stored connection has fewer scopes than specified here, they’ll be prompted to re-consent with upgraded scopes. | ### [](#token-injection-advanced)Token injection (advanced) The **Injection** section controls how the resolved OAuth token is placed on upstream requests: | Field | Default value | Notes | | --- | --- | --- | | Header name | Authorization | HTTP header name for the token. GitHub expects Authorization, so keep the default. | | Header prefix | Bearer | Value prefix before the token. GitHub expects Bearer , so keep the default. Set empty to omit the prefix entirely (for upstreams that expect a bare API key as the token). | > 💡 **TIP** > > **How to authenticate to GitHub** link explains GitHub’s expected authentication format. For standard GitHub OAuth, the defaults (`Authorization: Bearer `) are correct. ### [](#complete-creation-2)Complete creation 1. Review all fields. 2. Click **Submit**. The GitHub MCP server appears in the **MCP Servers** list showing: - **Name**: `my-gh` (or your chosen name) - **Type**: Managed (badge) - **Status**: Enabled (badge) - **Tools**: A list of available tools like `get_authenticated_user`, `list_my_orgs`, `list_org_repos`, and more > ❗ **IMPORTANT** > > **User OAuth vs service account OAuth:** > > - **User OAuth** (what we’re configuring): Each end-user authenticates with their own GitHub account. The upstream GitHub API sees requests as coming from that individual user and applies their permissions. > > - **Service account OAuth**: All users share one GitHub identity. The upstream sees every request as coming from the same service account. > > > For most scenarios where users need to access their own repositories or respect GitHub’s per-user permissions, choose **User OAuth**. ## [](#verify-the-mcp-server-works)Verify the MCP server works Test that the MCP server is correctly configured and can authenticate users. 1. In Agentic Data Plane, find your GitHub MCP server in the **MCP Servers** list. 2. Click it to view details. 3. If you tested the connection in Connections, you’re already connected and can test immediately. 4. If you skipped the Connections test, the first time you call a tool from this server, you’ll be prompted to authorize GitHub. The flow is: 1. Call a tool (for example, through a Claude Desktop integration pointing to this MCP server). 2. Agentic Data Plane returns `OAuthConnectionRequired` with an authorization URL. 3. The UI prompts you to connect to GitHub. 4. You authorize in GitHub. 5. The tool call automatically retries and succeeds. 5. After successful authorization, subsequent tool calls use your stored GitHub token with no additional prompts (until the token expires or scopes change). ## [](#what-you-accomplished)What you accomplished You have now: - Created a GitHub OAuth app with the correct callback URL - Registered GitHub as an OAuth provider in Agentic Data Plane - Tested the OAuth connection proactively - Created a GitHub managed MCP server with user-delegated OAuth - Verified that users can authenticate and call GitHub tools You could next create an agent using this GitHub MCP server. Each user who calls tools from this MCP server will authenticate with their own GitHub account. User tokens are stored securely in Agentic Data Plane’s token vault and automatically refreshed before expiry. ## [](#troubleshooting)Troubleshooting | Symptom | Solution | | --- | --- | | redirect_uri_mismatch error during authorization | The callback URL in your GitHub OAuth app doesn’t match Agentic Data Plane’s callback. Go to GitHub Settings → Developer settings → OAuth Apps → [Your App] and verify the Authorization callback URL is exactly https://aigw..clusters.rdpa.co/oauth/v1/callback. | | invalid_client error during token exchange | The Client ID or Client secret is incorrect, or the authentication method doesn’t match. Verify the Client ID in the OAuth provider matches GitHub, and that GITHUB_CLIENT_SECRET contains the correct client secret. Ensure Token Endpoint Auth Method is set to "Client Secret (Basic)". | | invalid_scope error during consent | One of the scopes you requested isn’t valid for GitHub OAuth apps. Check the GitHub OAuth scopes documentation and remove or rename invalid scopes. | | "OAuth provider not found" when creating MCP server | The provider name doesn’t match. Verify you created the provider with name github (lowercase) and are selecting the correct provider in the MCP server configuration. | | Connection works in Connections but fails in MCP server | The MCP server’s required scopes might be different from what you consented to in Connections. Edit the OAuth provider to include all necessary scopes, then re-consent in Connections. | | Token expired or OAuthTokenExpired error | GitHub tokens eventually expire or can be revoked. The user needs to re-authorize in Connections or by triggering the consent flow again on the next tool call. | | Permission denied when attaching provider to MCP server | You need the dataplane_aigateway_oauthprovider_attach permission on the GitHub provider. Contact your Agentic Data Plane administrator to grant this permission. | ## [](#next-steps)Next steps - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) --- # Page 16: Choose an Integration Pattern **URL**: https://docs.redpanda.com/agentic-data-plane/connect/integration-overview.md --- # Choose an Integration Pattern > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Choose an Integration Pattern latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: integration-overview page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: integration-overview.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/integration-overview.adoc description: Choose the right integration pattern for connecting agents, pipelines, and external applications. page-topic-type: best-practices personas: agent_builder, platform_engineer learning-objective-1: Choose the integration pattern that fits your use case learning-objective-2: Apply appropriate authentication for internal versus external integration learning-objective-3: Select the right communication protocol for your integration scenario page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-06" --- Choose the right integration pattern for how your agents, pipelines, and external applications communicate. The pattern you pick determines who initiates the call, how data flows, and whether the interaction is synchronous or event-driven. After reading this page, you will be able to: - Choose the integration pattern that fits your use case - Apply appropriate authentication for internal versus external integration - Select the right communication protocol for your integration scenario ## [](#integration-scenarios)Integration scenarios Agentic Data Plane supports three primary integration scenarios based on who initiates the call and where the caller is located: | Scenario | Description | When to Use | Guide | | --- | --- | --- | --- | | Agent needs capabilities | Your agent invokes MCP tools to fetch data, call APIs, or access external systems on-demand | Agent-initiated, synchronous, interactive workflows | How MCP Servers Work | | Pipeline processes events | Your Redpanda Connect pipeline invokes agents for each event in a stream using the a2a_message processor | Event-driven, automated, high-volume stream processing | Integrate with Redpanda Pipelines | | External system calls agent | Your application or agent (hosted outside Agentic Data Plane) calls Agentic Data Plane agents using the A2A protocol | Backend services, CLI tools, custom UIs, multi-platform agent workflows | Connect Agents with A2A | ## [](#common-use-cases-by-pattern)Common use cases by pattern Each integration pattern serves different scenarios based on how data flows and who initiates the interaction. ### [](#agent-needs-capabilities)Agent needs capabilities (MCP tools) Use MCP tools when your agent needs on-demand access to data or capabilities. The agent decides when to invoke tools as part of its reasoning process. It waits for responses before continuing. This pattern works well for interactive workflows: customer support lookups, approval flows, or context-aware chatbots. Avoid MCP tools for high-volume stream processing or automated workflows without user interaction. Use pipeline-initiated integration instead. For implementation details, see [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/). ### [](#pipeline-processes-events)Pipeline processes events (`a2a_message`) Use the `a2a_message` processor when your pipeline needs to invoke agents for every event in a stream. The pipeline controls when agents execute. This pattern is ideal for automated, high-volume processing where each event requires AI reasoning. Common scenarios include real-time fraud detection, sentiment scoring for customer reviews, and content moderation that classifies and routes content. For implementation details, see [Integrate with Redpanda Pipelines](https://docs.redpanda.com/agentic-data-plane/connect/pipeline-integration-patterns/). ### [](#external-system-calls-agent)External system calls agent Use external integration when your applications, services, or agents hosted outside Agentic Data Plane need to call Agentic Data Plane agents. External systems send requests using the A2A protocol and receive responses synchronously. This works for backend services, CLI tools, custom UIs, and agents hosted on other platforms. Common scenarios include backend services analyzing data as part of workflows, CLI tools invoking agents for batch tasks, custom UIs displaying agent responses, CRM agents coordinating with Redpanda agents, and multi-platform workflows spanning different infrastructure. To learn how the A2A protocol enables this integration, see [Connect Agents with A2A](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/). ## [](#pattern-comparison)Pattern comparison The following table compares the two primary internal integration patterns: | Criterion | Agents Invoking MCP Tools | Pipelines Calling Agents | | --- | --- | --- | | Trigger | User question or agent decision | Event arrival in topic | | Frequency | Ad-hoc, irregular, as needed | Continuous, every event | | Latency | Low (agent waits for response) | Higher (async acceptable) | | Control Flow | Agent decides when to invoke | Pipeline decides when to invoke | | Use Case | "Fetch me data", "Run this query" | "Process this stream", "Enrich all events" | | Human in Loop | Often yes (user-driven) | Often no (automated) | ## [](#security-considerations-for-external-integration)Security considerations for external integration When integrating external applications with Agentic Data Plane agents, protect credentials and tokens. ### [](#protect-service-account-credentials)Protect service account credentials Store the client ID and secret in secure credential stores, not in code. Use environment variables or your organization’s secrets manager. Rotate credentials if compromised and restrict access based on the principle of least privilege. ### [](#protect-access-tokens)Protect access tokens Access tokens grant full access to the agent. Anyone with a valid token can send requests, receive responses, and consume agent resources (subject to rate limits). Treat access tokens like passwords and never log them or include them in error messages. ## [](#next-steps)Next steps - [Connect Agents with A2A](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/) - [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) - [Integrate with Redpanda Pipelines](https://docs.redpanda.com/agentic-data-plane/connect/pipeline-integration-patterns/) --- # Page 17: Integrate with Your Stack **URL**: https://docs.redpanda.com/agentic-data-plane/connect/integrations.md --- # Integrate with Your Stack > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Integrate with Your Stack latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: integrations page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: integrations.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/integrations.adoc description: Choose an integration pattern and connect the Agentic Data Plane to your existing stack, Redpanda pipelines, and developer tools. page-git-created-date: "2026-06-01" page-git-modified-date: "2026-07-02" --- Connect the Agentic Data Plane to your existing systems. Choose an integration pattern, wire in Redpanda pipelines, and use Redpanda Agentic Data Plane from developer tools like Claude Code and Codex. - [Choose an Integration Pattern](https://docs.redpanda.com/agentic-data-plane/connect/integration-overview/) Choose the right integration pattern for connecting agents, pipelines, and external applications. - [Integrate with Redpanda Pipelines](https://docs.redpanda.com/agentic-data-plane/connect/pipeline-integration-patterns/) Build Redpanda Connect pipelines that invoke agents for event-driven processing and streaming enrichment. - [Run Claude Code and Codex through AI Gateway](https://docs.redpanda.com/agentic-data-plane/connect/coding-agents/) Launch Claude Code or Codex with rpk ai run, routing their model traffic through a managed, enterprise-passthrough, or AWS Bedrock Agentic Data Plane provider. --- # Page 18: BambooHR Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/bamboohr.md --- # BambooHR Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: BambooHR Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/bamboohr page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/bamboohr.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/bamboohr.adoc description: Let agents read BambooHR employee, time-off, and performance data with each caller's BambooHR OAuth identity. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the BambooHR managed MCP server with a BambooHR subdomain and user-delegated OAuth learning-objective-2: Identify the BambooHR tools available to agents learning-objective-3: Test BambooHR tool calls with an authorized user's connection page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-02" --- The **BambooHR** managed MCP server lets agents read BambooHR employee directory, time-off, and performance data with the calling user’s OAuth identity. The BambooHR configuration stores the company subdomain and the name of the BambooHR [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) to authenticate against. OAuth credentials and user tokens come from that provider and the [token vault](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#token-vault). After reading this page, you will be able to: - Configure the BambooHR managed MCP server with a BambooHR subdomain and user-delegated OAuth - Identify the BambooHR tools available to agents - Test BambooHR tool calls with an authorized user’s connection ## [](#what-this-mcp-server-does)What this MCP server does Use BambooHR when an agent needs HR context from BambooHR without sharing one upstream API key across every caller. Each caller authorizes with BambooHR, and tool calls run with the BambooHR permissions available to that caller. | Tool | What it does | | --- | --- | | get_employee | Fetches a single employee by ID. Use employee ID 0 to return the authenticated user’s own record. You can pass a comma-separated fields list, or leave it empty to return all fields the caller can access. | | get_employee_directory | Lists all employee directory entries visible to the authenticated user. | | get_time_off_requests | Queries time-off requests by date range. You can filter by employee ID, status, or time-off type. Supported statuses are approved, denied, superceded, requested, and canceled. | | whos_out | Returns absences and holidays in a date range. If you omit dates, the server starts with today and ends 14 days later. | | get_performance_feedback | Returns peer or manager feedback for an employee. You can filter by completed, pending, or all feedback. | ## [](#prerequisites)Prerequisites - A BambooHR workspace where you can create an OAuth 2.0 application. - A BambooHR OAuth Provider in Redpanda Agentic Data Plane. BambooHR OAuth authorize and token endpoints include your company subdomain. - A BambooHR company subdomain, such as `mycompany` for `mycompany.bamboohr.com`. The managed config accepts letters, numbers, and hyphens. - BambooHR users with the permissions required to read the employee, time-off, or performance data your agent needs. ## [](#configure-bamboohr-oauth)Configure BambooHR OAuth In BambooHR, create an OAuth 2.0 application in the BambooHR developer settings. Use the OAuth callback URL for your AI Gateway deployment. Register a BambooHR OAuth Provider in Agentic Data Plane with tenant-specific endpoints: ```text Authorization endpoint: https://api.bamboohr.com/api/gateway.php//v1/oauth2/authorize Token endpoint: https://api.bamboohr.com/api/gateway.php//v1/oauth2/token ``` Store the BambooHR client secret in the Agentic Data Plane secret store, then reference that secret from the OAuth Provider. ## [](#create-the-managed-mcp-server)Create the managed MCP server Create a managed MCP server with the BambooHR type. Set the `subdomain` field and reference the BambooHR OAuth Provider under the `userOauth` auth variant. BambooHR supports per-user OAuth only, so the `userOauth` block is required. The BambooHR managed config holds the company subdomain and the OAuth provider to authenticate against: ```json { "@type": "type.googleapis.com/redpanda.mcps.bamboohr.v1.BambooHRMCPConfig", "subdomain": "mycompany", "userOauth": { "providerName": "bamboohr" } } ``` `userOauth.providerName` is the resource name of the BambooHR OAuth Provider you registered. The provider’s stored per-user token is injected on each tool call. ## [](#authorize-and-test)Authorize and test Before a caller can use BambooHR tools, the caller must authorize the BambooHR OAuth Provider. After authorization, Redpanda stores the user’s access token in the token vault and subsequent tool calls use that token automatically. Test the server in the Inspector before you connect it to an agent. Start with `get_employee_directory` or `get_employee` with employee ID `0`, because both calls confirm that the user’s OAuth connection resolves and BambooHR returns data visible to that user. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | Tool calls return permission errors | Confirm the BambooHR user can access the requested HR data. Restricted BambooHR roles can return permission errors, especially for performance data. | | OAuth succeeds, but tool calls fail | Confirm the OAuth Provider endpoints use the same BambooHR subdomain as the MCP server configuration. | | The server cannot find the BambooHR company | Confirm subdomain contains only the part before .bamboohr.com, such as mycompany. | ## [](#next-steps)Next steps - [Configure User-Delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) - [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) --- # Page 19: Freshservice Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/freshservice.md --- # Freshservice Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Freshservice Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/freshservice page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/freshservice.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/freshservice.adoc description: Manage Freshworks Freshservice ITSM tickets, assets, change requests, and agents from an agent, with API-key or per-user OAuth authentication. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Freshservice managed MCP server in API-key or User-OAuth mode learning-objective-2: Find the Freshservice credentials each mode needs learning-objective-3: List, create, and update tickets, assets, and changes from the Inspector or an agent page-git-created-date: "2026-06-09" page-git-modified-date: "2026-07-29" --- The Freshservice managed MCP server lets agents work with your Freshworks Freshservice ITSM instance: list and search tickets, read full ticket detail, create and update tickets, browse CMDB assets, open change requests, and look up support agents. After reading this page, you will be able to: - Configure the Freshservice managed MCP server in API-key or User-OAuth mode - Find the Freshservice credentials each mode needs - List, create, and update tickets, assets, and changes from the Inspector or an agent ## [](#what-this-mcp-server-does)What this MCP server does Wraps the Freshservice REST API v2. The following authentication modes are supported: - API key (Basic authentication): A long-lived Freshservice API key sent as the HTTP Basic authentication username, with the literal string `X` as the password. Best for service-account-style use. - User OAuth: Per-user Freshservice OAuth tokens resolved from the gateway’s [token vault](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#token-vault). Best when you want each agent action attributed to the calling end-user. Responses are curated for token efficiency: high-volume fields (routing headers, internal SLA sub-deadlines, spam and email-config flags, agent scoreboards) are dropped before reaching the LLM, and ticket and change descriptions are returned as plain text rather than HTML. Freshservice error response bodies are never forwarded to the caller; only the HTTP status code is surfaced, so API keys and internal request IDs cannot leak into tool error text. ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - A Freshservice instance and its domain (for example, `mycompany.freshservice.com`). - For API-key mode: the API key from your Freshservice profile (see [Get Freshservice credentials](#get-freshservice-credentials)). - For User-OAuth mode: a Freshservice OAuth app and an [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) configured in Redpanda Agentic Data Plane. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). ## [](#get-freshservice-credentials)Get Freshservice credentials ### [](#option-1-api-key-recommended-for-service-accounts)Option 1: API key (recommended for service accounts) 1. In Freshservice, open **Profile Settings**. 2. Copy the value from the **API Key** section. 3. Store the key in the Agentic Data Plane secret store under a name like `FRESHSERVICE_API_KEY`. The MCP sends the key as the HTTP Basic authentication username with `X` as the password (`base64(:X)`), which is the Freshservice convention. The API key inherits the permissions of the Freshservice user it belongs to, so use an account with the roles your workflows need (agent, asset, and change permissions). ### [](#option-2-user-oauth)Option 2: User OAuth For per-user authentication, register an OAuth app on Freshservice and a matching OAuth Provider in Agentic Data Plane: 1. Register a Freshservice OAuth app at the Freshworks developer portal to obtain a client ID and client secret. 2. Register a matching OAuth Provider in Agentic Data Plane. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). The `freshservice` preset pre-fills the authorization and token endpoints; Agentic Data Plane substitutes your Freshservice subdomain into the `{domain}` placeholders. 3. Each end-user authenticates once through the OAuth flow; tokens are stored in the gateway’s token vault. The OAuth scopes are `read` and `write`. Drop `write` if the MCP only needs to read. ## [](#configure)Configure Create a new Freshservice MCP server in Agentic Data Plane: 1. Open **MCP Servers > Create Server**. 2. Pick `Freshservice` from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the Freshservice configuration form: | Field | Notes | | --- | --- | | domain | Your Freshservice host, without the https:// scheme or a trailing slash (for example, mycompany.freshservice.com). | | auth | api_key for service-account mode, or user_oauth for per-user mode. | | api_key (API-key mode) | Secret-store reference holding the API key (for example, FRESHSERVICE_API_KEY). UPPER_SNAKE_CASE. | | user_oauth (User-OAuth mode) | The OAuth Provider you configured, and the minimum scopes a user’s connection must have. | 5. Click **Create**. ### [](#configure-from-the-cli)Configure from the CLI For a managed server, set the auth method inside the `--managed-config` JSON. The `auth` field is required. #### API-key mode ```bash rpk ai mcp-server create --name acme-freshservice --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.freshservice.v1.FreshServiceMCPConfig", "domain": "mycompany.freshservice.com", "api_key": { "key_secret_ref": "FRESHSERVICE_API_KEY" } }' ``` #### User-OAuth mode ```bash rpk ai mcp-server create --name acme-freshservice-oauth --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.freshservice.v1.FreshServiceMCPConfig", "domain": "mycompany.freshservice.com", "user_oauth": { "provider_name": "freshservice-prod", "required_scopes": ["read", "write"] } }' ``` Replace `freshservice-prod` with the name of the OAuth Provider you configured. ## [](#tools)Tools The Freshservice MCP exposes tools across tickets, assets, changes, and agents: | Tool | Description | | --- | --- | | list_tickets | List tickets, with optional status, priority, and page filters. | | get_ticket | Fetch one ticket with its full description text and attachments. | | create_ticket | Open a new incident or service-request ticket. | | update_ticket | Update ticket fields such as status, priority, and assignee. | | list_assets | List CMDB assets, with optional type and page filters. | | get_asset | Fetch one asset with its dynamic type_fields. | | create_change | Open a new change request with planning fields. | | list_agents | List support agents, with optional active and email filters. | ### [](#example-list-open-tickets)Example: List open tickets ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-freshservice \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_tickets", "arguments": { "status": "open", "priority": "urgent" } } }' ``` Replace `` with your cluster ID and `$TOKEN` with a gateway access token. ### [](#example-create-a-ticket)Example: Create a ticket ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-freshservice \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "create_ticket", "arguments": { "subject": "Laptop will not boot", "description": "Reported by the Dresden office; powers on but no display.", "priority": 2, "status": 2 } } }' ``` ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | freshservice API error (status 401) | Confirm FRESHSERVICE_API_KEY matches the value from Profile Settings, and that the key’s Freshservice user has the roles the operation needs. | | freshservice API error (status 403) | The API key’s Freshservice user lacks permission for the resource (for example, assets or changes). Grant the role or use an account that has it. | | OAuthConnectionRequired (User-OAuth mode) | First call from a user with no stored token. The user completes the Freshservice OAuth consent flow, the token lands in the vault, and later calls reuse it. See User-delegated OAuth. | | scope_upgrade_required (User-OAuth mode) | The server’s required scopes were extended after users consented. Users re-consent with the higher scope. | > 📝 **NOTE** > > Freshservice error bodies are not forwarded to the caller, so tool errors carry only the HTTP status code. Reproduce the call against the Freshservice API directly to see the full error detail. ## [](#next-steps)Next steps - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) --- # Page 20: Grafana Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/grafana.md --- # Grafana Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Grafana Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/grafana page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/grafana.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/grafana.adoc description: Query Grafana dashboards, datasources, Prometheus metrics, and Loki logs from an agent, and create or update dashboards, using a service-account token. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Grafana managed MCP server with a service-account token learning-objective-2: Pick the right service-account role for read versus write workflows learning-objective-3: Search dashboards, query Prometheus and Loki, and upsert dashboards from the Inspector or an agent page-git-created-date: "2026-06-09" page-git-modified-date: "2026-07-29" --- The Grafana managed MCP server lets agents work with a Grafana instance: search dashboards and folders, list datasources, run PromQL queries against Prometheus datasources, run LogQL queries against Loki datasources, and create or update dashboards. After reading this page, you will be able to: - Configure the Grafana managed MCP server with a service-account token - Pick the right service-account role for read versus write workflows - Search dashboards, query Prometheus and Loki, and upsert dashboards from the Inspector or an agent ## [](#what-this-mcp-server-does)What this MCP server does Wraps Grafana’s HTTP API and proxies Prometheus and Loki queries through Grafana’s datasource proxy (`/api/datasources/proxy/uid/{uid}/…​`). A single base URL plus one service-account token covers both the core API and datasource queries, so the gateway makes no separate network connection to the metric or log backends. The tool surface is read-heavy. The one write tool is `create_or_update_dashboard`; there are no tools to mutate alerts or annotations. Authentication is a single shared service-account token, so every caller of this MCP server acts as that service account, and there is no per-user audit trail. Grafana exposes no OAuth client-registration flow for per-user delegation against an arbitrary instance, so the Grafana MCP server does not offer a User-OAuth mode. ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - A Grafana instance and its base URL (for example, `[https://myorg.grafana.net](https://myorg.grafana.net)`). - Permission to create a service account and a service-account token in Grafana. ## [](#get-grafana-credentials)Get Grafana credentials 1. In Grafana, go to **Administration > Users and access > Service accounts**. 2. Create a service account. Assign the Viewer role to use every read tool. To use `create_or_update_dashboard`, assign Editor (or a custom role with dashboard write permission) instead. 3. On the service account, select **Add service account token**, then copy the generated token (`glsa_…​`). It is shown only once. 4. Store the token in the Agentic Data Plane secret store under a name like `GRAFANA_SERVICE_ACCOUNT_TOKEN`. Note your instance base URL and, if your instance is multi-org, the numeric org ID. ## [](#configure)Configure Create a new Grafana MCP server in Agentic Data Plane: 1. Open **MCP Servers > Create Server**. 2. Pick `Grafana` from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the Grafana configuration form: | Field | Notes | | --- | --- | | base_url | Base URL of your Grafana instance (for example, https://myorg.grafana.net). | | org_id | Optional. The numeric organization ID for a multi-org instance. Omit it to use the token’s default organization. | | service_account_token | Secret-store reference holding the service-account token (for example, GRAFANA_SERVICE_ACCOUNT_TOKEN). UPPER_SNAKE_CASE. | 5. Click **Create**. ### [](#configure-from-the-cli)Configure from the CLI ```bash rpk ai mcp-server create --name acme-grafana --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.grafana.v1.GrafanaMCPConfig", "base_url": "https://myorg.grafana.net", "org_id": "1", "service_account_token": { "key_secret_ref": "GRAFANA_SERVICE_ACCOUNT_TOKEN" } }' ``` ## [](#tools)Tools The Grafana MCP exposes tools across dashboards, datasources, Prometheus, and Loki: | Tool | Description | | --- | --- | | search_dashboards | Search dashboards and folders by query (title substring), tags, and type (dash-db or dash-folder). Returns curated hits (uid, title, type, tags, url, folder). | | get_dashboard_summary | Fetch a curated summary of one dashboard by uid (title, tags, folder, and a compact per-panel list with each panel’s id, title, type, and datasource). | | list_datasources | List configured datasources (uid, name, type, is_default). Use the uid with the query tools. | | query_prometheus | Run an instant or range PromQL query against a Prometheus datasource (datasource_uid, expr, query_type, and time arguments). Returns the raw Prometheus result JSON. | | list_prometheus_metric_names | List metric names in a Prometheus datasource (datasource_uid, optional limit). | | list_prometheus_label_names | List label names in a Prometheus datasource (datasource_uid). | | list_prometheus_label_values | List the values of one label in a Prometheus datasource (datasource_uid, label). | | query_loki_logs | Run a LogQL query against a Loki datasource over a time range (datasource_uid, query, start, end, limit, direction). Returns the raw Loki result JSON. | | list_loki_label_names | List label names in a Loki datasource (datasource_uid, optional start and end). | | list_loki_label_values | List the values of one label in a Loki datasource (datasource_uid, label, optional start and end). | | create_or_update_dashboard | Create a dashboard or update an existing one (upsert on the model’s uid). Arguments: dashboard_json, folder_uid, overwrite, message. Requires an Editor service account. | ### [](#example-list-datasources)Example: List datasources ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-grafana \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_datasources", "arguments": {} } }' ``` Replace `` with your cluster ID and `$TOKEN` with a gateway access token. ### [](#example-run-an-instant-promql-query)Example: Run an instant PromQL query Find the Prometheus datasource `uid` with `list_datasources` first, then query it: ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-grafana \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "query_prometheus", "arguments": { "datasource_uid": "PBFA97CFB590B2093", "expr": "up", "query_type": "PROM_QUERY_TYPE_INSTANT" } } }' ``` ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | 401 Unauthorized | Confirm GRAFANA_SERVICE_ACCOUNT_TOKEN matches the token Grafana showed at creation, and that the service account is enabled. | | 403 Forbidden on create_or_update_dashboard | The service account has the Viewer role. Assign Editor (or a role with dashboard write permission). | | Wrong organization’s data | The token resolves to its default organization. Set the org_id field to target a specific organization on a multi-org instance. | ## [](#next-steps)Next steps - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) - [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) --- # Page 21: Ironclad Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/ironclad.md --- # Ironclad Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Ironclad Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/ironclad page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/ironclad.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/ironclad.adoc description: Read and manage contracts in Ironclad CLM. Per-user OAuth so each agent action runs as the calling end-user with their own Ironclad permissions. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Ironclad managed MCP server with per-user OAuth learning-objective-2: Pick the right region and scopes for your tenant learning-objective-3: List, fetch, and launch contract workflows from an agent page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-29" --- The **Ironclad** managed MCP server gives an LLM read and write access to [Ironclad](https://ironcladapp.com/), a contract lifecycle management (CLM) platform. Useful for agents that need to find contracts, check signature status, launch new contracts from templates, or retrieve executed documents. After reading this page, you will be able to: - Configure the Ironclad managed MCP server with per-user OAuth - Pick the right region and scopes for your tenant - List, fetch, and launch contract workflows from an agent ## [](#what-this-mcp-server-does)What this MCP server does Per-user OAuth 2.0 (Authorization Code grant). No static API key is stored in the MCP config; each user authorizes their own Ironclad account through AI Gateway’s OAuth flow. It is **not** a replacement for the Ironclad web UI for complex workflow management or template authoring. ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - An Ironclad tenant where you can register an OAuth app. - An [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) configured in Redpanda Agentic Data Plane for Ironclad. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). - Familiarity with [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). ## [](#get-ironclad-credentials)Get Ironclad credentials Set up the OAuth app on Ironclad and the matching OAuth Provider in Agentic Data Plane: 1. Log in to your Ironclad account and go to **Settings > API > OAuth Apps**. 2. Create a new OAuth app. Set the redirect URI to your AI Gateway callback URL (typically `https://aigw..clusters.rdpa.co/oauth/v1/callback`). 3. Select the following scopes: - `public.workflows.readWorkflows` - `public.workflows.readSchemas` - `public.workflows.createWorkflows` - `public.workflows.readDocuments` 4. Copy the `Client ID` and `Client Secret`. 5. In Agentic Data Plane, register an OAuth Provider with: - **Authorization endpoint**: `https://na1.ironcladapp.com/oauth/authorize` (use `eu1` for EU-hosted accounts; `demo` for sandbox) - **Token endpoint**: `https://na1.ironcladapp.com/oauth/token` (adjust region accordingly) - The Client ID and a secret-store reference for the Client Secret ## [](#configure)Configure Create a new Ironclad MCP server in Agentic Data Plane: 1. Open **MCP Servers > Create Server**. 2. Pick `Ironclad` from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the Ironclad configuration form: | Field | Notes | | --- | --- | | region | IRONCLAD_REGION_NA (default), IRONCLAD_REGION_EU for EU-hosted accounts, or IRONCLAD_REGION_DEMO for sandbox testing. | | OAuth Provider | The Ironclad OAuth Provider you configured. | | Required scopes | public.workflows.readWorkflows, public.workflows.readSchemas, public.workflows.createWorkflows, public.workflows.readDocuments. | 5. Click **Create**. ### [](#configure-from-the-cli)Configure from the CLI Ironclad authenticates per-user through the Ironclad OAuth Provider you configured. Reference that provider in the managed config’s `userOauth.providerName` field. Ironclad supports per-user OAuth only, so the `userOauth` block is required. The `--user-oauth-provider` and `--user-oauth-scopes` flags apply to remote (`--url`) servers only. ```bash rpk ai mcp-server create --name my-ironclad --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.ironclad.v1.IroncladMCPConfig", "region": "IRONCLAD_REGION_NA", "userOauth": { "providerName": "ironclad" } }' ``` For EU-hosted accounts, use `"IRONCLAD_REGION_EU"`. For sandbox testing, use `"IRONCLAD_REGION_DEMO"`. `userOauth.providerName` is the resource name of the Ironclad OAuth Provider you registered. ## [](#tools)Tools The Ironclad MCP exposes the following tools: | Tool | Description | | --- | --- | | list_workflows | List contracts with optional status filter and page/per_page pagination. | | get_workflow | Get full details of a contract by workflow_id. | | list_workflow_schemas | List available contract templates with their field IDs. | | create_workflow | Launch a new contract from a template (schema_id + attributes_json). | | list_workflow_documents | List documents attached to a contract. | ### [](#example-find-all-contracts-awaiting-signature)Example: Find all contracts awaiting signature ```bash curl -X POST https://aigw..clusters.rdpa.co/mcp/v1/my-ironclad \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_workflows", "arguments": {"status": "signing", "per_page": 10} } }' ``` ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | OAuthConnectionRequired | First call from a user with no stored token. The user completes Ironclad’s OAuth consent flow, the token lands in the vault, and subsequent calls reuse it. | | scope_upgrade_required | Server’s required_scopes was extended after users had already consented. Users re-consent with the higher scope. | | Wrong region results | Confirm the Region field matches your Ironclad tenant. EU-hosted accounts use IRONCLAD_REGION_EU; sandbox tenants use IRONCLAD_REGION_DEMO. | | schema_id not found in create_workflow | Run list_workflow_schemas first to get valid IDs for your tenant. | ## [](#limitations)Limitations This page does not cover: - **Template authoring**: Define templates in the Ironclad web UI, then reference them by `schema_id`. - **eSignature flows**: Handled inside Ironclad; this MCP launches and reads workflow state. ## [](#next-steps)Next steps - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) --- # Page 22: Jira Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/jira.md --- # Jira Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Jira Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/jira page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/jira.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/jira.adoc description: Let agents search, read, and manage Jira issues using either a shared API token or each end-user's own Atlassian identity through user-delegated OAuth. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Jira managed MCP server with Basic authentication or Atlassian's OAuth flow learning-objective-2: Pick the right scopes for the tools your agents use learning-objective-3: Walk a user through the consent flow and verify the connection page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- The **Jira** managed MCP server lets agents search, read, and manage Jira issues. It authenticates with either a shared API token (Basic authentication) or, for per-user identity, user-delegated OAuth. With OAuth it’s the enterprise counterpart to [the Slack setup guide](https://docs.redpanda.com/agentic-data-plane/connect/managed/slack/), and Atlassian’s flow has its own scope model and quirks worth calling out. After reading this page, you will be able to: - Configure the Jira managed MCP server with Basic authentication or Atlassian’s OAuth flow - Pick the right scopes for the tools your agents use - Walk a user through the consent flow and verify the connection ## [](#what-this-mcp-server-does)What this MCP server does The Jira managed type exposes the following read tools: - `query`: Search for issues using a JQL query. Returns the matching issues as JSON. - `get_issue`: Retrieve a single issue by its key, for example `PROJ-123`. - `list_projects`: Return visible Jira projects, optionally filtered by a search query. - `get_transitions`: Return the available workflow transitions for an issue. It also exposes the following write tools: - `create_issue`: Create a new issue. - `update_issue`: Update fields on an existing issue. - `transition_issue`: Move an issue to a new workflow state. - `add_comment`: Add a comment to an issue. - `add_worklog`: Log time spent on an issue. - `create_issue_link`: Create a directional link between two issues. ## [](#prerequisites)Prerequisites - A Jira (Atlassian Cloud) site and its base URL, for example `[https://mycompany.atlassian.net](https://mycompany.atlassian.net)`. - Credentials for one of the following authentication modes: - `Basic auth`: An Atlassian account email and an API token from `id.atlassian.com`, with the token stored in the Redpanda Agentic Data Plane secret store. - `User-delegated OAuth`: An Atlassian OAuth 2.0 (3LO) app registered against `[https://api.atlassian.com](https://api.atlassian.com)`, plus an [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) in Redpanda Agentic Data Plane configured for Atlassian’s authorize/token URLs and carrying the app’s client credentials. See [Configure User-Delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). ## [](#atlassians-scope-model-user-delegated-oauth)Atlassian’s scope model (user-delegated OAuth) When you use user-delegated OAuth, Atlassian uses a granular, prefixed scope namespace. The tools need: | Scope | Allows | | --- | --- | | read:jira-user | Read user profile. | | read:jira-work | Read issues, projects, sprints, and so on. Required by the read tools. | | write:jira-work | Create and update issues, transitions, comments, and worklogs. Required by the write tools. | | offline_access | Issue a refresh token so Redpanda can refresh expired access tokens. Required for any long-lived MCP server: without it, tokens expire after one hour and users re-consent every time. | > 📝 **NOTE** > > Always include `offline_access` in `required_scopes`. Without it, `OAuthTokenExpired` will hit users every hour. ## [](#configure)Configure 1. Open **MCP Servers > Create Server**. 2. Pick **Jira** from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the Jira configuration form: - `Base URL`: Your Jira instance URL, for example `[https://mycompany.atlassian.net](https://mycompany.atlassian.net)`. - `Max results per page` (optional): Page size for paginated queries. Defaults to `50`. - `Auth`: Choose `Basic auth` or `User-delegated OAuth`. - For `Basic auth`: Provide the account email and the API-token secret reference. - For `User-delegated OAuth`: Pick the Atlassian OAuth Provider you configured, and set `Required scopes` to at least `read:jira-user`, `read:jira-work`, and `offline_access`. Add `write:jira-work` if your agents use the write tools. 5. Click **Create**. ## [](#test-the-consent-flow)Test the consent flow 1. Open the **Inspector** tab. 2. Run an issue-search tool with a small JQL filter. 3. The first call returns `OAuthConnectionRequired` with an Atlassian `authorize_url`. The Inspector surfaces it as a consent prompt. 4. Click **Authorize**. Atlassian asks you to pick a site (Cloud instance) and approve scopes. 5. Atlassian redirects back. Your connection appears under **My Connections** with a site label. 6. Re-run the search; results come back. ## [](#use-with-agents)Use with agents Point an agent at the `Server URL` on the server’s **Connection** tab. Each user calling the agent will trigger their own consent flow on first call. With user-delegated OAuth, define the server’s `required_scopes` to include every scope the tools need: Atlassian doesn’t allow per-tool scope upgrades, so the user consents once with the full set. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | OAuthTokenExpired after about an hour | offline_access wasn’t in required_scopes at consent time. Update the server config and have users re-consent. | | "Resource not found" for a project the user has access to | Atlassian’s OAuth grants are site-scoped. The user authorized for one Cloud instance; the project lives on another. They need to re-consent with the second site. | | scope_upgrade_required after widening scopes | You added a scope to required_scopes after users had already consented. Users re-consent with the higher scope. | | invalid_grant during refresh | Refresh tokens expire if unused for ~90 days. The user re-consents. | ## [](#limitations)Limitations - **Atlassian app management**: The OAuth app and its callback URLs are managed in `developer.atlassian.com`, not in Agentic Data Plane. - **Jira Server / Data Center** (self-hosted): This MCP type targets Atlassian Cloud. Self-hosted Jira may need a self-managed MCP server instead. See [Register a self-managed MCP server](https://docs.redpanda.com/agentic-data-plane/connect/register-remote/). - **Confluence access**: Separate scope namespace; not exposed by this MCP server. ## [](#next-steps)Next steps - [Configure User-Delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) - [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) --- # Page 23: Kafka Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/kafka.md --- # Kafka Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Kafka Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/kafka page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/kafka.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/kafka.adoc description: Produce messages to topics on Kafka or Redpanda brokers through a managed MCP server hosted in the Agentic Data Plane. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Kafka managed MCP server against a Kafka or Redpanda cluster learning-objective-2: Produce a test message through the Inspector learning-objective-3: Pick the right SASL mechanism for your broker (PLAIN or SCRAM-SHA-256/512) page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- The **Kafka** managed MCP server lets agents produce messages to topics on either an Apache Kafka cluster or a Redpanda cluster. Despite the name, it works against any Kafka-compatible broker. After reading this page, you will be able to: - Configure the Kafka managed MCP server against a Kafka or Redpanda cluster - Produce a test message through the Inspector - Pick the right SASL mechanism for your broker (PLAIN or SCRAM-SHA-256/512) ## [](#what-this-mcp-server-does)What this MCP server does The Kafka managed type proxies a managed Kafka producer. It exposes the following tool: - `produce`: Send a message to a Kafka topic, with an optional key, an optional partition, and optional headers. Consuming messages, listing topics, and inspecting metadata are not currently exposed by this managed type. To read from topics, use a [self-managed MCP server](https://docs.redpanda.com/agentic-data-plane/connect/register-remote/) or Redpanda Connect. ## [](#prerequisites)Prerequisites - A Kafka or Redpanda cluster reachable from the Agentic Data Plane. - The cluster’s bootstrap servers and SASL/TLS settings. - For SCRAM or PLAIN: Secrets in the Redpanda Agentic Data Plane secret store for the username and password (`UPPER_SNAKE_CASE`, for example `KAFKA_SASL_USER` and `KAFKA_SASL_PASSWORD`). ## [](#configure)Configure 1. Open **MCP Servers > Create Server**. 2. Pick **Kafka** from the marketplace picker. 3. Fill in the identity fields (`name`, `description`). 4. In the Kafka configuration form, provide: - `Seed brokers`: Bootstrap broker addresses for the cluster. - `TLS`: Enable for production. You can optionally skip certificate verification for local development only. - `SASL mechanism`: `PLAIN`, `SCRAM-SHA-256`, or `SCRAM-SHA-512`. Leave empty to disable SASL. - `Username / password`: `UPPER_SNAKE_CASE` secret references for the SASL credentials. - `Compression` (optional): Defaults to `lz4`. - `Max in-flight` (optional): Maximum number of in-flight produce requests. Defaults to `10`. - `Timeout` (optional): Produce request timeout. Defaults to `10s`. 5. Click **Create**. ## [](#test)Test 1. Open the **Inspector** tab on the server’s detail page. 2. In **Tools**, select the `produce` tool. 3. Produce a test message to a sandbox topic and confirm a successful response. 4. Verify the message landed by consuming the topic with `rpk topic consume` or another Kafka client. See [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) for general Inspector usage. ## [](#authentication)Authentication The Kafka managed type’s authentication is part of its config, not the generic MCP authentication modes: it uses Kafka protocol authentication (SASL over TLS), not MCP authentication. | Mechanism | Use when | | --- | --- | | PLAIN | Username and password over TLS. Common for managed Kafka services. | | SCRAM-SHA-256 / SCRAM-SHA-512 | Salted challenge-response. Default for Redpanda. | TLS controls transport encryption: enable it, and optionally skip certificate verification for development. Client-certificate (mTLS) and `OAUTHBEARER` authentication are not currently supported by this managed type. ## [](#use-with-agents)Use with agents After the Kafka server is created, point an agent at the `Server URL` on the server’s **Connection** tab. The agent can then produce messages to topics through the exposed `produce` tool. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | connection refused or dial timeout | Brokers aren’t reachable from Agentic Data Plane egress. Confirm bootstrap addresses and any private-network requirements. | | SASL authentication failed | Check username/password reference content and the SASL mechanism. | | TLS handshake error | Certificate chain isn’t trusted, or you’ve enabled TLS against a plaintext broker. Confirm broker config. | | unknown topic or partition | The target topic doesn’t exist on the broker. Create it first, or confirm the topic name. | ## [](#limitations)Limitations - **Reading and administration**: This server only produces messages. Consuming, listing topics, and managing topics or ACLs aren’t exposed. Use rpk, a Kafka client, or Redpanda Connect. - **Schema registry**: Not exposed by this MCP server. - **Streaming joins or processing**: For stream processing, use Redpanda Connect. --- # Page 24: Plug in an App, Database, or Tool **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog.md --- # Plug in an App, Database, or Tool > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Plug in an App, Database, or Tool latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/managed-catalog page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/managed-catalog.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/managed-catalog.adoc description: Reference of every managed MCP server type Redpanda hosts in-process, grouped by category, with display name, description, and a link to a setup guide where one exists. page-topic-type: reference personas: agent_builder, platform_engineer page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- Managed MCP servers are in-process implementations Redpanda hosts for you. Each type has a fixed set of [tools](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#tool) and a type-specific configuration schema. To create one, open **MCP Servers > Create Server** in Redpanda Agentic Data Plane and pick the type from the marketplace picker. See [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) for the full create flow. This catalog lists the managed MCP server types Redpanda registers by default, grouped by category. ## [](#choosing-managed-vs-self-managed)Choosing managed vs. self-managed | Question | Choose managed when… | | --- | --- | | Who hosts and operates the server? | You want Redpanda to host it. | | Where do upstream credentials live? | You’re happy storing them in the Agentic Data Plane secret store. | | Do you need custom tool logic? | The fixed tool set of the managed type covers your use case. | | Do you need per-user identities at the upstream? | The managed type supports user-delegated OAuth for that system. | If any of these answers are "no," prefer [a self-managed server](https://docs.redpanda.com/agentic-data-plane/connect/register-remote/) instead. ## [](#ai)AI | Display name | Description | Setup guide | | --- | --- | --- | | AWS Bedrock (Preview) | Invoke foundation models (Claude, Llama, Titan) and generate embeddings on AWS Bedrock. | | | Cohere (Preview) | Generate embeddings and chat completions with the Cohere API. | | | OpenAI (Preview) | Chat completions, embeddings, and tools with the OpenAI API. | | ## [](#aws)AWS | Display name | Description | Setup guide | | --- | --- | --- | | AWS S3 (Preview) | Read, write, and manage objects in Amazon S3 buckets. | | | AWS SNS (Preview) | Publish and manage topics on AWS Simple Notification Service. | | | AWS SQS (Preview) | Send, receive, and manage messages on AWS Simple Queue Service. | | ## [](#communication)Communication | Display name | Description | Setup guide | | --- | --- | --- | | Discord (Preview) | Post messages, read channels, and manage servers on Discord. | | | Freshservice (Preview) | Manage ITSM tickets, assets, and change requests in Freshworks Freshservice. | Setup guide | | GitHub (Read) | Read-only access to GitHub repositories, pull requests, commits, and code. | Setup guide | | Jira (Preview) | Manage Jira issues, projects, and workflows. | Setup guide | | Pylon (Preview) | Search and manage Pylon issues, accounts, contacts, and knowledge-base articles. | | | ServiceNow (Preview) | Create and manage ServiceNow incidents, knowledge articles, and records. | Setup guide | | Slack (Preview) | Post messages and read channels on Slack. | Setup guide | | Zendesk (Preview) | Search and manage Zendesk Support tickets, users, and Help Center articles. | Setup guide | ## [](#database)Database | Display name | Description | Setup guide | | --- | --- | --- | | Elasticsearch (Preview) | Query and index documents in an Elasticsearch cluster. | | | Metabase (Preview) | Search tables and metrics, run queries, and inspect saved questions in Metabase. | Setup guide | | MongoDB (Preview) | Query collections and documents in MongoDB. | | | Qdrant (Preview) | Vector search over a Qdrant collection. | | | Redis (Preview) | Read, write, and query keys in Redis. | | | SQL (Preview) | Query SQL databases (Postgres, MySQL, ClickHouse, MSSQL, SQLite) with MCP. | Setup guide | ## [](#google)Google | Display name | Description | Setup guide | | --- | --- | --- | | GCP Pub/Sub (Preview) | Publish and subscribe to topics on Google Cloud Pub/Sub. | | | Gmail (Preview) | Read and send emails through Gmail with a service account or per-user OAuth. | | | Google Calendar | Read and manage Google Calendar events and schedules. | | | Google Drive | Read and search files in Google Drive. | | ## [](#streaming)Streaming | Display name | Description | Setup guide | | --- | --- | --- | | Kafka (Preview) | Produce, consume, and inspect topics on Kafka or Redpanda brokers. | Setup guide | | NATS (Preview) | Publish and subscribe on NATS and NATS JetStream. | | ## [](#utility)Utility | Display name | Description | Setup guide | | --- | --- | --- | | Azure AD (Preview) | Manage Azure Active Directory users and groups with Microsoft Graph API. | | | BambooHR | Access employee directory, time-off, and performance data from BambooHR. | Setup guide | | BILL (bill.com) (Preview) | Manage accounts-payable bills, vendors, AR invoices, payments, and customers in BILL. | | | DocuSign (Preview) | Send, track, and manage DocuSign signing envelopes. | | | Grafana (Preview) | Query Grafana dashboards, datasources, Prometheus metrics and Loki logs, and create or update dashboards. | Setup guide | | Greenhouse (Preview) | Manage jobs, candidates, and applications in Greenhouse ATS. | | | Ironclad (Preview) | Read and manage contracts in Ironclad CLM. | Setup guide | | Morningstar Portfolio Analytics (Preview) | Run X-Ray, performance, risk-score, hypothetical, and ESG analytics on caller-supplied portfolios with Morningstar Direct Web Services. | | | Morningstar Securities (Preview) | Search, retrieve, screen, and pull research on funds and equities with the Morningstar Direct Web Services Investment Analysis API. | | | NetSuite (Preview) | Query Oracle NetSuite records and run SuiteQL with the SuiteTalk REST API. | Setup guide | | Okta (Preview) | Manage Okta users and groups. | | | OpenAPI (Preview) | Expose any OpenAPI/Swagger HTTP API as MCP tools. | Setup guide | | Ramp (Preview) | Manage Ramp corporate cards, transactions, spend limits, and reimbursements. | Setup guide | | Salesforce | Query, create, update, and delete Salesforce CRM records using SOQL and the REST API, and run and inspect saved Salesforce reports. | Setup guide | | Sentry (Preview) | Read-only access to Sentry organizations, projects, issues, events, and releases for diagnosing and fixing errors. | Setup guide | | SharePoint (Preview) | Access SharePoint sites, document libraries, lists, and files through the Microsoft Graph API. | Setup guide | | Text Chunker (Preview) | Split and chunk text for RAG and LLM ingestion pipelines. | | | Workday (Preview) | Drive Workday Human Resources business processes with SOAP. | Setup guide | ## [](#next-steps)Next steps - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) - [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) - [Configure User-Delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) --- # Page 25: Metabase Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/metabase.md --- # Metabase Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Metabase Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/metabase page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/metabase.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/metabase.adoc description: Give an LLM agent read-and-query access to a Metabase analytics instance through the semantic layer (search, get_table, query metrics) and SQL escape hatches (run_native_query, run_card). page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Metabase managed MCP server with a v0.49+ API key bound to the right Metabase group learning-objective-2: Identify when to use semantic-layer tools (search, get_metric, query) versus the native-SQL escape hatches (run_native_query, run_card) learning-objective-3: Run a metric-first analysis against your Metabase instance from the Inspector or an agent page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- The **Metabase** managed MCP server lets agents read and query a Metabase analytics instance. The tool surface is a hybrid of Metabase’s semantic-layer primitives (tables, metrics, fields, dimensions) and SQL-first escape hatches (native queries and saved questions), wrapping the Metabase REST API with a long-lived API key. After reading this page, you will be able to: - Configure the Metabase managed MCP server with a v0.49+ API key bound to the right Metabase group - Identify when to use semantic-layer tools (`search`, `get_metric`, `query`) versus the native-SQL escape hatches (`run_native_query`, `run_card`) - Run a metric-first analysis against your Metabase instance from the Inspector or an agent ## [](#what-this-mcp-server-does)What this MCP server does Metabase is a self-service analytics platform that exposes data through a **semantic layer** (tables, metrics, fields) plus a SQL editor for ad-hoc native queries. This MCP wraps the Metabase REST API so an LLM can: - Search the semantic layer for relevant tables, metrics, saved questions, and dashboards. - Retrieve a table or metric’s structure (fields, dimensions, related tables). - Run a structured query against a metric or table with filters, group-by, and limits. - Run a saved question (card) or a hand-written native SQL query. The agent’s preferred path is **metric-first**: discover what already exists, fetch the metric’s definition, and call `query` against it so the aggregation logic stays human-vetted. The SQL escape hatches (`run_native_query`, `run_card`) are available when the semantic layer cannot express the question, but a metric is strictly safer because it forecloses common analytics mistakes (averaging averages, double-counting joined rows). It is **not** a Metabase admin tool. Creating dashboards, editing cards, configuring data sources, and managing users live in the Metabase admin UI. ## [](#authentication-model)Authentication model Metabase API keys (v0.49+) inherit the **permissions of the group they’re bound to**. The MCP sends the resolved key in the `X-API-Key` header on every upstream request. The Metabase MCP uses one API key per MCP instance, applied to every tool call, with no per-user delegation. To give different agents different access, mount multiple MCP instances bound to different Metabase groups. Auth is implemented as `oneof auth { StaticKeyAuth api_key }` (single variant today, future-proof for adding session or OAuth modes without a wire-format break). ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - A Metabase instance on v0.49 or later (API keys are not available on older versions). - Admin access to the Metabase instance to mint an API key. - A Metabase **group** with the right permissions for the data you want the agent to access (typically `Native query editing` on the relevant databases plus `View` on the relevant collections). - One Redpanda Agentic Data Plane secret-store entry for the API key. Secret references must be `UPPER_SNAKE_CASE`, for example `METABASE_API_KEY`. ## [](#get-a-metabase-api-key)Get a Metabase API key Mint the key in the Metabase admin UI: 1. Sign in to your Metabase instance as an admin. 2. Open **Settings > Authentication > API keys**. 3. Click **Create API key**. 4. Give the key a descriptive name, for example `redpanda-mcp`. 5. Bind the key to a group whose permissions match the access you want the agent to have. For an analytics agent, an `Analytics` group with `Native query editing` on the relevant databases and `View` on the relevant collections is typical. 6. Copy the key. Metabase shows it only once. 7. Save the key in your Agentic Data Plane secret store under a name like `METABASE_API_KEY`. > 📝 **NOTE** > > Permission errors surface from the upstream Metabase API as `metabase API error (status 4xx)`. Fix by adjusting the bound group’s permissions in Metabase, not by re-issuing a different key. ## [](#configure)Configure Create a new Metabase MCP server in Agentic Data Plane: 1. Open **MCP Servers > Create Server**. 2. Pick **Metabase** from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the Metabase configuration form: | Field | Notes | | --- | --- | | Base URL | Your Metabase instance URL, for example https://metabase.mycompany.com. No trailing slash. | | API key ref | Secret-store reference for the Metabase API key (UPPER_SNAKE_CASE). Example: METABASE_API_KEY. | 5. Click **Create**. ### [](#configure-from-the-cli)Configure from the CLI Run `rpk ai mcp-server create` with the Metabase managed-config payload: ```bash rpk ai mcp-server create --name metabase --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.metabase.v1.MetabaseMCPConfig", "base_url": "https://metabase.mycompany.com", "api_key": { "key_secret_ref": "METABASE_API_KEY" } }' ``` The `api_key` field wraps the shared `StaticKeyAuth`; `key_secret_ref` is the bare secret-store key name (`UPPER_SNAKE_CASE`). ## [](#tools)Tools The Metabase MCP exposes tools across a semantic-layer surface and a SQL-first surface. The agent’s preferred path is the semantic-layer surface; the SQL-first surface is an escape hatch. ### [](#semantic-layer-tools)Semantic-layer tools These six tools cover discovery, schema lookup, and structured queries against pre-vetted metrics. | Tool | Description | | --- | --- | | search | Run Metabase’s universal search across tables, metrics, saved questions, dashboards, and collections. Use this first to discover existing analyses before constructing a fresh query. | | get_table | Retrieve a table’s fields, related tables, and metrics defined on it. The field list is what the agent uses to write correct filters and group-bys. | | get_table_field_values | Sample values plus a small statistical summary for one field on a table. Useful before writing a filter; the agent can check actual cardinality and value shape rather than guessing. | | get_metric | Retrieve a metric definition with its queryable dimensions. Metrics are pre-vetted aggregations; calling query against a metric is strictly preferred over hand-rolled SQL when the measure already exists. | | get_metric_field_values | Sample values for a dimension of a metric. Same role as get_table_field_values, scoped to a metric’s queryable dimensions. | | query | One-shot structured query against a table OR a metric, with optional group_by_field_ids, filters (MBQL JSON snippets), and limit. Returns typed columns and rows. | ### [](#sql-first-escape-hatches)SQL-first escape hatches These five tools let an agent enumerate databases, run native SQL, and execute saved questions when the semantic layer cannot express the question. | Tool | Description | | --- | --- | | list_databases | Enumerate the databases Metabase is connected to. The id returned here is what get_table, list_tables, run_native_query, and query take as the database reference. | | list_tables | List tables in a database, optionally filtered by schema. Use this when browsing schema by name; search is the right tool when looking by keyword. | | run_native_query | Execute a native (raw SQL) query against a database. Escape hatch for cases the semantic layer cannot express; prefer query against a metric or table when possible. | | get_card | Retrieve a saved question’s definition (name, description, database, display type, native SQL when applicable). Use this to inspect an analysis a human curated. | | run_card | Execute a saved question and return its result rows. The card carries its own database, query, and parameters; this RPC just runs it as-is. | ## [](#examples)Examples The examples in this section assume `[https://aigw..clusters.rdpa.co/mcp/v1/metabase](https://aigw.\.clusters.rdpa.co/mcp/v1/metabase)` is your MCP server URL and that you’ve already authenticated to the gateway. ### [](#discover-what-exists-then-query-a-metric)Discover what exists, then query a metric Search for revenue-related objects: ```bash curl -sS -X POST https://aigw..clusters.rdpa.co/mcp/v1/metabase \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search", "arguments": { "q": "revenue", "models": ["metric", "card"], "page_size": 10 } } }' | jq ``` If `search` returns a metric like `{ "model": "metric", "id": 200, "name": "Monthly Revenue", …​ }`, fetch its dimensions: ```bash curl -sS -X POST https://aigw..clusters.rdpa.co/mcp/v1/metabase \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "get_metric", "arguments": { "metric_id": 200 } } }' | jq ``` Then run the metric grouped by one of its dimensions (the `field_id` values come from the previous response’s `dimensions[]`): ```bash curl -sS -X POST https://aigw..clusters.rdpa.co/mcp/v1/metabase \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "query", "arguments": { "database_id": 5, "metric_id": 200, "group_by_field_ids": [12], "limit": 1000 } } }' | jq ``` ### [](#native-sql-escape-hatch)Native SQL escape hatch When a question genuinely needs raw SQL (for example, multi-CTE windowed analysis Metabase’s MBQL doesn’t express), drop down to `run_native_query`: ```bash curl -sS -X POST https://aigw..clusters.rdpa.co/mcp/v1/metabase \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "run_native_query", "arguments": { "database_id": 5, "query": "SELECT date_trunc(\"month\", created_at) AS m, count(*) FROM orders GROUP BY 1 ORDER BY 1 DESC LIMIT 12" } } }' | jq ``` The bound group’s permissions on the target database determine whether the call succeeds. A key bound to a group without `Native query editing` on the database returns a 403. ## [](#notes-and-limits)Notes and limits Five behaviors are worth knowing before you point an agent at the server: - **Permissions follow the API key’s group.** The MCP doesn’t bypass Metabase’s permission system; permission errors surface as `metabase API error (status 4xx)`. Fix the group, not the MCP. - **Metric vs. saved question.** In Metabase v0.50+ both metrics and saved questions are stored as cards (`/api/card/:id`). `get_metric` validates that the card’s `type == "metric"` and surfaces queryable dimensions; `get_card` works on any card. `run_card` runs whatever is saved. - **Sample database.** The `list_databases` tool exposes Metabase’s bundled Sample Database with an `is_sample` flag set. Agents should usually exclude it from real analyses. - **Body cap.** Query results are capped at 25 MiB on the gateway-side wrapper. Queries that exceed the cap return an error rather than blowing up the agent’s context. Lower the `limit` argument on `query` or `run_native_query` if you hit it. - **Response curation.** The MCP drops Metabase’s internal indexing metadata (search ranking signals, fingerprint blobs, embedded user objects, per-column metadata blobs) so each response is 60–85% smaller than the raw REST API would return. Agents see clean, action-relevant fields. ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | metabase API error (status 401) | API key is invalid or has been revoked. Mint a new key in Settings > Authentication > API keys and update the secret in the Agentic Data Plane secret store under the same name. | | metabase API error (status 403) | The API key’s group lacks the required permission. Check the group’s database and collection permissions in Admin > Permissions. | | metabase API error (status 404) on get_table or get_metric | The table_id or metric_id doesn’t exist in the bound database. Confirm the ID with search or list_tables first. | | Query returns an error about exceeding the body cap | Result set exceeds 25 MiB. Lower limit on the query, or pre-aggregate by calling query against a metric. | | Agent keeps calling run_native_query instead of query | Confirm the relevant metric exists and has queryable dimensions. The agent prefers metrics when search or get_table surfaces them. | ## [](#limitations)Limitations This page does not cover: - **Metabase administration.** Creating dashboards, editing cards, configuring data sources, and managing users live in the Metabase admin UI or its `/api/setup` endpoints. - **Per-user delegation.** The MCP uses one shared API key per instance. To give different agents different access, mount multiple MCP instances bound to different Metabase groups. - **Metabase MBQL reference.** See Metabase’s own documentation for the full MBQL filter shape; the MCP passes `filters` arguments through verbatim. ## [](#next-steps)Next steps - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) - [Test a server’s tools](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) - [Plug in an App, Database, or Tool](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/) --- # Page 26: NetSuite Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/netsuite.md --- # NetSuite Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: NetSuite Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/netsuite page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/netsuite.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/netsuite.adoc description: Let agents read NetSuite records and run SuiteQL with each caller's NetSuite OAuth identity. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the NetSuite managed MCP server with account ID and user-delegated OAuth learning-objective-2: Identify the NetSuite read-only tools available to agents learning-objective-3: Test NetSuite tool calls with an authorized user's connection page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-29" --- The **NetSuite** managed MCP server lets agents query Oracle NetSuite records and run SuiteQL with the calling user’s OAuth identity. The server wraps SuiteTalk REST APIs and exposes read-only tools for records, customers, sales orders, and items. After reading this page, you will be able to: - Configure the NetSuite managed MCP server with account ID and user-delegated OAuth - Identify the NetSuite read-only tools available to agents - Test NetSuite tool calls with an authorized user’s connection ## [](#what-this-mcp-server-does)What this MCP server does Use NetSuite when an agent needs ERP, finance, or accounting context from records that a NetSuite user can already read. Every tool is read-only. | Tool | What it does | | --- | --- | | suite_ql_query | Runs a SuiteQL query and returns rows as JSON. Use this tool for joins, aggregates, and cross-record analysis. | | get_record | Fetches one record by record type and internal ID. You can expand sub-resources, such as line items and addresses. | | list_records | Lists records of a type with optional NetSuite filter expression and paging. Use typed helpers when they fit. | | get_customer | Fetches a customer record by internal ID. | | list_customers | Lists customers with optional company name, email, modified-since, inactive, and paging filters. | | list_sales_orders | Lists sales orders with optional customer ID, date range, status, modified-since, and paging filters. | | search_items | Searches inventory and service items by SKU, display name, item type, inactive flag, and paging filters. | The managed server does not expose write tools, saved-search execution, or report execution. ## [](#prerequisites)Prerequisites - A NetSuite Integration Record that uses OAuth 2.0 Authorization Code grant. - A NetSuite [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) in Redpanda Agentic Data Plane for the same account. - Your NetSuite account ID. Production accounts use a numeric ID such as `1234567`. Sandbox accounts include a suffix such as `1234567_SB1`; release-preview accounts can use a suffix such as `1234567_RP1`. - NetSuite users with the **REST Web Services** permission on at least one role. ## [](#configure-netsuite-oauth)Configure NetSuite OAuth In NetSuite, create an Integration Record with OAuth 2.0 enabled. Set the redirect URI to the OAuth callback URL for your AI Gateway deployment. Select the **REST Web Services** scope. Find your account ID under **Setup > Company > Company Information > ACCOUNT ID**. The managed server normalizes underscores to hyphens when it builds the SuiteTalk host. Register a NetSuite OAuth Provider in Agentic Data Plane with account-scoped endpoints: ```text Authorization endpoint: https://.app.netsuite.com/app/login/oauth2/authorize.nl Token endpoint: https://.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token Scopes: rest_webservices ``` Store the NetSuite client secret in the Agentic Data Plane secret store, then reference that secret from the OAuth Provider. ## [](#create-the-managed-mcp-server)Create the managed MCP server Create a managed MCP server with the NetSuite type. NetSuite authentication is part of the managed config, so include `user_oauth` inside the JSON. ```json { "@type": "type.googleapis.com/redpanda.mcps.netsuite.v1.NetSuiteMCPConfig", "account_id": "1234567_SB1", "user_oauth": { "provider_name": "netsuite", "required_scopes": ["rest_webservices"] } } ``` For a non-UI path, use `rpk ai mcp-server create` with `--managed-config`. The top-level `--user-oauth-provider` and `--user-oauth-scopes` flags apply to self-managed servers only. ```bash rpk ai mcp-server create --name netsuite \ --description "NetSuite ERP with user OAuth" \ --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.netsuite.v1.NetSuiteMCPConfig", "account_id": "1234567_SB1", "user_oauth": { "provider_name": "netsuite", "required_scopes": ["rest_webservices"] } }' ``` ## [](#authorize-and-test)Authorize and test Before a caller can use NetSuite tools, the caller must authorize the NetSuite OAuth Provider. After authorization, Redpanda stores the user’s access token in the token vault and subsequent tool calls use that token automatically. Test the server in the Inspector before you connect it to an agent. Start with a narrow `suite_ql_query`, `get_customer`, or `list_customers` call to confirm that NetSuite returns records visible to the authorized user. ## [](#netsuite-query-notes)NetSuite query notes NetSuite record filters use NetSuite-specific forms: - Use `CONTAIN` for substring filters, not `CONTAINS`. - Use `M/D/YYYY` date literals for REST collection filters. - Match reference fields by internal ID. For example, sales-order customer filters use `entity ANY_OF [12345]`. - Use NetSuite status IDs such as `_pendingFulfillment` for sales-order status filters, not display labels. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | Tool calls return 403 | Confirm the authorizing NetSuite user has the REST Web Services permission. | | OAuth succeeds, but tool calls fail | Confirm the OAuth Provider endpoints and the MCP server account_id refer to the same NetSuite account. | | A sales-order status filter returns no rows | Use the NetSuite internal status ID, such as _pendingFulfillment, instead of the display label. | ## [](#next-steps)Next steps - [Configure User-Delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) - [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) --- # Page 27: OpenAPI Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/openapi.md --- # OpenAPI Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: OpenAPI Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/openapi page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/openapi.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/openapi.adoc description: Expose any OpenAPI 3.x-described HTTP API as MCP tools. Point Redpanda at a spec URL and get a fully-typed tool surface for agents, with no custom code. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the OpenAPI managed MCP server against an OpenAPI 3 spec learning-objective-2: Pick the right authentication mode for the upstream API learning-objective-3: Verify generated tools through the Inspector page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- The **OpenAPI** managed MCP server is the "bring your own API" escape hatch. Hand it an OpenAPI 3.x spec, and it generates one MCP tool per operation in the spec. No custom code, no per-API managed type: useful when the API you want to expose is not in the catalog. After reading this page, you will be able to: - Configure the OpenAPI managed MCP server against an OpenAPI 3 spec - Pick the right authentication mode for the upstream API - Verify generated tools through the Inspector ## [](#what-this-mcp-server-does)What this MCP server does The OpenAPI managed type: - Loads an OpenAPI 3.x spec (3.0 or 3.1) from a URL or pasted JSON/YAML. Swagger 2.0 specs are not supported. - Generates one MCP tool per operation, with input schemas derived from the spec’s parameter and request-body schemas. `oneOf`, `anyOf`, and `discriminator` are supported; `callbacks` are not. - Forwards calls to the upstream API, applying the configured authentication. By default the generator walks schemas up to a depth of 5 (`max_schema_depth`); schemas nested deeper than that are truncated. ## [](#prerequisites)Prerequisites - An HTTP API with an OpenAPI 3.x spec. - The spec URL or the spec content itself. - Credentials for the API, if it requires them. ## [](#configure)Configure 1. Open **MCP Servers > Create Server**. 2. Pick **OpenAPI** from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the OpenAPI configuration form: - `Spec`: A URL to the OpenAPI 3.x spec (JSON or YAML), or paste the spec inline. Set exactly one. Inline specs are capped at 3 MiB; host larger specs and use the URL instead. - `Base URL` (optional): Useful when the spec’s `servers` block doesn’t match your environment. - `Operation filter` (optional): Include or exclude operations by tag, `operationId` glob, path glob, or HTTP method. - `Max schema depth` (optional): Maximum depth for schema conversion. Defaults to 5. - `Extract headers` (optional): Response header names to surface to the agent, such as `X-CSRF-Token` or `Set-Cookie`. Listed headers are appended to the tool result; all other response headers are dropped. Matching is case-insensitive. 5. Configure authentication (see [Authentication](#authentication)). 6. Click **Create**. ## [](#authentication)Authentication OpenAPI is the most flexible managed type for authentication: the upstream API can need anything. All the standard authentication modes apply: | Mode | Use when | | --- | --- | | No Auth | Public APIs (rare in practice). | | Bearer | API expects a bearer token. The handler sends Authorization: Bearer . | | API Key | API expects a key in a header or query parameter. Choose the placement and the parameter name. | | Basic | API expects HTTP Basic authentication (a username and password). | | User OAuth | API supports OAuth on behalf of users and you want per-user identities. Requires an OAuth Provider configured for that API. See Configure User-Delegated OAuth. | | Service-account OAuth | API supports the OAuth client-credentials grant and you want a single shared service-account identity for every call, rather than per-user tokens. | For `Service-account OAuth`, the gateway runs the client-credentials exchange once per server and shares the resulting token across all callers. Supply the client ID, a secret-store reference for the client secret, the token URL, and any scopes the API requires. Store the client secret in the Agentic Data Plane secret store under an `UPPER_SNAKE_CASE` key, such as `OAUTH_CLIENT_SECRET`, and reference it from the form. Use an `https` token endpoint. ## [](#test)Test 1. Open the **Inspector** tab. 2. The Tools panel lists every operation from your spec, named per the `operationId` (or per the path if `operationId` is missing). Tool names longer than 64 characters are truncated and given a short hash suffix to keep them unique, because LLM providers cap tool-name length. Parameter names that start with `$` (common in OData APIs, such as `$top` and `$filter`) appear without the `$` prefix in the tool schema; the server still sends the original parameter name to the API. 3. Pick one and run it. The Inspector renders a form from the operation’s parameter and request-body schemas. See [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) for general Inspector usage. ## [](#use-with-agents)Use with agents After tools generate cleanly, point an agent at the `Server URL` on the server’s **Connection** tab. The agent sees one tool per OpenAPI operation, named accordingly. Each tool returns the upstream response as a structured result with the fields `status_code`, `headers`, and `body`. `body` is the parsed JSON payload when the response is JSON, or the raw response text otherwise. `headers` holds the response headers you selected with `Extract headers`, and is empty when none are configured. Agents that read structured output can address these fields directly, and a plain-text copy of the same result is also included for clients that read only text. A 4xx or 5xx response surfaces as a tool error rather than a structured result. Every generated tool also accepts an optional `headers` input, which lets the agent set request headers the spec doesn’t declare. Agent-supplied headers can’t override the configured authentication headers or the spec’s own header parameters. Combined with `Extract headers`, this supports APIs that round-trip headers, such as a CSRF token fetched from one response and echoed on the next request. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | "Failed to load spec" | Confirm the spec URL is reachable from Redpanda Agentic Data Plane and serves valid JSON or YAML. CORS doesn’t matter (Redpanda fetches server-side). | | Tools list doesn’t include an expected operation | The operation may be missing an operationId, or the operation include/exclude filters might be excluding it. If two operations resolve to the same tool name, the server keeps one, drops the other, and logs a warning naming both. | | Tool input schema looks wrong | oneOf, anyOf, and discriminator are supported, but callbacks are not, and schemas deeper than max_schema_depth (default 5) are truncated. Adjust the spec or raise the depth. | | Calls return 401 | Authentication mode or credentials are wrong. Confirm secret content and the API’s expected authentication header. | | Calls return 404 with the right operation | servers block in the spec doesn’t match your real API endpoint. Use the Base URL field. | ## [](#limitations)Limitations - **Custom tool logic**: The OpenAPI type is purely a spec-to-tools generator. For business logic on top of the API, use a [self-managed MCP server](https://docs.redpanda.com/agentic-data-plane/connect/register-remote/). - **GraphQL APIs**: OpenAPI doesn’t describe GraphQL. For GraphQL APIs, use a self-managed server. - **gRPC services**: Same as GraphQL: use a self-managed server. --- # Page 28: Ramp Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/ramp.md --- # Ramp Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Ramp Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/ramp page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/ramp.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/ramp.adoc description: Manage Ramp corporate cards, transactions, spend limits, and reimbursements from an LLM agent. Per-user OAuth so each agent action runs as the calling end-user. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Ramp managed MCP server with per-user OAuth learning-objective-2: Pick the right scopes and environment for production vs sandbox learning-objective-3: List transactions, manage cards, and adjust spend limits from an agent page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-29" --- The **Ramp** managed MCP server lets an LLM read and act on your company’s Ramp spend data: listing and inspecting transactions, browsing cards, managing spend limits, querying users and departments, looking up vendors, and reviewing reimbursements. After reading this page, you will be able to: - Configure the Ramp managed MCP server with per-user OAuth - Pick the right scopes and environment for production vs sandbox - List transactions, manage cards, and adjust spend limits from an agent ## [](#what-this-mcp-server-does)What this MCP server does Wraps the [Ramp Developer API v1](https://docs.ramp.com/developer-api/v1) using per-user OAuth tokens, so each user’s Ramp permissions are enforced automatically and no shared API key is stored. It is suitable for expense analysis, spend-policy enforcement, and corporate card management workflows. It is **not** intended for accounting system integrations or bulk data exports; use Ramp’s native accounting sync or data export features for those tasks. ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - A Ramp account with admin access to the Ramp Developer Portal. - An [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) configured in Redpanda Agentic Data Plane for Ramp. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). - Familiarity with [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). ## [](#get-ramp-credentials)Get Ramp credentials Set up the OAuth app on Ramp and the matching OAuth Provider in Agentic Data Plane: 1. Sign in to the [Ramp Developer Portal](https://app.ramp.com/developer). 2. Go to **Developer Settings > Applications** and click **Create Application**. 3. Set the redirect URI to your AI Gateway OAuth callback (typically `https://aigw..clusters.rdpa.co/oauth/v1/callback`). 4. Note the **Client ID** and **Client Secret**. 5. Required scopes: - `transactions:read` - `cards:read` - `cards:write` - `users:read` - `departments:read` - `vendors:read` - `reimbursements:read` - `limits:read` - `limits:write` 6. In Agentic Data Plane, register an OAuth Provider with: - **Authorization endpoint**: `https://app.ramp.com/v1/authorize` - **Token endpoint**: `https://api.ramp.com/developer/v1/token` - The Client ID and a secret-store reference for the Client Secret ## [](#configure)Configure Create a new Ramp MCP server in Agentic Data Plane: 1. Open **MCP Servers > Create Server**. 2. Pick `Ramp` from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the Ramp configuration form: | Field | Notes | | --- | --- | | environment | production for the live Ramp API. demo for Ramp’s sandbox environment. Omit (or leave empty) for production. | | OAuth Provider | The Ramp OAuth Provider you configured. | | Required scopes | All the scopes listed above. Drop write scopes (cards:write, limits:write) if the MCP only needs to read. | 5. Click **Create**. ### [](#configure-from-the-cli)Configure from the CLI Ramp authenticates per-user through the Ramp OAuth Provider you configured. Reference that provider in the managed config’s `userOauth.providerName` field. Ramp supports per-user OAuth only, so the `userOauth` block is required. The `--user-oauth-provider` and `--user-oauth-scopes` flags apply to remote (`--url`) servers only. ```bash rpk ai mcp-server create --name my-ramp --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.ramp.v1.RampMCPConfig", "environment": "production", "userOauth": { "providerName": "ramp" } }' ``` Set `environment` to `"demo"` to target Ramp’s sandbox. `userOauth.providerName` is the resource name of the Ramp OAuth Provider you registered. ## [](#tools)Tools The Ramp MCP exposes the following tools: | Tool | Description | | --- | --- | | list_transactions | List transactions with optional filters. Supports pagination through the start cursor. Returns up to page_size results (max 100). | | get_transaction | Retrieve a single transaction by ID, including line items, accounting selections, and policy violations. | | list_cards | List corporate cards. Supports pagination. | | create_card | Issue a new virtual card. Returns a deferred task ID, since Ramp creates cards asynchronously. | | suspend_card | Suspend an active card by ID. Returns a deferred task ID. | | list_users | List Ramp users in your organization. Supports pagination. | | list_departments | List departments. Supports pagination. | | list_vendors | List vendors. Supports pagination. | | list_reimbursements | List out-of-pocket reimbursement requests. Supports pagination. | | list_limits | List spend limits. Supports pagination. | | create_limit | Create a new spend limit. Returns a deferred task ID, since Ramp creates limits asynchronously. | | update_limit | Update an existing spend limit’s display name or spending restrictions synchronously. | ### [](#example-list-recent-transactions)Example: List recent transactions ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/my-ramp \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_transactions", "arguments": { "page_size": 25 } } }' ``` ### [](#example-create-a-virtual-card-for-a-vendor)Example: Create a virtual card for a vendor ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/my-ramp \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "create_card", "arguments": { "display_name": "AWS Services", "user_id": "usr_abc123", "idempotency_key": "create-aws-card-2026", "spending_limit_amount": 5000.0, "spending_limit_interval": "MONTHLY", "spending_limit_currency": "USD" } } }' ``` ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | OAuthConnectionRequired | First call from a user with no stored token. The user completes Ramp’s OAuth consent flow, the token lands in the vault, and subsequent calls reuse it. | | scope_upgrade_required | Server’s required_scopes was extended after users had already consented. Users re-consent with the higher scope. | | create_card / create_limit returns a task ID with no card / limit details | These operations are asynchronous on Ramp’s side. The MCP returns a task ID that you can poll against Ramp’s API; the actual card or limit appears after the task completes. | | 403 Forbidden reading or writing | The calling user’s Ramp role doesn’t grant the action. Ramp’s role-based access control runs end-to-end: per-user OAuth means each user only sees what their Ramp account permits. | ## [](#limitations)Limitations This page does not cover: - **Bulk data export**: Use Ramp’s native data export. - **Accounting system integration**: Use Ramp’s accounting sync. - **Receipt management and approvals**: Handled in the Ramp web UI. ## [](#next-steps)Next steps - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) --- # Page 29: Salesforce Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/salesforce.md --- # Salesforce Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Salesforce Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/salesforce page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/salesforce.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/salesforce.adoc description: Query, create, update, and delete Salesforce CRM records with SOQL and the REST API, and run saved reports, from an LLM agent. Choose a shared service-account identity or per-user OAuth. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Choose between service-account OAuth and per-user OAuth for the Salesforce managed MCP server learning-objective-2: Configure the Salesforce managed MCP server against your org learning-objective-3: Query, modify, and report on Salesforce records from an agent page-git-created-date: "2026-06-10" page-git-modified-date: "2026-07-29" --- The **Salesforce** managed MCP server lets agents work with [Salesforce](https://www.salesforce.com/) CRM data: running SOQL queries and SOSL searches, reading and writing records, inspecting object metadata, and running saved Salesforce reports through the REST and Analytics APIs. After reading this page, you will be able to: - Choose between service-account OAuth and per-user OAuth for the Salesforce managed MCP server - Configure the Salesforce managed MCP server against your org - Query, modify, and report on Salesforce records from an agent ## [](#what-this-mcp-server-does)What this MCP server does The Salesforce MCP exposes the following tools: | Tool | What it does | | --- | --- | | query | Execute a SOQL query. | | query_more | Fetch the next page of a large query result, using the nextRecordsUrl returned by query. | | search | Execute a SOSL full-text search. | | list_objects | List all available sObject types in the org. | | describe_object | Get field and schema metadata for an sObject. | | get_record | Fetch a record by ID, with optional field selection. | | create_record | Create a new record. | | update_record | Update an existing record (PATCH). | | delete_record | Delete a record. | | describe_report | Get a report’s metadata: columns, groupings, and filters. | | run_report | Run a saved report synchronously and return its results. | `run_report` executes a saved Salesforce report through the Analytics REST API, applying the report’s built-in groupings, aggregates, and filters that raw SOQL cannot reproduce. Use `describe_report` first to discover a report’s columns and filters. To list reports, use `query` with `SELECT Id, Name, DeveloperName FROM Report`. ## [](#choose-an-authentication-mode)Choose an authentication mode The Salesforce MCP supports two authentication modes. Set exactly one in the managed config: | Mode | When to use | | --- | --- | | Service-account OAuth (serviceAccountOauth) | OAuth 2.0 client-credentials grant through a Connected App. Service-to-service: no browser, no redirect. Every caller shares one Salesforce identity. Use this when a single shared identity is acceptable. | | Per-user OAuth (userOauth) | Each caller’s Salesforce OAuth token is resolved from the token vault on every request, so tool calls respect Salesforce row-level security for the calling user. Requires a Salesforce OAuth Provider. Use this when each user must act as themselves. | ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - A Salesforce org where you can create a Connected App. A free Developer Edition org or a Sandbox works. - Your Salesforce instance URL (your **My Domain** URL), such as `https://mycompany.my.salesforce.com`. Use the full `https://` base domain with no path. - For **service-account OAuth**: a Connected App configured for the client-credentials flow, and its consumer key and consumer secret. - For **per-user OAuth**: a Salesforce [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) configured in Redpanda Agentic Data Plane. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) and [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). ## [](#create-a-connected-app-for-service-account-oauth)Create a Connected App for service-account OAuth Skip this section if you are using per-user OAuth. The client-credentials flow is a service-to-service flow: `client_id` + `client_secret` exchange for an `access_token`, with no browser interaction. 1. In Salesforce **Setup**, search for **App Manager** and click **New Connected App**. 2. Enter a Connected App Name and Contact Email. 3. Under **API (Enable OAuth Settings)**: - Check **Enable OAuth Settings**. - Set a Callback URL (required by the form, unused for client credentials). - Add the Manage user data via APIs (api) and Perform requests at any time (refresh\_token, offline\_access) OAuth scopes. - Check **Enable Client Credentials Flow**. 4. Click **Save**, then **Continue**. 5. Open the app from **App Manager**, click **Manage Consumer Details**, and copy the Consumer Key (your `client_id`) and Consumer Secret (your `client_secret`). 6. Set a Run As user: in **App Manager**, open the app, click **Manage > Edit Policies**, and under Client Credentials Flow set Run As to a Salesforce user with API access. Click **Save**. Store the consumer secret in the Redpanda Agentic Data Plane secret store under an `UPPER_SNAKE_CASE` key, such as `SALESFORCE_CLIENT_SECRET`. ## [](#configure)Configure Create a new Salesforce MCP server in Agentic Data Plane: 1. Open **MCP Servers > Create Server**. 2. Pick `Salesforce` from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the Salesforce configuration form, set the Salesforce instance URL (`orgUrl`) and pick an Auth Method: service-account OAuth or per-user OAuth. For per-user OAuth, select the Salesforce OAuth Provider. 5. Optionally pin a Salesforce REST API version. The default is `v65.0`. 6. Click **Create**. ### [](#configure-from-the-cli)Configure from the CLI Use [`rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) to create the server with a managed config. Set exactly one auth variant. For service-account OAuth, supply the Connected App’s `clientId`, a secret-store reference for the consumer secret (`clientSecretRef`), and the token URL: ```bash rpk ai mcp-server create --name my-salesforce --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.salesforce.v1.SalesforceMCPConfig", "orgUrl": "https://mycompany.my.salesforce.com", "serviceAccountOauth": { "clientId": "3MVG9...", "clientSecretRef": "SALESFORCE_CLIENT_SECRET", "tokenUrl": "https://mycompany.my.salesforce.com/services/oauth2/token" } }' ``` For per-user OAuth, reference the Salesforce OAuth Provider by name. The per-user token is resolved from the token vault on each call: ```bash rpk ai mcp-server create --name my-salesforce --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.salesforce.v1.SalesforceMCPConfig", "orgUrl": "https://mycompany.my.salesforce.com", "userOauth": { "providerName": "salesforce" } }' ``` To pin a specific API version, add `"apiVersion": "v62.0"` to the config. The default is `v65.0`. ## [](#tool-examples)Tool examples Run a SOQL query: ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/my-salesforce \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "query", "arguments": { "soql": "SELECT Id, Name, Industry, AnnualRevenue FROM Account ORDER BY AnnualRevenue DESC LIMIT 10" } } }' ``` Fetch a record by ID, restricting the returned fields: ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/my-salesforce \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "get_record", "arguments": { "sobject": "Account", "record_id": "001xx000003GYkZAAW", "fields": "Id,Name,Industry,AnnualRevenue,BillingCity" } } }' ``` ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | invalid_client_credentials from OAuth (service-account mode) | Confirm the Connected App has a Run As user set and the api scope, and that you are using the Consumer Key (not the app name) as clientId. | | OAuthConnectionRequired (per-user mode) | First call from a user with no stored token. The user completes Salesforce’s OAuth consent flow, the token lands in the vault, and subsequent calls reuse it. | | INSUFFICIENT_ACCESS errors | The acting identity (the Run As user for service-account mode, or the calling user for per-user mode) lacks permission on that object or record. Grant the appropriate profile or permission set. | | INVALID_FIELD in a SOQL query | The field does not exist or field-level security hides it from the acting identity. Use describe_object to see which fields are visible. | | nextRecordsUrl rejected by query_more | The URL must start with /services/data/. Pass the exact value returned by the query response. | ## [](#next-steps)Next steps - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) - [Test MCP tools](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) --- # Page 30: Sentry Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/sentry.md --- # Sentry Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Sentry Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/sentry page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/sentry.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/sentry.adoc description: Give an agent read-only access to Sentry organizations, projects, issues, events, and releases through per-user OAuth, so it can read a stack trace, scope an error's impact, and localize the fix. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Sentry managed MCP server with per-user OAuth learning-objective-2: Confine the server to a single Sentry organization (optional) learning-objective-3: Diagnose an issue from the Inspector or an agent, from discovery through to the suspect commit page-git-created-date: "2026-06-26" page-git-modified-date: "2026-07-29" --- The **Sentry** managed MCP server gives agents read-only access to a Sentry instance: discover organizations and projects, list and read issues, read the events (with stack traces) behind them, scope an error’s impact across releases and tags, and surface the commits most likely responsible. The intended use is an agent that reads a Sentry issue and its stack trace to diagnose a bug, then fixes it in the codebase. After reading this page, you will be able to: - Configure the Sentry managed MCP server with per-user OAuth - Confine the server to a single Sentry organization (optional) - Diagnose an issue from the Inspector or an agent, from discovery through to the suspect commit ## [](#what-this-mcp-server-does)What this MCP server does Wraps the Sentry REST API and exposes read-only tools grouped by the diagnose-and-fix flow: discover organizations and projects, read the error and its stack trace, scope the impact across tags and releases, and localize the fix to a suspect commit. Authentication is per-user OAuth only. Every tool call runs as the authenticated user against a Sentry OAuth token resolved from the gateway’s [token vault](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#token-vault), so there is no shared service account and each action is attributed to the calling end-user. The server requests only read scopes (`org:read`, `project:read`, `event:read`, `project:releases`). The server is read-only by design: resolving or ignoring issues, commenting, and any other write operation is deliberately absent. Use the Sentry UI or its API directly for those. > 📝 **NOTE** > > Tool output is developer-facing observability data and is not guaranteed to be free of personally identifiable information (PII). The curated event shape omits Sentry’s `user` and `request` context, but event `tags` are forwarded verbatim and can carry user-supplied values (for example `user`, `url`, `server_name`, or custom tags), and suspect-commit and release-commit output includes commit author names and email addresses. This MCP server connects to `sentry.io` only. Self-hosted Sentry is not supported. ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - A Sentry account on `sentry.io` with access to the organizations and projects you want the agent to read. - A Sentry OAuth application and a matching [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) configured in Redpanda Agentic Data Plane. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). ## [](#get-sentry-credentials)Get Sentry credentials Sentry MCP uses per-user OAuth, so you register an OAuth application on Sentry and a matching OAuth Provider in Agentic Data Plane: 1. In Sentry, go to **Settings > Account > API > Applications** and create a new application. Set the authorized redirect URI to your Agentic Data Plane gateway’s OAuth callback. 2. Copy the Client ID and Client Secret, and store the client secret in the Agentic Data Plane secret store. 3. Register a matching OAuth Provider in Agentic Data Plane. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). Use Sentry’s authorize endpoint (`[https://sentry.io/oauth/authorize/](https://sentry.io/oauth/authorize/)`) and token endpoint (`[https://sentry.io/oauth/token/](https://sentry.io/oauth/token/)`). 4. Each end-user authenticates once through the OAuth flow; tokens are stored in the gateway’s token vault. Required scopes: `org:read`, `project:read`, `event:read`, and `project:releases` cover all tools. `org:read` lists organizations and projects and resolves event IDs; `project:read` lists issues and reads project events and suspect commits; `event:read` reads issue events, tags, and hashes (the stack trace); and `project:releases` reads releases and their commits. All scopes are read-only. ## [](#configure)Configure Create a new Sentry MCP server in Agentic Data Plane: 1. Open **MCP Servers > Create Server**. 2. Pick `Sentry` from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the Sentry configuration form: | Field | Notes | | --- | --- | | organization_slug | Optional. Confines the server to a single Sentry organization. When set, every tool that takes an organization_slug is forced to this value and a request targeting a different organization is rejected; list_organizations stays unrestricted so it can still be used for discovery. Leave empty for unrestricted access, bounded only by the OAuth token. The slug is the URL segment at sentry.io/organizations/, not the display name. | | user_oauth | provider_name (the Sentry OAuth Provider you configured) and the minimum required scopes (org:read, project:read, event:read, project:releases covers all tools). | 5. Click **Create**. ### [](#configure-from-the-cli)Configure from the CLI Use [`rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) to create the server with a managed config. Set the OAuth provider and scopes inside the `--managed-config` JSON. Per-user OAuth is the only supported authentication method. #### Unrestricted The caller supplies the organization on each call, bounded only by the OAuth token’s access. ```bash rpk ai mcp-server create --name acme-sentry --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.sentry.v1.SentryMCPConfig", "user_oauth": { "provider_name": "sentry-prod", "required_scopes": ["org:read", "project:read", "event:read", "project:releases"] } }' ``` #### Confined to one organization Pin the server to a single organization with `organization_slug`. ```bash rpk ai mcp-server create --name acme-sentry --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.sentry.v1.SentryMCPConfig", "organization_slug": "my-org", "user_oauth": { "provider_name": "sentry-prod", "required_scopes": ["org:read", "project:read", "event:read", "project:releases"] } }' ``` ## [](#tools)Tools The Sentry MCP exposes read-only tools, grouped by the diagnose-and-fix flow: | Tool | Description | | --- | --- | | list_organizations | List the Sentry organizations the token can access. Used for discovery; never restricted by organization_slug. | | list_projects | List the projects within an organization. | | list_issues | List a project’s issues, filtered by a Sentry search query (for example, is:unresolved). | | get_issue | Fetch issue detail by numeric ID or short ID (for example, WEB-1). | | get_issue_latest_event | Return the most recent event for an issue, including its exception stack trace. | | list_issue_events | List the individual occurrences of an issue (compare a failing against a passing event). | | get_issue_event | Return one event of an issue with a full stack trace, by ID or the alias latest, oldest, or recommended (oldest is the regression boundary). | | get_event | Fetch an event by ID within a project, plus the issue ID it belongs to. | | resolve_event_id | Resolve a bare event ID to its issue and project at organization scope. | | get_issue_tag | Return the distribution of one tag (for example, release, environment, browser, or OS) for an issue. | | list_issue_tag_values | List the full set of values behind a tag’s capped top values. | | list_issue_hashes | List the issue’s grouping hashes. More than one hash means several crash signatures. | | get_event_committers | Return the commits and authors Sentry deems most likely responsible (suspect commits). Requires a source-code integration; returns empty when none is configured. | | list_releases | List an organization’s releases. Line an issue’s first-seen date up against a deploy. | | get_release | Return a single release’s detail by version. | | list_release_commits | List the commits that shipped in a release (the candidate changes behind a regression). | ## [](#tool-examples)Tool examples List the organizations you can read: ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-sentry \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_organizations", "arguments": {} } }' ``` Replace `` with your cluster ID and `$TOKEN` with a gateway access token. Find unresolved issues in a project: ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-sentry \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "list_issues", "arguments": { "organization_slug": "my-org", "project_slug": "web", "query": "is:unresolved", "stats_period": "24h" } } }' ``` Read an issue’s latest event and stack trace. This is the diagnostic step: the latest event carries the exception stack trace the agent reasons over. ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-sentry \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "get_issue_latest_event", "arguments": { "organization_slug": "my-org", "issue_id": "WEB-1" } } }' ``` ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | OAuthConnectionRequired | First call from a user with no stored token. The user completes Sentry’s OAuth consent flow, the token lands in the vault, and subsequent calls reuse it. See User-delegated OAuth. | | scope_upgrade_required | The server’s required_scopes was extended after users had already consented. Users re-consent with the higher scope. | | A request is rejected naming two organization slugs | The server is confined with organization_slug and the call targeted a different organization. Target the pinned organization, or use an unrestricted server. | | get_event_committers returns empty | Sentry has no source-code integration configured for the project, so it cannot attribute suspect commits. Configure a source-code integration in Sentry. | ## [](#limitations)Limitations This page does not cover: - **Write operations**: Resolving or ignoring issues, commenting, and managing alerts are deliberately absent. The server is read-only. - **Self-hosted Sentry**: The server connects to `sentry.io` only. ## [](#next-steps)Next steps - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) - [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) --- # Page 31: ServiceNow Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/servicenow.md --- # ServiceNow Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: ServiceNow Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/servicenow page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/servicenow.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/servicenow.adoc description: "Read and write a ServiceNow instance from an agent: incidents, knowledge articles, and allow-listed records, with service-account or per-user authentication." page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the ServiceNow managed MCP server with Basic authentication, OAuth client credentials, or User OAuth learning-objective-2: Use projections and hierarchies to shape responses and gate table reads learning-objective-3: Search, create, and update incidents and read allow-listed records from the Inspector or an agent page-git-created-date: "2026-06-09" page-git-modified-date: "2026-07-29" --- The ServiceNow managed MCP server lets agents work with a ServiceNow instance through the REST Table API: search, create, and update incidents, append work notes, search the knowledge base, look up users and assignment groups, search the configuration management database (CMDB) for configuration items, discover table schema and field choices, and read allow-listed tables. After reading this page, you will be able to: - Configure the ServiceNow managed MCP server with Basic authentication, OAuth client credentials, or User OAuth - Use projections and hierarchies to shape responses and gate table reads - Search, create, and update incidents and read allow-listed records from the Inspector or an agent ## [](#what-this-mcp-server-does)What this MCP server does Wraps the ServiceNow REST Table API. The MCP is vendor-generic: ServiceNow records are returned as opaque JSON objects (their field set varies by instance), and the agent learns each table’s shape and valid field values at runtime through the discovery tools (`get_table_schema`, `get_field_choices`). Customer-specific structure is supplied as configuration, not code: - Projections set the default field list returned per table (a ServiceNow incident carries about 100 fields, so projections keep responses small) and gate which tables the generic `query_records` tool may read. - Hierarchies declare dependent-field chains (for example, service area, then category, then subcategory). The agent reads the chain order with `describe_field_hierarchies` and resolves each field’s valid values at runtime with `get_field_choices`. No field values are stored in the configuration. It is not a general SQL interface, and it does not delete records: writes are limited to the typed incident tools plus generic record reads. ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - A ServiceNow instance and its URL (for example, `[https://acme.service-now.com](https://acme.service-now.com)`). - A ServiceNow service account, or an OAuth client, with the roles your workflows need (typically `itil` for incidents, `knowledge` for the knowledge base, and read access to `sys_dictionary` and `sys_choice` for schema discovery). - For User-OAuth mode: an [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) configured in Redpanda Agentic Data Plane. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). ## [](#choose-an-authentication-method)Choose an authentication method The MCP authenticates to ServiceNow as a single principal; it does not impersonate end-users. When creating an incident, the agent passes the requesting user’s `sys_id` in `caller_id`. Pick one of three methods: - Basic authentication (simplest): A dedicated ServiceNow user (for example, `svc_redpanda`) and its password. The username is plaintext; the password lives in the Agentic Data Plane secret store. - OAuth client credentials (service account): An OAuth API client registered under **System OAuth > Application Registry**. ServiceNow’s token endpoint is `[https://.service-now.com/oauth_token.do](https://\.service-now.com/oauth_token.do)`. - User OAuth: Per-user delegation through an OAuth Provider. ServiceNow’s recommended integration model is the service account, so prefer Basic authentication or OAuth client credentials unless you specifically need per-user attribution. ## [](#configure)Configure Create a new ServiceNow MCP server in Agentic Data Plane: 1. Open **MCP Servers > Create Server**. 2. Pick `ServiceNow` from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the ServiceNow configuration form: | Field | Notes | | --- | --- | | instance_url | Base URL of your ServiceNow instance (for example, https://acme.service-now.com). Must be an https:// URL. | | auth | basic_auth, oauth, or user_oauth. | | basic_auth (Basic-auth mode) | username (ServiceNow service-account username, for example svc_redpanda) and password_secret_ref (secret-store reference, UPPER_SNAKE_CASE). | | oauth (OAuth mode) | client_id, client_secret_ref (secret-store reference), and token_url (https://.service-now.com/oauth_token.do). | | user_oauth (User-OAuth mode) | provider_name (the OAuth Provider you configured) and the minimum required scopes. | | projections | Per-table default field lists and the read allow-list for query_records. | | hierarchies | Dependent-field chains the agent resolves at runtime. | 5. Click **Create**. ### [](#configure-from-the-cli)Configure from the CLI For a managed server, set the auth method inside the `--managed-config` JSON. The `auth` field is required. #### Basic authentication ```bash rpk ai mcp-server create --name acme-servicenow --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.servicenow.v1.ServiceNowMCPConfig", "instance_url": "https://acme.service-now.com", "basic_auth": { "username": "svc_redpanda", "password_secret_ref": "SERVICENOW_PASSWORD" }, "projections": [ { "table": "incident", "default_fields": ["number", "short_description", "state", "priority", "assignment_group", "caller_id"], "queryable": true }, { "table": "change_request", "queryable": true } ], "hierarchies": [ { "table": "incident", "name": "service", "fields": ["u_service_area", "u_service_category", "u_service_subcategory"] } ] }' ``` #### OAuth client credentials ```bash rpk ai mcp-server create --name acme-servicenow-oauth --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.servicenow.v1.ServiceNowMCPConfig", "instance_url": "https://acme.service-now.com", "oauth": { "client_id": "", "client_secret_ref": "SERVICENOW_CLIENT_SECRET", "token_url": "https://acme.service-now.com/oauth_token.do" } }' ``` #### User OAuth ```bash rpk ai mcp-server create --name acme-servicenow-user --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.servicenow.v1.ServiceNowMCPConfig", "instance_url": "https://acme.service-now.com", "user_oauth": { "provider_name": "servicenow-prod" } }' ``` Replace `` with the client ID from your ServiceNow OAuth application registry, and `servicenow-prod` with the name of the OAuth Provider you configured. ## [](#tools)Tools The ServiceNow MCP exposes tools across incidents, knowledge, schema discovery, lookups, and generic reads: | Tool | Description | | --- | --- | | search_incidents | Search incidents with a ServiceNow encoded query. | | get_incident | Fetch one incident by sys_id. | | create_incident | Create an incident (typed fields plus an additional_fields map for custom fields). | | update_incident | Update state, assignment, notes, urgency, or impact, or resolve or close an incident. | | add_work_note | Append a work note (internal) or comment (customer-visible) to an incident. | | search_knowledge | Full-text search over published knowledge articles. | | get_article | Fetch one knowledge article by sys_id or number. | | get_table_schema | Field metadata (name, type, mandatory, reference) for a table, from sys_dictionary. | | get_field_choices | Valid choice values for a field from sys_choice, optionally scoped to a parent value. | | describe_field_hierarchies | Declared dependent-field chains for a table, from the server configuration. | | lookup_user | Find users by name, email, or username; returns their sys_id. | | lookup_group | Find assignment groups by name; returns their sys_id. | | search_cmdb_ci | Search configuration items (cmdb_ci) with a ServiceNow encoded query; the sys_class_name field distinguishes CI classes such as servers, computers, applications, and services. | | query_records | Read any allow-listed table with an encoded query. | ### [](#example-search-open-incidents)Example: Search open incidents ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-servicenow \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_incidents", "arguments": { "query": "active=true^priority=1" } } }' ``` Replace `` with your cluster ID and `$TOKEN` with a gateway access token. ### [](#example-create-an-incident)Example: Create an incident The agent typically calls `lookup_user` and `get_field_choices` first to resolve `caller_id` and a valid `category` value. ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-servicenow \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "create_incident", "arguments": { "short_description": "VPN drops every few minutes in Dresden", "caller_id": "a1b2c3d4e5f6...", "urgency": 2, "impact": 2, "category": "network" } } }' ``` ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | 401 Unauthorized | Confirm the service-account credentials. For Basic authentication, check the username and SERVICENOW_PASSWORD; for OAuth, check the client ID, SERVICENOW_CLIENT_SECRET, and token URL. | | 403 Forbidden | The service account lacks the role for the operation (for example, itil for incidents or read access to sys_dictionary for get_table_schema). Grant the role in ServiceNow. | | query_records rejects a table | The table is not listed in projections with queryable set to true. Add a projection entry for it. | | OAuthConnectionRequired (User-OAuth mode) | First call from a user with no stored token. The user completes the ServiceNow OAuth consent flow, the token lands in the vault, and later calls reuse it. See User-delegated OAuth. | ## [](#limitations)Limitations This MCP server does not cover: - Record deletion: Writes are limited to the typed incident tools; the MCP never deletes records. - Arbitrary SQL: Reads go through the REST Table API and encoded queries, not a SQL interface. Use `query_records` against allow-listed tables instead. ## [](#next-steps)Next steps - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) --- # Page 32: SharePoint Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/sharepoint.md --- # SharePoint Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: SharePoint Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/sharepoint page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/sharepoint.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/sharepoint.adoc description: Let agents read SharePoint sites, document libraries, lists, and files, upload files, and search content through the Microsoft Graph API, using each end-user's own Microsoft identity through user-delegated OAuth. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Register a Microsoft Entra app and an OAuth provider for the SharePoint managed MCP server learning-objective-2: Create the SharePoint managed MCP server with the correct Microsoft Graph scopes learning-objective-3: Authorize a user and run the SharePoint tools from the Inspector or an agent page-git-created-date: "2026-06-03" page-git-modified-date: "2026-08-06" --- The **SharePoint** managed MCP server lets agents read SharePoint sites, document libraries, lists, and files, upload files, and search content through the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/api/resources/sharepoint). Each agent caller authenticates against Microsoft with their own identity through user-delegated OAuth, so every call stays bounded by the signed-in user’s own SharePoint permissions: the server never holds workspace-wide access. After reading this page, you will be able to: - Register a Microsoft Entra app and an OAuth provider for the SharePoint managed MCP server - Create the SharePoint managed MCP server with the correct Microsoft Graph scopes - Authorize a user and run the SharePoint tools from the Inspector or an agent > 📝 **NOTE** > > The SharePoint managed MCP server is in preview. If you don’t see SharePoint in the picker, contact Redpanda support. ## [](#what-this-mcp-server-does)What this MCP server does The SharePoint managed type wraps the Microsoft Graph API (`[https://graph.microsoft.com/v1.0](https://graph.microsoft.com/v1.0)`) and authenticates per user through the gateway’s [token vault](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#token-vault). Per-user OAuth is the only authentication mode this type supports. It exposes the following tools: | Tool | What it does | | --- | --- | | list_sites | Search for SharePoint sites. The search term passes straight to Graph’s /sites?search= endpoint. An empty search returns no results, so pass * to list every site or a name fragment to narrow the search. | | get_site | Fetch a single site by composite ID (contoso.sharepoint.com,,) or hostname path (contoso.sharepoint.com:/sites/team). | | list_drive_items | Browse a site’s default document library. Lists the library root by default; pass folder_id to descend into a folder. | | get_file_content | Read a file from a site’s document library as UTF-8 text, with its filename, MIME type, and size. | | upload_file | Upload a text file to a site’s document library, into the root or a folder. Requires the Sites.ReadWrite.All scope. | | search_content | Search across all SharePoint sites, files, and list items the user can see. The query supports Keyword Query Language (KQL). | | list_lists | List the SharePoint lists on a site. Hidden lists are excluded. | | list_list_items | List the items in a SharePoint list, with each item’s column values returned as JSON in fields_json. | The file tools operate on the site’s own default document library (`/sites//drive/…​`), never on a user’s personal OneDrive. File content travels as UTF-8 text in both directions: downloads through `get_file_content` are capped at 10 MiB, and uploads through `upload_file` are capped at 4 MiB (the Microsoft Graph simple-upload limit). Binary files aren’t supported; open the `web_url` returned by `list_drive_items` to access them directly. The `list_sites`, `list_drive_items`, and `list_list_items` tools return up to 100 items by default and accept a `page_size` of up to 999. The `search_content` tool returns up to 25 hits by default and accepts a `page_size` of up to 500. The `list_lists` tool takes no `page_size`. ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - Access to a Microsoft SharePoint tenant. - Permission to register an app in the [Microsoft Entra admin center](https://entra.microsoft.com) (or an Entra admin who can register one for you). - A way to write the OAuth client secret into the Redpanda Agentic Data Plane secret store. - For most tenants, a tenant admin who can grant admin consent for the Microsoft Graph scopes. See [Grant admin consent](#grant-admin-consent). - Familiarity with [user-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). ## [](#register-the-microsoft-entra-app)Register the Microsoft Entra app In the Microsoft Entra admin center, go to **App registrations > New registration** and create an app: 1. Give the app a descriptive name, for example, `Redpanda AI Gateway - SharePoint MCP`. 2. Set **Supported account types** to single tenant. 3. Set the **Redirect URI** to platform **Web** with the gateway’s OAuth callback for your cluster: ```no-highlight https://aigw..clusters.rdpa.co/oauth/v1/callback ``` Replace `` with your cluster identifier. The callback path is `/oauth/v1/callback`. 4. After registering, note the **Application (client) ID** and **Directory (tenant) ID** from the app’s Overview page. You need both when you configure the [OAuth provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider). > 💡 **TIP** > > Single-tenant apps must use the tenant-specific Microsoft OAuth endpoints (`[https://login.microsoftonline.com//oauth2/v2.0/…​](https://login.microsoftonline.com/\/oauth2/v2.0/…​);`), not the `/common/` endpoints, which can return `AADSTS` errors for single-tenant apps. Replace `` with the Directory (tenant) ID from the app’s Overview page. ## [](#add-microsoft-graph-permissions)Add Microsoft Graph permissions In the Microsoft Entra admin center, open the app’s **API permissions**, select **Add a permission > Microsoft Graph > Delegated permissions**, then add: | Scope | Why | | --- | --- | | Sites.ReadWrite.All | Read and write everything the server touches: sites, document libraries, files, lists, and upload_file. For read-only deployments, use Sites.Read.All instead, which drops upload_file. | | offline_access | Issues refresh tokens so connections stay valid over time. | The `openid`, `profile`, `email`, and `User.Read` scopes come from the OAuth provider’s standard scopes. > ❗ **IMPORTANT** > > Use the **Microsoft Graph** permissions, not the legacy **Office 365 SharePoint Online** API in the picker. The server calls Microsoft Graph only. > > Use the `Sites.` **scopes, not `Files.`**. The server’s file and list endpoints all live under `/sites//…​`, and its site lookups and content search are also authorized by the `Sites.*` scopes. The `Files.ReadWrite.All` scope additionally grants access to users' personal OneDrive, which the server never uses. ## [](#create-a-client-secret)Create a client secret In the Microsoft Entra admin center, open the app’s **Certificates & secrets** and select **New client secret**. Give it a description, choose an expiry, and select **Add**. Copy the secret value immediately; Microsoft never shows it again. Store the secret in the Agentic Data Plane secret store under an `UPPER_SNAKE_CASE` key, for example, `SHAREPOINT_CLIENT_SECRET`. The OAuth provider references the secret by name, so the plaintext never enters the MCP server configuration. ## [](#grant-admin-consent)Grant admin consent The SharePoint Graph scopes are high-privilege delegated scopes, so most tenants require a tenant admin to consent before any user can connect. A Global Administrator, Privileged Role Administrator, or Cloud Application Administrator opens the app, selects **API permissions**, then selects **Grant admin consent for ``**. Admin consent does not escalate access: delegated scopes always stay bounded by the signed-in user’s own SharePoint permissions. Admin consent approves the app to request the scopes so that individual users aren’t each prompted. Without it, a non-admin user sees the **Need admin approval** message on the consent screen. ## [](#configure-the-oauth-provider)Configure the OAuth provider Register an OAuth provider in Agentic Data Plane that points at Microsoft’s tenant-specific endpoints and references the client secret. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). The **Microsoft / Azure AD** preset in the provider catalog pre-fills the endpoints, standard scopes, PKCE, and token auth method; for a single-tenant app, replace its `/common/` endpoints with the tenant-specific ones. Use these values: - **Authorization endpoint**: `[https://login.microsoftonline.com//oauth2/v2.0/authorize](https://login.microsoftonline.com/\/oauth2/v2.0/authorize)` - **Token endpoint**: `[https://login.microsoftonline.com//oauth2/v2.0/token](https://login.microsoftonline.com/\/oauth2/v2.0/token)` - **Client ID**: The Application (client) ID from the Entra app. - **Client secret reference**: The secret-store key, for example, `SHAREPOINT_CLIENT_SECRET`. - **Token auth method**: Client secret in the POST body, with PKCE enabled (matches the Microsoft preset). - **Scopes**: `openid`, `email`, `profile`, `User.Read`, `Sites.ReadWrite.All`, `offline_access`. The provider page also shows the **Authorization Callback URL** to register as the Entra app’s redirect URI. ## [](#create-the-server)Create the server Create a new SharePoint MCP server in Agentic Data Plane: 1. Open **MCP Servers > Create server**. 2. Pick **SharePoint** from the marketplace picker. 3. Fill in the identity fields (`name`, `description`). 4. Under **Auth**, select **User OAuth** (the only option for this type), then set **Provider Name** to the SharePoint OAuth provider you configured. 5. Under **Required Scopes**, add `Sites.ReadWrite.All` (or `Sites.Read.All` for a read-only server). 6. Click **Submit**. The required scopes are enforced against each user’s connection. A connection with insufficient scopes returns `scope_upgrade_required`, and the user re-consents with the higher scope. ### [](#configure-from-the-cli)Configure from the CLI Use [`rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) to create the server with a managed config. Set the OAuth provider inside the managed config; the top-level `--user-oauth-provider` and `--user-oauth-scopes` flags apply to self-managed servers only. ```bash rpk ai mcp-server create --name sharepoint \ --description "SharePoint MCP over Microsoft Graph with per-user OAuth" \ --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.sharepoint.v1.SharePointMCPConfig", "userOauth": { "providerName": "sharepoint", "requiredScopes": ["Sites.ReadWrite.All"] } }' ``` ## [](#authorize-a-user-and-test)Authorize a user and test The SharePoint server uses per-user OAuth, so each user connects their Microsoft identity before tools work for them: 1. Open the server in Agentic Data Plane. If you haven’t connected to the SharePoint OAuth provider yet, a connection banner with a **Connect** button appears above the server’s tabs. Click **Connect**, sign in to Microsoft, and approve the consent screen. The token lands in the vault keyed to your identity. If you call a tool before connecting, the call returns an `OAuthConnectionRequired` error carrying an `authorize_url` that points at the gateway’s `/oauth/v1/authorize` endpoint. Opening that URL in a browser starts the same Microsoft consent flow. 2. Open the server’s **Inspector** tab and run `list_sites` with the argument `{"search": "*"}`. It returns the sites you can see. See [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/). > 💡 **TIP** > > The `list_sites` tool passes the search term straight to Graph’s `/sites?search=` endpoint, which returns nothing for an empty search. Pass `*` to list every site, or a name fragment to narrow the search. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | OAuthConnectionRequired | First call from a user with no stored token. The user completes Microsoft’s OAuth consent flow, the token lands in the vault, and subsequent calls reuse it. See User-delegated OAuth. | | Need admin approval on the Microsoft consent screen | A tenant admin hasn’t granted admin consent for the Graph scopes. See Grant admin consent. | | scope_upgrade_required | The user’s connection has fewer scopes than the server requires, either because the server’s required scopes grew or because the user originally consented with fewer. The user re-consents with the higher scope. | | AADSTS errors during authorization | A single-tenant app is using the /common/ OAuth endpoints. Switch the OAuth provider to the tenant-specific endpoints (https://login.microsoftonline.com//oauth2/v2.0/…​;). | | SharePoint API error (status 403, code: accessDenied) | The signed-in user lacks permission on that site, file, or list. Graph errors surface only the HTTP status and Graph error code; the upstream error message is withheld. | | list_sites returns no sites | An empty search returns nothing. Pass * to list every site, or a name fragment. | | upload_file fails | The upload_file tool requires the Sites.ReadWrite.All scope; a read-only server configured with Sites.Read.All cannot upload. Content is also capped at 4 MiB and must be UTF-8 text. | | get_file_content reports the file exceeds the byte cap | Downloads are capped at 10 MiB. Open the file’s web_url directly instead. | | Token expired and no refresh token available | The stored token expired and couldn’t be refreshed. Confirm offline_access is in the OAuth provider’s scopes, then have the user reconnect through the same consent flow. | ## [](#next-steps)Next steps - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) - [Test MCP tools](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) --- # Page 33: Slack Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/slack.md --- # Slack Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Slack Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/slack page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/slack.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/slack.adoc description: Let agents read threads, post messages, and add reactions in your Slack workspace using a shared bot token or each end-user's own Slack identity through user-delegated OAuth. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Slack managed MCP server with user-delegated OAuth learning-objective-2: Walk through the consent flow and verify the connection on the My Connections page learning-objective-3: Send a test message through the Inspector page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- The **Slack** managed MCP server is the canonical user-delegated OAuth example for Redpanda Agentic Data Plane. Each agent caller authenticates against Slack with their own credentials, and Redpanda injects their token at call time: so messages posted by the agent appear as the user, not as a shared bot. After reading this page, you will be able to: - Configure the Slack managed MCP server with user-delegated OAuth - Walk through the consent flow and verify the connection on the My Connections page - Send a test message through the Inspector ## [](#what-this-mcp-server-does)What this MCP server does The Slack managed type exposes the following tools: - `read_thread`: Read all messages in a thread, given a channel ID and thread timestamp. - `post`: Send a message to a channel, optionally as a threaded reply, using plain text or Block Kit blocks. - `react`: Add or remove an emoji reaction on a message. ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - A Slack workspace where you can install or authorize an OAuth app. - A Slack OAuth app registered (your own or a Redpanda-published reference app). - An [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) configured in Agentic Data Plane on the **Outbound providers** tab of **Integrations setup**, pointing at Slack’s authorize/token URLs and carrying the OAuth app’s client credentials. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). - Familiarity with [Configure User-Delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). ## [](#configure)Configure Create a new Slack MCP server in Agentic Data Plane: 1. Open **MCP Servers > Create Server**. 2. Pick **Slack** from the marketplace picker. 3. Fill in the identity fields (`name`, `description`). 4. In the Slack configuration form: - `Auth`: Choose a `Bot token` (a shared `xoxb-` token from the secret store) or `User-delegated OAuth` (per-user identity). - For `User-delegated OAuth`: Pick the Slack OAuth Provider you configured and set `Required scopes` for the tools you use (see [Authentication scopes](#authentication-scopes)). - `Post options` (optional): Toggle markdown formatting, link unfurling, media unfurling, and automatic link names. - `Reaction options` (optional): Maximum concurrent reaction calls. Defaults to 64. 5. Click **Create**. There’s no workspace field: the bot token or the user’s OAuth grant determines the workspace. ## [](#test-the-consent-flow)Test the consent flow After creating the server, run a tool that requires Slack authentication to verify the consent flow end-to-end: 1. Open the **Inspector** tab. 2. Run a tool that requires the user’s identity, for example `post`. 3. The first call returns `OAuthConnectionRequired` with a Slack `authorize_url`. The Inspector surfaces it as a consent prompt. 4. Click **Authorize**. You’re redirected to Slack; pick the workspace and approve the requested scopes. 5. Slack redirects back to Agentic Data Plane. Your connection now appears under **My Connections**. 6. Re-run the original tool call. The message posts to Slack as your user. ## [](#authentication-scopes)Authentication scopes When you use user-delegated OAuth, the tools need Slack scopes that match what they do: - `post` needs `chat:write`. To post in channels the user isn’t a member of, add `chat:write.public`. - `read_thread` needs a history scope for the channel type, for example `channels:history` (public) or `groups:history` (private). - `react` needs `reactions:write`. Other gotchas: - `chat:write` is a _user_ scope; `chat:write.public` is separate. - Tokens are workspace-scoped: the same user authorizing twice across two workspaces produces two separate connections. ## [](#use-with-agents)Use with agents After the server is created and at least one user has consented, you can point an agent at the `Server URL` on the server’s **Connection** tab. Each user calling the agent will trigger their own consent flow if they haven’t connected yet. ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | OAuthConnectionRequired even after consent | The token might be revoked or expired with no refresh. Check My Connections; disconnect and reconnect if needed. | | scope_upgrade_required | The server’s required scopes were widened after the user consented. The user re-consents to grant the new scope. | | "channel not found" on a channel the user can see in Slack | Reading a private channel’s thread needs the groups:history scope. Add it to the server’s required scopes and have users re-consent. | | invalid_auth from Slack | The OAuth Provider’s client credentials are wrong, or the OAuth app has been suspended in Slack. Check the provider config. | ## [](#limitations)Limitations This page does not cover: - **Configuring the Slack OAuth app**: Slack-side configuration (creating the app, picking redirect URIs, choosing scopes) happens in api.slack.com, not in Agentic Data Plane. - **Listing channels and looking up users**: Not exposed as tools. The server reads threads, posts messages, and adds reactions. --- # Page 34: SQL Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/sql.md --- # SQL Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: SQL Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/sql page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/sql.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/sql.adoc description: Query and write to SQL databases (PostgreSQL, MySQL, ClickHouse, SQL Server, and SQLite) through a managed MCP server hosted by Redpanda. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the SQL managed MCP server for your database learning-objective-2: Run a canonical SELECT query through the Inspector learning-objective-3: Pick the right driver and connection-string pattern for your database page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- The **SQL** managed MCP server gives agents read and write access to a SQL database through MCP. Redpanda runs the server in-process; you provide a connection string. Guardrails can restrict it to read-only. After reading this page, you will be able to: - Configure the SQL managed MCP server for your database - Run a canonical SELECT query through the Inspector - Pick the right driver and connection-string pattern for your database ## [](#what-this-mcp-server-does)What this MCP server does Redpanda’s SQL managed type proxies SQL statements to one of these database engines: - PostgreSQL (`postgres` or `pgx`) - MySQL / MariaDB - ClickHouse - Microsoft SQL Server (`mssql`) - SQLite (`sqlite3`) It exposes the following tools: - `query`: Run a read-only `SELECT` and return rows. Accepts positional parameters and an optional max-rows cap. - `execute`: Run a write statement (`INSERT`, `UPDATE`, `DELETE`, or DDL) and return the affected row count. Guardrails on the server config can restrict it: set `readonly` to disable `execute`, cap returned rows, restrict allowed schemas, block statement patterns, and set a per-query timeout. ## [](#prerequisites)Prerequisites - A SQL database reachable from the Agentic Data Plane. - A connection string (DSN) for the database, including the credentials. The DSN is stored as a sensitive value. ## [](#configure)Configure 1. Open **MCP Servers > Create Server**. 2. Pick **SQL** from the marketplace picker. 3. Fill in the identity fields (`name`, `description`). 4. In the SQL configuration form, provide: - `Driver`: One of `postgres`, `pgx`, `mysql`, `clickhouse`, `mssql`, or `sqlite3`. - `DSN`: The driver-specific connection string, including credentials. Stored as a sensitive value. - `Connection pool` (optional): Maximum open and idle connections, and connection lifetimes. - `Guardrails` (optional): `readonly` (disables `execute`), default and maximum row caps, a per-query timeout, allowed schemas, and blocked statement patterns. 5. Click **Create**. ## [](#test)Test After create, exercise the server through the Inspector tab. See [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/). A canonical first call: 1. Open the **Inspector** tab. 2. In **Tools**, select the `query` tool. 3. Run `SELECT 1` (or your driver’s equivalent). Confirm a single-row response. 4. To list tables, run `query` against the catalog, for example `SELECT table_name FROM information_schema.tables` on PostgreSQL or MySQL. ## [](#authentication)Authentication The SQL managed type has no MCP-level authentication modes. Credentials are carried inside the `DSN` (connection string), which is stored as a sensitive value. Supply them the way your driver expects, for example `postgres://user:password@host:5432/dbname`. User-delegated OAuth and service-account OAuth are not supported for SQL: there’s no per-user identity model that maps to a database connection. ## [](#use-with-agents)Use with agents After the SQL server is created, point an agent at the `Server URL` on the server’s **Connection** tab. The agent sees the SQL tools alongside any other MCP servers it has access to. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | connection refused from create | Database isn’t reachable from Agentic Data Plane. Confirm host, port, and any egress / firewall rules. | | authentication failed for user | Password reference points at the wrong secret, or the secret content is wrong. Re-create the secret with UPPER_SNAKE_CASE and verify it. | | Query timeout | Long-running queries exceed the configured timeout. Either tighten the query or raise the timeout on the server config. | | Tools list returns empty | The driver couldn’t introspect the schema. Verify the user has read access to information_schema (Postgres/MySQL) or the equivalent. | ## [](#limitations)Limitations - **Write access**: The `execute` tool runs writes and DDL unless `readonly` is set in the guardrails. Scope the database user’s permissions accordingly. - **Per-user database identities**: See [Authentication](#authentication). --- # Page 35: Workday Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/workday.md --- # Workday Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Workday Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/workday page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/workday.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/workday.adoc description: Drive Workday Human Resources business processes from an LLM agent. The Workday managed MCP wraps Workday's Human_Resources SOAP web services and authenticates with a service-account refresh-token grant. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Workday managed MCP server with an Integration System User (ISU) refresh token learning-objective-2: Choose the right WSDL version and tenant settings learning-objective-3: Run a Change_Personal_Information business process from the Inspector or an agent page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- The **Workday** managed MCP server lets agents drive Workday Human Resources business processes (multi-step, approval-driven workflows like onboarding, hiring, and personal-info changes) through Workday’s `Human_Resources` SOAP API. After reading this page, you will be able to: - Configure the Workday managed MCP server with an Integration System User (ISU) refresh token - Choose the right WSDL version and tenant settings - Run a Change\_Personal\_Information business process from the Inspector or an agent ## [](#what-this-mcp-server-does)What this MCP server does Workday is a SaaS HR and payroll platform. Customer mutations land through **business processes**: multi-step, approval-driven workflows. Workday’s REST API covers a partial read-side surface, but the business processes themselves live behind the SOAP `Human_Resources` WSDL. This MCP wraps the SOAP surface so an LLM can drive a business process the same way it would call any other tool. It is **not** a generic Workday browser. There is no SQL/RaaS access, no report execution, and no general "search the tenant" tool. Each MCP tool maps 1:1 to one business process. The current build exposes a single tool, `change_personal_information`, with more business processes landing as customers ask for them. ## [](#authentication-model)Authentication model Workday’s `Human_Resources` SOAP API authenticates with the OAuth 2.0 **refresh-token grant** plus HTTP Basic on the token endpoint. Unlike most managed MCPs, this is a vendor-specific auth shape that doesn’t fit the shared `static_key`, `service_account_oauth`, or `user_delegated_oauth` modes; Workday uses an `oauth_refresh_token` variant. The MCP exchanges the refresh token (in the request body) plus `username:password` (HTTP Basic) for a short-lived access token at `https:///ccx/oauth2//token`, then sends `Authorization: Bearer ` on every SOAP call. Authentication is one ISU per MCP instance, not per end-user. Customers that need per-user-delegated access mount multiple MCP instances (one per ISU/scope), not multiple users behind one MCP. ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - A Workday tenant where you can create an Integration System User and register an API client - Admin access to **Workday > Create Integration System User** and **Workday > Register API Client for Integrations** - Two Redpanda Agentic Data Plane secret-store entries: - `WORKDAY_PASSWORD`: The ISU password. - `WORKDAY_REFRESH_TOKEN`: The non-expiring refresh token. ## [](#get-workday-credentials)Get Workday credentials Set up authentication on the Workday side before configuring the MCP: 1. **Create an Integration System User (ISU)** under **Workday > Create Integration System User**. Note the username; it usually ends up as `@`. 2. **Register an API Client for Integrations** under **Workday > Register API Client for Integrations**: - **Grant types**: Include both `Refresh Token` (required) and `Authorization Code`. Workday’s UX requires both to be checked even when only the refresh-token grant is used at runtime. - **Non-Expiring Refresh Tokens**: Tick this option. Required for static-credential MCP usage; if Workday rotates the refresh token on every exchange, the cached value goes stale and authentication breaks. - **Scope**: Include `Human Resources` (and any other functional areas your business processes touch). 3. **Issue a refresh token to the ISU** by completing the one-time authorization-code flow Workday walks you through, or by using **View API Clients > Manage Refresh Tokens for Integrations** to mint one directly. 4. Save four values: the `tenant`, the `host` (the Workday data-center hostname, for example `wd2-impl-services1.workday.com`), the ISU `username`, and the ISU `password`. Save the `refresh_token` separately. ## [](#configure)Configure Create a new Workday MCP server in Agentic Data Plane: 1. Open **MCP Servers > Create Server**. 2. Pick **Workday** from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the Workday configuration form: | Field | Notes | | --- | --- | | Tenant | Your Workday tenant identifier, for example acme. | | Host | The Workday data-center hostname, for example wd2-impl-services1.workday.com. The MCP exchanges credentials at https:///ccx/oauth2//token. | | WSDL version | Optional; defaults to v46.0. Older tenants on v44.x or v45.x must set this explicitly to match the WSDL surface their tenant has enabled. | | Username | The ISU username (typically @). | | Password ref | Secret-store reference for the ISU password (UPPER_SNAKE_CASE). Example: WORKDAY_PASSWORD. | | Refresh token ref | Secret-store reference for the non-expiring refresh token (UPPER_SNAKE_CASE). Example: WORKDAY_REFRESH_TOKEN. | 5. Click **Create**. ### [](#configure-from-the-cli)Configure from the CLI ```bash rpk ai mcp-server create --name workday-hr --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.workday.v1.WorkdayMCPConfig", "tenant": "acme", "host": "wd2-impl-services1.workday.com", "wsdl_version": "v46.0", "oauth_refresh_token": { "username": "isu_user@acme", "password_secret_ref": "${secrets.WORKDAY_PASSWORD}", "refresh_token_secret_ref": "${secrets.WORKDAY_REFRESH_TOKEN}" } }' ``` ## [](#tools)Tools The Workday MCP exposes the following tools: | Tool | Description | | --- | --- | | change_personal_information | Kicks off the Change_Personal_Information business process for a worker. All fields except worker_id are optional. Only fields you set are sent to Workday, leaving the rest of the worker’s personal data unchanged. | ### [](#example-change-a-workers-date-of-birth-and-marital-status)Example: Change a worker’s date of birth and marital status ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/workday-hr \ -H 'Content-Type: application/json' -d '{ "jsonrpc":"2.0","method":"tools/call","id":1, "params":{ "name":"change_personal_information", "arguments":{ "worker_id":"E1001", "worker_id_type":"Employee_ID", "effective_date":{"year":2026,"month":5,"day":1}, "date_of_birth":{"year":1990,"month":5,"day":20}, "marital_status":"Married" } } }' ``` Dates use the `google.type.Date` shape (`{year, month, day}`); a missing field, or one with `year: 0`, is treated as "unset" and Workday applies its own default (today, for `effective_date`). A successful response surfaces the Workday Event WID and confirms the worker WID: ```json { "result": { "content": [{ "type": "text", "text": "{\"event_wid\":\"ev-wid-001\",\"worker_wid\":\"worker-wid-002\",\"version\":\"v46.0\"}" }] } } ``` If Workday returns a SOAP Fault (validation error, missing permissions, worker not found), the MCP surfaces the `faultstring` as a structured tool error so the LLM can decide whether to retry or ask the user. ## [](#tenant-specific-values)Tenant-specific values `gender`, `marital_status`, and `citizenship_status_ids` accept Workday IDs from the **customer’s** tenant configuration. Common defaults like `Single` / `Married` and ISO country codes work in most tenants, but check Workday’s "Maintain Marital Status" and "Maintain Citizenship Status" reports if a value is rejected. ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | 401 Unauthorized on token exchange | ISU credentials wrong, or the refresh token has been rotated. Confirm WORKDAY_PASSWORD and WORKDAY_REFRESH_TOKEN in the secret store are correct, and re-mint the refresh token in View API Clients > Manage Refresh Tokens for Integrations if needed. | | invalid_grant on every refresh | Non-Expiring Refresh Tokens was not checked when you registered the API client. Edit the client, tick the option, and re-mint the refresh token. | | SOAP fault: Invalid_Field_Value | A tenant-specific field ID (marital status, citizenship status, ethnicity) doesn’t match what your tenant accepts. Check the corresponding "Maintain …​" report in Workday for the exact IDs. | | SOAP fault: Insufficient_Permissions | The ISU lacks rights for the business process you’re invoking. Grant the relevant security domain on the ISU’s security group. | | SOAP fault: Worker_Not_Found | The worker_id plus worker_id_type doesn’t resolve. Verify the type (Employee_ID, Workday_ID, Contingent_Worker_ID) and the value. | ## [](#limitations)Limitations This page does not cover: - **Per-user-delegated access**: Workday authentication is one shared ISU per MCP. For per-user identities, mount multiple MCP instances (one per ISU/scope). - **Custom report execution**: This MCP wraps SOAP business processes, not reports. Use Workday RaaS or the report API for custom reports. - **Read-side data exploration**: There is no general _search Workday_ tool. Add specific business-process tools as needed. ## [](#next-steps)Next steps - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) - [Test a server’s tools](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) --- # Page 36: Zendesk Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/managed/zendesk.md --- # Zendesk Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Zendesk Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: managed/zendesk page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/zendesk.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/zendesk.adoc description: Search and manage Zendesk Support tickets, users, and Help Center articles. Service-account API token or per-user OAuth, plus token-efficient response shaping for LLM agents. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Zendesk managed MCP server in API-token or User-OAuth mode learning-objective-2: Pick the right scopes and Zendesk role for your workflows learning-objective-3: Search, read, create, and update tickets from the Inspector or an agent page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- The **Zendesk** managed MCP server lets agents search, read, create, and update tickets in your Zendesk Support instance, look up users and organizations, and search, read, create, and update Help Center articles. After reading this page, you will be able to: - Configure the Zendesk managed MCP server in API-token or User-OAuth mode - Pick the right scopes and Zendesk role for your workflows - Search, read, create, and update tickets from the Inspector or an agent ## [](#what-this-mcp-server-does)What this MCP server does Wraps the Zendesk REST API. The following authentication modes are supported: - **API token (Basic authentication)**: A long-lived agent token paired with the agent’s email. Best for service-account-style use. - **User OAuth**: Per-user Zendesk OAuth tokens resolved from the gateway’s [token vault](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#token-vault). Best when you want each agent action attributed to the calling end-user. Responses are curated for token efficiency: HATEOAS URLs, transport metadata, and rarely-used fields are dropped before reaching the LLM. Related users, groups, and organizations are resolved into nested ref objects through Zendesk side-loading (single round trip), and Help Center article HTML is converted to GitHub-flavored markdown. Typical responses are 3–7× smaller than raw Zendesk JSON. It is **not** intended for Zendesk admin operations (managing macros, triggers, ticket forms, custom fields, schedules, or SLAs); use the Zendesk Admin Center or a Terraform provider for those. ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - A Zendesk Support instance. - For **API token** mode: ability to create an API token under **Apps and integrations > APIs > Zendesk API**. - For **User OAuth** mode: a Zendesk OAuth client and an [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) configured in Redpanda Agentic Data Plane. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). ## [](#get-zendesk-credentials)Get Zendesk credentials ### [](#option-1-api-token-recommended-for-service-accounts)Option 1: API token (recommended for service accounts) 1. In the Zendesk Admin Center, go to **Apps and integrations > APIs > Zendesk API**. 2. On the **Settings** tab, enable **Token access**. 3. Click **Add API token**, give it a descriptive label (for example, `redpanda-ai-gateway`), and copy the token value. It is shown only once. 4. Note the **agent email** the token will act as (the email of the user who created the token). The HTTP Basic authentication string the MCP builds is `base64(/token:)`. The `/token` literal is Zendesk’s API-token quirk. 5. Store the token in the Agentic Data Plane secret store under a name like `ZENDESK_API_TOKEN`. **Required role**: Agents and Admins can use the API. Most ticket operations work for the Agent role; reading users with `search_users` requires Light Agent or higher; Help Center search works for any authenticated user. ### [](#option-2-user-oauth)Option 2: User OAuth For per-user authentication, register an OAuth client on Zendesk and a matching OAuth Provider in Agentic Data Plane: 1. Configure a Zendesk OAuth client under **Apps and integrations > APIs > OAuth Clients** (Confidential client, Authorization Code grant). 2. Register a matching OAuth Provider in Agentic Data Plane. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). Use Zendesk’s authorize and token endpoints. 3. Each end-user authenticates once through the OAuth flow; tokens are stored in the gateway’s token vault. **Required scopes**: `read tickets:write hc:read hc:write` covers all tools. Drop `tickets:write` (ticket writes) and `hc:write` (article create/update) if the MCP only needs to read. ## [](#configure)Configure Create a new Zendesk MCP server in Agentic Data Plane: 1. Open **MCP Servers > Create Server**. 2. Pick `Zendesk` from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the Zendesk configuration form: | Field | Notes | | --- | --- | | subdomain | Your Zendesk subdomain (the part before .zendesk.com). For acme.zendesk.com, set this to acme. | | auth | basic_auth for API-token mode, or user_oauth for per-user mode. | | basic_auth (API-token mode) | username (agent email used with the API token, for example agent@acme.com) and password_secret_ref (secret-store reference for the API token, UPPER_SNAKE_CASE). | | user_oauth (User-OAuth mode) | provider_name (the Zendesk OAuth Provider you configured) and the minimum required scopes (read, tickets:write, hc:read, hc:write covers all tools). | 5. Click **Create**. ### [](#configure-from-the-cli)Configure from the CLI For a managed server, set the auth method inside the `--managed-config` JSON. The `auth` field is required. #### API-token mode ```bash rpk ai mcp-server create --name acme-zendesk --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.zendesk.v1.ZendeskMCPConfig", "subdomain": "acme", "basic_auth": { "username": "agent@acme.com", "password_secret_ref": "ZENDESK_API_TOKEN" } }' ``` #### User-OAuth mode ```bash rpk ai mcp-server create --name acme-zendesk-oauth --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.zendesk.v1.ZendeskMCPConfig", "subdomain": "acme", "user_oauth": { "provider_name": "zendesk-prod", "required_scopes": ["read", "tickets:write", "hc:read"] } }' ``` ## [](#tools)Tools The Zendesk MCP exposes tools across tickets, users, organizations, and Help Center articles. Article writes (`create_article`, `update_article`) require the `hc:write` scope (User-OAuth mode) or a Help Center manager role (API-token mode): | Tool | Description | | --- | --- | | search_tickets | Search tickets with Zendesk’s search syntax (status:open priority:high tags:bug). The handler enforces a type:ticket qualifier and post-filters results, so non-ticket records can never leak through. | | list_tickets | Filter tickets by discrete fields (status, assignee_id, group_id). Faster than search_tickets and not subject to the search-API quota. Prefer this for "show me all open tickets assigned to X" workflows. | | get_ticket | Fetch a single ticket by ID with side-loaded requester, submitter, assignee, group, and organization. Set include_comments=true to embed up to 500 comments inline in the same response. | | list_ticket_comments | List the comment thread on a ticket with explicit pagination. Use this when the thread exceeds 500 comments; otherwise prefer get_ticket with include_comments=true. | | create_ticket | Open a new ticket (subject, description, optional priority/type/assignee/group/tags). Subject ≤150 chars, description ≤65536 chars, tags ≤50 chars each. | | update_ticket | Modify a ticket: status, priority, type, assignee, group, tags. Optionally append a public or internal comment in the same call. Distinct tags (replace) / add_tags / remove_tags fields. | | search_users | Find a Zendesk user by name, email, or other user-search fields. Returns full User objects. | | get_user | Fetch a single user by ID. Used to drill into a UserRef from a side-load when the agent needs the full User shape. | | list_organizations | List organizations in the Zendesk account. | | get_organization | Fetch a single organization by ID. Drills into an OrganizationRef from a side-load. | | search_articles | Search Help Center articles. Body is converted from HTML to GitHub-flavored markdown (tables included). | | get_article | Fetch a single Help Center article by ID. | | create_article | Create a new Help Center article from markdown (converted to HTML on upload), with an optional list of labels. The article is always created as a draft, so a human must publish it in Zendesk. | | update_article | Update an existing Help Center article. Only the fields you send change; omitted fields are left as-is. Markdown is converted to HTML on upload, and you can toggle draft status or clear all labels by sending an empty label list. | ### [](#example-triage-open-tickets)Example: Triage open tickets ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-zendesk \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_tickets", "arguments": { "query": "status:open priority:urgent", "max_results": 10 } } }' ``` ### [](#example-solve-a-ticket-with-a-closing-comment)Example: Solve a ticket with a closing comment ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-zendesk \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "update_ticket", "arguments": { "ticket_id": 12345, "status": "solved", "add_tags": ["resolved-by-agent"], "comment": { "body": "Resetting your password should fix this. Reopen if it persists.", "public": true } } } }' ``` ### [](#example-read-a-ticket-with-its-full-comment-thread)Example: Read a ticket with its full comment thread For "summarize this ticket" flows, inline the comments: ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-zendesk \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "get_ticket", "arguments": { "ticket_id": 12345, "include_comments": true } } }' ``` The handler follows Zendesk’s `next_page` URLs only when they point at the same host as the configured subdomain, so pagination cannot be hijacked by a malicious upstream response. ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | 401 Unauthorized (API-token mode) | Confirm ZENDESK_API_TOKEN content matches the value Zendesk showed at token creation, and the Username field is the agent email of the user who created the token. | | 403 Forbidden on search_users | The agent role on Zendesk’s side is below Light Agent. Upgrade the role or use API-token mode with a Light Agent or Admin email. | | OAuthConnectionRequired (User-OAuth mode) | First call from a user with no stored token. The user completes Zendesk’s OAuth consent flow, the token lands in the vault, and subsequent calls reuse it. See User-delegated OAuth. | | scope_upgrade_required (User-OAuth mode) | Server’s required_scopes was extended after users had already consented. Users re-consent with the higher scope. | | Search returns non-ticket records | Cannot happen: the handler enforces a type:ticket qualifier and post-filters results. If you see something unexpected, file an issue. | ## [](#limitations)Limitations This page does not cover: - **Zendesk admin operations**: Managing macros, triggers, ticket forms, custom fields, schedules, or SLAs. Use the Zendesk Admin Center or a Terraform provider. - **Voice / chat / Talk**: This MCP wraps Support tickets and Help Center; voice and chat are separate Zendesk products with their own APIs. ## [](#next-steps)Next steps - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) --- # Page 37: How MCP Servers Work **URL**: https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview.md --- # How MCP Servers Work > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: How MCP Servers Work latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: mcp-overview page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: mcp-overview.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/mcp-overview.adoc description: Connect AI agents to your databases, APIs, and business systems through managed MCP servers Redpanda hosts for you, or self-managed servers you register with Agentic Data Plane. page-topic-type: overview personas: agent_builder, platform_engineer learning-objective-1: Explain how AI agents connect to tools through MCP servers in Agentic Data Plane learning-objective-2: Distinguish managed from self-managed MCP server backends and choose the right type for your use case learning-objective-3: Identify key MCP capabilities including tool discovery, authentication, and code mode page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-10" --- The Model Context Protocol (MCP) is how AI agents talk to tools. In the Agentic Data Plane, you create **MCP Servers** that agents can connect to. Each MCP server exposes a set of [tools](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#tool), [resources](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#resource), and [prompts](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#prompt) that an agent can discover at runtime through `tools/list` and invoke through structured JSON-RPC calls. Redpanda handles upstream credentials, authentication flows, observability, and aggregation, so you can focus on what your agents do, not on the plumbing. Current MCP versions keep discovery and calls interoperable while allowing clients and servers to negotiate newer capabilities, such as long-running work and richer user experiences. The Inspector shows the negotiated protocol version and only surfaces capabilities that the server advertises. After reading this page, you will be able to: - Explain how AI agents connect to tools through MCP servers in Agentic Data Plane - Distinguish managed from self-managed MCP server backends and choose the right type for your use case - Identify key MCP capabilities including tool discovery, authentication, and code mode ![MCP Gateway connection flow. An Agentic Data Plane agent or external MCP client authenticates to MCP Gateway, discovers and calls tools, and receives results. MCP Gateway applies identity, access, authentication, policies, and observability before routing to either a Redpanda-managed MCP implementation or a self-managed MCP endpoint, which then reaches the upstream business system.](https://docs.redpanda.com/agentic-data-plane/connect/_images/mcp-gateway-connection-flow.svg) Figure 1. MCP Gateway gives managed and self-managed servers one governed tool path Redpanda offers two kinds of MCP server backends: | Backend | When to use | | --- | --- | | Managed | Redpanda hosts the server in-process. You pick a type from the marketplace (SQL, Kafka, Slack, Jira, OpenAPI, and many more) and configure it with your credentials. No infrastructure to run. | | Self-managed | You already run an MCP server somewhere and want Redpanda to proxy it for authentication, observability, aggregation, and agent access. Redpanda fronts your server with a managed URL and resolves authentication at the gateway. | The default catalog covers databases, cloud and productivity services, streaming systems, and communication tools. See [Managed catalog](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/) for the full list. ## [](#when-to-use-each)When to use each | Concern | Managed | Self-managed | | --- | --- | --- | | Infrastructure ownership | Redpanda hosts and operates | You host and operate | | Upstream credentials | Redpanda secret store; per-type schema | Redpanda secret store or token vault; you control the upstream authentication | | Custom tool logic | Limited to what the type exposes | Anything the MCP protocol supports | | Startup latency | In-process; effectively zero | Network round-trip to your endpoint | | Upgrade cadence | Redpanda manages | You manage | ## [](#whats-in-redpanda-agentic-data-plane)What’s in Redpanda Agentic Data Plane Agentic Data Plane has these top-level areas: - **LLM Providers**: OpenAI, Anthropic, Bedrock, Google AI, OpenAI-compatible endpoints. See [Configure your LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/). - **MCP Servers**: You are here. Both managed and self-managed servers live in this list. - **My Connections**: Each user’s own per-user OAuth connections for user-delegated MCP servers. See [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). - **Integrations setup**: The admin home for OAuth plumbing. Its **Outbound providers** tab holds reusable upstream OAuth provider definitions used by user-delegated MCP authentication (see [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/)); its **Inbound clients** tab holds external tools registered to request access tokens from the gateway (see [Connect Remote MCP Clients](https://docs.redpanda.com/agentic-data-plane/connect/remote-mcp-clients/)). ## [](#key-capabilities)Key capabilities - **Tool discovery**: After you create or register a server, Redpanda performs a live `tools/list` against it and populates the server’s detail page so you can see which tools are visible to agents. - **Service-account and user-delegated authentication**: Pick a single shared upstream identity for all callers, or have each end-user authenticate against the upstream system with their own credentials. - **Code mode**: For a server with a large tool catalog, turn on code mode to expose just two tools, `search` and `execute`, so an agent can find tools by regex and run them through a JavaScript sandbox instead of loading every tool definition into its context. See [Code Mode](https://docs.redpanda.com/agentic-data-plane/gateway/code-mode/). - **Inspector**: Test each tool, resource, and prompt directly from Agentic Data Plane before pointing an agent at the server. See [Test a server’s tools](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/). ## [](#next-steps)Next steps - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) - [Register a Self-Managed MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/register-remote/) - [Plug in an App, Database, or Tool](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/) --- # Page 38: Connect Tools with MCP Servers **URL**: https://docs.redpanda.com/agentic-data-plane/connect/mcp-servers.md --- # Connect Tools with MCP Servers > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Connect Tools with MCP Servers latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: mcp-servers page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: mcp-servers.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/mcp-servers.adoc description: Learn how MCP servers expose tools and data to agents, then plug in a managed type or build, register, and test your own. page-git-created-date: "2026-06-01" page-git-modified-date: "2026-06-18" --- MCP servers expose tools and data to your agents. Plug in a managed type from the catalog, or build, register, and test a server of your own. - [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) Connect AI agents to your databases, APIs, and business systems through managed MCP servers Redpanda hosts for you, or self-managed servers you register with Agentic Data Plane. - [Plug in an App, Database, or Tool](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/) Reference of every managed MCP server type Redpanda hosts in-process, grouped by category, with display name, description, and a link to a setup guide where one exists. - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) Create an MCP server in the Agentic Data Plane by picking a managed type from the marketplace or registering a self-managed server you host yourself, then configure authentication, code mode, and access. - [Register a Self-Managed MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/register-remote/) Front your own MCP server with a managed Redpanda URL. Pick a transport, configure authentication, and let agents discover the server's tools through Redpanda. - [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) Use the Inspector tab to call tools, inspect resources and prompts, and verify your MCP server works without standing up an agent. - [Shape Tool Data with Data Policies](https://docs.redpanda.com/agentic-data-plane/connect/data-policies/) Add data policies to an MCP server to mask, drop, or filter the data its tools send and return, restrict argument values, and preview the effect before saving. - [Code Mode](https://docs.redpanda.com/agentic-data-plane/gateway/code-mode/) Turn on code mode for an MCP server to replace a large tool catalog with two tools, search and execute, and cut the token cost of tool-heavy servers. --- # Page 39: Configure an OAuth Provider **URL**: https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers.md --- # Configure an OAuth Provider > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Configure an OAuth Provider latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: oauth-providers page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: oauth-providers.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/oauth-providers.adoc description: Register an OAuth provider in Agentic Data Plane so MCP servers can authenticate users (or service accounts) against an upstream system like Slack, Jira, GitHub, or Salesforce. page-topic-type: how-to personas: platform_engineer, security_compliance_lead learning-objective-1: Register an OAuth provider for an upstream system you want MCP servers to authenticate against learning-objective-2: Grant the right permissions so principals can attach the provider to MCP servers learning-objective-3: Edit, rotate credentials on, or delete an OAuth provider page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-04" --- Register an OAuth provider so AI Gateway can authenticate against an upstream system on behalf of users or service accounts. Any MCP server for that upstream attaches to the provider instead of managing its own credentials. After completing this guide, you will be able to: - Register an OAuth provider for an upstream system you want MCP servers to authenticate against - Grant the right permissions so principals can attach the provider to MCP servers - Edit, rotate credentials on, or delete an OAuth provider > ❗ **IMPORTANT** > > OAuth providers and OAuth clients govern **opposite directions** of authentication and are separate resources. > > - An **OAuth provider** (this page) governs **outbound** authentication: AI Gateway authenticating to an upstream system (GitHub, Slack, Salesforce, and so on) on a user’s behalf so MCP servers can call that upstream. > > - An **OAuth client** governs **inbound** authentication: an external app (Claude Desktop, ChatGPT, Copilot Studio) authenticating to AI Gateway so the app’s users can invoke MCP tools. > > > Both are managed under the **Integrations setup** entry in the sidebar: OAuth providers on the **Outbound providers** tab, OAuth clients on the **Inbound clients** tab. They remain separate resources with separate API definitions, permissions, and lifecycles. To register or manage an OAuth client (including revoking its refresh tokens to force a re-sign-in), see [Connect remote MCP clients to AI Gateway](https://docs.redpanda.com/agentic-data-plane/connect/remote-mcp-clients/). ## [](#prerequisites)Prerequisites Before you register the provider, make sure you have: - An OAuth 2.0 application registered with the upstream provider, with the gateway’s redirect URI configured. The redirect URI is the AI Gateway’s OAuth callback (typically `https://aigw..clusters.rdpa.co/oauth/v1/callback`). - The OAuth app’s **client ID** and **client secret**. - A secret already created in the Redpanda Agentic Data Plane secret store for the client secret. Secret references must be `UPPER_SNAKE_CASE`, for example `SLACK_CLIENT_SECRET`. - The list of **scopes** the upstream API needs. Include every scope any MCP server attached to this provider may need; users re-consent when scopes are added later. ## [](#required-permissions)Required permissions OAuth providers are governed by their own permission set. Among the built-in roles only Admin holds these permissions, so anyone else acts on OAuth providers through an [access policy](https://docs.redpanda.com/agentic-data-plane/control/access-policies/). A policy names the matching `OAuthProvider` actions: `get`, `list`, `create`, `update`, `delete`, and `attach`. The `attach` action is worth separating from the rest. A policy can grant someone the ability to bind an existing provider to an MCP server without also letting them create or edit providers. | Permission | Allows | | --- | --- | | dataplane_aigateway_oauthprovider_create | Create new OAuth providers. | | dataplane_aigateway_oauthprovider_get | Read existing OAuth providers. | | dataplane_aigateway_oauthprovider_update | Edit an existing OAuth provider’s endpoints, scopes, or credentials. | | dataplane_aigateway_oauthprovider_delete | Delete an OAuth provider. | | dataplane_aigateway_oauthprovider_attach | Required to attach this provider to an MCP server. Enforced as a sub-resource check in CreateMCPServer and UpdateMCPServer whenever authConfig.userOauth.provider_name is set or swapped. Without this permission, a principal with mcpserver_update could otherwise bind any provider’s token vault to an MCP they control and indirectly consume its tokens. | > 📝 **NOTE** > > The `_attach` permission is independent from `_get`, `_create`, `_update`, and `_delete`. Grant it only to the principals that need to bind a given provider’s token vault to an MCP server, and scope the policy to that provider with `resource == OAuthProvider::""`. ## [](#browse-oauth-providers)Browse OAuth providers Open **Integrations setup** in the sidebar and select the **Outbound providers** tab. The tab lists every provider registered in your organization. (The older `/oauth-providers` path still works but redirects here.) The list shows the following columns: | Column | What it shows | | --- | --- | | Name | The provider’s machine identifier (used in MCP server configuration to attach this provider). | | Grant types | A badge per grant type. Typically Browser consent for user-delegated OAuth. | | Status | Enabled or Disabled. | | Scopes | A chip list of the supported scopes, for example read:user, repo, read:org for a GitHub provider. | A **Filter** button narrows the list. The **Create provider** button opens the create form. ## [](#register-an-oauth-provider-in-the-ui)Register an OAuth provider in the UI Walk through the create form to register the upstream: 1. Open **Integrations setup** in the sidebar and select the **Outbound providers** tab. 2. Click **Create provider**. 3. Pick how to configure the provider: - Choose a preset from the catalog to pre-fill the standard authorization and token endpoints and recommended scopes. - Choose **Custom Provider** to enter the endpoints yourself. - Choose **Discover from MCP server URL** to point the gateway at a remote MCP server and let it detect the OAuth configuration for you. See [Discover a provider from an MCP server URL](#discover-a-provider-from-an-mcp-server-url). The catalog groups presets into categories you can filter with the category chips: **Identity & SSO**, **Code & Dev**, **Productivity**, **Files & Storage**, **Communication**, **CRM & Support**, **Data Platform**, **Observability**, **Infrastructure**, and **HR & Legal**. It covers common providers across these categories, such as GitHub, Google, Okta, Microsoft, and Slack, with more added over time. For any upstream without a preset, use **Custom Provider** and enter its endpoints manually. 4. Fill in the identity fields: | Field | Required | Notes | | --- | --- | --- | | Name | Yes | Lowercase letters, numbers, and hyphens only. Used to reference the provider in MCP server configuration. Immutable after create. | | Display name | Yes | Human-readable label shown in the UI. | | Authorization endpoint | Yes | The upstream’s OAuth authorize URL, for example https://slack.com/oauth/v2/authorize. | | Token endpoint | Yes | The upstream’s OAuth token URL, for example https://slack.com/api/oauth.v2.access. | | Revocation endpoint | No | RFC 7009 token-revocation URL. When set, the gateway calls it on disconnect (best-effort). Not all providers support this. | 5. Pick a `Grant type`: - **Browser Consent**: The user approves access in their browser (OAuth 2.0 Authorization Code flow). The default for user-delegated OAuth. - **Token Exchange**: RFC 8693 server-to-server token exchange. Shown in the form but not yet functional (future release); the gateway exchanges the user’s identity-provider JWT for a provider-scoped token without browser interaction. 6. Pick a `Token-endpoint authentication method`: - **HTTP Basic**: `client_id:client_secret` sent as the Basic authentication header. Most common. - **POST body**: Credentials sent as form fields in the token-request body. - **None**: For public clients that rely on PKCE only. Pick this when the upstream OAuth app is registered as a public client and AI Gateway authenticates by proving possession of a PKCE code verifier rather than a stored client secret. Leave the client-secret reference unset. 7. Provide the `Client ID` and a `Client Secret Ref` (a secret-store key in `UPPER_SNAKE_CASE`, for example `SLACK_CLIENT_SECRET`). Use the **Existing** tab to pick a secret already in the store, or **New** to create one inline. Leave the reference empty only for public clients that authenticate with PKCE. 8. Define the `Scopes`. Include every scope any MCP server may need. 9. Optionally turn on `Require PKCE` to add PKCE (RFC 7636) to the consent flow. Leave `Enabled` on so the provider can start consent flows. 10. Click **Create Provider**. The provider appears in the **Outbound providers** list. ## [](#discover-a-provider-from-an-mcp-server-url)Discover a provider from an MCP server URL When you connect to a remote MCP server that authenticates users over OAuth, you can let AI Gateway detect the server’s OAuth configuration instead of entering endpoints and credentials by hand. If the remote server supports client metadata documents, AI Gateway identifies itself with an HTTPS URL and does not create a registration. If the server instead supports dynamic client registration, the gateway registers itself automatically. In either case, you have no endpoints or client credentials to paste. > 📝 **NOTE** > > This is the _outbound_ direction: AI Gateway identifies itself to a remote MCP server’s OAuth server. It is distinct from the inbound direction, where external MCP clients identify themselves to AI Gateway. To let clients such as Claude Code or ChatGPT connect to the gateway, see [Connect remote MCP clients to AI Gateway](https://docs.redpanda.com/agentic-data-plane/connect/remote-mcp-clients/). To discover a provider: 1. Open **Integrations setup** in the sidebar and select the **Outbound providers** tab. 2. Click **Create provider**, then select the **Discover from MCP server URL** card. 3. Enter the remote MCP server’s URL and start the discovery probe. 4. Review the result and finish the setup. The gateway takes one of these paths, depending on what the probe finds: | Result | What happens | | --- | --- | | Server supports client metadata documents | The gateway identifies itself with the client metadata document it publishes and pre-fills the provider. No client registration or shared client secret is required. Confirm the details to create the provider. | | Server supports dynamic client registration | The gateway registers itself as an OAuth client with the remote server’s authorization server and pre-fills the provider. Confirm the details to create the provider. | | A matching provider already exists | The gateway points you at the provider already registered for that server so you can attach it instead of creating a duplicate. | | Server has no OAuth, or OAuth without client metadata documents or dynamic client registration | The gateway falls back to the manual create form, pre-filling whatever it could detect. Complete the remaining fields as described in Register an OAuth provider in the UI. | A provider created this way is marked with a **Discovered** badge in the list and on its detail page, which distinguishes it from a provider you configured manually. Its detail page also shows a **Registration** card. See [View provider details](#view-provider-details). You can reach the same automatic setup from the other direction. When you create a self-managed MCP server that authenticates users over OAuth, Redpanda checks the server URL and sets up the OAuth client as part of creating the server, with no provider registered first. The provider it creates appears here with the same **Discovered** badge. See [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). ## [](#register-from-the-cli)Register from the CLI Use [`rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) to script provider registration: ```bash rpk ai oauth-provider create \ --name ramp \ --display-name "Ramp" \ --auth-endpoint "https://app.ramp.com/v1/authorize" \ --token-endpoint "https://api.ramp.com/developer/v1/token" \ --client-id "$RAMP_CLIENT_ID" \ --client-secret-ref RAMP_CLIENT_SECRET \ --scopes "transactions:read,cards:read,users:read" ``` | Flag | Notes | | --- | --- | | --name | Resource name. Lowercase letters, numbers, hyphens. Immutable. Required. | | --display-name | Human-readable display name shown in the UI. Required. | | --auth-endpoint | OAuth authorization endpoint URL. Required. | | --token-endpoint | OAuth token endpoint URL. Required. | | --client-id | Client ID from the upstream OAuth app. Required. | | --client-secret-ref | Secret-store reference (UPPER_SNAKE_CASE). | | --scopes | Comma-separated scope list. | | --grant-types | Grant types: browser-consent (default), token-exchange. Comma-separated. | | --token-auth-method | Token-endpoint authentication method: client-secret-basic (default), client-secret-post, none. | | --pkce | Require PKCE for authorization code grants. | | --revocation-endpoint | OAuth token revocation endpoint URL. | | --enabled | Whether the provider is enabled (default true). | ## [](#list-and-filter-providers-with-the-api)List and filter providers with the API To enumerate OAuth providers programmatically, call `OAuthProviderService.ListOAuthProviders`. Beyond the `name_contains` substring match, the request accepts an AIP-160 `filter` expression and an AIP-132 `order_by`, so you can scope and sort the list on the server (for example, to fetch only enabled providers, ordered by display name) instead of filtering the loaded page. The list endpoint uses the same OIDC client-credentials authentication as the rest of AI Gateway. Mint a service-account access token using the flow in [Authenticate with OIDC client credentials](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/#authenticate-with-oidc-client-credentials), then pass it as a bearer token. The service account needs `dataplane_aigateway_oauthprovider_list`. The request’s `filter` object carries two independent fields: | Field | Meaning | | --- | --- | | name_contains | Case-insensitive substring match on the provider name. | | filter | AIP-160 expression (maximum 1024 characters) that the server ANDs with name_contains and the tenant scope. Filterable columns: name, display_name, enabled, grant_types, created_at, and updated_at. Use it for multi-value OR semantics, for example enabled = true or grant_types = "OAUTH_GRANT_TYPE_BROWSER_CONSENT". The grant_types column accepts the OAuthGrantType enum values OAUTH_GRANT_TYPE_BROWSER_CONSENT and OAUTH_GRANT_TYPE_TOKEN_EXCHANGE; enabled accepts true or false. | Set `order_by` (maximum 256 characters) to a comma-separated list of fields, each optionally suffixed with \` desc\` (ascending by default), for example `display_name` or `created_at desc`. Orderable fields are the keyset columns `name`, `display_name`, and `created_at`. An unsupported field returns `InvalidArgument`. Leave `order_by` empty to use the server default (`created_at desc`). The order is encoded into the page token, so keep it stable across a paged walk. ```bash ACCESS_TOKEN="" # from the client_credentials flow DATAPLANE_BASE="https://aigw..clusters.rdpa.co" curl -s --request POST \ --url "${DATAPLANE_BASE}/redpanda.api.adp.v1alpha1.OAuthProviderService/ListOAuthProviders" \ --header "Authorization: Bearer ${ACCESS_TOKEN}" \ --header 'Content-Type: application/json' \ --data '{ "filter": { "filter": "enabled = true" }, "order_by": "display_name", "page_size": 50 }' | jq ``` The response carries the matching `oauth_providers`, a `next_page_token` for the next page, an estimated `total_size` (AIP-158) of all providers matching the filter (ignoring pagination), and the gateway-wide `callback_url` (the OAuth redirect URI to register with your identity provider). ## [](#attach-to-an-mcp-server)Attach to an MCP server To attach an OAuth provider to an MCP server, the principal needs `dataplane_aigateway_oauthprovider_attach` on the named provider plus the usual `mcpserver_create` / `mcpserver_update` permission. See [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) for the full attach flow and [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) for the consent flow that runs on first call. ## [](#view-provider-details)View provider details Click a provider in the list to open its detail page. The header shows the display name, status badge, and resource name, with **Connect**, **Edit**, and **Delete** actions. A provider that was set up through discovery also shows a **Discovered** badge. The page groups the configuration into cards: - **Authorization Callback URL**: The gateway callback to register on the upstream OAuth app. - **OAuth Endpoints**: The authorization, token/refresh, and revocation endpoints. - **Client Configuration**: Client ID, Client Secret Ref, Auth Method, and whether PKCE is required. - **Registration** (discovered providers only): The dynamic-registration state. It shows the registration endpoint, the client-configuration URI (the RFC 7592 endpoint used to verify, refresh, or delete the registered client), and when the registration was last verified. The registration access token is a managed credential kept in the secret store, and its value is never shown. - **Scopes & Grant Types**: The default scopes and grant types. - **Metadata**: When the provider was created and last updated. ## [](#edit-and-rotate-credentials)Edit and rotate credentials You can change the provider’s configuration or rotate its client secret without re-creating the resource: - **Edit**: Open the provider’s detail page and click **Edit**. Endpoints, scopes, display name, and the client-secret reference can change. The `Name` is immutable. - **Rotate credentials**: Update the secret content in the secret store under the same name (for example, `SLACK_CLIENT_SECRET`). The provider’s reference is unchanged. Existing tokens in the vault stay valid; the new client secret is used the next time AI Gateway exchanges credentials. - **Disable temporarily**: Deleting the provider invalidates every MCP server’s connections that reference it, so disable the dependent MCP servers first if you want to pause traffic without losing user consent. ## [](#delete-a-provider)Delete a provider Deleting an OAuth provider: - Removes the provider record. - Causes every MCP server that referenced it to fail authentication on the next call (the `provider_name` reference no longer resolves). - Leaves user-stored tokens in the vault until garbage-collected, but they’re unusable without the provider definition. Plan the deletion: disable or reconfigure dependent MCP servers first, communicate the cutover to users so they can re-consent against a replacement provider, then delete. ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | PermissionDenied when creating an MCP server with this provider attached | Nothing grants the principal dataplane_aigateway_oauthprovider_attach on this provider. Ask an admin for a policy granting Action::"OAuthProvider.attach", scoped to this provider. | | Consent flow fails with redirect_uri_mismatch | The OAuth app’s registered redirect URI doesn’t match the gateway’s callback. Update the upstream OAuth app to include https://aigw..clusters.rdpa.co/oauth/v1/callback. | | invalid_client during token exchange | Client ID or client secret is wrong, or the Token-endpoint authentication method doesn’t match what the upstream expects. Check the upstream OAuth app’s settings. | | invalid_scope during consent | A scope in Supported scopes isn’t valid for the upstream. Check the upstream’s scope reference and remove or rename the offending scope. | ## [](#next-steps)Next steps - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) - [Plug in an App, Database, or Tool](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/) --- # Page 40: Integrate with Redpanda Pipelines **URL**: https://docs.redpanda.com/agentic-data-plane/connect/pipeline-integration-patterns.md --- # Integrate with Redpanda Pipelines > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Integrate with Redpanda Pipelines latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: pipeline-integration-patterns page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: pipeline-integration-patterns.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/pipeline-integration-patterns.adoc description: Build Redpanda Connect pipelines that invoke agents for event-driven processing and streaming enrichment. page-topic-type: best-practices personas: agent_builder, platform_engineer learning-objective-1: Identify when pipelines should call agents for stream processing learning-objective-2: Design event-driven agent invocation using the a2a_message processor learning-objective-3: Implement streaming enrichment with AI-generated fields page-git-created-date: "2026-05-28" page-git-modified-date: "2026-06-18" --- Build Redpanda Connect pipelines that invoke agents for automated, event-driven processing. Pipelines use the `a2a_message` processor to call agents for each event in a stream when you need AI reasoning, classification, or enrichment at scale. After reading this page, you will be able to: - Identify when pipelines should call agents for stream processing - Design event-driven agent invocation using the `a2a_message` processor - Implement streaming enrichment with AI-generated fields This page focuses on pipelines calling agents (pipeline-initiated integration). For agents invoking MCP tools, see [Agent needs capabilities](https://docs.redpanda.com/agentic-data-plane/connect/integration-overview/#agent-needs-capabilities). For external applications calling agents, see [External system calls agent](https://docs.redpanda.com/agentic-data-plane/connect/integration-overview/#external-system-calls-agent). ## [](#how-pipelines-invoke-agents)How pipelines invoke agents Pipelines use the [`a2a_message`](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/processors/a2a_message/) processor to invoke agents for each event in a stream. The processor uses the [A2A protocol](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/) to discover and communicate with agents. When the `a2a_message` processor receives an event, it sends the event data to the specified agent along with any prompt you provide. The agent processes the event using its reasoning capabilities and returns a response. The processor then adds the agent’s response to the event for further processing or output. The pipeline determines when to invoke agents based on events, not agent reasoning. ## [](#when-to-use-this-pattern)When to use this pattern Use the `a2a_message` processor when pipelines need AI reasoning for every event in a stream. The `a2a_message` processor is appropriate when: - **Every event needs AI analysis:** Each message requires reasoning, classification, or decision-making. - **You need streaming enrichment:** Add AI-generated fields to events at scale. - **Processing is fully automated:** No human in the loop, event-driven workflows. - **Batch latency is acceptable:** Agent reasoning time is tolerable for your use case. - **You’re handling high-volume streams:** Processing thousands or millions of events. ## [](#use-cases)Use cases Use the `a2a_message` processor in pipelines for these common patterns. ### [](#event-driven-agent-invocation)Event-driven agent invocation Use this pattern for real-time fraud detection on every transaction. Invoke agents automatically for each event: ```yaml # Event-driven agent invocation pipeline # Invokes an agent for each event in a stream input: redpanda: seed_brokers: ["${REDPANDA_BROKERS}"] topics: [transactions] consumer_group: fraud-detector tls: enabled: true sasl: - mechanism: SCRAM-SHA-256 username: "${REDPANDA_USERNAME}" password: "${REDPANDA_PASSWORD}" pipeline: processors: - a2a_message: agent_card_url: "${AGENT_CARD_URL}" prompt: "Analyze this transaction: ${!content()}" output: redpanda: seed_brokers: ["${REDPANDA_BROKERS}"] topic: fraud-alerts tls: enabled: true sasl: - mechanism: SCRAM-SHA-256 username: "${REDPANDA_USERNAME}" password: "${REDPANDA_PASSWORD}" ``` Replace `AGENT_CARD_URL` with your actual agent card URL. See [Agent card location](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/#agent-card-location). ### [](#streaming-data-enrichment)Streaming data enrichment Use this pattern to add sentiment scores to every customer review in real time. Add AI-generated metadata to events: ```yaml processors: - branch: request_map: 'root = this.text' processors: - a2a_message: agent_card_url: "${AGENT_CARD_URL}" result_map: 'root.sentiment = content()' ``` Replace `AGENT_CARD_URL` with your actual agent card URL. See [Agent card location](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/#agent-card-location). ### [](#asynchronous-workflows)Asynchronous workflows Use this pattern for nightly batch summarization of reports where latency is acceptable. Process events in the background: ```yaml input: redpanda: seed_brokers: ["${REDPANDA_BROKERS}"] topics: [daily-reports] consumer_group: report-analyzer tls: enabled: true sasl: - mechanism: SCRAM-SHA-256 username: "${REDPANDA_USERNAME}" password: "${REDPANDA_PASSWORD}" pipeline: processors: - a2a_message: agent_card_url: "${AGENT_CARD_URL}" prompt: "Summarize this report: ${!content()}" ``` Replace `AGENT_CARD_URL` with your actual agent card URL. See [Agent card location](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/#agent-card-location). ### [](#multi-agent-pipeline-orchestration)Multi-agent pipeline orchestration Use this pattern to translate feedback, analyze sentiment, and route it to the appropriate team. Chain multiple agents in sequence: ```yaml processors: - a2a_message: agent_card_url: "${TRANSLATOR_AGENT_URL}" - a2a_message: agent_card_url: "${SENTIMENT_AGENT_URL}" - a2a_message: agent_card_url: "${ROUTER_AGENT_URL}" ``` Replace the agent URL variables with your actual agent card URLs. See [Agent card location](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/#agent-card-location). ### [](#agent-as-transformation-node)Agent as transformation node Use this pattern to convert natural language queries to SQL for downstream processing. Use agent reasoning for complex transformations: ```yaml processors: - a2a_message: agent_card_url: "${AGENT_CARD_URL}" prompt: "Convert to SQL: ${!this.natural_language_query}" ``` Replace `AGENT_CARD_URL` with your actual agent card URL. See [Agent card location](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/#agent-card-location). ## [](#when-not-to-use-this-pattern)When not to use this pattern Do not use the `a2a_message` processor when: - Users need to interact with agents interactively. - The transformation is simple and does not require AI reasoning. - Agents need to dynamically decide what data to fetch based on context. For a detailed comparison between pipeline-initiated and agent-initiated integration patterns, see [Pattern comparison](https://docs.redpanda.com/agentic-data-plane/connect/integration-overview/#pattern-comparison). ## [](#example-real-time-fraud-detection)Example: Real-time fraud detection This example shows a complete pipeline that analyzes every transaction with an agent. ### [](#pipeline-configuration)Pipeline configuration ```yaml # Fraud detection pipeline with score-based routing # Analyzes every transaction and routes to different topics based on fraud score input: redpanda: seed_brokers: ["${REDPANDA_BROKERS}"] topics: [transactions] consumer_group: fraud-detector tls: enabled: true sasl: - mechanism: SCRAM-SHA-256 username: "${REDPANDA_USERNAME}" password: "${REDPANDA_PASSWORD}" pipeline: processors: - branch: request_map: | root.transaction_id = this.id root.amount = this.amount root.merchant = this.merchant root.user_id = this.user_id processors: - a2a_message: agent_card_url: "${AGENT_CARD_URL}" prompt: | Analyze this transaction for fraud: Amount: ${! json("amount") } Merchant: ${! json("merchant") } User: ${! json("user_id") } Return JSON: { "fraud_score": 0-100, "reason": "explanation", "recommend_block": true/false } result_map: | root = this root.fraud_analysis = content().parse_json().catch({}) - mapping: | root = this meta fraud_score = this.fraud_analysis.fraud_score output: switch: cases: - check: 'meta("fraud_score") >= 80' output: redpanda: seed_brokers: ["${REDPANDA_BROKERS}"] topic: fraud-alerts-high tls: enabled: true sasl: - mechanism: SCRAM-SHA-256 username: "${REDPANDA_USERNAME}" password: "${REDPANDA_PASSWORD}" - check: 'meta("fraud_score") >= 50' output: redpanda: seed_brokers: ["${REDPANDA_BROKERS}"] topic: fraud-alerts-medium tls: enabled: true sasl: - mechanism: SCRAM-SHA-256 username: "${REDPANDA_USERNAME}" password: "${REDPANDA_PASSWORD}" - output: redpanda: seed_brokers: ["${REDPANDA_BROKERS}"] topic: transactions-cleared tls: enabled: true sasl: - mechanism: SCRAM-SHA-256 username: "${REDPANDA_USERNAME}" password: "${REDPANDA_PASSWORD}" ``` Replace `AGENT_CARD_URL` with your agent card URL. See [Agent card location](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/#agent-card-location). This pipeline: - Consumes every transaction from the `transactions` topic. - Sends each transaction to the fraud detection agent using `a2a_message`. - Routes transactions to different topics based on fraud score. - Runs continuously, analyzing every transaction in real time. ## [](#next-steps)Next steps - [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) - [Choose an Integration Pattern](https://docs.redpanda.com/agentic-data-plane/connect/integration-overview/) - [Connect Agents with A2A](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/) --- # Page 41: Register a Self-Managed MCP Server **URL**: https://docs.redpanda.com/agentic-data-plane/connect/register-remote.md --- # Register a Self-Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Register a Self-Managed MCP Server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: register-remote page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: register-remote.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/register-remote.adoc description: Front your own MCP server with a managed Redpanda URL. Pick a transport, configure authentication, and let agents discover the server's tools through Redpanda. page-topic-type: how-to personas: platform_engineer, agent_builder learning-objective-1: Register a self-managed MCP server in Agentic Data Plane learning-objective-2: Pick the right transport (SSE vs. Streamable HTTP) and authentication mode learning-objective-3: Confirm tool discovery completed and the server is reachable through its proxy URL page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- Register your existing MCP server with Redpanda to add authentication, observability, and agent aggregation without changing your server’s code. This guide covers the self-managed path from [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) in depth. Choose this when you already run a server and want Redpanda to proxy it. After completing this guide, you will be able to: - Register a self-managed MCP server in Agentic Data Plane - Pick the right transport (SSE vs. Streamable HTTP) and authentication mode - Confirm tool discovery completed and the server is reachable through its proxy URL ## [](#when-to-use-this)When to use this Choose self-managed registration when: - The MCP server is already deployed in your environment and you don’t want to migrate it to a managed type. - You need custom tool logic that no managed type provides. - You want a unified MCP URL (and Inspector / observability / agent access) across servers without standing up your own gateway. If you don’t already run a server, prefer a managed type. See [Managed catalog](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/) for the catalog. ## [](#prerequisites)Prerequisites - An MCP server reachable from the Agentic Data Plane. - The endpoint URL. `http://` is allowed for everything except user-delegated OAuth, which requires `https://` (proto rule `remote_mcp.user_oauth_requires_https`). - Knowledge of which transport the server speaks (SSE or Streamable HTTP). If you don’t know, see [Transport choice](#test-transport). - If using static-key or service-account-OAuth: secrets pre-created in the Redpanda Agentic Data Plane secret store, `UPPER_SNAKE_CASE` (proto regex `^[A-Z][A-Z0-9_]*$`). - If using user-delegated OAuth with automatic setup: nothing, when the server supports dynamic client registration. If it doesn’t, register an OAuth app with the upstream vendor and have its client ID ready, plus a client-secret reference in the secret store for a confidential app. - If attaching an OAuth provider your organization already manages instead: the provider registered first. See [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). ## [](#create-the-server)Create the server 1. Open **MCP Servers** in the sidebar and click **Create Server**. 2. In the marketplace picker, choose **Remote (Proxied)**. 3. Fill in the identity fields (`name`, `description`, `enabled`); same constraints as in [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/). 4. Provide the `URL` and `Transport`. 5. Configure authentication (see [Authentication](#authentication)). 6. Click **Create**. ## [](#test-transport)Transport choice Two transports are available on the proto enum `MCPTransport`: - **SSE**: Server-sent events. The traditional MCP transport. - **Streamable HTTP**: Newer bidirectional protocol. Pick whichever your server actually speaks. To probe a server quickly: ```bash # SSE handshake: expect a stream of `event:` lines on success. curl -N -H "Accept: text/event-stream" https://your-server.example.com/mcp/sse # Streamable HTTP: expect a JSON-RPC response on success. curl -X POST -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \ https://your-server.example.com/mcp ``` ## [](#authentication)Authentication The authentication modes from [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/#configure-authentication) all apply. Several patterns are particularly common for self-managed servers: | Pattern | Use when | | --- | --- | | Static key with a custom header | First-party servers that authenticate with a non-Authorization header. Provide a header_name (for example, X-Api-Key) and a key_ref pointing at a UPPER_SNAKE_CASE secret. | | Service-account OAuth | The upstream system supports OAuth client credentials and you want one shared identity for all callers. Provide client_id, client_secret_ref, token_url, and any required scopes. | | Token passthrough | The upstream server already validates client tokens; Redpanda just forwards the caller’s Authorization header. | For user-delegated OAuth, the URL must be `https://`. Redpanda can set up OAuth automatically for the server, or you can attach an OAuth provider you already registered. See [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/). ## [](#tool-discovery)Tool discovery After create, Redpanda runs a live `tools/list` (the `ListMCPServerTools` RPC) against the server. The result is cached on the `MCPServer.tools` output-only field and shown on the detail page’s **Overview** tab. The **Inspector** tab (see [Test a server’s tools](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/)) exercises individual [tools](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#tool). If the tools list is empty or stale, open the **Inspector** tab and click **Refresh** to re-run discovery against the server. ## [](#connection-errors-and-retry)Connection errors and retry | Error | What it means | | --- | --- | | OAuthConnectionRequired | The user-delegated auth path needs a stored token vault entry for the calling user. Redpanda surfaces an authorize_url so the user can complete the consent flow. See User-delegated OAuth. | | OAuthTokenExpired | The user’s stored token has expired and refresh failed. Surface the new authorize URL and have the user re-consent. | | Plain connection error / 502 / 504 | Redpanda couldn’t reach your server. Look at the Connection tab on the detail page for the upstream error and check the connection-status banner. | ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | "Transport mismatch" or empty stream | Your server speaks the other transport. Re-probe with curl per Transport choice and update the Transport field on the server’s edit page. | | TLS errors when registering an https:// URL | Confirm the server’s certificate chains to a public CA (or the CA Redpanda’s egress trusts). Self-signed certs aren’t supported. | | 401 Unauthorized from the upstream | Authentication is misconfigured. For static-key or service-account-OAuth, verify the secret content and header_name. For token passthrough, confirm the caller is sending an Authorization header. | | Tool schema parse errors | The server returned a tools/list response with an invalid JSON schema for one or more tool inputs. Fix the upstream tool’s schema and refresh. | ## [](#next-steps)Next steps - [Configure User-Delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Code Mode](https://docs.redpanda.com/agentic-data-plane/gateway/code-mode/) --- # Page 42: Connect Remote MCP Clients **URL**: https://docs.redpanda.com/agentic-data-plane/connect/remote-mcp-clients.md --- # Connect Remote MCP Clients > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Connect Remote MCP Clients latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: remote-mcp-clients page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: remote-mcp-clients.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/remote-mcp-clients.adoc description: Connect external MCP clients to MCP servers in AI Gateway using client metadata documents, dynamic client registration, or manual registration. page-topic-type: how-to personas: agent_builder, platform_engineer, security_compliance_lead learning-objective-1: Choose a client identification method for an external chat app learning-objective-2: Wire a custom connector in Claude Desktop (or another chat client) to your MCP server learning-objective-3: Walk a user through the OAuth flow that runs end-to-end page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-10" --- External MCP clients (Claude Desktop, ChatGPT desktop, Gemini Apps, Cursor) connect to MCP servers hosted in AI Gateway over OAuth. A client can identify itself with a client metadata document, register itself dynamically, or use a client that an administrator registered manually. End-users get the MCP tools inside their preferred chat app, with Redpanda mediating both client-app authentication and upstream-system authentication. After completing this guide, you will be able to: - Choose a client identification method for an external chat app - Wire a custom connector in Claude Desktop (or another chat client) to your MCP server - Walk a user through the OAuth flow that runs end-to-end ![OAuth client onboarding options. Client ID metadata documents let a public client use a metadata URL without a stored registration. Dynamic client registration lets a client create and maintain its own registration in AI Gateway. Manual registration lets an administrator enter redirect URIs and distribute credentials for clients that support neither automated option.](https://docs.redpanda.com/agentic-data-plane/connect/_images/oauth-client-onboarding-options.svg) Figure 1. Choose the lightest client onboarding method the MCP client supports > ❗ **IMPORTANT** > > OAuth clients and OAuth providers govern _opposite directions_ of authentication and are separate resources. > > - An OAuth client (this page) governs _inbound_ authentication: an external chat app (Claude Desktop, ChatGPT, Copilot Studio, Cursor) authenticating to AI Gateway so its users can invoke MCP tools. > > - An OAuth provider governs _outbound_ authentication: AI Gateway authenticating to an upstream system (GitHub, Slack, Salesforce) on a user’s behalf when an MCP server uses user-delegated OAuth. > > > See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) for the outbound authentication side. ## [](#when-to-use-this)When to use this Use a remote MCP client connection when: - You want users to invoke MCP tools from inside Claude Desktop, ChatGPT desktop, Gemini Apps, or Cursor without writing custom integration code. - You already have, or are about to create, an MCP server (managed or self-managed) in AI Gateway. - End-users have accounts with the chat client and the upstream system you’re integrating with. Use a different approach when: - You need programmatic, server-side tool invocation. See [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/) for SDK-based access. - You need an in-house chat UI. Build against the AI Gateway’s MCP endpoints directly with the SDK of your choice. ## [](#architecture-how-the-resources-work-together)Architecture: How the resources work together Wiring a remote chat client to an MCP server uses three resources in AI Gateway: | Resource | Role | | --- | --- | | MCP server | The tool surface itself. Managed (Redpanda hosts it) or self-managed (you host it). See Create an MCP Server. | | OAuth Provider | Defines how AI Gateway authenticates against the upstream system on behalf of users (for example, GitHub) when the MCP server uses user-delegated OAuth. See Configure an OAuth Provider. Optional: only needed if the MCP server requires per-user upstream identity. | | OAuth Client | Defines how an external chat app (Claude Desktop, ChatGPT, Gemini, Cursor) authenticates against AI Gateway on behalf of users. The client can use an HTTPS URL as its client_id, register dynamically, or use credentials from a manual registration. This is what makes the chat-client integration possible. | Putting it together with a GitHub example: - The **MCP server** is a managed GitHub MCP, configured to use user-delegated OAuth. - The **OAuth Provider** points at GitHub’s OAuth endpoints; AI Gateway uses it to act as each user against GitHub. - The **OAuth Client** is registered for Claude Desktop; Claude Desktop uses it to act as each user against AI Gateway. When a user invokes a tool, AI Gateway runs both authentication handshakes: Claude to AI Gateway through the OAuth Client, then AI Gateway to GitHub through the OAuth Provider. ![Two-stage OAuth flow. An external MCP client authenticates inbound to AI Gateway through an OAuth client. AI Gateway invokes the MCP server, then authenticates outbound to the upstream system through an OAuth provider when user-delegated OAuth is configured.](https://docs.redpanda.com/agentic-data-plane/connect/_images/remote-mcp-client-authentication.svg) Figure 2. A remote MCP tool call crosses separate inbound and outbound OAuth boundaries ## [](#prerequisites)Prerequisites Before you wire up the chat-client connector, make sure you have: - An MCP server already created in AI Gateway. See [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/). - The server’s `Server URL`. Copy it from the server’s **Connection** tab. - For user-delegated MCP servers: An OAuth Provider configured for the upstream system. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). - End-users have accounts with the chat client (Claude, ChatGPT, Gemini, Cursor) and the upstream system the MCP server connects to. ## [](#client-metadata-documents)Let clients use metadata documents Client ID metadata documents let a public OAuth client use an HTTPS URL as its `client_id`. The client hosts a JSON metadata document at that URL instead of creating a saved registration on AI Gateway. The document identifies the client and lists its redirect URIs. When the client starts an authorization request, AI Gateway checks that the document names its own URL and includes the requested redirect URI. Clients that use a metadata document run the authorization-code flow with PKCE and do not use a shared client secret. Use metadata documents when the external MCP client supports them and you want clients to connect without an administrator creating or maintaining a registration. A client that uses a metadata document does not create an entry in the **Inbound clients** list. ### [](#enable-client-metadata-documents)Enable client metadata documents 1. Open **Integrations setup** in the sidebar and select the **Inbound clients** tab. 2. Select **Self-registration**. 3. Turn on **Accept client metadata documents (CIMD)**. 4. Under Trusted document domains, choose one of these options: - **Any domain**: Accept a valid metadata document from any HTTPS domain. - **Only these domains**: Accept documents only from the domains you list. A listed parent domain also covers its subdomains. 5. Under Allowed resources, add the exact MCP URLs these clients may access, or allow any MCP server on the gateway. 6. Click **Save settings**. > 📝 **NOTE** > > If the settings report that client metadata documents are not active on the gateway, clients cannot use a URL as their client ID yet. Contact the gateway operator before testing the connection. > ❗ **IMPORTANT** > > The domain policy controls which clients may identify themselves to the gateway. The allowed-resources policy separately controls which MCP servers those clients may request tokens for. Restrict both lists when only approved clients should reach specific MCP servers. If a client does not support metadata documents, use dynamic client registration or create the client manually. ## [](#register-an-oauth-client-in-ai-gateway)Register an OAuth Client in AI Gateway Register a client by hand when it supports neither client metadata documents nor dynamic client registration, when it needs a confidential `client_secret`, or when you want to pre-provision it before the first connection. For supported public clients, you can skip this manual flow. See [Let clients use metadata documents](#client-metadata-documents) or [Let clients self-register](#self-register-with-dcr). Create an OAuth Client to give the chat app the credentials it needs to authenticate against AI Gateway: 1. Open **Integrations setup** in the sidebar and select the **Inbound clients** tab. The tab lists every external tool registered to request access tokens from this gateway, with its `Name`, `Grant Types`, `Status`, and `Scopes`. (The older `/oauth-clients` path still works but redirects here.) 2. Click **Add external tool**. 3. Pick a well-known client to prefill its redirect URIs and recommended scopes, or choose **Custom Client** to register one from scratch. The catalog includes **Claude.ai Custom Connectors**, **Claude Desktop**, **ChatGPT**, **Cursor**, **Windsurf**, **Visual Studio Code** (which also covers GitHub Copilot in VS Code), **Zed**, **Gemini CLI**, and **mcp-remote bridge** (a stdio-to-HTTP bridge for clients without native remote OAuth). For any client not in the catalog (for example, the Gemini consumer apps or Microsoft Copilot Studio), use **Custom Client** and paste the redirect URIs the tool publishes. 4. Fill in the form: | Field | Notes | | --- | --- | | Display name | Human-readable label shown in the UI and on the consent screen, for example Claude.ai Custom Connectors. | | Name | Machine identifier, and the OAuth client_id. Lowercase letters, numbers, and hyphens only. Immutable after creation. | | Logo URI | Optional HTTPS URL for a logo shown on the consent screen. | | Redirect URIs | The exact URIs the gateway redirects to after a user approves. Each chat client publishes its own; a well-known client prefills them. Multiple URIs are allowed. Claude.ai, for example, uses two: https://claude.ai/api/mcp/auth_callback and https://claude.ai/api/organizations/custom-connectors/oauth/callback; Claude Desktop uses http://127.0.0.1:54545/callback. | | Allowed MCP Resources | Which MCP servers this client may request tokens for. Defaults to * (any MCP server hosted on this gateway). Click Restrict to limit the client to specific MCP resource URLs. | | Grant Types | Authorization Code (RFC 6749 §4.1) and Refresh Token (RFC 6749 §6, rotating single-use). This is the standard combination for browser-based chat clients with long-lived tokens. | | Token Endpoint Auth Method | How the client authenticates to the token endpoint: Client Secret (Basic) (default), Client Secret (POST), or None (PKCE only) for public clients that can’t store a secret. | | Require PKCE | Strongly recommended and enforced by default (RFC 7636). Adds an extra layer of security to the consent flow. | | Enabled | Whether the client can start new consent flows. Disabled clients reject new flows. | 5. Click **Register Client**. On submit, AI Gateway mints the `client_id`. Confidential clients (those using a Client Secret authentication method) also receive a `client_secret`, **shown only once**. Copy it immediately. The OAuth Server Endpoints panel shows the `Authorization Endpoint` and `Token/Refresh Endpoint` (under `/oauth/idp/`) and the `mcp` scope; paste these into the external app’s OAuth configuration. ## [](#self-register-with-dcr)Let clients self-register For clients that do not support metadata documents, you can let spec-conformant MCP clients register themselves. AI Gateway supports the OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591), but dynamic registration is off for each organization by default. After you enable it, the gateway advertises a `registration_endpoint` in its authorization-server metadata at `/.well-known/oauth-authorization-server`. Clients that read this metadata (Claude Code, Cursor, ChatGPT, and other spec-conformant MCP clients) register on their first connection attempt, run the authorization-code flow with PKCE, and obtain tokens without an admin provisioning a `client_id` or `client_secret` first. Enable self-registration before conformant clients can register. ### [](#enable-self-registration)Enable self-registration Run the `rpk ai oauth-client dcr update` command to enable self-registration and choose how callers are admitted: ```bash rpk ai oauth-client dcr update --enabled --admission-mode open ``` > 💡 **TIP** > > You can also review and change self-registration from the UI: on the **Integrations setup** page, open the **Inbound clients** tab and select **Self-registration** to open its settings. Inspect the current policy at any time: ```bash rpk ai oauth-client dcr get ``` The command reports whether self-registration is enabled, the admission mode, and the resource and rate caps, for example `ENABLED: true`, `ADMISSION_MODE: OPEN`, `ALLOWED_RESOURCES: ["*"]`. ### [](#admission-modes)Admission modes The admission mode controls who may register after you enable self-registration: | Mode | Behavior | | --- | --- | | open | Any spec-conformant client registers without credentials. Use this for clients that register anonymously, such as Claude Code. The registration rate limit and client cap still apply. | | initial-access-token | Callers must present an admin-minted, one-shot bearer token (an Initial Access Token) on the registration request. Use this to keep self-registration open only to holders of a token you hand out. | The `software-statement` admission mode is reserved and not yet supported. ### [](#restrict-and-rate-limit-self-registration)Restrict and rate-limit self-registration Pass caps to the same `rpk ai oauth-client dcr update` command to bound what self-registered clients can do: | Flag | Purpose | | --- | --- | | --allowed-resource | MCP server URL that every self-registered client may request tokens for. Repeatable. * allows any MCP server on the gateway. | | --client-cap | Maximum number of concurrent self-registered clients. | | --rate-per-hour | Maximum registrations accepted per hour. | | --inactive-ttl-days | Days of inactivity before AI Gateway removes a self-registered client. 0 keeps clients indefinitely. | AI Gateway disables and then removes inactive self-registered clients according to this policy, so abandoned registrations don’t accumulate. ### [](#mint-initial-access-tokens)Mint initial access tokens In `initial-access-token` mode, mint a one-shot token and give it to the client operator, who presents it on the registration request: ```bash rpk ai oauth-client dcr iat mint --label "Claude handoff" --ttl 24h ``` The token’s plaintext appears only once, on mint, and is consumed on the first successful registration. List and revoke tokens with: ```bash rpk ai oauth-client dcr iat list rpk ai oauth-client dcr iat revoke ``` Replace `` with the ID from the IAT list. ### [](#review-self-registered-clients)Review self-registered clients Self-registered clients appear alongside manually registered ones in the `rpk ai oauth-client list` output and on the **Inbound clients** tab, marked with a DCR badge and a name of the form `dcr-`. They authenticate with PKCE and no client secret. Audit them like any other client, and delete one to revoke its tokens: ```bash rpk ai oauth-client list rpk ai oauth-client delete ``` Replace `` with the `dcr-` name from the list. ## [](#wire-up-claude)Wire up Claude Anthropic supports custom MCP connectors in Claude.ai (web), Claude Desktop, and the Claude organization-settings UI. The setup flow is the same in each: 1. Open **Settings > Connectors** (or **Customize > Connectors** in newer builds; Anthropic surfaces a _Connectors have moved to Customize_ notice during the migration). 2. Click **Add custom connector**. 3. Fill in the connector details: | Field | Value | | --- | --- | | Name | Anything that helps the user identify the connector (for example, Redpanda GitHub). Surfaces in Claude’s tool list. | | Remote MCP server URL | The server’s Server URL from AI Gateway. Format: https://aigw..clusters.rdpa.co/mcp/v1/. | | OAuth client ID (optional, under Advanced settings) | The Client ID from the AI Gateway OAuth Client. Required for any MCP server that requires authentication. Leave blank only for public MCP servers that don’t require authentication. | | OAuth client secret (under Advanced settings) | The Client Secret from the AI Gateway OAuth Client. Required whenever Client ID is set. | 4. Click **Add**. The connector appears in the Connectors list with a `CUSTOM` badge. 5. Click **Connect** on the new connector row. Claude opens a browser tab pointed at AI Gateway’s authorization endpoint. Sign in with your AI Gateway identity provider. After approval, the connector becomes invokable in any conversation. > 📝 **NOTE** > > Anthropic’s modal warns that connectors are user-trust-based; Anthropic doesn’t control which tools developers expose. If you’re publishing a connector for end-users, document the upstream system and scopes clearly so users know what they’re authorizing. ## [](#wire-up-other-chat-clients)Wire up other chat clients The flow mirrors Claude Desktop. **ChatGPT**, **Cursor**, **Windsurf**, **Visual Studio Code**, **Zed**, **Gemini CLI**, and **mcp-remote bridge** have catalog presets in the **Add external tool** flow that prefill their redirect URIs; the others use a **Custom Client**. The exact menu paths and field labels differ by client: - **ChatGPT desktop**: Recent builds support remote MCP custom connectors. Confirm the latest menu path; OpenAI iterates on this surface. - **Cursor**: Supports remote MCP servers in recent builds. - **Windsurf**: Supports remote MCP servers in recent builds. - **Visual Studio Code**: Built-in MCP support, shared with GitHub Copilot in VS Code. Has a catalog preset. - **Zed**: Supports remote MCP server OAuth. Has a catalog preset. - **Gemini CLI**: Supports MCP server OAuth. Has a catalog preset. This is the command-line tool, distinct from the consumer Gemini apps, which use a **Custom Client**. - **mcp-remote bridge**: For stdio-only MCP clients bridged through `npx mcp-remote `. Has a catalog preset. - **Gemini apps**: Recent builds support remote MCP custom connectors. Register through **Custom Client**. - **Microsoft Copilot Studio**: Recent builds support remote MCP custom connectors registered against an external OAuth 2.0 authorization server. Register through **Custom Client**, and add Copilot Studio’s published redirect URIs to the AI Gateway OAuth Client before connecting. The required inputs are the same as Claude Desktop: connector name, MCP URL, Client ID, Client Secret. The chat client’s redirect URIs must be registered on the AI Gateway OAuth Client. ## [](#the-oauth-flow)The OAuth flow When a user calls a tool that needs upstream access, two OAuth handshakes run end-to-end. Most users only see the second one (and only on the very first tool call). ### [](#chat-client-connects-to-ai-gateway)Chat client connects to AI Gateway This handshake runs **once per user** when the connector is first added. 1. The user clicks **Connect** in the chat client. 2. The chat client opens a browser tab at the AI Gateway authorization endpoint, parameterized with the OAuth Client’s `client_id` and one of the registered redirect URIs. 3. AI Gateway authenticates the user against the configured IdP (Auth0 today, Zitadel later) and presents an Authorize access consent screen. The screen shows: - The OAuth Client’s name (for example, _Claude (GitHub Read demo) wants to access your data_). - The **Resource** being authorized: The MCP server name and URL. - The **Requested permissions**: The gateway’s internal scopes for this handshake (`mcp` and `offline_access`). These are **not** the upstream system’s scopes; the upstream’s scopes appear during the next handshake. - A footer reminding the user that they can revoke this access at any time in their Redpanda dashboard. 4. The user clicks **Allow**. AI Gateway redirects the chat client back to the redirect URI with an authorization code. 5. The chat client exchanges the code for an access token and a refresh token, and stores them locally in its credential store. 6. Subsequent calls to AI Gateway send the access token in `Authorization: Bearer …​`. The chat client refreshes the token automatically when it expires. ### [](#ai-gateway-connects-to-the-upstream-system)AI Gateway connects to the upstream system (Only for user-delegated MCP servers.) This handshake runs **once per user, per upstream**. For an MCP server using user-delegated OAuth (GitHub, Slack, Atlassian, Workday, and so on): 1. The user invokes a tool that requires upstream authentication. 2. AI Gateway has no stored upstream token for this user yet. The MCP protocol returns a `FAILED_PRECONDITION` response with an `OAuthConnectionRequired` error detail. The detail carries an `authorize_url` pointing at AI Gateway’s OAuth bridge for the configured upstream provider, for example: `https://aigw..clusters.rdpa.co/oauth/v1/authorize?provider_name=github&scopes=read:user,repo`. 3. The chat client renders the link in its response to the user. Inside Claude this appears as a hyperlinked URL with prose telling the user to authorize the upstream connection (for example, _Authorize the GitHub connection first_) before retrying. 4. The user clicks the link. AI Gateway redirects them to the **upstream system’s own OAuth consent page** (for example, GitHub’s standard authorization UI) listing the requested repositories and scopes. 5. The user clicks **Authorize** on the upstream’s consent page. The upstream redirects back to AI Gateway with an authorization code. AI Gateway exchanges the code for a token and stores it in its token vault under the user’s identity. 6. The user tells the chat client they’ve connected. The chat client retries the original tool call, which now succeeds. Subsequent calls reuse the stored upstream token automatically. After both steps complete, the user can invoke any tool on the MCP server transparently. They re-consent only if scopes change or the refresh tokens expire. > 📝 **NOTE** > > Claude (and other chat clients) layer their own **per-tool consent prompts** on top of the OAuth flow described here. The first time a connector tries to invoke a specific tool, Claude shows a prompt of the form _Claude wants to use {tool\_name} from {connector\_name}_ with **Always allow** / **Deny** buttons. This is the chat client’s own user-trust UX, not an additional AI Gateway authentication step. After a user picks **Always allow** for a tool, Claude won’t prompt again for that tool from that connector. > 📝 **NOTE** > > If the MCP server uses a service-account authentication mode instead of user-delegated OAuth, only Step 1 runs. AI Gateway calls the upstream with one shared identity and the user never sees the upstream consent flow. ## [](#manage-and-rotate)Manage and rotate Maintain registered OAuth Clients without re-creating them: - **List registered clients**: Open **Integrations setup** in the sidebar and select the **Inbound clients** tab. Each row shows the Name, Grant Types, Status, and Scopes. - **Edit a client**: Change the display name, logo URI, redirect URIs, allowed MCP resources, grant types, or token endpoint authentication method. The `client_id` is immutable; delete and recreate the client if you need a new one. - **Reissue the secret**: The Client Secret is shown only once at creation and can’t be regenerated in place. To issue a new secret, delete and recreate the client, then update every chat client that used it. - **Revoke all tokens**: Invalidate every refresh token AI Gateway has issued under this client without deleting the client itself (see [Revoke all tokens](#revoke-all-tokens)). - **Delete a client**: Invalidates every active token issued under it. Token revocation runs automatically as part of delete, so users connected through this client are signed out immediately. Every chat-client connector that depends on this OAuth Client breaks until reconfigured against a replacement. ### [](#revoke-all-tokens)Revoke all tokens Revoking all tokens invalidates every refresh token AI Gateway has issued under an OAuth Client. Use it when you need to force every connected user to sign in again, for example, after a leaked Client Secret, an offboarding event, or a policy change that warrants re-consent. Revoke from the UI: 1. Open **Integrations setup** in the sidebar, select the **Inbound clients** tab, and click the client whose tokens you want to revoke. 2. On the client detail page, click **Revoke all tokens**. 3. Confirm the action. Revoke from the CLI: ```bash rpk ai oauth-client revoke-tokens ``` The command prints the number of tokens it revoked, for example `Revoked 12 tokens for OAuth client claude-desktop`. The action is idempotent: a second invocation returns `Revoked 0 tokens for OAuth client claude-desktop` and exits 0. > 📝 **NOTE** > > Already-issued **short-lived access tokens** may continue to work until their natural expiry, typically a few minutes. The revocation invalidates **refresh tokens**, so after the access token expires, the chat client cannot mint a new one and the user is forced to re-authenticate. When AI Gateway auto-revokes tokens (on Client deletion or on lifecycle events that imply a hard cut), the same flow runs server-side without the explicit CLI or button click. Deletion revokes tokens at both levels. Deleting an OAuth client revokes that client’s refresh tokens. Deleting an upstream OAuth provider revokes every active token issued for that provider across all users before it removes the provider config. ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | Couldn’t connect to MCP server or connector setup fails immediately | The MCP URL is wrong, or the Client ID + Client Secret don’t match an OAuth Client. Confirm the Server URL on the MCP server’s Connection tab and the credentials on the OAuth Client’s detail page. | | redirect_uri_mismatch during the connect flow | The chat client’s callback URL isn’t registered on the OAuth Client. Add the URL the chat client publishes (Claude Desktop has two; check Claude’s docs for the current set). | | Connector authorized but no tools appear | The MCP server has zero tools, or tools/list failed at connection time. Open the server in the Inspector to confirm tools are discovered. See Test a server’s tools. | | Tool call returns an authorize link to the user | First call from a user with no stored upstream token. The user follows the link, completes upstream consent, and the call retries automatically (Step 2 of the flow above). | | scope_upgrade_required from a tool call | The MCP server’s required_scopes was extended after the user consented at the upstream. The user re-consents at the upstream with the higher scope. | | 401 Unauthorized from every call after working previously | The chat client’s access token expired and the refresh token also expired (or the OAuth Client secret was rotated). Disconnect the connector and re-add it to mint fresh tokens. | ## [](#limitations)Limitations This page does not cover: - **Custom desktop or mobile UIs**: Build against the AI Gateway MCP endpoints directly using your platform’s HTTP client; you don’t need an OAuth Client unless you want the same external-app flow. - **Agent-to-agent calls (A2A)**: See the Agents docs; remote MCP clients are end-user-facing. - **MCP server authoring**: See [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) for the server side. ## [](#next-steps)Next steps - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) --- # Page 43: Set Up a Self-Managed Agent **URL**: https://docs.redpanda.com/agentic-data-plane/connect/self-managed-agents.md --- # Set Up a Self-Managed Agent > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Set Up a Self-Managed Agent latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: self-managed-agents page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: self-managed-agents.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/self-managed-agents.adoc description: Register a self-managed agent, issue it a client credential, and route its LLM and tool calls through the AI Gateway so spend, traces, and transcripts attribute back to the agent. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Choose a self-managed agent over a managed agent for your use case learning-objective-2: Register a self-managed agent and issue it an OAuth client credential learning-objective-3: Route an agent's LLM and MCP calls through the AI Gateway and group them into transcripts page-git-created-date: "2026-06-17" page-git-modified-date: "2026-08-10" --- A self-managed agent is an agent you build and run yourself, registered with Redpanda Agentic Data Plane as an identity. You keep your runtime, framework, and hosting; Agentic Data Plane gives the agent a service account and a client credential, and the [AI Gateway](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#ai-gateway) becomes the agent’s LLM and MCP endpoint. Because every model call and tool call flows through the gateway, Agentic Data Plane attributes spend, tokens, latency, and traces back to the agent and reconstructs each session as a transcript. Agentic Data Plane does not host or run your agent. After reading this page, you will be able to: - Choose a self-managed agent over a managed agent for your use case - Register a self-managed agent and issue it an OAuth client credential - Route an agent’s LLM and MCP calls through the AI Gateway and group them into transcripts ## [](#self-managed-compared-to-managed-agents)Self-managed compared to managed agents The two agent types differ in who runs the agent and how it is defined. They coexist in the same registry, the same governance views, and the same cost-attribution queries. | Question | Self-managed | Managed | | --- | --- | --- | | Who runs the agent? | You do. Agentic Data Plane registers the agent and proxies its LLM and tool calls, but the runtime is yours. | Redpanda deploys, runs, and observes the agent for you. | | How is the agent defined? | It is already coded in your own framework, for example, LangChain, CrewAI, or a custom runtime. | You configure it declaratively through the create form, with no runtime code to maintain. | | What connects it to Agentic Data Plane? | A client credential the agent exchanges for a gateway token. Your code points its LLM and MCP clients at the gateway. | The managed runtime wires the gateway for you. | For the declarative path, see [Create an agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/). ## [](#prerequisites)Prerequisites - Access to create an agent, from an [access policy](https://docs.redpanda.com/agentic-data-plane/control/access-policies/) granting `Action::"Agent.create"`, or from the Admin role. See [Agent management permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#agent-management-permissions). - At least one [LLM provider configured](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/) in Agentic Data Plane. The agent calls the model through this provider. - If the agent calls tools: One or more [MCP servers](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) registered in Agentic Data Plane. - An agent built in your own framework. The **Setup** tab generates ready-to-paste samples for ai-sdk-go, LangChain, CrewAI, ADK Java, ADK Go, ADK Python, Vercel AI SDK, and Mastra. ## [](#register-the-agent)Register the agent 1. Open **Agents** in the sidebar. 2. Click **Create agent**. 3. Click **I host it myself**, so Agentic Data Plane registers the agent as an identity and leaves the runtime to you. ![The runtime choice in the create-agent flow, with a Redpanda manages it card for the managed runtime and an I host it myself card for self-managed agents](https://docs.redpanda.com/agentic-data-plane/shared/_images/create-agent-runtime-choice.png) 4. Fill in the identity fields on the **Register self-managed agent** canvas, then click **Create agent**: - **Name**: Required. Human-readable name shown in the agent list and detail header. Agentic Data Plane derives the agent’s resource ID from this name when you register the agent; you don’t enter the ID directly. The derived ID is used in URLs, in cost-attribution queries, and as the agent’s resource identifier, and it can’t be changed after creation. - **Description**: Optional. Up to 1024 characters. An internal note shown on the agent’s detail page. - **Tags**: Optional key/value pairs to organize and filter agents. Expand the **Advanced** area to add them. The agent opens on its detail page with a **Self-managed** type badge. A self-managed agent carries no provider, model, or tool configuration of its own: it is an identity that calls the organization’s shared gateway resources. ## [](#issue-a-client-secret)Issue a client secret Agentic Data Plane provisions a service account for the agent at registration. To authenticate the agent’s calls, issue an OAuth 2.0 client secret on the agent’s **Credentials** tab. 1. Open the agent’s **Credentials** tab. ![The Credentials tab for a self-managed agent, showing the service account Client ID, the authorized scope, and an empty client-secrets list with a Create secret button](https://docs.redpanda.com/agentic-data-plane/connect/_images/self-managed-agent-credentials.png) 2. Note the **Client ID**. It has the form `serviceaccounts/`, where `` is the agent’s identifier. The Client ID is public and stable: every secret on the agent shares it. 3. Click **Create secret**. 4. Optionally enter a **Name** to identify the secret in the list and in audit logs, for example, `production`. If you leave it blank, Agentic Data Plane assigns a default name such as `secret-1`. 5. Click **Generate secret**. Agentic Data Plane shows the plaintext **Client secret** one time. ![The Secret created dialog showing a masked client secret, a Copy secret button, and a warning that the plaintext is shown only at creation](https://docs.redpanda.com/agentic-data-plane/connect/_images/self-managed-agent-secret-created.png) 6. Copy the secret into your secret manager or container environment variables, then click **I’ve saved it**. > ❗ **IMPORTANT** > > The client secret is shown only at creation. Agentic Data Plane stores a hash and cannot show the plaintext again. Each secret expires 90 days after creation. To rotate without downtime, create a new secret, deploy it, and then revoke the old one with **Revoke** on its row in the secrets list. ## [](#connect-your-agent-to-the-ai-gateway)Connect your agent to the AI Gateway The agent’s **Setup** tab generates everything your code needs: the gateway endpoints, an environment-variable block, and a copy-paste SDK sample for your framework. Open the **Setup** tab, then complete the integration parts shown there. ![The Setup tab listing the integration flow for a self-managed agent: route LLM calls through the gateway, grant MCP access, configure MCP servers in code, and stamp the conversation ID](https://docs.redpanda.com/agentic-data-plane/connect/_images/self-managed-agent-setup-steps.png) On the **Setup** tab, select your **LLM provider**. Optionally, select the **MCP servers** the sample connects through. Your selection fills in the **Environment variables** block without changing the agent. ![The Setup tab Environment variables block, with exported values for the client ID, token URL, LLM provider URL, and MCP base URL](https://docs.redpanda.com/agentic-data-plane/connect/_images/self-managed-agent-setup-env.png) In the endpoint URLs below, `` is your cluster’s identifier and `` is `https://aigw..clusters.rdpa.co`. Copy the exact values from the **Setup** tab. ### [](#authenticate-with-the-client-credential)Authenticate with the client credential The gateway runs its own OAuth 2.0 identity provider. Exchange the Client ID and client secret for a short-lived access token with the `client_credentials` grant against the token endpoint: ```text /oauth/idp/token ``` Send the resulting token as an `Authorization: Bearer` header on every LLM and MCP request. The gateway authenticates on this token and injects the real upstream provider key itself, so your SDK’s own API-key field is a placeholder. Your client is responsible for refreshing the token before it expires. ### [](#route-llm-calls-through-the-gateway)Route LLM calls through the gateway Point your SDK’s base URL at the provider’s gateway endpoint instead of the upstream API: ```text /llm/v1/providers/ ``` In this URL, `` is the name of an LLM provider you configured in Agentic Data Plane. The gateway forwards each provider’s native API to the upstream, so you keep using the provider’s own SDK. The provider enforces a model allow-list: pick a model the provider serves, or the gateway rejects the call. For the full proxy contract and per-SDK setup, see [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/). ### [](#route-mcp-tool-calls-through-the-gateway)Route MCP tool calls through the gateway Point your MCP client at each server’s gateway URL, with the same bearer token: ```text /mcp/v1/ ``` In this URL, `` is the name of an MCP server registered in Agentic Data Plane. Routing tool calls through the gateway keeps them under the same identity, governance, and observability as the model calls. ### [](#group-calls-into-transcripts)Group calls into transcripts Stamp every request, both the model call and each tool call, with the `X-Redpanda-Genai-Conversation` header set to your framework’s own session identifier, for example, a chat-thread ID or a request ID. The gateway groups that session’s calls into one transcript on the agent’s **Transcripts** tab. This header is required for transcripts. Without it, the gateway drops the spans and the **Transcripts** tab stays empty. The header does not affect authentication or whether calls succeed. Each distinct header value becomes one conversation on the **Transcripts** tab, grouping every model call and tool call that carry it into one row. The **Turns** column counts the model calls in that conversation, so an agent that loops over several tool calls shows more than one. ![The Transcripts tab listing conversations, each grouped under one conversation ID, with columns for when it started, its duration, the number of turns, the status, and the token count](https://docs.redpanda.com/agentic-data-plane/connect/_images/self-managed-agent-transcripts.png) ## [](#framework-samples)Framework samples The **Setup** tab generates a ready-to-paste sample for your framework, prefilled with your selected provider and MCP servers. Each sample performs these steps the framework’s way: it runs the `client_credentials` grant, routes the LLM client and every MCP client through one HTTP client that carries the bearer token, and stamps the framework’s own session identifier as the `X-Redpanda-Genai-Conversation` header. The samples read their configuration from these environment variables: | Variable | Where to get it | | --- | --- | | REDPANDA_CLIENT_ID | The Client ID from the Credentials tab. | | REDPANDA_CLIENT_SECRET | A client secret you minted on the Credentials tab. | | REDPANDA_TOKEN_URL | The token endpoint from the Setup tab, ending in /oauth/idp/token. | | REDPANDA_LLM_PROVIDER_URL | The provider-scoped LLM endpoint from the Setup tab, ending in /llm/v1/providers/. | | REDPANDA_LLM_PROVIDER_TYPE | The upstream provider family the SDK builds against: openai, anthropic, or google. | | REDPANDA_LLM_MODEL | A model the provider serves. | | REDPANDA_MCP_BASE_URL | The MCP base endpoint from the Setup tab, ending in /mcp/v1. | | REDPANDA_MCP_SERVERS | A comma-separated list of MCP server names to connect, or empty for none. | Set these variables, then run the sample for your framework. ### ai-sdk-go ```go package main import ( "context" "crypto/rand" "encoding/hex" "fmt" "log" "net/http" "os" "strings" "time" "golang.org/x/oauth2" "golang.org/x/oauth2/clientcredentials" "github.com/redpanda-data/ai-sdk-go/agent" "github.com/redpanda-data/ai-sdk-go/agent/llmagent" "github.com/redpanda-data/ai-sdk-go/llm" "github.com/redpanda-data/ai-sdk-go/providers/anthropic" "github.com/redpanda-data/ai-sdk-go/providers/google" "github.com/redpanda-data/ai-sdk-go/providers/openai" "github.com/redpanda-data/ai-sdk-go/runner" "github.com/redpanda-data/ai-sdk-go/store/session" "github.com/redpanda-data/ai-sdk-go/tool" "github.com/redpanda-data/ai-sdk-go/tool/mcp" ) // convoKey carries the conversation id on the context. type convoKey struct{} // convoTransport stamps the session id (read from the context) as the // conversation header. It sits beneath the oauth2 transport, so one http.Client // carries the bearer AND the conversation id on the LLM call and every MCP tool // call. type convoTransport struct{ base http.RoundTripper } func (t *convoTransport) RoundTrip(r *http.Request) (*http.Response, error) { if id, ok := r.Context().Value(convoKey{}).(string); ok && id != "" { r = r.Clone(r.Context()) r.Header.Set("X-Redpanda-Genai-Conversation", id) } return t.base.RoundTrip(r) } func main() { ctx := context.Background() // OAuth2 client_credentials: x/oauth2 fetches and refreshes the bearer and // its Transport sets it on every request; convoTransport underneath adds the // conversation header. One client instruments the LLM call and every MCP call. cc := clientcredentials.Config{ ClientID: mustEnv("REDPANDA_CLIENT_ID"), ClientSecret: mustEnv("REDPANDA_CLIENT_SECRET"), TokenURL: mustEnv("REDPANDA_TOKEN_URL"), } hc := &http.Client{Transport: &oauth2.Transport{ Source: cc.TokenSource(ctx), Base: &convoTransport{base: http.DefaultTransport}, }} model, err := buildModel(ctx, hc) if err != nil { log.Fatal(err) } // MCP tools ride the SAME client. Each client syncs its server's tools into a // shared registry; Start connects and performs that initial sync. The agent // is then built from the registry, so the model can actually call the tools. registry := tool.NewRegistry(tool.RegistryConfig{}) mcpBase := mustEnv("REDPANDA_MCP_BASE_URL") for _, name := range mcpServers() { factory := mcp.NewStreamableTransport(mcpBase+"/"+name, mcp.WithHTTPClient(hc)) client, err := mcp.NewClient(name, factory, mcp.WithRegistry(registry), // sync this server's tools into the registry mcp.WithToolTimeout(time.Minute)) if err != nil { log.Fatal(err) } if err := client.Start(ctx); err != nil { log.Fatal(err) } defer client.Close() } // WithTools(registry) is what hands the synced MCP tools to the model. ag, err := llmagent.New("assistant", "You are a helpful agent.", model, llmagent.WithTools(registry)) if err != nil { log.Fatal(err) } run, err := runner.New(ag, session.NewInMemoryStore()) if err != nil { log.Fatal(err) } // The runner takes a CALLER-owned conversation id (run.Run keys the session on // it; ai-sdk-go does not mint one). Use your app's own id - a chat thread id, // request id, A2A contextId - reused across the turn; we mint one here. It is // the value convoTransport stamps as X-Redpanda-Genai-Conversation on the model // call and every MCP tool call. const prompt = "What tools can you call?" conversationID := newConversationID() ctx = context.WithValue(ctx, convoKey{}, conversationID) fmt.Printf("> %s\n\n", prompt) msg := llm.NewMessage(llm.RoleUser, llm.NewTextPart(prompt)) for ev, err := range run.Run(ctx, "user-123", conversationID, msg) { if err != nil { log.Fatal(err) } // MessageEvent carries a finished assistant turn (an agentic run may have // several). Print its text so you can see the model actually replied. if m, ok := ev.(agent.MessageEvent); ok { fmt.Println(m.Response.TextContent()) } } } // buildModel constructs the native ai-sdk-go model for the configured provider. // REDPANDA_LLM_PROVIDER_TYPE selects the SDK: "anthropic" and "google" use their // native wire (the gateway forwards /v1/messages and /v1beta/...:generateContent // to the upstream), everything else uses OpenAI chat-completions. All three point // at the same provider-scoped REDPANDA_LLM_PROVIDER_URL. The bearer (set by the // oauth2 transport) is the real auth; the key arg only satisfies the constructor // (the gateway ignores the native x-api-key/x-goog-api-key). func buildModel(ctx context.Context, hc *http.Client) (llm.Model, error) { base := mustEnv("REDPANDA_LLM_PROVIDER_URL") model := mustEnv("REDPANDA_LLM_MODEL") const key = "redpanda-gateway" switch strings.ToLower(os.Getenv("REDPANDA_LLM_PROVIDER_TYPE")) { case "anthropic": p, err := anthropic.NewProvider(key, anthropic.WithBaseURL(base), anthropic.WithHTTPClient(hc)) if err != nil { return nil, err } return p.NewModel(model) case "google", "gemini": p, err := google.NewProvider(ctx, key, google.WithBaseURL(base), google.WithHTTPClient(hc)) if err != nil { return nil, err } return p.NewModel(model) default: // openai (and openai-compatible) p, err := openai.NewProvider(key, openai.WithBaseURL(base), openai.WithHTTPClient(hc)) if err != nil { return nil, err } return p.NewModel(model) } } // mustEnv reads a required env var, exiting with a clear message (not an opaque // downstream panic) when it is unset. Export the values from the Setup tab. func mustEnv(k string) string { v := os.Getenv(k) if v == "" { log.Fatalf("missing env var %s - export it from the Setup tab", k) } return v } // newConversationID mints a fresh conversation id. In a real app, use your own // per-conversation id (chat thread id, request id, A2A contextId) reused across // the turn, not a value generated per call. func newConversationID() string { b := make([]byte, 8) _, _ = rand.Read(b) return "conv-" + hex.EncodeToString(b) } // mcpServers reads the comma-separated REDPANDA_MCP_SERVERS list. Empty is fine // - the agent then runs with no MCP tools. func mcpServers() []string { var out []string for _, p := range strings.Split(os.Getenv("REDPANDA_MCP_SERVERS"), ",") { if p = strings.TrimSpace(p); p != "" { out = append(out, p) } } return out } ``` ### LangChain ```python import asyncio import contextvars import os import httpx from langchain_mcp_adapters.client import MultiServerMCPClient from langgraph.prebuilt import create_react_agent def env(k: str) -> str: """Read a required env var, failing with a clear message (not an opaque KeyError) when it is unset. Export the values from the Setup tab.""" v = os.environ.get(k) if not v: raise SystemExit(f"missing env var {k} - export it from the Setup tab") return v def get_access_token() -> str: """OAuth2 client_credentials grant against the gateway IDP (httpx is already a dep).""" resp = httpx.post( env("REDPANDA_TOKEN_URL"), data={ "grant_type": "client_credentials", "client_id": env("REDPANDA_CLIENT_ID"), "client_secret": env("REDPANDA_CLIENT_SECRET"), }, ) resp.raise_for_status() return resp.json()["access_token"] token = get_access_token() mcp_base = env("REDPANDA_MCP_BASE_URL") # The LangGraph thread_id IS the conversation. Carry it in a contextvar so the # MCP transport reads the current one per request. thread_var: contextvars.ContextVar[str] = contextvars.ContextVar("thread") class GatewayAuth(httpx.Auth): """MCP headers are fixed per connection, so inject per request via httpx.Auth. The default tool mode opens a fresh session per call, so auth_flow re-reads the contextvar and always carries the current thread id. """ def auth_flow(self, request): request.headers["Authorization"] = f"Bearer {token}" request.headers["X-Redpanda-Genai-Conversation"] = thread_var.get() yield request def mcp_servers() -> dict: """Build the MultiServerMCPClient connection map from REDPANDA_MCP_SERVERS.""" servers = {} for name in os.environ.get("REDPANDA_MCP_SERVERS", "").split(","): name = name.strip() if name: servers[name] = { "transport": "streamable_http", "url": f"{mcp_base}/{name}", "auth": GatewayAuth(), } return servers mcp_client = MultiServerMCPClient(mcp_servers()) def build_model(thread_id: str): """Construct the native LangChain chat model for the configured provider. REDPANDA_LLM_PROVIDER_TYPE picks the SDK. Auth is the gateway bearer token, injected on the Authorization header; the SDK's own api_key field is just a non-empty placeholder (the gateway ignores the native x-api-key / x-goog-api-key). The thread id rides along as the conversation header. """ model = env("REDPANDA_LLM_MODEL") base_url = env("REDPANDA_LLM_PROVIDER_URL") headers = { "Authorization": f"Bearer {token}", "X-Redpanda-Genai-Conversation": thread_id, } provider = os.environ.get("REDPANDA_LLM_PROVIDER_TYPE", "openai").lower() if provider == "anthropic": from langchain_anthropic import ChatAnthropic return ChatAnthropic( model=model, base_url=base_url, default_headers=headers, api_key="unused", # gateway authenticates on the bearer header ) if provider in ("google", "gemini"): from langchain_google_genai import ChatGoogleGenerativeAI return ChatGoogleGenerativeAI( model=model, base_url=base_url, api_version="v1beta", # native Gemini wire under the provider URL additional_headers=headers, api_key="unused", # gateway authenticates on the bearer header ) # openai (and openai-compatible) from langchain_openai import ChatOpenAI return ChatOpenAI( model=model, base_url=base_url, api_key=token, ).bind(extra_headers={"X-Redpanda-Genai-Conversation": thread_id}) async def chat(thread_id: str, text: str): thread_var.set(thread_id) # one id per conversation tools = await mcp_client.get_tools() llm = build_model(thread_id) agent = create_react_agent(llm, tools) return await agent.ainvoke( {"messages": [("user", text)]}, config={"configurable": {"thread_id": thread_id}}, ) async def main(): result = await chat("user-123-thread-1", "What tools can you call?") for message in result["messages"]: message.pretty_print() if __name__ == "__main__": asyncio.run(main()) ``` ### CrewAI ```python import os import httpx from crewai import LLM, Agent, Crew, Task from crewai.llms.hooks import BaseInterceptor from crewai_tools import MCPServerAdapter def env(k: str) -> str: """Read a required env var, failing with a clear message (not an opaque KeyError) when it is unset. Export the values from the Setup tab.""" v = os.environ.get(k) if not v: raise SystemExit(f"missing env var {k} - export it from the Setup tab") return v def get_access_token() -> str: """OAuth2 client_credentials grant against the gateway IDP (httpx is already a dep).""" resp = httpx.post( env("REDPANDA_TOKEN_URL"), data={ "grant_type": "client_credentials", "client_id": env("REDPANDA_CLIENT_ID"), "client_secret": env("REDPANDA_CLIENT_SECRET"), }, ) resp.raise_for_status() return resp.json()["access_token"] token = get_access_token() provider_url = env("REDPANDA_LLM_PROVIDER_URL") provider_type = os.environ.get("REDPANDA_LLM_PROVIDER_TYPE", "openai").lower() model = env("REDPANDA_LLM_MODEL") mcp_base = env("REDPANDA_MCP_BASE_URL") # The gateway authenticates on this Bearer token; the native x-api-key / # x-goog-api-key are ignored, so the SDK's api_key is just a placeholder. GATEWAY_API_KEY = "redpanda-gateway" class GatewayInterceptor(BaseInterceptor): """LLM side (OpenAI / Anthropic native clients): stamp the Bearer token and the conversation id on every outbound request via a transport interceptor. The conversation id is carried per instance so one crew.kickoff() groups cleanly. Both the OpenAI and Anthropic native clients build an httpx client around this interceptor; Gemini does not support interceptors and is wired separately (see build_llm). """ def __init__(self, conversation_id: str) -> None: self.conversation_id = conversation_id def on_outbound(self, request: httpx.Request) -> httpx.Request: request.headers["Authorization"] = f"Bearer {token}" request.headers["X-Redpanda-Genai-Conversation"] = self.conversation_id return request def on_inbound(self, response): return response async def aon_outbound(self, request): return self.on_outbound(request) async def aon_inbound(self, response): return response def build_llm(conversation_id: str) -> LLM: """Build the native LLM for REDPANDA_LLM_PROVIDER_TYPE, pointed at the gateway provider URL and carrying the Bearer token + conversation header. """ if provider_type == "anthropic": # Native Anthropic SDK posts to {base_url}/v1/messages. The SDK sends # x-api-key natively; the interceptor adds Authorization: Bearer (which # the gateway authenticates on) plus the conversation header. return LLM( provider="anthropic", model=model, base_url=provider_url, api_key=GATEWAY_API_KEY, interceptor=GatewayInterceptor(conversation_id), ) if provider_type in ("google", "gemini"): # Native google-genai SDK posts to {base_url}/v1beta/models/{model}:generateContent. # It does NOT support transport interceptors, so the Bearer token and the # conversation header are set as fixed client headers via http_options. from google.genai import types return LLM( provider="gemini", model=model, api_key=GATEWAY_API_KEY, client_params={ "http_options": types.HttpOptions( base_url=provider_url, headers={ "Authorization": f"Bearer {token}", "X-Redpanda-Genai-Conversation": conversation_id, }, ), }, ) # openai (and openai-compatible): native OpenAI SDK posts to # {base_url}/chat/completions. The interceptor stamps both headers. return LLM( provider="openai", model=model, base_url=provider_url, api_key=GATEWAY_API_KEY, interceptor=GatewayInterceptor(conversation_id), ) def mcp_server_params(conversation_id: str) -> list: """MCP headers are fixed per connection, so build params per conversation.""" servers = [] for name in os.environ.get("REDPANDA_MCP_SERVERS", "").split(","): name = name.strip() if name: servers.append( { "url": f"{mcp_base}/{name}", "transport": "streamable-http", "headers": { "Authorization": f"Bearer {token}", "X-Redpanda-Genai-Conversation": conversation_id, }, } ) return servers def kickoff(prompt: str, llm: LLM, tools) -> str: agent = Agent(role="Assistant", goal="Help the user", backstory="", llm=llm, tools=tools) crew = Crew( agents=[agent], tasks=[Task(description=prompt, agent=agent, expected_output="A reply")], ) return crew.kickoff() def run_conversation(conversation_id: str, prompt: str) -> str: # One crew.kickoff() == one conversation: build the LLM and MCP clients with # this id so the model call and every tool call carry the same header. llm = build_llm(conversation_id) servers = mcp_server_params(conversation_id) if not servers: return kickoff(prompt, llm, []) with MCPServerAdapter(servers) as tools: return kickoff(prompt, llm, list(tools)) if __name__ == "__main__": print(run_conversation("user-123-conversation-1", "What tools can you call?")) ``` ### ADK Java ```java package com.redpanda.example; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import com.google.adk.agents.LlmAgent; import com.google.adk.models.langchain4j.LangChain4j; import com.google.adk.runner.Runner; import com.google.adk.sessions.InMemorySessionService; import com.google.adk.sessions.Session; import com.google.adk.tools.mcp.McpToolset; import com.google.adk.tools.mcp.StreamableHttpServerParameters; import com.google.genai.types.Content; import com.google.genai.types.Part; import dev.langchain4j.model.anthropic.AnthropicChatModel; import dev.langchain4j.model.chat.ChatModel; import dev.langchain4j.model.googleai.GoogleAiGeminiChatModel; import dev.langchain4j.model.openai.OpenAiChatModel; import java.net.URI; import java.net.URLEncoder; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.util.ArrayList; import java.util.List; import java.util.Locale; import java.util.Map; public final class Main { private Main() {} public static void main(String[] args) throws Exception { String token = accessToken(); String appName = "redpanda-self-managed-agent"; String userId = "user-123"; // ADK owns the session and mints its id - that id IS the conversation, never // a hardcoded constant. langchain4j fixes customHeaders at build time, so we // create the session first (createSession with a null id mints one), then // pass its id to the chat model and the runner. The same id rides the LLM // call and every MCP tool call. One run is one conversation. InMemorySessionService sessions = new InMemorySessionService(); Session session = sessions.createSession(appName, userId).blockingGet(); String sessionId = session.id(); String model = env("REDPANDA_LLM_MODEL"); ChatModel chat = buildChatModel(token, sessionId); // MCP: same bearer + conversation id, fixed per toolset construction. The // agent is built from the toolsets, so the model can call their tools. Map mcpHeaders = Map.of( "Authorization", "Bearer " + token, "X-Redpanda-Genai-Conversation", sessionId); String mcpBase = env("REDPANDA_MCP_BASE_URL"); List tools = new ArrayList<>(); for (String name : mcpServers()) { tools.add( new McpToolset( StreamableHttpServerParameters.builder() .url(mcpBase + "/" + name) .headers(mcpHeaders) .build())); } LlmAgent agent = LlmAgent.builder() .name("assistant") .description("Self-managed agent on the Redpanda AI Gateway.") .instruction("You are a helpful agent.") .model(LangChain4j.builder().chatModel(chat).modelName(model).build()) .tools(tools) .build(); // Build the runner over the SAME session service, so it sees the session we // just minted above. Runner runner = Runner.builder().agent(agent).appName(appName).sessionService(sessions).build(); Content message = Content.fromParts(Part.fromText("What tools can you call?")); runner .runAsync(userId, sessionId, message) .blockingForEach(event -> System.out.println(event.stringifyContent())); } /** * buildChatModel constructs the native langchain4j ChatModel for the configured provider. * *

REDPANDA_LLM_PROVIDER_TYPE selects the wire: "anthropic" speaks /v1/messages and "google" * speaks /v1beta/...:generateContent (the gateway forwards both to the upstream), everything else * speaks OpenAI chat-completions. All three point at the same provider-scoped * REDPANDA_LLM_PROVIDER_URL. * *

Auth is the gateway bearer, sent on the Authorization header via langchain4j's * customHeaders(Map) - fixed at build time, so it also carries the (fixed) conversation id. The * gateway authenticates on that bearer and ignores the native x-api-key/x-goog-api-key, so we * never send a real provider key (OpenAI/Anthropic require a non-empty apiKey, so we pass a dummy * placeholder; Gemini sends no key at all). */ private static ChatModel buildChatModel(String token, String sessionId) { String base = env("REDPANDA_LLM_PROVIDER_URL"); String model = env("REDPANDA_LLM_MODEL"); Map headers = Map.of( "Authorization", "Bearer " + token, "X-Redpanda-Genai-Conversation", sessionId); String type = System.getenv("REDPANDA_LLM_PROVIDER_TYPE"); switch (type == null ? "" : type.toLowerCase(Locale.ROOT)) { case "anthropic": // Native Anthropic Messages API. langchain4j posts to {baseUrl}/messages, so the base URL // carries the version segment: {provider-url}/v1 -> {provider-url}/v1/messages. return AnthropicChatModel.builder() .baseUrl(base + "/v1") .apiKey("redpanda") // dummy; gateway injects the real key and ignores x-api-key .modelName(model) .customHeaders(headers) .build(); case "google": case "gemini": // Native Gemini API. langchain4j posts to {baseUrl}/models/{model}:generateContent, so the // base URL carries the version segment: {provider-url}/v1beta. We do NOT call apiKey(...) - // leaving it null suppresses the x-goog-api-key header; auth rides the Authorization bearer // in customHeaders (requires langchain4j 1.15.0+). return GoogleAiGeminiChatModel.builder() .baseUrl(base + "/v1beta") .modelName(model) .customHeaders(headers) .build(); default: // openai (and openai-compatible) // OpenAI chat-completions. langchain4j posts to {baseUrl}/chat/completions; the provider // URL is the base as-is (the gateway's OpenAI upstream already includes /v1). return OpenAiChatModel.builder() .baseUrl(base) .apiKey("redpanda") // dummy; gateway injects the real key and ignores it .modelName(model) .customHeaders(headers) .build(); } } /** mcpServers reads the comma-separated REDPANDA_MCP_SERVERS list. */ private static List mcpServers() { List out = new ArrayList<>(); String raw = System.getenv("REDPANDA_MCP_SERVERS"); if (raw != null) { for (String name : raw.split(",")) { name = name.trim(); if (!name.isEmpty()) { out.add(name); } } } return out; } /** accessToken runs the OAuth2 client_credentials grant against the gateway IDP. */ private static String accessToken() throws Exception { String form = "grant_type=client_credentials" + "&client_id=" + enc(env("REDPANDA_CLIENT_ID")) + "&client_secret=" + enc(env("REDPANDA_CLIENT_SECRET")); HttpRequest request = HttpRequest.newBuilder(URI.create(env("REDPANDA_TOKEN_URL"))) .header("Content-Type", "application/x-www-form-urlencoded") .POST(HttpRequest.BodyPublishers.ofString(form)) .build(); HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString()); JsonNode node = new ObjectMapper().readTree(response.body()); return node.get("access_token").asText(); } private static String enc(String value) { return URLEncoder.encode(value, StandardCharsets.UTF_8); } /** * env reads a required env var, failing with a clear message (not an opaque downstream NPE) when * it is unset. Export the values from the Setup tab. */ private static String env(String k) { String v = System.getenv(k); if (v == null || v.isEmpty()) { throw new IllegalStateException("missing env var " + k + " - export it from the Setup tab"); } return v; } } ``` ### ADK Go ```go package main import ( "context" "fmt" "log" "net/http" "os" "strings" "golang.org/x/oauth2" "golang.org/x/oauth2/clientcredentials" "github.com/modelcontextprotocol/go-sdk/mcp" "google.golang.org/genai" "google.golang.org/adk/agent" "google.golang.org/adk/agent/llmagent" "google.golang.org/adk/model/gemini" "google.golang.org/adk/runner" "google.golang.org/adk/session" "google.golang.org/adk/tool" "google.golang.org/adk/tool/mcptoolset" ) const appName = "redpanda-self-managed-agent" // convoKey carries the ADK session id on the context. type convoKey struct{} // convoTransport stamps the session id (read from the context) as the // conversation header. It sits beneath the oauth2 transport, so one http.Client // carries the bearer AND the conversation id. ADK threads the ctx you pass to // runner.Run down to both the LLM HTTP call and the MCP tool-call POSTs. type convoTransport struct{ base http.RoundTripper } func (t *convoTransport) RoundTrip(r *http.Request) (*http.Response, error) { if id, ok := r.Context().Value(convoKey{}).(string); ok && id != "" { r = r.Clone(r.Context()) r.Header.Set("X-Redpanda-Genai-Conversation", id) // = ADK session id } return t.base.RoundTrip(r) } func main() { ctx := context.Background() // OAuth2 client_credentials: x/oauth2 fetches and refreshes the bearer and // its Transport sets it on every request; convoTransport underneath adds the // conversation header. One client instruments the LLM call and every MCP call. cc := clientcredentials.Config{ ClientID: mustEnv("REDPANDA_CLIENT_ID"), ClientSecret: mustEnv("REDPANDA_CLIENT_SECRET"), TokenURL: mustEnv("REDPANDA_TOKEN_URL"), } hc := &http.Client{Transport: &oauth2.Transport{ Source: cc.TokenSource(ctx), Base: &convoTransport{base: http.DefaultTransport}, }} // genai refuses to construct the Gemini-API client without a non-empty // APIKey, but the real auth is the bearer the oauth2 transport sets - this // just satisfies the constructor (the gateway ignores the x-goog-api-key). model, err := gemini.NewModel(ctx, mustEnv("REDPANDA_LLM_MODEL"), &genai.ClientConfig{ APIKey: "redpanda-gateway", HTTPClient: hc, HTTPOptions: genai.HTTPOptions{BaseURL: mustEnv("REDPANDA_LLM_PROVIDER_URL")}, }) if err != nil { log.Fatal(err) } // Each MCP server becomes a Toolset over the SAME client; the agent is built // from them via llmagent.Config.Toolsets, so the model can call the tools. mcpBase := mustEnv("REDPANDA_MCP_BASE_URL") var toolsets []tool.Toolset for _, name := range mcpServers() { ts, err := mcptoolset.New(mcptoolset.Config{ Transport: &mcp.StreamableClientTransport{Endpoint: mcpBase + "/" + name, HTTPClient: hc}, }) if err != nil { log.Fatal(err) } toolsets = append(toolsets, ts) } a, err := llmagent.New(llmagent.Config{ Name: "assistant", Model: model, Description: "Self-managed agent on the Redpanda AI Gateway.", Instruction: "You are a helpful agent.", Toolsets: toolsets, }) if err != nil { log.Fatal(err) } sessionService := session.InMemoryService() r, err := runner.New(runner.Config{ AppName: appName, Agent: a, SessionService: sessionService, }) if err != nil { log.Fatal(err) } // ADK owns the session; its id IS the conversation. Create it, put the id on // ctx, and the transport stamps it on the LLM call and every MCP tool call. resp, err := sessionService.Create(ctx, &session.CreateRequest{AppName: appName, UserID: "user-123"}) if err != nil { log.Fatal(err) } sessionID := resp.Session.ID() ctx = context.WithValue(ctx, convoKey{}, sessionID) const prompt = "What tools can you call?" fmt.Printf("> %s\n\n", prompt) msg := genai.NewContentFromText(prompt, genai.RoleUser) for ev, err := range r.Run(ctx, "user-123", sessionID, msg, agent.RunConfig{}) { if err != nil { log.Fatal(err) } if ev.LLMResponse.Content == nil { continue } for _, p := range ev.LLMResponse.Content.Parts { fmt.Print(p.Text) // the assistant's reply, streamed as parts arrive } } fmt.Println() } // mustEnv reads a required env var, exiting with a clear message (not an opaque // downstream panic) when it is unset. Export the values from the Setup tab. func mustEnv(k string) string { v := os.Getenv(k) if v == "" { log.Fatalf("missing env var %s - export it from the Setup tab", k) } return v } // mcpServers reads the comma-separated REDPANDA_MCP_SERVERS list. Empty is fine // - the agent then runs with no MCP tools. func mcpServers() []string { var out []string for _, p := range strings.Split(os.Getenv("REDPANDA_MCP_SERVERS"), ",") { if p = strings.TrimSpace(p); p != "" { out = append(out, p) } } return out } ``` ### ADK Python ```python import asyncio import os import uuid import requests from google.adk.agents import LlmAgent from google.adk.models.lite_llm import LiteLlm from google.adk.runners import InMemoryRunner from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams from google.adk.tools.mcp_tool.mcp_toolset import McpToolset from google.genai import types CONVERSATION_HEADER = "X-Redpanda-Genai-Conversation" APP_NAME = "redpanda-self-managed-agent" USER_ID = "user-123" def env(k: str) -> str: # Required env var, or a clear failure (not an opaque KeyError). Export from the Setup tab. v = os.environ.get(k) if not v: raise SystemExit(f"missing env var {k} - export it from the Setup tab") return v def get_access_token() -> str: # OAuth2 client_credentials grant against the gateway IDP (requests sets the # form content-type automatically when data= is a dict). resp = requests.post( env("REDPANDA_TOKEN_URL"), data={ "grant_type": "client_credentials", "client_id": env("REDPANDA_CLIENT_ID"), "client_secret": env("REDPANDA_CLIENT_SECRET"), }, timeout=30, ) resp.raise_for_status() return resp.json()["access_token"] def model_arg() -> str: # ADK Python drives the gateway through LiteLlm. REDPANDA_LLM_PROVIDER_TYPE # selects the route. Anthropic uses the native Messages wire (LiteLlm appends # /v1/messages to api_base). OpenAI and Google both go through the # OpenAI-compatible /chat/completions route: LiteLlm's gemini/ provider drops # the /v1beta path on a custom api_base, so Google is routed through openai/ too. model = env("REDPANDA_LLM_MODEL") provider = os.environ.get("REDPANDA_LLM_PROVIDER_TYPE", "openai").lower() if provider == "anthropic": return f"anthropic/{model}" return f"openai/{model}" def build_model(token: str, conversation_id: str) -> LiteLlm: # api_key is a placeholder: the gateway authenticates on the bearer, not the # native key. The bearer + conversation id ride extra_headers, which LiteLlm # forwards verbatim to the provider request (the LLM call). return LiteLlm( model=model_arg(), api_base=env("REDPANDA_LLM_PROVIDER_URL"), api_key="redpanda-gateway", extra_headers={ "Authorization": f"Bearer {token}", CONVERSATION_HEADER: conversation_id, }, ) def build_toolsets(token: str, conversation_id: str) -> list[McpToolset]: # One McpToolset per server over MCP Streamable HTTP; the same bearer + # conversation id ride every tool call, matching the LLM call. base = env("REDPANDA_MCP_BASE_URL") headers = {"Authorization": f"Bearer {token}", CONVERSATION_HEADER: conversation_id} names = [n.strip() for n in os.environ.get("REDPANDA_MCP_SERVERS", "").split(",") if n.strip()] return [ McpToolset(connection_params=StreamableHTTPConnectionParams(url=f"{base}/{name}", headers=headers)) for name in names ] async def main() -> None: # Fetched once for this short-lived sample; a long-running agent should # refresh the bearer before its TTL. token = get_access_token() # conversation_id is YOUR conversation id (chat thread, request id, A2A # contextId) - never a shared constant. ADK uses it as the session id, and it # is stamped on the LLM call and every MCP tool call. Mint one here. This demo # runs one conversation; a multi-conversation app rebuilds build_model + # build_toolsets per conversation (the id is baked into both). conversation_id = uuid.uuid4().hex agent = LlmAgent( name="assistant", model=build_model(token, conversation_id), instruction="You are a helpful agent.", tools=build_toolsets(token, conversation_id), ) runner = InMemoryRunner(agent=agent, app_name=APP_NAME) # create_session accepts session_id=, so the caller's id IS the session id. await runner.session_service.create_session( app_name=APP_NAME, user_id=USER_ID, session_id=conversation_id ) message = types.Content(role="user", parts=[types.Part(text="What tools can you call?")]) async for event in runner.run_async(user_id=USER_ID, session_id=conversation_id, new_message=message): if event.is_final_response() and event.content and event.content.parts: print(event.content.parts[0].text) # the assistant's reply if __name__ == "__main__": asyncio.run(main()) ``` ### Vercel AI SDK ```typescript import { createAnthropic } from '@ai-sdk/anthropic'; import { createGoogleGenerativeAI } from '@ai-sdk/google'; import { createOpenAICompatible } from '@ai-sdk/openai-compatible'; import { createMCPClient } from '@ai-sdk/mcp'; import { generateText, stepCountIs, type LanguageModel, type ToolSet } from 'ai'; import { randomUUID } from 'node:crypto'; const CONVERSATION_HEADER = 'X-Redpanda-Genai-Conversation'; // Required env var, or a clear failure (not an opaque 401 later). Export from the Setup tab. function env(key: string): string { const value = process.env[key]; if (!value) { throw new Error(`missing env var ${key} - export it from the Setup tab`); } return value; } // OAuth2 client_credentials grant against the gateway IDP -> the bearer for every call. async function getAccessToken(): Promise { const res = await fetch(env('REDPANDA_TOKEN_URL'), { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'client_credentials', client_id: env('REDPANDA_CLIENT_ID'), client_secret: env('REDPANDA_CLIENT_SECRET'), }), }); if (!res.ok) { throw new Error(`token request failed: ${res.status}`); } const { access_token } = (await res.json()) as { access_token: string }; return access_token; } // Fetched once for this short-lived sample. A long-running agent should refresh // the bearer before its TTL (for example, mint it inside a custom fetch, as the // Mastra sample does). const token = await getAccessToken(); const mcpBase = env('REDPANDA_MCP_BASE_URL'); // buildModel constructs the native AI SDK model for the configured provider. // REDPANDA_LLM_PROVIDER_TYPE selects the provider: "anthropic" and "google" use // their native wire (the gateway forwards /v1/messages and // /v1beta/...:generateContent to the upstream), everything else uses the // OpenAI-compatible /chat/completions route. All three point at the same // provider-scoped REDPANDA_LLM_PROVIDER_URL. The bearer is the real auth; apiKey // is a placeholder for the ignored native x-api-key / x-goog-api-key. function buildModel(): LanguageModel { const base = env('REDPANDA_LLM_PROVIDER_URL'); const model = env('REDPANDA_LLM_MODEL'); switch ((process.env['REDPANDA_LLM_PROVIDER_TYPE'] ?? 'openai').toLowerCase()) { case 'anthropic': { // baseURL + "/v1" -> the gateway forwards /v1/messages. const provider = createAnthropic({ baseURL: `${base}/v1`, apiKey: 'redpanda-gateway', headers: { Authorization: `Bearer ${token}` }, }); return provider(model); } case 'google': case 'gemini': { // baseURL + "/v1beta" -> /v1beta/models/:generateContent. const provider = createGoogleGenerativeAI({ baseURL: `${base}/v1beta`, apiKey: 'redpanda-gateway', headers: { Authorization: `Bearer ${token}` }, }); return provider(model); } default: { // OpenAI-compatible /chat/completions. apiKey becomes the Authorization: // Bearer the gateway authenticates on, so no placeholder header is needed. const provider = createOpenAICompatible({ name: 'redpanda', apiKey: token, baseURL: base, }); return provider(model); } } } const model = buildModel(); // MCP tool servers over Streamable HTTP. Transport headers are fixed per // connection, so build the clients per conversation: the bearer (gateway auth) // and the SAME conversation id ride every MCP tool call, matching the LLM call. async function connectTools(conversationId: string): Promise<{ tools: ToolSet; close: () => Promise }> { const headers = { Authorization: `Bearer ${token}`, [CONVERSATION_HEADER]: conversationId }; const urls = (process.env['REDPANDA_MCP_SERVERS'] ?? '') .split(',') .map((s) => s.trim()) .filter(Boolean) .map((name) => `${mcpBase}/${name}`); const clients = await Promise.all( urls.map((url) => createMCPClient({ transport: { type: 'http', url, headers } })) ); const toolSets = await Promise.all(clients.map((client) => client.tools())); const tools: ToolSet = Object.assign({}, ...toolSets); const close = async (): Promise => { await Promise.allSettled(clients.map((client) => client.close())); }; return { tools, close }; } // conversationId is YOUR conversation id, passed in by the caller (chat thread, // request id, A2A contextId) - never a shared constant. One chat() == one // conversation; the same id is stamped on the LLM call and every MCP tool call. async function chat(conversationId: string, prompt: string): Promise { const { tools, close } = await connectTools(conversationId); try { const { text } = await generateText({ model, tools, prompt, stopWhen: stepCountIs(10), // Stamp the conversation id so the gateway groups this LLM call with the // MCP tool calls into one transcript. headers: { [CONVERSATION_HEADER]: conversationId }, }); return text; } finally { await close(); } } // In your app the conversation id is the inbound thread/request id; mint one here. const answer = await chat(randomUUID(), 'What tools can you call?'); console.log(answer); ``` ### Mastra ```typescript import { createAnthropic } from '@ai-sdk/anthropic'; import { createGoogleGenerativeAI } from '@ai-sdk/google'; import { createOpenAICompatible } from '@ai-sdk/openai-compatible'; import { Agent } from '@mastra/core/agent'; import { MCPClient } from '@mastra/mcp'; import { AsyncLocalStorage } from 'node:async_hooks'; import { randomUUID } from 'node:crypto'; import type { LanguageModel } from 'ai'; const CONVERSATION_HEADER = 'X-Redpanda-Genai-Conversation'; // Required env var, or a clear failure (not an opaque 401 later). Export from the Setup tab. function env(key: string): string { const value = process.env[key]; if (!value) { throw new Error(`missing env var ${key} - export it from the Setup tab`); } return value; } // Holds the CURRENT conversation id for the in-flight turn. gatewayFetch reads it // so the LLM call and every MCP tool call carry the SAME id. In your app this is // your own id (chat thread, request id, A2A contextId) - never a shared constant. const conversation = new AsyncLocalStorage(); // OAuth2 client_credentials bearer, cached and refreshed before it expires. let token: { value: string; expiresAt: number } | undefined; async function bearer(): Promise { if (token && Date.now() < token.expiresAt - 30_000) { return token.value; } const res = await fetch(env('REDPANDA_TOKEN_URL'), { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'client_credentials', client_id: env('REDPANDA_CLIENT_ID'), client_secret: env('REDPANDA_CLIENT_SECRET'), }), }); if (!res.ok) { throw new Error(`token request failed: ${res.status}`); } const json = (await res.json()) as { access_token: string; expires_in?: number }; token = { value: json.access_token, expiresAt: Date.now() + (json.expires_in ?? 3600) * 1000 }; return token.value; } // ONE fetch shared by the model provider and every MCP server: it sets the bearer // (gateway auth) and stamps the conversation id (read live from AsyncLocalStorage) // on every request. Sharing it keeps the LLM call and the MCP tool calls in lockstep. const gatewayFetch: typeof fetch = async (input, init) => { const headers = new Headers(init?.headers); headers.set('Authorization', `Bearer ${await bearer()}`); const id = conversation.getStore(); if (id) { headers.set(CONVERSATION_HEADER, id); } return fetch(input, { ...init, headers }); }; const mcpBase = env('REDPANDA_MCP_BASE_URL'); // buildModel builds the AI SDK model Mastra runs on, pointed at the gateway. // REDPANDA_LLM_PROVIDER_TYPE selects the provider: "anthropic" and "google" use // their native wire with the version segment on the base URL (/v1, /v1beta), // everything else uses the OpenAI-compatible /chat/completions route. gatewayFetch // overwrites the Authorization header with the real bearer on every request, so // apiKey is just a placeholder that satisfies each constructor. function buildModel(): LanguageModel { const base = env('REDPANDA_LLM_PROVIDER_URL'); const model = env('REDPANDA_LLM_MODEL'); switch ((process.env['REDPANDA_LLM_PROVIDER_TYPE'] ?? 'openai').toLowerCase()) { case 'anthropic': { const provider = createAnthropic({ baseURL: `${base}/v1`, apiKey: 'redpanda-gateway', fetch: gatewayFetch, }); return provider(model); } case 'google': case 'gemini': { const provider = createGoogleGenerativeAI({ baseURL: `${base}/v1beta`, apiKey: 'redpanda-gateway', fetch: gatewayFetch, }); return provider(model); } default: { const provider = createOpenAICompatible({ name: 'redpanda', apiKey: 'redpanda-gateway', baseURL: base, fetch: gatewayFetch, }); return provider(model); } } } // Each MCP server is ${mcpBase}/ over Streamable HTTP; gatewayFetch carries // the bearer + conversation id on every tool call. Built once, reused per turn. const serverNames = (process.env['REDPANDA_MCP_SERVERS'] ?? '') .split(',') .map((s) => s.trim()) .filter(Boolean); const mcp = new MCPClient({ servers: Object.fromEntries( serverNames.map((name) => [name, { url: new URL(`${mcpBase}/${name}`), fetch: gatewayFetch }]) ), }); const agent = new Agent({ name: 'assistant', instructions: 'You are a helpful agent.', model: buildModel(), tools: await mcp.listTools(), }); // One conversation == one id, scoped with conversation.run so gatewayFetch stamps // it on the model call and every MCP tool call. In your app, pass your own id here. async function chat(conversationId: string, prompt: string): Promise { return conversation.run(conversationId, async () => { const result = await agent.generate(prompt, { maxSteps: 10 }); return result.text; }); } const answer = await chat(randomUUID(), 'What tools can you call?'); console.log(answer); await mcp.disconnect(); ``` > 📝 **NOTE** > > ADK Go ships only Gemini-shaped models, so the ADK Go sample works against a Google provider only. For an OpenAI or Anthropic provider, use one of the other frameworks. ## [](#observe-the-agent)Observe the agent Because the agent’s traffic flows through the gateway, Agentic Data Plane attributes its activity without any instrumentation in your code: - **Cost & Usage**: Spend, tokens, and latency roll up to the agent. See them on the agent’s **Cost & Usage** tab and in [budgets](https://docs.redpanda.com/agentic-data-plane/control/budgets/). - **Transcripts**: Each session that carries the conversation header appears on the agent’s **Transcripts** tab. See [See what your agent did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/). Transcript message text is recorded per LLM provider and is off by default. A transcript always shows token usage, latency, and tool calls; it shows the prompt and response text only when input and output message recording is turned on for the provider. See [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/). ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | 401 on the token request | The Client ID or client secret is wrong, or the secret expired or was revoked. The Client ID must be the full serviceaccounts/ value. Issue a new secret on the Credentials tab. | | 403 with model_not_allowed | The model is not on the provider’s allow-list. Pick a model the provider serves. The Setup tab fills in a valid model for you. | | 404 from the LLM endpoint | The provider name in the URL does not match a configured provider. Confirm the segment after /providers/ matches the provider’s name exactly. | | The Transcripts tab stays empty | The agent is not sending the X-Redpanda-Genai-Conversation header. Stamp it on every model call and tool call with the framework’s session identifier. | | A transcript shows usage but no message text | Message recording is off for the agent’s LLM provider. Turn on input and output message recording in the provider settings. Recording applies to future conversations only. | ## [](#next-steps)Next steps - [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/) - [See what your agent did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/) - [Create an agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) --- # Page 44: Write Effective System Prompts **URL**: https://docs.redpanda.com/agentic-data-plane/connect/system-prompts.md --- # Write Effective System Prompts > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Write Effective System Prompts latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: system-prompts page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: system-prompts.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/system-prompts.adoc description: Write system prompts that produce reliable, predictable agent behavior through clear constraints and tool guidance. page-topic-type: best-practices personas: agent_builder learning-objective-1: Identify effective system prompt patterns for agent reliability learning-objective-2: Apply constraint patterns to prevent unintended agent behavior learning-objective-3: Evaluate system prompts for clarity and completeness page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-24" --- Write system prompts that produce reliable, predictable agent behavior. Good prompts define scope, specify constraints, and guide tool usage. After reading this page, you will be able to: - Identify effective system prompt patterns for agent reliability - Apply constraint patterns to prevent unintended agent behavior - Evaluate system prompts for clarity and completeness ## [](#role-definition)Role definition Define what your agent does and the boundaries of its responsibilities. A clear role prevents scope creep and helps the agent refuse out-of-scope requests appropriately. ### [](#be-specific-about-agent-identity)Be specific about agent identity Define what the agent does, not what it is. Do ```text You are an order fulfillment agent for an e-commerce platform. You help customers track orders, update shipping addresses, and process returns. ``` Don’t ```text You are a helpful assistant. ``` ### [](#define-what-the-agent-does-and-doesnt-do)Define what the agent does and doesn’t do Explicitly state boundaries: what tasks the agent handles, what tasks it should refuse or delegate, and when to ask for human assistance. ```text Responsibilities: - Track customer orders - Update shipping addresses - Process returns up to $500 Do not: - Provide product recommendations (redirect to website) - Process refunds above $500 (escalate to manager) - Access orders from other customers ``` ## [](#tool-specification)Tool specification Tell the agent which tools are available and when to use them. Explicit tool guidance reduces errors and prevents the agent from guessing when to invoke capabilities. ### [](#list-available-tools)List available tools Name each tool the agent can use: ```text Available tools: - get_customer_orders: Retrieve order history for a customer - update_order_status: Change order state (shipped, delivered, canceled) - calculate_refund: Compute refund amount based on return policy ``` ### [](#explain-when-to-use-each-tool)Explain when to use each tool Provide decision criteria for tool selection. Do ```text Use get_customer_orders when: - Customer asks about order history - You need order details to answer a question Use update_order_status only when: - Customer explicitly requests a cancellation - You have confirmed the order is eligible for status changes ``` Don’t ```text Use the tools as needed. ``` ## [](#constraints-and-safety)Constraints and safety Set explicit boundaries to prevent unintended agent behavior. ### [](#define-data-boundaries)Define data boundaries Specify what data the agent can access: ```text Data access: - Only orders from the last 90 days - Only data for the authenticated customer - No access to employee records or internal systems ``` ### [](#set-response-guidelines)Set response guidelines Control output format and content: ```text Response guidelines: - Present order details as tables - Always include order numbers in responses - State the analysis time window when showing trends - If you cannot complete a task, explain why and suggest alternatives ``` ## [](#context-and-conversation-management)Context and conversation management Guide the agent on how to handle unclear requests and stay within conversation scope. These guidelines keep interactions focused and prevent the agent from making assumptions. ### [](#handle-ambiguous-requests)Handle ambiguous requests Guide the agent on how to clarify: ```text When request is unclear: 1. Ask clarifying questions 2. Suggest common interpretations 3. Do not guess customer intent ``` ### [](#define-conversation-boundaries)Define conversation boundaries Set limits on conversation scope: ```text Conversation scope: - Answer questions about orders, shipping, and returns - Do not provide product recommendations (redirect to website) - Do not engage in general conversation unrelated to orders ``` ## [](#error-handling)Error handling Guide agents to handle failures gracefully through clear prompt instructions. Agent errors fall into these categories: tool failures (external system issues) and reasoning failures (agent confusion or limits). ### [](#tool-failure-types)Tool failure types Tools can fail for multiple reasons. Transient failures include network timeouts, temporary unavailability, and rate limits. Permanent failures include invalid parameters, permission denied, and resource not found errors. Partial failures occur when tools return incomplete data or warnings. ### [](#graceful-degradation)Graceful degradation Design prompts so agents continue when tools fail: Example prompt guidance for graceful degradation ```text When a tool fails: 1. Attempt an alternative tool if available 2. If no alternative exists, explain the limitation 3. Offer partial results if you retrieved some data before failure 4. Do not make up information to fill gaps ``` Agents that degrade gracefully provide value even when systems are partially down. Implement retries in tools, not in agent prompts. The tool should retry network calls automatically before returning an error to the agent. ### [](#escalation-patterns)Escalation patterns Some failures require human intervention. Budget exceeded errors occur when max iterations are reached before task completion. Insufficient tools means no tool is available for the required action. Ambiguous requests happen when the agent can’t determine user intent after clarification attempts. Data access failures occur when multiple tools fail with no alternative path. Design prompts to recognize escalation conditions: Example prompt guidance for escalation ```text When you cannot complete the task: 1. Explain what you tried and why it didn't work 2. Tell the user what information or capability is missing 3. Suggest how they can help (provide more details, contact support, and so on) ``` ### [](#common-error-scenarios)Common error scenarios Include guidance for specific error types in your system prompt: **Timeout during tool execution:** When a tool takes longer than the agent timeout limit, the agent receives a timeout error in context. The agent should explain the delay to the user and suggest a retry. **Invalid tool parameters:** When the agent passes a wrong data type or missing required field, the tool returns a validation error. The agent should reformat parameters and retry, or ask the user for correct input. **Authentication failure:** When a tool can’t access a protected resource, it returns a permission denied error. The agent should explain the access limitation without exposing credentials or internal details. ## [](#output-formatting)Output formatting Control how the agent presents information to users. Consistent formatting makes responses easier to read and ensures critical information appears in predictable locations. ### [](#specify-structure)Specify structure Define how the agent presents information: ```text Output format: - Use tables for multiple items - Use bulleted lists for steps or options - Use code blocks for tracking numbers or order IDs - Include units (dollars, kilograms) in all numeric values ``` ## [](#template-variables)Template variables The system prompt is a Go template that Redpanda renders on every invocation. Use `{{.Variable}}` expressions to inject the current date and the calling user into the prompt at request time. A prompt with no template expressions renders unchanged, so existing prompts keep working without edits. The same variables are available in agent and subagent system prompts. System prompts support field substitution (such as `{{.User.Email}}`) and the simple conditionals `{{if}}` and `{{with}}`. Loops (`{{range}}`), sub-template definitions (`{{define}}` and `{{block}}`), and template invocation (`{{template}}`) are not supported. Agentic Data Plane rejects a prompt that uses them. ### [](#available-variables)Available variables | Expression | Description | Example output | | --- | --- | --- | | {{.Now.Date}} | Current date, in YYYY-MM-DD form | 2026-06-18 | | {{.Now.Weekday}} | Current day of the week | Thursday | | {{.Now.Month}} | Current month name | June | | {{.Now.Year}} | Current year | 2026 | | {{.Now.Time}} | Raw current timestamp. Apply a Go time layout for full control, for example, {{.Now.Time.Format "15:04 MST"}}. | 15:04 UTC | | {{.User.Email}} | Email of the user the agent acts for. Empty when no user is tied to the request, such as a service-account call. | user@example.com | All times are UTC. ### [](#example-prompt)Example prompt ```text You are a support agent. Today is {{.Now.Weekday}}, {{.Now.Month}} {{.Now.Year}}. You are assisting {{.User.Email}}. Scope every answer to that user's account, and do not reference other users' data. ``` ### [](#keep-prompts-cache-friendly)Keep prompts cache-friendly Model providers can cache an identical prompt prefix between requests to reduce cost and latency. The date fields, `{{.Now.Date}}`, `{{.Now.Weekday}}`, `{{.Now.Month}}`, and `{{.Now.Year}}`, hold the same value all day, so the prompt stays identical and the cache keeps hitting. Formatting a sub-day value from `{{.Now.Time}}`, such as the minute or second, changes the prompt on every request and defeats the cache. Use `{{.Now.Time}}` only when the agent needs the time of day. ### [](#validate-template-changes)Validate template changes When you create or update a managed agent, Agentic Data Plane validates the system prompt and rejects an invalid template with an error that names the field, so a mistake surfaces when you save the agent rather than after deployment. The agent also parses the prompt when it starts. Common mistakes include: - An unclosed `{{ }}` expression - A reference to a variable that does not exist - An unsupported construct, such as `{{range}}` - An undefined function from a stray non-template macro, such as `{{ FQ_START_DATE }}` - A time call that returns more than one value, such as `{{.Now.Time.Clock}}` Test the agent after editing the prompt. ## [](#evaluation-and-testing)Evaluation and testing Test system prompts systematically to verify behavior matches intent. Follow this process to validate prompts: | Test Type | What to Test | Example | | --- | --- | --- | | Boundary cases | Requests at edge of agent scope | Just inside: "Track order 123" (should work)Just outside: "Recommend products" (should refuse)Ambiguous: "Help with my order" (should clarify) | | Tool selection | Agent chooses correct tools | Create requests requiring each toolTest multiple applicable tools (verify best choice)Test no applicable tools (verify explanation) | | Constraint compliance | Agent follows "never" rules | Explicit forbidden: "Show payment methods"Indirect forbidden: "What’s the credit card number?"Verify refusal with explanation | | Error handling | Tool failures and limitations | Disable MCP server tool temporarilySend request requiring disabled toolVerify graceful response (no fabricated data) | | Ambiguous requests | Clarification behavior | Vague: "Check my stuff"Verify specific questions: "Orders, returns, or account?"Ensure no guessing of user intent | ## [](#design-principles)Design principles Apply these principles when writing system prompts to create reliable agent systems. ### [](#design-for-inspectability)Design for inspectability Make agent reasoning transparent so you can debug by reading conversation history. Your system prompt should encourage clear explanations: ```text Response format: - State what you're doing before calling each tool - Explain why you chose this tool over alternatives - If a tool fails, describe what went wrong and what you tried ``` Log all tool invocations with parameters, record tool results in structured format, and store agent responses with reasoning traces. Opaque agents that "just work" are impossible to fix when they break. ### [](#design-for-testability)Design for testability Test agents with boundary cases (requests at the edge of agent capability), error injection (simulate tool failures to verify graceful degradation), context limits (long conversations approaching token limits), and ambiguous requests (unclear user input to verify clarification behavior). Use the systematic testing approach in [Evaluation and testing](#evaluation-and-testing). ### [](#design-for-cost-control)Design for cost control Write clear system prompts that reduce wasted iterations. Vague prompts cause agent confusion and unnecessary tool calls. Each wasted iteration costs tokens. Guide agents to: - Request only needed data from tools (use pagination, filters) - Avoid redundant tool calls (check context before calling) - Stop when the task completes (don’t continue exploring) For cost management strategies including iteration limits and monitoring, see [Understand Agent Concepts](https://docs.redpanda.com/agentic-data-plane/connect/concepts/). ## [](#example-system-prompt-with-best-practices)Example: System prompt with best practices This complete example demonstrates all the patterns described in this guide: ```text You are an order analytics agent for Acme E-commerce. Responsibilities: - Answer questions about customer order trends - Analyze order data from Redpanda topics - Provide insights on order patterns Available tools: - get_customer_orders: Retrieve order history (parameters: customer_id, start_date, end_date) - analyze_recent_orders: Compute order statistics (parameters: time_window, group_by) When to use tools: - Use get_customer_orders for individual customer queries - Use analyze_recent_orders for trend analysis across multiple orders Never: - Expose customer payment information or addresses - Analyze data older than 90 days unless explicitly requested - Make business recommendations without data to support them Data access: - Only orders from the authenticated customer account - Maximum of 90 days of historical data Response guidelines: - Present structured data as tables - Always state the analysis time window - Include order counts in trend summaries - If data is unavailable, explain the limitation When request is unclear: - Ask which time period to analyze - Confirm whether to include canceled orders - Do not assume customer intent ``` ## [](#common-anti-patterns)Common anti-patterns Avoid these patterns that lead to unpredictable agent behavior. ### [](#vague-role-definition)Vague role definition Define specific agent responsibilities and scope. Generic role definitions fail because the agent has no guidance on what tasks to handle, what requests to refuse, or when to escalate to humans. Don’t ```text You are a helpful AI assistant. ``` This doesn’t constrain behavior or set expectations. The agent might attempt tasks outside its capabilities or handle requests it should refuse. Do ```text You are an order fulfillment agent for an e-commerce platform. You help customers track orders, update shipping addresses, and process returns up to $500. Do not: - Provide product recommendations (redirect to website) - Process refunds above $500 (escalate to manager) ``` Clear scope prevents the agent from attempting out-of-scope tasks and defines escalation boundaries. ### [](#missing-constraints)Missing constraints Set explicit boundaries on data access and operations. Without constraints, agents may access sensitive data, process excessive historical records, or perform operations beyond their authorization. Don’t ```text You can access customer data to help answer questions. ``` This provides no boundaries on what data, how much history, or which customers. The agent might retrieve payment information, access other customers' data, or query years of records. Do ```text Data access: - Only orders from the authenticated customer - Maximum of 90 days of historical data - No access to payment methods or billing addresses ``` Explicit boundaries prevent unauthorized access and scope queries to reasonable limits. ### [](#implicit-tool-selection)Implicit tool selection Specify when to use each tool with clear decision criteria. Vague tool guidance forces agents to guess based on tool names alone, leading to wrong tool choices, unnecessary calls, or skipped tools. Don’t ```text Use the available tools to complete tasks. ``` The agent must guess which tool applies when. This leads to calling the wrong tool first, calling all tools unnecessarily, or fabricating answers without using tools. Do ```text Use get_customer_orders when: - Customer asks about order history - You need order details to answer a question Use update_order_status only when: - Customer explicitly requests a cancellation - You have confirmed the order is eligible for status changes ``` Decision criteria enable reliable tool selection based on request context. ## [](#next-steps)Next steps - [Agentic Data Plane Quickstart for Agent Builders](https://docs.redpanda.com/agentic-data-plane/get-started/agent-builder-quickstart/) - [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) --- # Page 45: Test an MCP Server’s Tools with the Inspector **URL**: https://docs.redpanda.com/agentic-data-plane/connect/test-tools.md --- # Test an MCP Server’s Tools with the Inspector > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Test an MCP Server’s Tools with the Inspector latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: test-tools page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: test-tools.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/test-tools.adoc description: Use the Inspector tab to call tools, inspect resources and prompts, and verify your MCP server works without standing up an agent. page-topic-type: how-to personas: agent_builder learning-objective-1: Run an MCP tool from the Inspector and read its response learning-objective-2: Inspect a server's resources, prompts, and session activity learning-objective-3: Diagnose common errors (missing authentication, scope upgrade required, transport mismatch) before pointing an agent at the server page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-10" --- Verify that your MCP server’s [tools](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#tool), [resources](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#resource), and [prompts](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#prompt) work correctly before agents depend on them. The Inspector runs on the same JSON-RPC connection agents use, so a passing test means fewer failed tool calls in production. Use the Inspector after creating a server or whenever you change a tool’s schema. After completing this guide, you will be able to: - Run an MCP tool from the Inspector and read its response - Inspect a server’s resources, prompts, and session activity - Diagnose common errors (missing authentication, scope upgrade required, transport mismatch) before pointing an agent at the server ## [](#when-to-use-the-inspector)When to use the Inspector - After creating or registering a server, to confirm tool discovery completed and tools run correctly. - While iterating on a self-managed server, to test schema changes against a live connection. - When debugging an agent failure, to isolate whether the issue is in the agent or in the MCP server itself. ## [](#open-the-inspector)Open the Inspector 1. Open **MCP Servers** in the sidebar and click into your server. 2. Switch to the **Inspector** tab. The Inspector is a console: a tool list and a tool runner sit side by side, with a status strip along the top. Resource and prompt panels appear underneath only when the server exposes those capabilities. Two more surfaces open from the status strip: **Session details** and the **Protocol panel**. See [Review session and protocol details](#session) for both. ![MCP Inspector flow. The Inspector identifies the server’s MCP version and capabilities, discovers tools, resources, and prompts, sends a selected tool call as JSON-RPC, and shows the formatted result beside the wire frames, timing, progress, and errors.](https://docs.redpanda.com/agentic-data-plane/connect/_images/mcp-inspector-lifecycle.svg) Figure 1. The MCP Inspector follows one request from discovery through the protocol view ## [](#run-a-tool)Run a tool The tool list shows every tool the server returned from `tools/list`. When a server exposes more than one tool, a filter box narrows the list by tool name, title, or description, and shows a count of how many tools match. Long tool names wrap in full instead of being cut off. Select a tool to load it into the runner. 1. Select a tool from the list. The runner shows the tool’s input and, after you run it, its response. 2. Provide the tool’s input using one of the input modes: - **Form**: A field-by-field form generated from the tool’s input JSON schema. - **JSON**: The raw JSON input, for pasting or editing a whole object at once. - **cURL**: A ready-to-run `curl` command for the call, with a copy action. 3. Click **Run tool**, or press Ctrl+Enter (Cmd+Enter on macOS). While the call is in flight, a progress bar reflects any progress the server reports, and you can **Cancel** it. The response appears in a tabbed result card: - **Result**: The tool’s output. Toggle between **Formatted** (pretty-printed JSON) and **Raw** (the exact response text). - **Raw JSON-RPC**: The reconstructed request and response envelopes, with the method and parameters exactly as the server sees them. - **Output schema**: The tool’s declared output schema, shown when the tool provides one. A status indicator reports whether the call succeeded and how long it took. Copy actions let you copy the input, the output, or the JSON-RPC envelope. If the tool returns an error, the result card shows the structured error detail. See [Common errors](#errors) for what each common error means. ### [](#code-mode-tools)Code-mode tools If the server has **Code mode** enabled, the tool list also includes `{name}_search` and `{name}_execute` alongside the server’s regular tools. These are the helpers an agent uses to discover and orchestrate tools through generated Python or JavaScript. Test them like any other tool. ## [](#inspect-resources)Inspect resources When the server exposes resources through `resources/list`, a **Resources** panel appears below the runner. Many MCP servers don’t expose resources at all: if there’s no panel, that’s fine. If your server does expose resources: 1. Click a resource to load its content into the pane. 2. The Inspector renders text, JSON, and binary types differently; for a binary payload, it reports the size and tells you to decode the content with a client SDK. ## [](#inspect-prompts)Inspect prompts When the server exposes prompt templates through `prompts/list`, a **Prompts** panel appears below the runner. Prompt templates are parameterized prompts an agent can invoke by name. As with resources, many servers don’t expose prompts. If your server does expose prompts: 1. Click a prompt to render its template. 2. Fill in any required parameters in the rendered form. 3. Click **Run** to see the rendered prompt content. ## [](#session)Review session and protocol details The status strip along the top of the console shows the connection status and how many tool calls you’ve made this session, along with two controls: **Session details** opens a side panel with the session’s connection health, negotiated capabilities, and protocol version. Use it to confirm the Inspector connected and to see which capabilities (tools, resources, prompts) the server advertised. **Protocol panel** opens a panel next to the runner: - **Wire**: The JSON-RPC request and result frames for your calls, any notifications the server sends, and a timing breakdown of the most recent call. - **Timeline**: A running log of the calls you’ve made this session, each with its result and latency. - **Logs**: Log lines the server sends over MCP logging. A telemetry strip reports the last call’s latency, time to first byte, payload size, and estimated context tokens. Click **Clear** to empty these views. ## [](#errors)Common errors | Error | Meaning and fix | | --- | --- | | OAuthConnectionRequired | User-delegated auth has no stored token for the calling user. Redpanda includes an authorize_url in the error detail; complete the consent flow per User-delegated OAuth. | | OAuthTokenExpired | Stored token is expired and refresh failed. Re-consent through My Connections. | | scope_upgrade_required | The user’s connection lacks one of the server’s required_scopes. Re-consent with the higher scope. | | Transport / connection error | The Inspector can’t reach the upstream. For self-managed servers, check the Connection tab on the detail page; verify the URL and transport choice. | | Tool input validation error | The form’s input doesn’t match the tool’s schema. The error message includes the offending field. Update and re-run. | ## [](#test-from-the-cli)Test from the CLI Use [`rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) for the same tool calls outside the UI, when scripting smoke tests or running checks from CI. ```bash # List every tool exposed by a server rpk ai mcp-server tools list # Call a tool with a JSON arg blob rpk ai mcp-server tools call --input '{"arg1":"value"}' # Get server detail; includes the tool list by default. Add --no-tools # to skip discovery (faster when you only want metadata). rpk ai mcp-server get ``` The command targets the AI Gateway of your selected Agentic Data Plane environment, using credentials from `rpk ai auth login`. See [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/) for installation and sign-in. ## [](#next-steps)Next steps - [Code Mode](https://docs.redpanda.com/agentic-data-plane/gateway/code-mode/) - [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) --- # Page 46: Connect an Agent to Microsoft Teams **URL**: https://docs.redpanda.com/agentic-data-plane/connect/triggers/microsoft-teams.md --- # Connect an Agent to Microsoft Teams > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Connect an Agent to Microsoft Teams latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: triggers/microsoft-teams page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: triggers/microsoft-teams.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/triggers/microsoft-teams.adoc description: Add a Microsoft Teams trigger to a deployed agent so people in your organization can chat with it in a personal Teams chat. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Register a Microsoft Teams bot and configure its Azure app registration for single-tenant access learning-objective-2: Add a Microsoft Teams trigger to an agent and copy its messaging endpoint learning-objective-3: Publish the bot to your organization and verify the agent responds in a Teams chat page-git-created-date: "2026-06-02" page-git-modified-date: "2026-08-10" --- A Microsoft Teams trigger connects a deployed agent to Microsoft Teams so people in your organization can chat with it in a personal Teams chat. Replies stream back into the chat as the agent produces them, and the agent receives the message sender’s verified email address, so it can identify the user. The setup spans three systems: the Microsoft Teams Developer Portal hosts the bot and the Teams app, the Azure portal holds the bot’s authentication settings and permissions, and Agentic Data Plane holds the agent’s trigger. After reading this page, you will be able to: - Register a Microsoft Teams bot and configure its Azure app registration for single-tenant access - Add a Microsoft Teams trigger to an agent and copy its messaging endpoint - Publish the bot to your organization and verify the agent responds in a Teams chat ## [](#prerequisites)Prerequisites - A deployed agent. If you don’t have one, see [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/). - Microsoft Entra admin access for your organization. Granting API permission consent and approving the Teams app require an admin. - Access to the [Teams Developer Portal](https://dev.teams.microsoft.com) and the [Teams admin center](https://admin.teams.microsoft.com). > 📝 **NOTE** > > Microsoft and Redpanda each need a value from the other: Redpanda needs the bot credentials before it can show the messaging endpoint URL, and the bot needs that URL to finish its setup. In this guide, you create the bot first without an endpoint, add the trigger in Redpanda to get the URL, and then return to Microsoft to finish. > > The Microsoft steps refer to a third-party product. Specific UI elements may not be up to date. For current instructions, see the [Microsoft Teams Developer Portal documentation](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/teams-developer-portal). ## [](#create-a-bot-in-the-teams-developer-portal)Create a bot in the Teams Developer Portal 1. Go to the [Teams Developer Portal](https://dev.teams.microsoft.com/tools) and open **Tools** > **Bot management**. 2. Click **New bot**, enter a name, and create it. ![The Bot management page in the Teams Developer Portal](https://docs.redpanda.com/agentic-data-plane/connect/_images/teams-devportal-bots.png) 3. Leave the endpoint address blank for now. You get the URL from Redpanda later. ## [](#generate-a-client-secret)Generate a client secret In the bot’s settings: 1. Click **Client secrets**. 2. Click **New client secret**. 3. Copy the generated secret value and store it securely. The value is shown only when you create it. ![The Client secret created dialog in the Teams Developer Portal](https://docs.redpanda.com/agentic-data-plane/connect/_images/teams-devportal-secret.png) You now have two values from the Teams side: the bot ID, shown in the bot list, and the client secret you just generated. The bot ID and the application (client) ID of the bot’s app registration are the same value. > 💡 **TIP** > > If you can’t create another client secret in the Teams Developer Portal, open the bot’s app registration in the Azure portal and create one under **Certificates & secrets** instead. ## [](#configure-the-app-registration-in-azure)Configure the app registration in Azure Creating a bot in the Teams Developer Portal also creates a matching app registration in Microsoft Entra. Adjust its settings. ### [](#find-the-app-registration)Find the app registration 1. In the [Azure portal](https://portal.azure.com), search for **App registrations**. 2. Open the **Owned applications** tab and select your bot’s app registration. 3. On the **Overview** page, note the application (client) ID and the directory (tenant) ID. You need both when you add the trigger. ![The Essentials pane of an app registration in the Azure portal](https://docs.redpanda.com/agentic-data-plane/connect/_images/azure-app-overview.png) ### [](#set-the-account-type-to-single-tenant)Set the account type to single-tenant > ❗ **IMPORTANT** > > The app registration must be single-tenant. A multi-tenant configuration causes 401 authorization errors on every inbound message. If the bot stops responding after setup, check this first. Changes can take up to 60 minutes to propagate. 1. In the app registration, open **Authentication**. 2. On the **Supported accounts** tab, select the single-tenant option for the supported account types. Depending on the portal experience, it is labeled **Single tenant only** or **Accounts in this organizational directory only**. ![The Supported accounts tab of the app registration’s Authentication page in the Azure portal](https://docs.redpanda.com/agentic-data-plane/connect/_images/azure-supported-accounts.png) 3. Save. ### [](#add-microsoft-graph-permissions)Add Microsoft Graph permissions The trigger uses the bot’s own credentials to look up the message sender’s email address in Microsoft Graph and passes it to the agent as the user identity. This lookup runs as a background service, so it requires application permissions, not delegated permissions. 1. In the app registration, open **API permissions**. 2. Click **Add a permission** and select **Microsoft Graph**. 3. Select **Application permissions**. 4. Add each of these permissions: | Permission | Purpose | | --- | --- | | User.ReadBasic.All | Resolve the sender’s email address from their Microsoft Entra object ID. | | Chat.Read.All | Read chat messages, as required by Teams. | | Chat.ReadBasic.All | Read chat metadata, as required by Teams. | 5. Click **Grant admin consent**. The button includes your organization’s name. The status of each permission changes from **Not granted** to **Granted**. ![The Configured permissions table on the app registration’s API permissions page](https://docs.redpanda.com/agentic-data-plane/connect/_images/azure-api-permissions.png) > 📝 **NOTE** > > Granting admin consent requires a Microsoft Entra admin role, such as Global Administrator or Privileged Role Administrator. If the button is unavailable, ask an admin to grant consent. ## [](#add-the-microsoft-teams-trigger-to-your-agent)Add the Microsoft Teams trigger to your agent 1. Open your agent’s **Triggers** tab. 2. Click **Add trigger** and select **Microsoft Teams**. 3. Fill in the trigger configuration: | Field | Value | | --- | --- | | Display name | A name for this trigger, for example, Production bot. The trigger’s unique ID is derived from it at creation and can’t be changed afterward. | | Description | Optional. A short description of the trigger, shown in the agent’s trigger list. | | Application (client) ID | The application (client) ID from the app registration Overview page. | | Directory (tenant) ID | The directory (tenant) ID from the app registration Overview page. | | Client secret | A reference to a secret in the secret store that holds the client secret you generated. Select Existing to pick one, or New to name the secret, paste the value, and click Create secret. Only the reference is kept on the trigger. | ![The Add trigger page with Microsoft Teams selected, a display name and description entered, the application and tenant IDs filled in, and the New client secret fields showing a secret name and masked value](https://docs.redpanda.com/agentic-data-plane/connect/_images/teams-trigger-form.png) 4. Click **Create trigger**. The new trigger appears on the **Triggers** tab with a **Pending** status. ![A collapsed Microsoft Teams trigger card named Production bot with a Pending status](https://docs.redpanda.com/agentic-data-plane/connect/_images/teams-trigger-added.png) ## [](#copy-the-messaging-endpoint)Copy the messaging endpoint Redpanda’s messaging bridge picks up the new trigger, validates the bot credentials with Microsoft, and reports the trigger’s messaging endpoint URL. This takes up to a minute, and the **Triggers** tab refreshes on its own. 1. On the **Triggers** tab, wait for the status to change from **Pending** to **Connected**. The card expands automatically and the **Messaging endpoint** field shows the URL, similar to: ```text https://msteams-bridge..clusters.rdpa.co/teams/v1/ ``` In this URL, `` is the ID of the cluster the agent runs on, and `` is the agent’s ID. 2. Copy the URL exactly as shown. You need it in the next step. ![An expanded Microsoft Teams trigger card with a green Connected badge, showing the application client ID, directory tenant ID, client secret reference, and the messaging endpoint URL with a copy button](https://docs.redpanda.com/agentic-data-plane/connect/_images/teams-trigger-connected.png) If the status changes to **Error** instead, the message on the card explains the reason. See [Troubleshooting](#troubleshooting). ## [](#set-the-endpoint-url-on-the-bot)Set the endpoint URL on the bot 1. Go back to the [Teams Developer Portal](https://dev.teams.microsoft.com/tools). 2. Open **Tools** > **Bot management** and select your bot. 3. Paste the messaging endpoint URL into the endpoint address field. ![The bot’s Configure page in the Teams Developer Portal](https://docs.redpanda.com/agentic-data-plane/connect/_images/teams-devportal-endpoint.png) 4. Save. If you manage the bot as an Azure Bot resource instead, paste the URL into the **Messaging endpoint** field on the bot’s **Configuration** page in the Azure portal. ## [](#create-and-publish-the-teams-app)Create and publish the Teams app A Teams app makes the bot visible to people in your organization. 1. In the Teams Developer Portal, click **Apps**, and then create a new app and give it a name. 2. On the **Basic information** tab, fill in the descriptions, developer information, and the application (client) ID from the app registration. 3. Open **App features**, select **Bot**, and choose the bot you created. Under the scopes where people can use the bot, select **Personal**. With only this scope selected, people use the bot in personal chats and can’t add it to channels or group chats, which matches what the trigger is designed for. 4. Click **Publish** > **Publish to your org**. This submits the app for admin approval. ## [](#approve-the-app-in-the-teams-admin-center)Approve the app in the Teams admin center 1. Go to the [Teams admin center](https://admin.teams.microsoft.com). 2. Open **Teams apps** > **Manage apps** and search for your app. 3. Select the app, then click **Publish** to approve it. The app can take up to 24 hours to appear in the Teams app catalog after approval. > 💡 **TIP** > > By default, the app is available to everyone in the organization. To restrict it, assign it to specific users or groups under **Manage apps**. To pin it to the Teams sidebar, add it to a setup policy under **Setup policies**. ## [](#verify)Verify 1. Open the agent’s **Triggers** tab and confirm the trigger status is **Connected**. This confirms that Redpanda validated the bot credentials with Microsoft. It does not confirm that the endpoint URL is set correctly on the bot, so also send a real message. 2. In Microsoft Teams, find the app in your chats and send it a message. While the agent works, Teams shows a progress indicator, and then the reply streams into the chat with an AI-generated label. Tool calls appear as cards that update in place as they finish. ## [](#how-a-message-flows)How a message flows When someone messages the bot, Teams delivers the message to the trigger’s messaging endpoint. Redpanda’s messaging bridge authenticates the request against the trigger’s bot credentials, resolves the sender’s email address through Microsoft Graph, and forwards the message to the agent along with that identity. The reply streams back into the chat as the agent produces it. A reply that exceeds the Teams streaming limits finishes as a regular message. An agent can have several Microsoft Teams triggers, each with its own bot registration and credentials. For example, you can expose one agent through a production bot and a test bot at the same time. Inbound messages are matched to the trigger whose bot they were addressed to. Each trigger’s health is rechecked continuously: about every 30 seconds, the bridge validates the trigger’s credentials with Microsoft and updates the status on the **Triggers** tab. If a client secret expires or is rotated to a wrong value, the trigger flips to **Error** with the reason, without anyone sending a message. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | The bot never responds, or replies with a 401 error | The app registration is most likely set to multi-tenant. In the Azure portal, open the app registration, click Authentication, and select the single-tenant option for the supported account types. Allow up to 60 minutes for the change to propagate. | | The trigger shows Error with a message that the client secret is not set in the secret store | The messaging bridge could not read the secret from this cluster’s secret store. In Secrets Store, confirm that a secret exists whose ID exactly matches the reference on the trigger. If it does and the error persists, contact Redpanda support. | | The trigger shows Error with a message that Microsoft rejected the bot credentials | The application (client) ID, directory (tenant) ID, and client secret don’t match a valid app registration. The Microsoft error code in the message names the exact cause. For example, AADSTS7000215 means the client secret value is invalid. | | Teams shows a Permissions needed message | A Teams admin has not yet approved the app. Approve it in the Teams admin center. | | The Grant admin consent button is unavailable | The signed-in Azure user lacks admin privileges. Ask a Global Administrator to grant consent on the API permissions page. | | The agent responds but doesn’t receive the sender’s email address | The User.ReadBasic.All Graph permission is missing, or admin consent was not granted. Recheck the Microsoft Graph permissions step. | | The trigger status stays on Pending | The messaging bridge has not reported on the trigger yet. The first report normally arrives within a minute. If it doesn’t, refresh the tab; if the status still doesn’t change, contact Redpanda support. | ## [](#next-steps)Next steps - [Trigger Agents](https://docs.redpanda.com/agentic-data-plane/connect/triggers/overview/) - [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) - [How Agents Work](https://docs.redpanda.com/agentic-data-plane/connect/agents-overview/) --- # Page 47: Trigger Agents **URL**: https://docs.redpanda.com/agentic-data-plane/connect/triggers/overview.md --- # Trigger Agents > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Trigger Agents latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: triggers/overview page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: triggers/overview.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/triggers/overview.adoc description: Triggers invoke a deployed agent without calling its API directly, from Microsoft Teams or on a schedule. page-topic-type: overview personas: agent_builder, platform_engineer learning-objective-1: Describe what an agent trigger is and how a trigger invokes an agent learning-objective-2: Describe how triggers are added, edited, and disconnected on an agent learning-objective-3: Interpret the status that an agent's Triggers tab reports for each trigger page-git-created-date: "2026-06-02" page-git-modified-date: "2026-08-03" --- A trigger is a configured way to invoke an agent without calling its API directly. Without a trigger, an agent only responds to direct calls against its API. Two trigger types are available: - A Microsoft Teams trigger connects the agent to Microsoft Teams. People in your organization chat with the agent in a personal Teams chat, and replies stream back as the agent produces them. See [Connect an Agent to Microsoft Teams](https://docs.redpanda.com/agentic-data-plane/connect/triggers/microsoft-teams/). - A schedule trigger runs the agent automatically on a recurring schedule. Each run sends a fixed message to the agent and is recorded as a transcript, with no reply path back. See [Run an Agent on a Schedule](https://docs.redpanda.com/agentic-data-plane/connect/triggers/schedule/). Each trigger is its own resource on the agent, created, edited, and disconnected on its own, so you can attach several to the same agent. For example, one agent can serve a production Teams bot and a test Teams bot side by side, each through its own trigger. > 📝 **NOTE** > > Triggers are available for Redpanda-managed agents only. A self-managed agent runs on your own infrastructure and is invoked through it, so it has no **Triggers** tab. To bring a self-managed agent into Agentic Data Plane for observability and governance, see [Set up a self-managed agent](https://docs.redpanda.com/agentic-data-plane/connect/self-managed-agents/). After reading this page, you will be able to: - Describe what an agent trigger is and how a trigger invokes an agent - Describe how triggers are added, edited, and disconnected on an agent - Interpret the status that an agent’s Triggers tab reports for each trigger ## [](#manage-triggers)Manage triggers Triggers live on the agent’s detail page, on the **Triggers** tab: - Click **Add trigger**, pick the trigger type, and fill in its configuration. A Microsoft Teams trigger takes the bot’s application (client) ID, directory (tenant) ID, and a secret store reference to the bot’s client secret. For the full setup, including the Microsoft side, see [Connect an Agent to Microsoft Teams](https://docs.redpanda.com/agentic-data-plane/connect/triggers/microsoft-teams/). - To change a trigger’s configuration, edit it on its card. The trigger’s unique ID, derived from its display name at creation, and the trigger’s type are fixed; the display name, description, and type-specific configuration stay editable. - To remove a trigger, disconnect or delete it on its card, depending on its type. Removing it stops the agent from being invoked through that trigger and can’t be undone. A Microsoft Teams trigger also exposes a messaging endpoint: a URL that Teams delivers inbound messages to. Redpanda reports this URL on the trigger’s card shortly after you add the trigger, and you register it with your bot so Teams knows where to send messages. ## [](#trigger-status)Trigger status Adding a trigger does not validate it on the spot. For a Microsoft Teams trigger, Redpanda’s messaging bridge checks each trigger in the background, about every 30 seconds, by validating its credentials with Microsoft, and reports the result. The **Triggers** tab shows one of three states: - Pending: No check has been reported yet. A trigger sits here briefly after you add it. - Connected: The latest check passed. For a Microsoft Teams trigger, this means Microsoft accepted the bot credentials. - Error: The latest check failed. The message on the card explains the reason, for example, a rejected client secret. Because the check runs continuously, the status also catches problems that appear later: if a bot’s client secret expires, the trigger flips to Error without anyone sending a message. The tab refreshes the status on its own, and you can also refresh on demand. A schedule trigger reports the outcome of its runs rather than a connection check. Its card shows the last run’s outcome and the next run time. For the outcomes a run can have, see [Run an Agent on a Schedule](https://docs.redpanda.com/agentic-data-plane/connect/triggers/schedule/). ## [](#next-steps)Next steps - [Connect an Agent to Microsoft Teams](https://docs.redpanda.com/agentic-data-plane/connect/triggers/microsoft-teams/) - [Run an Agent on a Schedule](https://docs.redpanda.com/agentic-data-plane/connect/triggers/schedule/) - [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) --- # Page 48: Run an Agent on a Schedule **URL**: https://docs.redpanda.com/agentic-data-plane/connect/triggers/schedule.md --- # Run an Agent on a Schedule > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Run an Agent on a Schedule latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: triggers/schedule page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: triggers/schedule.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/triggers/schedule.adoc description: Add a schedule trigger to a deployed agent so it runs automatically on a recurring cron schedule, in the timezone you choose. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Add a schedule trigger to an agent using a preset or a cron expression learning-objective-2: Choose the timezone and input prompt for scheduled runs learning-objective-3: Describe how a scheduled run invokes the agent and who it runs as page-git-created-date: "2026-07-27" page-git-modified-date: "2026-08-03" --- A schedule trigger runs a deployed agent automatically on a recurring schedule that you define with a cron expression. Each run sends a fixed message, the input prompt, to the agent in the timezone you choose. A schedule trigger is one-directional. It starts the agent on time and records the run as a transcript. This differs from a Microsoft Teams trigger, where a person sends a message and the agent’s reply streams back to them. Each scheduled run invokes the agent on behalf of the person who created the trigger, with that person’s access, and the run is attributed to them in transcripts and cost reporting. Editing the schedule later doesn’t change who it runs as. > 📝 **NOTE** > > Triggers are available for Redpanda-managed agents only. A self-managed agent runs on your own infrastructure and is invoked through it, so it has no **Triggers** tab. To bring a self-managed agent into Agentic Data Plane for observability and governance, see [Set up a self-managed agent](https://docs.redpanda.com/agentic-data-plane/connect/self-managed-agents/). After reading this page, you will be able to: - Add a schedule trigger to an agent using a preset or a cron expression - Choose the timezone and input prompt for scheduled runs - Describe how a scheduled run invokes the agent and who it runs as ## [](#prerequisites)Prerequisites - A deployed Redpanda-managed agent. If you don’t have one, see [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/). ## [](#add-a-schedule-trigger)Add a schedule trigger 1. In Redpanda Cloud, open your agent’s **Triggers** tab. 2. Click **Add trigger** and select **Schedule**. 3. Under Details, enter a display name, for example, `Daily summary`. The trigger’s unique ID is derived from it at creation and can’t be changed afterward. To describe the trigger for other people, add a description. 4. Set the schedule and timezone. See [Set the schedule](#set-the-schedule) and [Choose the timezone](#choose-the-timezone). 5. Under Input, enter an input prompt. This text is the message the agent receives on every run, for example, `Summarize new support tickets from the last 24 hours`. 6. Click **Create trigger**. The trigger is active as soon as you create it. An agent can have up to 10 schedule triggers, so you can run the same agent on several schedules, each with its own input prompt. ## [](#set-the-schedule)Set the schedule Under Schedule, set when the agent runs: - For a common cadence, pick a preset and set the time. The presets are hourly, daily, weekdays, weekly, and monthly. - For a schedule the presets don’t cover, expand the **Advanced** section and enter a standard five-field cron expression. A cron expression has five fields, separated by spaces: minute, hour, day of month, month, and day of week. For example, `0 9 * * 1-5` runs at 9:00 AM on weekdays. The readback below the field restates the schedule in plain language and previews the next run, so you can confirm the expression does what you intend. Two limits apply to the schedule: - Runs must be at least 15 minutes apart. A schedule whose runs fall closer together than that is rejected with the message that the schedule runs too frequently. - Shortcut expressions such as `@daily` and `@hourly` are not supported. Use a five-field expression instead. ## [](#choose-the-timezone)Choose the timezone Select a timezone. The schedule is evaluated in this timezone, and it accounts for daylight saving, so a run set for 9:00 AM stays at 9:00 AM across the change. The field defaults to your browser’s timezone, and you can change it to any IANA timezone, for example, `Europe/Prague` or `America/New_York`. The next run time shown on the form and on the trigger’s card is a preview, computed in the schedule’s timezone. Redpanda remains the authority on the exact time each run fires. ## [](#how-a-scheduled-run-works)How a scheduled run works At each scheduled time, Redpanda invokes the agent with the input prompt as a user message. The agent processes the message as it would a chat, and the work is recorded as a transcript. Because the run is one-directional, no reply is delivered anywhere. Only one run of a trigger is in flight at a time. Redpanda records each run in the trigger’s run history with an outcome: - Succeeded: Redpanda started the run and the agent accepted it. - Failed: The run could not be started, or the agent rejected it. The recorded error explains the reason. - Missed: The scheduled time passed during Redpanda downtime. Missed runs are not retried or caught up later. - Skipped: The previous run of the same trigger was still in progress at the scheduled time. To review past runs, expand the trigger’s card and click **View runs**. Each run is listed with its outcome, and a run that reached the agent produces a transcript, the same as any other agent invocation. ## [](#manage-a-schedule-trigger)Manage a schedule trigger Schedule triggers live on the agent’s **Triggers** tab, each on its own card: - To change a trigger, edit it on its card. The trigger’s unique ID and its type are fixed. The display name, description, schedule, timezone, and input prompt stay editable. - To review past runs, expand the card and click **View runs**. - To stop the schedule, delete the trigger on its card. Deleting stops all future runs and can’t be undone. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | The schedule is rejected as running too frequently | Two runs fall less than 15 minutes apart. Widen the schedule so consecutive runs are at least 15 minutes apart. | | A shortcut expression such as @daily is rejected | Shortcut expressions are not supported. Rewrite the schedule as a five-field cron expression, for example, 0 0 * * * for every day at midnight. | | Runs fire at an unexpected local time | Check the trigger’s timezone. The schedule is evaluated in the timezone set on the trigger, not the viewer’s local time, and it shifts with daylight saving. | | A run is recorded as Missed | The scheduled time passed while Redpanda was unavailable. Missed runs are not caught up. The next scheduled run proceeds as normal. | | A run is recorded as Skipped | The previous run of the same trigger was still in progress at the scheduled time. Give the agent more time between runs, or simplify the input prompt so each run finishes sooner. | ## [](#next-steps)Next steps - [Trigger Agents](https://docs.redpanda.com/agentic-data-plane/connect/triggers/overview/) - [Connect an Agent to Microsoft Teams](https://docs.redpanda.com/agentic-data-plane/connect/triggers/microsoft-teams/) - [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) --- # Page 49: Configure User-Delegated OAuth **URL**: https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth.md --- # Configure User-Delegated OAuth > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Configure User-Delegated OAuth latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: user-delegated-oauth page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: user-delegated-oauth.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/user-delegated-oauth.adoc description: Have each end-user authenticate against the MCP server's upstream system with their own credentials. Redpanda stores their token in the vault and injects it at call time. page-topic-type: how-to personas: platform_engineer, agent_builder, security_compliance_lead learning-objective-1: Configure an MCP server to use user-delegated OAuth, with either automatic setup or a provider you registered learning-objective-2: Walk an end-user through the consent flow and verify the connection learning-objective-3: Troubleshoot scope upgrades, token expiry, and refresh failures page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- User-delegated OAuth means each end-user authenticates against the MCP server’s upstream system (for example, Slack, Jira, Google) with their own credentials. Redpanda stores their token in the token vault and injects it at call time. Contrast with service-account OAuth, where one shared identity is used for every caller. For a self-managed server, Redpanda can set up the OAuth client for you from the server URL, or you can attach an OAuth provider your organization already registered. Managed servers always attach a provider. After completing this guide, you will be able to: - Configure an MCP server to use user-delegated OAuth, with either automatic setup or a provider you registered - Walk an end-user through the consent flow and verify the connection - Troubleshoot scope upgrades, token expiry, and refresh failures ## [](#prerequisites)Prerequisites - For a **managed** MCP server, or to attach a provider your organization already manages on a **self-managed** server: an OAuth provider resource configured on the **Outbound providers** tab of **Integrations setup**. The provider declares the upstream’s `authorize_url`, `token_url`, supported scopes, and client credentials. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). - For automatic setup on a **self-managed** server: nothing, if the server supports dynamic client registration. If it doesn’t, you need an OAuth app registered with the upstream vendor, its client ID, and, for a confidential app, a client-secret reference already created in the secret store in `UPPER_SNAKE_CASE` (proto regex `^[A-Z][A-Z0-9_]*$`). - The scopes the upstream API needs, if you want to request a specific set rather than whatever the server advertises. - For **self-managed** MCP servers: the server URL must be `https://` (proto rule `remote_mcp.user_oauth_requires_https`). HTTP is rejected at create time. - For **managed** MCP servers: the type must support user-delegated OAuth. SQL doesn’t; Slack, Jira, and Google managed types do. Check [Managed catalog](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/) before configuring. ## [](#configure-the-server)Configure the server 1. Create your MCP server (see [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/)). 2. Set up the OAuth client for the upstream. What you do depends on the server type: - For a **self-managed** (remote) server, enter the server URL and let Redpanda check what it supports. For a server that authenticates users over OAuth, Redpanda recommends setting up OAuth automatically, which means Redpanda registers an OAuth client and manages each user’s tokens for you. If the server supports dynamic client registration, there is nothing else to configure. If it doesn’t, Redpanda walks you through the parts it can’t do for you: register an OAuth app in the upstream’s developer console, add the authorization callback URL that Redpanda displays to that app, then paste the app’s credentials back into the form. The credentials are the `Client ID` from the developer console and, for a confidential app, a client-secret reference from the secret store in `UPPER_SNAKE_CASE`, for example `GITHUB_CLIENT_SECRET`. Leave the reference empty for a public PKCE app. Either way, Redpanda records the provider it resolved or created for the server, marked with a **Discovered** badge in the **Outbound providers** list so you can tell it from a provider you registered by hand. See [Discover a provider from an MCP server URL](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/#discover-a-provider-from-an-mcp-server-url). To attach an OAuth provider your organization already manages instead, click **Use a different authentication method**, set `Method` to `User-delegated OAuth`, then set `Setup` to `Attach existing provider` and select the provider (`UserOAuthAuth.provider_name`). Click **New** to register a provider without leaving the form. The same `Setup` toggle switches back to `Set up automatically`. - For a **managed** server, select the OAuth provider in the type’s configuration (`UserOAuthAuth.provider_name`). Managed types always attach a provider, so automatic setup doesn’t apply. 3. (Optional) Restrict the scopes Redpanda requests. Expand **Set specific scopes** and list the scopes the upstream API needs (`UserOAuthAuth.required_scopes`). Redpanda enforces them at consent time. Leave it empty to request whatever the server advertises. 4. (Optional) Override token injection through the API or CLI. By default Redpanda sends `Authorization: Bearer `. To use a different header, set `TokenInjection.header_name`. To omit the prefix entirely (for example, an upstream that expects a bare API key as the token), set `TokenInjection.header_prefix` to the empty string. The create form doesn’t expose these fields. 5. Save. > 📝 **NOTE** > > Choosing user-delegated OAuth instead of service-account OAuth **is** the credential-mode decision: there’s no separate field. User-delegated gives each caller a per-user upstream identity; service-account gives every caller one shared identity. Switching between them later requires re-consent for every active user. > 📝 **NOTE** > > Editing an existing server works differently. The edit page doesn’t re-check the server URL, so you set `Method` and `Setup` yourself. Leaving the provider empty there keeps the provider the server already has, so switching an existing server to automatic setup is an explicit choice (`UserOAuthAuth.automatic_setup`): automatic setup re-runs discovery and can register a new upstream client. Setting both a provider name and automatic setup is rejected. > 💡 **TIP** > > From the CLI, `--user-oauth-provider` and `--user-oauth-scopes` on `rpk ai mcp-server create` or `rpk ai mcp-server update` attach a provider you already registered; the flags don’t request automatic setup. To script automatic setup, set `automatic_setup: true` under the server’s `user_oauth` block in a GitOps manifest. See [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) and [Manage Resources with GitOps](https://docs.redpanda.com/agentic-data-plane/cli/gitops/). ## [](#the-user-connection-flow)The user connection flow The first time a user calls a tool that needs this server’s authentication, Redpanda doesn’t have a stored token for them. The behavior is: 1. The MCP RPC returns `FAILED_PRECONDITION` with an `OAuthConnectionRequired` error detail. The detail carries an `authorize_url`. 2. Agentic Data Plane surfaces a consent prompt to the user, pointing at the `authorize_url`. 3. The user completes the device-authorization flow with the upstream provider. 4. The upstream provider redirects back to Redpanda with a token. Redpanda stores it in the token vault under that user’s identity. 5. The original tool call retries automatically. Subsequent calls reuse the stored token. After consent, the user can see and revoke their connection under **My Connections** in Agentic Data Plane. ## [](#manage-your-connections)Manage your connections The **My Connections** page in the sidebar is each user’s view of their own third-party connections, so a user can authorize the providers their MCP servers need without waiting for a tool call to trigger the consent flow. It shows connections for your own identity only. The page uses a two-pane layout. The left rail lists providers grouped by status: - **Available to connect**: Providers you haven’t authorized yet. - **Connected**: Providers with a usable connection. - **Needs attention**: Connections that have failed, or whose refresh token is close to expiring, and need to be reconnected. Select a provider to open its detail pane on the right. The pane shows the granted scopes, a status badge (**Connected**, **Needs attention**, **Action required**, or **Not connected**), and the actions for that provider: **Connect** runs the consent flow and stores a token in the vault under your identity, **Reconnect** re-runs consent for an existing connection (for example, to grant additional scopes or recover after a refresh token expires), and **Disconnect** revokes it. A connection that the gateway can renew automatically from a stored refresh token stays **Connected** with no action from you; it moves to **Needs attention** or **Action required** only when it can no longer renew on its own. > 📝 **NOTE** > > Connections are per-user. Each user authorizes their own accounts, and one user’s connections are not visible to or usable by another. You can also manage your connections from the terminal: run `rpk ai connection list` to see the services you are signed in to, and `rpk ai connection revoke ` to disconnect one. See [rpk ai connection](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-connection/). ## [](#scope-upgrades)Scope upgrades If a user’s stored connection has fewer scopes than the server’s `required_scopes`, the gateway returns a `scope_upgrade_required` error and surfaces a new `authorize_url` requesting the additional scopes. The user re-consents; the connection is updated in place. ## [](#refresh-and-expiry)Refresh and expiry Redpanda transparently refreshes tokens before they expire, using the refresh token returned at consent time. A connection is only considered expired when its access token has lapsed **and** the gateway can no longer renew it automatically. As long as a usable refresh token is stored, the connection stays active across access-token expiry, and the gateway renews access silently on the next call. This matters for upstreams that issue short-lived access tokens with long-lived refresh tokens: a GitHub App, for example, issues 8-hour access tokens backed by refresh tokens that last around six months, so an idle connection stays active for months rather than showing as expired within hours. A connection is reported as expired, meaning the user must reconnect, only when the access token has lapsed and no usable refresh token exists: either none was stored, or the refresh token itself has expired. When that happens, the next tool call returns `OAuthTokenExpired` with a `reason`, and the user must re-consent through the same flow as the initial connection. Each connection reports whether a refresh token backs it, so a client can tell a connection that renews automatically from one that needs reconnecting. The `OAuthConnectionService.ListConnections` and `GetConnection` responses expose this on the `Connection` message through two read-only fields: `refresh_token_present` (a refresh token is stored, so the gateway renews access automatically) and `refresh_token_expires_at` (when the refresh token itself expires, if the upstream reports it, as GitHub Apps do; absent when unknown or non-expiring). ## [](#service-account-oauth-contrast)Service-account OAuth contrast If you want one shared upstream identity for every caller (instead of per-user identities), choose **Service-account OAuth** on the server instead of **User-delegated OAuth**. With service-account OAuth, every caller of every tool sees the same upstream identity; the upstream system has no idea which Agentic Data Plane user invoked the tool. With user-delegated OAuth, the upstream system sees each end-user as themselves and applies their own permissions. For the field-by-field service-account-OAuth setup, see [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/#configure-authentication). ## [](#worked-examples)Worked examples - [Slack](https://docs.redpanda.com/agentic-data-plane/connect/managed/slack/): consumer-facing user-delegated OAuth example. Shows the consent flow against a real Slack workspace. - [Jira](https://docs.redpanda.com/agentic-data-plane/connect/managed/jira/): enterprise user-delegated OAuth example. Atlassian’s OAuth flow differs from Slack’s; this page calls out scope-management gotchas. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | "OAuth provider not found" | The provider name on the server doesn’t match an OAuth provider in Agentic Data Plane. Check spelling and that the provider exists. | | "HTTPS required" on save (self-managed only) | User-delegated OAuth requires https:// URLs on the MCP server (proto rule remote_mcp.user_oauth_requires_https). Switch the server’s URL to HTTPS. | | OAuthConnectionRequired returned even after the user consented | The user’s vault entry might have been revoked or the token expired with no refresh. Have the user re-consent through My Connections. | | scope_upgrade_required returned | The required scopes on the server changed (or the user originally consented with fewer scopes). The user re-consents with the higher scope. | | My Connections shows stale entries | Connections persist until manually revoked. Have the user disconnect and reconnect the connection if upstream credentials changed. | ## [](#next-steps)Next steps - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [Service-account OAuth setup](https://docs.redpanda.com/agentic-data-plane/connect/create-server/#configure-authentication) --- # Page 50: Control & Govern **URL**: https://docs.redpanda.com/agentic-data-plane/control.md --- # Control & Govern > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Control & Govern latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: index page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/index.adoc description: Govern agent activity with guardrails, spend limits, and permissions. page-git-created-date: "2026-05-28" page-git-modified-date: "2026-06-10" --- Govern agent activity across your deployment. Set guardrails and spend limits, and control who can do what with roles and permissions. - [Set Up Guardrails](guardrails/) Understand how guardrails work, create them, review blocked requests, and look up the available policies. - [Analyze Cost and Usage](cost-usage/) Break down LLM spend, requests, and tokens by provider, model, token type, agent, user, or tag. Compare periods, export CSV reports, and see which agents are active right now. - [Set Up Budgets](budgets/) Cap LLM spend with per-agent budgets, and see what the Agentic Data Plane records automatically and where to view it. - [Track Spend by Tag](cost-allocation-tags/) Group and filter LLM spend by the tags you set on agents, so you can attribute cost to a department, team, or environment for chargeback and reporting. - [Manage Access](access/) Control who can do what in the Agentic Data Plane with access policies. --- # Page 51: Manage Access Policies **URL**: https://docs.redpanda.com/agentic-data-plane/control/access-policies.md --- # Manage Access Policies > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Manage Access Policies latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: access-policies page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: access-policies.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/access-policies.adoc description: Create Cedar-based access policies that permit or forbid specific actions in the Agentic Data Plane, with conditions over resource tags and ownership. page-topic-type: how-to personas: security_compliance_lead, platform_engineer learning-objective-1: Create an access policy that permits or forbids specific actions learning-objective-2: Write policy conditions that read tags and ownership safely learning-objective-3: Manage access policies from the CLI page-git-created-date: "2026-07-30" page-git-modified-date: "2026-08-07" --- Use access policies to express rules that roles can’t: deny a group access to production-tagged agents, or let only a resource’s creator modify one. Each policy permits or forbids specific actions, with conditions evaluated on every request. After reading this page, you will be able to: - Create an access policy that permits or forbids specific actions - Write policy conditions that read tags and ownership safely - Manage access policies from the CLI > 📝 **NOTE** > > Access policies are a preview capability, available when your organization has them enabled. If you don’t see **Access** in the sidebar, they aren’t enabled for your organization. ## [](#how-access-policies-work)How access policies work Access policies use the [Cedar policy language](https://www.cedarpolicy.com/). A policy is a `permit` or `forbid` statement over three parts: - **Principal**: Who the policy applies to. A user (`User::"[alice@example.com](mailto:alice@example.com)"`) or a group (`Group::"support"`). Principals don’t carry attributes such as department or nationality: model those facts as group membership. - **Action**: What operation the policy covers. An action ID is an entity type and a verb joined by a dot, for example `Action::"Agent.get"` or `Action::"McpServerTool.call"`. See [Action reference](#action-reference). - **Resource**: What the action targets, as a typed entity, for example `resource is Agent` for every agent or `resource == Agent::"support-bot"` for one. Most entity IDs are the resource’s bare name, the same one the API path uses. The policy resources are the exception: `Policy` and `PolicyTemplate` carry their collection prefix, as in `Policy::"policies/deny-prod-reads"`. Always pin the resource type. With a specific action ID such as `Action::"Agent.get"` the pin is redundant, because the action already names its one entity type, but it costs nothing. With an action group a `permit` requires it. Validation also uses the pin to catch conditions that can never match, so pinning is what turns a silent no-op into a save-time error. Every request resolves the same way: - A request is denied unless a `permit` matches it. - A matching `forbid` always wins. This is what makes cross-cutting denials possible: one `forbid` can override any number of grants. Enforcement is fail-closed. A `forbid` that errors during evaluation denies the request rather than being skipped. Policy changes also reach the enforcement points asynchronously, so a successful save is not yet an enforcement guarantee. ### [](#how-roles-compose-with-policies)How roles compose with policies Use roles to get started and to stay coarse: provision the first user, and hand out the Admin role where per-resource precision isn’t the point. Redpanda turns those role bindings into permits for you, so they take part in the same evaluation and you never author them by hand. Among the built-in roles, only Admin carries Agentic Data Plane permissions, so role-based access control (RBAC) gives you one coarse grant and nothing in between. Writer and Reader reach the control plane, Kafka, pipelines, and knowledge bases, but no agent, MCP server, or LLM provider. Policies are how you grant everyone who shouldn’t be an Admin. See [Control Who Can Do What](https://docs.redpanda.com/agentic-data-plane/control/permissions-overview/). From there, authorization defers to policy evaluation. Every decision that needs a condition, a specific resource, or a denial belongs in a policy, and a `forbid` overrides whatever a role granted. ## [](#action-reference)Action reference Verbs are shared across entity types, and an action ID pairs one verb with one entity. This table lists the verbs each entity type supports, by entity type in alphabetical order. Combine them with a dot to get the action ID: `Budget` plus `update` is `Action::"Budget.update"`. | Entity type | Verbs | | --- | --- | | AdminConnection | list, revoke, rotate | | Agent | get, list, create, update, delete, invoke | | AgentCredential | list, create, delete | | AgentNetwork | get | | AgentTrigger | get, list, create, update, delete | | AgentTriggerRun | list | | AuditLog | list | | Budget | get, list, create, update, delete | | CIMDSettings | get, update | | DCRSettings | get, update | | EffectivePolicySet | get, list | | Guardrail | get, list, create, update, delete | | LLMProvider | get, list, create, update, delete, invoke | | McpServer | get, list, create, update, delete, initialize, ping, tools_list, prompts_get, prompts_list, resources_list, resources_read, resources_templates_list, logging_set_level | | McpServerTool | call | | OAuthClient | get, list, create, update, delete | | OAuthConnection | get, list, authorize, revoke | | OAuthProvider | get, list, create, update, delete, attach | | Policy | get, list, create, update, delete | | PolicyTemplate | get, list, create, update, delete | | Session | get, list, delete | | Spending | get | | SystemPolicy | list | | Transcript | get, list | The `SystemPolicy.list` action gates reading the permits derived from role bindings. That view names every binding’s principal, so it sits on its own action rather than riding along with `Policy.list`. Entity type names are case-sensitive, and the casing doesn’t always follow the prose (`McpServer`, not `MCPServer`). Copy them from this table. Access policies cover the entity types listed here and nothing else. A policy can’t govern anything outside the table, including Redpanda Connect pipelines and knowledge bases. Copy action IDs from this table rather than deriving them from a resource or API name, because the two don’t line up predictably. ### [](#action-groups)Action groups Each verb also exists as an action group, so `action in Action::"get"` matches every `.get` action. > ❗ **IMPORTANT** > > A `permit` that references an action group must pin the resource type with `resource is ` or `resource == ::""`. Saving an unpinned group permit fails, because group membership grows as new resource types adopt the verb, so the stored grant would silently widen on the next deployment. Writing `resource in ::""` doesn’t count as a pin: it bounds the subtree but not the type, so the grant would still widen when a descendant type adopts the verb. `forbid` statements are exempt: a growing deny widens in the safe direction. Use action groups in `forbid`, where one clause can cover every type that adopts a verb. In a `permit` the required type pin narrows the group back down to the actions of that one type, so naming the actions is equivalent and clearer. To grant a verb across every type, name each `.` action explicitly. The Access page does this for you when you pick verbs with the All resources scope. ## [](#attribute-reference)Attribute reference Conditions read the attributes in this table. Every one is optional at the schema level, so each needs a `has` guard before you read it. An unguarded read is an evaluation error, and in a `forbid` that error denies. | Attribute | Entity types that carry it | Required guard | | --- | --- | --- | | Tags | Agent, Budget, Guardrail, LLMProvider, McpServer, OAuthClient, OAuthProvider, Policy | resource.hasTag("") | | created_by, updated_by | Agent, AgentTrigger, Budget, Guardrail, LLMProvider, McpServer, OAuthClient, OAuthProvider, Policy, PolicyTemplate | resource has created_by | | changed_tags | Agent, Budget, Guardrail, LLMProvider, McpServer, OAuthClient, OAuthProvider, on update only | resource has changed_tags | Put the guard first in the same boolean expression, then read the value. [Write conditions](#write-conditions) shows the full form for each. Tags are the attribute half of attribute-based access control (ABAC). Not every type carries them, and the set doesn’t follow a rule you can infer, so check the table rather than assuming. The read-only and derived types carry neither tags nor a creator: sessions, transcripts, agent credentials, OAuth connections, and the derived policy views. The `Policy` type carries tags but no `changed_tags`, so you can condition on a policy’s current tags but not on a tag transition. Both `created_by` and `updated_by` hold `User` references, so compare them to `principal` directly rather than to a string. A condition on any attribute a type doesn’t carry is dead code. It’s valid Cedar, it saves when the resource type isn’t pinned, and it never matches. Pin the type and validation catches it instead. ## [](#prerequisites)Prerequisites - Access policies enabled for your organization. - An account that can author access policies. Admin is the only built-in role that can, because policy authoring is itself an Agentic Data Plane permission. Writer and Reader can’t create, edit, or view them. To let someone author policies without making them an Admin, grant the policy permissions through a custom role, or through a policy that names the `Policy` actions. See [Access policy permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#access-policy-permissions). ## [](#open-the-access-page)Open the Access page Open **Access** in the sidebar. These tabs cover everyday work: - **Policies**: The access policies you author. This is where you create, edit, and delete them. - **Templates**: Reusable policy templates, including the built-in quick-start set. The **Roles** and **System policies** tabs are read-only views of what RBAC already grants. ## [](#create-a-policy)Create a policy 1. On the **Policies** tab, click **Create policy**. 2. Give the policy a name. 3. Choose the effect: Permit grants access, and Forbid takes access away, overriding anything a permit or a role grants. 4. Set the principal: a user from your organization directory, or a group name from your identity provider (IdP). Group membership stays managed in the IdP. 5. Under Permissions, choose how to grant: - Actions: Pick individual verbs for a one-off grant. - Template: Link to a reusable template. The template fixes which actions the policy covers and which effect it carries, so the effect and conditions you set here are ignored. The principal and scope you set still apply, so you decide who gets it and how far it reaches. 6. In Actions mode, work through these steps: 1. Action: Select verbs. The picker offers them in categories: Management (`get`, `list`, `create`, `update`, `delete`), Execution (`invoke`, `call`), Access lifecycle (`attach`, `authorize`, `revoke`, `rotate`), and MCP protocol. A category is a display grouping, not a Cedar action group. 2. Applies to: Choose All resources for every type, All of a type for every resource of one type, or Specific resource for one. Picking a child type under Specific resource scopes to the children of one parent, such as the tools of one MCP server. 3. Conditions: Optional. Add WHEN rows to narrow when the policy applies and UNLESS rows to carve out exceptions. Each row conditions on a resource tag or its creator. See [Attribute reference](#attribute-reference). 7. Click **Create policy**. 8. Confirm the policy appears on the **Policies** tab with the effect, principal, and scope you set. > 💡 **TIP** > > Set the scope before picking verbs if you already know it. The picker only offers verbs the scoped type supports, so narrowing the scope afterward drops any selected verb the new type doesn’t have. The footer summarizes the grant in plain language and lists whatever is still missing before you can save. A `permit` that covers write verbs across every type raises a warning rather than blocking the save. Narrow the scope unless you genuinely want that reach. Every save validates the policy against the current schema, so a policy that stores successfully is well-formed. See [A policy won’t save](#a-policy-wont-save). The **Form** and **Cedar** toggle at the top of the page switches between the form fields and the Cedar text. Edits in either view update the other, and writing Cedar directly produces the same policy. The toggle doesn’t appear when your starting point fixes the principal or the scope, such as an agent’s **Permissions** tab, because raw Cedar could rewrite the locked clause. A policy that grants a whole role bundle opens read-only in this form. To change what it grants, change the role binding in the control plane. ### [](#start-from-a-template)Start from a template The **Templates** tab includes built-in quick-start templates, each a superset of the one before it: | Template | Grants | | --- | --- | | Read only | View-only access across all resources (get, list, and read). | | Sandboxed | Read-only access plus the ability to use agents and MCP servers (invoke, call tools). No management. | | Standard | Sandboxed access plus full management of agents, MCP servers, LLM providers, guardrails, triggers, and budgets. Excludes managing access policies. | | Full access | Every Agentic Data Plane action, including managing access policies. | A template fixes the action set, not the reach. Applies to defaults to All resources, and you narrow it from there: to every resource of one type, or to a single resource. The same Read only template can therefore back an org-wide viewer grant and a one-agent grant, with no second template to maintain. The built-in templates all permit. A template you author yourself can forbid instead, and a policy that links it denies. > 📝 **NOTE** > > A template is a live link, not a copy. Editing a template changes what every policy linked to it grants, so check who links a template before you widen it. ### [](#the-built-in-owner-lifecycle-policy)The built-in Owner lifecycle policy One policy ships with the feature and applies to everyone: users can get, update, and delete the agents, MCP servers, LLM providers, guardrails, and budgets they created, plus create and manage triggers on their own agents. It deliberately stops short in a few places. Creating a resource at the top level isn’t covered, because a create authorizes against a payload that records no creator yet, so ownership can’t grant it. Agent credentials and sessions aren’t covered either, because neither records a creator at all. ## [](#write-conditions)Write conditions Conditions make policies attribute-based: they read resource tags, group membership, and ownership at evaluation time. Follow these rules to write conditions that behave the way you expect. Validation at save time enforces most of them. Put the rule in `when` and the exemption in `unless`. Both clauses can sit on the same policy, and a negated test inside `when` is harder to read than the `unless` that replaces it. ### [](#guard-every-tag-read)Guard every tag read Reading a tag a resource doesn’t have is an evaluation error, not false. Always pair `getTag` with a `hasTag` check on the same key. This policy denies reads of ITAR-tagged agents, and exempts US persons: ```cedar forbid ( principal, action == Action::"Agent.get", resource is Agent ) when { resource.hasTag("itar") && resource.getTag("itar") == "true" } unless { principal in Group::"us-persons" }; ``` Without the `hasTag` guard, the policy errors on every untagged resource, and an erroring `forbid` denies. You would block access to every untagged agent, the opposite of the intent. Validation rejects the unguarded form when you save. A tag condition on a type that carries no tags is dead code: it’s valid Cedar but can never match, and validation flags it when the policy pins the resource type. Pin the type on every policy that reads tags so you get that check. See [Attribute reference](#attribute-reference) for which types carry tags. ### [](#model-people-facts-as-groups)Model people facts as groups Principals carry an email and group memberships, nothing else. Write `principal in Group::"nationality/US"`, not `principal.nationality == "US"`. Validation rejects attribute reads on principals. ### [](#guard-ownership-reads)Guard ownership reads To reference a resource’s creator, guard the read the same way as a tag: ```cedar resource has created_by && resource.created_by == principal ``` Write the attribute on the left of the comparison. The condition builder on the Access page parses this shape back into editable rows, and `principal == resource.created_by` leaves the policy read-only in the UI. ### [](#conditions-on-writes-evaluate-the-resulting-state)Conditions on writes evaluate the resulting state On create and update actions, `resource` is the state the operation produces, not the stored row. A `forbid` on production-tagged agents therefore fires on any update to an agent that carries the tag, even an update that doesn’t touch tags, and stops firing on the update that removes the tag. A write-scoped tag condition therefore behaves as a state invariant. A resource that violates it is frozen for non-exempt principals until an update fixes the violation. Reads and deletes evaluate the stored row, so a resulting-state condition behaves normally on those verbs. To gate the transition itself (adding or removing a specific tag), condition on `changed_tags`, the set of tag keys the update adds, removes, or changes: ```cedar forbid ( principal, action == Action::"Agent.update", resource is Agent ) when { resource has changed_tags && resource.changed_tags.contains("itar") } unless { principal in Group::"itar-cleared" }; ``` The `changed_tags` attribute exists only on the update path, so this policy doesn’t fire on create. To close the create case too, pair the policy with a create-scoped clause that reads the tag directly: ```cedar forbid ( principal, action == Action::"Agent.create", resource is Agent ) when { resource.hasTag("itar") } unless { principal in Group::"itar-cleared" }; ``` ### [](#guard-scalar-attributes-and-only-on-the-true-case)Guard scalar attributes, and only on the true case A scalar field that holds its zero value doesn’t appear on the entity at all, so `resource.enabled == true` errors whenever `enabled` is `false`, and that error denies. Guard scalar reads the same way as tags: ```cedar resource has enabled && resource.enabled == true ``` You can’t condition on a scalar’s zero value. Absent and `false` are indistinguishable, so `resource has enabled && resource.enabled == false` never matches, saves without complaint, and silently does nothing. Write the rule as the positive case and flip it with `unless`. ## [](#grant-an-agent-its-own-permissions)Grant an agent its own permissions Each agent’s detail page includes a **Permissions** tab. The Access policies card lists what the agent itself may do, acting as its own principal. **Create policy** opens the same policy form with the principal locked to the agent’s service account, so the policy targets a `User` principal like any other. A read-only Roles & access card shows the RBAC role bindings that apply to the agent, both direct and inherited. Those are managed in the control plane. An MCP server’s **Access** tab uses the same form from the other end: it locks the resource scope to that server rather than the principal. To control who may act **on** an agent, rather than what the agent may do, author a policy on the **Policies** tab with `resource == Agent::""`. ## [](#manage-policies-from-the-cli)Manage policies from the CLI Run `rpk ai policy` commands to create, get, list, update, and delete access policies, and to apply or diff them from manifest files for GitOps workflows. See [rpk ai policy](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-policy/). ## [](#examples)Examples These policies cover the shapes that come up most often. Adapt the group names, tag keys, and actions to your environment. ### [](#deny-a-group-access-to-production-agents)Deny a group access to production agents Members of `contractors` can’t read agents tagged `env=prod`, no matter what their roles grant: ```cedar forbid ( principal in Group::"contractors", action == Action::"Agent.get", resource is Agent ) when { resource.hasTag("env") && resource.getTag("env") == "prod" }; ``` ### [](#only-owners-can-modify-their-agents)Only owners can modify their agents Nobody but an agent’s creator can update it: ```cedar forbid ( principal, action == Action::"Agent.update", resource is Agent ) unless { resource has created_by && resource.created_by == principal }; ``` ### [](#restrict-who-can-call-one-mcp-servers-tools)Restrict who can call one MCP server’s tools Only the `support` group may call tools on the `zendesk` MCP server. The resource is the tool child entity, scoped to its parent server: ```cedar permit ( principal in Group::"support", action == Action::"McpServerTool.call", resource is McpServerTool in McpServer::"zendesk" ); ``` ### [](#default-closed-classification-gate)Default-closed classification gate Nothing is readable until it’s explicitly cleared. An agent with no `classification` tag is denied, and only `classification=public` clears the gate: ```cedar forbid ( principal, action == Action::"Agent.get", resource is Agent ) unless { resource.hasTag("classification") && resource.getTag("classification") == "public" }; ``` ## [](#troubleshoot)Troubleshoot Policy problems surface either when you save a policy or when a request hits it. Start from the error you have. ### [](#a-policy-wont-save)A policy won’t save Validation runs in strict mode against the current schema and reports every problem it finds at once. The error text is abbreviated here; search your own error for the quoted fragment. | Error contains | Fix | | --- | --- | | Unknown action | The action ID isn’t one the schema defines. If you pasted a role permission name, the error names the action ID to use instead. Otherwise take the . ID from Action reference; the error suggests a near match when it can find one. | | unrecognized entity type | Check the spelling and the casing. A resource that exists in the API isn’t automatically a policy entity type. | | unable to guarantee safety of access to tag | Add resource.hasTag("") && immediately before the getTag call, on the same key. | | not found on entity type User | Principals carry no attributes. Model the fact as a group and write principal in Group::"us-persons". | | without a resource type pin | A permit names an action group. Add resource is , or name each . action explicitly. | | clause can never match | The condition reads an attribute the pinned type doesn’t carry, such as a tag condition on an untagged type. Check Attribute reference, then retarget the policy or drop the clause. | Validation runs against the policy body, and only when a write includes it, so it never rejects a policy stored before a schema change. To run the current checks against an older policy, re-submit its body, for example by re-applying it with `rpk ai policy apply`. Editing only the name or description re-validates nothing. ### [](#a-request-is-denied)A request is denied A denial caused by access policies surfaces as a permission-denied error: - A `forbid` that matches cleanly returns a generic permission-denied message. Check the **Policies** tab for a `forbid` covering the action and resource. - A `forbid` that errors during evaluation also denies, and the error names the policy. Check that policy for an unguarded tag or attribute read, then re-submit its body to run current validation against it. - A missing `permit` also denies, with the same generic message. Confirm a `permit` covers the action, whether from a policy or from a role binding, and add one if nothing does. On update actions, authorization runs inside the write transaction, after request validation. An unauthorized caller can therefore receive an invalid-argument or not-found error instead of a permission-denied one, and a concurrent-modification conflict can surface as an aborted error. Treat any of them as a failure, and don’t branch on which arrives first. ## [](#next-steps)Next steps - [rpk ai policy](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-policy/) - [Control Who Can Do What](https://docs.redpanda.com/agentic-data-plane/control/permissions-overview/) - [Roles and Permissions Reference](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/) --- # Page 52: Manage Access **URL**: https://docs.redpanda.com/agentic-data-plane/control/access.md --- # Manage Access > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Manage Access latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: access page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: access.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/access.adoc description: Control who can do what in the Agentic Data Plane with access policies. page-git-created-date: "2026-06-01" page-git-modified-date: "2026-08-03" --- Control who can do what in the Agentic Data Plane. Write access policies that permit or forbid specific actions for a user, a group, or a service account, and look up the permissions behind them. - [Control Who Can Do What](https://docs.redpanda.com/agentic-data-plane/control/permissions-overview/) Understand how Agentic Data Plane decides who can do what: access policies carry the decision, and RBAC bootstraps the administrators who author them. - [Manage Access Policies](https://docs.redpanda.com/agentic-data-plane/control/access-policies/) Create Cedar-based access policies that permit or forbid specific actions in the Agentic Data Plane, with conditions over resource tags and ownership. - [Roles and Permissions Reference](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/) Look up the permissions Agentic Data Plane enforces across LLM providers, MCP servers, agents, access policies, pipelines, knowledge bases, and governance APIs. --- # Page 53: Set Up Budgets **URL**: https://docs.redpanda.com/agentic-data-plane/control/budgets.md --- # Set Up Budgets > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Set Up Budgets latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: budgets page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: budgets.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/budgets.adoc description: Cap LLM spend with per-agent budgets, and see what the Agentic Data Plane records automatically and where to view it. page-topic-type: how-to personas: platform_engineer, pilot_lead learning-objective-1: Set a per-agent budget that caps LLM spend and warns before the cap learning-objective-2: Identify what spending data the Agentic Data Plane records automatically learning-objective-3: View spend breakdowns by agent, model, and provider page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-30" --- The Agentic Data Plane caps LLM spend with budgets and records every LLM call as a spending event. Set a budget to enforce a hard spending cap per agent, then read what you actually spend on the **Cost & Usage** page under **Governance**, through individual [transcripts](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#transcript), and through breakdown queries by provider, model, user, agent, or provider type. After completing these steps, you will be able to: - Set a per-agent budget that caps LLM spend and warns before the cap - Identify what spending data the Agentic Data Plane records automatically - View spend breakdowns by agent, model, and provider ## [](#set-a-spend-limit)Set a budget A **budget** caps LLM spend over a recurring period. When an agent’s spend for the period reaches the budget’s hard limit, AI Gateway rejects that agent’s next LLM request with `HTTP 429` until the period resets. A separate warning threshold fires before the cap, so you can react before AI Gateway cuts the agent off. Redpanda Agentic Data Plane enforces budgets per agent. A budget identifies an _agent_ by its resource name in the form `agents/`, the same identity that appears as `agent_name` in spend data. ### [](#how-a-budget-works)How a budget works | Setting | What it does | | --- | --- | | Limit | The hard cap on per-period spend. You set it in dollars in the UI; the API stores it in USD microcents (1 cent = 1,000,000 microcents). When a matching agent’s accrued spend for the period reaches this value, the agent’s next LLM request through the gateway gets HTTP 429. Spend resets to zero at the start of each period. | | Warning threshold | A spend level, lower than the limit, at which Agentic Data Plane warns: gateway responses carry a SpendLimit-Warning header and Agentic Data Plane records a warning metric. Requests still pass. Must be greater than zero and less than the limit. | | Period | How often the spend pool resets: daily, weekly, or monthly. Periods are calendar-aligned in UTC: daily at 00:00 UTC, weekly at 00:00 UTC Monday, monthly at 00:00 UTC on the first of the month. | | Target agent | Which agent the budget applies to. Leave it unset to create the tenant default budget. Set it to an agent’s resource name (agents/) to create a per-agent override. | ### [](#default-and-per-agent-override-budgets)Default and per-agent override budgets You can have one default budget per tenant and at most one override per agent: - The **default** budget (no target agent) gives every agent its own independent pool of the limit per period. One agent reaching its cap doesn’t affect another. - A **per-agent override** targets a single agent by resource name (`agents/`) and replaces the default for that agent. Use an override to give a specific agent a higher or lower cap than the fleet default. Adding an override partway through a period doesn’t reset the agent’s usage: while a default budget exists, a new override inherits the default’s current spending window instead of starting a fresh one, so spend the agent already accrued this period still counts toward the override’s cap. Deleting and recreating an override behaves the same way, so an agent can’t gain fresh runway by having its override recreated mid-period. Editing a budget’s limit never moves the window either; spend already accrued this period keeps counting. (If no default budget exists, the override starts a new window when you create it.) The target agent is immutable. To move an override to a different agent, delete it and create a new one. An override matches on the agent’s resource name, so recreating an agent with the same name keeps the override pointed at it; the new instance counts as a continuation for budget purposes. When you read a budget, it also reports the current period’s spend, when the period started, when it resets, and (for the default budget) the agent currently closest to its cap. ### [](#set-a-budget-in-the-ui)Set a budget in the UI Open **Budgets** under **Governance** in the sidebar. The page shows the tenant default budget as a card: its cap and period, the warn threshold, and how many agents are doing fine, getting close, or over the limit. Per-agent overrides appear in a table below the card, with each override’s `Agent override` target, `Period`, current `Usage` against the cap, `Warn at` threshold, and when it was last `Updated`. To create the tenant default budget: 1. Click **Create default budget**. 2. Under `Budget`, set `Cap usage at` to a dollar amount and choose a period (day, week, or month). Use the quick-set chips ($25, $100, $500, $1,000) for common values. 3. Drag the `Warn at` slider to set the warning threshold as a percentage of the cap (80% by default). 4. Review the Configuration preview panel, which summarizes the budget, period, and the warn and block thresholds in dollars, then click **Create default budget**. Open the default budget from the **Budgets** page to see its detail view: the per-agent spending limit (each agent gets its own limit, not one shared pool), the reset schedule, the warn threshold, and how much each agent has spent so far toward its limit. To give one agent a different cap, click **Add override**, pick the agent (each agent can have at most one override; agents that already have one are grayed out), then set the `Budget` and `Warn at` controls the same way. The `Resource name` is auto-derived from the picked agent and is immutable; the `Display name` is editable. ### [](#manage-budgets-through-the-api)Manage budgets through the API `BudgetService` exposes standard create, read, update, and delete operations: | Method | Use it to | | --- | --- | | CreateBudget | Create the tenant default or a per-agent override. | | GetBudget, ListBudgets | Read one budget, or list all budgets, each with current-period spend status. | | UpdateBudget | Change the limit, warning threshold, or period. Send a field mask naming the fields you change. | | DeleteBudget | Remove a budget. Deleting the default removes the per-agent pools; deleting an override falls that agent back to the default. | A service account needs the matching `dataplane_adp_budget_*` permission for each operation (`create`, `get`, `list`, `update`, or `delete`). See [Budget permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#budget-permissions). ## [](#what-agentic-data-plane-records-automatically)What Agentic Data Plane records automatically Every LLM call routed through AI Gateway becomes a spending event. Each event captures: - Input tokens, output tokens, and cached tokens. - Total cost (in microcents). - Request count. - The provider, model, user, and organization context the call ran under. No setup required: the gateway captures spending the moment your first agent runs through it. Agentic Data Plane tracks streaming and non-streaming requests the same way, and attributes cache-write tokens (Anthropic 4.x, OpenAI 4.x prompt caches) correctly on streaming responses, so cost rollups stay accurate when an agent reuses long system prompts. > 📝 **NOTE** > > Agentic Data Plane reports cost in **microcents**. 1 cent = 1,000,000 microcents, so $1 = 100,000,000 microcents. Divide `total_cost_microcents` by 100,000,000 to convert to dollars. ### [](#per-request-pricing-variations)Per-request pricing variations A few request- or response-time signals change the rate Agentic Data Plane applies to a single call. You don’t configure these; the spending pipeline picks them up from the upstream response or request and bills accordingly. - **Anthropic fast mode**: Anthropic exposes a fast-mode option on some models (for example, Opus 4.6 fast) that carries a per-token premium over the default rate. Agentic Data Plane reads the `speed` field on each Anthropic response and bills fast-mode calls at the model’s fast-mode rate. Requests without a `speed` field fall back to the default rate. - **Context-tier pricing**: A few models charge a different rate after a request crosses a context-length threshold. Gemini Pro, for example, prices requests above a 128K-token context at a higher tier than shorter requests. Agentic Data Plane uses the call’s context-token count so requests at or above the threshold bill at the tiered rate automatically. ## [](#where-to-view-your-spend)Where to view your spend You don’t view spend on the **Budgets** page. The **Cost & Usage** page, transcripts, and breakdown queries are the read surfaces: | Surface | Use it for | | --- | --- | | Cost & Usage page (Governance sidebar group) | Time-series spend, request, and token charts across providers and models. Use it to group by provider, model, or token type, then filter by provider, model, cost type, token type, user, or agent. See Analyze Cost and Usage. | | Transcripts | Per-call cost on individual executions. Useful when investigating a specific agent run or debugging a cost anomaly. See Read a transcript. | | Breakdown queries | Aggregated spend by provider, model, user, agent, or provider type, available through GetSpendingBreakdown for programmatic access. | Every breakdown and time-series query reads from the same `SpendingFilter` shape: a time range plus optional `provider_name`, `model_id`, `user_email`, `agent_name`, `agent_uid`, or `organization_id` filters. Combine filters to scope a query (for example, "all spend on Anthropic for user `alice` in April"). You can break results down by provider, model, user, agent, or provider type; `organization_id` is a filter only, not a breakdown dimension. For more expressive queries, `SpendingFilter` also accepts an AIP-160 `filter` expression that lets you combine and negate dimensions in a single string (for example, `provider_name="anthropic" AND model_id!="claude-sonnet-4-6"`). The convenience fields and the `filter` expression compose; populate one or both. `user_email` and `organization_id` are populated automatically from the request’s authenticated identity (the caller’s email and organization), so spend is attributed without any setup on your part. ## [](#query-spend-programmatically)Query spend programmatically `SpendingService.GetSpendingBreakdown` is the canonical RPC for pulling spend out of Agentic Data Plane. Use it for chargeback reporting, scheduled emails, internal cost dashboards, or any workflow the built-in UI doesn’t cover. ### [](#authenticate)Authenticate `SpendingService` uses the same OIDC client-credentials grant as the rest of AI Gateway. Mint a service-account access token using the flow in [Authenticate with OIDC client credentials](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/#authenticate-with-oidc-client-credentials), then pass the token in the `Authorization: Bearer ` header on every call. The service account needs `dataplane_adp_spending_get` on the resource you’re querying. See [Spending permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#spending-permissions). ### [](#request-shape)Request shape `GetSpendingBreakdown` takes a `SpendingFilter` plus a `dimension`. The filter accepts: | Field | Meaning | | --- | --- | | start_time, end_time | RFC 3339 timestamps bracketing the window. Required. | | provider_name | Restrict to one LLM provider (matches the Name field on the provider’s detail page). | | model_id | Restrict to one model identifier (claude-sonnet-4-6, gpt-5.2, and so on). | | user_email | Restrict to one identified user, matched on the caller’s email. Anonymous traffic is excluded. | | agent_name | Restrict to one agent by its resource name (agents/), recorded on every call made by or on behalf of an agent. Leave it empty to match every row, including direct user calls; set it to scope spend to a single agent, summed across every instance that has used the name. | | agent_uid | Restrict to one agent instance, identified by an opaque UUID. Only valid when agent_name is also set: setting agent_uid alone is rejected. Use it to exclude spend from a previously deleted agent that reused the same name. | | organization_id | Restrict to one organization. Multi-tenant deployments only. | | filter | AIP-160 expression that combines and negates dimensions in a single string (for example, provider_name="anthropic" AND model_id!="claude-sonnet-4-6"). Composes with the structured fields above; populate one or both. | The `dimension` value chooses the breakdown dimension. Valid values are the `BreakdownDimension` enum: `BREAKDOWN_DIMENSION_PROVIDER`, `BREAKDOWN_DIMENSION_MODEL`, `BREAKDOWN_DIMENSION_USER`, `BREAKDOWN_DIMENSION_AGENT`, `BREAKDOWN_DIMENSION_PROVIDER_TYPE`, and `BREAKDOWN_DIMENSION_TAG`. A breakdown on `BREAKDOWN_DIMENSION_AGENT` keys on the agent’s resource name (`agents/`) and excludes rows with no agent (direct user calls), the same way the other dimensions skip empty keys. Spend is summed across every instance that has used the name, so an agent that was deleted and recreated appears as a single entry. `BREAKDOWN_DIMENSION_TAG` groups spend by the value of a tag you set on your agents (for example, `department`) and takes an extra `tag_key` field. Use it to attribute cost to a department, team, or environment. See [Track Spend by Tag](https://docs.redpanda.com/agentic-data-plane/control/cost-allocation-tags/). ### [](#curl-example)cURL example Pull per-user spend for the last 7 days against an Anthropic provider: ```bash ACCESS_TOKEN="" # from the client_credentials flow DATAPLANE_BASE="https://aigw..clusters.rdpa.co" curl -s --request POST \ --url "${DATAPLANE_BASE}/redpanda.api.adp.v1alpha1.SpendingService/GetSpendingBreakdown" \ --header "Authorization: Bearer ${ACCESS_TOKEN}" \ --header 'Content-Type: application/json' \ --data '{ "filter": { "start_time": "2026-05-17T00:00:00Z", "end_time": "2026-05-24T00:00:00Z", "provider_name": "prod-anthropic" }, "dimension": "BREAKDOWN_DIMENSION_USER" }' | jq ``` The response carries one `entries` row per user in the window. Each entry has a `key` (the user) and a `stats` object with `total_cost_microcents`, `total_requests`, `total_tokens` (server-derived), and per-bucket `input`, `output`, and `cached` usage. Divide `total_cost_microcents` by 100,000,000 to convert to dollars. ### [](#python-example)Python example Generated client code lives in the proto bundle; if your project doesn’t already import it from cloudv2, drive `SpendingService` over plain HTTPS: ```python import os, requests from datetime import datetime, timedelta, timezone token = os.environ["ACCESS_TOKEN"] # from the client_credentials flow base = os.environ["DATAPLANE_BASE"] # https://aigw..clusters.rdpa.co end = datetime.now(timezone.utc) start = end - timedelta(days=7) body = { "filter": { "start_time": start.isoformat().replace("+00:00", "Z"), "end_time": end.isoformat().replace("+00:00", "Z"), "filter": 'provider_name="prod-anthropic"', }, "dimension": "BREAKDOWN_DIMENSION_USER", } r = requests.post( f"{base}/redpanda.api.adp.v1alpha1.SpendingService/GetSpendingBreakdown", headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"}, json=body, ) r.raise_for_status() for entry in r.json().get("entries", []): stats = entry["stats"] dollars = int(stats["total_cost_microcents"]) / 100_000_000 print(f"{entry['key']}: ${dollars:,.2f} ({stats['total_requests']} requests)") ``` The proto-generated client (Connect-Go or grpc-python) is the long-term recommendation; the cURL and `requests` examples are for quick scripting. ### [](#related-methods)Related methods `SpendingService` exposes additional methods that follow the same `SpendingFilter` shape: - `GetSpendingSummary`: Total spend, tokens, and requests for the range, with no breakdown. Also returns the previous comparable period so you can show a trend. - `GetSpendingTimeSeries`: Spend bucketed over the time range (hourly or daily), for chart-style consumers. - `GetSpendingTimeSeriesByDimension`: Time-series buckets split by a breakdown dimension (top-N keys by cost), for stacked charts. Reports `truncated_key_count` when more keys matched than were returned. ## [](#guardrail-cost)Guardrail cost AWS bills guardrail evaluation directly to the AWS account whose credentials the guardrail’s backend uses. This cost does not appear in Agentic Data Plane cost reporting and is not counted against budgets. For current rates, see [AWS Bedrock pricing](https://aws.amazon.com/bedrock/pricing/). For what each policy does, see [How guardrails work](https://docs.redpanda.com/agentic-data-plane/control/guardrails/overview/) and [Guardrail policy reference](https://docs.redpanda.com/agentic-data-plane/control/guardrails/types-reference/). ## [](#override-per-model-pricing)Override per-model pricing The Agentic Data Plane ships with default per-model pricing per provider, covering input, output, and cache-read prices for every model in the built-in catalog. Cost reporting uses these prices when it computes per-call spend, which is why every dollar value on the **Cost & Usage** page, in transcripts, and in `SpendingService` queries works without any setup. If your organization negotiates non-standard pricing, or you want to track spend against an internal chargeback rate, override the rates as part of configuring an LLM provider. Overrides are scoped to a single provider, where you edit the rate per model. See [Override per-model pricing](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/#pricing-overrides). ## [](#next-steps)Next steps - [Read a transcript](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/) - [How guardrails work](https://docs.redpanda.com/agentic-data-plane/control/guardrails/overview/) --- # Page 54: Track Spend by Tag **URL**: https://docs.redpanda.com/agentic-data-plane/control/cost-allocation-tags.md --- # Track Spend by Tag > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Track Spend by Tag latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: cost-allocation-tags page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: cost-allocation-tags.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/cost-allocation-tags.adoc description: Group and filter LLM spend by the tags you set on agents, so you can attribute cost to a department, team, or environment for chargeback and reporting. page-topic-type: how-to personas: platform_engineer, pilot_lead learning-objective-1: Tag agents so their LLM spend is attributed to a department, team, or environment learning-objective-2: Group and filter spend by tag in the Cost & Usage page learning-objective-3: Query spend by tag programmatically through SpendingService page-git-created-date: "2026-07-22" page-git-modified-date: "2026-07-30" --- Cost-allocation tags reuse the key/value tags you already set on an agent and give them a second job: grouping and filtering [LLM](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#large-language-model-llm) spend. Tag your agents with a dimension that matches how you report cost (for example, `department`, `team`, or `env`), and the Agentic Data Plane attributes every LLM call that agent makes to those tags. You can then break spend down by `department` on the **Cost & Usage** page, filter a report to `env=prod`, or pull per-team totals through the API for chargeback. You configure no separate tag registry and no spending pipeline. Tag an agent, and its spend is attributed automatically from the next call onward. After reading this page, you will be able to: - Tag agents so their LLM spend is attributed to a department, team, or environment - Group and filter spend by tag in the Cost & Usage page - Query spend by tag programmatically through SpendingService ## [](#prerequisites)Prerequisites - A running agent. If you do not have one, see [Agentic Data Plane Quickstart for Administrators](https://docs.redpanda.com/agentic-data-plane/get-started/adp-quickstart/). - To query spend through the API, a service account with the `dataplane_adp_spending_get` permission. See [Spending permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#spending-permissions). ## [](#how-tag-based-spend-tracking-works)How tag-based spend tracking works When an agent makes an LLM call through AI Gateway, the Agentic Data Plane records a spending event and stamps it with a snapshot of that agent’s tags at the time of the call. Cost reports then group and filter on those stamped tags. Three behaviors follow from this design: Attribution is point-in-time and immutable The tags recorded on a spending event are the agent’s tags at the moment of the call. Editing an agent’s tags later never rewrites past spend: historical rows keep the tags they were recorded with, and new spend picks up the new tags. A chargeback report for a closed period stays stable even after you retag agents. Tag changes take a short time to take effect After you create or retag an agent, its spend can briefly record under the old tags, or as untagged, until the change takes effect. Unattributable spend is grouped as **Untagged** Calls that carry no value for the tag key you group on collapse into a single **Untagged** bucket. This bucket covers direct user calls that do not run through an agent, calls from an agent that has no tags, and the brief window before a new agent’s tags take effect. ## [](#tag-your-agents-for-cost-tracking)Tag your agents for cost tracking Tags live on the agent. Set them when you create an agent or edit an existing one, either in the agent form (the **Tags** section) or through the `CreateAgent` and `UpdateAgent` methods. See [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/). A tag is a key/value pair. Choose keys that match your reporting dimensions and apply them consistently across agents: | Tag | Attributes spend to | | --- | --- | | department=sales | A business unit or cost center. | | team=revops | A team within a department. | | env=prod | An environment, to separate production spend from staging or development. | > ⚠️ **CAUTION** > > Do not put secrets or personally identifiable information (PII) in tag values. Tag values appear in cost reports and API responses. ## [](#track-spend-by-tag-in-the-ui)Track spend by tag in the UI Open **Cost & Usage** under **Governance** in the sidebar. For the page overview, see [Analyze Cost and Usage](https://docs.redpanda.com/agentic-data-plane/control/cost-usage/). Tags add two independent controls: Group by Tag Choose **Tag** as the group-by dimension, then pick a tag key, for example, `department`. Each chart series becomes one tag value, plus an **Untagged** series for spend with no value for that key. Use it to see how spend splits across departments or environments over the selected range. Tag filter Add a tag filter to scope the whole page to specific tag values, independent of what you group by. Selecting several values of the same key matches any of them (OR); selecting values across different keys requires all of them (AND). For example, filter to `department=sales` OR `department=support`, and `env=prod`, to see production spend for those two departments. The filter also applies to the CSV export, so an exported report matches what you see on screen. ## [](#query-spend-by-tag-with-the-api)Query spend by tag with the API The `SpendingService` API exposes tags as a breakdown dimension and a filter. These calls use the same authentication, `SpendingFilter` shape, and `dataplane_adp_spending_get` permission as the rest of the spending API. For authentication and the base request shape, see [Query spend programmatically](https://docs.redpanda.com/agentic-data-plane/control/budgets/#query-spend-programmatically). Reach the methods over the Connect protocol (POST and JSON) at `/redpanda.api.adp.v1alpha1.SpendingService/`. In this path, `` is your cluster’s AI Gateway base URL. Request fields use snake\_case (`start_time`, `tag_key`), and the JSON response uses camelCase (`totalCostMicrocents`, `totalRequests`). ### [](#group-a-breakdown-by-tag)Group a breakdown by tag The `GetSpendingBreakdown` and `GetSpendingTimeSeriesByDimension` methods accept `BREAKDOWN_DIMENSION_TAG` as the `dimension`, together with a `tag_key` that names the key to group on: | Field | Meaning | | --- | --- | | dimension | Set to BREAKDOWN_DIMENSION_TAG to group results by a tag value. | | tag_key | The tag key to group on, for example, department. Required when dimension is BREAKDOWN_DIMENSION_TAG, and ignored for any other dimension. A tag breakdown with an empty tag_key is rejected. | Each entry in the response keys on a tag value, with the same `stats` object (cost in microcents, request count, and token buckets) as the other breakdown dimensions. Spend with no value for the key is returned under the empty-string key, which the UI labels **Untagged**. ### [](#filter-any-query-by-tag)Filter any query by tag Every spending query reads a `SpendingFilter`, which accepts an [AIP-160](https://google.aip.dev/160) `filter` expression. Reference a tag with `tags.`, where `` is the tag key to match: ```none tags.department = "sales" tags.department = "sales" AND tags.env = "prod" ``` Tag predicates compose with the structured `SpendingFilter` fields, such as `provider_name`, `model_id`, `user_email`, and `agent_name`, so you can scope a per-user breakdown to one department. ### [](#curl-example)cURL example Break down the last seven days of spend by `department`: ```bash ACCESS_TOKEN="" # from the client_credentials flow DATAPLANE_BASE="https://aigw..clusters.rdpa.co" curl -s --request POST \ --url "${DATAPLANE_BASE}/redpanda.api.adp.v1alpha1.SpendingService/GetSpendingBreakdown" \ --header "Authorization: Bearer ${ACCESS_TOKEN}" \ --header 'Content-Type: application/json' \ --data '{ "filter": { "start_time": "2026-05-17T00:00:00Z", "end_time": "2026-05-24T00:00:00Z" }, "dimension": "BREAKDOWN_DIMENSION_TAG", "tag_key": "department" }' | jq ``` In this URL, `` is your cluster’s ID, and `` is a token from the client-credentials flow. The response carries one `entries` row per `department` value in the window, plus a row for untagged spend whose `key` is the empty string (omitted from the JSON). Each row has a `key`, the tag value, and a `stats` object whose fields use camelCase JSON names, such as `totalCostMicrocents` and `totalRequests`, plus per-bucket token usage. Divide `totalCostMicrocents` by 100,000,000 to convert to dollars. ## [](#limits-and-constraints)Limits and constraints | Constraint | Value | | --- | --- | | Tags per agent | At most 50 key/value pairs per agent. | | Tag value length | At most 256 characters per value. | | Distinct tag keys | No fixed limit. The keys available for grouping are whatever keys exist across agents that have recorded spend in the selected window. | | Untagged spend | Spend with no value for the grouped key (direct user calls, untagged agents, and spend recorded before an agent’s tags take effect) is grouped under a single Untagged bucket. | ## [](#troubleshooting)Troubleshooting Spend you expect under a tag shows as **Untagged** The agent had no tags when it made the call, or you tagged or retagged it moments earlier and the change had not taken effect yet. Recheck after a short wait. Direct user calls that do not run through an agent are always untagged. Editing an agent’s tags did not change past reports Attribution is point-in-time by design. Only spend recorded after the edit picks up the new tags; historical spend keeps the tags it was recorded with. ## [](#next-steps)Next steps - [Set Up Budgets](https://docs.redpanda.com/agentic-data-plane/control/budgets/) - [Analyze Cost and Usage](https://docs.redpanda.com/agentic-data-plane/control/cost-usage/) - [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) --- # Page 55: Analyze Cost and Usage **URL**: https://docs.redpanda.com/agentic-data-plane/control/cost-usage.md --- # Analyze Cost and Usage > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Analyze Cost and Usage latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: cost-usage page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: cost-usage.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/cost-usage.adoc description: Break down LLM spend, requests, and tokens by provider, model, token type, agent, user, or tag. Compare periods, export CSV reports, and see which agents are active right now. page-topic-type: how-to personas: platform_engineer, pilot_lead learning-objective-1: Break down spend, requests, and tokens by provider, model, token type, agent, user, or tag learning-objective-2: Turn on period comparisons and export the data as CSV learning-objective-3: Identify the agents active right now and open their recent conversations page-git-created-date: "2026-07-30" page-git-modified-date: "2026-08-07" --- The **Cost & Usage** page is the spending and usage report for your Agentic Data Plane: every [LLM](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#large-language-model-llm) call the gateway routes is recorded, priced, and charted here. Use it to see where spend comes from, attribute it to a provider, model, agent, user, or tag, and export the numbers for reporting. After reading this page, you will be able to: - Break down spend, requests, and tokens by provider, model, token type, agent, user, or tag - Turn on period comparisons and export the data as CSV - Identify the agents active right now and open their recent conversations ## [](#prerequisites)Prerequisites This page assumes traffic through at least one [LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/); with no traffic, the charts are empty. > 📝 **NOTE** > > Dollar values come from per-model pricing: the built-in catalog rates, or the overrides you set on a provider. Cost reporting works without any pricing setup. See [Override per-model pricing](https://docs.redpanda.com/agentic-data-plane/control/budgets/#override-per-model-pricing). ## [](#open-the-report)Open the report Open **Cost & Usage** under **Governance** in the sidebar. The page has two tabs: - **Cost & usage**: The spending report. Charts of spend, requests, and tokens over a time window, with grouping, filters, and CSV export. - **Activity**: The live view. The agents active right now, with a drill-down into their recent conversations. ## [](#choose-the-time-window)Choose the time window The date-range picker offers last 24 hours, last 7 days (the default), last 14 days, last 30 days, last 90 days, month to date, quarter to date, year to date, and custom ranges. The chart subtitle shows the selected date range and bucket size. A custom range writes `customStart` and `customEnd` ISO-8601 timestamps to the page URL, so the view is shareable: copy the URL after picking a custom range and any teammate who opens it lands on the same window. To compare against the period before, turn on the **Compare to previous period** switch in the date-range picker. The picker shows which previous window the report compares against, and each series in the report compares against its own numbers from that period. ## [](#break-down-and-filter)Break down and filter Use **Group by** to switch the chart breakdown between providers, models, token type, agents, users, and tags: - Group by provider to see which upstream consumed the most budget. - Group by model to see which model drove spend inside one or more providers. - Group by token type to separate input, output, cached, cache-write, and reasoning usage where those buckets apply. - Group by agent or user to attribute spend to the agent or the identified caller that drove it. - Group by a tag key to attribute spend to a dimension you define, such as `department` or `env`. Tag grouping picks the key from a submenu, and the control shows the active key, for example `Tag: department`. See [Track Spend by Tag](https://docs.redpanda.com/agentic-data-plane/control/cost-allocation-tags/). Each dimension, Provider, Model, Cost type, Token type, User, and Agent, has its own filter button above the charts, and you can combine them freely. For example, filter to one Anthropic provider, drill into `claude-opus-4-7`, then limit the spend view to input tokens. Selecting an agent also narrows the provider options to the providers that agent used. The tag filter is independent of grouping, so you can group by model while filtering to `env=prod`. Deleted providers stay in the report so history remains complete. Turn off **Show deleted providers** to hide them; when everything that matches your filters is from deleted providers, the chart says so instead of rendering blank. ## [](#read-the-charts)Read the charts The report includes these charts: - Spend over time: Estimated spend in USD for the selected range. - Requests over time: Request count for the selected range. - Tokens over time: Token count for the selected range. The chart renders empty buckets in the selected range as zero-height bars rather than gaps, so quiet days line up with their date label and the trend stays readable when traffic is bursty. The chart palette is colorblind-safe. When multiple providers of the same type exist (for example, two OpenAI providers), the chart renders each one with a distinct hatched pattern so the series stay visually distinguishable. The spend chart footer summarizes the selected view by cost bucket, including total, input, output, cached, cache writes, and reasoning when the selected traffic includes those categories. Each chart can be maximized for a closer look, and exported on its own: the chart export downloads the data as currently shown, including any truncation the chart applies to keep the top series readable. ## [](#download-cost-and-usage-report)Download the report as CSV To export the data behind the charts, use the download controls in the toolbar: - Click **Download full report** to download the complete, untruncated dataset for the current filters and date range as a CSV file. Every cost type and token type is a separate column. - Next to **Download full report**, open the report-grouping options to choose how the exported rows are grouped. Under Time bucket, pick Hourly, Daily, Monthly, or Total (no time column). Under Break down by, select any combination of Provider, Model, User, and Agent. Use **Download full report** when you need the whole dataset rather than the charted view. ## [](#see-which-agents-are-active-now)See which agents are active now The **Activity** tab answers a different question from the report: instead of what something cost, it shows what’s running right now. It ranks the agents with traffic over a window of the last hour (the default), the last 24 hours, or the last 7 days, and shows each agent’s change against the previous window. Select an agent to see its recent requests and open a conversation. The Playground’s live view also hands off to this tab: when an agent task is still running after several minutes, the Playground points you here to follow it to completion. ## [](#next-steps)Next steps - [Set Up Budgets](https://docs.redpanda.com/agentic-data-plane/control/budgets/) - [Track Spend by Tag](https://docs.redpanda.com/agentic-data-plane/control/cost-allocation-tags/) - [See What Your Agent Did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/) --- # Page 56: Set Up Guardrails **URL**: https://docs.redpanda.com/agentic-data-plane/control/guardrails.md --- # Set Up Guardrails > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Set Up Guardrails latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: guardrails/index page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: guardrails/index.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/guardrails/index.adoc description: Understand how guardrails work, create them, review blocked requests, and look up the available policies. page-git-created-date: "2026-06-01" page-git-modified-date: "2026-07-08" --- Guardrails inspect and control the requests and responses that flow through your AWS Bedrock LLM providers. Learn how they work, create one, review blocked requests, and look up the available policies. - [How Guardrails Work](overview/) Learn how Agentic Data Plane guardrails use AWS Bedrock policies to inspect and control LLM requests and responses, and how a blocked request surfaces. - [Create a Guardrail](create-guardrail/) Create a guardrail with the wizard, configure its Bedrock authentication and policies, attach it to a Bedrock LLM provider, and verify that it blocks. - [Review Blocked Requests](violations/) Understand how a blocked request surfaces, where guardrail activity is recorded, and what to check when a guardrail blocks too much or too little. - [Guardrail Policy Reference](types-reference/) Reference for the guardrail policy types, their configuration fields, actions, directions, and limits. --- # Page 57: Create a Guardrail **URL**: https://docs.redpanda.com/agentic-data-plane/control/guardrails/create-guardrail.md --- # Create a Guardrail > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Create a Guardrail latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: guardrails/create-guardrail page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: guardrails/create-guardrail.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/guardrails/create-guardrail.adoc description: Create a guardrail with the wizard, configure its Bedrock authentication and policies, attach it to a Bedrock LLM provider, and verify that it blocks. page-topic-type: how-to personas: security_compliance_lead, platform_engineer learning-objective-1: Create a guardrail and configure its backend and policies learning-objective-2: Attach the guardrail to an LLM provider and enable it learning-objective-3: Verify the guardrail blocks a request and trace it through the transcript page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-08" --- Create a guardrail to inspect and control the requests and responses that flow through an AWS Bedrock LLM provider. You configure the guardrail in a wizard (details, authentication, and policies), attach it to a Bedrock provider, and confirm it blocks. After reading this page, you will be able to: - Create a guardrail and configure its backend and policies - Attach the guardrail to an LLM provider and enable it - Verify the guardrail blocks a request and trace it through the transcript ## [](#prerequisites)Prerequisites - An AWS region and Bedrock access. A guardrail reconciles against the AWS Bedrock control plane, so you need either AWS credentials it can use or a Bedrock LLM provider whose credentials it can borrow. - At least one AWS Bedrock LLM provider to attach the guardrail to. Guardrails attach to Bedrock providers only. See [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/). - For the Sensitive information, Content filters, Contextual grounding, and Automated reasoning policies, confirm the features you need are available in your chosen Bedrock region. ## [](#add-the-details)Add the details Open the wizard and give the guardrail its name and the messages that callers see when a policy blocks a request. 1. Open **Guardrails** in the sidebar and click **Create guardrail**. 2. On the Details step, set the following: | Field | Notes | | --- | --- | | Name | Required. Lowercase letters, numbers, and hyphens only, 1 to 63 characters. Used in the resource path and can’t be changed after creation. | | Display Name | Optional. A friendlier name shown in the list and detail views. | | Description | Optional. | | Blocked Input Message | Required. The message returned to the caller when a policy blocks a prompt. 1 to 500 characters. | | Blocked Output Message | Required. The message returned instead of the model’s response when a policy blocks it. 1 to 500 characters. | | Enabled | Leave off for now. Enable the guardrail after you configure its policies. | 3. Click **Next**. ## [](#configure-authentication)Configure authentication This step, labeled **Authentication** in the wizard, sets the AWS region and credentials the guardrail uses to reach Bedrock. 1. Select a region. The region decides which Bedrock models and guardrail features you can reach, because not every feature is available in every region. Use the same region as the Bedrock provider or model you intend to protect. 2. Choose a credential source: - Standalone AWS credentials: Supply credentials for this guardrail directly. - Borrow from a Bedrock provider: Reuse the credentials of a Bedrock LLM provider you already configured. 3. If you chose standalone credentials, choose a credential type: - Default provider chain: Use the credentials available in the runtime environment. - Static access keys: Supply an access key ID and secret access key, each stored as a secret reference in the Agentic Data Plane secret store. - Assume IAM role: Supply a role ARN, with an optional external ID and session name. 4. Click **Next**. ## [](#turn-on-policies)Turn on policies Each policy is optional, but a guardrail must enforce at least one. Turn on the policies you need, then configure each. For the full configuration of every policy, see [Guardrail policy reference](https://docs.redpanda.com/agentic-data-plane/control/guardrails/types-reference/). ### [](#start-from-a-preset)Start from a preset The Quick start row at the top of the Policies step applies a preset, a bundle of policy settings for a common goal: - **Content safety**: Blocks hate speech, insults, sexual content, violence, and misconduct at high strength. - **PII protection**: Masks emails, phone numbers, names, addresses, card numbers, and US Social Security numbers. - **Prompt attack defense**: Blocks jailbreak and prompt-injection attempts before they reach the model. Presets are additive: applying one never removes rules you already configured. Apply a preset, then adjust the individual policies it turned on. ### [](#choose-individual-policies)Choose individual policies Turn on each policy you need and configure its rules: - Content filters: Harmful-content categories (hate, insults, sexual, violence, misconduct, and prompt attacks). - Word filters: Exact words and phrases from your own lists and platform-managed lists such as profanity. - Denied topics: Topics blocked by meaning rather than exact words. - Sensitive information: PII detected by built-in entity types and your own regex patterns, then detected, blocked, or anonymized. - Contextual grounding: Factual grounding and relevance checks for RAG-style output. Output only. - Automated reasoning: Formal Bedrock Automated Reasoning policies. Detect only. Each policy you turn on exposes a separate **Evaluate this policy** toggle. Turn it off to save the policy’s configuration without enforcing it, which lets you stage a policy before it takes effect. > 📝 **NOTE** > > Two separate toggles control evaluation: > > - The guardrail-level **Enabled** toggle, on the Details step, turns the whole guardrail on or off. A disabled guardrail keeps its configuration but evaluates no traffic. > > - The policy-level **Evaluate this policy** toggle controls a single policy within the guardrail. A policy with this toggle off is saved but not evaluated. > > > A policy acts on traffic only when its guardrail is enabled and its own **Evaluate this policy** toggle is on. A policy you turn on needs at least one rule. Agentic Data Plane rejects a guardrail that has no policy turned on, or that turns on a policy with no rules set, such as a content-filter policy with no category configured or a contextual-grounding policy with neither grounding nor relevance enabled. A staged policy does not count toward this minimum, because a policy with its **Evaluate this policy** toggle off is not enforced. A guardrail needs at least one policy that is both turned on and evaluated, so if you stage every policy, Agentic Data Plane rejects the guardrail. When you finish, click **Create guardrail**. ## [](#attach-the-guardrail-to-a-provider)Attach the guardrail to a provider A guardrail takes effect only after a provider references it. On an AWS Bedrock LLM provider, set the guardrail field in the provider’s Bedrock settings to the one you created. Only Bedrock providers expose this setting. A provider references one guardrail, and you can reuse the same guardrail across many providers. See [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/). ## [](#enable-the-guardrail)Enable the guardrail After you configure the policies and attach the guardrail, set the guardrail to enabled. A disabled guardrail keeps its configuration but skips evaluation entirely, which is useful while you stage a policy or troubleshoot whether the guardrail is responsible for unexpected blocks. Enabling or disabling a guardrail takes effect within about 30 seconds, because the gateway briefly caches guardrail settings. ## [](#verify-the-guardrail-blocks)Verify the guardrail blocks Send a request through an attached provider that violates a policy. For example, with the sensitive-information policy set to block on input, send a prompt that contains an email address or other PII. The request returns your blocked input message instead of a model response. Open the request’s [transcript](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#transcript) and confirm the guardrail recorded its action. See [See what your agent did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/) for the transcript walkthrough and [Review blocked requests](https://docs.redpanda.com/agentic-data-plane/control/guardrails/violations/) for how blocked requests surface. ## [](#edit-disable-or-delete-a-guardrail)Edit, disable, or delete a guardrail From the guardrails list or a guardrail’s detail page: - Edit the guardrail to change its backend or policies. Changes take effect within about 30 seconds, because the gateway briefly caches guardrail settings. - Disable the guardrail to stop evaluation without losing its configuration. - Delete the guardrail to remove it permanently. Deletion asks you to confirm by typing the guardrail’s name. > ❗ **IMPORTANT** > > You cannot delete a guardrail while an LLM provider still references it. Agentic Data Plane blocks the delete and names the providers you must detach first. Open each listed provider, clear its `Guardrail` field, then delete the guardrail. This protects in-flight traffic: if the guardrail were removed while a provider still pointed at it, every request through that provider would fail. ## [](#next-steps)Next steps - [Guardrail policy reference](https://docs.redpanda.com/agentic-data-plane/control/guardrails/types-reference/) - [Review blocked requests](https://docs.redpanda.com/agentic-data-plane/control/guardrails/violations/) - [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/) --- # Page 58: How Guardrails Work **URL**: https://docs.redpanda.com/agentic-data-plane/control/guardrails/overview.md --- # How Guardrails Work > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: How Guardrails Work latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: guardrails/overview page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: guardrails/overview.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/guardrails/overview.adoc description: Learn how Agentic Data Plane guardrails use AWS Bedrock policies to inspect and control LLM requests and responses, and how a blocked request surfaces. page-topic-type: overview personas: security_compliance_lead, platform_engineer, agent_builder learning-objective-1: Describe what a guardrail does and how you attach one to an AWS Bedrock LLM provider learning-objective-2: Identify the available policy types and the situations each fits learning-objective-3: Recognize how a blocked request surfaces and which page to read next page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-10" --- A guardrail is a set of safety and policy filters that inspect and control how agents and gateways use models. A guardrail can block prompt injection, deny off-topic content, redact or block personally identifiable information (PII), and check responses for factual grounding. You attach a guardrail to an AWS Bedrock LLM provider, and Agentic Data Plane applies it to every request and response that flows through that provider. Agentic Data Plane guardrails run on AWS Bedrock Guardrails. Each guardrail syncs its policy configuration to the Bedrock control plane, so it needs an AWS region and Bedrock credentials. Guardrails attach to AWS Bedrock providers only; other provider types don’t expose a guardrail setting. After reading this page, you will be able to: - Describe what a guardrail does and how you attach one to an AWS Bedrock LLM provider - Identify the available policy types and the situations each fits - Recognize how a blocked request surfaces and which page to read next ## [](#policy-types)Policy types A guardrail bundles a set of policies. Each is optional, but a guardrail must enforce at least one. Turn on the ones you need. | Policy | What it does | | --- | --- | | Content filters | Classify prompts and responses against harmful-content categories: hate, insults, sexual, violence, misconduct, and prompt attacks. Prompt-attack detection applies to input only. | | Word filters | Block or detect exact words and phrases, using your own lists and platform-managed lists such as profanity. | | Denied topics | Block content by meaning rather than exact words, so it catches paraphrases and misspellings. | | Sensitive information | Detect PII using built-in entity types and your own regex patterns, then detect, block, or anonymize it. | | Contextual grounding | For RAG-style applications, check model output for factual grounding against a source and relevance to the query. Output only. | | Automated reasoning | Mathematically verify model output against formal Bedrock Automated Reasoning policies. Detect only: it never blocks, and findings appear in the trace. | For each policy’s full configuration, see [Guardrail policy reference](https://docs.redpanda.com/agentic-data-plane/control/guardrails/types-reference/). ## [](#where-a-guardrail-runs)Where a guardrail runs A guardrail evaluates both sides of an LLM call: - Input: Agentic Data Plane evaluates the prompt before forwarding it upstream. Use input evaluation to stop sensitive or malicious content from reaching the model. - Output: Agentic Data Plane evaluates the model’s response before returning it to the caller. Use output evaluation to control what the model generates. Some policies are direction-specific. Content-filter prompt-attack detection runs on input only, contextual grounding runs on output only, and automated reasoning runs on output and only reports findings. For streaming responses, Agentic Data Plane skips output evaluation in this release. Input evaluation still applies. ![Guardrail evaluation flow. A caller’s prompt passes through input policies before the Bedrock model. Allowed prompts reach the model; blocked prompts return the configured blocked-input message. For non-streaming calls, model output passes through output policies before an allowed, redacted, or blocked response reaches the caller.](https://docs.redpanda.com/agentic-data-plane/control/_images/guardrail-evaluation-flow.svg) Figure 1. A guardrail can stop a request before the model or control the response after it ## [](#where-you-attach-a-guardrail)Where you attach a guardrail You attach a guardrail by setting an AWS Bedrock LLM provider’s guardrail. The guardrail setting appears in the provider’s Bedrock settings, and only Bedrock providers can reference a guardrail. Each provider references at most one guardrail, and a single guardrail can be reused across many providers. The guardrail’s detail page lists the providers that use it. You create and configure the guardrail first, then attach it from the provider. See [Create a guardrail](https://docs.redpanda.com/agentic-data-plane/control/guardrails/create-guardrail/). Agentic Data Plane enforces this reference in both directions. A provider can only point at a guardrail that exists, and you cannot delete a guardrail while a provider still references it. To remove a guardrail that is in use, detach it from each provider first. ## [](#what-happens-when-a-guardrail-blocks)What happens when a guardrail blocks When a policy blocks an input, Agentic Data Plane stops the request and returns your configured blocked input message to the caller. When a policy blocks an output, Agentic Data Plane returns your configured blocked output message instead of the model’s response. The sensitive-information policy can also anonymize matched PII in place rather than block, replacing each match with its entity type, such as `{EMAIL}`. The two directions differ: on output, Agentic Data Plane delivers the redacted response to the caller. On input, Agentic Data Plane does not forward the redacted prompt to the model. Agentic Data Plane short-circuits the request like a block and returns your configured blocked input message. Agentic Data Plane records guardrail activity as attributes on the request’s OpenTelemetry trace, which you read in [transcripts](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#transcript). This release does not include a separate violations dashboard. See [Review blocked requests](https://docs.redpanda.com/agentic-data-plane/control/guardrails/violations/) for how a blocked request surfaces. ## [](#next-steps)Next steps - [Create a guardrail](https://docs.redpanda.com/agentic-data-plane/control/guardrails/create-guardrail/) - [Guardrail policy reference](https://docs.redpanda.com/agentic-data-plane/control/guardrails/types-reference/) - [Review blocked requests](https://docs.redpanda.com/agentic-data-plane/control/guardrails/violations/) --- # Page 59: Guardrail Policy Reference **URL**: https://docs.redpanda.com/agentic-data-plane/control/guardrails/types-reference.md --- # Guardrail Policy Reference > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Guardrail Policy Reference latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: guardrails/types-reference page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: guardrails/types-reference.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/guardrails/types-reference.adoc description: Reference for the guardrail policy types, their configuration fields, actions, directions, and limits. page-topic-type: reference personas: security_compliance_lead, platform_engineer page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-08" --- A guardrail bundles a set of policies, each backed by AWS Bedrock Guardrails. Each policy is optional, but a guardrail must enforce at least one. This page documents each policy type’s configuration fields, available actions, direction settings, and regional availability. ## [](#common-settings)Common settings Two settings recur across policies: - Action: what the policy does when it matches. `None` detects and records the match in the trace without intervening. `Block` stops the request and returns the configured blocked message. The sensitive-information policy adds `Anonymize`. - Direction: most policies evaluate input, output, or both, and you set the action per direction. Some policies are fixed to one direction (noted below). > 📝 **NOTE** > > Feature availability varies by AWS region. Choose a region that supports the policies you need, and see the [AWS Bedrock Guardrails documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) for exhaustive behavior and regional support. ## [](#content-filters)Content filters Classify prompts and responses against harmful-content categories and block or detect them per category. | Field | Description | | --- | --- | | Categories | Hate, Insults, Sexual, Violence, Misconduct, and Prompt attack. Configure each category independently. Prompt-attack detection evaluates input only. | | Strength | Per category and direction. Sets the confidence cutoff for a match: None scores the category in the trace without acting, Low matches only high-confidence content, Medium matches medium-confidence and above, and High matches any non-negligible content. Higher strength is stricter. | | Action | Per category and direction: None (detect) or Block. | | Modality | Text or Image. | ## [](#word-filters)Word filters Block or detect exact words and phrases. | Field | Description | | --- | --- | | Custom words | Your own list of words and phrases to match. | | Managed lists | Platform-managed lists. Profanity is available today. | | Action | Per direction (input and output): None (detect) or Block. Set independently for custom words and for each managed list. | ## [](#denied-topics)Denied topics Block content by meaning rather than exact words, so the policy catches paraphrases and misspellings. A policy holds up to 30 topics. | Field | Description | | --- | --- | | Name | Topic name, 1 to 100 characters. | | Definition | What the topic covers, up to 1000 characters. The definition drives the semantic match, so write it as a clear, self-contained statement. Keep example phrases and negations out of the definition; put concrete examples in the Examples field instead, which improves accuracy. | | Examples | Up to five example phrases, each up to 100 characters, that match the topic. | | Action | Per direction (input and output): None (detect) or Block. | ## [](#sensitive-information)Sensitive information Detect personally identifiable information (PII) by built-in entity type or by your own regular expressions, then detect, block, or anonymize it. | Field | Description | | --- | --- | | Entities | Built-in entity types. Each entity has a per-direction action. | | Regexes | Custom patterns. Each rule has a name (1 to 100 characters), an RE2 pattern (1 to 500 characters; lookaround is not supported), an optional description, and a per-direction action. | | Action | Per direction (input and output): None (detect), Block, or Anonymize. Anonymize replaces each match in place with its entity type, such as {EMAIL}, and applies to text only. The two directions differ: on output, Agentic Data Plane delivers the redacted response to the caller. On input, this release does not forward the redacted prompt to the model. Instead, an anonymize match short-circuits the request like a block: the model is never called, and Agentic Data Plane returns your configured blocked input message rather than the redacted prompt. Block replaces the whole payload with the blocked message. | The built-in entity types are: `ADDRESS`, `AGE`, `NAME`, `EMAIL`, `PHONE`, `USERNAME`, `PASSWORD`, `DRIVER_ID`, `LICENSE_PLATE`, `VEHICLE_IDENTIFICATION_NUMBER`, `CREDIT_DEBIT_CARD_CVV`, `CREDIT_DEBIT_CARD_EXPIRY`, `CREDIT_DEBIT_CARD_NUMBER`, `PIN`, `INTERNATIONAL_BANK_ACCOUNT_NUMBER`, `SWIFT_CODE`, `IP_ADDRESS`, `MAC_ADDRESS`, `URL`, `AWS_ACCESS_KEY`, `AWS_SECRET_KEY`, `US_BANK_ACCOUNT_NUMBER`, `US_BANK_ROUTING_NUMBER`, `US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER`, `US_PASSPORT_NUMBER`, `US_SOCIAL_SECURITY_NUMBER`, `CA_HEALTH_NUMBER`, `CA_SOCIAL_INSURANCE_NUMBER`, `UK_NATIONAL_HEALTH_SERVICE_NUMBER`, `UK_NATIONAL_INSURANCE_NUMBER`, and `UK_UNIQUE_TAXPAYER_REFERENCE_NUMBER`. ## [](#contextual-grounding)Contextual grounding For retrieval-augmented generation (RAG) applications, check model output against a source and the user’s query. This policy evaluates output only and has two independent sub-filters. | Sub-filter | Description | | --- | --- | | Grounding | Checks that the response is factually grounded in the provided source. | | Relevance | Checks that the response is relevant to the user’s query. | Each sub-filter has its own enable toggle, a threshold between `0.0` and `0.99`, and an action. The action fires when the response scores below the threshold, so higher thresholds are stricter. The action is `None` (detect) or `Block`. ## [](#automated-reasoning)Automated reasoning Mathematically verify model output against formal Bedrock Automated Reasoning policies. This policy is detect-only: it never blocks, and its findings appear in the trace. | Field | Description | | --- | --- | | Policy ARNs | One or two Bedrock Automated Reasoning policy Amazon Resource Names (ARNs) to attach. Each ARN must point at a specific numeric version (for example, ending in :1 or :2); the DRAFT version is rejected. Create and publish the policies in the AWS Bedrock console first, then reference their versioned ARNs here. | | Confidence threshold | A value between 0.0 and 1.0. Below this confidence, a finding is reported as non-definitive. | ## [](#next-steps)Next steps - [Create a guardrail](https://docs.redpanda.com/agentic-data-plane/control/guardrails/create-guardrail/) - [Review blocked requests](https://docs.redpanda.com/agentic-data-plane/control/guardrails/violations/) - [How guardrails work](https://docs.redpanda.com/agentic-data-plane/control/guardrails/overview/) --- # Page 60: Review Blocked Requests **URL**: https://docs.redpanda.com/agentic-data-plane/control/guardrails/violations.md --- # Review Blocked Requests > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Review Blocked Requests latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: guardrails/violations page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: guardrails/violations.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/guardrails/violations.adoc description: Understand how a blocked request surfaces, where guardrail activity is recorded, and what to check when a guardrail blocks too much or too little. page-topic-type: how-to personas: security_compliance_lead, platform_engineer, agent_builder learning-objective-1: Review what a caller sees when a guardrail blocks a request learning-objective-2: Find guardrail activity in a request's transcript learning-objective-3: Diagnose a guardrail that blocks too much or doesn't fire page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-30" --- When a guardrail acts on a request, the caller sees a blocked message and Agentic Data Plane records the action on the request’s trace. This release does not include a dedicated violations dashboard, so you review blocked requests through [transcripts](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#transcript). After reading this page, you will be able to: - Review what a caller sees when a guardrail blocks a request - Find guardrail activity in a request’s transcript - Diagnose a guardrail that blocks too much or doesn’t fire ## [](#what-the-caller-sees)What the caller sees - Blocked input: Agentic Data Plane stops the request before it reaches the model and returns your configured blocked input message. - Blocked output: Agentic Data Plane returns your configured blocked output message instead of the model’s response. - Anonymized PII: When the sensitive-information policy anonymizes a match on output, Agentic Data Plane delivers the response with each match replaced in place by its entity type, such as `{EMAIL}`. On input, this release does not forward the redacted prompt to the model: Agentic Data Plane short-circuits the request like a block and returns your configured blocked input message, not the redacted prompt. Automated reasoning never blocks. It records findings on the trace for your application to act on. ## [](#where-guardrail-activity-is-recorded)Where guardrail activity is recorded Agentic Data Plane records guardrail activity as attributes on the request’s OpenTelemetry trace, which you read in the request’s transcript alongside the LLM call, tool calls, and cost data. See [See what your agent did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/). For streaming responses, Agentic Data Plane skips output evaluation and marks the skip on the trace. Input evaluation still applies to streaming requests. ## [](#troubleshoot-guardrail-behavior)Troubleshoot guardrail behavior When a guardrail blocks legitimate traffic or fails to act when you expect it to, work through the checks in this section to find the cause. ### [](#a-guardrail-blocks-too-much)A guardrail blocks too much If a guardrail blocks legitimate traffic: - Content filters: Lower the strength for the affected category, or set its action to detect while you tune. - Sensitive information: Narrow the entity types or regex patterns to the data you actually care about. Structured payloads such as code or JSON can contain strings that resemble PII. - Denied topics: Tighten each topic’s definition and examples so the semantic match is more specific. - Contextual grounding: Lower the threshold so only clearly ungrounded or irrelevant responses are caught. To stage a change without enforcing it, set the policy’s action to detect and review the results on the trace before you block. For contextual grounding, you can also turn off a filter’s **Evaluate this check** switch to skip evaluating it entirely. ### [](#a-guardrail-doesnt-fire)A guardrail doesn’t fire If you expect a guardrail to act and it doesn’t: - Confirm the guardrail is enabled. A disabled guardrail keeps its configuration but skips evaluation. - Confirm the specific policy is enabled. The guardrail’s detail page shows each policy’s **Enabled** or **Disabled** status; a disabled policy takes no action. For contextual grounding, also confirm the filter’s **Evaluate this check** switch is on. - Confirm the Bedrock provider the request used references this guardrail. A guardrail acts only on providers that reference it. - Confirm the direction. An output-only policy such as contextual grounding never acts on input, and output policies are skipped for streaming responses. - Confirm the request actually went through the Bedrock provider. Direct-to-provider requests that bypass Agentic Data Plane are not evaluated. ## [](#next-steps)Next steps - [See what your agent did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/) - [Guardrail policy reference](https://docs.redpanda.com/agentic-data-plane/control/guardrails/types-reference/) - [Create a guardrail](https://docs.redpanda.com/agentic-data-plane/control/guardrails/create-guardrail/) --- # Page 61: Control Who Can Do What **URL**: https://docs.redpanda.com/agentic-data-plane/control/permissions-overview.md --- # Control Who Can Do What > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Control Who Can Do What latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: permissions-overview page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: permissions-overview.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/permissions-overview.adoc description: "Understand how Agentic Data Plane decides who can do what: access policies carry the decision, and RBAC bootstraps the administrators who author them." page-topic-type: concept personas: security_compliance_lead, platform_engineer learning-objective-1: Explain how access policies decide who can do what in Agentic Data Plane learning-objective-2: Explain why Admin is the only built-in role that reaches Agentic Data Plane learning-objective-3: Grant a user, a group, or a service account the access it needs page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-07" --- Redpanda Agentic Data Plane decides who can do what with [access policies](https://docs.redpanda.com/agentic-data-plane/control/access-policies/). A policy names a principal, an action, and a resource, and either permits or forbids. That’s the authorization model: policies are what you write, and policy evaluation is what every API call resolves against. Role-based access control (RBAC) has one job here. Assign the Admin role to the people who administer the deployment, and they author the policies that grant everyone else. Admin is the only built-in role that carries Agentic Data Plane permissions at all. This page explains how the two fit together and how to grant access to a user, a group, or a service account. After reading this page, you will be able to: - Explain how access policies decide who can do what in Agentic Data Plane - Explain why Admin is the only built-in role that reaches Agentic Data Plane - Grant a user, a group, or a service account the access it needs ## [](#policies-decide-roles-bootstrap)Policies decide, roles bootstrap Every Agentic Data Plane request resolves the same way: - A request is denied unless a `permit` matches it. - A matching `forbid` always wins, over any `permit` and over anything a role granted. Both role bindings and access policies feed that one evaluation. Redpanda compiles your role bindings into permits automatically, so an Admin’s access arrives through the same path as a policy you wrote. There is no separate RBAC check that runs first and no second system to reason about. The division of labor: - **Access policies** express the decision. A policy takes a user or an identity provider group as its principal, conditions on resource tags and ownership, narrows to a single resource, and denies. Policies are how you grant access. - **RBAC** bootstraps and administers. It gets your first administrators in, and it is deliberately coarse: Admin, or nothing. RBAC is not the mechanism for granting day-to-day access in Agentic Data Plane. When you need to express something, express it as a policy. > 📝 **NOTE** > > Access policies are a preview capability, enabled per organization. Until they’re enabled for yours, an Admin binding or a custom role is the only way to reach an Agentic Data Plane API. See [Manage Access Policies](https://docs.redpanda.com/agentic-data-plane/control/access-policies/). > ❗ **IMPORTANT** > > Admin grants every Agentic Data Plane permission on every resource, so it is not a least-privilege answer for day-to-day users. Bind Admin to the people who administer the deployment. Grant everything else with a policy. ## [](#admin-is-the-only-built-in-role-that-reaches-agentic-data-plane)Admin is the only built-in role that reaches Agentic Data Plane Built-in roles span all of Redpanda Cloud. Only Admin reaches Agentic Data Plane. | Role | What it grants in Agentic Data Plane | | --- | --- | | Admin | Every Agentic Data Plane permission, on every resource. Bootstraps a deployment, and covers the operators who configure providers, agents, MCP servers, and pricing, and who author access policies. | | Writer, Reader | Nothing. Both roles keep their control-plane, Kafka, pipeline, and knowledge-base permissions, so a Writer can manage Redpanda Connect pipelines and knowledge bases and still can’t read, create, or invoke an agent, MCP server, or LLM provider. | | PipelineInvoker and the Kafka and Schema Registry roles | Nothing. These cover Redpanda Connect pipelines, topics, consumer groups, and Schema Registry subjects. | There are no Agentic Data Plane Invoker or transcript-reader roles to assign. Runtime-only access for a service account (calling an MCP tool, proxying an LLM request) and read access to conversation transcripts come from policies you write, not roles you pick from a list. Redpanda used to ship narrow built-in roles for exactly those cases and no longer provisions them, because a policy does the same job with a condition and a scope attached. > 📝 **NOTE** > > If your organization predates this change, those roles may still appear in your role list. Don’t build new grants on them. Author the equivalent policy instead. ## [](#grant-access-to-a-user-group-or-service-account)Grant access to a user, group, or service account Write a policy. The principal is a user or a group, so you can grant a whole identity provider group in one statement and let group membership stay managed in your IdP. For example, to let your support team call the tools on one MCP server and nothing else: ```cedar permit ( principal in Group::"support", action == Action::"McpServerTool.call", resource is McpServerTool in McpServer::"zendesk" ); ``` Policies also do the things a role bundle structurally can’t: condition on a resource tag, restrict access to a resource’s creator, or deny an action across every principal at once. See [Manage Access Policies](https://docs.redpanda.com/agentic-data-plane/control/access-policies/) for the authoring workflow, the actions a policy can name, and worked examples. Access policies use their own vocabulary. A policy names an entity type and a verb, such as `Action::"Agent.get"`, not the permission strings on this page. See [Action reference](https://docs.redpanda.com/agentic-data-plane/control/access-policies/#action-reference). A custom role holding Agentic Data Plane permissions still works. Reach for one when you need a permission bundle bound at a control-plane scope, or for the `dataplane_aiagent_a2a_*` permissions, which no policy action covers. ## [](#agentic-data-plane-permissions)Agentic Data Plane permissions Permissions are the RBAC-side vocabulary. You need them to read what Admin grants and to define a custom role. They are not what a policy names. Agentic Data Plane permissions live in these families: - `dataplane_adp_mcpserver_*`: Manage and call MCP servers (CRUD plus runtime operations like `tools_call` and `resources_read`). - `dataplane_adp_llmprovider_*`: Manage LLM providers and proxy LLM requests through AI Gateway. The `_invoke` permission is what your applications need at runtime. - `dataplane_adp_agent_*` and `dataplane_adp_agent_credential_*`: Manage declarative AI agents and the OIDC credentials issued to them. - `dataplane_adp_policy_*` and `dataplane_adp_policytemplate_*`: Author and read access policies and policy templates. - `dataplane_adp_transcript_*`: Read agent conversation transcripts, which carry full conversation content. - `dataplane_adp_auditlog_*`: Read audit log events, which record who attempted an action, on which resource, and whether it was allowed. - `dataplane_adp_spending_*`: Read AI spending data for governance and cost reporting. - `dataplane_aiagent_a2a_*`: Invoke agent-to-agent (A2A) operations against an agent’s own ingress. These are the one Agentic Data Plane family a policy can’t govern; see [A2A runtime permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#a2a-runtime-permissions). - `dataplane_aigateway_*`: Manage enterprise AI Gateway features, including OAuth providers and clients, model providers, rate and spend limits, audit, and pricing. Admin is the only built-in role that holds any of them. The legacy `dataplane_mcpserver_*` namespace, which older proto versions still enforce, is scoped the same way. Two more families belong to Redpanda Connect resources that Agentic Data Plane uses. These are owned outside Agentic Data Plane, so they stay in the Writer and Reader roles and are outside what a policy can govern: - `dataplane_pipeline_*`: Manage and invoke Redpanda Connect pipelines. - `dataplane_knowledgebase_*`: Manage retrieval-augmented generation knowledge bases. For the full list, see [Roles and Permissions Reference](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/). ## [](#identity-and-impersonation)Identity and impersonation Agentic Data Plane API calls authenticate as one of two identity types: - **User identity (OIDC)**: A human user signed in through Redpanda’s OIDC provider. The Agentic Data Plane UI uses this identity when an admin manages Agentic Data Plane resources interactively. - **Service account**: A non-human identity backed by OIDC client credentials. Applications, CI jobs, and `rpk ai` use service accounts. Both are policy principals. A service account is granted access the same way a user is, with a policy naming it as the principal. Account impersonation, which lets Redpanda Console reuse a user’s identity for Kafka API and Schema Registry calls, applies to those two subsystems only. Agentic Data Plane endpoints continue to authenticate clients directly through their OIDC tokens, regardless of how account impersonation is configured at the cluster level. ## [](#where-agentic-data-plane-fits-in-redpanda-cloud-rbac)Where Agentic Data Plane fits in Redpanda Cloud RBAC Agentic Data Plane permissions are part of the same Redpanda Cloud RBAC system that gates control-plane resources such as resource groups, networks, and clusters. They are scoped more tightly than the rest of it. The Writer and Reader roles bundle control-plane permissions with dataplane Kafka permissions, so a Writer binding at the organization scope covers those layers in one grant. It does not reach Agentic Data Plane. A developer who holds Writer on the organization can create a cluster and manage topics and pipelines, and still gets a permission-denied error from every agent, MCP server, and LLM provider API until a policy grants that access. Admin spans every layer, including Agentic Data Plane. ## [](#next-steps)Next steps - [Manage Access Policies](https://docs.redpanda.com/agentic-data-plane/control/access-policies/) - [Roles and Permissions Reference](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/) --- # Page 62: Roles and Permissions Reference **URL**: https://docs.redpanda.com/agentic-data-plane/control/permissions-reference.md --- # Roles and Permissions Reference > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Roles and Permissions Reference latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: permissions-reference page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: permissions-reference.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/control/pages/permissions-reference.adoc description: Look up the permissions Agentic Data Plane enforces across LLM providers, MCP servers, agents, access policies, pipelines, knowledge bases, and governance APIs. page-topic-type: reference personas: security_compliance_lead, platform_engineer learning-objective-1: Look up an Agentic Data Plane permission by namespace learning-objective-2: Identify the operation each permission gates learning-objective-3: Map a denied API call to the permission it enforces page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-06" --- Every Redpanda Agentic Data Plane API call enforces a single permission. This reference lists the Agentic Data Plane-namespaced permissions and the operation each one gates. Use this reference to: - Look up an Agentic Data Plane permission by namespace - Identify the operation each permission gates - Map a denied API call to the permission it enforces > ❗ **IMPORTANT** > > These permission strings are the role-based access control (RBAC) vocabulary. They are not what you write to grant access. > > Agentic Data Plane access is granted with [access policies](https://docs.redpanda.com/agentic-data-plane/control/access-policies/), which name their own actions, such as `Action::"Agent.get"`. See [Action reference](https://docs.redpanda.com/agentic-data-plane/control/access-policies/#action-reference) for the list. Use this page to read what the Admin role covers, to map an API operation to the permission it enforces when you’re debugging a denial, or to define a custom role. For how policies and roles fit together, see [Control Who Can Do What](https://docs.redpanda.com/agentic-data-plane/control/permissions-overview/). ## [](#how-to-read-this-reference)How to read this reference Each table column means the same thing across every namespace. - The Permission column is the exact string the API enforces. - The Operation column is the user-facing action this permission gates. Admin is the only built-in role that grants any of the permissions on this page, and it grants all of them, so there is no per-role column to read. Writer, Reader, and the task-specific built-in roles grant none of them. Two Redpanda Connect namespaces behave differently. [Pipeline](#pipeline-permissions) and [knowledge base](#knowledge-base-permissions) permissions are owned outside Agentic Data Plane, so they remain part of Writer and Reader and keep their role columns. ## [](#mcp-server-permissions)MCP server permissions The `dataplane_adp_mcpserver_*` permissions gate both server management (CRUD) and the MCP protocol calls a client makes against a running server. | Permission | Operation | | --- | --- | | dataplane_adp_mcpserver_create | Register a new MCP server | | dataplane_adp_mcpserver_update | Modify an existing MCP server’s configuration | | dataplane_adp_mcpserver_delete | Delete an MCP server | | dataplane_adp_mcpserver_get | View one MCP server’s configuration | | dataplane_adp_mcpserver_list | List MCP servers | | dataplane_adp_mcpserver_initialize | Initialize an MCP session against a server | | dataplane_adp_mcpserver_ping | Health-check an MCP server | | dataplane_adp_mcpserver_resources_list | List resources a server exposes | | dataplane_adp_mcpserver_resources_templates_list | List resource templates a server exposes | | dataplane_adp_mcpserver_resources_read | Read a resource from a server | | dataplane_adp_mcpserver_prompts_list | List prompts a server exposes | | dataplane_adp_mcpserver_prompts_get | Retrieve a prompt from a server | | dataplane_adp_mcpserver_tools_list | List tools a server exposes | | dataplane_adp_mcpserver_tools_call | Invoke a tool on an MCP server | | dataplane_adp_mcpserver_logging_set_level | Adjust an MCP server’s log level | A legacy `dataplane_mcpserver_*` namespace mirrors these permissions and is still enforced by older proto versions. It is scoped the same way: Admin grants both namespaces, and no other built-in role grants either. ## [](#llm-provider-permissions)LLM provider permissions The `dataplane_adp_llmprovider_*` permissions gate AI Gateway provider configuration and the runtime proxy that forwards LLM requests upstream. | Permission | Operation | | --- | --- | | dataplane_adp_llmprovider_create | Create an LLM provider | | dataplane_adp_llmprovider_get | View one LLM provider’s configuration | | dataplane_adp_llmprovider_list | List LLM providers | | dataplane_adp_llmprovider_update | Modify an LLM provider’s configuration | | dataplane_adp_llmprovider_delete | Delete an LLM provider | | dataplane_adp_llmprovider_invoke | Proxy LLM requests through AI Gateway at runtime | The `dataplane_adp_llmprovider_invoke` permission is all an application needs to send traffic through AI Gateway. It is the narrowest useful grant for a service account, and no built-in role provides it on its own. Grant it with an access policy naming `Action::"LLMProvider.invoke"`. ## [](#agent-management-permissions)Agent management permissions The `dataplane_adp_agent_*` permissions gate declarative agent configuration. | Permission | Operation | | --- | --- | | dataplane_adp_agent_create | Create a declarative agent | | dataplane_adp_agent_get | View one agent’s configuration | | dataplane_adp_agent_list | List agents | | dataplane_adp_agent_update | Modify an agent’s configuration | | dataplane_adp_agent_delete | Delete an agent | ## [](#agent-credential-permissions)Agent credential permissions The `dataplane_adp_agent_credential_*` permissions gate the OIDC client credentials an agent uses for outbound calls. | Permission | Operation | | --- | --- | | dataplane_adp_agent_credential_create | Issue a new OIDC client credential for an agent | | dataplane_adp_agent_credential_list | List an agent’s credentials | | dataplane_adp_agent_credential_delete | Revoke an agent credential | ## [](#agent-trigger-permissions)Agent trigger permissions The `dataplane_adp_agent_trigger_*` permissions gate triggers that start an agent in response to an external event, such as an incoming message or a schedule. See [Trigger Agents](https://docs.redpanda.com/agentic-data-plane/connect/triggers/overview/). | Permission | Operation | | --- | --- | | dataplane_adp_agent_trigger_create | Create a trigger on an agent | | dataplane_adp_agent_trigger_get | View a trigger on an agent | | dataplane_adp_agent_trigger_list | List triggers on agents | | dataplane_adp_agent_trigger_update | Modify a trigger on an agent | | dataplane_adp_agent_trigger_delete | Delete a trigger on an agent | A further `dataplane_adp_agent_trigger_report_health` permission lets internal trigger observers report trigger health. Only Admin grants it, and nothing tenant-facing needs it. ## [](#agent-session-permissions)Agent session permissions The `dataplane_adp_agent_session_*` permissions gate access to an agent’s conversation sessions: the persisted conversation threads a managed agent accumulates as it runs. Sessions exist for managed agents only; a self-managed agent keeps no session store. The runtime creates sessions, so there is no create or update permission. | Permission | Operation | | --- | --- | | dataplane_adp_agent_session_list | List an agent’s conversation sessions (summaries only) | | dataplane_adp_agent_session_get | View one conversation session, including its full message transcript | | dataplane_adp_agent_session_delete | Delete an agent’s conversation sessions | > 📝 **NOTE** > > Granting `dataplane_adp_agent_session_get` exposes a session’s full conversation content (prompts, tool inputs and outputs, and model output), the same class of content that transcript access exposes. Treat it as sensitively as the transcript permissions when a policy grants it. ## [](#transcript-permissions)Transcript permissions The `dataplane_adp_transcript_*` permissions gate read access to agent conversation transcripts. Transcripts carry the full content of an agent’s conversations (system prompts, user messages, tool arguments, and model output). See [See What Your Agent Did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/) for what a transcript records. | Permission | Operation | | --- | --- | | dataplane_adp_transcript_get | View a single agent conversation transcript | | dataplane_adp_transcript_list | List agent conversation transcripts | > 📝 **NOTE** > > Transcript access is separate from agent read access. A principal that can view an agent’s configuration through `dataplane_adp_agent_get` cannot read that agent’s transcripts. Grant transcript access deliberately, with a policy naming the `Transcript` actions, to the users and service accounts that need to read conversation content. ## [](#audit-log-permissions)Audit log permissions The `dataplane_adp_auditlog_*` permissions gate read access to authorization events. Audit events can include user identities, resource names, network information, configuration changes, and captured request or response data. See [Review the Audit Log](https://docs.redpanda.com/agentic-data-plane/monitor/audit-log/) for how to review them. | Permission | Operation | | --- | --- | | dataplane_adp_auditlog_list | List audit log events and view an event’s details | > 📝 **NOTE** > > The built-in **Read only** template grants `dataplane_adp_auditlog_list`, along with every template built on top of it. To let a principal read resource configuration without reading the audit log, write your own template or policy that omits `AuditLog.list` rather than linking a built-in template. ## [](#access-policy-permissions)Access policy permissions The `dataplane_adp_policy_*` and `dataplane_adp_policytemplate_*` permissions gate the access policies and policy templates themselves. See [Manage Access Policies](https://docs.redpanda.com/agentic-data-plane/control/access-policies/). | Permission | Operation | | --- | --- | | dataplane_adp_policy_create | Create an access policy | | dataplane_adp_policy_get | View one access policy | | dataplane_adp_policy_list | List access policies | | dataplane_adp_policy_update | Modify an access policy | | dataplane_adp_policy_delete | Delete an access policy | | dataplane_adp_policytemplate_create | Create a policy template | | dataplane_adp_policytemplate_get | View one policy template | | dataplane_adp_policytemplate_list | List policy templates | | dataplane_adp_policytemplate_update | Modify a policy template | | dataplane_adp_policytemplate_delete | Delete a policy template | | dataplane_adp_systempolicy_list | List the policies derived from role bindings | | dataplane_adp_effectivepolicyset_get | View the policy set in effect for a principal | | dataplane_adp_effectivepolicyset_list | List effective policy sets | > ❗ **IMPORTANT** > > The permission to author access policies is itself an Agentic Data Plane permission, so Admin is the only built-in role that has it. Whoever manages access for your deployment needs Admin, or a policy that grants the `Policy` actions explicitly. Granting policy authoring is equivalent to granting everything a policy can grant. The `dataplane_adp_systempolicy_list` permission is separate from `dataplane_adp_policy_list` because the derived view names the principal of every role binding in the organization. ## [](#spending-permissions)Spending permissions The `dataplane_adp_spending_*` permissions gate the governance APIs that surface AI spend, request counts, and token volume. See [Set Up Budgets](https://docs.redpanda.com/agentic-data-plane/control/budgets/) for what spending data Agentic Data Plane records automatically. | Permission | Operation | | --- | --- | | dataplane_adp_spending_get | Read AI spending data for governance and cost reports | ## [](#budget-permissions)Budget permissions The `dataplane_adp_budget_*` permissions gate per-agent LLM spend budgets. See [Set a budget](https://docs.redpanda.com/agentic-data-plane/control/budgets/#set-a-spend-limit). | Permission | Operation | | --- | --- | | dataplane_adp_budget_create | Create a budget | | dataplane_adp_budget_get | View a budget and its current-period spend | | dataplane_adp_budget_list | List budgets | | dataplane_adp_budget_update | Modify a budget | | dataplane_adp_budget_delete | Delete a budget | ## [](#guardrail-permissions)Guardrail permissions The `dataplane_adp_guardrail_*` permissions gate guardrail policies that screen LLM requests and responses. See [How Guardrails Work](https://docs.redpanda.com/agentic-data-plane/control/guardrails/overview/). | Permission | Operation | | --- | --- | | dataplane_adp_guardrail_create | Create a guardrail policy | | dataplane_adp_guardrail_get | View one guardrail policy’s configuration | | dataplane_adp_guardrail_list | List guardrail policies | | dataplane_adp_guardrail_update | Modify a guardrail policy | | dataplane_adp_guardrail_delete | Delete a guardrail policy | ## [](#a2a-runtime-permissions)A2A runtime permissions The `dataplane_aiagent_a2a_*` permissions, along with `dataplane_adp_a2a_invoke`, gate agent-to-agent (A2A) runtime traffic. | Permission | Operation | | --- | --- | | dataplane_adp_a2a_invoke | Invoke an A2A agent | | dataplane_aiagent_a2a_message_send | Send a message to an agent | | dataplane_aiagent_a2a_message_stream | Open a streaming message connection to an agent | | dataplane_aiagent_a2a_tasks_get | Read one A2A task | | dataplane_aiagent_a2a_tasks_list | List A2A tasks | | dataplane_aiagent_a2a_tasks_cancel | Cancel an A2A task | | dataplane_aiagent_a2a_tasks_subscribe | Subscribe to A2A task events | | dataplane_aiagent_a2a_get_extended_agent_card | Read an agent’s extended agent card | The `dataplane_adp_a2a_invoke` permission covers the AI Gateway A2A proxy path, and a policy can grant it by naming `Action::"Agent.invoke"`. The `dataplane_aiagent_a2a_*` permissions are different. The agent’s own ingress enforces them against the caller’s RBAC permission set, and they have no access-policy action, so a policy can’t grant them. A service account that talks to an agent’s A2A endpoint directly needs Admin or a custom role holding this set. ## [](#pipeline-permissions)Pipeline permissions The `dataplane_pipeline_*` permissions gate Redpanda Connect pipelines used by Agentic Data Plane for ingestion and transformation. These are Redpanda Connect permissions rather than Agentic Data Plane permissions, so the Writer, Reader, and PipelineInvoker built-in roles grant them as shown. The PipelineInvoker role grants only the runtime invocation permissions. | Permission | Operation | Writer | Reader | Invoker | | --- | --- | --- | --- | --- | | dataplane_pipeline_create | Create a pipeline | ✓ | | | | dataplane_pipeline_get | View one pipeline’s configuration | ✓ | ✓ | | | dataplane_pipeline_list | List pipelines | ✓ | ✓ | | | dataplane_pipeline_update | Modify a pipeline’s configuration | ✓ | | | | dataplane_pipeline_delete | Delete a pipeline | ✓ | | | | dataplane_pipeline_start | Start a stopped pipeline | ✓ | | | | dataplane_pipeline_stop | Stop a running pipeline | ✓ | | | | dataplane_pipeline_gateway_invoke | Invoke a pipeline through the gateway endpoint | ✓ | | PipelineInvoker | | dataplane_pipeline_otlp_grpc_invoke | Send OTLP traces to a pipeline over gRPC | ✓ | | PipelineInvoker | | dataplane_pipeline_otlp_http_invoke | Send OTLP traces to a pipeline over HTTP | ✓ | | PipelineInvoker | Access policies can’t govern pipelines. The entity types a policy can name are listed in [Action reference](https://docs.redpanda.com/agentic-data-plane/control/access-policies/#action-reference), and pipelines aren’t among them. ## [](#knowledge-base-permissions)Knowledge base permissions The `dataplane_knowledgebase_*` permissions gate retrieval-augmented generation (RAG) knowledge bases. Like the pipeline permissions, these are Redpanda Connect permissions and remain part of Writer and Reader. | Permission | Operation | Writer | Reader | | --- | --- | --- | --- | | dataplane_knowledgebase_create | Create a knowledge base | ✓ | | | dataplane_knowledgebase_get | View one knowledge base’s configuration | ✓ | ✓ | | dataplane_knowledgebase_list | List knowledge bases | ✓ | ✓ | | dataplane_knowledgebase_update | Modify a knowledge base’s configuration | ✓ | | | dataplane_knowledgebase_delete | Delete a knowledge base | ✓ | | ## [](#built-in-roles-summary)Built-in roles summary | Role | Coverage of the permissions on this page | | --- | --- | | Admin | Every Agentic Data Plane permission on this page, plus the pipeline and knowledge-base permissions. Bind it to the operators who administer the deployment. | | Writer | No Agentic Data Plane permissions. Grants full management of pipelines and knowledge bases, alongside its control-plane and Kafka permissions. | | Reader | No Agentic Data Plane permissions. Grants _get and _list on pipelines and knowledge bases, alongside its control-plane and Kafka permissions. | | PipelineInvoker | No Agentic Data Plane permissions. Grants the three pipeline runtime invocation permissions. | Redpanda no longer provisions Agentic Data Plane-specific built-in roles for runtime invocation or transcript reads, and isn’t adding more. Grant that access with an [access policy](https://docs.redpanda.com/agentic-data-plane/control/access-policies/). A custom role holding permissions from this page still works. Reach for one when you need a bundle bound at a control-plane scope, or for the `dataplane_aiagent_a2a_*` permissions, which no policy action covers. ## [](#next-steps)Next steps - [Control Who Can Do What](https://docs.redpanda.com/agentic-data-plane/control/permissions-overview/) - [Manage Access Policies](https://docs.redpanda.com/agentic-data-plane/control/access-policies/) --- # Page 63: Routing & LLM Settings **URL**: https://docs.redpanda.com/agentic-data-plane/gateway.md --- # Routing & LLM Settings > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Routing & LLM Settings latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: index page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/gateway/pages/index.adoc description: Configure AI Gateway, LLM providers, and routing. page-git-created-date: "2026-05-28" page-git-modified-date: "2026-06-01" --- AI Gateway is the proxy that routes agent traffic to your LLM providers. Learn how it works, configure providers, and connect your agents to the gateway. - [How AI Gateway Works](overview/) AI Gateway is Agentic Data Plane's managed proxy for LLM APIs. Create a provider for OpenAI, Anthropic, Google AI, AWS Bedrock, or an OpenAI-compatible endpoint, and point your applications at a Redpanda-hosted URL with managed secrets, authentication, and observability. - [Configure an LLM Provider](configure-provider/) Create an LLM provider to proxy requests to OpenAI, Anthropic, Google AI, AWS Bedrock, or any OpenAI-compatible endpoint through Redpanda Agentic Data Plane. - [Connect Your App to AI Gateway](connect-agent/) Point your application or AI agent at an AI Gateway provider's proxy URL. Covers the URL shape, the local development workflow with rpk ai, the OIDC client-credentials flow for CI and application code, and SDK examples for OpenAI, Anthropic, Google AI, AWS Bedrock, and OpenAI-compatible endpoints. --- # Page 64: Set Up AWS Bedrock as an LLM Provider **URL**: https://docs.redpanda.com/agentic-data-plane/gateway/bedrock-setup.md --- # Set Up AWS Bedrock as an LLM Provider > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Set Up AWS Bedrock as an LLM Provider latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: bedrock-setup page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: bedrock-setup.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/gateway/pages/bedrock-setup.adoc description: Create the IAM user, policy, and access keys required for AI Gateway to invoke Amazon Bedrock models, then register the provider in Agentic Data Plane. page-topic-type: how-to personas: platform_engineer learning-objective-1: Create an IAM policy that grants AI Gateway permission to invoke Bedrock foundation models and cross-region inference profiles learning-objective-2: Create a dedicated IAM user, attach the policy, and generate access keys for AI Gateway learning-objective-3: Register Bedrock as an LLM provider in Agentic Data Plane and select the models you want to expose page-git-created-date: "2026-05-28" page-git-modified-date: "2026-07-30" --- This guide walks you through the AWS-side setup AI Gateway needs to invoke Amazon Bedrock, then through the Redpanda Agentic Data Plane flow that registers Bedrock as an LLM provider. For background on how Bedrock foundation models, cross-region inference profiles, and IAM patterns map to the provider form, see [AWS Bedrock: Inference profiles and IAM](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/#bedrock-inference-profiles) on the main provider configuration page. After completing this guide, you will be able to: - Create an IAM policy that grants AI Gateway permission to invoke Bedrock foundation models and cross-region inference profiles - Create a dedicated IAM user, attach the policy, and generate access keys for AI Gateway - Register Bedrock as an LLM provider in Agentic Data Plane and select the models you want to expose ## [](#prerequisites)Prerequisites - An AWS account with Bedrock model access enabled in the region you plan to call. Model availability varies by region; see [Bedrock models by region](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html). - Access to the AWS CLI configured with credentials that can create IAM users, policies, and access keys. - Access to the Redpanda UI. ## [](#create-the-iam-policy)Create the IAM policy Create a policy that grants the two Bedrock invoke actions on both foundation-model ARNs and cross-region inference-profile ARNs: ```bash aws iam create-policy \ --policy-name RedpandaBedrockInvoke \ --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "BedrockInvoke", "Effect": "Allow", "Action": [ "bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream" ], "Resource": [ "arn:aws:bedrock:*::foundation-model/*", "arn:aws:bedrock:*:*:inference-profile/*" ] } ] }' ``` The second resource entry enables cross-region inference profiles such as `us.anthropic.claude-sonnet-4-6`, which AI Gateway uses when the model identifier carries a geography prefix. See [AWS Bedrock: Inference profiles and IAM](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/#bedrock-inference-profiles) for the full prefix list and pricing implications. > 📝 **NOTE** > > Anthropic Claude 4.6 and later models cannot be invoked with the bare foundation-model ID and require an inference profile. Without the second `Resource` entry, those calls fail with `AccessDenied`. To restrict the policy to specific models and regions for production, replace the wildcard resources with explicit ARNs. For example: ```json { "Resource": [ "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-sonnet-4-6", "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-haiku-4-5-20251001" ] } ``` ## [](#create-the-iam-user)Create the IAM user Create a dedicated IAM user for AI Gateway and attach the policy: ```bash aws iam create-user --user-name redpanda-bedrock-invoker aws iam attach-user-policy \ --user-name redpanda-bedrock-invoker \ --policy-arn arn:aws:iam:::policy/RedpandaBedrockInvoke ``` Replace `` with the account ID returned in the `create-policy` output (visible in the policy ARN). > 💡 **TIP** > > Don’t reuse an existing IAM user. A dedicated user makes it easy to rotate credentials or revoke access without affecting other AWS workloads. ## [](#generate-access-keys)Generate access keys Generate the access keys AI Gateway uses: ```bash aws iam create-access-key --user-name redpanda-bedrock-invoker ``` Save the `AccessKeyId` and `SecretAccessKey` from the output. You need both in the next section to register them as Redpanda secrets. > ⚠️ **CAUTION** > > AWS displays the secret access key only at creation. Store it in a password manager or pass it directly into the secret-creation flow in the next section. ## [](#verify-bedrock-access-optional)Verify Bedrock access (optional) Confirm the IAM user can invoke Bedrock before moving to the UI: ```bash aws bedrock-runtime invoke-model \ --model-id us.anthropic.claude-haiku-4-5-20251001-v1:0 \ --region us-east-1 \ --content-type application/json \ --accept application/json \ --body "$(echo -n '{"anthropic_version":"bedrock-2023-05-31","max_tokens":32,"messages":[{"role":"user","content":"Hello"}]}' | base64)" \ /tmp/bedrock-test.json \ && jq . /tmp/bedrock-test.json && rm /tmp/bedrock-test.json ``` A successful model response confirms the IAM policy, region, and credentials are correct. If you see `AccessDenied`, check the policy resource list and confirm Bedrock model access is enabled in the target region. ## [](#register-bedrock-as-an-llm-provider)Register Bedrock as an LLM provider 1. Open **LLM Providers** in the sidebar and click **Add provider**. 2. Select **AWS Bedrock** as the provider type. 3. Enter a Name such as `my-bedrock`. Use lowercase letters, digits, and hyphens. The name is immutable and appears in the proxy URL. 4. Select the Region where you want to invoke Bedrock, such as `us-east-1`. 5. For Credential type, select **Static keys**. (This guide uses the access keys you created above. For the default-chain and assume-role options, see [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/).) 6. Configure the credentials: 1. In the Access key ID ref dropdown, type a secret name such as `AWS_ACCESS_KEY_ID`. 2. Paste the `AccessKeyId` value from the IAM user setup and click **Create**. The secret is stored in the Agentic Data Plane secret store, scoped to AI Gateway. 3. Repeat for Secret access key ref. Use a name such as `AWS_SECRET_ACCESS_KEY` and paste the `SecretAccessKey` value. Secret names are normalized to `UPPER_SNAKE_CASE` automatically and get the AI Gateway scope, which makes them usable across the platform: LLM providers, MCP servers, and agents. 7. Select the models you want to expose through this provider, for example: - `anthropic.claude-sonnet-4-6` - `anthropic.claude-haiku-4-5-20251001` - `amazon.nova-pro-v1:0` For Anthropic Claude 4.6 and later, pick the inference profile (for example, `us.anthropic.claude-sonnet-4-6`) rather than the bare foundation-model ID. 8. Click **Create provider**. 9. Verify the provider by clicking **Test connection** on its edit page. A successful response confirms that the credentials, region, and IAM policy are correctly configured. ## [](#cross-region-inference-profile-billing)Cross-region inference profile billing When you call a cross-region inference profile (any model identifier with a `us.`, `eu.`, `apac.`, `au.`, `jp.`, or `global.` prefix), AI Gateway bills at the regional rate for that profile. The regional prefix is preserved end to end so usage on the **Cost & Usage** page under **Governance** reflects the correct per-region price. For example, requests to `eu.anthropic.claude-haiku-4-5` bill at the EU Haiku rate, not the headline foundation-model rate. The `global.` profile shares the headline rate; the geography-specific profiles (`us.`, `eu.`, `apac.`, `au.`, `jp.`) carry approximately a 10% cross-region inference premium. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | AccessDenied from Bedrock | Confirm the IAM policy includes both bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream, and that the resource list covers the model or inference profile you’re calling. For Claude 4.6 and later, the policy must include arn:aws:bedrock:*:*:inference-profile/* or an explicit inference-profile ARN. | | secret "" not found | Confirm the secret exists in the cloud secret store and the reference in the provider configuration matches exactly. Secret names are UPPER_SNAKE_CASE. | | ValidationException: model ID not supported | The model isn’t enabled in the region you chose. Open the AWS Bedrock console, switch to the target region, and enable model access for the foundation models you want to expose. | | Invocation of model ID … with on-demand throughput isn’t supported | You called a Claude 4.6 or later model with a bare foundation-model ID. Switch to an inference profile, for example us.anthropic.claude-sonnet-4-6 instead of anthropic.claude-sonnet-4-6. See AWS Bedrock: Inference profiles and IAM. | ## [](#next-steps)Next steps - [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/) - [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/) --- # Page 65: Code Mode **URL**: https://docs.redpanda.com/agentic-data-plane/gateway/code-mode.md --- # Code Mode > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Code Mode latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: code-mode page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: code-mode.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/gateway/pages/code-mode.adoc description: Turn on code mode for an MCP server to replace a large tool catalog with two tools, search and execute, and cut the token cost of tool-heavy servers. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Explain how code mode reduces tool-token usage for an MCP server learning-objective-2: Enable code mode on an MCP server and find its code-mode endpoint learning-objective-3: Use the search and execute tools to find and call tools through code mode page-git-created-date: "2026-06-09" page-git-modified-date: "2026-07-29" --- Enable code mode on an MCP server to cut the token cost of serving a large tool catalog. Instead of loading every tool definition into context, agents search for the tools they need and run them through a lightweight JavaScript sandbox. After reading this page, you will be able to: - Explain how code mode reduces tool-token usage for an MCP server - Enable code mode on an MCP server and find its code-mode endpoint - Use the search and execute tools to find and call tools through code mode > 📝 **NOTE** > > Code mode applies to one MCP server at a time. It is a token-reduction technique for a server with many tools, not a way to combine multiple servers behind one endpoint. ## [](#how-code-mode-works)How code mode works When code mode is enabled on an MCP server, the AI Gateway serves a virtual sibling endpoint alongside the server’s normal one. If the server is reachable at `https://aigw..clusters.rdpa.co/mcp/v1/`, its code-mode endpoint is the same path with a `-code` suffix: ```none https://aigw..clusters.rdpa.co/mcp/v1/-code ``` That endpoint exposes exactly two tools instead of the server’s full catalog: `search` Find tools in the underlying server’s catalog. Takes an optional `query`, a regular expression (Go RE2 syntax) matched against each tool’s name and description. It returns the full schema (name, description, and input schema) of every match, or null when nothing matches. Omit the query to list the entire catalog, which is large, so prefer a narrow regex. `execute` Run JavaScript in a sandbox that is connected to the same MCP server. The value of the last expression in your code is returned as the tool result. Inside the sandbox, two synchronous host functions are available: - `call_tool({name, arguments})`: Invoke a tool on the server and return its output directly. It throws if the tool returns an error. JSON output is parsed into the matching JavaScript value; anything else is returned as a string. - `search_tools(query)`: Search the catalog by regex, the same as the `search` tool. A typical interaction is: call `search` with a narrow regex to find candidate tools, read the returned input schema, then call `execute` with code that invokes one or more of those tools. ### [](#sandbox-constraints)Sandbox constraints The `execute` sandbox is isolated and intentionally limited: - Code is capped at 64 KiB. - A single `execute` call can make at most 50 tool calls. - Each sandbox has a memory limit and a runtime limit. - The `call_tool` and `search_tools` host functions are synchronous, so do not use `await` on them. Top-level `await` and top-level `return` are syntax errors, promises are not awaited (returning one yields an empty result), and `console.log` output is discarded. Calls that code mode makes to the underlying server run with the same identity and authentication as the server itself, including any per-user [token vault](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#token-vault) credentials. Code mode does not widen what the server can reach. ## [](#when-to-use-code-mode)When to use code mode Turn on code mode when: - A server exposes a large tool catalog, so loading every tool definition on each request is expensive or pushes out other context. - An agent frequently performs multi-step tool sequences that you would rather run in one round trip instead of several model turns. Leave it off for servers with only a handful of tools, where the overhead of searching and writing code outweighs the token savings of a small catalog. ## [](#enable-code-mode)Enable code mode Enable code mode on the MCP server, then point your agent or client at the code-mode endpoint. 1. Open **MCP Servers** in the sidebar. 2. Create a server, or open an existing one to edit it. See [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/). 3. Turn on the **Code mode** toggle. 4. Save the server. The server’s detail page shows the code-mode endpoint URL (the primary URL with a `-code` suffix). 5. Configure your agent or MCP client to connect to the code-mode URL instead of the primary URL. ## [](#test-from-the-cli)Test from the CLI The `--code-mode` flag on `rpk ai mcp-server tools` targets the virtual `-code` endpoint instead of the server’s primary endpoint, so you can exercise `search` and `execute` directly. List the code-mode tools: ```bash rpk ai mcp-server tools list --code-mode ``` Search the underlying catalog: ```bash rpk ai mcp-server tools call search --code-mode \ --args '{"query":"(?i)pull.*create"}' ``` Run code through the `execute` tool: ```bash rpk ai mcp-server tools call execute --code-mode \ --args '{"code":"var pulls = call_tool({ name: \"github_pulls_list\", arguments: { owner: \"redpanda-data\", repo: \"redpanda\", state: \"open\" } }); JSON.stringify(pulls.map(function (p) { return { number: p.number, title: p.title }; }));"}' ``` The code calls a tool, shapes the result, and returns the value of its last expression. Because `call_tool` is synchronous, a single `execute` call can search, call several tools, and combine the results without extra model round trips. ## [](#next-steps)Next steps - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) - [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) - [Test MCP Tools](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) --- # Page 66: Configure an LLM Provider **URL**: https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider.md --- # Configure an LLM Provider > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Configure an LLM Provider latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: configure-provider page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: configure-provider.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/gateway/pages/configure-provider.adoc description: Create an LLM provider to proxy requests to OpenAI, Anthropic, Google AI, AWS Bedrock, or any OpenAI-compatible endpoint through Redpanda Agentic Data Plane. page-topic-type: how-to personas: platform_engineer, agent_builder learning-objective-1: Create an LLM provider for OpenAI, Anthropic, Google AI, AWS Bedrock, or an OpenAI-compatible endpoint learning-objective-2: Select the models you want to expose through the provider learning-objective-3: Verify the provider is reachable using the built-in Test connection control page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-11" --- Create an LLM provider to give your applications a managed proxy URL: Redpanda handles the upstream API keys, forwards requests to the provider, and records usage for you. Create a provider for each upstream you use, whether that’s OpenAI, Anthropic, Google AI, AWS Bedrock, or an OpenAI-compatible endpoint. After reading this page, you will be able to: - Create an LLM provider for OpenAI, Anthropic, Google AI, AWS Bedrock, or an OpenAI-compatible endpoint - Select the models you want to expose through the provider - Verify the provider is reachable using the built-in Test connection control ## [](#prerequisites)Prerequisites - An API key (or AWS credentials for Bedrock) for the upstream provider you want to configure. - Optional: Secrets already created in your dataplane’s secret store for the provider’s credentials. The create form can also store a new API key inline, so you don’t have to prepare a secret first. Secret identifiers use `UPPER_SNAKE_CASE`. For example: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `AWS_ACCESS_KEY_ID`. ## [](#open-the-create-llm-provider-page)Open the Create LLM provider page 1. Open **LLM Providers** in the sidebar. 2. Click **Add provider**. ## [](#fill-in-the-identity-fields)Fill in the identity fields The Identity section collects the provider’s name. Enter a `Display name`: a human-readable label shown in dashboards and model selectors, up to 253 characters. Agentic Data Plane derives the provider’s resource ID from the display name in the background; the create form doesn’t show it. The resource ID is the machine identifier used in API calls and CLI commands: lowercase letters, numbers, and hyphens only (`^[a-z][a-z0-9-]*$`), up to 63 characters, and immutable after creation. It appears in the proxy URL (`/llm/v1/providers//…​`). ## [](#choose-a-provider-type)Choose a provider type In the Provider type section, pick the type that matches your upstream. | Type | Use when | | --- | --- | | OpenAI | Proxy GPT, o-series, and embeddings through the OpenAI API. Best when you already hold an OpenAI API key or want the broadest GPT model catalog. | | Anthropic | Call Claude Opus, Sonnet, and Haiku directly. Strong at coding, long-context reasoning, and tool use. Supports forwarding client Authorization headers to Anthropic for enterprise and Max-plan subscription passthrough (see Anthropic: Authorization passthrough). | | Google AI | Reach Gemini Pro, Flash, and multimodal models through Google AI Studio. Ideal for long-context workloads and image/video inputs. | | AWS Bedrock | Invoke foundation models (Claude, Llama, Titan, Nova, Mistral, AI21 Jamba, Gemma) hosted inside your AWS account. Requires an AWS region and credentials (static, STS-assumed role, or the default credential chain). Supports the native Bedrock APIs (InvokeModel, Converse) and an OpenAI-compatible Chat Completions endpoint for gpt-oss and Gemma models. See AWS Bedrock: Inference profiles and IAM for picking the right model identifier, and Set up AWS Bedrock as an LLM provider for a step-by-step IAM and access-key walkthrough. | | OpenAI-compatible | Point at any OpenAI-compatible endpoint that ships /v1/chat/completions (vLLM, Ollama, LM Studio, LocalAI, Together, Groq, OpenRouter). Useful for self-hosted models and aggregator gateways. Requires a Base URL. Authentication is optional. | Selecting a type reveals the type-specific configuration fields. ## [](#fill-in-the-type-specific-configuration)Fill in the type-specific configuration Each `API key reference` and credential field points at a secret-store entry, not the secret value itself. On the create form, the Credential section lists the keys already in your dataplane’s secret store: pick one, or select `Bring a new API key reference` to store a new key inline. Enter a `Key name` and the `API key` value, then click **Save key**. Agentic Data Plane stores the key in the secret store under an identifier derived from the key name, shown under the field; the value is stored encrypted and can’t be viewed again after saving. When you edit a provider later, the `API key reference` field offers an **Existing** tab to pick a stored secret and a **New** tab to create one inline. ### OpenAI | Field | Notes | | --- | --- | | Base URL | Optional. Leave empty for the standard OpenAI API (https://api.openai.com/v1). Override for Azure OpenAI or other OpenAI-hosted endpoints. | | API key reference | Required. Secret-store reference for the OpenAI API key. Must be UPPER_SNAKE_CASE, for example OPENAI_API_KEY. | ### Anthropic | Field | Notes | | --- | --- | | Base URL | Optional. Leave empty for the standard Anthropic API (https://api.anthropic.com). | | API key reference | Required unless Authorization passthrough is on. UPPER_SNAKE_CASE, for example ANTHROPIC_API_KEY. | | Authorization passthrough | Optional toggle. When on, AI Gateway forwards the client’s Authorization header to Anthropic instead of using a server-side API key. Used for enterprise and Max-plan OAuth passthrough: each client authenticates with its own Anthropic subscription. Leave the API key reference empty when using passthrough. | ### Google AI | Field | Notes | | --- | --- | | Base URL | Optional. Leave empty for the standard Google AI API (https://generativelanguage.googleapis.com). | | API key reference | Required. Secret-store reference for the Google AI API key. UPPER_SNAKE_CASE, for example GOOGLE_AI_API_KEY. | > ❗ **IMPORTANT** > > Gemini uses the `x-goog-api-key` header for authentication, not `Authorization: Bearer`. This matters when you wire up clients. See [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/). ### AWS Bedrock | Field | Notes | | --- | --- | | Region | Required. AWS region where the Bedrock endpoint is deployed, for example us-east-1. | | Base URL | Optional. Override the default regional Bedrock endpoint. | | Credential type | How AI Gateway authenticates to Bedrock: Default chain, Static keys, or Assume IAM role. The fields below depend on the mode you pick. | | Access key ID reference | Static keys only. Secret-store reference for the AWS access key ID, UPPER_SNAKE_CASE (typically AWS_ACCESS_KEY_ID). | | Secret access key reference | Static keys only. Secret-store reference for the AWS secret access key, UPPER_SNAKE_CASE (typically AWS_SECRET_ACCESS_KEY). | | Role ARN | Assume IAM role only. Required. ARN of the IAM role AI Gateway assumes through AWS STS, for example arn:aws:iam::123456789012:role/BedrockRole. | | External ID | Assume IAM role only. Optional. External ID for cross-account role assumption. Set it only when the role’s trust policy mandates an external ID. | | Session name | Assume IAM role only. Optional. Session name that appears in AWS CloudTrail audit logs, for example redpanda-adp. | | Guardrail | Optional. Name of a guardrail to attach to this provider, or empty for none. Only the Bedrock provider type exposes this setting. AI Gateway validates the name when you save: it rejects a guardrail that doesn’t exist or is being deleted, so set the field to an existing guardrail or leave it empty. See Create a guardrail. | Pick a **Credential type** to control how AI Gateway authenticates to Bedrock: - **Default chain** (default): Leave the credentials unset to use the AWS SDK’s default provider chain (environment variables, shared config, EKS Pod Identity, IRSA, or instance profile). Use this when the gateway already runs with an AWS identity. - **Static keys**: An access key pair stored in the secret store. Use this when no ambient AWS identity is available. This is the path the [Bedrock setup guide](https://docs.redpanda.com/agentic-data-plane/gateway/bedrock-setup/) walks through. - **Assume IAM role**: AI Gateway assumes an IAM role through AWS STS. Use this for cross-account access or when your security policy requires short-lived credentials. ### OpenAI-compatible | Field | Notes | | --- | --- | | Base URL | Required. URL of your OpenAI-compatible endpoint, for example http://vllm.internal:8000/v1, http://ollama.local:11434/v1, or an aggregator like Together / Groq / OpenRouter. | | API key reference | Optional. Leave empty for endpoints with no authentication (common for local runtimes). UPPER_SNAKE_CASE if set. | > 💡 **TIP** > > OpenAI-compatible endpoints can serve any model. Enter the exact model identifiers your upstream server exposes (for example, `meta-llama/Llama-3.3-70B-Instruct` or `qwen3:8b`). > 📝 **NOTE** > > For the OpenAI, Google AI, and AWS Bedrock provider types, AI Gateway validates that the credential references resolve before it accepts the create or update. AI Gateway rejects a missing or empty secret reference at save time instead of failing at first call. The OpenAI-compatible type does not require a credential reference, so it can be created with no authentication for local runtimes such as Ollama or vLLM. ## [](#select-models)Select models Models you select on this form become the catalog the provider exposes. For **OpenAI**, **Anthropic**, **Google AI**, and **AWS Bedrock**, the form shows a picker backed by the provider’s catalog, with the full catalog selected by default. Keep the default, or deselect models to narrow what the provider exposes. Each model in the picker shows its input and output price per million tokens. Pick from the list, or type a model identifier the catalog doesn’t show. For **OpenAI-compatible**, the form takes a freeform list: type the exact identifiers your upstream serves. Redpanda maintains the catalog of available models in the picker. When an upstream provider publishes a new model, it usually appears in the picker within a day or two; admins don’t have to wait for a Redpanda release. New models aren’t enabled automatically: an admin still selects the model in the catalog to make it callable through this provider. For Bedrock, the picker exposes inference profiles, not raw foundation-model IDs. See [AWS Bedrock: Inference profiles and IAM](#bedrock-inference-profiles). > 📝 **NOTE** > > Redpanda stores models as structured `ProviderModel` entries (one entry per model, with the model name as the only required field). Each model can carry custom pricing overrides that replace the catalog rates for that model in cost reporting; see [Override per-model pricing](#pricing-overrides). The legacy flat `models` field still works on writes for backward compatibility. Beyond pricing, the catalog carries each model’s capabilities and context-window limits. The model discovery API (the `ListModels` and `GetModel` methods on `ModelService`) reports `max_input_tokens` (the largest context the model accepts) and `max_output_tokens` (the most it can generate in a single response) for each model. Both are read-only catalog metadata: a limit the catalog doesn’t declare stays unset rather than reported as zero. Clients read `max_input_tokens` to show how full an agent’s context window is, such as the context-window indicator on the agent’s **Playground** tab. ### [](#pricing-overrides)Override per-model pricing Cost reporting prices each call at the catalog rates for the model. If your organization negotiates non-standard rates, or you track spend against an internal chargeback rate, override the rates per model on this provider. In the model picker, each selected model carries a pencil icon (Override pricing). Click it to open the pricing dialog for that model. The dialog lists one field per billing bucket, in the same order as the provider’s published rate card: | Bucket | What it bills | | --- | --- | | Input | Per 1M input tokens. Tool-use input also bills at this rate. | | Output | Per 1M output tokens. Reasoning tokens also bill at this rate. | | Cached input | Per 1M tokens read from prompt cache. | | Cache write (5-minute TTL) | Per 1M tokens written to a 5-minute prompt cache. | | Cache write (1-hour TTL) | Per 1M tokens written to a 1-hour prompt cache. | Enter rates in dollars per million tokens. Each field is independent: - Leave a field blank to keep the catalog rate for that bucket. The catalog rate shows as the field’s placeholder. - Enter a positive value to replace the catalog rate for that bucket only. - Enter `0` to make that bucket explicitly free, which is different from leaving it blank. Cache writes with an unknown TTL always bill at the catalog rate; they have no override field. Use the reset control on a field to clear a single override, or clear every field to drop all overrides for the model. Overrides are scoped to this provider and model, and they change what Agentic Data Plane’s cost reporting computes, not what the upstream provider actually charges you. ## [](#provider-detail-page)Explore the provider detail page After you create the provider, its detail page organizes everything about it into tabs: **Overview**, **Models**, **Connect**, **Playground** (when enabled for your organization), and **Settings**. ### [](#overview)Overview The **Overview** tab opens on a row of stat tiles: **Models enabled** (the models configured on this provider), **Requests** over the last 24 hours, **Spend** over the last 30 days, and **Health** over the last 24 hours, shown with a status indicator that reads healthy, degraded, failing, or idle based on the provider’s recent request and error volume. Below the tiles, a **Gateway traffic** chart plots request and token volume over time next to the **Connection** card. The Connection card shows the provider type, an **Active** or **Disabled** status badge, the authentication passthrough state, the proxy URL, the upstream base URL, the API key secret reference, and any attached guardrail, each with a copy control where relevant. A **Who calls what** card then draws the caller-to-model traffic for a time range you pick with the range selector, and a **Callers** table lists, over the same range, each agent or user that called the provider, with its request count, the models it used, its error count, spend, and when it was last seen. Search the table by caller name, slug, or email, and select a row to open that caller’s details on the **Cost & Usage** page. For analysis across providers, use the **Cost & Usage** page under **Governance** (see [View cost and usage](#view-cost-and-usage)). ### [](#models)Models The **Models** tab lists the chat models available on this provider. Each row shows the model’s name and identifier, icons for the capabilities it supports (such as vision, tools, JSON, or reasoning), its context-window limit, and its input and output prices per million tokens. Hover over a capability icon to read what that capability means. Use the toggle on a row to enable or disable that model on the provider. Select a model to open its detail page (see [View a model’s detail page](#model-detail-page)). Enabled models sort to the top. Use the search box to find a model by display name or identifier, and the **Status** and **Capability** filters to narrow the list. ### [](#connect)Connect The **Connect** tab generates ready-made client configuration for this provider: a gateway-token step, ready-to-run `rpk ai` setup steps, setup instructions for popular clients such as Claude Code, and code examples in several languages, all with the provider’s proxy URL prefilled. For a Bedrock provider, the Claude Code snippets run against the gateway without local AWS credentials, because the gateway signs the upstream AWS requests for you. See [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/) for the underlying flow. ### [](#playground)Playground When the **Playground** tab is available, use it to test one of the provider’s models before you connect application code. Choose a model, send a prompt, and optionally adjust response controls such as reasoning effort and maximum output tokens. The response streams into the conversation while the Playground shows the request, response events, status, and timing. Playground conversations are ephemeral. ![LLM Playground test loop. A user selects a model, writes a prompt, and chooses response controls. AI Gateway translates and sends the request to the configured provider, streams the response back, and exposes request details, response events, status, and timing in the Playground.](https://docs.redpanda.com/agentic-data-plane/gateway/_images/llm-playground-test-loop.svg) Figure 1. Playground turns a model test into an inspectable gateway request ### [](#settings)Settings The **Settings** tab is where you edit the provider after you create it. It is organized into sections: - **General**: Edit the display name. The provider type and resource ID are fixed after creation and shown read-only. - **Credential**: Change how the gateway authenticates to the upstream provider. To rotate a stored key’s value for every provider that uses it, follow the link to **Provider keys** in the Secret Store. - **Connection**: The read-only proxy URL and the editable upstream base URL. Use **Test connection** to confirm the provider is reachable before you save. - **Models**: Choose which models this provider exposes to agents and developers. - **Transcripts**: Turn message-body recording on or off (see [Configure transcript logging](#transcript-logging)). When you change a field, a save bar appears with **Save changes** and **Discard**. Below the form, an enable/disable control stops or resumes routing without deleting anything, and a **Delete this provider** danger zone permanently removes the provider after you confirm. ### [](#model-detail-page)View a model’s detail page From the **Models** tab, select a model to open its detail page. The page gathers what the catalog knows about that model on this provider in one place: - An overview strip with the model’s context window (largest input it accepts), maximum output (most it can generate in a single response), and price (input and output rates per million tokens). Each value appears only when the catalog declares it. - Model details: The model ID and the provider’s proxy URL, each with a copy control. - Pricing: A read-only rate card of the model’s effective per-bucket rates, that is, the catalog rates with any per-model overrides applied (see [Override per-model pricing](#pricing-overrides)). This section appears only when rates are known, and links to the upstream provider’s pricing reference. - Capabilities: The model’s capabilities from the catalog, with a link to the upstream provider’s capabilities reference. This section appears only when the catalog declares capabilities. - Usage: Spend, Requests, and Tokens cards for traffic routed to this model through this provider over the last 7 days. Select **View more** on a card to open a metric detail drawer. ## [](#transcript-logging)Configure transcript logging The **Transcripts** section on the provider’s **Settings** tab controls whether AI Gateway records the message bodies this provider proxies. It has two independent toggles, both off by default: | Toggle | What it captures | | --- | --- | | Record inputs | Captures the full request body (prompt content and tool-call arguments) on observability traces. | | Record outputs | Captures the full response body (completion content and tool-call results) on observability traces. | Because both toggles default to off, AI Gateway does not retain message bodies for a new provider until you turn them on. Enable them to power turn-by-turn investigation and per-conversation drill-down in [the Transcripts view](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/). Leave them off for workloads where the message body must not be retained, such as regulated PII or customer secrets. These are per-provider settings, not per-request: applications cannot opt in or out at call time. To split sensitive from non-sensitive traffic, create one provider with recording on and another with it off, and route each application to whichever proxy URL matches its data class. Recording settings do not affect cost and usage telemetry. Token counts, latency, and provider/model attribution are always recorded, so the **Cost & Usage** page reports spend for traffic on the provider regardless of these toggles; only the message bodies are withheld when the toggles are off. > 📝 **NOTE** > > Changing a toggle takes effect for new requests. Transcripts already captured under the previous setting are not retroactively redacted; delete or rotate the provider if you need to purge historical content. ## [](#save-and-verify)Save and verify 1. Click **Create provider**. Until the form is complete, the button stays disabled and the hint next to it tells you what’s still needed (for example, saving the new key). 2. After create, you land on the provider’s **Connect** tab, with client setup instructions and code examples that have the proxy URL prefilled. To copy the proxy URL on its own, open the **Overview** tab and use the copy control on the Connection card. The proxy URL is where your applications point. 3. To confirm the provider is reachable, open the **Settings** tab and click **Test connection** in the **Connection** section. The result appears as a message below the button. 4. To wire up an application, use the **Connect** tab or follow [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/). A successful **Test connection** result confirms that the provider’s credentials, region (Bedrock), and network path are all correct. If the call fails, see [Troubleshooting](#troubleshooting). ## [](#bedrock-inference-profiles)AWS Bedrock: Inference profiles and IAM Bedrock has three concepts that affect how you configure a provider: foundation models, cross-region inference profiles, and IAM. Get these right and the **Test connection** check passes. Get them wrong and you see `AccessDenied` or `ValidationException` errors. ### [](#foundation-models-versus-inference-profiles)Foundation models versus inference profiles A **foundation model** is the base model AWS exposes (for example, `anthropic.claude-sonnet-4-6`). It runs in the AWS region you call. A **cross-region inference profile** wraps a foundation model with a geography prefix that routes requests across multiple regions for higher availability and throughput. The prefix tells AWS which geography the request should run in: | Prefix | Geography | | --- | --- | | us. | US regions | | eu. | EU regions | | apac. | Asia-Pacific regions | | au. | Australia regions | | jp. | Japan regions | | global. | Any region; routes for lowest cost | Examples: `us.anthropic.claude-sonnet-4-6` (Claude Sonnet 4.6 routed across US regions), `eu.anthropic.claude-haiku-4-5` (Haiku 4.5 routed across EU regions). > ❗ **IMPORTANT** > > Anthropic Claude 4.6+ models (Sonnet 4.6, Opus 4.6, Opus 4.7) cannot be invoked with the bare foundation-model ID; they require an inference profile. If you try the bare ID, Bedrock returns: > > "Invocation of model ID … with on-demand throughput isn’t supported. Retry your request with the ID or ARN of an inference profile that contains this model." > > Older 4.5 and earlier Claude models still accept bare IDs. Pricing varies by profile. The bare foundation-model ID and the `global.` profile share AWS’s headline rate; geo profiles (`us.`, `eu.`, `apac.`, `au.`, `jp.`) carry approximately a 10% cross-region inference premium. Use `global.` when you want the headline rate and don’t need a specific geography. Use `us.` / `eu.` / `apac.` when data residency matters. AI Gateway preserves the regional prefix end to end when it records spend, so the **Cost & Usage** page attributes usage to the correct regional rate. A call to `eu.anthropic.claude-haiku-4-5` is billed at the EU Haiku rate, not the headline foundation-model rate. ### [](#iam-policy-patterns)IAM policy patterns Bedrock IAM resources have different ARN structures depending on whether you reference a foundation model, a system-defined inference profile, or an account-scoped application inference profile. The provider’s IAM principal needs `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` on every resource it calls. | Resource type | ARN shape | | --- | --- | | Foundation model | arn:aws:bedrock:{region}::foundation-model/{model-id} (no account ID; AWS-owned) | | System-defined inference profile | arn:aws:bedrock:{region}:*:inference-profile/{profile-id} (wildcard account; system-defined) | | Application inference profile (account-scoped) | arn:aws:bedrock:{region}:{account-id}:application-inference-profile/{profile-id} | A minimal policy granting access to all foundation models plus all cross-region profiles: ```json { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"], "Resource": [ "arn:aws:bedrock:*::foundation-model/*", "arn:aws:bedrock:*:*:inference-profile/*" ] }] } ``` For production, scope to specific models and regions instead of using wildcards. ## [](#anthropic-authorization-passthrough)Anthropic: Authorization passthrough If you want each client to authenticate against Anthropic with its own subscription (Claude Pro, Max, Team, or enterprise), enable `Authorization passthrough` instead of configuring a server-side API key. In this mode: - Leave the `API key` field empty. - Clients must send their own Anthropic `Authorization` header with every request. AI Gateway forwards it unchanged. - Use this when you want to aggregate individual client subscriptions rather than share a single API account. The provider detail page shows whether Authorization passthrough is enabled in the Connection card. ## [](#browse-providers-in-the-list-view)Browse providers in the list view The **LLM Providers** list page is the at-a-glance home for every provider in your dataplane. Open it from the sidebar’s **LLM Providers** entry. | Column | What it shows | | --- | --- | | Provider | The provider-type icon (OpenAI, Anthropic, Google, AWS Bedrock, or OpenAI-compatible), the display name, and the resource identifier beneath it. Select the provider name to open its detail page. | | Status | Active for an enabled provider. A disabled provider rejects requests to its proxy URL until you enable it again. | | Models | The model identifiers configured on the provider, shown as chips. A provider with no models configured shows a dash. | | 24h requests | Request count over the last 24 hours. | | 30d spend | Spend over the last 30 days. For longer-range or cross-provider analysis, use the Cost & Usage page under Governance (see View cost and usage). | Use the search box to find a provider by name, and the **Filter** button to narrow the list by provider type, model, or status. The **Add provider** button opens the create flow described in [Open the Create LLM provider page](#open-the-create-llm-provider-page). Each row’s actions menu can activate or deactivate the provider, copy its proxy or base URL, or delete it. The list paginates, with a rows-per-page selector in the footer. ## [](#view-cost-and-usage)View cost and usage The **Cost & Usage** page under **Governance** tracks spend, request volume, and token volume over time across providers, models, agents, and users, with period comparisons and CSV export. This report moved to its own page: see [Analyze Cost and Usage](https://docs.redpanda.com/agentic-data-plane/control/cost-usage/). ## [](#edit-disable-or-delete-a-provider)Edit, disable, or delete a provider - **Edit**: Open the **Settings** tab and change any field except the provider type and resource ID, which are immutable after creation. The display name, credential reference, base URL, and model list can all change. When you edit a field, a save bar appears; click **Save changes** to apply your edits. - **Disable**: On the **Settings** tab, click **Disable provider** and confirm. The provider remains in the list, but requests to its proxy URL are rejected until you enable it again. Use this when you want to pause traffic without losing configuration. - **Delete**: On the **Settings** tab, use the **Delete this provider** danger zone, click **Delete provider**, and type `delete` to confirm. The action is permanent. In-flight requests fail and downstream clients receive errors until reconfigured. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | secret "" not found | Confirm the secret exists in your dataplane’s secret store and the reference in the provider configuration is spelled identically (UPPER_SNAKE_CASE, no typos). | | Bedrock returns AccessDenied or region errors | Verify the AWS region field matches the region where your Bedrock models are enabled. Bedrock model availability varies by region. Confirm the IAM principal has bedrock:InvokeModel on the foundation-model and inference-profile ARNs you use. See AWS Bedrock: Inference profiles and IAM. | | Bedrock returns "Invocation of model ID … with on-demand throughput isn’t supported" | You called a Claude 4.6+ model with a bare foundation-model ID. Switch to an inference profile (for example, us.anthropic.claude-sonnet-4-6 instead of anthropic.claude-sonnet-4-6). See AWS Bedrock: Inference profiles and IAM. | | Anthropic returns 401 when passthrough is enabled | Confirm the client is sending its own Authorization header and the API key field on the provider is empty. | | Gemini returns 401 | Gemini uses the x-goog-api-key header, not Authorization. If you’re seeing 401s on Gemini, check that the client is sending the correct header. See Connect your app to AI Gateway. | | Provider list empty or 403 | Confirm your account can act on LLM providers. Listing them needs Action::"LLMProvider.list" and creating one needs Action::"LLMProvider.create". Outside the Admin role, both come from an access policy. See LLM provider permissions. | ## [](#limitations)Limitations AI Gateway does not provide these capabilities. For current status, see the [Agentic Data Plane release notes](https://docs.redpanda.com/agentic-data-plane/reference/release-notes/). - **Multi-provider routing, failover, and retries across providers.** A synthetic provider that fans requests to multiple upstreams is not part of AI Gateway. - **Rate limits.** Requests-per-second, per-minute, or per-day limits are not available. To cap spend rather than request rate, use [budgets](https://docs.redpanda.com/agentic-data-plane/control/budgets/), which enforce a per-agent hard cap. - **Managed MCP aggregation at the gateway.** Register MCP tool servers separately under **MCP Servers** in Agentic Data Plane. ## [](#next-steps)Next steps - [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/) - [Set up budgets](https://docs.redpanda.com/agentic-data-plane/control/budgets/) --- # Page 67: Connect Your App to AI Gateway **URL**: https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent.md --- # Connect Your App to AI Gateway > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Connect Your App to AI Gateway latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: connect-agent page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: connect-agent.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/gateway/pages/connect-agent.adoc description: Point your application or AI agent at an AI Gateway provider's proxy URL. Covers the URL shape, the local development workflow with rpk ai, the OIDC client-credentials flow for CI and application code, and SDK examples for OpenAI, Anthropic, Google AI, AWS Bedrock, and OpenAI-compatible endpoints. page-topic-type: how-to personas: agent_builder learning-objective-1: Construct the proxy URL for an LLM provider you have configured learning-objective-2: Authenticate to AI Gateway with the rpk ai CLI for local development or with OIDC client credentials for CI and programmatic clients learning-objective-3: Send requests through the proxy URL with the SDK of your choice page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-10" --- This guide shows how to connect your [AI agent](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#ai-agent) or application to the AI Gateway. You construct the proxy URL for a provider you have already created, authenticate (with the [`rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) CLI for local development or with OIDC client credentials for CI and application code), and send your first request with the SDK of your choice. > 💡 **TIP** > > The provider’s **Connect** tab in Agentic Data Plane generates this configuration for you: a gateway-token step, setup instructions for popular clients, and code examples with the provider’s proxy URL prefilled. Copy from the tab for a quick start, or follow this page for the full flow. After completing this guide, you will be able to: - Construct the proxy URL for an LLM provider you have configured - Authenticate to AI Gateway with the `rpk ai` CLI for local development or with OIDC client credentials for CI and programmatic clients - Send requests through the proxy URL with the SDK of your choice ## [](#prerequisites)Prerequisites - A configured LLM provider. If you haven’t created one yet, see [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/). - For local development, nothing else. You’ll install `rpk ai` in the next section. - For CI or programmatic clients: Your agent’s service account client ID and a client secret, issued from the agent’s **Credentials** tab. See [Service account authorization](https://docs.redpanda.com/agentic-data-plane/connect/concepts/#service-account-authorization). To register an agent and issue credentials, see [Set Up a Self-Managed Agent](https://docs.redpanda.com/agentic-data-plane/connect/self-managed-agents/). - A development environment with your chosen programming language. ## [](#proxy-url-anatomy)Proxy URL anatomy Every provider you create in AI Gateway gets its own proxy URL: ```text /llm/v1/providers// ``` - ``: The AI Gateway base URL for your dataplane. Cluster-specific subdomain on `clusters.rdpa.co` (for example, `[https://aigw..clusters.rdpa.co](https://aigw.\.clusters.rdpa.co)`). Copy the exact value from the `Proxy URL` field on any provider’s Connection card. - ``: The name you gave the provider when you created it, for example `my-openai` or `prod-anthropic`. - ``: The upstream provider’s native API path (for example, `v1/chat/completions` for OpenAI, `v1/messages` for Anthropic). AI Gateway forwards the request to the upstream provider, attaches the configured credentials, and records the request for observability. Your application never sees the upstream API key. > 💡 **TIP** > > The provider detail page generates ready-to-run snippets pre-filled with the correct proxy URL and paths. When in doubt, copy from the Connect your app section there. ## [](#authenticate-with-rpai)Use `rpk ai` for local development The [`rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) command is the Redpanda AI CLI. Use it to manage AI Gateway resources (LLM providers, MCP servers, OAuth providers) and call MCP tools from the command line. `rpk ai` is self-contained: it has its own login and its own Agentic Data Plane environment selection, independent of any `rpk cloud` session. 1. [Install `rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-install/): ```bash rpk ai install ``` Update later with [`rpk ai upgrade`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-upgrade/); remove with [`rpk ai uninstall`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-uninstall/). > 📝 **NOTE** > > Upgrading `rpk` does not upgrade the plugin. The plugin is a separate binary that stays at its installed version, even across `rpk` upgrades, until you run `rpk ai upgrade`. New commands and flags in the reference marked "introduced in ai version X" require the plugin at that version or later. 2. Sign in. This runs an OAuth device-authorization flow in your browser, caches credentials in `~/.rpai/credentials` (readable only by you), then lists the Agentic Data Plane environments in your organization so you can select one: ```bash rpk ai auth login ``` 3. Select the Agentic Data Plane environment whose AI Gateway you want to target. The `rpk ai env use` command accepts an environment name or ID and switches the active environment: ```bash rpk ai env list rpk ai env use ``` Inspect the resolved environment and token state at any time with `rpk ai env show` and `rpk ai auth status`. 4. Verify the connection: ```bash rpk ai llm-provider list ``` If the cached token has expired, `rpk ai` returns a 401; rerun `rpk ai auth login` to refresh it. > 📝 **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 AI Gateway URL for a single invocation (for example, a local gateway, or a staging environment the environments list does not include), pass `--rpai-endpoint`: > > ```bash > rpk ai --rpai-endpoint http://localhost:8090 llm-provider list > ``` > > This overrides the selected environment’s AI Gateway URL for that one command, and the flag is not bound to an environment variable. For a manual or local gateway you use repeatedly, define it once as an environment instead: > > ```bash > rpk ai env add local --ai-gateway-url http://localhost:8090 --auth-mode none > rpk ai env use local > ``` ### [](#environment-variables)Environment variables The `rpk ai` command honors the following environment variables: | Variable | Purpose | | --- | --- | | RPAI_TOKEN | Static bearer token for the gateway. rpk ai normally manages its own token through rpk ai auth login; set this (or pass --token) to override, for example in a headless or CI shell. | | RPAI_CONFIG, RPAI_VERBOSE, RPAI_FORMAT | Map to --rpai-config, --rpai-verbose, --format (short flags -c, -v, -o). Long flag names are renamed under rpk ai to avoid collision with rpk’s globals. There is no environment variable for environment selection (use `--rpai-environment or rpk ai env use) or for the AI Gateway URL override (use the --rpai-endpoint flag). | ## [](#authenticate-with-oidc-client-credentials)Authenticate with OIDC client credentials (CI and programmatic) For application code, CI runners, server-side processes, and headless agents, use the OIDC `client_credentials` grant directly. This is the canonical authentication path for SDK-style usage; `rpk ai` is for command-line workflows, not for embedding in application code. Values are surfaced on the provider’s Connection card; defaults at the time of writing are below. | Parameter | Value (today) | | --- | --- | | Discovery URL | https://auth.prd.cloud.redpanda.com/.well-known/openid-configuration. Also surfaced as the Discovery field on the provider’s Connection card. | | Token endpoint | https://auth.prd.cloud.redpanda.com/oauth/token | | Audience | cloudv2-production.redpanda.cloud | | Grant type | client_credentials | #### cURL ```bash AUTH_TOKEN=$(curl -s --request POST \ --url 'https://auth.prd.cloud.redpanda.com/oauth/token' \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=client_credentials \ --data client_id= \ --data client_secret= \ --data audience=cloudv2-production.redpanda.cloud | jq -r .access_token) ``` Replace `` and `` with your service account credentials. #### Python (authlib) ```python from authlib.integrations.requests_client import OAuth2Session import requests # Discover token endpoint from OIDC metadata metadata = requests.get( "https://auth.prd.cloud.redpanda.com/.well-known/openid-configuration" ).json() token_endpoint = metadata["token_endpoint"] client = OAuth2Session( client_id="", client_secret="", token_endpoint=token_endpoint, ) token = client.fetch_token( grant_type="client_credentials", audience="cloudv2-production.redpanda.cloud", ) access_token = token["access_token"] ``` Passing `token_endpoint` to the `OAuth2Session` constructor lets `authlib` handle renewal automatically. For `client_credentials` grants, it fetches a new token rather than using a refresh token. #### Node.js (openid-client) ```javascript import { Issuer } from 'openid-client'; const issuer = await Issuer.discover( 'https://auth.prd.cloud.redpanda.com' ); const client = new issuer.Client({ client_id: '', client_secret: '', }); const tokenSet = await client.grant({ grant_type: 'client_credentials', audience: 'cloudv2-production.redpanda.cloud', }); const accessToken = tokenSet.access_token; ``` ### [](#token-lifecycle-management)Token lifecycle management > ❗ **IMPORTANT** > > Your client is responsible for refreshing tokens before they expire. OIDC access tokens have a limited TTL set by the identity provider and are not automatically renewed by AI Gateway. Check the `expires_in` field in the token response for the exact duration. - Proactively refresh at ~80% of the token’s TTL to avoid failed requests. - `authlib` (Python) handles renewal automatically when you pass `token_endpoint` to `OAuth2Session`. - For other languages, cache the token and its expiry, then request a new token before the current one expires. - For SDK code, refresh OIDC client-credentials tokens through your client library (see the `authlib` example above). ## [](#send-requests-with-your-sdk)Send requests with your SDK The examples in this section assume you’ve set: ```bash export PROXY_URL="/llm/v1/providers/" export AUTH_TOKEN="" # from the client_credentials flow above ``` ### OpenAI SDK ```python import os from openai import OpenAI client = OpenAI( base_url=os.environ["PROXY_URL"], # .../llm/v1/providers/my-openai api_key=os.environ["AUTH_TOKEN"], # OIDC access token ) response = client.chat.completions.create( model="gpt-4o", # native OpenAI model ID messages=[{"role": "user", "content": "Hello from AI Gateway"}], ) print(response.choices[0].message.content) ``` The OpenAI SDK calls the proxy’s `/v1/chat/completions` path, which AI Gateway forwards to OpenAI unchanged. Use it with any OpenAI provider and, with a different `base_url`, with any OpenAI-compatible provider (vLLM, Ollama, LM Studio, Together, Groq, OpenRouter). ### Anthropic SDK ```python import os from anthropic import Anthropic client = Anthropic( base_url=os.environ["PROXY_URL"], # .../llm/v1/providers/my-anthropic auth_token=os.environ["AUTH_TOKEN"], # OIDC access token ) message = client.messages.create( model="claude-sonnet-4-6", max_tokens=1024, messages=[{"role": "user", "content": "Hello from AI Gateway"}], ) print(message.content[0].text) ``` The Anthropic SDK hits `v1/messages` on the proxy, which AI Gateway forwards to Anthropic. If the provider is configured with `Auth passthrough`, send your own Anthropic `Authorization` header instead of an `auth_token`. AI Gateway forwards it unchanged. ### Google Gemini SDK ```python import os from google import genai client = genai.Client( api_key=os.environ["AUTH_TOKEN"], # forwarded as x-goog-api-key http_options={"base_url": os.environ["PROXY_URL"]}, # .../llm/v1/providers/my-google ) response = client.models.generate_content( model="gemini-2.0-flash", contents="Hello from AI Gateway", ) print(response.text) ``` > ❗ **IMPORTANT** > > Gemini authenticates with the `x-goog-api-key` header, not `Authorization: Bearer`. Most Google SDKs set `x-goog-api-key` automatically from the `api_key` parameter. If you hand-roll the request, set the header yourself. ### AWS Bedrock Bedrock is different: SigV4 signing is performed **server-side** by AI Gateway using the credentials on the provider. Your client only needs to call the proxy URL with an OIDC access token. ```python import os, httpx # Bedrock 4.6+ Anthropic models require an inference profile (us./eu./apac./global.). # Replace with the inference profile your provider exposes. response = httpx.post( f"{os.environ['PROXY_URL']}/model/us.anthropic.claude-sonnet-4-6/invoke", headers={"Authorization": f"Bearer {os.environ['AUTH_TOKEN']}"}, json={ "anthropic_version": "bedrock-2023-05-31", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 1024, }, ) print(response.json()) ``` See [the Bedrock provider reference](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/#bedrock-inference-profiles) for inference-profile selection guidance. > 💡 **TIP** > > Bedrock’s `Converse` API works the same way: send to `/model/{MODEL_ID}/converse` with a Converse-shaped body. Or use the AWS SDK’s `bedrockruntime` client and set its `BaseEndpoint` to the proxy URL; the SDK signs the request, AI Gateway re-signs server-side with the provider’s credentials, and your client never sees AWS keys. ### OpenAI-compatible Use the OpenAI SDK with the proxy URL of the OpenAI-compatible provider and whatever model identifier the upstream exposes: ```python import os from openai import OpenAI client = OpenAI( base_url=os.environ["PROXY_URL"], # .../llm/v1/providers/my-vllm api_key=os.environ["AUTH_TOKEN"], ) response = client.chat.completions.create( model="meta-llama/Llama-3.3-70B-Instruct", # as exposed by your upstream messages=[{"role": "user", "content": "Hello"}], ) ``` > 📝 **NOTE** > > The provider detail page also has client guides for **Claude Code**, **Codex**, and **Gemini** (the desktop client). Open **Connect your app** on the provider’s page to see the per-client setup instructions. ## [](#group-requests-into-transcripts)Group requests into transcripts AI Gateway groups a session’s LLM calls and MCP tool calls into a single transcript using the `X-Redpanda-Genai-Conversation` request header. Stamp this header with your framework’s session or thread ID, using the same value on every request in the session, and the gateway maps it to the `gen_ai.conversation.id` attribute on each span so the spans group into one conversation. This header is required for the agent’s **Transcripts** tab to populate. Without it, the gateway drops the spans and the tab stays empty. The header doesn’t affect authentication or whether requests succeed. Set it through your SDK’s default-headers mechanism so it rides along with both the LLM call and each MCP tool call: ```python import os from openai import OpenAI client = OpenAI( base_url=os.environ["PROXY_URL"], api_key=os.environ["AUTH_TOKEN"], default_headers={"X-Redpanda-Genai-Conversation": session_id}, ) ``` Replace `session_id` with the session or thread identifier your framework already tracks, and stamp the same value on the session’s MCP tool calls so the whole turn groups into one transcript. For how transcripts read this attribute, see [View agent transcripts](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/). ## [](#streaming-responses)Streaming responses Streaming passes through unchanged. Use the SDK’s native streaming API; the proxy forwards the stream byte-for-byte. ```python response = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "Write a short poem"}], stream=True, ) for chunk in response: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True) ``` ## [](#handle-errors)Handle errors AI Gateway returns standard HTTP status codes. The upstream provider’s error body passes through, so your existing SDK error handling works: | Status | Meaning | | --- | --- | | 400 | Bad request. Invalid parameters or malformed JSON. | | 401 | Authentication failed. Token invalid, expired, or (for Gemini) sent in the wrong header. | | 403 | Forbidden. Nothing grants the service account this action, or the provider is disabled. | | 404 | Provider or model not found. Verify the provider name in the URL and the model identifier. | | 429 | Rate limited by the upstream provider. AI Gateway does not enforce its own rate limits today. Respect Retry-After if present. | | 5xx | Upstream or gateway error. Retry with exponential backoff. | ## [](#best-practices)Best practices - Use environment variables for the proxy URL and token. Never hard-code them. - Refresh OIDC tokens through your client library so refresh is invisible to your SDK code (`authlib` for Python, `openid-client` for Node.js, and so on). - 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. - Observe usage in Redpanda Agentic Data Plane on each provider’s detail page. ## [](#troubleshooting)Troubleshooting ### [](#401-unauthorized)401 Unauthorized - If you’re using `rpk ai`: Rerun `rpk ai auth login` to refresh the credentials. Token expiry surfaces as a 401. - If you’re using OIDC client credentials: Check the token hasn’t expired and refresh it. Verify the audience is `cloudv2-production.redpanda.cloud` and the `Authorization` header is formatted `Bearer `. - For Gemini: Ensure the token is sent as `x-goog-api-key`, not `Authorization`. - For Anthropic with passthrough: Ensure the client is sending a valid Anthropic `Authorization` header. ### [](#404-not-found)404 Not found - Re-check the provider name in the proxy URL. The segment after `/providers/` must match the provider’s `Name` exactly. - For model-not-found: Confirm the model identifier is one your provider’s catalog actually serves. OpenAI-compatible endpoints accept whatever model IDs the upstream exposes. ### [](#403-forbidden)403 Forbidden - The service account may lack the required access. Ask an admin for an [access policy](https://docs.redpanda.com/agentic-data-plane/control/access-policies/) that names the service account as its principal and grants `Action::"LLMProvider.invoke"`, plus `Action::"LLMProvider.get"` if the account also reads provider config. No built-in role short of Admin grants these. See [LLM provider permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#llm-provider-permissions). - The provider may be disabled. Check the `Status` field on its Connection card. ### [](#connection-timeout-or-reset)Connection timeout or reset - Verify the proxy URL is correct (copy directly from the provider’s Connection card). - Check that the provider isn’t pointing at a private base URL your client can’t reach (OpenAI-compatible providers only). - Confirm the upstream provider’s status page. ## [](#next-steps)Next steps - [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/) --- # Page 68: How AI Gateway Works **URL**: https://docs.redpanda.com/agentic-data-plane/gateway/overview.md --- # How AI Gateway Works > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: How AI Gateway Works latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: overview page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: overview.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/gateway/pages/overview.adoc description: AI Gateway is Agentic Data Plane's managed proxy for LLM APIs. Create a provider for OpenAI, Anthropic, Google AI, AWS Bedrock, or an OpenAI-compatible endpoint, and point your applications at a Redpanda-hosted URL with managed secrets, authentication, and observability. page-topic-type: overview personas: agent_builder, platform_engineer, security_compliance_lead learning-objective-1: Describe what AI Gateway is and how a managed proxy differs from direct upstream calls learning-objective-2: Explain how LLM providers, secrets, and OIDC authentication fit together in AI Gateway learning-objective-3: Identify use cases where AI Gateway fits, and use cases where it does not page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-10" --- AI Gateway is Redpanda Agentic Data Plane’s managed proxy for LLM APIs. Instead of giving every application a provider API key and letting it call the upstream directly, you create an **LLM provider** in Agentic Data Plane and point your applications at a Redpanda-hosted proxy URL. Redpanda handles the upstream credentials, forwards the request, and records usage. Your code continues to use the provider’s native SDK. After reading this page, you will be able to: - Describe what AI Gateway is and how a managed proxy differs from direct upstream calls - Explain how LLM providers, secrets, and OIDC authentication fit together in AI Gateway - Identify use cases where AI Gateway fits, and use cases where it does not ## [](#the-problem-ai-gateway-solves)The problem AI Gateway solves Teams adopting LLMs can quickly hit operational problems: - **Credential sprawl:** Every team that touches an LLM gets its own API key. Rotation is manual, offboarding is manual, and it’s hard to know who’s using what. - **SDK lock-in and switching cost:** Each provider has its own SDK, authentication scheme, and model catalog. Swapping OpenAI for Anthropic means a code change, not a configuration change. - **No shared view of usage:** Provider dashboards tell you what a single API key spent. They don’t tell you what your organization spent, broken down by team or application. ![AI Gateway connection flow. An administrator configures an LLM provider with its upstream endpoint, credentials, and allowed models. Local developers connect with rpk ai and deployed applications or self-managed agents use OAuth client credentials. AI Gateway authenticates, routes, applies policy, and records usage before calling the upstream model provider.](https://docs.redpanda.com/agentic-data-plane/gateway/_images/ai-gateway-connection-flow.svg) Figure 1. Configure a provider once, then route every client through one governed AI Gateway path ## [](#what-ai-gateway-gives-you)What AI Gateway gives you AI Gateway consolidates provider access behind the following capabilities. ### [](#traffic-stays-in-your-vpc)Traffic stays in your VPC LLM requests are proxied through your dataplane’s AI Gateway. API keys are stored in your dataplane’s secret store and never leave your infrastructure. Upstream calls leave your VPC only when the LLM provider is third-party (OpenAI, Anthropic, Google AI). Self-hosted OpenAI-compatible endpoints stay entirely inside your network. ### [](#centralized-secrets)Centralized secrets The upstream API key (or AWS credentials for Bedrock) lives in the Redpanda secret store and is attached to the provider at configuration time. Your application never sees it; rotation happens in one place. ### [](#a-managed-proxy-url-per-provider)A managed proxy URL per provider Every provider you create has its own URL of the form `/llm/v1/providers//`. Your application points its SDK at this URL instead of the upstream, continues to use the provider’s native API, and authenticates to Redpanda with a short-lived OIDC access token. The gateway base is a cluster-specific subdomain (for example, `aigw..clusters.rdpa.co`). Copy the exact value from the `Proxy URL` field on any provider’s detail page. ### [](#native-sdk-compatibility)Native SDK compatibility Use the provider’s own SDK: OpenAI, Anthropic, Google AI, AWS Bedrock, or any OpenAI-compatible client (vLLM, Ollama, LM Studio, LocalAI, Together, Groq, OpenRouter). AI Gateway does not require a single unified SDK. It forwards native requests to the native upstream. ### [](#managed-authentication)Managed authentication Applications authenticate to Agentic Data Plane with OIDC service accounts instead of long-lived provider API keys. Service accounts use the same role and audit model as every other Agentic Data Plane resource, and mint short-lived tokens that are easy to revoke. For local command-line workflows, use [`rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) to sign in (`rpk ai auth login`) and talk to the gateway. CI and programmatic clients use the OIDC client-credentials grant directly. See [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/). ### [](#per-provider-observability)Per-provider observability The provider’s detail page in Agentic Data Plane records spend, request counts, and token counts for the last 7 days. The **Cost & Usage** page under **Governance** expands that view with time-series charts, provider and model grouping, date ranges, and filters for provider, model, cost type, token type, user, and agent. ## [](#whats-in-the-ui)What’s in the UI In Agentic Data Plane ([ai.redpanda.com](https://ai.redpanda.com)) you’ll find these areas: - **Home**: The landing page after sign-in. A snapshot of items that need attention (such as a budget over its cap or a disabled resource, with quick actions to resolve them), recent request and spend activity, budget status, and counts of your Agentic Data Plane resources with quick links into each area. - **Agents**: Create and manage Redpanda-hosted agents and registered self-managed agents. - **Guardrails**: Define content policies, word filters, and PII rules that apply to traffic on a Bedrock provider. - **LLM Providers**: Create, edit, enable, and delete providers. This is the home of AI Gateway configuration. - **MCP Servers**: Register [MCP](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#model-context-protocol-mcp) tool servers for agents. Separate from the AI Gateway proxy URL. - **My Connections**: Each user’s own per-user OAuth connections to the configured providers. - **Integrations setup**: Admin home for the OAuth plumbing behind MCP tools. The **Outbound providers** tab registers upstream identity providers for user-delegated MCP authentication (for example, GitHub or Google); the **Inbound clients** tab registers external tools (Claude.ai, ChatGPT, Cursor) that request access tokens from the gateway. - **Secrets Store**: Create and manage the secrets that providers, MCP servers, and agents reference by name. - **Governance**: The **Cost & Usage** page for spend, request, and token analysis across providers, models, and agents, and the **Budgets** page for per-agent spend caps. LLM Providers is where you configure provider settings. The others are covered by their own docs. ## [](#supported-providers)Supported providers AI Gateway supports the following provider types. The UI labels and short descriptions match the picker on the **Create LLM provider** page. | Type | Typical upstream | | --- | --- | | OpenAI | Proxy GPT, o-series, and embeddings through the OpenAI API. Best when you already hold an OpenAI API key or want the broadest GPT model catalog. | | Anthropic | Call Claude Opus, Sonnet, and Haiku directly. Optionally forwards the client’s Authorization header for enterprise and Max-plan subscription passthrough. | | Google AI | Reach Gemini Pro, Flash, and multimodal models through Google AI Studio. Ideal for long-context workloads and image/video inputs. | | AWS Bedrock | Invoke foundation models (Claude, Llama, Titan, Nova) hosted inside your AWS account. Use when data residency, IAM, or VPC egress matter more than raw feature parity. Signed with SigV4 server-side by AI Gateway. | | OpenAI-compatible | Point at any OpenAI-compatible endpoint (vLLM, Ollama, LM Studio, LocalAI, Together, Groq, OpenRouter). Useful for self-hosted models and aggregator gateways that ship /v1/chat/completions. | See [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/) for the full form reference for each type. ## [](#when-to-use-ai-gateway)When to use AI Gateway AI Gateway is a good fit when you want to: - Pull provider API keys out of application code and manage them centrally. - Keep LLM traffic inside your dataplane’s VPC and your secrets out of application code. - Authenticate applications to LLMs using the same OIDC identity you use for other Agentic Data Plane resources. - Run a self-hosted OpenAI-compatible endpoint (vLLM, Ollama, LM Studio) alongside 1P providers behind a single management plane. - Separate operator and developer roles. Operators configure providers and credentials; developers point at proxy URLs. It is not the right fit when you: - Only ever call a single provider with a single API key and are happy managing that key inline. - Need routing, failover, or cross-provider load balancing across providers. AI Gateway does not provide these capabilities. ## [](#out-of-scope)Limitations AI Gateway does not provide these capabilities. For current status, see the [Agentic Data Plane release notes](https://docs.redpanda.com/agentic-data-plane/reference/release-notes/). - **Multi-provider routing, failover, and retries.** A synthetic provider that fans requests to multiple upstreams is not part of AI Gateway. - **Rate limits.** Requests-per-second, per-minute, or per-day caps are not available. To cap spend rather than request rate, use [budgets](https://docs.redpanda.com/agentic-data-plane/control/budgets/), which enforce a per-agent hard cap. - **Managed MCP aggregation at the gateway.** Register MCP tool servers separately under **MCP Servers** in Agentic Data Plane. ## [](#next-steps)Next steps 1. [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/) 2. [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/) --- # Page 69: Get Started **URL**: https://docs.redpanda.com/agentic-data-plane/get-started.md --- # Get Started > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Get Started latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: index page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/get-started/pages/index.adoc description: Stand up Redpanda Agentic Data Plane and ship your first agent. page-git-created-date: "2026-04-29" page-git-modified-date: "2026-07-24" --- Redpanda’s Agentic Data Plane runs and governs AI agents on your streaming data. Get an overview of the platform, then follow the quickstart that matches your role: agent builders create and test their first agent, and administrators set up the LLM provider that makes agent building possible. - [Redpanda Agentic Data Plane Overview](adp-overview/) Enterprise-grade infrastructure for building, deploying, and governing AI agents at scale with compliance-grade audit trails. - [Agentic Data Plane Quickstart for Agent Builders](agent-builder-quickstart/) Sign in to Redpanda Agentic Data Plane, explore the agents your organization already runs, then build, test, and iterate on your own agent backed by MCP tools. - [Agentic Data Plane Quickstart for Administrators](adp-quickstart/) Set up Redpanda Agentic Data Plane for your organization: configure an LLM provider with a key stored in the platform secret store, verify it, and hand off to your agent builders. --- # Page 70: Redpanda Agentic Data Plane Overview **URL**: https://docs.redpanda.com/agentic-data-plane/get-started/adp-overview.md --- # Redpanda Agentic Data Plane Overview > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Redpanda Agentic Data Plane Overview latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: adp-overview page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: adp-overview.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/get-started/pages/adp-overview.adoc description: Enterprise-grade infrastructure for building, deploying, and governing AI agents at scale with compliance-grade audit trails. page-topic-type: overview personas: agent_builder, platform_engineer, security_compliance_lead, pilot_lead, domain_evaluator learning-objective-1: Identify the key components of Redpanda Agentic Data Plane and their purposes learning-objective-2: Describe how each component addresses enterprise governance and reliability requirements learning-objective-3: Determine whether Redpanda Agentic Data Plane fits your organization's requirements for AI agent deployment page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-10" --- Enterprises spent decades building governance for their human workforce: identity, access control, audit trails, and accountability. They never built the same controls for [AI agents](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#ai-agent). Most agents run with broad credentials, no identity of their own, and no record of what they did, which is why enterprise AI so often stalls before it reaches production. Redpanda Agentic Data Plane closes that gap. Agentic Data Plane is governance infrastructure for enterprise agents: it sits between your agents and your data, gives every agent an identity, mediates every tool call and data access, and records every action so you can replay and audit it. With Agentic Data Plane, you connect agents to all your enterprise data, from real-time event streams to databases and business systems, and run them safely at scale without losing control. Agentic Data Plane builds on open standards, including MCP, OAuth, OpenTelemetry, and the Kafka protocol, so governance sits above your choice of LLM, cloud, or agent framework. You stay free to adopt new models and frameworks as they emerge, without re-platforming or locking into a single vendor. Agentic Data Plane is its own product surface. It runs on Redpanda, so there’s no separate cluster to stand up first: Redpanda provisions the underlying environment when you add Agentic Data Plane. After reading this page, you will be able to: - Identify the key components of Redpanda Agentic Data Plane and their purposes - Describe how each component addresses enterprise governance and reliability requirements - Determine whether Redpanda Agentic Data Plane fits your organization’s requirements for AI agent deployment ## [](#who-runs-each-component)Who runs each component **Managed** and **self-managed** describe runtime ownership, not whether a resource is governed. Redpanda runs managed agents and managed MCP server implementations. You run self-managed agents and MCP servers, while Agentic Data Plane registers their identities and fronts their model or tool traffic through the gateways. An LLM provider is different: it is a gateway connection to an upstream model service, not a model runtime hosted in Agentic Data Plane. ![Resource ownership comparison. Redpanda runs managed agent runtimes and managed MCP server implementations. Customers run self-managed agent runtimes and self-managed MCP endpoints. AI Gateway and MCP Gateway provide identity, policy, and observability across both ownership models. LLM providers remain upstream model services connected through an Agentic Data Plane provider configuration.](https://docs.redpanda.com/agentic-data-plane/get-started/_images/resource-ownership-models.svg) Figure 1. Runtime ownership changes, but gateway identity and governance stay consistent ## [](#architecture)Architecture Agents and clients connect through Agentic Data Plane rather than reaching your systems directly. Agentic Data Plane gives every agent an identity and applies guardrails and spend caps, mediates tool and data access through MCP servers to your systems of record, and routes every LLM call through the AI Gateway. All activity streams to the Redpanda Data Platform as OpenTelemetry traces for replay, audit, and cost reporting. ![Architecture diagram: Redpanda-managed agents](https://docs.redpanda.com/agentic-data-plane/get-started/_images/adp-architecture.png) Figure 2. Redpanda Agentic Data Plane sits between your agents and clients and your external systems and LLM providers ## [](#ai-gateway)AI Gateway The AI Gateway is a managed proxy for LLM APIs. You configure an LLM provider once, and applications point at a Redpanda-hosted proxy URL while continuing to use the provider’s native SDK. Redpanda holds the upstream credentials, so application code never carries a provider API key and rotation happens in one place. Because every LLM call flows through one managed entry point, you get usage and cost visibility broken down by provider, model, and user, across any agent framework or platform, including Redpanda’s own, without locking into any single vendor’s SDK. Applications authenticate with short-lived OIDC service-account tokens, and streaming responses pass through unchanged. To control spend, set caps and per-agent [budgets](https://docs.redpanda.com/agentic-data-plane/control/budgets/) in one place. For more information, see [How AI Gateway Works](https://docs.redpanda.com/agentic-data-plane/gateway/overview/). ## [](#mcp-servers)MCP servers [MCP servers](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#mcp-server) translate agent intent into connections to databases, queues, HRIS, CRMs, and other business systems. They are the simplest way to give agents context and capabilities without writing glue code. MCP servers are lightweight, support OIDC-based authentication, and enforce deterministic policies at the tool level. You pick a managed type from the marketplace and configure it with your credentials, or register a self-managed server. Policy enforcement programmatically prevents prompt injection, SQL injection, and other agent-based attacks. With real-time debugging capabilities, you reduce integration time while getting enterprise-grade security. You can reuse your existing infrastructure and data sources rather than building new integrations from scratch. For more information, see [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/). ## [](#ai-agents)AI agents With Redpanda AI agents, you declare the agent behavior you want and Redpanda handles execution and orchestration. Instead of writing Python or JavaScript, you configure agents declaratively: set a system prompt, choose a model, and attach the tools the agent can use. You can orchestrate multiple specialized [sub-agents](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#subagent), or bring your own frameworks like LangChain or LlamaIndex. What makes this practical at scale is a broad library of prebuilt tools and integrations with built-in filtering, enrichment, and routing, which give declarative definitions real power. The result is faster time-to-production, lower maintenance (declarative definitions instead of imperative code), and organizational consistency across teams. For more information, see [How Agents Work](https://docs.redpanda.com/agentic-data-plane/connect/agents-overview/). ## [](#built-in-governance-controls)Built-in governance controls Redpanda Agentic Data Plane addresses critical enterprise requirements across all components. - **Security by design**: MCP servers enforce policies at the tool level, programmatically preventing prompt injection, SQL injection, and other agent-based attacks. Policy enforcement is deterministic and controlled. Agents cannot bypass security constraints even through creative prompting. - **Unified authorization**: All components use OIDC-based authentication with an on-behalf-of authorization model. When a user invokes an agent, the agent inherits the intersection of its own permissions and the user’s permissions, so an agent can only do what the user behind it is allowed to do. This ensures proper data access scoping. An embedded identity provider lets any standards-compliant MCP client, such as Claude Desktop, Claude Code, or Microsoft Copilot Studio, connect over OAuth without custom header handling. - **Complete observability**: Redpanda Agentic Data Plane provides two levels of inspection. Execution logs ([transcripts](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#transcript)) give a read-only view of every agent run, capturing each prompt, response, and tool call with token and USD cost per conversation, plus status, duration, and an interactive timeline. Traces are emitted as OpenTelemetry data into an immutable Redpanda topic with 100% sampling. Real-time debugging tools let you inspect individual MCP server calls down to individual tool invocations with full timing data. You can view detailed agent actions in Agentic Data Plane and replay data for agent evaluations. For more information, see [How Observability Works](https://docs.redpanda.com/agentic-data-plane/monitor/concepts/). - **Compliance and audit**: Redpanda Agentic Data Plane records every agent action and the data sources used in each decision, which supports audit and compliance efforts (for example, frameworks such as ISO 42001 or the EU AI Act). Execution logs are stored in Redpanda topics and can be materialized to Iceberg tables for longer-term retention and analysis. ## [](#use-cases)Use cases Common Redpanda Agentic Data Plane use cases include: - **Automate financial operations**: Build agents that reconcile invoices across vendors and ERP systems, monitor real-time spending against budget, or review contracts against approved templates and flag out-of-policy clauses for legal review. - **Streamline HR and people operations**: Answer employee questions against benefits, payroll, and HRIS systems; automate onboarding and offboarding workflows; or triage internal support tickets to the right team. - **Improve customer experience**: Route customer inquiries to the right team, summarize prior support history before an agent picks up the case, or surface relevant knowledge-base articles in real time. - **Modernize infrastructure operations**: Detect anomalies in real-time telemetry from cloud, network, or factory equipment, correlate signals across disparate monitoring systems, and auto-create maintenance tickets with the relevant context already attached. - **Extend enterprise productivity tools**: Integrate Microsoft Copilot or other workplace agents with internal data sources and systems that are otherwise inaccessible. ## [](#next-steps)Next steps - [Quickstart for Agent Builders](https://docs.redpanda.com/agentic-data-plane/get-started/agent-builder-quickstart/) - [Quickstart for Administrators](https://docs.redpanda.com/agentic-data-plane/get-started/adp-quickstart/) - [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/) --- # Page 71: Agentic Data Plane Quickstart for Administrators **URL**: https://docs.redpanda.com/agentic-data-plane/get-started/adp-quickstart.md --- # Agentic Data Plane Quickstart for Administrators > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Agentic Data Plane Quickstart for Administrators latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: adp-quickstart page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: adp-quickstart.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/get-started/pages/adp-quickstart.adoc description: "Set up Redpanda Agentic Data Plane for your organization: configure an LLM provider with a key stored in the platform secret store, verify it, and hand off to your agent builders." page-topic-type: quickstart personas: platform_engineer learning-objective-1: Configure your first LLM provider in Agentic Data Plane with an Anthropic API key learning-objective-2: Verify the provider is enabled and its connection is active learning-objective-3: Grant your builders access and point them to the agent builder quickstart page-git-created-date: "2026-06-04" page-git-modified-date: "2026-08-07" --- This quickstart sets up Redpanda Agentic Data Plane for your organization. An administrator configures a [large language model (LLM)](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#large-language-model-llm) provider. This is a one-time task. Until a provider exists, no one in your organization can build [agents](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#ai-agent) against the platform. You get an Anthropic API key, create the provider with the key stored in the platform secret store, confirm the connection is active, and hand off to your builders. This quickstart configures an Anthropic provider, but Agentic Data Plane also supports OpenAI, Google AI, AWS Bedrock, and OpenAI-compatible endpoints. If your organization already has an LLM provider configured and you want to build an agent, go to the [agent builder quickstart](https://docs.redpanda.com/agentic-data-plane/get-started/agent-builder-quickstart/) instead. After reading this page, you will be able to: - Configure your first LLM provider in Agentic Data Plane with an Anthropic API key - Verify the provider is enabled and its connection is active - Grant your builders access and point them to the agent builder quickstart ## [](#prerequisites)Prerequisites - The [Admin role](https://docs.redpanda.com/agentic-data-plane/control/permissions-overview/) in Agentic Data Plane. Admin is the only built-in role that carries Agentic Data Plane permissions. - An Anthropic account. If you don’t have one, the [Get an Anthropic API key](#get-an-anthropic-api-key) section walks through signup. ## [](#what-you-set-up)What you set up 1. **Anthropic API key**. Created in the Anthropic console and stored in the Agentic Data Plane secret store, so the raw key never has to live on a builder’s machine. 2. **Anthropic LLM provider**. An organization-level resource that routes Claude API calls through Agentic Data Plane so credentials, usage, and [transcripts](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#transcript) stay on the platform. Configure it once, and every builder can select it when they create agents. When you sign in to Agentic Data Plane at [ai.redpanda.com](https://ai.redpanda.com), you land on the Home page: a snapshot of items that need your attention, recent gateway traffic, month-to-date spend and token totals, budget status, and quick actions for common tasks. Start the tasks in this guide from the sidebar. ## [](#get-an-anthropic-api-key)Get an Anthropic API key Anthropic requires a payment method before it issues an API key. Add billing first, then create the key. 1. Open [platform.claude.com](https://platform.claude.com) and sign in, or create a new account. 2. Add a payment method to your account if you haven’t already. Anthropic requires a payment method before it issues API keys. (Optional: add a small amount of prepaid credit so the first calls don’t fail on a fresh account.) 3. In the sidebar, select a workspace other than `Claude Code`. The `Claude Code` workspace uses a separate key-creation flow that doesn’t fit this quickstart. 4. In the sidebar, click **API keys**. 5. Click **Create key**. In the Create API key dialog, name the key `adp-quickstart` and click **Add**. 6. Copy the key (it starts with `sk-ant-`). > ❗ **IMPORTANT** > > Anthropic shows the API key value once. If you close the dialog without copying, you can’t recover it. Paste the key into a secure note before continuing. The next section creates the secret in Agentic Data Plane’s secret store as part of the provider form, so you don’t have to keep the key on your local machine. 7. (Optional) On the **API keys** page, confirm the new key appears in the list. ## [](#configure-your-llm-provider)Configure your LLM provider Now point Agentic Data Plane at Anthropic. Agentic Data Plane references provider credentials by secret name, not by raw value, and you create the secret inline as part of this form. 1. Sign in to Agentic Data Plane at [ai.redpanda.com](https://ai.redpanda.com). 2. In the sidebar, open **LLM Providers**. 3. Click **Add provider**. 4. `Display name`: Enter `anthropic-quickstart`. This label appears in dashboards and model selectors. Agentic Data Plane derives the provider’s resource ID from it in the background, using lowercase letters, numbers, and hyphens; the ID is used in API calls and CLI commands and can’t be changed after creation. 5. `Provider type`: Select `Anthropic`. 6. In the Credential section, select `Bring a new API key reference` and add the key inline: - `Key name`: Enter `Anthropic API key`. Agentic Data Plane stores the key in the platform secret store under an identifier derived from this name (`ANTHROPIC_API_KEY`), shown under the field. The identifier can’t be changed later. - `API key`: Paste the `sk-ant-` key you copied from Anthropic. - Click **Save key**. The key is stored encrypted and can’t be viewed again after saving, so if you mistype it, save a new key. New keys get the AI Gateway scope automatically, which makes them usable across the platform: LLM providers, MCP servers, and agents. To create secrets ahead of time or manage them later, open **Secrets Store** in the sidebar. 7. Leave `Authorization passthrough` off. This quickstart uses one shared key, not per-user OAuth. 8. Leave the default `Base URL` in place. The form prefills the standard Anthropic endpoint. 9. In the Models section, keep the default selection and confirm `claude-sonnet-4-6` is selected. It’s a good default for agents and handles multi-step tool use reliably. The catalog of available models is maintained by Redpanda and starts fully selected. The models you leave selected become the catalog this provider exposes to agents and applications; you can change the list later from the provider detail page. 10. For Transcripts, turn on `Record inputs` and `Record outputs`. Both are off by default, which limits transcripts to token counts, latency, and tool calls. Turning them on lets your builders replay full conversations, including prompts, responses, and tool arguments. This setting applies to every agent on the provider, so leave it off for providers that carry regulated or sensitive data. See [Configure transcript logging](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/#transcript-logging). 11. Click **Create provider**. 12. On the provider detail page, select the **Overview** tab. Confirm the badge next to the provider name shows `Enabled` and the `Status` in the Connection card shows `Active`. If the Status badge stays in a failure state, see the [provider troubleshooting table](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/#troubleshooting). The most common cause is a typo in the secret reference or a key that wasn’t issued in the workspace Agentic Data Plane can read. For the full provider field reference (transcript logging, Bedrock IAM, Anthropic authentication passthrough, OpenAI-compatible endpoints), see [Configure an LLM provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/). ## [](#hand-off-to-your-builders)Hand off to your builders With the provider active, your organization is ready for agents. To get builders started: 1. Write an [access policy](https://docs.redpanda.com/agentic-data-plane/control/access-policies/) that lets your builders create MCP servers and agents. Point it at the identity provider group they already belong to and grant the whole team in one statement. Don’t reach for a role here: Admin is the only built-in role that touches Agentic Data Plane, and it grants far more than a builder needs. See [Control Who Can Do What](https://docs.redpanda.com/agentic-data-plane/control/permissions-overview/). Access policies are a preview capability. If they aren’t enabled for your organization yet, a custom role holding `dataplane_adp_agent_*` and `dataplane_adp_mcpserver_*` is the interim path. 2. Send them the [agent builder quickstart](https://docs.redpanda.com/agentic-data-plane/get-started/agent-builder-quickstart/). It assumes exactly what you just set up: a signed-in user who can create agents, and an active LLM provider. Builders pick a model in the agent form’s **Model** section, where the provider’s display name (`anthropic-quickstart`) appears next to the models it serves. They don’t see or handle the API key. ## [](#clean-up)Clean up If you set this provider up only as a test, delete it so it doesn’t continue to count against your account. 1. Delete the LLM provider (`anthropic-quickstart`). Open the provider detail page, scroll to the Delete this provider section, click **Delete**, and type `delete` to confirm. Note that the underlying secret (`ANTHROPIC_API_KEY`) is not deleted automatically. 2. (Optional) Delete the secret. Open **Secrets Store**, click `ANTHROPIC_API_KEY`, then **Delete**. 3. (Optional, on the Anthropic side) Revoke the API key. Open [platform.claude.com](https://platform.claude.com), navigate to **Manage** > **API keys** in the workspace where you created the key, find `adp-quickstart` in the list, and revoke it from the row’s action menu. If you want to keep the provider but rotate the key, edit the provider and change the `API key reference` to a new secret. ## [](#next-steps)Next steps - [Agentic Data Plane Quickstart for Agent Builders](https://docs.redpanda.com/agentic-data-plane/get-started/agent-builder-quickstart/) - [Configure an LLM Provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/) - [Set Up Budgets](https://docs.redpanda.com/agentic-data-plane/control/budgets/) - [Set Up Guardrails](https://docs.redpanda.com/agentic-data-plane/control/guardrails/) - [Control Who Can Do What](https://docs.redpanda.com/agentic-data-plane/control/permissions-overview/) --- # Page 72: Agentic Data Plane Quickstart for Agent Builders **URL**: https://docs.redpanda.com/agentic-data-plane/get-started/agent-builder-quickstart.md --- # Agentic Data Plane Quickstart for Agent Builders > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Agentic Data Plane Quickstart for Agent Builders latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: agent-builder-quickstart page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: agent-builder-quickstart.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/get-started/pages/agent-builder-quickstart.adoc description: Sign in to Redpanda Agentic Data Plane, explore the agents your organization already runs, then build, test, and iterate on your own agent backed by MCP tools. page-topic-type: quickstart personas: agent_builder learning-objective-1: Find and evaluate the agents that already run in your organization learning-objective-2: Build an agent that combines an LLM provider with tools from an MCP server learning-objective-3: Test, iterate on, and verify agent behavior with the Playground and Transcripts tabs page-git-created-date: "2026-07-20" page-git-modified-date: "2026-08-10" --- This quickstart takes you from zero to a working agent: you sign in, explore the agents your organization already runs, then build your own that turns a natural-language question into a real API call. By the end, you have an agent you can test, tune, and share with your team. Redpanda Agentic Data Plane is Redpanda’s platform for running and governing [AI agents](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#ai-agent) on your streaming data. For the bigger picture, see the [Agentic Data Plane overview](https://docs.redpanda.com/agentic-data-plane/get-started/adp-overview/). After reading this page, you will be able to: - Find and evaluate the agents that already run in your organization - Build an agent that combines an LLM provider with tools from an MCP server - Test, iterate on, and verify agent behavior with the Playground and Transcripts tabs ## [](#prerequisites)Prerequisites > ❗ **IMPORTANT** > > Before you build, your organization needs a [large language model (LLM)](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#large-language-model-llm) provider configured. If your administrator has already set one up, continue. If not, or you’re not sure, complete the [administrator quickstart](https://docs.redpanda.com/agentic-data-plane/get-started/adp-quickstart/) first, then come back. It’s a one-time setup. - Access to Agentic Data Plane at [ai.redpanda.com](https://ai.redpanda.com). If you can’t sign in, ask your administrator for an invitation. - Access to create agents and MCP servers. Your administrator grants this with an [access policy](https://docs.redpanda.com/agentic-data-plane/control/access-policies/), or with a custom role where policies aren’t enabled yet. The Writer and Reader roles don’t cover Agentic Data Plane. If a create button is disabled or a save returns a permission error, ask them to check what applies to you or your group. - At least one LLM provider configured in your organization. ## [](#what-you-build)What you build You create the following Agentic Data Plane resources, in order: 1. **PetStore [MCP server](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#mcp-server)**. Exposes the public Swagger PetStore API as a set of [MCP tools](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#mcp-tool) the agent can call. PetStore is a public demo API with no authentication, so you can focus on the flow instead of credentials. 2. **Pet store assistant agent**. Combines your organization’s LLM provider and the MCP server so a natural-language question becomes a real API call against PetStore. After the agent works, you replay one of its runs turn-by-turn on its **Transcripts** tab, then learn how to swap the demo API for a system your team actually uses. ## [](#sign-in-and-look-around)Sign in and look around Sign in to Agentic Data Plane at [ai.redpanda.com](https://ai.redpanda.com). You land on the Home page: a snapshot of items that need your attention, recent gateway traffic, month-to-date spend and token totals, budget status, and quick actions for common tasks. Start every task in this guide from the sidebar. ## [](#explore-existing-agents)Explore existing agents Before you build anything, see what already exists. Your organization may run agents you can use or learn from. 1. In the sidebar, open **Agents**. The agent registry lists every agent in your organization with its status. 2. Select an agent to open its detail page. The tabs give you a complete picture of the agent: - **Overview**: The agent’s full configuration, including its model, system prompt, and tools. - **Triggers**: Schedules and event sources that invoke the agent. - **Playground**: An interactive chat surface for testing the agent. - **Cost & Usage**: The agent’s budget status and its spend and request volume, broken down by LLM provider. - **Transcripts**: A record of every conversation against the agent. - **Permissions**: Who can act on the agent and what the agent can access. This tab appears when access policies, a preview capability, are enabled for your organization. 3. (Optional) Open the **Playground** tab of an existing agent and send it a prompt to see how it behaves. If an existing agent already covers your use case, you can stop here and use it. Otherwise, continue to build your own. ## [](#create-an-mcp-server-with-a-public-openapi-spec)Create an MCP server with a public OpenAPI spec The OpenAPI managed MCP server type takes any OpenAPI 3.x spec URL and generates one MCP tool per operation. You point it at the public Swagger PetStore, which exposes a small pet-inventory API with no authentication. > 📝 **NOTE** > > PetStore is a public demo that Swagger hosts for testing and is occasionally unavailable. Before you start, open [the spec URL](https://petstore3.swagger.io/api/v3/openapi.json) in your browser. If it doesn’t return JSON, wait a few minutes and retry; PetStore usually recovers quickly. Checking now saves you from debugging your agent later for an upstream outage that isn’t your fault. 1. In the sidebar, open **MCP Servers** and click **Add MCP server**. 2. Search for and select the **OpenAPI** card from the marketplace picker. ![The Create MCP Server marketplace picker filtered by a search for openAPI, showing the Remote (Proxied) card and the OpenAPI card](https://docs.redpanda.com/agentic-data-plane/get-started/_images/create-mcp-server-picker.png) 3. `Name`: Enter `petstore-quickstart`. 4. `Description`: Enter `Public PetStore API exposed as MCP tools for quickstart testing`. Optional, but helps you find the server later. 5. Leave the `Enable Code Mode` toggle off. Code mode adds search and execute tools that let agents run sandboxed code against the server’s tools. The PetStore catalog is small enough that you don’t need it for this quickstart. 6. Leave the Output format section at its defaults. 7. `Spec`: Enter `[https://petstore3.swagger.io/api/v3/openapi.json](https://petstore3.swagger.io/api/v3/openapi.json)`. 8. `Base URL`: Leave blank. The PetStore spec already declares the right `servers` block, so no override is needed. 9. Skip all other optional configuration fields. 10. For the authentication mode, select `No Auth`. PetStore is a public API. 11. Click **Create server**. 12. Redpanda fetches the spec, parses it, and generates one MCP tool per operation. When the server is ready, open its detail page. 13. On the **Connection** tab, copy the `Server URL`. MCP clients use this URL to connect to the server. 14. Open the **Inspector** tab. Redpanda runs a live `tools/list` against the server and lists every tool it discovered. Confirm the list includes `findpetsbystatus`, `getpetbyid`, `findpetsbytags`, and `addpet`. The OpenAPI MCP server lowercases tool names when it generates them from the spec’s `operationId` values. The exact tool count depends on the operations defined in the spec at fetch time. A populated list confirms the connection works. If the list is empty or the tab shows an error, see [OpenAPI MCP troubleshooting](https://docs.redpanda.com/agentic-data-plane/connect/managed/openapi/#troubleshooting). For the full OpenAPI MCP reference (authentication modes, operation filters, base URL overrides), see [OpenAPI managed MCP server](https://docs.redpanda.com/agentic-data-plane/connect/managed/openapi/). ## [](#build-your-agent)Build your agent Combine your organization’s LLM provider and the PetStore MCP server into an agent. Agentic Data Plane configures a managed agent on a single canvas titled **New managed agent**, with sections for **Identity**, **Model**, **Instructions**, and **Tools**, plus a collapsible **Advanced** area for subagents and tags. Required fields are marked with an asterisk (`*`). For the full reference, see [Create an agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/). 1. In the sidebar, open **Agents**. 2. Click **Create agent**. 3. Choose how the agent runs. Click `Redpanda manages it`, so Redpanda deploys, runs, and observes the agent for you. ![The runtime choice in the create-agent flow, with a Redpanda manages it card for the managed runtime and an I host it myself card for self-managed agents](https://docs.redpanda.com/agentic-data-plane/shared/_images/create-agent-runtime-choice.png) > 📝 **NOTE** > > The other option, `I host it myself`, registers an agent you run on your own infrastructure. This quickstart uses the managed runtime. 4. On the **New managed agent** page, in the **Identity** section, set the following: - `Name`: Enter `pet-store-assistant`. This name appears in the agent registry list and the detail header. Agentic Data Plane derives the agent’s resource ID from it when you create the agent; you don’t enter the ID directly, and it can’t be changed after creation. - `Description`: Enter `Quickstart agent that answers questions about the PetStore inventory`. 5. For **Model**, open the picker and select `claude-sonnet-4-6`. It handles multi-step tool use reliably, which is what an agent needs. The picker is a single searchable list of every model your organization’s configured providers expose, with the provider that serves each model shown next to it. Selecting the model also selects its provider; for this quickstart that’s the `anthropic-quickstart` provider your administrator configured. When more than one provider serves the same model, each pairing is its own entry, so pick the one that names `anthropic-quickstart`. If the picker is empty, no provider exists yet; ask your administrator to complete the [administrator quickstart](https://docs.redpanda.com/agentic-data-plane/get-started/adp-quickstart/). > 📝 **NOTE** > > These names assume the Anthropic provider from the administrator quickstart. If your organization configured a different provider, pick any model it offers that supports tool use. 6. For **Instructions**, paste in the following system prompt: ```text You are a pet store inventory assistant. You have access to PetStore API tools through MCP. Use them to answer questions about pets. The most useful read tools are: - findpetsbystatus: List pets by status (available, pending, sold) - getpetbyid: Look up a specific pet by ID - findpetsbytags: Search by tag Rules: - Always call a tool before answering. Don't make up pet data. - After each tool call, summarize what the tool returned and cite the tool name in your response. - If a tool fails or returns no data, say so and stop. Don't retry with invented IDs. - Stick to read operations for this quickstart. Don't add, update, or delete pets. ``` 7. For **Tools**, select the `petstore-quickstart` checkbox in the server list. If your organization runs many MCP servers, a **Search MCP servers** box appears above the list; use it to find the server. (Don’t click **Add MCP server** on the left. That builds a new server, and you already have one.) The agent discovers the server’s tools at runtime; you don’t pre-select individual tools, and the system prompt’s "stick to read operations" rule constrains behavior. You can change this list at any time. 8. Leave the **Advanced** area collapsed. The quickstart uses a single agent with no subagents or tags. 9. Click **Create agent**. If the button is disabled, the helper text next to it tells you which required field is still missing (a name and a model). 10. Wait for the agent status to change from `Starting` to `Running`. ## [](#test-the-agent-in-the-playground)Test the agent in the Playground The **Playground** tab is a chat surface for the agent. Type a prompt into the input at the bottom of the page and click the paper-plane icon in the input’s bottom-right corner to send. Each prompt creates a Task card in the conversation that walks through the agent’s execution turn-by-turn: TaskStatusUpdate entries (`Submitted` → `Working` → `Completed`) with token counts, individual tool-call cards showing the tool name and latency, and an Artifact card holding the final response. **Clear context** (at the bottom of the input) resets the conversation between tests. 1. On the agent detail page, open the **Playground** tab. 2. Send the first prompt: ```text What pets are available right now? ``` The agent calls `findpetsbystatus` with `status=available` and returns a summary of the pets, naming the tool. This PetStore endpoint is occasionally flaky; if it returns an HTTP 500, retry the prompt. 3. (Optional) Send an open-ended prompt to confirm multi-step reasoning: ```text Find a pet tagged "friendly" and tell me whether it's available. ``` The agent may call `findpetsbytags` first, then `getpetbyid` for one of the matches, then summarize. If the agent hallucinates data instead of calling a tool, tighten the system prompt’s "Always call a tool before answering" rule. See [system prompt best practices](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/) for patterns. If a tool card shows an HTTP 500 error and the Artifact apologizes about the pet store API being unavailable, that’s the public Swagger PetStore being intermittently down. The agent is behaving correctly (the "if a tool fails, say so and stop" rule in the system prompt is what produced the apology). Retry the prompt; PetStore usually recovers within a few minutes. ## [](#iterate-on-your-agent)Iterate on your agent Agent configuration isn’t fixed after you create it. Edit the system prompt or model, save, and re-test in the Playground to see how behavior changes. 1. On the agent detail page, open the **Overview** tab. The tab shows the agent’s full configuration, organized into sections that you edit and save one at a time. 2. In the System prompt section, select the edit icon and adjust the prompt to change how the agent responds. For example: - Add a constraint: `Never call more than one tool per response.` - Change the output format: `Always format pet details as a bulleted list.` - Add a confirmation step: `Before answering, restate which tool you plan to call and why.` 3. Click **Save**. 4. Open the **Playground** tab, click **Clear context**, and re-send one of the earlier prompts to compare the agent’s behavior against your change. For system prompt patterns and anti-patterns, see [Write effective system prompts](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/). ## [](#see-what-your-agent-did)See what your agent did Every conversation with the agent is recorded as a [transcript](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#transcript) you can replay turn-by-turn. Your Playground tests are already there. > 📝 **NOTE** > > The **Chat** view and the tool arguments and results depend on message recording, which the LLM provider controls with the `Record inputs` and `Record outputs` toggles, both off by default. The paired [administrator quickstart](https://docs.redpanda.com/agentic-data-plane/get-started/adp-quickstart/) turns them on. If your administrator left them off, transcripts still capture token counts, latency, and tool calls, but the message text is empty. For details, see [Configure transcript logging](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/#transcript-logging). 1. On the agent detail page, open the **Transcripts** tab. The tab lists the agent’s recent conversations, one row per conversation, with its start time, duration, turn count, status, and token total. 2. Select the conversation from your Playground test. 3. Toggle between the two views: - **Chat**: The user-visible exchange, as a conversation. - **Detailed**: Adds per-turn metadata: latency, input/output token splits, and each tool call with its arguments, result, latency, and status. The **Detailed** view is where you verify the agent did what you asked: which tool it called, with which arguments, and what came back. For the full transcript reference, see [See what your agent did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/). ## [](#make-it-real)Make it real PetStore proves the flow. To build something your team uses, swap the demo API for a real system: 1. In the sidebar, open **MCP Servers** and click **Add MCP server**. 2. Pick a type from the marketplace picker that matches a system your team uses, such as Slack, Jira, or a SQL database. See the [managed MCP catalog](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/) for every type Redpanda hosts, with links to setup guides. 3. Configure its authentication. Unlike PetStore, real systems need credentials: an API key stored as a secret, or per-user OAuth. Some authentication modes need one-time setup from your administrator; see [Set up authentication](https://docs.redpanda.com/agentic-data-plane/connect/authentication/). 4. Add the new server to your agent’s **Tools** section, and update the system prompt to describe the new tools and rules. Your own API works too: if it has an OpenAPI 3.x spec, the same OpenAPI server type you used for PetStore exposes it as tools. See [OpenAPI Managed MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/managed/openapi/). ## [](#use-your-agent-beyond-the-ui)Use your agent beyond the UI Your agent isn’t limited to the Agentic Data Plane UI. After it’s running, you can reach it and its tools from other software: - Surface your MCP tools in a chat client like Claude Desktop or ChatGPT: [Connect Remote MCP Clients](https://docs.redpanda.com/agentic-data-plane/connect/remote-mcp-clients/) - Call the agent from your own application over its A2A endpoint: [Connect to the agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/#connect-to-the-agent) - Let the agent respond in Microsoft Teams: [Trigger Agents](https://docs.redpanda.com/agentic-data-plane/connect/triggers/overview/) ## [](#clean-up)Clean up If this was a one-off exercise, delete the resources you created so they don’t continue to count against your organization. 1. Delete the agent (`pet-store-assistant`) first. Open the agent detail page, scroll to the Delete this agent section, click **Delete**, and type `delete` to confirm. 2. Delete the MCP server (`petstore-quickstart`). Same pattern. Leave your organization’s LLM provider alone. It’s a shared resource that other builders use. ## [](#next-steps)Next steps - [Use the Agentic Data Plane CLI](https://docs.redpanda.com/agentic-data-plane/cli/) - [Write Effective System Prompts](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/) --- # Page 73: Monitor & Debug **URL**: https://docs.redpanda.com/agentic-data-plane/monitor.md --- # Monitor & Debug > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Monitor & Debug latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: index page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/monitor/pages/index.adoc description: See what your agents did, investigate runs, and check speed, cost, and errors. page-git-created-date: "2026-05-28" page-git-modified-date: "2026-06-18" --- See what your agents are doing and why. Monitor agent activity, read individual run transcripts, troubleshoot failures, and track speed, cost, and errors. - [How Observability Works](concepts/) Understand how Redpanda captures end-to-end execution transcripts on an immutable distributed log for agent governance and observability. - [Monitor Agent Activity](monitor-agents/) Monitor agent execution, inspect available MCP tools, analyze conversation history, track token usage, and debug issues using Playground and Transcripts. - [Visualize Your Agent Network](agent-network/) See a live map of your agents, the models they call, and the MCP servers they use, with usage, cost, and health for a chosen time window. - [Review the Audit Log](audit-log/) Review authorization decisions across Agentic Data Plane, filter events, and inspect who acted on which resource and whether the request was allowed. - [See What Your Agent Did](transcripts/) Open a transcript in Agentic Data Plane, read the conversation turn by turn, and investigate errors, costs, and performance. - [Troubleshoot Agents](troubleshoot-ai-agents/) Diagnose and fix common issues with AI agents including deployment failures, runtime behavior problems, and tool execution errors. --- # Page 74: Visualize Your Agent Network **URL**: https://docs.redpanda.com/agentic-data-plane/monitor/agent-network.md --- # Visualize Your Agent Network > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Visualize Your Agent Network latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: agent-network page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: agent-network.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/monitor/pages/agent-network.adoc description: See a live map of your agents, the models they call, and the MCP servers they use, with usage, cost, and health for a chosen time window. page-topic-type: how-to personas: platform_engineer, agent_builder, security_compliance_lead learning-objective-1: Trace which models and tools each agent uses in the network graph learning-objective-2: Scope the view to a time window and health status learning-objective-3: Inspect an agent, LLM provider, MCP server, or tool to check usage, cost, and errors page-git-created-date: "2026-07-31" page-git-modified-date: "2026-08-10" --- The **Agent Network** view is a live map of your Agentic Data Plane: every agent, the [LLM](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#large-language-model-llm) providers it calls, and the [MCP servers](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#mcp-server) and tools it uses, drawn as a graph with usage, cost, and health for the time window you choose. Use it to see at a glance what your agents are actually doing, which models and tools carry the most traffic, and where errors are clustering. After reading this page, you will be able to: - Trace which models and tools each agent uses in the network graph - Scope the view to a time window and health status - Inspect an agent, LLM provider, MCP server, or tool to check usage, cost, and errors The view draws on the same recorded telemetry that powers [transcripts](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/), enriched with cost data. It shows what actually ran during the selected window. A configured resource with no traffic in the window still appears, with its metrics marked as having no recorded data yet. > 📝 **NOTE** > > The Agent Network view is a preview capability, available when your organization has it enabled. If you don’t see **Agent Network** under **Agents** in the sidebar, it isn’t enabled for your organization. ## [](#prerequisites)Prerequisites The Agent Network view requires the `dataplane_adp_agentnetwork_get` permission. See [Control Who Can Do What](https://docs.redpanda.com/agentic-data-plane/control/permissions-overview/). ## [](#open-the-agent-network-view)Open the Agent Network view Open **Agents** in the sidebar, then click **Agent Network**. The header shows your agent and MCP server counts, plus conversations, tool calls, cost, and tokens for the selected time window. These totals always cover the whole network, even when the graph is filtered or showing only the busiest agents. ## [](#read-the-graph)Read the graph The graph arranges nodes in columns, with traffic flowing left to right: - **Agents**: Your agents, grouped into a cluster you can click to expand. - **LLM providers**: The providers agents send model requests to, with cost and token usage on each card. When you have many providers, the column paginates. - **MCP servers**: The servers agents call tools on. Click a server to expand its tools into their own column, showing per-tool call counts. Lines connect each agent to the providers and servers it used during the window, and line thickness shows traffic volume. Agent-to-provider lines can represent either token usage or cost: switch between **Tokens** and **Cost** in the on-canvas legend. Agent-to-server lines always represent tool calls. ## [](#scope-the-view)Scope the view Use the toolbar to control what the graph shows: - **Window**: Choose from last hour, last 24 hours (the default), last 7 days, or last 30 days. - **Status**: Show all nodes, only nodes with activity, or only nodes with errors. - **Sort LLMs**: Order providers by cost or token use, or list them alphabetically. - **Sort MCPs**: Order servers by tool calls, or list them alphabetically. - **Refresh**: Reload the graph with current data. - **Reset view**: Return to the default layout and selection. Click a node to inspect it, click it again to deselect, and press Esc to reset the selection. The view state persists in the URL, so you can bookmark a scoped view or share it with your team. ## [](#inspect-a-node)Inspect a node Selecting a node opens a detail panel: - **Agent**: The agent’s model and description, plus window metrics: conversations, spend, turns per conversation, and 95th-percentile request latency. - **LLM provider**: Cost and token usage, split by the models observed in the window. - **MCP server**: Tool count, connected agent count, tool calls, and connection status, plus the server’s tools and the agents and users that called it during the window. Click an agent to jump to its details. - **Tool**: The tool’s description and its usage in the window: how many agents called it, how many calls it received, the server it belongs to, and its status. ## [](#monitor-health)Monitor health Each node carries a health state derived from its error rate in the window: healthy, degraded, or error. Use the **Status** filter to isolate nodes with errors. The view flags every MCP server that needs attention, whether its credentials fail to resolve (for example, an expired or missing user connection) or its tool calls fail on their own. Each alert names the cause and shows how many agents are affected and how many calls failed, so you can act before more calls fail. For a credential failure, reconnect the user connection. See [Configure User-Delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) for managing user connections. ## [](#next-steps)Next steps - [Monitor Agent Activity](https://docs.redpanda.com/agentic-data-plane/monitor/monitor-agents/) - [See What Your Agent Did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/) - [Troubleshoot Agents](https://docs.redpanda.com/agentic-data-plane/monitor/troubleshoot-ai-agents/) --- # Page 75: Review the Audit Log **URL**: https://docs.redpanda.com/agentic-data-plane/monitor/audit-log.md --- # Review the Audit Log > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Review the Audit Log latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: audit-log page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: audit-log.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/monitor/pages/audit-log.adoc description: Review authorization decisions across Agentic Data Plane, filter events, and inspect who acted on which resource and whether the request was allowed. page-topic-type: how-to personas: security_compliance_lead, platform_engineer learning-objective-1: Filter authorization events by time, outcome, subsystem, or search term learning-objective-2: Inspect the actor, action, resource, source, and policy behind an authorization decision learning-objective-3: Choose the audit log or a transcript for an investigation page-git-created-date: "2026-08-04" page-git-modified-date: "2026-08-10" --- The audit log records authorization decisions across Agentic Data Plane. Use it to answer who performed an action, which resource they acted on, where the request came from, and whether the request was allowed or denied. After reading this page, you will be able to: - Filter authorization events by time, outcome, subsystem, or search term - Inspect the actor, action, resource, source, and policy behind an authorization decision - Choose the audit log or a transcript for an investigation > 📝 **NOTE** > > The audit log is a preview capability. Access to the page is granted per organization, and audit recording is enabled per deployment; the two are independent. If you don’t see **Audit Log** in the sidebar, it isn’t enabled for your organization. > > A deployment can therefore show the page with no recorded events. If the table is empty for a period you know had activity, see [Troubleshooting](#troubleshoot-the-audit-log). ## [](#prerequisites)Prerequisites Your account needs the `dataplane_adp_auditlog_list` permission to open the audit log and view event details. Outside the Admin role, audit log reads come from an [access policy](https://docs.redpanda.com/agentic-data-plane/control/access-policies/) naming `Action::"AuditLog.list"`. See [Audit log permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#audit-log-permissions). > ❗ **IMPORTANT** > > Audit events can include user identities, resource names, network information, configuration changes, and captured request or response data. Grant audit log access only to people who need it, and review events before sharing them. ## [](#open-the-audit-log)Open the audit log 1. Open **Audit Log** in the sidebar. 2. Review the most recent events. The default time range is Last 24 hours. 3. Select a row to open its details. The table shows these fields: | Field | Description | | --- | --- | | Actor | The user accountable for the action. When an agent or another identity acted for the user, the table also identifies that caller when available. | | Subsystem | The part of Agentic Data Plane that handled the action. | | Action | The operation and service involved. | | Resource | The type and identifier of the affected resource. When one call decided on more than one resource, this shows a count, such as 3 resources, and the detail panel lists each resource with its own decision. | | Outcome | Whether the authorization decision allowed the action, denied it, or, for a call that decided on more than one resource, allowed some resources and denied others (Partial). Hover over the outcome to see the deciding policy when available. | | Time | When the decision occurred. | ## [](#filter-events)Filter events Use the controls above the table to narrow an investigation: - **Search**: Match a keyword against the event messages. - **Actor**: Enter an exact actor identity, such as an email address, to show only that actor’s events. - **Resource type**: Enter a full namespaced resource type, such as `redpanda.agent`, to show events for that type. Matching ignores case. The table’s Resource column shows the type without its namespace prefix, so `redpanda.agent` appears as `agent`. - **Resource ID**: Enter an exact resource identifier to show events for a single resource. Matching is case-sensitive. - **Outcome**: Show allowed actions, denied actions, or partial outcomes. Select more than one to combine them. - **Subsystem**: Select one or more of Management API, LLM proxy, MCP gateway, A2A proxy, and Spending. - **Time range**: Choose a duration of Last hour, Last 24 hours, Last 7 days, Last 30 days, or All time. To review a past window, set an end time, and the duration counts back from that time instead of from now. Filters work together. For example, select Denied, choose MCP gateway, and set Last hour to investigate recent MCP authorization failures. ## [](#inspect-an-event)Inspect an event Select an event to open its detail panel. The panel identifies the actor, outcome, subsystem, operation, resource, deciding policy, source, and time when that information is available. When a call decided on more than one resource, the panel opens with a Resources section that lists each resource and its own decision. Select a resource to see its individual outcome and deciding policy in the panel. Depending on the action, the panel may also show: - The agent or caller that acted for a user - The event class and activity - A configuration change with before and after values - Captured request data - Response status, error, or captured response data Captured values may be redacted, truncated, or absent. An empty field does not mean that no activity occurred. Use the event summary and outcome as the primary record of the authorization decision. ## [](#audit-log-compared-to-transcripts)Audit log compared to transcripts Use the audit log for access and accountability questions: - Who attempted an action? - Which resource and subsystem were involved? - Was the action allowed or denied? - Which policy made the decision? Use [transcripts](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/) for execution questions about an agent conversation, including model turns, tool calls, errors, timing, and token usage. An investigation may need both views: start with the audit log to identify an authorization decision, then inspect the related agent activity when you need execution details. ## [](#troubleshoot-the-audit-log)Troubleshoot the audit log | Issue | What to do | | --- | --- | | Audit Log is missing from the sidebar | The preview may not be enabled for your organization. Contact your Redpanda representative. | | You cannot open the audit log | Ask an administrator to confirm that your account has dataplane_adp_auditlog_list, from the Admin role or from an access policy naming Action::"AuditLog.list". | | No events match | Clear the search and filters, then widen the time range. The default view includes only the last 24 hours. If the table stays empty, audit recording may not be enabled for this deployment yet; page access and recording are gated independently. | | An event has no request, response, or configuration details | Not every event includes these fields. Use the event’s actor, action, resource, outcome, and time to continue the investigation. | ## [](#next-steps)Next steps - [How Redpanda stores audit events](https://docs.redpanda.com/agentic-data-plane/monitor/concepts/#how-redpanda-stores-audit-events) - [Transcripts compared to audit logs](https://docs.redpanda.com/agentic-data-plane/monitor/concepts/#transcripts-compared-to-audit-logs) - [See What Your Agent Did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/) - [Control Who Can Do What](https://docs.redpanda.com/agentic-data-plane/control/permissions-overview/) --- # Page 76: How Observability Works **URL**: https://docs.redpanda.com/agentic-data-plane/monitor/concepts.md --- # How Observability Works > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: How Observability Works latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: concepts page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: concepts.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/monitor/pages/concepts.adoc description: Understand how Redpanda captures end-to-end execution transcripts on an immutable distributed log for agent governance and observability. page-topic-type: concepts personas: domain_evaluator, security_compliance_lead, platform_engineer, agent_builder learning-objective-1: Explain how transcripts and spans capture execution flow learning-objective-2: Interpret transcript structure for debugging and monitoring learning-objective-3: Distinguish between transcripts and audit logs page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-10" --- Redpanda provides complete observability and governance for AI agents through automated [transcript](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#transcript) capture. Every agent execution, from simple tool calls to complex multi-agent, multi-turn workflows, generates a permanent, write-once record stored on Redpanda’s [log](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#log). The structure of every execution (its reasoning steps, tool invocations, model interactions, and data flows) is captured with 100% sampling and no gaps. Agentic Data Plane records the full message content of each step (the prompts sent to the model and the responses it returns) only when you turn on input and output capture for the LLM provider, because that content can contain sensitive data. See [Configure an LLM Provider](https://docs.redpanda.com/agentic-data-plane/gateway/configure-provider/). With transcripts, organizations gain the ability to debug agent behavior, identify performance bottlenecks, meet regulatory compliance requirements, and maintain accountability for AI-driven decisions. Transcripts use OpenTelemetry standards and [Raft](https://raft.github.io/)\-based consensus for correctness, establishing a trustworthy foundation for agent governance. After reading this page, you will be able to: - Explain how transcripts and spans capture execution flow - Interpret transcript structure for debugging and monitoring - Distinguish between transcripts and audit logs ## [](#what-are-transcripts)What are transcripts A transcript records the complete execution of an agentic behavior from start to finish. It captures every step (across multiple agents, tools, models, and services) in a single, traceable record. The AI Gateway and every [agent](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#ai-agent) and [MCP server](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#mcp-server) in your Agentic Data Plane automatically emit OpenTelemetry traces to a [topic](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#topic) called `redpanda.otel_traces`. Redpanda’s immutable distributed log stores these traces. Transcripts capture: - Tool invocations and results - Agent reasoning steps - Data processing operations - External API calls - Error conditions - Performance metrics With 100% sampling, every operation is captured with no gaps. Agentic Data Plane records message content (the prompts and model responses behind each step) only when you enable input and output capture on the LLM provider. Until then, transcripts hold the execution structure and metadata but not the raw prompt and response bodies. The underlying storage uses a distributed log built on Raft consensus (with TLA+ proven correctness), giving transcripts a trustworthy, immutable record for governance, debugging, and performance analysis. ## [](#traces-and-spans)Traces and spans [OpenTelemetry](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#opentelemetry) traces provide a complete picture of how a request flows through your system: - A _trace_ represents the entire lifecycle of a request (for example, a tool invocation from start to finish). - A _span_ represents a single unit of work within that trace (such as a data processing operation or an external API call). - A trace contains one or more spans organized hierarchically, showing how operations relate to each other. ## [](#agent-transcript-hierarchy)Agent transcript hierarchy Agent executions create a hierarchy of spans that reflect how agents process requests. Understanding this hierarchy helps you interpret agent behavior and identify where issues occur. ### [](#agent-span-types)Agent span types Agent transcripts contain these span types: | Span Type | Description | Use To | | --- | --- | --- | | ai-agent | Top-level span representing the entire agent invocation from start to finish. Includes all processing time, from receiving the request through executing the reasoning loop, calling tools, and returning the final response. | Measure total request duration and identify slow agent invocations. | | agent | Internal agent processing that represents reasoning and decision-making. Shows time spent in the LLM reasoning loop, including context processing, tool selection, and response generation. Multiple agent spans may appear when the agent iterates through its reasoning loop. | Track reasoning time and identify iteration patterns. | | invoke_agent | Agent and sub-agent invocation in multi-agent architectures, following the OpenTelemetry agent invocation semantic conventions. Represents one agent calling another through the A2A protocol. | Trace calls between root agents and sub-agents, measure cross-agent latency, and identify which sub-agent was invoked. | | openai, anthropic, or other LLM providers | LLM provider API call showing calls to the language model. The span name matches the provider, and attributes typically include the model name (like gpt-5.2 or claude-sonnet-4-5). | Identify which model was called, measure LLM response time, and debug LLM API errors. | | rpcn-mcp | MCP tool invocation representing calls to Remote MCP servers. Shows tool execution time, including network latency and tool processing. | Measure tool execution time and identify slow MCP tool calls. | ### [](#typical-agent-execution-flow)Typical agent execution flow A simple agent request creates this hierarchy: ai-agent (6.65 seconds) ├── agent (6.41 seconds) │ ├── invoke\_agent: customer-support-agent (6.39 seconds) │ │ └── openai: chat gpt-5.2 (6.2 seconds) This hierarchy shows that the LLM API call (6.2 seconds) accounts for most of the total agent invocation time (6.65 seconds), revealing the bottleneck in this execution flow. ## [](#mcp-server-transcript-hierarchy)MCP server transcript hierarchy MCP server tool invocations produce a different span hierarchy focused on tool execution and internal processing. This structure reveals performance bottlenecks and helps debug tool-specific issues. ### [](#mcp-server-span-types)MCP server span types MCP server transcripts contain these span types: | Span Type | Description | Use To | | --- | --- | --- | | mcp-{server-id} | Top-level span representing the entire MCP server invocation. The server ID uniquely identifies the MCP server instance. This span encompasses all tool execution from request receipt to response completion. | Measure total MCP server response time and identify slow tool invocations. | | service | Internal service processing span that appears at multiple levels in the hierarchy. Represents internal MCP server operations including routing, processing, and component execution. | Track internal processing overhead and identify where time is spent in the service layer. | | Tool name (for example, get_order_status, get_customer_history) | The specific MCP tool being invoked. This span name matches the tool name defined in the MCP server configuration. | Identify which tool was called and measure tool-specific execution time. | | processors | Processor pipeline execution span showing the collection of processors that process the tool’s data. Appears as a child of the tool invocation span. | Measure total processor pipeline execution time. | | Processor name (for example, mapping, http, branch) | Individual processor execution span representing a single internal processor in the MCP server pipeline. The span name matches the processor type. | Identify slow processors and debug processing logic. | ### [](#typical-mcp-server-execution-flow)Typical MCP server execution flow An MCP tool invocation creates this hierarchy: mcp-d5mnvn251oos73 (4.00 seconds) ├── service > get\_order\_status (4.07 seconds) │ └── service > processors (43 microseconds) │ └── service > mapping (18 microseconds) This shows: 1. Total MCP server invocation: 4.00 seconds 2. Tool execution (get\_order\_status): 4.07 seconds 3. Processor pipeline: 43 microseconds 4. Mapping processor: 18 microseconds (data transformation) The majority of time (4+ seconds) is spent in tool execution, while internal processing (mapping) takes only microseconds. This indicates the tool itself (likely making external API calls or database queries) is the bottleneck, not the MCP server’s internal processing. ## [](#transcript-layers-and-scope)Transcript layers and scope Transcripts contain multiple layers of instrumentation, from HTTP transport through application logic to external service calls. The `scope.name` field in each span identifies which instrumentation layer created that span. ### [](#instrumentation-layers)Instrumentation layers A complete agent transcript includes these layers: | Layer | Scope Name | Purpose | | --- | --- | --- | | HTTP Server | go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp | HTTP transport layer receiving requests. Shows request/response sizes, status codes, client addresses, and network details. | | AI SDK (Agent) | github.com/redpanda-data/ai-sdk-go/plugins/otel | Agent application logic. Shows agent invocations, LLM calls, tool executions, conversation IDs, token usage, and model details. Includes gen_ai.* semantic convention attributes. | | HTTP Client | go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp | Outbound HTTP calls from agent to MCP servers. Shows target URLs, request methods, and response codes. | | MCP Server | rpcn-mcp | MCP server tool execution. Shows tool name, input parameters, result size, and execution time. Appears as a separate service.name in resource attributes. | ### [](#how-layers-connect)How layers connect Layers connect through parent-child relationships in a single transcript: ai-agent-http-server (HTTP Server layer) └── invoke\_agent customer-support-agent (AI SDK layer) ├── chat gpt-5-nano (AI SDK layer, LLM call 1) ├── execute\_tool get\_order\_status (AI SDK layer) │ └── HTTP POST (HTTP Client layer) │ └── get\_order\_status (MCP Server layer, different service) │ └── processors (MCP Server layer) └── chat gpt-5-nano (AI SDK layer, LLM call 2) The request flow demonstrates: 1. HTTP request arrives at agent 2. Agent invokes sub-agent 3. Agent makes first LLM call to decide what to do 4. Agent executes tool, making HTTP call to MCP server 5. MCP server processes tool through its pipeline 6. Agent makes second LLM call with tool results 7. Response returns through HTTP layer ### [](#cross-service-transcripts)Cross-service transcripts When agents call MCP tools, the transcript spans multiple services. Each service has a different `service.name` in the resource attributes: - Agent spans: `"service.name": "ai-agent"` - MCP server spans: `"service.name": "mcp-{server-id}"` Both use the same `traceId`, allowing you to follow a request across service boundaries. ### [](#key-attributes-by-layer)Key attributes by layer Different layers expose different attributes: HTTP Server/Client layer (following [OpenTelemetry semantic conventions for HTTP](https://opentelemetry.io/docs/specs/semconv/http/http-spans/)): - `http.request.method`, `http.response.status_code` - `server.address`, `url.path`, `url.full` - `network.peer.address`, `network.peer.port` - `http.request.body.size`, `http.response.body.size` AI SDK layer (following [OpenTelemetry semantic conventions for generative AI](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/)): - `gen_ai.operation.name`: Operation type (`invoke_agent`, `chat`, `execute_tool`) - `gen_ai.conversation.id`: Links spans to the same conversation session. A conversation may include multiple agent invocations (one per user request). Each invocation creates a separate trace that shares the same conversation ID. - `gen_ai.agent.name`: Sub-agent name for multi-agent systems - `gen_ai.provider.name`, `gen_ai.request.model`: LLM provider and model - `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`: Token consumption - `gen_ai.usage.input_tokens_cost_usd`, `gen_ai.usage.output_tokens_cost_usd`: USD cost per call, derived from token counts and a per-model pricing table - `gen_ai.tool.name`, `gen_ai.tool.call.arguments`: Tool execution details - `gen_ai.input.messages`, `gen_ai.output.messages`: Full LLM conversation context MCP Server layer: - Tool-specific attributes like `order_id`, `customer_id` - `result_prefix`, `result_length`: Tool result metadata - Component-specific attributes from your tool configuration The `scope.name` field identifies which instrumentation layer created each span. ## [](#understand-the-transcript-structure)Understand the transcript structure Each span captures a unit of work. Here’s what a typical MCP tool invocation looks like: ```json { "traceId": "71cad555b35602fbb35f035d6114db54", "spanId": "43ad6bc31a826afd", "name": "http_processor", "attributes": [ {"key": "city_name", "value": {"stringValue": "london"}}, {"key": "result_length", "value": {"intValue": "198"}} ], "startTimeUnixNano": "1765198415253280028", "endTimeUnixNano": "1765198424660663434", "instrumentationScope": {"name": "rpcn-mcp"}, "status": {"code": 0, "message": ""} } ``` - `traceId` links all spans in the same request across services - `spanId` uniquely identifies this span - `name` identifies the operation or tool - `instrumentationScope.name` identifies which layer created the span (for example, `rpcn-mcp` for MCP tools) - `attributes` contain operation-specific metadata - `status.code` indicates success (0) or error (2) ### [](#parent-child-relationships)Parent-child relationships Transcripts show how operations relate. A tool invocation (parent) may trigger internal operations (children): ```json { "traceId": "71cad555b35602fbb35f035d6114db54", "spanId": "ed45544a7d7b08d4", "parentSpanId": "43ad6bc31a826afd", "name": "http", "instrumentationScope": {"name": "redpanda-connect"}, "status": {"code": 0, "message": ""} } ``` The `parentSpanId` links this child span to the parent tool invocation. Both share the same `traceId` so you can reconstruct the complete operation. ## [](#error-events-in-transcripts)Error events in transcripts When something goes wrong, transcripts capture error details: ```json { "traceId": "71cad555b35602fbb35f035d6114db54", "spanId": "ba332199f3af6d7f", "parentSpanId": "43ad6bc31a826afd", "name": "http_request", "events": [ { "name": "event", "timeUnixNano": "1765198420254169629", "attributes": [{"key": "error", "value": {"stringValue": "type"}}] } ], "status": {"code": 0, "message": ""} } ``` The `events` array captures what happened and when. Use `timeUnixNano` to see exactly when the error occurred within the operation. ## [](#opentelemetry-traces-topic)How Redpanda stores trace data The `redpanda.otel_traces` topic stores OpenTelemetry spans using Redpanda’s [Schema Registry](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#schema-registry) wire format, with a custom Protobuf schema named `redpanda.otel_traces-value` that follows the [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otel/protocol/) specification. Spans include attributes following OpenTelemetry [semantic conventions for generative AI](https://opentelemetry.io/docs/specs/semconv/gen-ai/), such as `gen_ai.operation.name` and `gen_ai.conversation.id`. The schema is automatically registered in the Schema Registry with the topic, so Kafka clients can consume and deserialize trace data correctly. Redpanda manages both the `redpanda.otel_traces` topic and its schema automatically. If you delete either the topic or the schema, they are recreated automatically. However, deleting the topic permanently deletes all trace data, and the topic comes back empty. Do not produce your own data to this topic. It is reserved for OpenTelemetry traces. ### [](#topic-configuration-and-lifecycle)Topic configuration and lifecycle The `redpanda.otel_traces` topic has a predefined retention policy. Configuration changes to this topic are not supported. If you modify settings, Redpanda reverts them to the default values. The topic persists even after all agents and MCP servers are deleted, allowing you to retain historical trace data for analysis. Transcripts may contain sensitive information from your tool inputs and outputs. Review the data in transcripts before sharing or exporting to external systems. Read access to transcript data is governed by the transcript permissions rather than by topic ACLs on `redpanda.otel_traces`. Among the built-in roles, only Admin holds them. See [Transcript permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#transcript-permissions). ## [](#how-redpanda-stores-audit-events)How Redpanda stores audit events When the Audit Log preview is enabled, Agentic Data Plane structures audit events according to the [Open Cybersecurity Schema Framework (OCSF)](https://ocsf.io/), an open, vendor-neutral schema for security events. OCSF gives events from different subsystems a shared vocabulary. Agentic Data Plane uses the OCSF API Activity event class for authorization decisions on API operations and the Entity Management event class for configuration changes. This keeps fields such as actor, resource, activity, and outcome consistent across the audit log. OCSF standardizes what an event means; it does not define how events are stored or exported. In Agentic Data Plane, use the Audit Log view to review these records. Redpanda keeps recent events in streaming storage and archives them in an Apache Iceberg-backed historical store in object storage. The Audit Log view presents both as one time-ordered history, so you can investigate new and older activity from the same view. Captured request, response, or configuration data may contain sensitive information. Agentic Data Plane redacts supported secret and sensitive configuration fields. Identities and other audit attributes may remain visible, and captured data may be truncated or omitted. Review an event before sharing it outside your organization. The Audit Log view returns events for your Agentic Data Plane environment. Access requires an audit log permission. See [Audit log permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#audit-log-permissions). ## [](#transcripts-compared-to-audit-logs)Transcripts compared to audit logs Transcripts and audit logs serve different but complementary purposes. Transcripts provide: - A complete, immutable record of every execution step, stored on Redpanda’s distributed log with no gaps - Hierarchical view of request flow through your system (parent-child span relationships) - Detailed timing information for performance analysis - Ability to reconstruct execution paths and identify bottlenecks Transcripts are optimized for execution-level observability and governance. The audit log provides: - The user accountable for an action, plus the agent or caller that acted for the user when available - The affected resource, operation, subsystem, and time - The allowed, partial, or denied outcome and the deciding policy when available For access and accountability questions, use [the audit log](https://docs.redpanda.com/agentic-data-plane/monitor/audit-log/). For questions about an agent’s model turns, tool calls, timing, or errors, use transcripts. An investigation may use both views. ## [](#history-reconstruction)Reconstructed transcript history Trace data on `redpanda.otel_traces` is subject to a retention policy. When a transcript covers a long-running conversation whose earliest spans have already been evicted, Redpanda reconstructs the missing turns from the LLM message context carried on later spans (`gen_ai.input.messages`) and sets the boolean field `is_reconstructed` to `true` on each affected turn. The UI surfaces this as a **Reconstructed** badge on those turns: `is_reconstructed` is the backing data field; "Reconstructed" is the visible label. Reconstructed turns preserve the high-level intent and role ordering of the conversation, but do not preserve byte-level fidelity: token counts, per-turn latency, and tool-call arguments are unavailable for the reconstructed range. ## [](#next-steps)Next steps - [See What Your Agent Did](https://docs.redpanda.com/agentic-data-plane/monitor/transcripts/) - [Monitor Agent Activity](https://docs.redpanda.com/agentic-data-plane/monitor/monitor-agents/) - [Visualize Your Agent Network](https://docs.redpanda.com/agentic-data-plane/monitor/agent-network/) - [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) --- # Page 77: Monitor Agent Activity **URL**: https://docs.redpanda.com/agentic-data-plane/monitor/monitor-agents.md --- # Monitor Agent Activity > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Monitor Agent Activity latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: monitor-agents page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: monitor-agents.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/monitor/pages/monitor-agents.adoc description: Monitor agent execution, inspect available MCP tools, analyze conversation history, track token usage, and debug issues using Playground and Transcripts. page-topic-type: how-to personas: agent_builder, platform_engineer, domain_evaluator learning-objective-1: Verify agent behavior and review its MCP capabilities using the Playground tab learning-objective-2: Track token usage and performance metrics learning-objective-3: Debug agent execution using transcripts page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-10" --- Use monitoring to track agent performance, analyze conversation patterns, debug execution issues, and optimize token costs. After reading this page, you will be able to: - Verify agent behavior and review its MCP capabilities using the **Playground** tab - Track token usage and performance metrics - Debug agent execution using transcripts For conceptual background on traces and observability, see [How Observability Works](https://docs.redpanda.com/agentic-data-plane/monitor/concepts/). ## [](#prerequisites)Prerequisites You must have a running agent. If you do not have one, see [Agentic Data Plane Quickstart for Agent Builders](https://docs.redpanda.com/agentic-data-plane/get-started/agent-builder-quickstart/). ## [](#debug-agent-execution-with-transcripts)Debug agent execution with transcripts An agent’s **Transcripts** tab shows each conversation with timing, errors, and token usage. Use it to debug issues, verify agent behavior, and monitor performance. ### [](#navigate-an-agents-transcripts)Navigate an agent’s transcripts 1. Open **Agents** in the sidebar and select your agent. 2. Open the **Transcripts** tab. The tab lists the agent’s recent conversations, one row per conversation: - `Conversation`: The conversation ID, with the conversation title when one exists. - `Started`: When the conversation began. - `Duration`: End-to-end wall-clock time. - `Turns`: Number of turns in the conversation. - `Status`: `Completed`, `Error`, or `Running`. - `Tokens`: Total tokens across the conversation. Use the search box to match a conversation ID or title, and the status dropdown to narrow the list to `Completed`, `Error`, or `Running` conversations. The list loads in pages; click **Load more** to fetch older conversations. #### [](#conversation-detail)Conversation detail Click a row to open the conversation. The header shows the conversation ID with a status badge, the start time, duration, and turn count, plus a total-tokens chip. Toggle between two views: - **Chat**: The user-visible exchange, as a conversation. - **Detailed**: Adds per-turn metadata: latency, input/output token splits, and each tool call with its arguments, result, latency, and status. If any turns were rebuilt from LLM message context after their original spans were evicted, those turns carry a _reconstructed_ marker. For the mechanics, see [Reconstructed transcript history](https://docs.redpanda.com/agentic-data-plane/monitor/concepts/#history-reconstruction). ### [](#check-agent-health)Check agent health Use the **Transcripts** tab to verify your agent is healthy. Recent conversations should show `Completed` status, duration within your expected range, and stable token usage without unexpected growth. Several warning signs indicate problems. Conversations with `Error` status need investigation. When duration increases over time, your context window may be growing or tool calls could be slowing down. Many LLM calls for simple requests often signal that the agent is stuck in loops or making unnecessary iterations. If you see no new transcripts, the agent may be stopped or encountering deployment issues. Pay attention to patterns across multiple conversations. When all recent transcripts show errors, start by checking agent status, MCP server connectivity, and system prompt configuration. A list that alternates between success and error typically points to intermittent tool failures or external API issues. If duration increases steadily over a session, your context window is likely filling up. Clear the conversation history to reset it. High token usage combined with relatively few LLM calls usually means tool results are large or your system prompts are verbose. ### [](#debug-with-transcripts)Debug with transcripts Use the **Transcripts** tab to diagnose specific issues: If the agent is not responding: 1. Check the list for recent conversations. If none appear, the agent may be stopped. 2. Verify agent status in the main **Agents** view. 3. Look for error transcripts with deployment or initialization failures. If the agent fails during execution: 1. Set the status dropdown to `Error` and open the failed conversation. 2. Switch to the **Detailed** view and find the turn carrying the error. 3. Check the tool call’s arguments and result for error messages. 4. Cross-reference with MCP server status. If performance is slow: 1. Compare the `Duration` column across recent conversations. 2. Open a slow conversation in the **Detailed** view and scan per-turn latency to find the bottleneck. 3. Check if LLM calls are taking longer than expected. 4. Verify tool execution time on the nested tool calls. ### [](#track-token-usage-and-costs)Track token usage and costs View token consumption in the conversation detail view. The **Detailed** view breaks each turn into input tokens (everything sent to the LLM including system prompt, conversation history, and tool results) and output tokens (what the LLM generates in agent responses); the header chip shows the conversation total. Calculate cost per request: Cost = (input\_tokens x input\_price) + (output\_tokens x output\_price) Example: GPT-5.2 with 4,302 input tokens and 1,340 output tokens at $0.00000175 per input token and $0.000014 per output token costs $0.026 per request. For cost optimization strategies, see [Cost calculation](https://docs.redpanda.com/agentic-data-plane/connect/concepts/#cost-calculation). ## [](#test-agent-behavior-with-playground)Test agent behavior with Playground The **Playground** tab provides real-time conversation testing. Use it to test agent responses interactively and verify behavior before deploying changes. ![Playground test loop. A user sends a prompt, the agent streams responses, artifacts, and MCP tool calls, and Playground shows context and token usage. The user can retry or clear context, while completed runs remain available in transcripts and activity views.](https://docs.redpanda.com/agentic-data-plane/monitor/_images/agent-inspector-test-loop.svg) Figure 1. Playground closes the loop between a test prompt and production evidence ### [](#access-playground)Access Playground 1. Open **Agents** in the sidebar. 2. Click your agent name. 3. Open the **Playground** tab. 4. Enter test queries and review responses. 5. Check the conversation panel to see tool calls. 6. Start a new session to test fresh conversations or click **Clear context** to reset history. ### [](#review-mcp-tools-and-subagents)Review MCP tools and subagents For a managed agent, the Playground composer has a **Tools** control, and a **Subagents** control when the agent delegates to subagents. Use them to review the capabilities available to the agent before you send a test message. To review the agent’s direct MCP servers and their tools: ![Playground tool discovery. The Tools control displays direct MCP servers, and the Subagents control displays the agent’s subagents. Direct servers expose their tools to the agent. Each subagent exposes only the tools from the MCP servers configured for that subagent. Authentication and availability affect which tools are visible.](https://docs.redpanda.com/agentic-data-plane/monitor/_images/inspector-mcp-tool-discovery.svg) Figure 2. Playground shows tool access through direct MCP servers and subagents 1. Open the agent’s **Playground** tab. 2. Click **Tools** in the composer. 3. Under Direct MCP servers, expand a server to see its type, description, and exposed tools. Each tool entry shows its name and description when the server provides one. The list reflects the agent’s current configuration and the tools each direct MCP server exposes. It does not guarantee that a later tool call succeeds. Server availability, access policy, or an external connection can still affect a call at runtime. Some remote MCP servers require you to connect your own account before their tools are shown. Expand the server and click **Connect**, complete the authorization in the new browser tab, then return to Playground. The list refreshes when you return. If it does not, click **Refresh tools**. Use the status shown under a server to resolve common issues: | Status | What to do | | --- | --- | | Authentication required | Click Connect and complete the authorization flow. Protected tools remain hidden until the connection grants the required access. | | Unavailable | Ask an administrator to confirm that the MCP server exists and is enabled for the agent. | | Couldn’t load tools | Click Try again. If the error continues, check the MCP server’s availability and authentication settings. | | No tools exposed by this MCP server | Confirm that the server publishes tools and that the agent is connected to the intended server. | When the agent delegates to subagents, the composer also shows a **Subagents** control next to **Tools**. Click it to review the delegation targets this agent can orchestrate. Each entry lists the subagent’s name, its description, and the MCP servers configured on it. ### [](#context-window-usage)Context-window usage As you test, the composer tracks how much of the model’s context window the conversation consumes. When the agent uses a model from Redpanda’s catalog, a context-usage indicator appears in the composer after the first response and shows the share of the context window in use. Click it to open a breakdown of the window size, the input, output, reasoning, and cached tokens for the session, the **Session total**, and the estimated **Total cost**. The indicator counts input tokens plus cached tokens, so it reflects the full context occupancy under prompt caching, not fresh input alone. As a conversation grows and the indicator approaches the window size, start a new session or click **Clear context** to reset the history before responses slow down or the agent starts dropping earlier context. For models that aren’t in the catalog, such as OpenAI-compatible providers or hand-entered model IDs, the composer shows a plain input and output token count instead, because the context-window size isn’t known. ### [](#long-running-tasks)Long-running tasks The Playground live view streams a test run as it happens. If a task is still running after about five minutes, Playground stops the live view and shows a **Still running** notice: the task keeps running in the background, so you don’t need to hold the Playground open. Follow it to completion on the **Activity** tab of the **Cost & Usage** page under **Governance**. ### [](#testing-best-practices)Testing best practices Test your agents systematically by exploring edge cases and potential failure scenarios. Begin with boundary testing. Requests at the edge of agent capabilities verify that scope enforcement works correctly. Error handling becomes clear when you request unavailable data and observe whether the agent degrades gracefully. Even with proper system prompt constraints, testing confirms that your agent responds appropriately to edge cases. Monitor iteration counts during complex requests to ensure they complete within your configured limits. Ambiguous or vague queries reveal whether the agent asks clarifying questions or makes risky assumptions. Throughout testing, track token usage per request to estimate costs and identify which query patterns consume the most resources. ## [](#next-steps)Next steps - [How Observability Works](https://docs.redpanda.com/agentic-data-plane/monitor/concepts/) - [Visualize Your Agent Network](https://docs.redpanda.com/agentic-data-plane/monitor/agent-network/) - [Troubleshoot Agents](https://docs.redpanda.com/agentic-data-plane/monitor/troubleshoot-ai-agents/) --- # Page 78: See What Your Agent Did **URL**: https://docs.redpanda.com/agentic-data-plane/monitor/transcripts.md --- # See What Your Agent Did > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: See What Your Agent Did latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: transcripts page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: transcripts.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/monitor/pages/transcripts.adoc description: Open a transcript in Agentic Data Plane, read the conversation turn by turn, and investigate errors, costs, and performance. page-topic-type: how-to personas: agent_builder, domain_evaluator, platform_engineer, security_compliance_lead learning-objective-1: Open a transcript from an agent's Transcripts tab learning-objective-2: Read a transcript as a turn-by-turn conversation, including tool calls and token usage learning-objective-3: Investigate errors, slow turns, and cost anomalies from the transcript detail view page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-03" --- Use an agent’s transcripts to read a complete record of each conversation, turn by turn. Each transcript captures the conversation between the user, the agent, any LLM calls, and any tools it invoked, along with token usage, latency, estimated cost, and any errors. For conceptual background on the underlying OpenTelemetry data model, see [How Observability Works](https://docs.redpanda.com/agentic-data-plane/monitor/concepts/). After reading this page, you will be able to: - Open a transcript from an agent’s Transcripts tab - Read a transcript as a turn-by-turn conversation, including tool calls and token usage - Investigate errors, slow turns, and cost anomalies from the transcript detail view ## [](#prerequisites)Prerequisites - A [running agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/) with at least one execution. - Access to read transcripts, from an [access policy](https://docs.redpanda.com/agentic-data-plane/control/access-policies/) granting the `Transcript` actions, or from the Admin role. No other built-in role grants transcript reads. ## [](#open-an-agents-transcripts)Open an agent’s transcripts 1. Open **Agents** in the sidebar and select the agent. 2. Open the **Transcripts** tab. The tab lists the agent’s recent conversations, one row per conversation. ## [](#read-the-transcripts-list)Read the transcripts list Each row represents one conversation. Columns include: - `Conversation`: The conversation ID, with the conversation title when one exists. - `Started`: When the conversation began. - `Duration`: End-to-end wall-clock time. - `Turns`: Number of turns in the conversation. - `Status`: `Completed`, `Error`, or `Running`. - `Tokens`: Total tokens across the conversation. A transcript marked _reconstructed_ is one in which some turns were rebuilt from LLM message context after the original spans were evicted from `redpanda.otel_traces`. See [Reconstructed transcript history](https://docs.redpanda.com/agentic-data-plane/monitor/concepts/#history-reconstruction) for what that means. ### [](#filter-the-list)Filter the list - Use the search box to match against a conversation ID or title. - Use the status dropdown to narrow the list to `Completed`, `Error`, or `Running` conversations. The list loads in pages. Click **Load more** to fetch older conversations, and use the refresh control to pick up new ones. ## [](#open-a-transcript)Open a transcript Click any row to open the conversation detail view. The view has two parts: a summary header and the conversation. ### [](#summary-header)Summary header The summary header reports: - The conversation ID and a status badge (`Completed`, `Error`, or `Running`). - The start time, end-to-end duration, and turn count. - A total-tokens chip. - A **Chat** / **Detailed** view toggle. Chat shows the user-visible exchange; Detailed adds per-turn metadata such as latency, token splits, and tool calls. If the conversation ended with a top-level error, an error banner appears below the header with the code and message. ### [](#read-the-conversation)Read the conversation Turns are listed in order by role: - **SYSTEM**: The system prompt and any priming instructions. - **USER**: A user message that started or continued the conversation. - **ASSISTANT**: A response from the LLM. In the Detailed view, shows input/output token counts and latency. If the assistant turn called a tool, its tool calls are nested underneath. - **TOOL**: A tool invocation. Shows the tool name, the arguments passed, the result, and the latency of the call. Any turn may carry the `is_reconstructed` marker. Reconstructed turns preserve role order and the high-level content of the conversation but do not carry per-turn token counts, latency, or tool-call arguments. See [Reconstructed transcript history](https://docs.redpanda.com/agentic-data-plane/monitor/concepts/#history-reconstruction) for the mechanics. ### [](#errors)Errors An errored transcript shows `TranscriptStatus.ERROR` in the summary header. The specific failure appears on the turn that raised it, with: - **Code**: `TranscriptError.code` (for example, a provider error code or `INVALID_ARGUMENT`) - **Message**: A short description from the LLM provider, the tool, or the agent runtime If the failure happened during a tool call, the error is attached to the TOOL turn; if it was an LLM call, it’s on the ASSISTANT turn; if neither, it’s on the trace root. ## [](#common-investigation-tasks)Common investigation tasks ### [](#debug-errors)Debug errors 1. Set the status dropdown to `Error`. 2. Open the failing transcript and scroll to the turn carrying the error code. 3. Read the immediately preceding turns (tool arguments, assistant output) for root cause. ### [](#investigate-performance-issues)Investigate performance issues 1. Sort the list visually by the `Duration` column to spot slow conversations. 2. Open a slow transcript, switch to the **Detailed** view, and scan the per-turn latency to find the bottleneck turn. 3. For tool-bound bottlenecks, expand the tool call to see arguments and result size: a large result often correlates with slow tool execution. ### [](#analyze-tool-usage)Analyze tool usage Open a transcript in the **Detailed** view to read each tool call: arguments in, results out, latency, and a status pill. Tool calls are nested under the assistant turn that made them. ### [](#monitor-llm-interactions-and-cost)Monitor LLM interactions and cost The transcript shows token usage per turn. For spend analysis across agents, models, and users, open **Cost & Usage** under **Governance** in the sidebar (see [Analyze Cost and Usage](https://docs.redpanda.com/agentic-data-plane/control/cost-usage/)), or use breakdown queries through `SpendingService`; per-transcript `estimated_cost_usd` is also available through the Transcripts API. ## [](#limitations)Limitations - The list loads in pages from most recent backward. If the conversation you need is old, keep loading more pages or search by its conversation ID. - Reconstructed turns do not carry token counts, latency, or tool-call arguments for the reconstructed range. For byte-level fidelity, lower the ingestion lag or extend `redpanda.otel_traces` retention (see [How Redpanda stores trace data](https://docs.redpanda.com/agentic-data-plane/monitor/concepts/#opentelemetry-traces-topic)). - Estimated USD cost is only populated for models covered by the pricing table. ## [](#troubleshooting)Troubleshooting ### [](#transcript-stuck-in-running)Transcript stuck in RUNNING A transcript stays in `RUNNING` until the root span closes. Common causes: - The agent or MCP server is still executing (this is normal: Wait, or open a newer transcript). - The root span never flushed because the process was killed mid-execution. Expect this to resolve after the OTLP ingestion lag clears; if it doesn’t after several minutes, the trace is likely orphaned. ### [](#usd-cost-shows-0)USD cost shows 0 `TranscriptUsage.estimated_cost_usd` is populated by the cost-reporting pipeline from the `gen_ai.usage.*` attributes on each LLM-call span combined with a per-model pricing table. For the full list of cost-bearing attributes (including the explicit USD-cost fields), see [Key attributes by layer](https://docs.redpanda.com/agentic-data-plane/monitor/concepts/#key-attributes-by-layer). If cost is `0` for a transcript that clearly used tokens, check: - The model is in the pricing table. To use a custom rate (negotiated contract, internal chargeback), see [Override per-model pricing](https://docs.redpanda.com/agentic-data-plane/control/budgets/#override-per-model-pricing). - The cost-reporting pipeline is enabled on your environment. - The LLM-call spans carry the `gen_ai.usage.*` attributes the pipeline reads: Either the token-count inputs (`gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`) or the explicit USD-cost fields listed on the concepts page. > 📝 **NOTE** > > Cache-write tokens (Anthropic 4.x, OpenAI 4.x prompt caches) are attributed to the **CACHED** bucket on streaming and non-streaming responses alike. If a transcript shows zero cache cost on a request that clearly populated a prompt cache, check that the upstream actually wrote to the cache (the response includes a non-zero `cache_creation_input_tokens` or equivalent token-count field) before treating it as a discrepancy. ### [](#all-turns-marked-reconstructed)All turns marked reconstructed Reconstruction happens when the original spans have been evicted from `redpanda.otel_traces`. Causes: - Retention on `redpanda.otel_traces` is aggressive relative to how long the conversation has been running. - OTLP ingestion fell behind and the span was dropped before it reached the topic. For long-running conversations, accept some reconstruction; for short conversations whose turns are all reconstructed, investigate ingestion and retention. ### [](#transcript-missing-entirely)Transcript missing entirely - Confirm the agent or MCP server actually ran: Check its logs and the corresponding session or task topic. - Confirm your user can read transcripts. Outside the Admin role, transcript reads come from an [access policy](https://docs.redpanda.com/agentic-data-plane/control/access-policies/) naming the `Transcript` actions. Check the Access page for a policy that covers your user or one of its groups, and for a `forbid` that overrides it. See [Transcript permissions](https://docs.redpanda.com/agentic-data-plane/control/permissions-reference/#transcript-permissions). - Confirm the feature flag enabling transcripts is on for your environment. ## [](#next-steps)Next steps - [Monitor Agent Activity](https://docs.redpanda.com/agentic-data-plane/monitor/monitor-agents/) - [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) - [Troubleshoot Agents](https://docs.redpanda.com/agentic-data-plane/monitor/troubleshoot-ai-agents/) --- # Page 79: Troubleshoot Agents **URL**: https://docs.redpanda.com/agentic-data-plane/monitor/troubleshoot-ai-agents.md --- # Troubleshoot Agents > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Troubleshoot Agents latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: troubleshoot-ai-agents page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: troubleshoot-ai-agents.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/monitor/pages/troubleshoot-ai-agents.adoc description: Diagnose and fix common issues with AI agents including deployment failures, runtime behavior problems, and tool execution errors. page-topic-type: troubleshooting personas: agent_builder, platform_engineer learning-objective-1: Diagnose deployment failures and resource allocation errors learning-objective-2: Resolve runtime behavior issues including tool selection and iteration limits learning-objective-3: Fix tool execution problems and authentication failures page-git-created-date: "2026-05-28" page-git-modified-date: "2026-08-07" --- Use this page to diagnose and fix common issues with AI agents, including deployment failures, runtime behavior problems, tool execution errors, and integration issues. ## [](#deployment-issues)Deployment issues Fix issues that prevent agents from connecting to required resources. ### [](#mcp-server-connection-failures)MCP server connection failures **Symptoms:** Agent starts but the tools don’t respond or return connection errors. **Causes:** - MCP server stopped or crashed after agent creation - Network connectivity issues between agent and MCP server - MCP server authentication or permission issues **Solution:** 1. Verify MCP server status in **Remote MCP**. 2. Check MCP server logs for errors. 3. Restart the MCP server if needed. 4. Verify agent has permission to access the MCP server. **Prevention:** - Monitor MCP server health - Use appropriate retry logic in tools ## [](#runtime-behavior-issues)Runtime behavior issues Resolve problems with agent decision-making, tool selection, and response generation. ### [](#agent-not-calling-tools)Agent not calling tools **Symptoms:** Agent responds without calling any tools, or fabricates information instead of using tools. **Causes:** - System prompt doesn’t clearly specify when to use tools - Tool descriptions are vague or missing - LLM model lacks sufficient reasoning capability - Max iterations is too low **Solution:** 1. Strengthen tool usage guidance in your system prompt: ```text ALWAYS use get_order_status when customer mentions an order ID. NEVER respond about order status without calling the tool first. ``` 2. Review tool descriptions in your MCP server configuration. 3. Use a more capable model from the supported list for your gateway. 4. Increase max iterations if the agent is stopping before reaching tools. **Prevention:** - Write explicit tool selection criteria in system prompts - Test agents with the [systematic testing approach](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/#evaluation-and-testing) - Use models appropriate for your task complexity ### [](#calling-wrong-tools)Calling wrong tools **Symptoms:** Agent selects incorrect tools for the task, or calls tools with invalid parameters. **Causes:** - Tool descriptions are ambiguous or overlap - Too many similar tools confuse the LLM - System prompt doesn’t provide clear tool selection guidance **Solution:** 1. Make tool descriptions more specific and distinct. 2. Add "when to use" guidance to your system prompt: ```text Use get_order_status when: - Customer provides an order ID (ORD-XXXXX) - You need to check current order state Use get_shipping_info when: - Order status is "shipped" - Customer asks about delivery or tracking ``` 3. Reduce the number of tools you expose to the agent. 4. Use subagents to partition tools by domain. **Prevention:** - Follow tool design patterns in [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) - Limit each agent to 10-15 tools maximum - Test boundary cases where multiple tools might apply ### [](#stuck-in-loops-or-exceeding-max-iterations)Stuck in loops or exceeding max iterations **Symptoms:** Agent reaches max iterations without completing the task, or repeatedly calls the same tool with the same parameters. **Causes:** - Tool returns errors that the agent doesn’t know how to handle - Agent doesn’t recognize when the task is complete - Tool returns incomplete data that prompts another call - System prompt encourages exhaustive exploration **Solution:** 1. Add completion criteria to your system prompt: ```text When you have retrieved all requested information: 1. Present the results to the user 2. Stop calling additional tools 3. Do not explore related data unless asked ``` 2. Add error handling guidance: ```text If a tool fails after 2 attempts: - Explain what went wrong - Do not retry the same tool again - Move on or ask for user guidance ``` 3. Review tool output to ensure it signals completion clearly. 4. Increase max iterations if the task legitimately requires many steps. **Prevention:** - Design tools to return complete information in one call - Set max iterations appropriate for task complexity (see [Why iterations matter](https://docs.redpanda.com/agentic-data-plane/connect/concepts/#why-iterations-matter)) - Test with ambiguous requests that might cause loops ### [](#making-up-information)Making up information **Symptoms:** Agent provides plausible-sounding answers without calling tools, or invents data when tools fail. **Causes:** - System prompt doesn’t explicitly forbid fabrication - Agent treats tool failures as suggestions rather than requirements - Model is hallucinating due to lack of constraints **Solution:** 1. Add explicit constraints to your system prompt: ```text Critical rules: - NEVER make up order numbers, tracking numbers, or customer data - If a tool fails, explain the failure - do not guess - If you don't have information, say so explicitly ``` 2. Test error scenarios by temporarily disabling tools. 3. Use a more capable model that follows instructions better. **Prevention:** - Include "never fabricate" rules in all system prompts - Test with requests that require unavailable data - Monitor transcripts and session topic for fabricated responses ### [](#analyzing-conversation-patterns)Analyzing conversation patterns **Symptoms:** Agent behavior is inconsistent or produces unexpected results. **Solution:** Review conversation history in transcripts to identify problematic patterns: - Agents calling the same tool repeatedly: Indicates loop detection is needed - Large gaps between messages: Suggests tool timeout or slow execution - Agent responses without tool calls: Indicates a tool selection issue - Fabricated information: Suggests a missing "never make up data" constraint - Truncated early messages: Indicates the context window was exceeded **Analysis workflow:** 1. Use **Playground** to reproduce the issue. 2. Review full conversation including tool invocations. 3. Identify where agent behavior diverged from expected. 4. Check system prompt for missing guidance. 5. Verify tool responses are formatted correctly. ## [](#performance-issues)Performance issues Diagnose and fix issues related to agent speed and resource consumption. ### [](#slow-response-times)Slow response times **Symptoms:** Agent takes 10+ seconds to respond to simple queries. **Causes:** - LLM model is slow (large context processing) - Too many tool calls in sequence - Tools themselves are slow (database queries, API calls) - Large context window from long conversation history **Solution:** 1. Use a faster, lower-latency model tier for simple queries and reserve larger models for complex reasoning. 2. Review conversation history in the **Playground** tab to identify unnecessary tool calls. 3. Optimize tool implementations: 1. Add caching where appropriate 2. Reduce query complexity 3. Return only needed data (use pagination, filters) 4. Clear the conversation history if the context is very large. **Prevention:** - Right-size model selection based on task complexity - Design tools to execute quickly (< 2 seconds ideal) - Set appropriate max iterations to prevent excessive exploration - Monitor token usage and conversation length ### [](#high-token-costs)High token costs **Symptoms:** Token usage is higher than expected, costs are increasing rapidly. **Causes:** - Max iterations configured too high - Agent making unnecessary tool calls - Large tool results filling context window - Long conversation history not being managed - Using expensive models for simple tasks **Solution:** 1. Review token usage in transcripts. 2. Lower max iterations for this agent. 3. Optimize tool responses to return less data: ```text Bad: Return all 10,000 customer records Good: Return paginated results, 20 records at a time ``` 4. Add cost control guidance to system prompt: ```text Efficiency guidelines: - Request only the data you need - Stop when you have enough information - Do not call tools speculatively ``` 5. Switch to a more cost-effective model for simple queries. 6. Clear conversation history periodically in the **Playground** tab. **Prevention:** - Set appropriate max iterations (10-20 for simple, 30-40 for complex) - Design tools to return minimal necessary data - Monitor token usage trends - See cost calculation guidance in [Cost calculation](https://docs.redpanda.com/agentic-data-plane/connect/concepts/#cost-calculation) ## [](#tool-execution-issues)Tool execution issues Fix problems with timeouts, invalid parameters, and error responses. ### [](#tool-timeouts)Tool timeouts **Symptoms:** Tools fail with timeout errors, agent receives incomplete results. **Causes:** - External API is slow or unresponsive - Database query is too complex - Network latency between tool and external system - Tool processing large datasets in memory **Solution:** 1. Add timeout handling to tool implementation: ```yaml http: url: https://api.example.com/data timeout: "5s" # Set explicit timeout ``` 2. Optimize external queries: 1. Add database indexes 2. Reduce query scope 3. Cache frequent queries 3. Increase tool timeout if operation legitimately takes longer. 4. Add retry logic for transient failures. **Prevention:** - Set explicit timeouts in all tool configurations - Test tools under load - Monitor external API performance - Design tools to fail fast on unavailable services ### [](#invalid-parameters)Invalid parameters **Symptoms:** Tools return validation errors about missing or incorrectly formatted parameters. **Causes:** - Tool schema doesn’t match implementation - Agent passes wrong data types - Required parameters not marked as required in schema - Agent misunderstands parameter purpose **Solution:** 1. Verify tool schema matches implementation: ```yaml input_schema: properties: order_id: type: string # Must match what tool expects description: "Order ID in format ORD-12345" ``` 2. Add parameter validation to tools. 3. Improve parameter descriptions in tool schema. 4. Add examples to tool descriptions: ```yaml description: | Get order status by order ID. Example: get_order_status(order_id="ORD-12345") ``` **Prevention:** - Write detailed parameter descriptions - Include format requirements and examples - Test tools with invalid inputs to verify error messages - Use JSON Schema validation in tool implementations ### [](#tool-returns-errors)Tool returns errors **Symptoms:** Tools execute but return error responses or unexpected data formats. **Causes:** - External API returned error - Tool implementation has bugs - Data format changed in external system - Tool lacks error handling **Solution:** 1. Check tool logs in MCP server. 2. Test tool directly (outside agent context). 3. Verify external system is operational. 4. Add error handling to tool implementation: ```yaml processors: - try: - http: url: ${API_URL} catch: - mapping: | root.error = "API unavailable: " + error() ``` 5. Update agent system prompt to handle this error type. **Prevention:** - Implement comprehensive error handling in tools - Monitor external system health - Add retries for transient failures - Log all tool errors for analysis ## [](#integration-issues)Integration issues Fix problems with external applications calling agents and pipeline-to-agent integration. ### [](#agent-card-does-not-contain-a-url)Agent card does not contain a URL **Symptoms:** Pipeline fails with error: `agent card does not contain a URL` or `failed to init processor path root.pipeline.processors.0` **Causes:** - The `agent_card_url` points to the base agent endpoint instead of the agent card JSON file **Solution:** The `agent_card_url` must point to the agent card JSON file, not the base agent endpoint. **Incorrect configuration:** ```yaml processors: - a2a_message: agent_card_url: "https://your-agent-id.ai-agents.your-cluster-id.clusters.rdpa.co" prompt: "Analyze this transaction: ${!content()}" ``` **Correct configuration:** ```yaml processors: - a2a_message: agent_card_url: "https://your-agent-id.ai-agents.your-cluster-id.clusters.rdpa.co/.well-known/agent-card.json" prompt: "Analyze this transaction: ${!content()}" ``` The agent card is always available at `/.well-known/agent-card.json` according to the A2A protocol standard. **Prevention:** - Always append `/.well-known/agent-card.json` to the agent endpoint URL - Test the agent card URL in a browser before using it in pipeline configuration - See [Agent card location](https://docs.redpanda.com/agentic-data-plane/connect/a2a-concepts/#agent-card-location) for details ### [](#pipeline-integration-failures)Pipeline integration failures **Symptoms:** Pipelines using `a2a_message` processor fail or timeout. **Causes:** - Agent is not running or restarting - Agent timeout is too low for pipeline workload - Authentication issues between pipeline and agent - High event volume overwhelming agent **Solution:** 1. Check agent status and resource allocation. 2. Increase agent resource tier for high-volume pipelines. 3. Add error handling in pipeline: ```yaml processors: - try: - a2a_message: agent_card_url: "https://your-agent-url/.well-known/agent-card.json" catch: - log: message: "Agent invocation failed: ${! error() }" ``` **Prevention:** - Test pipeline-agent integration with low volume first - Size agent resources appropriately for event rate - See integration patterns in [Integrate with Redpanda Pipelines](https://docs.redpanda.com/agentic-data-plane/connect/pipeline-integration-patterns/) ## [](#monitor-and-debug-agents)Monitor and debug agents For comprehensive guidance on monitoring agent activity, analyzing conversation history, tracking token usage, and debugging issues, see [Monitor Agent Activity](https://docs.redpanda.com/agentic-data-plane/monitor/monitor-agents/). ## [](#next-steps)Next steps - [Write Effective System Prompts](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/) - [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/) - [Choose an Agent Architecture](https://docs.redpanda.com/agentic-data-plane/connect/architecture-patterns/) --- # Page 80: Reference **URL**: https://docs.redpanda.com/agentic-data-plane/reference.md --- # Reference > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Reference latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: index page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/index.adoc description: Field and command reference for Agentic Data Plane. page-git-created-date: "2026-04-29" page-git-modified-date: "2026-06-01" --- Look up the details. This section covers the `rpk` command-line reference and the Agentic Data Plane glossary. - [Install or Update rpk](rpk-install/) Install or update rpk to interact with Redpanda from the command line. - [rpk Command Reference](rpk/) Reference for the rpk commands used to manage the Redpanda Agentic Data Plane from the command line. - [Glossary](glossary/) Definitions of key terms used in Redpanda Agentic Data Plane documentation. - [Release Notes](release-notes/) What's new in the Agentic Data Plane: new features, improvements, and bug fixes, by release. --- # Page 81: Glossary **URL**: https://docs.redpanda.com/agentic-data-plane/reference/glossary.md --- # Glossary > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Glossary latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: glossary page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: glossary.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/glossary.adoc description: Definitions of key terms used in Redpanda Agentic Data Plane documentation. page-git-created-date: "2026-04-23" page-git-modified-date: "2026-06-29" --- ## [](#agentic-data-plane)Agentic Data Plane ### [](#agent2agent-a2a-protocol)Agent2Agent (A2A) protocol Communication protocol that enables AI agents to discover, coordinate with, and delegate tasks to other agents in a distributed system. The A2A protocol allows agents to work together by sharing capabilities, coordinating workflows, and distributing complex tasks across multiple specialized agents. It provides standardized messaging, capability discovery, and task delegation mechanisms for multi-agent systems. ### [](#agentic-data-plane-2)Agentic Data Plane Infrastructure layer that enables AI agents to discover, connect to, and interact with data sources and tools through standardized protocols. The Agentic Data Plane provides the underlying infrastructure for AI agents to access streaming data, invoke tools, and coordinate operations across distributed systems using protocols like MCP and A2A. ### [](#ai-agent)AI agent A system built around a large language model (LLM) that interprets user intent, selects the right tools, and chains multiple steps into a workflow. AI agents can understand natural language instructions, reason about tasks, invoke tools through MCP servers, and coordinate multiple operations to accomplish complex workflows. ### [](#ai-gateway)AI Gateway A unified entry point for AI traffic that provides LLM routing, MCP tool aggregation, cost controls, and observability across multiple LLM providers. ### [](#ai-token)AI token A credential used specifically for authenticating AI agents and authorizing their access to resources in agentic systems. AI tokens are specialized authentication credentials for AI agents, distinct from bearer tokens used in traditional API authentication. They enable agents to authenticate with MCP servers and access data plane resources while maintaining audit trails of agent operations. ### [](#context-window)context window The maximum amount of text (measured in tokens) that an LLM can process in a single request. The context window determines how much information an agent can consider at once, including the system prompt, conversation history, tool outputs, and retrieved documents. Larger context windows enable more sophisticated reasoning but may increase latency and cost. Common sizes range from 8K to 200K+ tokens. ### [](#declarative-agent)declarative agent An AI agent that runs in Redpanda’s managed runtime, where you configure its behavior (LLM, system prompt, and attached tools) instead of writing agent code. Contrast with a self-managed agent, which you build and run in your own runtime. ### [](#frontier-model)frontier model The most advanced and capable AI models available, representing the current state-of-the-art in language understanding and reasoning. Frontier models are cutting-edge large language models with exceptional reasoning, planning, and problem-solving capabilities. Examples include GPT-4, Claude 3, and Gemini Ultra. These models are commonly used to power sophisticated AI agents that require advanced decision-making and tool orchestration. ### [](#large-language-model-llm)large language model (LLM) An AI model trained on vast amounts of text data that can understand and generate human-like text, reason about tasks, and follow instructions. Large language models power AI agents by providing natural language understanding, reasoning capabilities, and the ability to plan and execute complex tasks. LLMs interpret user requests, decide which tools to invoke, and synthesize responses based on retrieved data. ### [](#mcp-client)MCP client An AI application or agent that connects to MCP servers to discover and invoke tools. MCP clients use the Model Context Protocol to communicate with MCP servers, discovering available tools, understanding their capabilities, and invoking them with appropriate parameters. The client handles authentication, request formatting, and response processing. ### [](#mcp-server)MCP server A service that exposes tools and resources using the Model Context Protocol, allowing AI agents to discover and invoke them. MCP servers act as bridges between AI agents and external systems, providing standardized interfaces for tool discovery, invocation, and resource access. ### [](#model-context-protocol-mcp)Model Context Protocol (MCP) A standardized protocol that enables AI agents to connect with external data sources and tools in Redpanda. MCP provides a consistent interface for AI applications to discover and interact with data sources, services, and computational tools through Redpanda infrastructure. ### [](#oauth-client)OAuth client An Agentic Data Plane resource that governs inbound authentication: an external app (Claude Desktop, ChatGPT, Copilot Studio) authenticating to AI Gateway so the app’s users can invoke MCP tools. Separate from an OAuth provider, which governs outbound authentication. ### [](#oauth-connection)OAuth connection A stored authorization that links a user to a third-party provider, created when the user completes the OAuth consent flow. OAuth connections hold access and refresh tokens in the token vault for agents to use on the user’s behalf. ### [](#oauth-provider)OAuth provider An Agentic Data Plane resource that governs outbound authentication: AI Gateway authenticating to an upstream system (GitHub, Slack, Salesforce, and so on) on a user’s behalf so MCP servers can call it. Separate from an OAuth client, which governs inbound authentication. ### [](#observability-o11y)observability (o11y) The ability to understand a system’s internal state by examining its external outputs, such as traces, metrics, and logs. In Redpanda’s agentic systems, observability enables debugging agent behavior, monitoring performance, analyzing execution flow, and identifying bottlenecks through transcripts captured in the `redpanda.otel_traces` topic. ### [](#opentelemetry)OpenTelemetry Open-source observability framework that provides standardized APIs, libraries, and tools for capturing and exporting telemetry data. OpenTelemetry provides standardized APIs for capturing traces, metrics, and logs from applications. Redpanda agents and MCP servers automatically emit OpenTelemetry traces to the `redpanda.otel_traces` topic to provide complete observability into agentic system operations. ### [](#otlp-opentelemetry-protocol)OTLP (OpenTelemetry Protocol) Standard protocol for encoding and transmitting telemetry data defined by the OpenTelemetry project. OTLP is the OpenTelemetry Protocol specification for encoding and transmitting telemetry data. Redpanda stores spans in the `redpanda.otel_traces` topic using a Protobuf schema that closely follows the OTLP specification. ### [](#prompt)prompt Natural language instructions or context provided to an LLM to guide its behavior and responses. Prompts are the primary way to communicate with LLMs and AI agents. They can include instructions, examples, context, and questions that guide the model’s reasoning and output. Effective prompt design is critical for agent performance and reliability. ### [](#resource)resource Read-only data that an MCP server exposes and agents can fetch by URI. Resources provide file contents, database rows, or API responses without performing side effects. ### [](#self-managed-agent)self-managed agent An AI agent you build and run yourself, in your own runtime and framework, registered with Redpanda Agentic Data Plane as an identity. The AI Gateway becomes the agent’s LLM and MCP endpoint, so the Agentic Data Plane attributes spend, tokens, latency, and traces back to the agent. The Agentic Data Plane does not host or run the agent. Contrast with a declarative agent, which runs in Redpanda’s managed runtime. ### [](#self-managed-mcp-server)self-managed MCP server An MCP server you host and operate yourself, registered with Redpanda Agentic Data Plane so the AI Gateway can proxy tool calls to it. Contrast with a managed MCP server, which Redpanda hosts in-process for you. ### [](#span)span A single unit of work within a trace representing one operation, such as a data processing operation or an external API call. Spans are organized in the Redpanda UI as parent-child relationships that show how operations flow through the system. Each span captures details about a specific operation, including timing, status, and metadata. ### [](#spending-event)spending event A record produced by the AI Gateway for every LLM call. Each event captures input, output, and cached token counts, the total cost in microcents, request count, and the provider, model, user, and organization context that the call ran under. ### [](#subagent)subagent A specialized AI agent that handles specific tasks or domains as part of a larger multi-agent system. Subagents are autonomous components within a multi-agent architecture that have focused expertise in particular domains or operations. They communicate with a parent agent or other subagents to accomplish complex workflows that require coordination across multiple specializations. ### [](#system-prompt)system prompt Initial instructions that define an agent’s role, capabilities, and behavioral guidelines. The system prompt is provided at the start of an agent session and establishes the agent’s identity, available tools, operating constraints, and response style. It remains active throughout the conversation and shapes all subsequent agent behavior and decision-making. ### [](#token-vault)token vault Encrypted per-user store for the OAuth access and refresh tokens used to access third-party providers. Redpanda injects a user’s token at call time and refreshes it automatically; connections persist until the user revokes them. ### [](#tool-invocation)tool invocation The process of an AI agent executing an MCP tool to perform a specific operation. Tool invocation occurs when an agent determines that it needs to use a tool, formats the request with appropriate parameters, sends it to the MCP server, and processes the response. Each invocation is captured in transcripts as spans for observability and debugging. ### [](#tool)tool A capability exposed by an MCP server that an AI agent can discover at runtime and invoke through structured JSON-RPC calls. Tools encapsulate operations such as querying a database, calling an API, or sending a message. ### [](#trace)trace The complete lifecycle of a request captured as a collection of spans, showing how operations relate to each other. A trace represents the complete lifecycle of a request (for example, a tool invocation from start to finish). A trace contains one or more spans organized hierarchically, showing how operations relate to each other. ### [](#transcript)transcript Complete observability record of agent or MCP server operations captured as OpenTelemetry traces and stored in the redpanda.otel\_traces topic. Transcripts capture tool invocations, agent reasoning steps, data processing operations, external API calls, error conditions, and performance metrics. They provide a complete record of how agentic systems operate, enabling debugging, auditing, and performance analysis. ## [](#redpanda-cloud)Redpanda Cloud ### [](#beta)beta Features in beta are available for testing and feedback. They are not supported by Redpanda and should not be used in production environments. ### [](#byoc)BYOC Bring Your Own Cloud (BYOC) is a fully-managed Redpanda Cloud deployment where clusters run in your private cloud, so all data is contained in your own environment. Redpanda handles provisioning, operations, and maintenance. ### [](#byovnet)BYOVNet A Bring Your Own Virtual Network (BYOVNet) cluster allows you to deploy the Redpanda data plane into your existing Azure VNet to fully manage the networking lifecycle. Compared to standard BYOC, BYOVNet provides more security, but the configuration is more complex. ### [](#byovpc)BYOVPC A Bring Your Own Virtual Private Cloud (BYOVPC) cluster allows you to deploy the Redpanda data plane into your existing VPC on AWS or GCP to fully manage the networking lifecycle. Compared to standard BYOC, BYOVPC provides more security, but the configuration is more complex. ### [](#connector)connector Enables Redpanda to integrate with external systems, such as databases. ### [](#control-plane)control plane This part of Redpanda Cloud enforces rules in the data plane, including cluster management, operations, and maintenance. ### [](#data-plane)data plane This part of Redpanda Cloud contains Redpanda clusters and other components, such as Redpanda Console, Redpanda Operator, and `rpk`. It is managed by an agent that receives cluster specifications from the control plane. Sometimes used interchangeably with clusters. ### [](#data-sovereignty)data sovereignty Containing all your data in your environment. With BYOC, Redpanda handles provisioning, monitoring, and upgrades, but you manage your streaming data without Redpanda’s control plane ever seeing it. Additionally, with BYOVPC, the Redpanda Cloud agent doesn’t create any new resources or alter any settings in your account. ### [](#dedicated-cloud)Dedicated Cloud A fully-managed Redpanda Cloud deployment option where you host your data in Redpanda’s VPC, and Redpanda handles provisioning, operations, and maintenance. Dedicated clusters are single-tenant deployments that support private networking (for example, VPC peering to talk over private IPs) for better data isolation. ### [](#limited-availability)limited availability Features in limited availability (LA) are production-ready and are covered by Redpanda Support for early adopters. ### [](#pipeline)pipeline A single configuration file running in Redpanda Connect with an input connector, an output connector, and optional processors in between. A pipeline typically streams data into Redpanda from an operational source (like PostgreSQL) or streams data out of Redpanda into an analytical system (like Snowflake). ### [](#redpanda-cloud-2)Redpanda Cloud A fully-managed data streaming service deployed with Redpanda Console. It includes automated upgrades and patching, backup and recovery, data and partition balancing, and built-in connectors. Redpanda Cloud is available in Serverless, Dedicated, and Bring Your Own Cloud (BYOC) deployment options to suit different data sovereignty and infrastructure requirements. ### [](#redpanda-console)Redpanda Console The web-based UI for managing and monitoring Redpanda clusters and streaming workloads. You can also set up and manage connectors in Redpanda Console. Redpanda Console is an integral part of Redpanda Cloud, but it also can be used as a standalone program as part of a Redpanda Self-Managed deployment. ### [](#remote-mcp)Remote MCP An MCP server hosted in your Redpanda Cloud cluster. It exposes custom tools that AI assistants can call to access your data and workflows. ### [](#resource-group)resource group A container for Redpanda Cloud resources, including clusters and networks. You can rename your default resource group, and you can create more resource groups. For example, you may want different resource groups for production and testing. ### [](#serverless)Serverless Serverless is the fastest and easiest way to start data streaming. You host your data in Redpanda’s VPC, and Redpanda handles automatic scaling, provisioning, operations, and maintenance. ### [](#sink-connector)sink connector Exports data from a Redpanda cluster into a target system. ### [](#source-connector)source connector Imports data from a source system into a Redpanda cluster. ## [](#redpanda-connect)Redpanda Connect ### [](#mcp-tool)MCP tool A function that an AI assistant can call to perform a specific task, such as fetching data from an API, querying a database, or processing streaming data. Each tool is defined using Redpanda Connect components and annotated with MCP metadata. ### [](#processor)processor A Redpanda Connect component that transforms data, validates inputs, or calls external APIs within a processing pipeline. Processors are stateless components in Redpanda Connect that operate on individual messages or batches. When used as MCP tools, processors handle data transformations, validate parameters, and invoke external services. Each processor executes independently per request with no state maintained between invocations. ### [](#redpanda-connect-mcp-server)Redpanda Connect MCP server A process that exposes Redpanda Connect components to MCP clients. You write each tool’s logic using Redpanda Connect configurations and annotate them with MCP metadata so clients can discover and invoke them. ### [](#redpanda-connect-2)Redpanda Connect A framework for building data streaming applications using declarative YAML configurations. Redpanda Connect provides components such as inputs, processors, outputs, and caches to define data flows and transformations. ## [](#redpanda-sql)Redpanda SQL ### [](#oxla)Oxla The SQL engine technology that powers Redpanda SQL. "Oxla" may appear in version strings, error messages, and some API field names. ### [](#redpanda-catalog)Redpanda catalog A catalog in Redpanda SQL that maps Redpanda topics to SQL tables. The default Redpanda catalog (`default_redpanda_catalog`) is provisioned automatically when Redpanda SQL is enabled. ### [](#redpanda-sql-2)Redpanda SQL A PostgreSQL-compatible SQL engine built into Redpanda Data Platform for querying streaming data in Redpanda topics. Redpanda SQL provides analytical SQL queries over Redpanda topic data without requiring ETL pipelines or a separate analytics system. It can also query the Iceberg-translated history of Iceberg-enabled topics alongside live records. ## [](#redpanda-core)Redpanda core ### [](#availability-zone-az)availability zone (AZ) One or more data centers served by high-bandwidth links with low latency, typically within a close distance of one another. ### [](#broker)broker An instance of Redpanda that stores and manages event streams. Multiple brokers join together to form a Redpanda cluster. Sometimes used interchangeably with node, but a node is typically a physical or virtual server. See also: node ### [](#client)client A producer application that writes events to Redpanda, or a consumer application that reads events from Redpanda. This could also be a client library, like librdkafka or franz-go. ### [](#cluster)cluster One or more brokers that work together to manage real-time data streaming, processing, and storage. ### [](#consumer-group)consumer group A set of consumers that cooperate to read data for better scalability. As group members arrive and leave, partitions are re-assigned so each member receives a proportional share. ### [](#consumer-offset)consumer offset The position of a consumer in a specific topic partition, to track which records they have read. A consumer offset of 3 means it has read messages 0-2 and will next read message 3. ### [](#consumer)consumer A client application that subscribes to Redpanda topics to asynchronously read events. ### [](#controller-broker)controller broker A broker that manages operational metadata for a Redpanda cluster and ensures replicas are distributed among brokers. At any given time, one active controller exists in a cluster. If the controller fails, another broker is automatically elected as the controller. ### [](#data-stream)data stream A continuous flow of events in real time that are produced and consumed by client applications. Redpanda is a data streaming platform. Also known as event stream. ### [](#event)event A record of something changing state at a specific time. Events can be generated by various sources, including sensors, applications, and devices. Producers write events to Redpanda, and consumers read events from Redpanda. ### [](#iceberg-catalog)Iceberg catalog A metadata service that tracks Apache Iceberg tables and their schemas. Redpanda supports REST catalogs (such as AWS Glue, GCP BigLake, Snowflake Open Catalog, or Databricks Unity Catalog) and filesystem-based catalogs. Redpanda SQL connects to a REST catalog with `CREATE ICEBERG CATALOG` to query the Iceberg-committed history of a topic. ### [](#iceberg-mode)Iceberg mode The Redpanda topic property (`redpanda.iceberg.mode`) that controls whether and how the topic’s records are translated into an Apache Iceberg table. ### [](#iceberg-topic)Iceberg topic A Redpanda topic with Iceberg integration enabled, so its data is also stored as an Apache Iceberg table that downstream analytical systems can read directly. Also called an Iceberg-enabled topic. ### [](#iceberg-translation)Iceberg translation The background process that converts records on an Iceberg topic into Apache Iceberg format and commits them to the configured Iceberg catalog. ### [](#kafka-api)Kafka API Producers and consumers interact with Redpanda using the Kafka API. It uses the default port 9092. ### [](#learner)learner A broker that is a follower in a Raft group but is not part of quorum. In a Raft group, a broker can be in learner status. Learners are followers that cannot vote and so do not count towards quorum (the majority). They cannot be elected to leader nor can they trigger leader elections. Brokers can be promoted or demoted between learner and voter. New Raft group members start as learners. ### [](#listener)listener Configuration on a broker that defines how it should accept client or inter-broker connections. Each listener is associated with a specific protocol, hostname, and port combination. The listener defines where the broker should listen for incoming connections. ### [](#log)log An ordered, append-only, immutable sequence of records. The log is Redpanda’s core storage abstraction for event streams. At the conceptual level, topics represent replayable logs. Physically, each partition is implemented as a log file on disk, divided into segments. Redpanda uses the Raft consensus algorithm to coordinate writing data to log files and replicate them across brokers for fault tolerance. See also: topic, partition, segment ### [](#message)message One or more records representing individual events being transmitted. Redpanda transfers messages between producers and consumers. Sometimes used interchangeably with record. ### [](#node)node A machine, which could be a server, a virtual machine (instance), or a Docker container. Every node has its own disk. Partitions are stored locally on nodes. In Kubernetes, a Node is the machine that Redpanda runs on. Outside the context of Kubernetes, this term may be used interchangeably with broker, such as `node_id`. See also: broker ### [](#offset-commit)offset commit An acknowledgement that the event has been read. ### [](#offset)offset A unique integer assigned to each record to show its location in the partition. ### [](#pandaproxy)pandaproxy Original name for the subsystem of Redpanda that allows access to your data through a REST API. This name still appears in the HTTP Proxy API and the Schema Registry API. ### [](#partition-leader)partition leader Every Redpanda partition forms a Raft group with a single elected leader. This leader handles all writes, and it replicates data to followers to ensure that a majority of brokers store the data. ### [](#partition)partition A subset of events in a topic, like a log file. It is an ordered, immutable sequence of records. Partitions allow you to distribute a stream, which lets producers write messages in parallel and consumers read messages in parallel. Partitions are made up of segment files on disk. ### [](#producer)producer A client application that writes events to Redpanda. Redpanda stores these events in sequence and organizes them into topics. ### [](#rack)rack A failure zone that has one or more Redpanda brokers assigned to it. ### [](#raft)Raft The consensus algorithm Redpanda uses to coordinate writing data to log files and replicating that data across brokers. For more details, see [https://raft.github.io/](https://raft.github.io/) ### [](#record)record A self-contained data entity with a defined structure, representing a single event. Sometimes used interchangeably with message. ### [](#replicas)replicas Copies of partitions that are distributed across different brokers, so if one broker goes down, there is a copy of the data. ### [](#retention)retention The mechanism for determining how long Redpanda stores data on local disk or in object storage before purging it. ### [](#replication-factor)replication factor The number of partition copies in a cluster. This is set to 3 in Redpanda Cloud deployments and 1 (no replication) in Self-Managed deployments. A replication factor of at least 3 ensures that each partition has a copy of its data on at least one other broker. One replica acts as the leader, and the other replicas are followers. ### [](#schema)schema An external mechanism to describe the structure of data and its encoding. Schemas validate the structure and ensure that producers and consumers can connect with data in the same format. ### [](#seastar)Seastar An open-source thread-per-core C++ framework, which binds all work to physical cores. Redpanda is built on Seastar. For more details, see [https://seastar.io/](https://seastar.io/) ### [](#seed-server)seed server The initial set of brokers that a Redpanda broker contacts to join the cluster. Seed servers play a crucial role in cluster formation and recovery, acting as a point of reference for new or restarting brokers to understand the current topology of the cluster. ### [](#segment)segment Discrete part of a partition, used to break down a continuous stream into manageable chunks. You can set the maximum duration (`segment.ms`) or size (`segment.bytes`) for a segment to be open for writes. ### [](#serialization)serialization The process of converting a record into a format that can be stored. Deserialization is the process of converting a record back to the original state. Redpanda Schema Registry supports Avro and Protobuf serialization formats. ### [](#shard)shard A CPU core. ### [](#subject)subject A logical grouping or category for schemas. When data formats are updated, a new version of the schema can be registered under the same subject, allowing for backward and forward compatibility. ### [](#thread-per-core)thread-per-core Programming model that allows Redpanda to pin each of its application threads to a CPU core to avoid context switching and blocking. ### [](#topic-partition)topic partition A topic may be partitioned through multiple brokers. A "topic partition" represents this logical separation in Redpanda, which is managed natively by Raft. ### [](#topic)topic A logical stream of related events that are written to the same log. It can be divided into multiple partitions. A topic can have various clients writing events to it and reading events from it. ### [](#wire-format)wire format A serialization format used by Schema Registry that prefixes each record with a magic byte and 4-byte schema ID, so consumers can identify and apply the correct schema. ## [](#redpanda-features)Redpanda features ### [](#admin-api)Admin API A REST API used to manage and monitor Redpanda Self-Managed clusters. It uses the default port 9644. For more information about using this API with Self-Managed Redpanda, see [/api/doc/admin](https://docs.redpanda.com/api/doc/admin). Note: The Redpanda Admin API is different from the [Kafka Admin API](https://kafka.apache.org/documentation/#adminapi). ### [](#cloud-topic)Cloud Topic A Redpanda topic type, Cloud Topics use object storage (S3, GCS, or MinIO) as the primary data store (rather than replicating data across brokers). Unlike standard Redpanda topics, Cloud Topics allow users with flexible latency requirements to lower or eliminate costs associated with cross-AZ networking. ### [](#compaction)compaction Feature that retains the latest value for each key within a partition while discarding older values. ### [](#controller-snapshot)controller snapshot Snapshot of the current cluster metadata state saved to disk, so broker startup is fast. ### [](#data-transforms)data transforms Framework to manipulate or enrich data written to Redpanda topics. You can develop custom data functions, which run asynchronously using a WebAssembly (Wasm) engine inside a Redpanda broker. ### [](#http-proxy)HTTP Proxy Redpanda HTTP Proxy (pandaproxy) allows access to your data through a REST API. It is built into the Redpanda binary and uses the default port 8082. ### [](#leader-pinning)Leader Pinning Feature that places a topic’s partition leaders in a preferred location, such as a cloud availability zone, to reduce networking costs and latency for nearby clients. ### [](#maintenance-mode)maintenance mode A state where a Redpanda broker temporarily doesn’t take any partition leaderships. It continues to store data as a follower. This is usually done for system maintenance or a rolling upgrade. ### [](#rack-awareness)rack awareness Feature that lets you distribute replicas of the same partition across different racks to minimize data loss and improve fault tolerance in the event of a rack failure. ### [](#rebalancing)rebalancing Process of moving partition replicas and transferring partition leadership for improved performance. Redpanda provides various topic-aware tools to balance clusters for best performance. - Leadership balancing changes where data is written to first, but it does not involve any data transfer. The partition leader regularly sends heartbeats to its followers. If a follower does not receive a heartbeat within a timeout, it triggers a new leader election. Redpanda also provides leadership balancing when brokers are added or decommissioned. - Partition replica balancing moves partition replicas to alleviate disk pressure and to honor the configured replication factor across brokers and the additional redundancy across failure domains (such as racks). Redpanda provides partition replica rebalancing when brokers are added or decommissioned. - With an Enterprise license, you can additionally enable Continuous Data Balancing to continuously monitor broker and rack availability and disk usage. ### [](#rolling-upgrade)rolling upgrade The process of upgrading each broker in a Redpanda cluster, one at a time, to minimize disruption and ensure continuous availability. ### [](#rpk)rpk Redpanda’s command-line interface tool for managing Redpanda clusters. ### [](#remote-read-replica)Remote Read Replica A read-only topic that mirrors a topic on a different cluster, using data from Tiered Storage. ### [](#schema-registry-context)Schema Registry context An independent namespace for subjects within a Schema Registry. Contexts let multiple groups of schemas coexist in one registry without naming conflicts. The default context is named ".". ### [](#schema-registry)Schema Registry Redpanda Schema Registry (pandaproxy) is the interface for storing and managing event schemas. Producers and consumers register and retrieve schemas they use from the registry. It is built into the Redpanda binary and uses the default port 8081. ### [](#shadow-cluster)shadow cluster A read-only Redpanda cluster that continuously receives replicated data from a source cluster through a shadow link. During a disaster, you can fail over to the shadow cluster so it handles production traffic. ### [](#shadow-link)shadow link A persistent connection between two Redpanda clusters that continuously replicates topic data, metadata, consumer offsets, ACLs, and Schema Registry content from a source cluster to a shadow cluster for disaster recovery. ### [](#tiered-storage)Tiered Storage Feature that lets you offload log segments to object storage in near real-time, providing long-term data retention and topic recovery. ## [](#redpanda-in-kubernetes)Redpanda in Kubernetes ### [](#cert-manager)cert-manager A Kubernetes controller that simplifies the process of obtaining, renewing, and using certificates. For more details, see [https://cert-manager.io/docs/](https://cert-manager.io/docs/) ### [](#redpanda-helm-chart)Redpanda Helm chart Generates and applies all the manifest files you need for deploying Redpanda in Kubernetes. ### [](#redpanda-operator)Redpanda Operator Extends Kubernetes with custom resource definitions (CRDs), which allow Redpanda clusters to be treated as native Kubernetes resources. ## [](#redpanda-licenses)Redpanda licenses ### [](#redpanda-community-edition)Redpanda Community Edition Redpanda software that is available under the Redpanda Business Source License (BSL). These core features are free and source-available. ### [](#redpanda-enterprise-edition)Redpanda Enterprise Edition Redpanda software that is available under the Redpanda Community License (RCL). It includes the free features licensed with the Redpanda Community Edition, as well enterprise features, such as Tiered Storage, Remote Read Replicas, and Continuous Data Balancing. ### [](#self-managed)Self-Managed Redpanda Self-Managed refers to the product offering that includes both the Enterprise Edition and the Community Edition of Redpanda. Sometimes used interchangeably with self-hosted. ## [](#redpanda-security)Redpanda security ### [](#access-control-list-acl)access control list (ACL) A security feature used to define and enforce granular permissions to resources, ensuring only authorized users or applications can perform specific operations. ACLs act on principals. ### [](#advertised-listener)advertised listener The address a Redpanda broker broadcasts to producers, consumers, and other brokers. It specifies the hostname and port for connections to different listeners. Clients and other brokers use advertised listeners to connect to services such as the Admin API, Kafka API, and HTTP Proxy API. The advertised address might differ from the listener address in scenarios where brokers are behind a NAT, in a Docker container, or in Kubernetes. Advertised addresses ensure clients can reach the Redpanda brokers even in complex network setups. ### [](#authentication)authentication The process of verifying the identity of a principal, user, or service account. Also known as AuthN. ### [](#authorization)authorization The process of specifying access rights to resources. Access rights are enforced through roles or access control lists (ACLs). Also known as AuthZ. ### [](#bearer-token)bearer token An access token used for authentication and authorization in web applications and APIs. It holds user credentials, usually in the form of random strings of characters. ### [](#gbac)GBAC Group-based access control lets you manage Redpanda permissions at scale by assigning them to OIDC groups instead of individual users. GBAC lets you manage Redpanda permissions at scale using the groups that already exist in your identity provider (IdP). You define access once for a group and your IdP controls who belongs to it. You can grant permissions to groups in two ways: create ACLs with `Group:` principals, or assign groups as members of RBAC roles. Both approaches can be used independently or together. ### [](#identity-provider-idp)identity provider (IdP) A service that creates, maintains, and manages identity information while providing authentication services to applications. Identity providers authenticate users and issue tokens that applications can use to verify identity and access permissions. Common IdPs include Okta, Auth0, Azure AD, and Google Identity Platform. ### [](#openid-connect-oidc)OpenID Connect (OIDC) Authentication layer built on OAuth 2.0 that allows clients to verify user identity and obtain basic profile information. OpenID Connect provides a standardized way for applications to authenticate users through identity providers. In Redpanda’s agentic systems, OIDC enables secure authentication for AI agents and MCP servers accessing cloud resources. ### [](#principal)principal An authenticated identity (user, service account, or group) that Redpanda evaluates when enforcing ACLs and role assignments. Redpanda supports `User:` and `Group:` principal types. Permissions are granted to principals through ACLs or RBAC role assignments. ### [](#rbac)RBAC Role-based access control lets you assign users access to specific resources. ### [](#service-account)service account An identity independent of the user who created it that can be used to authenticate and perform operations. This is especially useful for authentication of machines. --- # Page 82: Release Notes **URL**: https://docs.redpanda.com/agentic-data-plane/reference/release-notes.md --- # Release Notes > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Release Notes latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: release-notes page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: release-notes.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/release-notes.adoc description: "What's new in the Agentic Data Plane: new features, improvements, and bug fixes, by release." page-topic-type: reference page-git-created-date: "2026-07-01" page-git-modified-date: "2026-08-10" --- The latest updates to the Agentic Data Plane. For the in-product summary, open **What’s new** from the top bar. ## [](#v0-2-37-2026-08-10)v0.2.37 (2026-08-10) ### [](#improvements)Improvements MCP Servers `[UI]` The **Data Policies** tab now counts a server’s tools by protection state: **protected** for a tool a data policy covers, **findings** for a tool with no policy that returns fields whose names look sensitive, and **no policy** for the rest. Every tool falls in exactly one group. The tool lists on **Data Policies** and the MCP server **Inspector** tab are also searchable, and long tool names wrap in full instead of being cut off, so tools whose names differ only at the end are easier to tell apart. Agents `[UI]` The agent **Inspector** tab is now called **Playground**. ### [](#bug-fixes)Bug fixes LLM Providers `[UI]` Editing a provider’s connection settings in the ADP UI, for example pointing it at a different API key secret, reported success and kept the old value. Those edits now save. The display name and model selection were unaffected, as were changes made with the `rpk ai` plugin or the API. Re-open any provider whose connection settings you edited in the UI and confirm it uses the secret you intended. Agents `[UI]` The agent **Playground** now tells you when an agent has no subagents attached instead of opening an empty panel. OAuth Providers `[UI]` All granted scopes are readable on provider and client detail pages. A long scope ran outside its popup, and a long list of scopes ran off the bottom of the screen with no way to scroll, so not every scope was visible. Interface `[UI]` Side panels close when you click outside them. ## [](#v0-2-36-2026-08-06)v0.2.36 (2026-08-06) ### [](#improvements-2)Improvements Security This release includes general security and stability improvements. ## [](#v0-2-35-2026-08-06)v0.2.35 (2026-08-06) ### [](#features)Features Access `[UI]` The new **Access** page, available as a preview, controls what people can do with the resources in your ADP environment. Write your own permit and forbid rules on **Policies**, or start from a **Templates** preset: **Read only**, **Sandboxed** to use agents and MCP servers without changing them, **Standard** to also manage resources, or **Full access**. **Roles** shows what each of your organization’s roles can do, and **System policies** shows who already has access through those roles. Agents `[UI]` The agent prompt editor now formats your prompt as you write it. **Live** mode renders headings, lists, and emphasis, and shows the raw Markdown only on the line your cursor is on. Switch between **Live**, **Markdown**, and **Preview** without losing your place, or start from a template for a support agent, data analyst, coding assistant, incident responder, or research coordinator. ### [](#improvements-3)Improvements Agents `[UI]` The agent **Setup** tab splits MCP servers into **Managed**, run by Redpanda, and **Self-managed**, run by you, and shows each managed server’s logo, so a long list is easier to scan. Interface `[UI]` The app opens faster on a first visit. ### [](#bug-fixes-2)Bug fixes OAuth Clients Claude can now connect to an MCP server on ADP with a Client ID Metadata Document (CIMD). Retry the connection from Claude, with nothing to change on your side. Connecting failed with **unable to retrieve client by id** because ADP refused an entire document over a single OAuth grant type that the document lists and ADP does not issue. ADP now ignores those grant types and honors the rest of the document, for any client, not only Claude. Agents `[UI]` The create-agent wizard previewed a self-managed agent’s client ID in a format that `rpk ai agent credential create` no longer returns. Only the preview was wrong, so credentials you already issued are unaffected. Interface `[UI]` Notifications are readable in dark mode instead of washing out against a dark background, and they now appear at the top right of the screen. ## [](#v0-2-34-2026-08-04)v0.2.34 (2026-08-04) ### [](#features-2)Features OAuth Clients An MCP client can now reach a protected server with a Client ID Metadata Document (CIMD), the MCP spec’s successor to Dynamic Client Registration. The app hosts its own metadata at an `https` URL and presents that URL as its client ID, so nobody creates a client by hand. Turn on **Accept client metadata documents (CIMD)** on the **Integrations setup** page, choose whether to accept documents from **Any domain** or **Only these domains**, and list the MCP servers those clients can reach. Models GPT-5.6 Sol, Terra, and Luna are now in the Amazon Bedrock catalog. Enable `openai.gpt-5.6-sol`, `openai.gpt-5.6-terra`, or `openai.gpt-5.6-luna` on a Bedrock provider. ### [](#improvements-4)Improvements Security This release includes general security and stability improvements. ### [](#bug-fixes-3)Bug fixes LLM Providers Creating an LLM provider now works on Google Cloud environments. Saving the provider’s API key failed because the form attached an internal label that Google Secret Manager rejects. Cost & Usage Cost reporting overstated GPT-5.6 Luna and Terra spend. OpenAI reduced the rates for both models on July 30, so reported cost now matches the current rates. Figures recorded before this release keep their earlier, higher numbers. ## [](#v0-2-33-2026-08-03)v0.2.33 (2026-08-03) ### [](#improvements-5)Improvements MCP Servers `[UI]` The server details page groups setup, tools, and connection details more clearly, and tool schemas stay readable when you expand a nested object. Environments `[UI]` Switching to another environment now takes you to the home page of that environment, instead of leaving you on a page that belongs to the previous one. Security This release includes general security and stability improvements. ### [](#bug-fixes-4)Bug fixes OAuth Clients An MCP client that registers itself with Dynamic Client Registration (DCR, RFC 7591) can now connect to a server on ADP. Claude.ai, Claude Code, and Cursor were rejected during registration, and the error named the MCP server’s vendor rather than the real cause. Interface `[UI]` Confirmation dialogs now place their buttons in the same order as the rest of the product. ## [](#v0-2-32-2026-07-30)v0.2.32 (2026-07-30) ### [](#features-3)Features MCP Servers Connecting a remote MCP server that uses **User OAuth** now takes a URL and one sign-in per person, with no app created by hand in a vendor console. Select **Set up automatically** and ADP reads the server’s OAuth configuration and registers itself as a client using Dynamic Client Registration (DCR, RFC 7591). For a server that does not support DCR, you can still enter a client ID and secret yourself. Models Claude Opus 5, Gemini 3.6 Flash, and Gemini 3.5 Flash Lite are now in the model catalog. Enable `claude-opus-5` on an Anthropic provider, or `gemini-3.6-flash` and `gemini-3.5-flash-lite` on a Google provider. Claude Opus 5 is also in the Amazon Bedrock catalog. CLI The `rpk ai connection` commands bring your own OAuth connections to the terminal, matching what **My Connections** shows in the UI. Run `rpk ai connection list` to see the services you are signed in to, and `rpk ai connection revoke ` to disconnect your own account from one. ### [](#improvements-6)Improvements LLM Providers `[UI]` Creating an LLM provider is now a single form: paste model IDs one per line, and create the provider’s API key secret without leaving the page. For Amazon Bedrock you can browse the catalog by model family and enable or disable models in bulk. MCP Servers OpenAI MCP servers now transcribe audio files with `gpt-transcribe` instead of `whisper-1`. Servers that set a transcription model explicitly keep it. MCP Servers `[UI]` When the inspector cannot reach a server, it now explains the failure in readable text and offers **Try again** and **Edit server**. The raw response stays available in a collapsed panel for network debugging. ### [](#bug-fixes-5)Bug fixes MCP Servers Remote MCP servers set to **OAuth (Service Account)** now attach the service account’s access token to their upstream requests. They previously sent no credentials at all, so a server requiring authentication rejected every request. Cost & Usage Cost reporting understated large Anthropic requests: above 200,000 input tokens, Anthropic charges a higher long-context rate that ADP was not applying. Those requests now report their real cost, so expect reported spend to step up with no change in usage. Figures recorded before this release keep their earlier, lower numbers. Interface `[UI]` Selecting **Contact support** on an error now files a support request with Redpanda. The error was previously logged for diagnostics without a request being created. ## [](#v0-2-31-2026-07-28)v0.2.31 (2026-07-28) ### [](#improvements-7)Improvements Environments `[UI]` When your organization has no Agentic Data Plane environment yet, ADP now shows which of your clusters can host one, with each cluster’s cloud region and city. ### [](#bug-fixes-6)Bug fixes Activity Conversation transcripts are recorded again after new conversations stopped appearing in the Activity views on **LLM Providers** and **Cost & Usage** in the previous release. Interface `[UI]` Filtering and paging through lists now work correctly across **Connections**, **Integrations**, and **Secrets**. Filter checkboxes show and clear what you selected, and lists no longer jump to the wrong page while data reloads. ## [](#v0-2-30-2026-07-27)v0.2.30 (2026-07-27) ### [](#improvements-8)Improvements Security This release includes general security and stability improvements. ## [](#v0-2-29-2026-07-27)v0.2.29 (2026-07-27) ### [](#features-4)Features Agents Agents now support scheduled triggers. Give an agent a cron schedule and it runs automatically at the times you set. MCP Servers You can now pick a token-optimized output format for each MCP server. Set a server’s **Output format** to JSON, TOON, or JTON to control how tool results are encoded before an agent reads them. ### [](#bug-fixes-7)Bug fixes MCP Servers Connecting a remote MCP server now streams its responses reliably, so its tools load instead of appearing empty. ## [](#v0-2-28-2026-07-24)v0.2.28 (2026-07-24) ### [](#features-5)Features MCP Servers As a preview, MCP servers now have a **Data Policies** tab where you can define rules that mask, redact, or filter fields out of a tool’s results before the model sees them. Author and preview policies per server. MCP Servers OpenAPI MCP servers can now authenticate to a downstream API with an OAuth client-credentials (service-account) flow. All requests share one service-account identity instead of each user’s own credentials. ### [](#improvements-9)Improvements MCP Servers OpenAPI MCP servers now return tool results as structured output with the response’s status code, headers, and parsed body, so agents can read them reliably. LLM Providers `[UI]` You can now find a provider in the list by its display name, not just its ID. ### [](#bug-fixes-8)Bug fixes CLI Deriving an environment with `rpk ai env add --from ` now inherits the base environment’s ADP API URL and authentication mode instead of resetting them to defaults. CLI The `rpk ai env list` output no longer shows duplicate or stale local-only environments. ## [](#v0-2-27-2026-07-22)v0.2.27 (2026-07-22) ### [](#improvements-10)Improvements Security This release includes general security and stability improvements. ## [](#v0-2-26-2026-07-22)v0.2.26 (2026-07-22) ### [](#features-6)Features OAuth Providers Connecting a remote MCP server that uses OAuth no longer requires you to paste in authorization and token endpoints or a client ID and secret. Redpanda reads the server’s OAuth configuration from its URL and registers a client automatically through Dynamic Client Registration (DCR). MCP Servers The ServiceNow MCP server can now search CMDB configuration items, so agents can look up servers, laptops, applications, and services. ### [](#improvements-11)Improvements MCP Servers `[UI]` The setup guides for connecting an AI client now cover Claude, ChatGPT, Zed, and the Codex CLI, with corrected steps. MCP Servers `[UI]` The copy-paste code examples for connecting to MCP servers and LLM providers now use the latest SDK versions across Node, Python, Go, Java, and curl. Interface `[UI]` List rows are now fully clickable to open the detail view, instead of only the name link. Interface `[UI]` When something fails, the interface now offers clear next steps such as retry, reload, and copying the error details. ### [](#bug-fixes-9)Bug fixes My Connections Connecting a remote MCP server that signs you in with your own account (user-delegated OAuth) now works. Sign-in no longer fails before completing. ## [](#v0-2-25-2026-07-17)v0.2.25 (2026-07-17) ### [](#features-7)Features Models `[UI]` Every LLM provider now has a **Models** tab where you can browse the models it serves, turn individual models on or off, and filter them by capability or status. LLM Providers `[UI]` Each provider now has an **Activity** tab that shows the agents, requests, and conversations routed through it over a time range you choose. ### [](#improvements-12)Improvements LLM Providers `[UI]` The providers list shows each provider’s models with small trend charts for recent requests and spend, and you can filter the list to providers that serve a specific model. LLM Providers `[UI]` Each provider’s **Settings** tab shows which Secret Store entries authenticate it, with a shortcut to manage those keys. LLM Providers `[UI]` The **Connect** setup guide lets you pick your coding agent and operating system, and gives copy-paste `rpk ai` steps tailored to your environment. MCP Servers `[UI]` Running a tool in the server inspector now shows clear, actionable validation errors for invalid inputs instead of a generic failure. ### [](#bug-fixes-10)Bug fixes OAuth Clients Connecting an AI client to a **Code Mode** MCP server over OAuth now succeeds; Code Mode adds tools that let agents run sandboxed code against the server. Clients such as Claude Code and the MCP Inspector now register automatically through Dynamic Client Registration (DCR) instead of failing with a missing-scope error. My Connections `[UI]` Using the browser Back button after starting a connection no longer leaves the **Connect** button stuck; the connection state resets cleanly. Home `[UI]` A brand-new environment no longer shows a misleading all-clear health status before you have set anything up. ## [](#v0-2-24-2026-07-13)v0.2.24 (2026-07-13) ### [](#features-8)Features Models OpenAI providers now offer the GPT-5.6 model family: GPT-5.6 Luna, GPT-5.6 Terra, and GPT-5.6 Sol. ### [](#improvements-13)Improvements Models `[UI]` Each model now has a detail page showing its overview, pricing, and capabilities. ### [](#bug-fixes-11)Bug fixes Models `[UI]` Model usage now shows a clear error when a usage query fails, instead of misleading zero values. Cost & Usage Cost and usage reports now count cached tokens accurately even when a provider returns incomplete usage data. MCP Servers `[UI]` The inspector shows upstream HTML and XML errors as readable text instead of raw markup. My Connections `[UI]` The Connect and Reconnect buttons now show a loading state while the provider’s consent screen opens. ## [](#v0-2-23-2026-07-13)v0.2.23 (2026-07-13) ### [](#features-9)Features Models You can now use the Google Gemma 4 model family with your Amazon Bedrock providers, in three sizes from largest to smallest: Gemma 4 31B, Gemma 4 26B-A4B, and Gemma 4 E2B. ### [](#improvements-14)Improvements Integrations setup `[UI]` Manage OAuth providers and MCP client access in one tabbed **Integrations setup** area, replacing the separate pages. My Connections `[UI]` The **My Connections** page groups your account connections by status and lets you connect or reconnect without leaving the page. Security This release includes general security and stability improvements. ### [](#bug-fixes-12)Bug fixes My Connections Connections that renew automatically, for example GitHub, no longer show as expired shortly after connecting. You are prompted to reconnect only when a connection can no longer renew itself. ## [](#v0-2-22-2026-07-10)v0.2.22 (2026-07-10) ### [](#features-10)Features Models Amazon Bedrock providers now offer two new models: Mistral Large 3 and Amazon Nova 2 Lite. ### [](#improvements-15)Improvements MCP Servers The Amazon Bedrock MCP server can now generate embeddings with Cohere Embed v4. Agents Creating or updating an agent now rejects an invalid Bedrock model name immediately, instead of accepting it and failing later. Agents `[UI]` When an agent task is still running after five minutes, the inspector stops the live view and points you to the **Activity** page to follow it; the task keeps running. Security This release includes general security and stability improvements. ### [](#bug-fixes-13)Bug fixes Agents A reply that was cut off by the model’s token limit no longer causes the next message in the conversation to fail. ## [](#v0-2-20-2026-07-09)v0.2.20 (2026-07-09) ### [](#features-11)Features Cost & Usage Tag your agents and break down cost and usage by tag: group the report by a tag key, filter by tag values, and see untagged traffic in its own bucket. ### [](#improvements-16)Improvements Security This release includes general security and stability improvements. ## [](#v0-2-19-2026-07-08)v0.2.19 (2026-07-08) ### [](#features-12)Features Cost & Usage Download your full cost and usage report as a CSV, broken down by provider, model, user, or agent and by hour, day, or month. ### [](#improvements-17)Improvements Home The home dashboard is rebuilt around an overall health status, an hourly chart of token use and spend, and your top spending agents and users at a glance. LLM Providers `[UI]` The Connect tab gives you ready-to-run `rpk ai` setup steps and client code snippets, including running Claude Code against a Bedrock provider without local AWS credentials. Interface When a request fails, a clearer error page lets you retry, open full error details, and copy the failing request as a `curl` command to reproduce or report it. Security This release includes general security and stability improvements. ### [](#bug-fixes-14)Bug fixes Agents `[UI]` In the agent editor, the model picker now stays anchored to its field instead of jumping to the side when you open it. Interface After a new release is deployed, the app now reloads cleanly instead of getting stuck on a stale page. ## [](#v0-2-18-2026-07-03)v0.2.18 (2026-07-03) ### [](#improvements-18)Improvements Interface Text across the interface is now larger and easier to read. Security This release includes general security and stability improvements. ### [](#bug-fixes-15)Bug fixes Interface Collapsible and accordion panels now animate smoothly. ## [](#v0-2-17-2026-07-02)v0.2.17 (2026-07-02) ### [](#features-13)Features CLI Launch Claude Code against one of your Amazon Bedrock LLM providers with `rpk ai run claude -L `; the gateway authenticates to AWS for you, so your machine needs no AWS credentials. Agents Give each subagent its own model and LLM provider in the agent editor. ### [](#improvements-19)Improvements Agents Updating an agent no longer interrupts it: the new version starts and takes over before the old one stops. Models Each model now reports its `max_input_tokens` and `max_output_tokens` limits through the API. ### [](#bug-fixes-16)Bug fixes LLM Providers `[UI]` Filters in the metric detail panel on provider and model pages now apply to the chart, and the panel no longer hides its filter menus or covers the sidebar. LLM Providers `[UI]` The spend total in the metric detail panel was inflated when grouping by cost type; only the display was wrong, recorded usage was unaffected. Cost & Usage `[UI]` In period comparisons grouped by model or user, each line now compares against its own numbers from the previous period, not another line’s. ## [](#v0-2-16-2026-07-01)v0.2.16 (2026-07-01) ### [](#features-14)Features OAuth Clients MCP clients such as Claude Code, Cursor, and ChatGPT can now register themselves through OAuth Dynamic Client Registration (DCR), instead of needing an OAuth client created by hand. ### [](#improvements-20)Improvements Agents `[UI]` Creating policies is now faster, since resource options load as you need them instead of all at once. MCP Servers `[UI]` Claude Code users can now set up managed MCP servers with a single command, or use manual configuration from a separate tab. ## [](#v0-2-12-2026-07-01)v0.2.12 (2026-07-01) ### [](#features-15)Features Models Claude Sonnet 5 is now available to select on the Anthropic and Bedrock providers. ### [](#bug-fixes-17)Bug fixes Agents `[UI]` A completed tool call in the agent inspector now switches to **Completed** the moment it finishes, instead of showing **Working** until the next step. ## [](#v0-2-11-2026-06-30)v0.2.11 (2026-06-30) ### [](#bug-fixes-18)Bug fixes CLI Signing in with `rpk ai auth login` now clears the expired-token errors that kept `rpk ai` commands failing even after a successful login. ## [](#v0-2-10-2026-06-30)v0.2.10 (2026-06-30) ### [](#features-16)Features Agents `[UI]` When an agent produces a chart, the agent inspector now displays it: switch between the chart, its data, and its definition, and zoom in or download it. Error handling `[UI]` Capture a failed request for support and get a reference ID to quote. ### [](#improvements-21)Improvements Error handling `[UI]` Failed requests now show the full error message and type, with expandable technical details, instead of a generic internal error. List pages `[UI]` The MCP servers, LLM providers, OAuth providers, OAuth clients, and Secrets Store lists now have consistent search, filtering, and multi-row selection. ### [](#bug-fixes-19)Bug fixes LLM Providers The Bedrock provider rejected valid model IDs whose version contains a dot, in all regions; these now route correctly. ## [](#v0-2-9-2026-06-29)v0.2.9 (2026-06-29) ### [](#features-17)Features MCP Servers Connect to Sentry through a new managed MCP server. LLM Providers Set your own per-model pricing on a provider, so usage and cost reflect the rates you actually pay. rpk ai `[CLI]` Apply or diff your LLM providers, MCP servers, and OAuth providers from config files, now against an Agentic Data Plane environment. ### [](#improvements-22)Improvements MCP Servers Filter the server list by type and status. OAuth Providers Filter providers and clients by status and how they were created. Cost & Usage Export charts to CSV and download a full usage report. Environments The environment switcher now shows each environment’s region, so you don’t make changes in the wrong one. ### [](#bug-fixes-20)Bug fixes Reliability Fixed hangs when switching environments, and the app now recovers on its own after a new version ships instead of showing errors. Lists Fixed filters showing wrong results, and lists now refresh immediately after you add or edit an item. --- # Page 83: Install or Update rpk **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk-install.md --- # Install or Update rpk > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Install or Update rpk latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk-install page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk-install.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk-install.adoc description: Install or update rpk to interact with Redpanda from the command line. page-git-created-date: "2026-05-28" page-git-modified-date: "2026-05-28" --- The `rpk` tool is a single binary application that provides a way to interact with your Redpanda clusters from the command line. For example, you can use `rpk` to do the following: - Monitor your cluster’s health - Create, produce, and consume from topics - Set up access control lists (ACLs) and other security features Redpanda Cloud deployments should always use the latest version of `rpk`. ## [](#check-rpk-version)Check rpk version To check your current version of the rpk binary, run `rpk --version`. The following example lists the latest version of `rpk`. If your installed version is lower than this latest version, then update `rpk`. For a list of versions, see [Redpanda releases](https://github.com/redpanda-data/redpanda/releases/). ```bash rpk --version ``` ```bash rpk version 26.2.1 (rev 5218325) ``` ## [](#install-or-update-rpk-on-linux)Install or update rpk on Linux To install, or update to, the latest version of `rpk` for Linux, run: ### amd64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-amd64.zip -d ~/.local/bin/ ``` ### arm64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-arm64.zip -d ~/.local/bin/ ``` > 💡 **TIP** > > You can use `rpk` on Windows only with [WSL](https://learn.microsoft.com/windows/wsl/install). However, commands that require Redpanda to be installed on your machine are not supported, such as [`rpk container`](https://docs.redpanda.com/streaming/current/reference/rpk/rpk-container/rpk-container/) commands, [`rpk iotune`](https://docs.redpanda.com/streaming/current/reference/rpk/rpk-iotune/), and [`rpk redpanda`](https://docs.redpanda.com/streaming/current/reference/rpk/rpk-redpanda/rpk-redpanda/) commands. ## [](#install-or-update-rpk-on-macos)Install or update rpk on macOS ### Homebrew 1. If you don’t have Homebrew installed, [install it](https://brew.sh/). 2. To install or update `rpk`, run: ```bash brew install redpanda-data/tap/redpanda ``` ### Manual Download To install or update `rpk` through a manual download, choose the option for your system architecture. For example, if you have an M1 or newer chip, select **Apple Silicon**. #### Intel macOS To install, or update to, the latest version of `rpk` for Intel macOS, run: ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-darwin-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-darwin-amd64.zip -d ~/.local/bin/ ``` To install, or update to, a version other than the latest, run: ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/download/v/rpk-darwin-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-darwin-amd64.zip -d ~/.local/bin/ ``` #### Apple Silicon To install, or update to, the latest version of `rpk` for Apple Silicon, run: ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-darwin-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-darwin-arm64.zip -d ~/.local/bin/ ``` To install, or update to, a version other than the latest, run: ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/download/v/rpk-darwin-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-darwin-arm64.zip -d ~/.local/bin/ ``` ## [](#next-steps)Next steps For the complete list of `rpk` commands and their syntax, see the [rpk reference](https://docs.redpanda.com/agentic-data-plane/reference/rpk/). --- # Page 84: rpk Command Reference **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk.md --- # rpk Command Reference > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk Command Reference latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/index page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/index.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/index.adoc description: Reference for the rpk commands used to manage the Redpanda Agentic Data Plane from the command line. page-git-created-date: "2026-05-11" page-git-modified-date: "2026-07-29" --- This section documents the `rpk` commands you use to manage the Redpanda Agentic Data Plane from the command line. Use `rpk ai` to manage AI Gateway resources (LLM providers, MCP servers, OAuth providers) and call MCP tools directly from your terminal. `rpk ai` is self-contained: it has its own login (`rpk ai auth login`) and its own Agentic Data Plane environment selection (`rpk ai env`), independent of any `rpk cloud` session. The active AI Gateway URL comes from the selected environment unless you override it with `--rpai-endpoint`. For subcommands available after install (`rpk ai llm-provider`, `rpk ai mcp-server`, `rpk ai oauth-provider`, and more), run `rpk ai --help` from your terminal. - [rpk ai](rpk-ai/rpk-ai/) Manage the Redpanda AI Gateway. - [rpk profile](rpk-profile/rpk-profile/) Manage `rpk` profiles. An rpk profile talks to a single Redpanda cluster. - [rpk -X](rpk-x-options/) Override any rpk configuration option for a single command with the -X flag, or set it persistently with an RPK\_ environment variable. --- # Page 85: rpk ai agent a2a card **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-a2a-card.md --- # rpk ai agent a2a card > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent a2a card latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-a2a-card page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-a2a-card.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-a2a-card.adoc description: "Fetch the A2A agent card: the JSON discovery document describing the agent's identity, skills, supported transports and capabilities. Use -o json to feed the raw card to other tools." page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Fetch the A2A agent card: the JSON discovery document describing the agent’s identity, skills, supported transports and capabilities. Use `-o json` to feed the raw card to other tools. ## [](#usage)Usage ```bash rpk ai agent a2a card [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --timeout | duration | abort the call after this long (0 to wait forever). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 86: rpk ai agent a2a send **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-a2a-send.md --- # rpk ai agent a2a send > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent a2a send latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-a2a-send page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-a2a-send.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-a2a-send.adoc description: Send a text message to an agent over A2A and print the reply. The message comes from the positional argument, or from stdin when the argument is omitted or "-" (so you can pipe a prompt in). page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Send a text message to an agent over A2A and print the reply. The message comes from the positional argument, or from stdin when the argument is omitted or "-" (so you can pipe a prompt in). By default the call blocks until the agent replies. Replies that spawn a long-running task print the task id so you can follow up with `rpk ai agent a2a task get|watch|cancel`. For work that may outlive `--timeout` (default 5m), prefer `--stream` or `--no-block` so the task id is in hand from the start. Conversation state: every reply prints a context-id (stderr in the default format, part of the JSON in `-o json`). Pass it back via `--context-id` to continue the same conversation. When a task ends in state input-required, answer it by sending again with both `--task-id` and `--context-id` from the reply. Output: the agent’s reply text goes to stdout; ids and state go to stderr as `key: value` lines so pipes stay clean. Use `-o json` for the full A2A response (message or task object). With `--stream`, `json` and `yaml` both emit one JSON event per line (JSONL). Exit codes: 0 success or input-required, 4 task failed/canceled/ rejected, 1 anything else. ## [](#usage)Usage ```bash rpk ai agent a2a send [flags] ``` ## [](#examples)Examples This section provides examples of how to use `rpk ai agent a2a send`. Ask and wait for the answer ```bash rpk ai agent a2a send financial-advisor "What moved the S&P 500 today?" ``` Continue the conversation from a previous reply’s context-id ```bash rpk ai agent a2a send financial-advisor --context-id CTX "Why?" ``` Answer a task that ended in input-required ```bash rpk ai agent a2a send financial-advisor --task-id TASK --context-id CTX "Account A-17" ``` Pipe the prompt from a file, get the full JSON reply ```bash cat prompt.txt | rpk ai agent a2a send financial-advisor -o json ``` Stream events as they happen ```bash rpk ai agent a2a send financial-advisor --stream "Give me a market summary" ``` Fire-and-forget: submit, then poll with `task get` ```bash rpk ai agent a2a send financial-advisor --no-block "Deep analysis please" ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --context-id | string | continue an existing conversation (printed by a previous send). | | --no-block | bool | return immediately with the submitted task instead of waiting for completion. | | --stream | bool | stream the reply as A2A events (message/stream) instead of waiting for the final result. | | --task-id | string | continue an existing task (for example, answer an input-required task). | | --timeout | duration | abort the call after this long (0 to wait forever). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 87: rpk ai agent a2a task cancel **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-a2a-task-cancel.md --- # rpk ai agent a2a task cancel > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent a2a task cancel latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-a2a-task-cancel page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-a2a-task-cancel.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-a2a-task-cancel.adoc description: Ask the agent to cancel a running task and print the task's resulting state. Cancellation is cooperative; the agent may already have finished, in which case the terminal state is returned unchanged. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Ask the agent to cancel a running task and print the task’s resulting state. Cancellation is cooperative; the agent may already have finished, in which case the terminal state is returned unchanged. ## [](#usage)Usage ```bash rpk ai agent a2a task cancel [flags] ``` ## [](#examples)Examples This section provides examples of how to use `rpk ai agent a2a task cancel`. ```bash rpk ai agent a2a task cancel financial-advisor TASK_ID ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --timeout | duration | abort the call after this long (0 to wait forever). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 88: rpk ai agent a2a task get **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-a2a-task-get.md --- # rpk ai agent a2a task get > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent a2a task get latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-a2a-task-get page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-a2a-task-get.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-a2a-task-get.adoc description: Fetch a task's current state, status message, artifacts and (optionally truncated) message history. Use -o json for the full task object. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Fetch a task’s current state, status message, artifacts and (optionally truncated) message history. Use `-o json` for the full task object. ## [](#usage)Usage ```bash rpk ai agent a2a task get [flags] ``` ## [](#examples)Examples This section provides examples of how to use `rpk ai agent a2a task get`. ```bash rpk ai agent a2a task get financial-advisor TASK_ID rpk ai agent a2a task get financial-advisor TASK_ID --history 10 -o json ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --history | int | number of most recent history messages to include. | | --timeout | duration | abort the call after this long (0 to wait forever). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 89: rpk ai agent a2a task watch **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-a2a-task-watch.md --- # rpk ai agent a2a task watch > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent a2a task watch latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-a2a-task-watch page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-a2a-task-watch.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-a2a-task-watch.adoc description: Reattach to a running task's event stream (A2A tasks/resubscribe) and print events until the task reaches a terminal state. Use after a disconnected --stream send or a --no-block send. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Reattach to a running task’s event stream (A2A tasks/resubscribe) and print events until the task reaches a terminal state. Use after a disconnected `--stream` send or a `--no-block` send. Watch waits as long as the task runs (no timeout by default; bound it with `--timeout`). Exit codes match send: 0 success or input-required, 4 task failed/canceled/rejected, 1 anything else. ## [](#usage)Usage ```bash rpk ai agent a2a task watch [flags] ``` ## [](#examples)Examples This section provides examples of how to use `rpk ai agent a2a task watch`. ```bash rpk ai agent a2a task watch financial-advisor TASK_ID rpk ai agent a2a task watch financial-advisor TASK_ID -o json # one JSON event per line ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --timeout | duration | abort after this long (default: wait forever). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 90: rpk ai agent a2a task **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-a2a-task.md --- # rpk ai agent a2a task > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent a2a task latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-a2a-task page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-a2a-task.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-a2a-task.adoc description: Manage tasks created by agent-to-agent (A2A) conversations. Task IDs come from rpk ai agent a2a send replies. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Manage tasks created by agent-to-agent (A2A) conversations. Task IDs come from `rpk ai agent a2a send` replies. Use subcommands to get, watch, or cancel a task. ## [](#usage)Usage ```bash rpk ai agent a2a task [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 91: rpk ai agent a2a **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-a2a.md --- # rpk ai agent a2a > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent a2a latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-a2a page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-a2a.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-a2a.adoc description: Interact with an agent over the A2A (Agent-to-Agent) protocol. The AGENT argument is either a registry agent name (resolved to the agent's A2A endpoint via its runtime status) or a full A2A endpoint URL (anything starting with http:// or https://). page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Interact with an agent over the A2A (Agent-to-Agent) protocol. The AGENT argument is either a registry agent name (resolved to the agent’s A2A endpoint via its runtime status) or a full A2A endpoint URL (anything starting with http:// or https://). Authentication: your environment’s bearer token is attached when the target is a registry agent or an explicit URL on the environment’s dataplane host. Explicit URLs on other hosts are called without credentials so your token never leaves the platform (a note on stderr says so when this happens). Output formats: table (`default`, human-readable) and `-o json` / `-o yaml`. Streams (`--stream`, task watch) emit one JSON event per line under both `json` and `yaml`. Exit codes: 0 success (including tasks waiting for more input), 4 task ended failed/canceled/rejected, 1 anything else. ## [](#usage)Usage ```bash rpk ai agent a2a [flags] ``` ## [](#examples)Examples This section provides examples of how to use `rpk ai agent a2a`. Discover what an agent can do ```bash rpk ai agent a2a card financial-advisor ``` Ask a question (waits for the reply) ```bash rpk ai agent a2a send financial-advisor "How did tech stocks do today?" ``` Continue the same conversation ```bash rpk ai agent a2a send financial-advisor --context-id CTX "And yesterday?" ``` Stream the reply as it is produced ```bash rpk ai agent a2a send financial-advisor --stream "Summarize the market" ``` Inspect, watch, or cancel a long-running task ```bash rpk ai agent a2a task get financial-advisor TASK_ID rpk ai agent a2a task watch financial-advisor TASK_ID rpk ai agent a2a task cancel financial-advisor TASK_ID ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 92: rpk ai agent apply **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-apply.md --- # rpk ai agent apply > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent apply latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-apply page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-apply.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-apply.adoc description: "Reconcile agents from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource." page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Reconcile agents from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource. Fields you omit are left untouched; to clear a field, write it explicitly. Lists, maps and oneof variants replace wholesale. Fields that can only be set at creation time are immutable; changing one is an error. Manifests round-trip with `get -o yaml` for this resource. Pass `-f` - to read stdin. This does not delete resources absent from the manifests (no prune), and drift is detected only for the fields a manifest names; see `diff --help`. ## [](#usage)Usage ```bash rpk ai agent apply [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | strings | manifest file, directory, or - for stdin (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 93: rpk ai agent create **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-create.md --- # rpk ai agent create > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent create latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-create page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-create.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-create.adoc description: Create an agent. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Create an agent. ## [](#usage)Usage ```bash rpk ai agent create [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --description | string | longer description of the agent’s purpose. | | --display-name | string | display name. | | --llm-provider | string | name of the LLM provider resource the agent uses. | | --max-iterations | int32 | maximum agent loop iterations per invocation. | | --mcp-server | strings | MCP server resource name the agent may call (repeatable). | | --model | string | model the agent runs (for example, claude-sonnet-4-6). | | --self-managed | bool | register a metadata-only self-managed agent (the platform won’t run it). | | --spec-file | string | path to a JSON/YAML ManagedAgentSpec; enables subagents/agent_card that scalar flags can’t express (mutually exclusive with --self-managed and the spec flags). | | --system-prompt | string | system prompt for the agent. | | --tag | stringToString | metadata tag key=value (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 94: rpk ai agent credential create **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-credential-create.md --- # rpk ai agent credential create > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent credential create latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-credential-create page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-credential-create.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-credential-create.adoc description: Create a client ID and secret pair for an agent. The client secret is shown once and cannot be retrieved again. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Create a client ID and secret pair for an agent. The client secret is shown once and cannot be retrieved again. ## [](#usage)Usage ```bash rpk ai agent credential create [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --description | string | human-readable description of the credential. | | --ttl | duration | lifetime before the credential expires (for example, 720h); 0 means no expiry. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 95: rpk ai agent credential delete **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-credential-delete.md --- # rpk ai agent credential delete > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent credential delete latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-credential-delete page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-credential-delete.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-credential-delete.adoc description: Delete a credential. Specify the full resource name as shown by rpk ai agent credential list, for example agents/my-agent/credentials/abc123. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Delete a credential. Specify the full resource name as shown by `rpk ai agent credential list`, for example `agents/my-agent/credentials/abc123`. ## [](#usage)Usage ```bash rpk ai agent credential delete [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 96: rpk ai agent credential list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-credential-list.md --- # rpk ai agent credential list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent credential list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-credential-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-credential-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-credential-list.adoc description: List an agent's credentials. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- List an agent’s credentials. ## [](#usage)Usage ```bash rpk ai agent credential list [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 97: rpk ai agent credential **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-credential.md --- # rpk ai agent credential > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent credential latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-credential page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-credential.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-credential.adoc description: Manage an agent's credentials (create, list, delete). page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Manage an agent’s credentials (`create`, list, delete). ## [](#usage)Usage ```bash rpk ai agent credential [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 98: rpk ai agent delete **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-delete.md --- # rpk ai agent delete > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent delete latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-delete page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-delete.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-delete.adoc description: Delete an agent. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Delete an agent. ## [](#usage)Usage ```bash rpk ai agent delete [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 99: rpk ai agent diff **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-diff.md --- # rpk ai agent diff > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent diff latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-diff page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-diff.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-diff.adoc description: Dry-run of apply for agents. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Dry-run of apply for agents. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. Exits non-zero when any change is pending, so CI can gate on `no drift`. > 📝 **NOTE** > > diff proves only that the fields a manifest names match live. It does not detect resources that exist live but are absent from the manifests (no prune), nor drift in fields a manifest omits. ## [](#usage)Usage ```bash rpk ai agent diff [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | strings | manifest file, directory, or - for stdin (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 100: rpk ai agent get **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-get.md --- # rpk ai agent get > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent get latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-get page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-get.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-get.adoc description: Get an agent. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Get an agent. ## [](#usage)Usage ```bash rpk ai agent get [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 101: rpk ai agent list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-list.md --- # rpk ai agent list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-list.adoc description: List agents. page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- List agents. ## [](#usage)Usage ```bash rpk ai agent list [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --filter | string | AIP-160 filter expression, for example, name:`web` or display_name=prod. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 102: rpk ai agent start **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-start.md --- # rpk ai agent start > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent start latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-start page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-start.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-start.adoc description: Start a managed agent, setting its desired state to running. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Start a managed agent, setting its desired state to running. ## [](#usage)Usage ```bash rpk ai agent start [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 103: rpk ai agent stop **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-stop.md --- # rpk ai agent stop > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent stop latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-stop page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-stop.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-stop.adoc description: Stop a managed agent, setting its desired state to stopped. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Stop a managed agent, setting its desired state to stopped. ## [](#usage)Usage ```bash rpk ai agent stop [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 104: rpk ai agent transcript get **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-transcript-get.md --- # rpk ai agent transcript get > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent transcript get latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-transcript-get page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-transcript-get.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-transcript-get.adoc description: Get a single conversation transcript with its turns. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Get a single conversation transcript with its turns. ## [](#usage)Usage ```bash rpk ai agent transcript get [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 105: rpk ai agent transcript list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-transcript-list.md --- # rpk ai agent transcript list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent transcript list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-transcript-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-transcript-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-transcript-list.adoc description: List an agent's conversation transcripts. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- List an agent’s conversation transcripts. ## [](#usage)Usage ```bash rpk ai agent transcript list [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --errors-only | bool | only conversations that contain errors. | | --query | string | free-text search across conversation titles and content. | | --since | string | only conversations started at/after this time (RFC3339, or a duration ago like 24h). | | --status | string | filter by status: running, completed, error. | | --until | string | only conversations started before this time (RFC3339, or a duration ago like 1h). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 106: rpk ai agent transcript **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-transcript.md --- # rpk ai agent transcript > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent transcript latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-transcript page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-transcript.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-transcript.adoc description: Inspect an agent's conversation transcripts (list, get). page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Inspect an agent’s conversation transcripts (`list`, get). ## [](#usage)Usage ```bash rpk ai agent transcript [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 107: rpk ai agent update **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent-update.md --- # rpk ai agent update > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent update latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent-update page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent-update.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent-update.adoc description: Update an agent. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Update an agent. ## [](#usage)Usage ```bash rpk ai agent update [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --description | string | new description. | | --display-name | string | new display name. | | --llm-provider | string | name of the LLM provider resource the agent uses. | | --max-iterations | int32 | maximum agent loop iterations per invocation. | | --mcp-server | strings | MCP server resource name the agent may call (repeatable). | | --model | string | model the agent runs (for example, claude-sonnet-4-6). | | --system-prompt | string | system prompt for the agent. | | --tag | stringToString | replacement metadata tags key=value (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 108: rpk ai agent **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-agent.md --- # rpk ai agent > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai agent latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-agent page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-agent.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-agent.adoc description: Manage agents registered with the Redpanda AI platform. Agents are either managed (adp runs them; configured via a model, LLM provider, system prompt and MCP servers) or self-managed (a metadata-only record tracking a user-hosted agent). page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- Manage agents registered with the Redpanda AI platform. Agents are either managed (adp runs them; configured via a model, LLM provider, system prompt and MCP servers) or self-managed (a metadata-only record tracking a user-hosted agent). `create` makes a managed agent by default; pass `--self-managed` for the metadata-only variant. The `credential` subcommand provisions client-id/secret pairs an agent uses to authenticate against the gateway. The `a2a` subcommand talks to a running agent over the A2A protocol (fetch its card, send messages, manage tasks). ## [](#usage)Usage ```bash rpk ai agent [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 109: rpk ai auth login **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-auth-login.md --- # rpk ai auth login > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai auth login latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-auth-login page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-auth-login.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-auth-login.adoc description: Run the OAuth 2.0 device authorization grant against Redpanda Cloud, persist the resulting credentials, and prompt to select an environment whose AI Gateway URL becomes the active profile's dataplane URL. Credentials are stored in the rpk ai credentials file with 0600 permissions, keyed by organization. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Run the OAuth 2.0 device authorization grant against Redpanda Cloud, persist the resulting credentials, and prompt to select an environment whose AI Gateway URL becomes the active profile’s dataplane URL. Credentials are stored in the `rpk ai` credentials file with `0600` permissions, keyed by organization. A successful login rewrites the config in the current schema, so running `rpk ai auth login` is also how you migrate a config left over from an older version of the plugin. If the current environment’s organization still holds valid credentials, login is a no-op and prints "Already logged in". Run `rpk ai auth logout` first to re-authenticate, or `rpk ai auth logout --all` for a full clean slate. ## [](#usage)Usage ```bash rpk ai auth login [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --no-browser | bool | do not attempt to open the browser; print the URL only. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 110: rpk ai auth logout **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-auth-logout.md --- # rpk ai auth logout > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai auth logout latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-auth-logout page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-auth-logout.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-auth-logout.adoc description: Delete stored credentials for the current organization (or --all for a full clean slate). page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Delete stored credentials for the current organization (or `--all` for a full clean slate). ## [](#usage)Usage ```bash rpk ai auth logout [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --all | bool | full clean slate: remove ALL credentials AND the config file (including manual environments). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 111: rpk ai auth status **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-auth-status.md --- # rpk ai auth status > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai auth status latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-auth-status page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-auth-status.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-auth-status.adoc description: Show the authentication state for the current environment. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Show the authentication state for the current environment. ## [](#usage)Usage ```bash rpk ai auth status [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -o, --format | string | output format: table|`json`|`yaml`|markdown (overrides root --format). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 112: rpk ai auth token **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-auth-token.md --- # rpk ai auth token > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai auth token latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-auth-token page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-auth-token.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-auth-token.adoc description: Print the current bearer access token to stdout (refreshes if expired). page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Print the current bearer access token to stdout (refreshes if expired). ## [](#usage)Usage ```bash rpk ai auth token [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --refresh-within | duration | proactively refresh if the token expires within this window (for polling callers like a Codex/Claude auth helper); 0 uses the default 60s leeway. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 113: rpk ai auth **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-auth.md --- # rpk ai auth > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai auth latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-auth page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-auth.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-auth.adoc description: Manage rpk ai authentication (login, logout, token, status). page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Manage `rpk` ai authentication (`login`, logout, token, status). ## [](#usage)Usage ```bash rpk ai auth [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 114: rpk ai connection list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-connection-list.md --- # rpk ai connection list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai connection list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-connection-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-connection-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-connection-list.adoc description: List your OAuth connections. page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- List your OAuth connections. ## [](#usage)Usage ```bash rpk ai connection list [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 115: rpk ai connection revoke **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-connection-revoke.md --- # rpk ai connection revoke > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai connection revoke latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-connection-revoke page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-connection-revoke.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-connection-revoke.adoc description: "Revoke your connection to the named OAuth provider: the stored tokens are invalidated and the provider's revocation endpoint is called best-effort. This affects only your own connection, not other users'." page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- Revoke your connection to the named OAuth provider: the stored tokens are invalidated and the provider’s revocation endpoint is called best-effort. This affects only your own connection, not other users'. ## [](#usage)Usage ```bash rpk ai connection revoke [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 116: rpk ai connection **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-connection.md --- # rpk ai connection > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai connection latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-connection page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-connection.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-connection.adoc description: List and revoke the OAuth connections you hold to third-party providers. A connection is your personal grant to a provider (created by signing in through the consent flow) that lets user_oauth MCP servers act on your behalf. page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- List and revoke the OAuth connections you hold to third-party providers. A connection is your personal grant to a provider (created by signing in through the consent flow) that lets user\_oauth MCP servers act on your behalf. Revoke is per user, per provider. ## [](#usage)Usage ```bash rpk ai connection [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 117: rpk ai env add **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-env-add.md --- # rpk ai env add > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai env add latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-env-add page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-env-add.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-env-add.adoc description: Add a manual rpk ai environment with explicit URLs. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Add a manual `rpk` ai environment with explicit URLs. ## [](#usage)Usage ```bash rpk ai env add [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --adp-api-url | string | adp-api base URL (optional; derived from the AI Gateway URL when omitted). | | --ai-gateway-url | string | AI Gateway base URL (required). | | --auth-mode | string | auth mode: device|rpk|token|none (default device). device borrows your logged-in org’s token; use none/token for a local aigw. | | --description | string | optional human-readable description. | | --from | string | copy an existing manual environment as the base. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 118: rpk ai env delete **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-env-delete.md --- # rpk ai env delete > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai env delete latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-env-delete page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-env-delete.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-env-delete.adoc description: Delete a manual environment. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Delete a manual environment. ## [](#usage)Usage ```bash rpk ai env delete [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --force | bool | delete even if NAME is the current environment. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 119: rpk ai env list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-env-list.md --- # rpk ai env list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai env list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-env-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-env-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-env-list.adoc description: List environments (current org's live Agentic Data Plane envs + local manual envs). page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-07" --- List environments (current org’s live Agentic Data Plane envs + local manual envs). ## [](#usage)Usage ```bash rpk ai env list [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --local | bool | skip the live Agentic Data Plane environments lookup; show only local manual environments. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 120: rpk ai env rename **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-env-rename.md --- # rpk ai env rename > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai env rename latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-env-rename page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-env-rename.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-env-rename.adoc description: Rename a manual environment. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Rename a manual environment. ## [](#usage)Usage ```bash rpk ai env rename [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 121: rpk ai env show **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-env-show.md --- # rpk ai env show > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai env show latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-env-show page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-env-show.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-env-show.adoc description: Show the effective resolved environment as YAML (tokens redacted). page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Show the effective resolved environment as YAML (tokens redacted). ## [](#usage)Usage ```bash rpk ai env show [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 122: rpk ai env use **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-env-use.md --- # rpk ai env use > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai env use latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-env-use page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-env-use.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-env-use.adoc description: Switch to a manual environment, or select an Agentic Data Plane environment by name or id. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-07" --- Switch to a manual environment, or select an Agentic Data Plane environment by name or id. ## [](#usage)Usage ```bash rpk ai env use [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 123: rpk ai env **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-env.md --- # rpk ai env > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai env latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-env page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-env.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-env.adoc description: Manage rpk ai environments (list, use, add, show, rename, delete). page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Manage `rpk` ai environments (`list`, use, add, show, rename, delete). ## [](#usage)Usage ```bash rpk ai env [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 124: rpk ai install **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-install.md --- # rpk ai install > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai install latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-install page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-install.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-install.adoc description: Install the Redpanda AI CLI. This command installs the latest version by default. page-git-created-date: "2026-05-11" page-git-modified-date: "2026-08-06" --- Install the Redpanda AI CLI. This command installs the latest version by default. Alternatively, you may specify an `rpk ai version` using the `--ai-version` flag. You may force the installation using the `--force` flag. ## [](#usage)Usage ```bash rpk ai install [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --ai-version | string | Redpanda AI CLI version to install (for example, 0.1.2). | | --force | bool | Force install of the Redpanda AI CLI. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 125: rpk ai llm-provider apply **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-llm-provider-apply.md --- # rpk ai llm-provider apply > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai llm-provider apply latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-llm-provider-apply page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-llm-provider-apply.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-llm-provider-apply.adoc description: "Reconcile LLM providers from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource." page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Reconcile LLM providers from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource. Fields you omit are left untouched; to clear a field, write it explicitly. Lists, maps and oneof variants replace wholesale. Fields that can only be set at creation time are immutable; changing one is an error. Manifests round-trip with `get -o yaml` for this resource. Pass `-f` - to read stdin. This does not delete resources absent from the manifests (no prune), and drift is detected only for the fields a manifest names; see `diff --help`. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai llm-provider apply [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | strings | manifest file, directory, or - for stdin (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 126: rpk ai llm-provider check **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-llm-provider-check.md --- # rpk ai llm-provider check > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai llm-provider check latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-llm-provider-check page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-llm-provider-check.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-llm-provider-check.adoc description: Runs a lightweight probe against the upstream to verify credentials and reachability. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Runs a lightweight probe against the upstream to verify credentials and reachability. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai llm-provider check [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 127: rpk ai llm-provider create **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-llm-provider-create.md --- # rpk ai llm-provider create > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai llm-provider create latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-llm-provider-create page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-llm-provider-create.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-llm-provider-create.adoc description: "Create an LLM provider. Choose the provider-config by setting flags from one group; the group you use selects it: openai-config, anthropic-config, google-config, bedrock-config, openai-compatible-config." page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Create an LLM provider. Choose the provider-config by setting flags from one group; the group you use selects it: openai-config, anthropic-config, google-config, bedrock-config, openai-compatible-config. Setting flags from two groups is an error. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai llm-provider create [flags] ``` ## [](#examples)Examples This section provides examples of how to use `rpk ai llm-provider create`. ```bash rpk ai llm-provider create my-llm-provider \ --openai-config.api-key-ref OPENAI_API_KEY ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --display-name | string | Human-readable name for display in the UI. | | --provider-models | stringArray | Model identifiers available through this provider. Leave empty to allow all models. (repeatable; name (bare values comma-split) or protojson object; replaces the full list on update). | | --enabled | bool | Whether this provider is active and accepting requests. (true when set; pass --enabled=false to disable). | | --openai-config.base-url | string | Override the default API endpoint. Leave empty for the standard OpenAI API. | | --openai-config.api-key-ref | string | Secret store reference for the API key. Leave empty for no-auth endpoints (Ollama, vLLM, local models). | | --anthropic-config.base-url | string | Override the default API endpoint. Leave empty for the standard Anthropic API. | | --anthropic-config.api-key-ref | string | Secret store reference for the API key. Leave empty when using authorization passthrough. | | --anthropic-config.authorization-passthrough | bool | Forward the client’s Authorization header to Anthropic instead of using a server-side API key. Used for enterprise/Max plan OAuth passthrough. (true when set; pass --anthropic-config.authorization-passthrough=false to disable). | | --google-config.base-url | string | Override the default API endpoint. Leave empty for the standard Google AI API. | | --google-config.api-key-ref | string | Secret store reference for the Google AI API key. | | --bedrock-config.region | string | AWS region where the Bedrock endpoint is deployed. (required in its group) (alias: --region). | | --bedrock-config.base-url | string | Override the default Bedrock endpoint URL. Leave empty for the standard regional endpoint. | | --bedrock-config.static-credentials.access-key-id-ref | string | Secret store reference for the AWS access key ID. (required in its group) (alias: --access-key-id-ref). | | --bedrock-config.static-credentials.secret-access-key-ref | string | Secret store reference for the AWS secret access key. (required in its group) (alias: --secret-access-key-ref). | | --bedrock-config.assume-role.role-arn | string | ARN of the IAM role to assume for Bedrock access. (required in its group) (alias: --role-arn). | | --bedrock-config.assume-role.external-id | string | External ID for cross-account role assumption. Required when the role’s trust policy mandates it. | | --bedrock-config.assume-role.session-name | string | Session name for CloudTrail audit logging. | | --openai-compatible-config.base-url | string | Override the default API endpoint. Leave empty for the standard OpenAI API. | | --openai-compatible-config.api-key-ref | string | Secret store reference for the API key. Leave empty for no-auth endpoints (Ollama, vLLM, local models). | | --transcripts.record-input-messages | bool | Capture full request bodies (prompts) on observability traces. (true when set; pass --transcripts.record-input-messages=false to disable). | | --transcripts.record-output-messages | bool | Capture full response bodies (completions) on observability traces. (true when set; pass --transcripts.record-output-messages=false to disable). | | --guardrail | string | Name of a Guardrail to attach to this provider. Leave empty for no guardrail. For Bedrock provider the guardrail uses AWS Bedrock Guardrail directly. For all other providers the proxy evaluates user input against the Bedrock Guardrail’s standalone backend. In both cases a guardrail intervention short-circuits the request. | | --tags | stringArray | Tags. (repeatable key=value; replaces the full map on update). (New in 0.2.33) | | -f, --filename | string | manifest to create from (YAML or JSON; "-" for stdin); flags override file values. | | --dry-run | bool | print the request that would be sent (with the computed update mask) and exit without calling the server. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 128: rpk ai llm-provider delete **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-llm-provider-delete.md --- # rpk ai llm-provider delete > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai llm-provider delete latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-llm-provider-delete page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-llm-provider-delete.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-llm-provider-delete.adoc description: Delete an LLM provider. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Delete an LLM provider. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai llm-provider delete [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 129: rpk ai llm-provider diff **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-llm-provider-diff.md --- # rpk ai llm-provider diff > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai llm-provider diff latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-llm-provider-diff page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-llm-provider-diff.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-llm-provider-diff.adoc description: Dry-run of apply for LLM providers. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Dry-run of apply for LLM providers. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. Exits non-zero when any change is pending, so CI can gate on `no drift`. > 📝 **NOTE** > > diff proves only that the fields a manifest names match live. It does not detect resources that exist live but are absent from the manifests (no prune), nor drift in fields a manifest omits. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai llm-provider diff [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | strings | manifest file, directory, or - for stdin (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 130: rpk ai llm-provider get **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-llm-provider-get.md --- # rpk ai llm-provider get > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai llm-provider get latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-llm-provider-get page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-llm-provider-get.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-llm-provider-get.adoc description: Get an LLM provider. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Get an LLM provider. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai llm-provider get [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 131: rpk ai llm-provider list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-llm-provider-list.md --- # rpk ai llm-provider list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai llm-provider list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-llm-provider-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-llm-provider-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-llm-provider-list.adoc description: List LLM providers. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- List LLM providers. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai llm-provider list [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --name-contains | string | Name contains. | | --filter | string | AIP-160 filter expression (https://google.aip.dev/160). | | --page-size | int32 | Page size. | | --page-token | string | Page token. | | --order-by | string | AIP-132 order: a comma-separated list of fields, each optionally suffixed with " desc" (default ascending). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 132: rpk ai llm-provider update **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-llm-provider-update.md --- # rpk ai llm-provider update > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai llm-provider update latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-llm-provider-update page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-llm-provider-update.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-llm-provider-update.adoc description: Update an LLM provider. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Update an LLM provider. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai llm-provider update [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --display-name | string | Human-readable name for display in the UI. | | --provider-models | stringArray | Model identifiers available through this provider. Leave empty to allow all models. (repeatable; name (bare values comma-split) or protojson object; replaces the full list on update). | | --enabled | bool | Whether this provider is active and accepting requests. (true when set; pass --enabled=false to disable). | | --openai-config.base-url | string | Override the default API endpoint. Leave empty for the standard OpenAI API. | | --openai-config.api-key-ref | string | Secret store reference for the API key. Leave empty for no-auth endpoints (Ollama, vLLM, local models). | | --anthropic-config.base-url | string | Override the default API endpoint. Leave empty for the standard Anthropic API. | | --anthropic-config.api-key-ref | string | Secret store reference for the API key. Leave empty when using authorization passthrough. | | --anthropic-config.authorization-passthrough | bool | Forward the client’s Authorization header to Anthropic instead of using a server-side API key. Used for enterprise/Max plan OAuth passthrough. (true when set; pass --anthropic-config.authorization-passthrough=false to disable). | | --google-config.base-url | string | Override the default API endpoint. Leave empty for the standard Google AI API. | | --google-config.api-key-ref | string | Secret store reference for the Google AI API key. | | --bedrock-config.region | string | AWS region where the Bedrock endpoint is deployed. (required in its group) (alias: --region). | | --bedrock-config.base-url | string | Override the default Bedrock endpoint URL. Leave empty for the standard regional endpoint. | | --bedrock-config.static-credentials.access-key-id-ref | string | Secret store reference for the AWS access key ID. (required in its group) (alias: --access-key-id-ref). | | --bedrock-config.static-credentials.secret-access-key-ref | string | Secret store reference for the AWS secret access key. (required in its group) (alias: --secret-access-key-ref). | | --bedrock-config.assume-role.role-arn | string | ARN of the IAM role to assume for Bedrock access. (required in its group) (alias: --role-arn). | | --bedrock-config.assume-role.external-id | string | External ID for cross-account role assumption. Required when the role’s trust policy mandates it. | | --bedrock-config.assume-role.session-name | string | Session name for CloudTrail audit logging. | | --openai-compatible-config.base-url | string | Override the default API endpoint. Leave empty for the standard OpenAI API. | | --openai-compatible-config.api-key-ref | string | Secret store reference for the API key. Leave empty for no-auth endpoints (Ollama, vLLM, local models). | | --transcripts.record-input-messages | bool | Capture full request bodies (prompts) on observability traces. (true when set; pass --transcripts.record-input-messages=false to disable). | | --transcripts.record-output-messages | bool | Capture full response bodies (completions) on observability traces. (true when set; pass --transcripts.record-output-messages=false to disable). | | --guardrail | string | Name of a Guardrail to attach to this provider. Leave empty for no guardrail. For Bedrock providers the guardrail rides the upstream call via AWS guardrail headers and is enforced by Bedrock itself. For all other providers the proxy evaluates user input against the guardrail’s standalone ApplyGuardrail backend before forwarding the request upstream. In both cases a guardrail intervention short-circuits the request. | | --tags | stringArray | Tags. (repeatable key=value; replaces the full map on update). (New in 0.2.33) | | -f, --filename | string | manifest to update from (YAML or JSON; "-" for stdin); flags override file values. | | --dry-run | bool | print the request that would be sent (with the computed update mask) and exit without calling the server. | | --clear | strings | field paths to clear (added to the update mask with the field unset), for example, --clear guardrail. | | --update-mask | strings | override the inferred update mask with exactly these paths. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 133: rpk ai llm-provider **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-llm-provider.md --- # rpk ai llm-provider > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai llm-provider latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-llm-provider page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-llm-provider.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-llm-provider.adoc description: Manage LLM providers (create, get, list, update, delete). page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Manage LLM providers (`create`, get, list, update, delete). > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai llm-provider [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 134: rpk ai mcp-server apply **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-mcp-server-apply.md --- # rpk ai mcp-server apply > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai mcp-server apply latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-mcp-server-apply page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-mcp-server-apply.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-mcp-server-apply.adoc description: "Reconcile MCP servers from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource." page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Reconcile MCP servers from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource. Fields you omit are left untouched; to clear a field, write it explicitly. Lists, maps and oneof variants replace wholesale. Fields that can only be set at creation time are immutable; changing one is an error. Manifests round-trip with `get -o yaml` for this resource. Pass `-f` - to read stdin. This does not delete resources absent from the manifests (no prune), and drift is detected only for the fields a manifest names; see `diff --help`. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai mcp-server apply [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | strings | manifest file, directory, or - for stdin (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 135: rpk ai mcp-server create **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-mcp-server-create.md --- # rpk ai mcp-server create > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai mcp-server create latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-mcp-server-create page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-mcp-server-create.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-mcp-server-create.adoc description: "Create an MCP server. Choose the backend by setting flags from one group; the group you use selects it: remote, managed." page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Create an MCP server. Choose the backend by setting flags from one group; the group you use selects it: remote, managed. Setting flags from two groups is an error. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai mcp-server create [flags] ``` ## [](#examples)Examples This section provides examples of how to use `rpk ai mcp-server create`. ```bash rpk ai mcp-server create my-mcp-server \ --remote.url https://mcp.example.com/sse \ --remote.transport sse ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --enabled | bool | Whether this server is active and discoverable. (true when set; pass --enabled=false to disable). | | --description | string | Human-readable description shown in help text and UIs. | | --code-mode | bool | Enable code mode: adds {name}_search and {name}_execute tools alongside existing tools. (true when set; pass --code-mode=false to disable). | | --data-policies | stringArray | Data policies shaping this server’s tool calls (see MCPServer.data_policies). (repeatable; protojson object; replaces the full list on update). | | --response-format | string | Output format for tool results (token optimization). (one of: jton, toon). | | --tags | stringArray | Arbitrary key/value metadata tags (see MCPServer.tags). (repeatable key=value; replaces the full map on update). (New in 0.2.33) | | --remote.url | string | Endpoint URL of the remote MCP server. (required in its group) (alias: --url). | | --remote.transport | string | MCP transport protocol. SSE for server-sent events, Streamable HTTP for newer bidirectional protocol. (one of: sse, streamable-http; required in its group) (alias: --transport). | | --remote.none | bool | None. (selects this auth mode; takes no value). | | --remote.token-passthrough | bool | Token passthrough. (selects this auth mode; takes no value). | | --remote.static-key.key-secret-ref | string | Secret store reference for the API key. (required in its group). | | --remote.static-key.header-name | string | HTTP header name for the API key. Defaults to 'Authorization'. | | --remote.service-account-oauth.client-id | string | OAuth client ID from the provider’s developer console. (required in its group). | | --remote.service-account-oauth.client-secret-ref | string | Secret store reference for the OAuth client secret. (required in its group). | | --remote.service-account-oauth.token-url | string | OAuth token endpoint URL for exchanging credentials. (required in its group). | | --remote.service-account-oauth.scopes | strings | OAuth scopes to request when obtaining tokens. (repeatable; replaces the full list on update). | | --remote.user-oauth.provider-name | string | OAuth provider that manages tokens for this server’s users. Leave empty to set OAuth up automatically from the server URL. | | --remote.user-oauth.required-scopes | strings | Minimum OAuth scopes a user’s connection must have. Insufficient scopes return a scope_upgrade_required error. (repeatable; replaces the full list on update). | | --remote.user-oauth.injection.header-name | string | HTTP header name for the token. Defaults to 'Authorization'. | | --remote.user-oauth.injection.header-prefix | string | Value prefix before the token. Defaults to 'Bearer'. Set empty for no prefix. | | --remote.user-oauth.client-id | string | OAuth client ID from the vendor console. Only for automatic setup of a server without dynamic client registration; leave empty otherwise. | | --remote.user-oauth.client-secret-ref | string | Secret-store reference for the OAuth client secret (confidential apps only). Leave empty for public PKCE clients. | | --remote.user-oauth.automatic-setup | bool | Ask the gateway to set OAuth up for this server instead of attaching an existing provider. (true when set; pass --remote.user-oauth.automatic-setup=false to disable). | | --managed.config | types | Type-specific configuration for the managed MCP server. (protojson with an "@type": a short type name (run the resource’s types command) or a full type URL). | | -f, --filename | string | manifest to create from (YAML or JSON; "-" for stdin); flags override file values. | | --dry-run | bool | print the request that would be sent (with the computed update mask) and exit without calling the server. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 136: rpk ai mcp-server delete **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-mcp-server-delete.md --- # rpk ai mcp-server delete > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai mcp-server delete latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-mcp-server-delete page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-mcp-server-delete.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-mcp-server-delete.adoc description: Delete an MCP server. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Delete an MCP server. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai mcp-server delete [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 137: rpk ai mcp-server diff **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-mcp-server-diff.md --- # rpk ai mcp-server diff > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai mcp-server diff latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-mcp-server-diff page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-mcp-server-diff.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-mcp-server-diff.adoc description: Dry-run of apply for MCP servers. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Dry-run of apply for MCP servers. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. Exits non-zero when any change is pending, so CI can gate on `no drift`. > 📝 **NOTE** > > diff proves only that the fields a manifest names match live. It does not detect resources that exist live but are absent from the manifests (no prune), nor drift in fields a manifest omits. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai mcp-server diff [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | strings | manifest file, directory, or - for stdin (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 138: rpk ai mcp-server get **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-mcp-server-get.md --- # rpk ai mcp-server get > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai mcp-server get latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-mcp-server-get page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-mcp-server-get.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-mcp-server-get.adoc description: Get an MCP server. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Get an MCP server. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai mcp-server get [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 139: rpk ai mcp-server list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-mcp-server-list.md --- # rpk ai mcp-server list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai mcp-server list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-mcp-server-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-mcp-server-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-mcp-server-list.adoc description: List MCP servers. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- List MCP servers. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai mcp-server list [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --name-contains | string | Name contains. | | --filter | string | AIP-160 filter expression (https://google.aip.dev/160). | | --page-size | int32 | Page size. | | --page-token | string | Page token. | | --order-by | string | AIP-132 order: a comma-separated list of fields, each optionally suffixed with " desc" (default ascending). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 140: rpk ai mcp-server tools call **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-mcp-server-tools-call.md --- # rpk ai mcp-server tools call > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai mcp-server tools call latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-mcp-server-tools-call page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-mcp-server-tools-call.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-mcp-server-tools-call.adoc description: Invoke a tool on an MCP server through the aigw MCP proxy. The server's /mcp/v1/ endpoint is reached with the same bearer token used by the rest of rpk ai; aigw resolves user-delegated OAuth tokens from the vault when the MCP server is configured with --user-oauth-provider. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Invoke a tool on an MCP server through the aigw MCP proxy. The server’s /mcp/v1/ endpoint is reached with the same bearer token used by the rest of `rpk ai`; aigw resolves user-delegated OAuth tokens from the vault when the MCP server is configured with `--user-oauth-provider`. Arguments passed to the tool are a JSON object supplied via `--args`. Example: ```text rpk ai mcp tools call gf-servicenow-sand2 listtablerecords \ --args '{"tableName":"incident","sysparm_limit":3}' ``` With `--code-mode` the call targets the virtual code-mode sibling endpoint (/mcp/v1/-code). That endpoint exposes search (tool catalog for the primary) and execute (runs JavaScript in a sandbox with call\_tool bound to the primary’s tools). Example: ```text rpk ai mcp tools call pg-garrett execute --code-mode \ --args '{"code":"var r = call_tool({name:\"query\", arguments:{query:\"SELECT 1\"}}); JSON.stringify(r);"}' ``` > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai mcp-server tools call [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --args | string | JSON object of tool arguments, for example, '{foo:`bar`}'. Empty means no arguments. | | --code-mode | bool | Target the virtual code-mode sibling endpoint (-code) instead of the primary. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 141: rpk ai mcp-server tools list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-mcp-server-tools-list.md --- # rpk ai mcp-server tools list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai mcp-server tools list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-mcp-server-tools-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-mcp-server-tools-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-mcp-server-tools-list.adoc description: List tools on an MCP server by calling tools/list through the aigw MCP proxy. Hits the server's /mcp/v1/<name> endpoint, so the same auth and token-vault path used by tools/call is exercised here. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- List tools on an MCP server by calling tools/list through the aigw MCP proxy. Hits the server’s /mcp/v1/ endpoint, so the same auth and token-vault path used by tools/call is exercised here. Useful for checking that a managed MCP’s tool schema loaded correctly and that a user-delegated server is reachable with the caller’s vault token. With `--code-mode` the session targets the virtual code-mode sibling endpoint (/mcp/v1/-code), which exposes the sandbox meta-tools (`search`, execute). To see the parent’s tool catalog from the sandbox, invoke the search tool explicitly: ```text rpk ai mcp tools call search --code-mode ``` > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai mcp-server tools list [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --code-mode | bool | Target the virtual code-mode sibling endpoint (-code) instead of the primary. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 142: rpk ai mcp-server tools **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-mcp-server-tools.md --- # rpk ai mcp-server tools > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai mcp-server tools latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-mcp-server-tools page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-mcp-server-tools.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-mcp-server-tools.adoc description: Interact with tools on an MCP server. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Interact with tools on an MCP server. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai mcp-server tools [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 143: rpk ai mcp-server types **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-mcp-server-types.md --- # rpk ai mcp-server types > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai mcp-server types latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-mcp-server-types page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-mcp-server-types.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-mcp-server-types.adoc description: List available managed MCP types. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- List available managed MCP types. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai mcp-server types [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 144: rpk ai mcp-server update **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-mcp-server-update.md --- # rpk ai mcp-server update > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai mcp-server update latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-mcp-server-update page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-mcp-server-update.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-mcp-server-update.adoc description: Update an MCP server. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Update an MCP server. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai mcp-server update [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --enabled | bool | Whether this server is active and discoverable. (true when set; pass --enabled=false to disable). | | --description | string | Human-readable description shown in help text and UIs. | | --code-mode | bool | Enable code mode: adds {name}_search and {name}_execute tools alongside existing tools. (true when set; pass --code-mode=false to disable). | | --data-policies | stringArray | Data policies shaping this server’s tool calls (see MCPServer.data_policies). (repeatable; protojson object; replaces the full list on update). | | --response-format | string | Output format for tool results (token optimization). (one of: jton, toon). | | --tags | stringArray | Arbitrary key/value metadata tags (see MCPServer.tags). (repeatable key=value; replaces the full map on update). (New in 0.2.33) | | --remote.url | string | Endpoint URL of the remote MCP server. (required in its group) (alias: --url). | | --remote.transport | string | MCP transport protocol. SSE for server-sent events, Streamable HTTP for newer bidirectional protocol. (one of: sse, streamable-http; required in its group) (alias: --transport). | | --remote.none | bool | None. (selects this auth mode; takes no value). | | --remote.token-passthrough | bool | Token passthrough. (selects this auth mode; takes no value). | | --remote.static-key.key-secret-ref | string | Secret store reference for the API key. (required in its group). | | --remote.static-key.header-name | string | HTTP header name for the API key. Defaults to 'Authorization'. | | --remote.service-account-oauth.client-id | string | OAuth client ID from the provider’s developer console. (required in its group). | | --remote.service-account-oauth.client-secret-ref | string | Secret store reference for the OAuth client secret. (required in its group). | | --remote.service-account-oauth.token-url | string | OAuth token endpoint URL for exchanging credentials. (required in its group). | | --remote.service-account-oauth.scopes | strings | OAuth scopes to request when obtaining tokens. (repeatable; replaces the full list on update). | | --remote.user-oauth.provider-name | string | OAuth provider that manages tokens for this server’s users. Leave empty to set OAuth up automatically from the server URL. | | --remote.user-oauth.required-scopes | strings | Minimum OAuth scopes a user’s connection must have. Insufficient scopes return a scope_upgrade_required error. (repeatable; replaces the full list on update). | | --remote.user-oauth.injection.header-name | string | HTTP header name for the token. Defaults to 'Authorization'. | | --remote.user-oauth.injection.header-prefix | string | Value prefix before the token. Defaults to 'Bearer'. Set empty for no prefix. | | --remote.user-oauth.client-id | string | OAuth client ID from the vendor console. Only for automatic setup of a server without dynamic client registration; leave empty otherwise. | | --remote.user-oauth.client-secret-ref | string | Secret-store reference for the OAuth client secret (confidential apps only). Leave empty for public PKCE clients. | | --remote.user-oauth.automatic-setup | bool | Ask the gateway to set OAuth up for this server instead of attaching an existing provider. (true when set; pass --remote.user-oauth.automatic-setup=false to disable). | | --managed.config | types | Type-specific configuration for the managed MCP server. (protojson with an "@type": a short type name (run the resource’s types command) or a full type URL). | | -f, --filename | string | manifest to update from (YAML or JSON; "-" for stdin); flags override file values. | | --dry-run | bool | print the request that would be sent (with the computed update mask) and exit without calling the server. | | --clear | strings | field paths to clear (added to the update mask with the field unset), for example, --clear guardrail. | | --update-mask | strings | override the inferred update mask with exactly these paths. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 145: rpk ai mcp-server **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-mcp-server.md --- # rpk ai mcp-server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai mcp-server latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-mcp-server page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-mcp-server.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-mcp-server.adoc description: Manage MCP servers (create, get, list, update, delete). page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Manage MCP servers (`create`, get, list, update, delete). > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai mcp-server [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 146: rpk ai model get **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-model-get.md --- # rpk ai model get > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai model get latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-model-get page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-model-get.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-model-get.adoc description: Get model details from the catalog. page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- Get model details from the catalog. ## [](#usage)Usage ```bash rpk ai model get [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --provider-type | string | provider type (for disambiguation when a model is exposed by multiple providers). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 147: rpk ai model list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-model-list.md --- # rpk ai model list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai model list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-model-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-model-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-model-list.adoc description: List available models in the catalog. page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- List available models in the catalog. ## [](#usage)Usage ```bash rpk ai model list [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --provider-type | string | filter by provider type (openai, openai-compatible, anthropic, google, bedrock). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 148: rpk ai model **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-model.md --- # rpk ai model > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai model latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-model page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-model.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-model.adoc description: Discover the models the Redpanda AI gateway exposes. The catalog is read-only; model list and model get are the only verbs. page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- Discover the models the Redpanda AI gateway exposes. The catalog is read-only; `model list` and `model get` are the only verbs. The catalog is populated from each LLM provider’s metadata plus any extras the operator has pinned to a tenant. Aliases: `models`, `m`. The catalog is read-only. The catalog is populated from each LLM provider’s metadata plus any extras the operator has pinned to a tenant. ## [](#usage)Usage ```bash rpk ai model [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 149: rpk ai oauth-client apply **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-apply.md --- # rpk ai oauth-client apply > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client apply latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-apply page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-apply.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-apply.adoc description: "Reconcile OAuth clients from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource." page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Reconcile OAuth clients from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource. Fields you omit are left untouched; to clear a field, write it explicitly. Lists, maps and oneof variants replace wholesale. Fields that can only be set at creation time are immutable; changing one is an error. Manifests round-trip with `get -o yaml` for this resource. Pass `-f` - to read stdin. This does not delete resources absent from the manifests (no prune), and drift is detected only for the fields a manifest names; see `diff --help`. ## [](#usage)Usage ```bash rpk ai oauth-client apply [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | strings | manifest file, directory, or - for stdin (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 150: rpk ai oauth-client create **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-create.md --- # rpk ai oauth-client create > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client create latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-create page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-create.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-create.adoc description: Register an OAuth client with the AI gateway. The generated client secret is printed once and cannot be retrieved afterward. page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- Register an OAuth client with the AI gateway. The generated client secret is printed once and cannot be retrieved afterward. Save it immediately in a secret manager. ## [](#usage)Usage ```bash rpk ai oauth-client create [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --display-name | string | Shown on the user consent page. Use the external tool’s brand name. | | --logo-uri | string | Logo URL displayed alongside the client name on the consent page. HTTPS only. | | --redirect-uris | strings | Allowed redirect URIs (exact match, RFC 3986 normalized). No query or fragment components. (repeatable; replaces the full list on update). | | --allowed-resources | strings | MCP URLs this client may request tokens for. Use "*" to allow any MCP on this gateway. (repeatable; replaces the full list on update). | | --grant-types | strings | OAuth grant types this client may use. Authorization Code + Refresh Token is the standard combination. (one of: oauth-client-grant-type-authorization-code, oauth-client-grant-type-refresh-token; repeatable; replaces the full list on update). | | --token-endpoint-auth-method | string | How the client authenticates to the token endpoint. Phase 1 supports client_secret_basic and client_secret_post. (one of: oauth-client-token-endpoint-auth-method-client-secret-basic, oauth-client-token-endpoint-auth-method-client-secret-post, oauth-client-token-endpoint-auth-method-none). | | --pkce-required | bool | Require PKCE (RFC 7636) on authorization requests. Strongly recommended and enforced by default. (true when set; pass --pkce-required=false to disable). | | --enabled | bool | Whether this client may request new tokens. Disabled clients are rejected at the authorize endpoint. (true when set; pass --enabled=false to disable). | | --tags | stringArray | Tags. (repeatable key=value; replaces the full map on update). (New in 0.2.33) | | -f, --filename | string | manifest to create from (YAML or JSON; "-" for stdin); flags override file values. | | --dry-run | bool | print the request that would be sent (with the computed update mask) and exit without calling the server. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 151: rpk ai oauth-client dcr get **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-dcr-get.md --- # rpk ai oauth-client dcr get > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client dcr get latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-dcr-get page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-dcr-get.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-dcr-get.adoc description: Show the Dynamic Client Registration (DCR) settings for the current tenant, including whether DCR is enabled and the configured admission mode. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Show the Dynamic Client Registration (DCR) settings for the current tenant, including whether DCR is enabled and the configured admission mode. ## [](#usage)Usage ```bash rpk ai oauth-client dcr get [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 152: rpk ai oauth-client dcr iat list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat-list.md --- # rpk ai oauth-client dcr iat list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client dcr iat list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat-list.adoc description: List Initial Access Tokens (plaintext is never shown). page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- List Initial Access Tokens (plaintext is never shown). ## [](#usage)Usage ```bash rpk ai oauth-client dcr iat list [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 153: rpk ai oauth-client dcr iat mint **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat-mint.md --- # rpk ai oauth-client dcr iat mint > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client dcr iat mint latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat-mint page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat-mint.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat-mint.adoc description: Mint a one-shot Initial Access Token for use at the OAuth client registration endpoint. The token plaintext is printed once and only a hash is stored. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Mint a one-shot Initial Access Token for use at the OAuth client registration endpoint. The token plaintext is printed once and only a hash is stored. ## [](#usage)Usage ```bash rpk ai oauth-client dcr iat mint [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --label | string | human-readable label shown in the IAT list (recommended). | | --ttl | duration | validity window, for example, 1h, 24h, 168h (0 = server default of 1h; ceiling 720h). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 154: rpk ai oauth-client dcr iat revoke **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat-revoke.md --- # rpk ai oauth-client dcr iat revoke > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client dcr iat revoke latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat-revoke page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat-revoke.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat-revoke.adoc description: "Revoke an unconsumed Initial Access Token so it can no longer be exchanged at the registration endpoint. Idempotent: revoking an already-revoked or consumed token returns 0." page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Revoke an unconsumed Initial Access Token so it can no longer be exchanged at the registration endpoint. Idempotent: revoking an already-revoked or consumed token returns 0. ## [](#usage)Usage ```bash rpk ai oauth-client dcr iat revoke [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 155: rpk ai oauth-client dcr iat **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat.md --- # rpk ai oauth-client dcr iat > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client dcr iat latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-dcr-iat.adoc description: "Manage Initial Access Tokens (IATs): one-shot bearer credentials a caller presents to the public registration endpoint when the tenant's admission mode is initial-access-token. The plaintext is printed exactly once on mint; only a hash is stored." page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Manage Initial Access Tokens (IATs): one-shot bearer credentials a caller presents to the public registration endpoint when the tenant’s admission mode is initial-access-token. The plaintext is printed exactly once on mint; only a hash is stored. ## [](#usage)Usage ```bash rpk ai oauth-client dcr iat [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 156: rpk ai oauth-client dcr update **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-dcr-update.md --- # rpk ai oauth-client dcr update > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client dcr update latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-dcr-update page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-dcr-update.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-dcr-update.adoc description: Update the tenant's DCR settings. Only the flags you pass change; everything else keeps its current value (the CLI reads the current settings and writes back the merged result). page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Update the tenant’s DCR settings. Only the flags you pass change; everything else keeps its current value (the CLI reads the current settings and writes back the merged result). Enable open self-registration: ```text rpk ai oauth-client dcr update --enabled --admission-mode open ``` Require admin-minted Initial Access Tokens instead: ```text rpk ai oauth-client dcr update --admission-mode initial-access-token ``` Turn the endpoint off again: ```text rpk ai oauth-client dcr update --enabled=false ``` ## [](#usage)Usage ```bash rpk ai oauth-client dcr update [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --admission-mode | string | how callers are admitted: open, initial-access-token. | | --allowed-resource | strings | MCP URL every DCR-issued client may request tokens for; "*" = any. repeatable. | | --client-cap | int32 | max concurrent DCR-issued clients (0 = runtime default). | | --enabled | bool | whether the public registration endpoint accepts requests. | | --inactive-ttl-days | int32 | days of inactivity before a DCR client is removed (0 = never). | | --rate-per-hour | int32 | max registrations per hour (0 = runtime default). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 157: rpk ai oauth-client dcr **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-dcr.md --- # rpk ai oauth-client dcr > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client dcr latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-dcr page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-dcr.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-dcr.adoc description: Manage Dynamic Client Registration (DCR) settings for the AI gateway. DCR allows OAuth clients to register themselves programmatically at a public endpoint. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Manage Dynamic Client Registration (DCR) settings for the AI gateway. DCR allows OAuth clients to register themselves programmatically at a public endpoint. When DCR is enabled, spec-conformant MCP clients (such as Claude and Cursor) self-register at the public `/oauth/idp/register` endpoint with no admin pre-provisioning. Admission is governed by the mode: - `open`: anyone may register (rate limit and client cap still apply) - `initial-access-token`: callers must present an admin-minted one-shot bearer token - `software-statement`: reserved, not yet supported DCR is disabled per tenant by default. The gateway operator must also enable the global `ingress.idp.dcr.global_enabled` flag. ## [](#usage)Usage ```bash rpk ai oauth-client dcr [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 158: rpk ai oauth-client delete **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-delete.md --- # rpk ai oauth-client delete > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client delete latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-delete page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-delete.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-delete.adoc description: Delete an OAuth client. page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- Delete an OAuth client. ## [](#usage)Usage ```bash rpk ai oauth-client delete [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 159: rpk ai oauth-client diff **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-diff.md --- # rpk ai oauth-client diff > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client diff latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-diff page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-diff.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-diff.adoc description: Dry-run of apply for OAuth clients. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Dry-run of apply for OAuth clients. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. Exits non-zero when any change is pending, so CI can gate on `no drift`. > 📝 **NOTE** > > diff proves only that the fields a manifest names match live. It does not detect resources that exist live but are absent from the manifests (no prune), nor drift in fields a manifest omits. ## [](#usage)Usage ```bash rpk ai oauth-client diff [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | strings | manifest file, directory, or - for stdin (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 160: rpk ai oauth-client get **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-get.md --- # rpk ai oauth-client get > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client get latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-get page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-get.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-get.adoc description: Get an OAuth client. page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- Get an OAuth client. ## [](#usage)Usage ```bash rpk ai oauth-client get [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 161: rpk ai oauth-client list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-list.md --- # rpk ai oauth-client list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-list.adoc description: List OAuth clients. page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- List OAuth clients. ## [](#usage)Usage ```bash rpk ai oauth-client list [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --name-contains | string | Name contains. | | --filter | string | AIP-160 filter expression (https://google.aip.dev/160). | | --page-size | int32 | Page size. | | --page-token | string | Page token. | | --order-by | string | AIP-132 order: a comma-separated list of fields, each optionally suffixed with " desc" (default ascending). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 162: rpk ai oauth-client revoke-tokens **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-revoke-tokens.md --- # rpk ai oauth-client revoke-tokens > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client revoke-tokens latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-revoke-tokens page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-revoke-tokens.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-revoke-tokens.adoc description: Revoke every refresh token the AI gateway has issued for the named OAuth client. Forces all users who connected this client to sign in again. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Revoke every refresh token the AI gateway has issued for the named OAuth client. Forces all users who connected this client to sign in again. Already-issued short-lived access tokens may continue working until natural expiry (typically minutes). This command is idempotent: running it again returns 0. ## [](#usage)Usage ```bash rpk ai oauth-client revoke-tokens [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 163: rpk ai oauth-client update **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client-update.md --- # rpk ai oauth-client update > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client update latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client-update page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client-update.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client-update.adoc description: Update an OAuth client. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Update an OAuth client. > 📝 **NOTE** > > This command was introduced in ai version 0.2.28. ## [](#usage)Usage ```bash rpk ai oauth-client update [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --display-name | string | Shown on the user consent page. Use the external tool’s brand name. | | --logo-uri | string | Logo URL displayed alongside the client name on the consent page. HTTPS only. | | --redirect-uris | strings | Allowed redirect URIs (exact match, RFC 3986 normalized). No query or fragment components. (repeatable; replaces the full list on update). | | --allowed-resources | strings | MCP URLs this client may request tokens for. Use "*" to allow any MCP on this gateway. (repeatable; replaces the full list on update). | | --grant-types | strings | OAuth grant types this client may use. Authorization Code + Refresh Token is the standard combination. (one of: oauth-client-grant-type-authorization-code, oauth-client-grant-type-refresh-token; repeatable; replaces the full list on update). | | --token-endpoint-auth-method | string | How the client authenticates to the token endpoint. Phase 1 supports client_secret_basic and client_secret_post. (one of: oauth-client-token-endpoint-auth-method-client-secret-basic, oauth-client-token-endpoint-auth-method-client-secret-post, oauth-client-token-endpoint-auth-method-none). | | --pkce-required | bool | Require PKCE (RFC 7636) on authorization requests. Strongly recommended and enforced by default. (true when set; pass --pkce-required=false to disable). | | --enabled | bool | Whether this client may request new tokens. Disabled clients are rejected at the authorize endpoint. (true when set; pass --enabled=false to disable). | | --tags | stringArray | Tags. (repeatable key=value; replaces the full map on update). (New in 0.2.33) | | -f, --filename | string | manifest to update from (YAML or JSON; "-" for stdin); flags override file values. | | --dry-run | bool | print the request that would be sent (with the computed update mask) and exit without calling the server. | | --clear | strings | field paths to clear (added to the update mask with the field unset), for example, --clear guardrail. | | --update-mask | strings | override the inferred update mask with exactly these paths. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 164: rpk ai oauth-client **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-client.md --- # rpk ai oauth-client > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-client latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-client page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-client.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-client.adoc description: Manage OAuth clients registered with the AI gateway's OAuth Authorization Server. An OAuth client is an external tool (such as Claude AI, ChatGPT, or Cursor) that requests access tokens for an MCP server. page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- Manage OAuth clients registered with the AI gateway’s OAuth Authorization Server. An OAuth client is an external tool (such as Claude AI, ChatGPT, or Cursor) that requests access tokens for an MCP server. ## [](#usage)Usage ```bash rpk ai oauth-client [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 165: rpk ai oauth-provider apply **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-provider-apply.md --- # rpk ai oauth-provider apply > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-provider apply latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-provider-apply page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-provider-apply.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-provider-apply.adoc description: "Reconcile OAuth providers from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource." page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Reconcile OAuth providers from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource. Fields you omit are left untouched; to clear a field, write it explicitly. Lists, maps and oneof variants replace wholesale. Fields that can only be set at creation time are immutable; changing one is an error. Manifests round-trip with `get -o yaml` for this resource. Pass `-f` - to read stdin. This does not delete resources absent from the manifests (no prune), and drift is detected only for the fields a manifest names; see `diff --help`. ## [](#usage)Usage ```bash rpk ai oauth-provider apply [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | strings | manifest file, directory, or - for stdin (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 166: rpk ai oauth-provider create **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-provider-create.md --- # rpk ai oauth-provider create > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-provider create latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-provider-create page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-provider-create.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-provider-create.adoc description: Create an OAuth provider. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Create an OAuth provider. ## [](#usage)Usage ```bash rpk ai oauth-provider create [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --display-name | string | Shown to users when selecting this provider. Use the provider’s brand name. | | --authorization-endpoint | string | The URL where users are redirected to grant consent. Found in your provider’s OAuth documentation. | | --token-endpoint | string | The URL where the gateway exchanges authorization codes for access tokens. | | --revocation-endpoint | string | Optional. Called when a user disconnects. Not all providers support token revocation. | | --client-id | string | OAuth client ID from the provider’s developer console. Omit when using register_from_url (it is discovered and registered automatically). | | --client-secret-ref | string | Reference to a secret stored in the secret store. Not required for public clients using PKCE. | | --scopes | strings | OAuth scopes determine what data and actions the token grants access to. Set to the union of all scopes needed across MCP servers to avoid re-consent. (repeatable; replaces the full list on update). | | --grant-types | strings | Select at least one grant type. Browser Consent is the standard OAuth 2.0 flow. Token Exchange enables server-to-server delegation. (one of: oauth-grant-type-browser-consent, oauth-grant-type-token-exchange; repeatable; replaces the full list on update). | | --pkce-required | bool | Proof Key for Code Exchange adds a challenge to the authorization flow, preventing code interception attacks. Recommended for all providers. (true when set; pass --pkce-required=false to disable). | | --token-endpoint-auth-method | string | How the gateway authenticates when exchanging codes for tokens. Check your provider’s documentation for the supported method. (one of: oauth-token-endpoint-auth-method-client-secret-basic, oauth-token-endpoint-auth-method-client-secret-post, oauth-token-endpoint-auth-method-none). | | --extra-auth-params | stringArray | Additional query parameters appended to the authorization URL. (repeatable key=value; replaces the full map on update). | | --extra-token-params | stringArray | Additional parameters sent in the token exchange request body. (repeatable key=value; replaces the full map on update). | | --enabled | bool | Whether this provider accepts new connections. (true when set; pass --enabled=false to disable). | | --register-from-url | string | Remote MCP server URL to auto-detect OAuth from. The gateway discovers endpoints and registers a client automatically. | | --tags | stringArray | Tags. (repeatable key=value; replaces the full map on update). (New in 0.2.33) | | -f, --filename | string | manifest to create from (YAML or JSON; "-" for stdin); flags override file values. | | --dry-run | bool | print the request that would be sent (with the computed update mask) and exit without calling the server. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 167: rpk ai oauth-provider delete **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-provider-delete.md --- # rpk ai oauth-provider delete > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-provider delete latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-provider-delete page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-provider-delete.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-provider-delete.adoc description: Delete an OAuth provider. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Delete an OAuth provider. ## [](#usage)Usage ```bash rpk ai oauth-provider delete [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 168: rpk ai oauth-provider diff **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-provider-diff.md --- # rpk ai oauth-provider diff > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-provider diff latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-provider-diff page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-provider-diff.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-provider-diff.adoc description: Dry-run of apply for OAuth providers. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Dry-run of apply for OAuth providers. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. Exits non-zero when any change is pending, so CI can gate on `no drift`. > 📝 **NOTE** > > diff proves only that the fields a manifest names match live. It does not detect resources that exist live but are absent from the manifests (no prune), nor drift in fields a manifest omits. ## [](#usage)Usage ```bash rpk ai oauth-provider diff [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | strings | manifest file, directory, or - for stdin (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 169: rpk ai oauth-provider get **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-provider-get.md --- # rpk ai oauth-provider get > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-provider get latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-provider-get page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-provider-get.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-provider-get.adoc description: Get an OAuth provider. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Get an OAuth provider. ## [](#usage)Usage ```bash rpk ai oauth-provider get [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 170: rpk ai oauth-provider list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-provider-list.md --- # rpk ai oauth-provider list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-provider list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-provider-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-provider-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-provider-list.adoc description: List OAuth providers. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- List OAuth providers. ## [](#usage)Usage ```bash rpk ai oauth-provider list [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --name-contains | string | Name contains. | | --filter | string | AIP-160 filter expression (https://google.aip.dev/160). | | --page-size | int32 | Page size. | | --page-token | string | Page token. | | --order-by | string | AIP-132 order: a comma-separated list of fields, each optionally suffixed with " desc" (default ascending). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 171: rpk ai oauth-provider update **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-provider-update.md --- # rpk ai oauth-provider update > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-provider update latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-provider-update page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-provider-update.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-provider-update.adoc description: Update an OAuth provider. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Update an OAuth provider. ## [](#usage)Usage ```bash rpk ai oauth-provider update [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --display-name | string | Shown to users when selecting this provider. Use the provider’s brand name. | | --authorization-endpoint | string | The URL where users are redirected to grant consent. Found in your provider’s OAuth documentation. | | --token-endpoint | string | The URL where the gateway exchanges authorization codes for access tokens. | | --revocation-endpoint | string | Optional. Called when a user disconnects. Not all providers support token revocation. | | --client-secret-ref | string | Reference to a secret stored in the secret store. Not required for public clients using PKCE. | | --scopes | strings | OAuth scopes determine what data and actions the token grants access to. Set to the union of all scopes needed across MCP servers to avoid re-consent. (repeatable; replaces the full list on update). | | --grant-types | strings | Select at least one grant type. Browser Consent is the standard OAuth 2.0 flow. Token Exchange enables server-to-server delegation. (one of: oauth-grant-type-browser-consent, oauth-grant-type-token-exchange; repeatable; replaces the full list on update). | | --pkce-required | bool | Proof Key for Code Exchange adds a challenge to the authorization flow, preventing code interception attacks. Recommended for all providers. (true when set; pass --pkce-required=false to disable). | | --token-endpoint-auth-method | string | How the gateway authenticates when exchanging codes for tokens. Check your provider’s documentation for the supported method. (one of: oauth-token-endpoint-auth-method-client-secret-basic, oauth-token-endpoint-auth-method-client-secret-post, oauth-token-endpoint-auth-method-none). | | --extra-auth-params | stringArray | Additional query parameters appended to the authorization URL. (repeatable key=value; replaces the full map on update). | | --extra-token-params | stringArray | Additional parameters sent in the token exchange request body. (repeatable key=value; replaces the full map on update). | | --enabled | bool | Whether this provider accepts new connections. (true when set; pass --enabled=false to disable). | | --tags | stringArray | Tags. (repeatable key=value; replaces the full map on update). (New in 0.2.33) | | -f, --filename | string | manifest to update from (YAML or JSON; "-" for stdin); flags override file values. | | --dry-run | bool | print the request that would be sent (with the computed update mask) and exit without calling the server. | | --clear | strings | field paths to clear (added to the update mask with the field unset), for example, --clear guardrail. | | --update-mask | strings | override the inferred update mask with exactly these paths. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 172: rpk ai oauth-provider **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-oauth-provider.md --- # rpk ai oauth-provider > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai oauth-provider latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-oauth-provider page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-oauth-provider.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-oauth-provider.adoc description: Manage OAuth authorization-server configurations registered with the Redpanda AI gateway. OAuth providers describe third-party authorization servers that user-facing MCP servers can authenticate against via the device-consent flow. page-git-created-date: "2026-07-02" page-git-modified-date: "2026-08-06" --- Manage OAuth authorization-server configurations registered with the Redpanda AI gateway. OAuth providers describe third-party authorization servers that user-facing MCP servers can authenticate against via the device-consent flow. ## [](#usage)Usage ```bash rpk ai oauth-provider [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 173: rpk ai policy apply **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-policy-apply.md --- # rpk ai policy apply > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai policy apply latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-policy-apply page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-policy-apply.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-policy-apply.adoc description: "Reconcile policies from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource." page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Reconcile policies from one or more YAML manifests. For each manifest: create the resource if absent, otherwise update only the fields that are present in the manifest AND differ from the live resource. Fields you omit are left untouched; to clear a field, write it explicitly. Lists, maps and oneof variants replace wholesale. Fields that can only be set at creation time are immutable; changing one is an error. Manifests round-trip with `get -o yaml` for this resource. Pass `-f` - to read stdin. This does not delete resources absent from the manifests (no prune), and drift is detected only for the fields a manifest names; see `diff --help`. > 📝 **NOTE** > > This command was introduced in ai version 0.2.26. ## [](#usage)Usage ```bash rpk ai policy apply [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | strings | manifest file, directory, or - for stdin (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 174: rpk ai policy create **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-policy-create.md --- # rpk ai policy create > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai policy create latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-policy-create page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-policy-create.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-policy-create.adoc description: "Create a Cedar authorization policy: the allow/deny gate that decides WHETHER a principal may call a tool." page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Create a Cedar authorization policy: the allow/deny gate that decides WHETHER a principal may call a tool. The Cedar body must contain exactly one statement; scope the resource to your MCP server, for example: ```text permit(principal, action == Action::"dataplane_adp_mcpserver_tools_call", resource == McpServer::"servicenow"); ``` Data shaping (`masking`, dropping, row filtering) is NOT configured here. It lives on the MCP server’s data policies (`rpk` ai mcp …​), not in Cedar text; the @redact\_mask / @redact\_drop annotations are gone. > 📝 **NOTE** > > This command was introduced in ai version 0.2.26. ## [](#usage)Usage ```bash rpk ai policy create [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --cedar | string | inline Cedar policy text. Mutually exclusive with --cedar-file. | | --cedar-file | string | path to a file containing the Cedar policy text (.cedar). Mutually exclusive with --cedar. | | --description | string | human-readable description. | | --display-name | string | human-readable display name. | | --name | string | policy id (required; lowercase letters, numbers, hyphens). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 175: rpk ai policy delete **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-policy-delete.md --- # rpk ai policy delete > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai policy delete latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-policy-delete page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-policy-delete.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-policy-delete.adoc description: Delete a policy. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Delete a policy. > 📝 **NOTE** > > This command was introduced in ai version 0.2.26. ## [](#usage)Usage ```bash rpk ai policy delete [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --etag | string | optional etag for optimistic concurrency; delete fails if it no longer matches. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 176: rpk ai policy diff **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-policy-diff.md --- # rpk ai policy diff > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai policy diff latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-policy-diff page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-policy-diff.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-policy-diff.adoc description: Dry-run of apply for policies. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Dry-run of apply for policies. Prints, per manifest, whether apply would create, update (and which fields), or leave the resource unchanged. Exits non-zero when any change is pending, so CI can gate on `no drift`. > 📝 **NOTE** > > diff proves only that the fields a manifest names match live. It does not detect resources that exist live but are absent from the manifests (no prune), nor drift in fields a manifest omits. > 📝 **NOTE** > > This command was introduced in ai version 0.2.26. ## [](#usage)Usage ```bash rpk ai policy diff [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | strings | manifest file, directory, or - for stdin (repeatable). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 177: rpk ai policy get **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-policy-get.md --- # rpk ai policy get > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai policy get latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-policy-get page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-policy-get.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-policy-get.adoc description: Get a policy. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Get a policy. > 📝 **NOTE** > > This command was introduced in ai version 0.2.26. ## [](#usage)Usage ```bash rpk ai policy get [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 178: rpk ai policy list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-policy-list.md --- # rpk ai policy list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai policy list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-policy-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-policy-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-policy-list.adoc description: List policies. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- List policies. > 📝 **NOTE** > > This command was introduced in ai version 0.2.26. ## [](#usage)Usage ```bash rpk ai policy list [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 179: rpk ai policy update **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-policy-update.md --- # rpk ai policy update > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai policy update latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-policy-update page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-policy-update.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-policy-update.adoc description: Update a policy in place. Only the flags you pass are written; the field mask is built from the flags actually set, so omitted fields are left untouched. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Update a policy in place. Only the flags you pass are written; the field mask is built from the flags actually set, so omitted fields are left untouched. > 📝 **NOTE** > > This command was introduced in ai version 0.2.26. ## [](#usage)Usage ```bash rpk ai policy update [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --cedar | string | inline Cedar policy text. Mutually exclusive with --cedar-file. | | --cedar-file | string | path to a file containing the Cedar policy text (.cedar). Mutually exclusive with --cedar. | | --description | string | new description. | | --display-name | string | new display name. | | --etag | string | optional etag for optimistic concurrency. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 180: rpk ai policy **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-policy.md --- # rpk ai policy > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai policy latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-policy page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-policy.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-policy.adoc description: Manage Cedar authorization policies (create, get, list, update, delete). page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Manage Cedar authorization policies (`create`, get, list, update, delete). > 📝 **NOTE** > > This command was introduced in ai version 0.2.26. ## [](#usage)Usage ```bash rpk ai policy [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 181: rpk ai run claude **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-run-claude.md --- # rpk ai run claude > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai run claude latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-run-claude page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-run-claude.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-run-claude.adoc description: Launch Anthropic's Claude Code CLI with its model traffic routed through the Redpanda AI gateway for the current rpk ai environment. rpk ai points ANTHROPIC_BASE_URL at the gateway's Anthropic Messages endpoint for the chosen provider and wires the gateway auth for the life of the session. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Launch Anthropic’s Claude Code CLI with its model traffic routed through the Redpanda AI gateway for the current `rpk` ai environment. `rpk` ai points ANTHROPIC\_BASE\_URL at the gateway’s Anthropic Messages endpoint for the chosen provider and wires the gateway auth for the life of the session. No token is ever written to disk. Both auth modes run in your REAL Claude Code config home, so your workspace trust, onboarding, theme, and MCP servers all apply. `rpk` ai writes nothing into `~/.claude` in either mode: - managed (api key): the gateway apiKeyHelper (`rpk ai auth token`, which Claude Code re-runs to refresh the bearer; aigw injects the upstream Anthropic key) is passed via `claude --settings` as a JSON string; off disk, merged on top of your settings, your `~/.claude/settings.json` untouched. - passthrough (enterprise/Max subscription): your existing subscription login (stored under your config home) is used. `rpk` ai only sets the gateway base URL and the X-Redpanda-Cloud-Token header (minted fresh at launch) in the environment; your subscription OAuth flows through aigw to Anthropic untouched. Pass `--claude-config-dir` to run against an isolated config home instead of your real one (`rpk` ai still never writes into it). In passthrough mode the X-Redpanda-Cloud-Token gateway JWT is set in the launched process environment, so Claude Code’s tool subprocesses (Bash, hooks, MCP) inherit it; the same Redpanda Cloud token any process running as you can already mint with `rpk ai auth token`, and Claude Code has no documented mechanism to scrub it from those subprocesses. Because passthrough uses your real config home, any auth configured in your `~/.claude/settings.json` (an apiKeyHelper, or env.ANTHROPIC\_AUTH\_TOKEN) still applies and outranks the subscription OAuth aigw needs to relay; `rpk` ai scrubs only the inherited shell env, not your on-disk settings. Anthropic and Bedrock providers are supported. A bedrock provider launches Claude Code in its native Bedrock mode pointed at the same gateway prefix; aigw signs the upstream call with the provider’s AWS credentials (SigV4), so no AWS keys ever reach your machine and the managed apiKeyHelper auth works exactly as above (passthrough does not apply; there is no Bedrock analog of a Claude subscription). Pass `-m` an inference-profile id from the provider’s model allowlist (Bedrock Anthropic models 4.6+ carry a us./eu./apac./global. prefix). Claude Code’s background (small/fast) model defaults to a Haiku-class inference profile in Bedrock mode; if the provider\`s allowlist doesn\`t include it, export ANTHROPIC\_SMALL\_FAST\_MODEL with an allowlisted id. Pass Claude Code’s own flags after a literal --: ```text rpk ai run claude -L anthropic -m claude-sonnet-4-6 -- --permission-mode plan rpk ai run claude -L bedrock -m us.anthropic.claude-sonnet-4-6 -- -p "hi" ``` ## [](#usage)Usage ```bash rpk ai run claude [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --bedrock | bool | force bedrock mode. Only needed when you have invoke-only access and rpk ai can’t read the provider to detect its type; when the provider can be read, its own type wins. | | --claude-config-dir | string | run against this CLAUDE_CONFIG_DIR instead of your real/inherited config home (rpk ai never writes into it; the managed apiKeyHelper rides in --settings). Default: your real home, so trust/onboarding/theme/MCP all apply. | | -L, --llmprovider | string | aigw LLM provider name to route through (an anthropic or bedrock provider). | | -m, --model | string | model id to use (must be in the provider’s allowlist; for bedrock providers an inference-profile id like us.anthropic.claude-sonnet-4-6); omit to let Claude Code pick its default. | | --passthrough | bool | force passthrough (enterprise/subscription) auth mode. Only needed when you have invoke-only access and rpk ai can’t read the provider to detect the mode; when the provider can be read, its own setting wins. | | --print-settings | bool | print the generated Claude Code settings.json plus launch env, then exit (no claude needed; the provider type/mode resolve via a best-effort gateway lookup; offline the dump falls back to the managed anthropic shape, or bedrock with --bedrock). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 182: rpk ai run codex **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-run-codex.md --- # rpk ai run codex > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai run codex latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-run-codex page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-run-codex.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-run-codex.adoc description: Launch the OpenAI Codex CLI with its model traffic routed through the Redpanda AI gateway for the current rpk ai environment. rpk ai generates a throwaway Codex config in a temporary CODEX_HOME, points it at the gateway's OpenAI-compatible Responses endpoint for the chosen provider, and wires Codex's bearer to rpai auth token so it refreshes itself for the life of the session. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Launch the OpenAI Codex CLI with its model traffic routed through the Redpanda AI gateway for the current `rpk` ai environment. `rpk` ai generates a throwaway Codex config in a temporary CODEX\_HOME, points it at the gateway’s OpenAI-compatible Responses endpoint for the chosen provider, and wires Codex’s bearer to `rpk ai auth token` so it refreshes itself for the life of the session. Your own `~/.codex` config is never read or modified, and no token is written to disk. The launch directory is auto-trusted under a workspace-write sandbox (approval\_policy=on-request) so the fresh CODEX\_HOME doesn’t prompt for trust on every run; pass `--no-auto-trust` to keep Codex’s normal first-run trust prompt. Only openai / openai\_compatible providers are supported (Codex speaks the OpenAI Responses API). Pass Codex’s own flags after a literal --: ```text rpk ai run codex -L openai -m gpt-5.3-codex -e high -- --ask-for-approval never ``` ## [](#usage)Usage ```bash rpk ai run codex [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --codex-home | string | persistent CODEX_HOME dir (default: a throwaway temp dir); its config.toml is regenerated each run and the dir is tightened to 0700; your real ~/.codex is refused. | | -e, --effort | string | model reasoning effort: minimal|low|medium|high (omit to let Codex use its default). | | -L, --llmprovider | string | aigw LLM provider name to route through (must be openai/openai_compatible). | | -m, --model | string | model id to use (must be in the provider’s allowlist); omit to let Codex pick its default. | | --no-auto-trust | bool | do not pre-trust the launch directory; let Codex show its normal first-run trust prompt instead (default: the launch dir is auto-trusted under a workspace-write sandbox). | | --print-config | bool | print the generated Codex config.toml and exit (no gateway call, no codex needed). | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 183: rpk ai run **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-run.md --- # rpk ai run > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai run latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-run page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-run.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-run.adoc description: Launch a third-party coding agent configured to send its model traffic through the Redpanda AI gateway for the current environment, reusing `rpk ai`'s login and auto-refreshing token. page-git-created-date: "2026-06-25" page-git-modified-date: "2026-08-06" --- Launch a third-party coding agent configured to send its model traffic through the Redpanda AI gateway for the current environment, reusing \`rpk ai’s login and auto-refreshing token. ## [](#usage)Usage ```bash rpk ai run [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 184: rpk ai uninstall **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-uninstall.md --- # rpk ai uninstall > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai uninstall latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-uninstall page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-uninstall.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-uninstall.adoc description: Uninstall the Redpanda AI CLI. page-git-created-date: "2026-05-11" page-git-modified-date: "2026-08-06" --- Uninstall the Redpanda AI CLI. ## [](#usage)Usage ```bash rpk ai uninstall [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 185: rpk ai upgrade **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-upgrade.md --- # rpk ai upgrade > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai upgrade latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-upgrade page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-upgrade.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-upgrade.adoc description: Upgrade to the latest Redpanda AI CLI version. page-git-created-date: "2026-05-11" page-git-modified-date: "2026-08-06" --- Upgrade to the latest Redpanda AI CLI version. ## [](#usage)Usage ```bash rpk ai upgrade [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --no-confirm | bool | Disable confirmation prompt for major version upgrades. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 186: rpk ai version **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai-version.md --- # rpk ai version > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai version latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai-version page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai-version.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai-version.adoc description: Print rpk ai version and commit. page-git-created-date: "2026-05-27" page-git-modified-date: "2026-08-06" --- Print `rpk ai version` and commit. ## [](#usage)Usage ```bash rpk ai version [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 187: rpk ai **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai.md --- # rpk ai > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk ai latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-ai/rpk-ai page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-ai/rpk-ai.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-ai/rpk-ai.adoc description: Manage the Redpanda AI Gateway. page-git-created-date: "2026-05-11" page-git-modified-date: "2026-08-06" --- > 📝 **NOTE** > > The `rpk ai` commands require an Agentic Data Plane cluster. For more information, see [Run agents on all your data, safely.](https://docs.redpanda.com/agentic-data-plane/home/). Manage the Redpanda AI Gateway. ## [](#usage)Usage ```bash rpk ai [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 188: rpk profile clear **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-clear.md --- # rpk profile clear > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile clear latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-clear page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-clear.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-clear.adoc description: Clear the current profile. This command clears the current profile, which can be useful to unset a production cluster profile. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Clear the current profile. This command clears the current profile, which can be useful to unset a production cluster profile. ## [](#usage)Usage ```bash rpk profile clear [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 189: rpk profile create **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-create.md --- # rpk profile create > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile create latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-create page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-create.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-create.adoc description: Create a new rpk profile with connection settings for a Redpanda cluster. There are multiple ways to create a profile. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Create a new `rpk` profile with connection settings for a Redpanda cluster. There are multiple ways to create a profile. A name must be provided if not using `--from-cloud` or `--from-rpk-container`. - You can use `--from-redpanda` to generate a new profile from an existing `redpanda.yaml` file. The special value `current` creates a profile from the current `redpanda.yaml` as it is loaded within `rpk`. - You can use `--from-rpk-container` to generate a profile from an existing cluster created using `rpk container start` command. The name is not needed when using this flag. - You can use `--from-profile` to generate a profile from an existing profile or from a profile in a `yaml` file. First, the filename is checked, then an existing profile name is checked. The special value `current` creates a new profile from the existing profile with any active environment variables or flags applied. - You can use `--from-cloud` to generate a profile from an existing cloud cluster ID. Note that you must be logged in with `rpk cloud login` first. The special value `prompt` will prompt to select a cloud cluster to create a profile for. - For serverless clusters that support both public and private networking, you will be prompted to select a network type unless you specify `--serverless-network`. To avoid prompts in automation, explicitly set `--serverless-network` to `public` or `private`. - You can use `--set key=value` to directly set fields. The key can either be the name of a `-X` flag or the path to the field in the profile’s YAML format. For example, using `--set tls.enabled=true` OR `--set kafka_api.tls.enabled=true` is equivalent. The `--set` flag is always applied last and can be used to set additional fields in tandem with `--from-redpanda` or `--from-cloud`. The `--set` flag supports autocompletion, suggesting the `-X` key format. If you begin writing a YAML path, the flag will suggest the rest of the path. It is recommended to always use the `--description` flag; the description is printed in the output of [`rpk profile list`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-list/). Once the command completes successfully, `rpk` switches to the newly created profile. ## [](#usage)Usage ```bash rpk profile create [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -d, --description | string | Optional description of the profile. | | --from-cloud | string | Create profile from Redpanda Cloud cluster. Automatically configures authentication and connection settings. | | --from-profile | string | Create and switch to a new profile from an existing profile or from a profile in a yaml file. | | --from-redpanda | string | Create and switch to a new profile from a redpanda.yaml file. | | --from-rpk-container | bool | Create and switch to a new profile generated from a running cluster created with rpk container. | | --serverless-network | string | Networking type for serverless clusters: public or private (if not specified, will prompt if both are available). | | -s, --set | stringArray | Set a profile configuration field. Format: key=value. Common fields: brokers, admin_api.addresses, tls.enabled. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | ## [](#suggested-reading)Suggested reading - [`rpk profile list`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-list/) --- # Page 190: rpk profile current **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-current.md --- # rpk profile current > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile current latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-current page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-current.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-current.adoc description: Print the current profile name. This is a tiny command that simply prints the current profile name, which may be useful in scripts, or a PS1, or to confirm what you have selected. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Print the current profile name. This is a tiny command that simply prints the current profile name, which may be useful in scripts, or a PS1, or to confirm what you have selected. ## [](#usage)Usage ```bash rpk profile current [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -n, --no-newline | bool | Do not print a newline after the profile name. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 191: rpk profile delete **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-delete.md --- # rpk profile delete > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile delete latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-delete page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-delete.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-delete.adoc description: Delete an rpk profile. Deleting a profile removes it from the rpk.yaml file. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Delete an rpk profile. Deleting a profile removes it from the `rpk.yaml` file. If the deleted profile was the selected profile, `rpk` will use in-memory defaults until a new profile is selected. ## [](#usage)Usage ```bash rpk profile delete [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 192: rpk profile edit-globals **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-edit-globals.md --- # rpk profile edit-globals > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile edit-globals latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-edit-globals page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-edit-globals.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-edit-globals.adoc description: Edit rpk globals. This command opens your default editor to edit the rpk global configurations. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Edit `rpk` globals. This command opens your default editor to edit the `rpk` global configurations. ## [](#usage)Usage ```bash rpk profile edit-globals [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 193: rpk profile edit **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-edit.md --- # rpk profile edit > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile edit latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-edit page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-edit.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-edit.adoc description: Edit an rpk profile. This command opens your default editor to edit the specified profile, or the current profile if no profile is specified. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Edit an rpk profile. This command opens your default editor to edit the specified profile, or the current profile if no profile is specified. If the profile does not exist, this command creates it and switches to it. The editor will display all available configuration fields. Fields that are not currently set are shown as comments with documentation. To set a field, uncomment it and provide a value. ## [](#usage)Usage ```bash rpk profile edit [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 194: rpk profile list **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-list.md --- # rpk profile list > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile list latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-list page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-list.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-list.adoc description: List rpk profiles. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- List `rpk` profiles. ## [](#usage)Usage ```bash rpk profile list [flags] ``` ## [](#aliases)Aliases ```bash rpk profile ls ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --format | string | Output format (json,yaml,text,wide,help). (New in v26.2.1) | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 195: rpk profile print-globals **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-print-globals.md --- # rpk profile print-globals > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile print-globals latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-print-globals page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-print-globals.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-print-globals.adoc description: Print rpk global configuration. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Print `rpk` global configuration. ## [](#usage)Usage ```bash rpk profile print-globals [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 196: rpk profile print **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-print.md --- # rpk profile print > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile print latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-print page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-print.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-print.adoc description: Print rpk profile configuration. If no name is specified, this command prints the current profile as it exists in the rpk.yaml file. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Print `rpk` profile configuration. If no name is specified, this command prints the current profile as it exists in the `rpk.yaml` file. To print both the profile as it exists in the `rpk.yaml` file and the current profile as it is loaded in `rpk` with internal defaults, user-specified flags, and environment variables applied, use the `-v`/`--verbose` flag. ## [](#usage)Usage ```bash rpk profile print [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 197: rpk profile prompt **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-prompt.md --- # rpk profile prompt > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile prompt latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-prompt page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-prompt.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-prompt.adoc description: Prompt a profile name formatted for a PS1 prompt. This command prints ANSI-escaped text per your current profile's prompt field. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Prompt a profile name formatted for a PS1 prompt. This command prints ANSI-escaped text per your current profile’s `prompt` field. If the current profile does not have a prompt, this prints nothing. If the prompt is invalid, this exits 0 with no message. To validate the current prompt, use the `--validate` flag. This command may introduce other `%` variables in the future, if you want to print a `%` directly, use `%%` to escape it. To use this in zsh, be sure to add setopt PROMPT\_SUBST to your .zshrc. To edit your PS1, use something like PS1='$(`rpk profile prompt`)' in your shell rc file. ## [](#usage)Usage ```bash rpk profile prompt [flags] ``` ### [](#format)Format The `prompt` field supports space or comma separated modifiers and a quoted string that is be modified. Inside the string, the variable `%p` or `%n` refers to the profile name. As a few examples: ```text prompt: hi-white, bg-red, bold, "[%p]" prompt: hi-red "PROD" prompt: white, "dev-%n ``` If you want to have multiple formats, you can wrap each formatted section in parentheses. ```text prompt: ("--") (hi-white bg-red bold "[%p]") ``` ### [](#colors)Colors All ANSI colors are supported, with names matching the color name: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`. The `hi-` prefix indicates a high-intensity color: `hi-black`, `hi-red`, etc. The `bg-` prefix modifies the background color: `bg-black`, `bg-hi-red`, etc. ### [](#modifiers)Modifiers Four modifiers are supported, `bold`, `faint`, `underline`, and `invert`. ### [](#raw-mode)Raw mode The `raw` modifier disables ANSI color escapes entirely, outputting plain text. This is useful when your shell has issues with ANSI escape sequences affecting terminal width calculations. ```text prompt: raw, "%n" prompt: raw, "[%p]" ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --validate | bool | Exit with an error message if the prompt is invalid. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 198: rpk profile rename-to **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-rename-to.md --- # rpk profile rename-to > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile rename-to latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-rename-to page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-rename-to.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-rename-to.adoc description: Rename the current rpk profile. This command renames the currently active profile to the specified name. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Rename the current `rpk profile`. This command renames the currently active profile to the specified name. To switch profiles first, use `rpk profile use`. ## [](#usage)Usage ```bash rpk profile rename-to [flags] ``` ## [](#aliases)Aliases ```bash rpk profile rename ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 199: rpk profile set-globals **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-set-globals.md --- # rpk profile set-globals > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile set-globals latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-set-globals page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-set-globals.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-set-globals.adoc description: Set rpk globals fields. This command takes a list of key=value pairs to write to the global config section of rpk.yaml. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Set `rpk` globals fields. This command takes a list of key=value pairs to write to the global config section of `rpk.yaml`. The globals section contains a set of settings that apply to all profiles and changes the way that `rpk` acts. For a list of global flags and what they mean, check `rpk -X help` and look for any key that begins with `globals`. This command supports autocompletion of valid keys. You can also use the format `set key value` if you intend to only set one key. ## [](#usage)Usage ```bash rpk profile set-globals [KEY=VALUE]+ [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 200: rpk profile set **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-set.md --- # rpk profile set > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile set latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-set page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-set.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-set.adoc description: Set fields in the current rpk profile. As in the create command, this command takes a list of key=value pairs to write to the current profile. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Set fields in the current `rpk profile`. As in the create command, this command takes a list of key=value pairs to write to the current profile. The key can either be the name of a `-X` flag or the path to the field in the profile’s `yaml` format. For example, using `--set` tls.enabled=true OR `--set` kafka\_api.tls.enabled=true is equivalent. The former corresponds to the `-X` flag tls.enabled, while the latter corresponds to the path kafka\_api.tls.enabled in the profile’s `yaml`. To see all available `-X` fields, run `rpk -X help`. This command supports autocompletion of valid keys, suggesting the `-X` key format. If you begin writing a YAML path, this command will suggest the rest of the path. You can also use the format `set key value` if you intend to only set one key. ## [](#usage)Usage ```bash rpk profile set [KEY=VALUE]+ [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | > ⚠️ **CAUTION** > > Profile files may contain sensitive information such as passwords or SASL credentials. Do not commit `rpk.yaml` files to version control systems like Git. --- # Page 201: rpk profile use **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-use.md --- # rpk profile use > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile use latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-use page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-use.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-use.adoc description: Switch to a different rpk profile, making it the active profile for subsequent rpk commands. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Switch to a different `rpk profile`, making it the active profile for subsequent `rpk` commands. ## [](#usage)Usage ```bash rpk profile use [flags] ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 202: rpk profile validate **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile-validate.md --- # rpk profile validate > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile validate latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile-validate page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile-validate.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile-validate.adoc description: Validate profile configuration and detect common issues. page-git-created-date: "2026-07-28" page-git-modified-date: "2026-08-06" --- Validate profile configuration and detect common issues. This command checks the current profile (or a specified profile) for: - `Cloud settings`: Whether from\_cloud matches the broker URLs - `Auth reference`: Whether the profile references a valid authentication - `Auth kind`: Whether the authentication type is correctly configured - `Auth token`: Whether the token exists and is not expired ## [](#usage)Usage ```bash rpk profile validate [flags] ``` ## [](#examples)Examples This section provides examples of how to use `rpk profile validate`. Validate the current profile: ```bash rpk profile validate ``` Validate a specific profile: ```bash rpk profile validate my-profile ``` ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 203: rpk profile **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile.md --- # rpk profile > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk profile latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-profile/rpk-profile page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-profile/rpk-profile.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-profile/rpk-profile.adoc description: Manage rpk profiles. An rpk profile talks to a single Redpanda cluster. page-git-created-date: "2026-05-11" page-git-modified-date: "2026-08-06" --- Manage `rpk` profiles. An rpk profile talks to a single Redpanda cluster. You can create multiple profiles for multiple clusters and swap between them with `rpk profile use`. Multiple profiles may be useful if, for example, you use `rpk` to talk to a localhost cluster, a dev cluster, and a prod cluster, and you want to keep your configuration in one place. You can also use the RPK\_PROFILE environment variable to temporarily override the current profile without modifying your configuration. The `--profile` flag takes precedence over the environment variable if both are set. ## [](#usage)Usage ```bash rpk profile [flags] ``` ## [](#subcommands)Subcommands | Command | Description | | --- | --- | | rpk profile clear | Clear the current profile. This command clears the current profile, which can be useful to unset a production cluster profile. | | rpk profile create | Create a new rpk profile with connection settings for a Redpanda cluster. | | rpk profile current | Print the current profile name. This is a tiny command that simply prints the current profile name, which may be useful in scripts, or a PS1, or to confirm what you have selected. | | rpk profile delete | Delete an rpk profile. Deleting a profile removes it from the rpk.yaml file. | | rpk profile edit | Edit an rpk profile. This command opens your default editor to edit the specified profile, or the current profile if no profile is specified. | | rpk profile edit-globals | Edit rpk globals. This command opens your default editor to edit the rpk global configurations. | | rpk profile list | List rpk profiles. | | rpk profile print | Print rpk profile configuration. If no name is specified, this command prints the current profile as it exists in the rpk.yaml file. | | rpk profile print-globals | Print rpk global configuration. | | rpk profile prompt | Prompt a profile name formatted for a PS1 prompt. This command prints ANSI-escaped text per your current profile’s prompt field. | | rpk profile rename-to | Rename the current rpk profile. This command renames the currently active profile to the specified name. | | rpk profile set | Set fields in the current rpk profile. As in the create command, this command takes a list of key=value pairs to write to the current profile. | | rpk profile set-globals | Set rpk globals fields. This command takes a list of key=value pairs to write to the global config section of rpk.yaml. | | rpk profile use | Switch to a different rpk profile, making it the active profile for subsequent rpk commands. | | rpk profile validate | Validate profile configuration and detect common issues. | ## [](#global-flags)Global flags | Value | Type | Description | | --- | --- | --- | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. | | --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. | | --profile | string | rpk profile to use. | | -v, --verbose | bool | Enable verbose logging. | --- # Page 204: rpk -X **URL**: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-x-options.md --- # rpk -X > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: rpk -X latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: rpk/rpk-x-options page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: rpk/rpk-x-options.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/reference/pages/rpk/rpk-x-options.adoc description: Override any rpk configuration option for a single command with the -X flag, or set it persistently with an RPK_ environment variable. page-git-created-date: "2026-05-11" page-git-modified-date: "2026-08-06" --- Use the `-X` flag to override any rpk-specific configuration option for a single command, without modifying your rpk profile. Each option follows the form `key=value`: for example, `rpk -X tls.enabled=true` enables TLS for the Kafka API. Every `-X` option also has an environment-variable equivalent: prefix with `RPK_` and replace periods (`.`) with underscores (`_`). For example, `tls.enabled` becomes `RPK_TLS_ENABLED`. To list every available option, run: ```bash rpk -X list ``` Run `rpk -X help` for inline descriptions, or see the [full `rpk -X` reference](https://docs.redpanda.com/current/reference/rpk/rpk-x-options/) in the Redpanda docs. > 💡 **TIP** > > For persistent configuration across commands and sessions, prefer [rpk profiles](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-profile/rpk-profile/) over environment variables or `-X` flags. ---