Agent Prompt

Prompt engineering fundamentals

The agent prompt is the foundation of your AI agent’s behavior. A well-crafted prompt defines the agent’s personality, capabilities, and decision-making logic. Poor prompts lead to inconsistent, irrelevant, or incorrect responses.

Prompt structure template

# Role Definition
You are a [specific role] that [primary function].

# Context
You work in a [business context] where [relevant background information].

# Capabilities
You can:
- [Capability 1]
- [Capability 2]
- [Capability 3]

# Instructions
When processing requests:
1. [Step 1]
2. [Step 2]
3. [Step 3]

# Examples
Input: [Sample input]
Output: [Expected output format]

# Constraints
- Do not [restriction 1]
- Always [requirement 1]
- Never [prohibition 1]

# Output Format
Respond in [specific format] with [required elements].

Access control and permissions

Prompt editing requires “Developer” role or higher. Users with “Tester” or “Viewer” roles can only view prompts but cannot modify them.

Role-based prompt access

SuperAdmin/Admin: Full access to all prompt features including AI refinement
Developer: Can edit prompts and use refinement tools; changes require approval for production
Tester: Read-only access for testing purposes
Viewer: Limited to viewing published prompts only

Creating effective prompts

Step-by-step prompt creation

Define the agent's role

Clearly specify what the agent is and what it does.Good example:

You are a customer service specialist for an e-commerce platform. 
Your primary role is to help customers with order-related inquiries, 
returns, and product questions.

Poor example:

You are helpful.

Provide context and background

Give the agent relevant business context and domain knowledge.Good example:

You work for TechStore, an online electronics retailer. We sell 
computers, phones, accessories, and home electronics. Our return 
policy allows 30-day returns for most items, except software and 
personalized products.

Define capabilities and limitations

Clearly state what the agent can and cannot do.Good example:

You can:
- Look up order status and tracking information
- Process return requests and issue refunds
- Answer product questions and provide recommendations
- Escalate complex issues to human agents

You cannot:
- Process payments or update billing information
- Modify orders that have already shipped
- Access customer account passwords

Include examples and patterns

Provide sample interactions to guide the agent’s responses.Good example:

Example 1:
Customer: "Where is my order?"
You: "I'd be happy to help you track your order. Could you please 
provide your order number or the email address used for the purchase?"

Example 2:
Customer: "I want to return this item"
You: "I can help you with that return. To get started, I'll need 
your order number and the reason for the return."

Set output format requirements

Specify how the agent should structure its responses.Good example:

Always structure your responses as follows:
1. Acknowledge the customer's request
2. Ask for any required information
3. Provide the solution or next steps
4. Offer additional help if appropriate

Use a friendly, professional tone. Keep responses concise but complete.

Access refinement

In the Inspector’s Details tab, click “Refine with AI” after writing your initial prompt.

Review suggestions

The AI will analyze your prompt and suggest improvements for:

Clarity and specificity
Missing context or examples
Better structure and organization
More precise instructions

Apply or customize

Choose to apply all suggestions, select specific improvements, or manually edit the refined version.

Use refinement as a starting point, not a final solution. Always review and customize AI suggestions to match your specific use case.

Iterate multiple times: Refine prompts based on actual agent performance
Test with real scenarios: Use actual customer queries to validate prompt effectiveness
Monitor performance: Track response quality and adjust prompts accordingly
Version control: Keep track of prompt changes and their impact on performance

Debugging prompt issues

Common prompt problems and solutions

Agent gives irrelevant responses

Symptoms: Agent responds to queries but answers are off-topic or unhelpfulDebugging steps:

Check if the prompt clearly defines the agent’s role and scope
Verify that examples match the types of queries you expect
Review the context section for missing business information
Test with sample queries to identify gaps

Sample debugging code:

// Test prompt effectiveness
const testQueries = [
  "What is your return policy?",
  "How do I track my order?",
  "Can I cancel my order?",
  "What are your business hours?"
];

// Each query should produce relevant, helpful responses

Resolution: Add more specific role definition, relevant examples, and business context

Agent ignores instructions

Symptoms: Agent doesn’t follow specific instructions or constraintsDebugging steps:

Check if instructions are clear and unambiguous
Verify that constraints are explicitly stated
Review the examples to ensure they demonstrate desired behavior
Test with edge cases to identify instruction gaps

Sample debugging code:

// Test instruction compliance
const constraintTests = [
  "Can you process a refund?", // Should ask for order details
  "What's my password?", // Should refuse and redirect
  "Cancel my order", // Should check if order can be cancelled
];

// Verify agent follows all constraints

Resolution: Make instructions more explicit, add negative examples, and strengthen constraints

Inconsistent response format

Symptoms: Agent responses vary in structure and formatDebugging steps:

Check if output format requirements are clearly specified
Verify that examples demonstrate the desired format
Review the prompt for conflicting format instructions
Test with multiple queries to identify format inconsistencies

Sample debugging code:

// Test response format consistency
const formatTests = [
  "Help me with my order",
  "I want to return something",
  "What products do you sell?"
];

// All responses should follow the same structure

Resolution: Clarify output format requirements and provide consistent examples

Agent asks for unnecessary information

Symptoms: Agent requests information that’s not needed for the taskDebugging steps:

Review the prompt for overly broad information requests
Check if examples demonstrate efficient information gathering
Verify that the agent understands what information is actually needed
Test with scenarios where minimal information should suffice

Sample debugging code:

// Test information efficiency
const efficiencyTests = [
  "Track order 12345", // Should only need order number
  "Return item ABC", // Should only need order details
  "Business hours", // Should not need any customer info
];

// Verify agent asks only for necessary information

Resolution: Streamline information requirements and provide examples of efficient interactions

Advanced prompt techniques

Chain-of-thought prompting

When processing a request, think through the problem step by step:

First, identify what the customer is asking for
Determine what information you need to help them
Consider any constraints or limitations
Provide a clear, helpful response
Offer additional assistance if appropriate

Few-shot learning

Here are examples of how to handle different types of requests:

Example 1 - Order Status:
Customer: "Where is my order?"
You: "I'd be happy to help you track your order. Could you please provide your order number?"

Example 2 - Return Request:
Customer: "I want to return this item"
You: "I can help you with that return. To get started, I'll need your order number and the reason for the return."

Example 3 - Product Question:
Customer: "Do you have this item in stock?"
You: "I can check our inventory for you. Could you please provide the product name or SKU?"

Role-playing and persona

You are Sarah, a friendly and knowledgeable customer service representative 
with 5 years of experience helping customers with their orders. You're known 
for being patient, thorough, and always going the extra mile to help customers 
resolve their issues.

Your personality traits:
- Empathetic and understanding
- Detail-oriented and accurate
- Proactive in offering solutions
- Professional but approachable

Testing and validation

Prompt testing checklist

Role is clearly defined and specific
Context includes relevant business information
Capabilities and limitations are explicitly stated
Examples demonstrate desired behavior
Output format is clearly specified
Constraints are unambiguous
Prompt handles edge cases appropriately
Response quality meets business requirements

Performance monitoring

Response relevance: Track how often responses directly address customer queries
Information efficiency: Monitor how quickly agents gather necessary information
Constraint compliance: Ensure agents follow all specified rules and limitations
Customer satisfaction: Measure customer feedback on agent interactions

Integration with other components

RAG integration

Knowledge Base: Ground prompts with enterprise data
Data Sources: Connect prompts to relevant information sources

Tool integration

Tools: Enable prompts to trigger external actions
DevStudio: Create custom tools for specific prompt needs

Variable management

Variables: Use captured data to personalize prompts
Decision Logic: Create dynamic prompts based on workflow state

Best practices summary

Start specific: Define clear roles and boundaries from the beginning
Iterate based on data: Use actual performance metrics to refine prompts
Test thoroughly: Validate prompts with real-world scenarios
Monitor continuously: Track performance and adjust as needed
Document changes: Keep track of prompt versions and their impact
Collaborate: Get feedback from stakeholders and end users
Stay current: Update prompts as business requirements evolve

1. Getting Started

2. Building Assistants

3. Graph Studio (Workflow Builder)

4. DevStudio (Tool Builder)

5. Triggers & Intents

6. Builds & Environments

7. Observability & Billing

8. User Management

9. Reference

10. Troubleshooting & Support

Prompt engineering fundamentals

Prompt structure template

Access control and permissions

Role-based prompt access

Creating effective prompts

Step-by-step prompt creation

AI-powered prompt refinement

Using the built-in refinement tool

Refinement best practices

Debugging prompt issues

Common prompt problems and solutions

Advanced prompt techniques

Chain-of-thought prompting

Few-shot learning

Role-playing and persona

Testing and validation

Prompt testing checklist

Performance monitoring

Integration with other components

RAG integration

Tool integration

Variable management

Best practices summary

​Prompt engineering fundamentals

​Prompt structure template

​Access control and permissions

​Role-based prompt access

​Creating effective prompts

​Step-by-step prompt creation

​AI-powered prompt refinement

​Using the built-in refinement tool

​Refinement best practices

​Debugging prompt issues

​Common prompt problems and solutions

​Advanced prompt techniques

​Chain-of-thought prompting

​Few-shot learning

​Role-playing and persona

​Testing and validation

​Prompt testing checklist

​Performance monitoring

​Integration with other components

​RAG integration

​Tool integration

​Variable management

​Best practices summary

Prompt engineering fundamentals

Prompt structure template

Access control and permissions

Role-based prompt access

Creating effective prompts

Step-by-step prompt creation

AI-powered prompt refinement

Using the built-in refinement tool

Refinement best practices

Debugging prompt issues

Common prompt problems and solutions

Advanced prompt techniques

Chain-of-thought prompting

Few-shot learning

Role-playing and persona

Testing and validation

Prompt testing checklist

Performance monitoring

Integration with other components

RAG integration

Tool integration

Variable management

Best practices summary