Agentic Data Plane

Understand Agent Concepts

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

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 following diagram shows how agents process requests through iterative reasoning:

Diagram showing the agent reasoning loop: User Request flows to LLM Receives Context
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
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

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

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

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 tools extend agent capabilities beyond text generation. Understanding when and how tools execute helps you design effective tool sets.

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

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

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 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.

Context and state management

Agents handle two types of information: conversation context (what’s been discussed) and state (persistent data across sessions).

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

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

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/<agent-name>. The principal is <agent-name>@iam.serviceaccounts.<dns-zone>, where <dns-zone> 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, 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.

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 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.

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