Collapse navigation tree

Collapse

System Prompt Best Practices

Write system prompts that produce reliable, predictable agent behavior. Good prompts define scope, specify constraints, and guide tool usage.

The Agentic Data Plane is supported on BYOC clusters running with AWS and Redpanda version 25.3 and later.

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

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

Define what the agent does, not what it is.

Do
You are an order fulfillment agent for an e-commerce platform. You help customers track orders, update shipping addresses, and process returns.
Don’t
You are a helpful assistant.

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.

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

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

Name each tool the agent can use:

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

Provide decision criteria for tool selection.

Do
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
Use the tools as needed.

Constraints and safety

Set explicit boundaries to prevent unintended agent behavior.

Define data boundaries

Specify what data the agent can access:

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

Control output format and content:

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

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

Guide the agent on how to clarify:

When request is unclear:
1. Ask clarifying questions
2. Suggest common interpretations
3. Do not guess customer intent

Define conversation boundaries

Set limits on conversation scope:

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

Guide agents to handle failures gracefully through clear prompt instructions. Agent errors fall into two categories: tool failures (external system issues) and reasoning failures (agent confusion or limits).

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

Design prompts so agents continue when tools fail:

Example prompt guidance for graceful degradation
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

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
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, etc.)

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

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

Define how the agent presents information:

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

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 tool
Test 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 temporarily
Send request requiring disabled tool
Verify 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

Apply these principles when writing system prompts to create reliable agent systems.

Design for inspectability

Make agent reasoning transparent so you can debug by reading conversation history. Your system prompt should encourage clear explanations:

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

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.

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

Example: System prompt with all best practices

This complete example demonstrates all the patterns described in this guide:

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

Avoid these patterns that lead to unpredictable agent behavior.

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

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

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