Agentic Data Plane

Create an Agent

Create a new AI agent declaratively through Redpanda ADP. No Python or JavaScript code required. This guide walks through the create form section by section, then covers the post-create steps for discovery metadata and testing.

After reading this page, you will be able to:

  • Create an ADP agent through the create form

  • Configure an LLM provider, model, and execution settings

  • Configure tools, subagents, and discovery metadata for an agent

Prerequisites

Open the create form

  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 register an agent you build and run yourself, see Register Your Own Agent (BYOA).)

    The runtime choice in the create-agent flow

ADP configures the agent on a single page with five sections: Details, Model, Behavior, Tools, and Subagents. A stepper on the left tracks the sections and summarizes what you’ve set in each; click a step to jump to its section. Required fields are marked with a red asterisk.

Details

In the Details section, configure the identity fields that appear in the agent registry list, transcripts, and audit logs.

  1. Review the Agent ID. ADP pre-fills a generated ID and re-derives it from the display name as you type, using lowercase letters, numbers, and hyphens (up to 63 characters). Editing the ID directly stops the auto-derive. The ID is used in URLs and CLI commands and can’t be changed after creation.

  2. Enter a Display name. Required. Shown in the agent registry list and detail header (for example, Customer Support Agent).

  3. Optionally, add a Description. Up to 1024 characters.

  4. Optionally, add Tags as key/value pairs to organize and filter agents in the registry.

Model

In the Model section, select the large language model (LLM) provider and model the agent uses to interpret user intent and decide which tools to invoke.

  1. Select an LLM provider. Required. The dropdown lists every LLM provider configured in ADP (for example, support-bedrock-v2). To add a new provider, see Configure an LLM provider.

  2. Select a Model. Required. The list is populated by the selected provider (for example, us.anthropic.claude-haiku-4-5-20251001-v1:0). If the provider has no allowlist, you can type the model identifier directly.

    For model selection guidance, see Model selection guide.

  3. Optionally, expand Advanced and set Max iterations. Leave it at 0 to use the runtime default. Max iterations is the upper bound on agent reasoning loops per request; the proto contract allows 0-200. Each iteration consumes tokens and adds latency.

    If you override the default, choose based on task complexity:

    • Simple queries (10-20): Single tool call, direct answers, minimal reasoning.

    • Balanced workflows (20-40): Multiple tool calls, data aggregation, moderate analysis.

    • Complex analysis (40-100): Exploratory queries, extensive tool chaining, deep reasoning.

For external model specifications and pricing:

Behavior

In the Behavior 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. The prompt field is a Markdown editor: format the prompt visually, or switch to the Raw tab to edit the Markdown source directly.

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:

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.

Tools

In the Tools section, select the Model Context Protocol (MCP) servers that expose tools to the agent. This section is optional, and you can change the list at any time after creation.

  1. Under MCP servers, select each server you want the agent to call.

  2. The agent discovers each 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.

Apply the principle of least privilege. Connect only the servers the agent needs.

For registering MCP servers, see Create an MCP server.

Subagents

In the Subagents section, optionally add internal specialists within the same agent. Each subagent has its own name, description, system prompt, and MCP tools, but all subagents share the parent agent’s provider, model, and execution settings.

  1. To add a specialist, click Add subagent and configure it:

    • Name: Required. Up to 63 characters. Must start with a lowercase letter, contain only lowercase letters, digits, and hyphens, and end with a letter or digit (for example, order-agent). The name is also a DNS-1123 / AIP-122 compliant identifier.

    • Description: Optional. Up to 1024 characters.

    • System prompt: Up to 16,384 characters. Domain-specific instructions for what the subagent does.

    • MCP tools: Select the tools this subagent can access.

  2. To keep the agent flat, leave the list empty.

The root agent orchestrates and delegates work to the appropriate subagent based on the request.

For multi-agent design patterns, see Agent architecture patterns.

Create the agent

  1. Check the stepper on the left, which summarizes what you set in each section. To change anything, click the step to jump back to its section.

  2. Click Create agent. If a required field is missing, a "Cannot create agent" error lists what to fix.

  3. Wait for the agent to reach the Running state.

ADP creates the agent’s service account automatically when you create the agent. The default name uses the pattern cluster-<cluster-id>-agent-<agent-name>-sa, and ADP applies default permissions. For details and how to manage service accounts, see Service account authorization.

When the agent is running, ADP shows its A2A endpoint URL on the Connect tab, along with authentication guidance and ready-to-paste code examples for calling the agent with the official A2A client SDKs.

You can use this URL to call the agent programmatically or integrate it with external systems. See Choose an Integration Pattern.

Issue agent credentials

Every agent has a hidden service account in ADP that scopes the calls the agent makes to MCP servers and the Redpanda broker. To call the agent from an external system as that service account, issue an OAuth 2.0 client credential on the agent’s Credentials tab.

The Setup tab on the agent detail page shows the equivalent OAuth client configuration (token endpoint, scopes, sample request) after a credential exists. The sample requests target a specific LLM provider’s gateway endpoint: pick a provider on the tab and the examples fill in its endpoint URL.

The client_secret value is plaintext and returned only at create time. ADP cannot retrieve it again. Capture the value into your secret store before you leave the dialog. To rotate, create a new credential, update the consumer, then delete the old one.

  1. Open the agent and click the Credentials tab.

  2. Click Create credential.

  3. Optionally enter a Description (up to 1024 characters) to identify what the credential is used for, for example customer-support-bot prod.

  4. Optionally pick an Expires at date. Leave it unset for a non-expiring credential.

  5. Click Create.

    ADP shows a one-time dialog containing:

    • Client ID: An OAuth 2.0 client identifier in the form serviceaccounts/<agent-name>. Stable across credentials and rotations: every credential on the same agent carries the same value.

    • Client secret: The plaintext OAuth client secret, shown only at create time.

  6. Copy both values into your secret store before closing the dialog. The credential row appears in the Credentials table with its description, expiry, and creation time, but the secret is never retrievable again.

To list existing credentials, return to the Credentials tab. The list shows the metadata fields for each credential (description, expiry, creation time) but not the secret.

To delete a credential, click the delete action on the credential row. Delete is idempotent: deleting a credential that no longer exists succeeds. After delete, the OAuth token endpoint rejects the corresponding client_id / client_secret pair.

Required permissions

Credential operations are governed by their own permission set:

Permission Allows

dataplane_adp_agent_credential_create

Issue new credentials for the agent.

dataplane_adp_agent_credential_list

List credential metadata for the agent.

dataplane_adp_agent_credential_delete

Delete credentials for the agent.

Configure A2A discovery metadata (optional)

A2A discovery metadata lets external systems find and invoke the agent through capability-based discovery. Configure this after creation, on the agent’s A2A tab.

For agent card design guidance, see Create an Agent Card.

  1. Open the agent and click the A2A tab.

  2. Configure identity fields:

    • Icon URL: A publicly accessible image URL (recommended: 256x256 PNG or SVG).

    • Documentation URL: Link to comprehensive agent documentation.

  3. Configure provider information:

    • Organization: Your organization or team name.

    • URL: Website or contact URL.

  4. Add Skills to describe what the agent can do for capability-based discovery. For each skill:

    • Skill ID (required): Lowercase letters, digits, and hyphens (for example, fraud-analysis).

    • Skill name (required): Human-readable name displayed in agent directories.

    • Description (required): What the skill does and when to use it. Be specific about inputs, outputs, and use cases.

    • Tags (optional): Categorization terms (for example, fraud, security, finance).

    • Examples (optional): Sample queries demonstrating how to invoke this skill.

  5. Save your changes. The updated metadata appears immediately at https://<your-agent-url>/.well-known/agent-card.json.

For more about agent cards and how they’re consumed, see Agent cards.

Test your agent

Two tabs on the agent detail page support testing and observability:

  • Inspector: Send test prompts interactively and inspect each step of the agent’s reasoning, tool calls, and responses. Use Inspector during development and tuning.

  • Transcripts: Records every conversation against the agent (prompt, tool calls, tool outputs, final response). Use Transcripts to audit production behavior.

    1. Open the agent’s Inspector tab.

    2. Enter a test prompt.

    3. Verify the agent:

  • Selects appropriate tools

  • Follows the system prompt’s constraints

  • Returns the expected output format

    1. Iterate on the system prompt, MCP tool selection, or model choice as needed.

For detailed observability strategies, see Monitor Agent Activity.

Example configurations

Simple query agent

  • Model: GPT-5 Mini (fast, cost-effective)

  • Tools: Single MCP server exposing a get_orders tool

  • Max iterations: 10

  • Use case: Customer order lookups

Complex analytics agent

  • Model: Claude Sonnet 4.5 (balanced)

  • Tools: Multiple servers for data query, aggregation, and formatting

  • Max iterations: 30

  • Use case: Multi-step data analysis

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

  • Max iterations: 20

  • Use case: E-commerce operations

Next steps