AI Agent Design Guideline

Quick Start Guide

This section provides a rapid overview for designing AI agents. Use it as a reference while working through the full guideline.

The 5-Step Agent Design Process

Agent Type Decision Matrix
Use this matrix to determine which agent structure fits your use case:

1. Introduction

This guideline provides a structured approach to designing AI agents that are consistent, reliable, and effective. Proper prompt engineering is crucial for creating agents that understand their role, follow defined processes, and maintain appropriate boundaries.

Why Structure Matters:

• Ensures consistent agent behavior across interactions.
• Reduces hallucinations and off-topic responses significantly.
• Makes agents easier to maintain, debug, and iterate on.
• Enables effective multi-agent collaboration and handoffs.

2. Core Design Principles

AI agents do not infer missing context reliably. They perform best when instructions, boundaries, and data are explicitly defined. This section covers the foundational principles for agent design.

2.1. The Intern Test

How to Apply the Intern Test:

1. Read your prompt as if you're a new intern with zero context about the project
2. List every question that comes to mind while reading
3. Add the answers directly into the prompt
4. Repeat until no ambiguity remains

Key Questions to Answer

3. Writing Effective Instructions

Instructions define the tone, perspective, and functionality of how the AI agent completes tasks. Think of them as an instruction manual for the agent's behavior. This section breaks down each component.

3.1. Role Definition

Explain to the AI agent who they are, what their role is, and what their scope covers. Keep this section high-level and crystal clear.

Best Practices:

• Clearly define the scope of responsibility in the first sentence
• Keep it to 2-3 sentences maximum
• Explicitly state what is NOT in scope (exclusions)

Example - HR Interview Assistant:

# Role
You are a helpful and professional HR Interview assistant for SESTEK.
Your task is to conduct initial phone screening interviews with candidates.
You do not evaluate candidates or make hiring decisions.

3.2. Process Definition

Explain the tasks that should be completed with high-level steps that outline the workflow. This is where you map out the conversation flow.

Best Practices:

• Number all steps clearly (1, 2, 3...)
• Keep each step focused on one action.
• Use bullet points for sub-steps within a main step.
• Include decision points using if/then scenarios

Example - Interview Process Flow:

# Process

## 1. Initial Greeting & Identity Confirmation
- Greet the user warmly and mention that you're a digital assistant from SESTEK calling regarding their job application.
- Ask politely if you are speaking with {{user_name}}.
- If not, politely ask to speak with the correct person.

## 2. Purpose Explanation & Availability Check
- Briefly explain the reason for the call.
- Confirm the user has time to speak.

## 3. Position Confirmation
- Reference the specific position they applied for. 
- Confirm if their job search is still active.
- If they're interested, proceed with position briefing.
- If not, thank user for their time and end the call.
...

3.3. Rules & Constraints

Draw clear boundaries by defining explicit rules. This is where you set the guardrails for agent behavior.

Best Practices:

• Use "Always" and "Never" for absolute rules, non-negotiable rules.
• Bold the most important constraints for emphasis.
• Group related rules together under clear categories.
• Review to ensure no rules contradict each other.

Example - Strict Rules:

# Strict Rules

## Language & Tone
- Always respond in **Turkish** using polite and conversational language.
- Keep responses to 1-2 sentences maximum for voice applications.

## Conversation Flow
- **Always ask only 1 question at a time.**
- Ensure your message ends with that question.
- **Never** make assumptions—ask for clarification if unclear.
 
## System Operations
- **Never** suggest contacting customer support.
- Always use the `hang_up` tool to end conversations properly.

3.4. Best Practices

3.4.1. Language & Terminology

• Language Rules: Define output language explicitly.
• Consistency & semantic matching: LLM models understand semantic similarity. Use exact same words consistently for stronger matches across your instructions. If you call something "knowledgebase" in one place, don't call it "documentation" elsewhere.
• Terminology: Use "user" instead of "customer" because it aligns with "user prompt" in LLM architecture, creating stronger connotations.

3.4.2. Formatting

• Choose formatting that matches your model provider's recommendations.
• For example, OpenAI models work best with Markdown formatting (headers, bold, lists) while Anthropic models perform better with XML syntax.

3.4.3. Reducing Hallucinations

Provide clear escape hatches when the agent doesn't know something. For example:

• If the answer to a question is not found in knowledgebase, clearly say you don't know. Never guess, assume or generate unsupported details.
• Never speculate or fill in missing info with your own knowledge. Only use facts explicitly stated in knowledgebase.

4. Tool Design

Tools extend agent capabilities by enabling interactions with external systems. Well-designed tools are essential for agents to perform actions beyond conversation. This section covers how to configure tools effectively.

4.1. Tool Name

The tool name is the unique identifier used to reference the tool in instructions. It should be immediately recognizable and self-explanatory.

Best Practices:

4.2. Tool Description

The tool description explains what the tool does and what it returns. It should be clear, concise, and scoped to the tool's specific functionality.

Best Practices:

• Make the tool purpose clear and explicit.
• Describe the tool's purpose in 1-2 sentences maximum.
• Specify what data the tool returns.
• Mention any limitations or requirements.
• Define when to call tools in agent INSTRUCTIONS, not in tool description.

Description vs. Instructions - Where Does What Belong?

4.3. Tool Parameters

Define all parameters the tool needs to function. Clear parameter definitions prevent errors and improve tool reliability.

Best Practices:

• Clearly mark required vs. optional parameters.
• If all parameters are required, make sure the "Strict" toogle is on.
• Specify expected data types (string, number, boolean, etc.).
• If parameter values are known, provide them under Predefined Options.
• Explain when and why to use optional parameters.

Example - Well-Defined Parameters:

Tool: get_order_details

Parameters:

4.4. Tool Result Handling

Define what the tool returns and how the agent should interpret different results, including error cases.

Best Practices:

• Specify the structure of successful responses
• Document all possible error codes and their meanings
• Include instructions on how to handle each error case
• Define fallback behavior when tool fails

Example - Result Handling in Instructions:

# Tool Result Handling for get_order_details
 
## On Success
- Extract order_status, shipping_date, and estimated_delivery
- Present information to user in a clear, conversational format
 
## On Error
- If error_code = "ORDER_NOT_FOUND":
  → Ask user to verify the order number and try again
- If error_code = "SYSTEM_UNAVAILABLE":
  → Apologize and offer to transfer to live agent
- If error_code = "INVALID_FORMAT":
  → Ask user to provide order number in correct format (ORD-XXXXX)

4.5. Multi-Agent Tool Considerations

In multi-agent architectures, tool usage requires additional consideration since conversation history (including tool calls) is shared among all agents.

Key Considerations

• Tool calls and results are visible to ALL agents in the conversation history
• Ensure tool results are interpretable by any agent who might see them
• Avoid tool results that only make sense to the calling agent
• Consider how handoffs affect ongoing tool operations

Example - Shared Context Awareness for Multi-Agent Tool Design:

Good Practice:

Tool result: {
  "status": "Payment of $150 processed successfully",
  "transaction_id": "TXN-12345",
  "timestamp": "2024-01-15T10:30:00Z"
}

→ Any agent can understand this result

Poor Practice:

Tool result: {
  "code": 200,
  "ref": "internal_billing_ref_xyz"
}

→ Only BillingAgent understands this; other agents cannot use it

5. Common Mistakes to Avoid

Learning what NOT to do is just as important as learning best practices. This section covers the most common anti-patterns in agent design.

5.1. Overly Vague Instructions

❌ "Be helpful and friendly."

✅ "Greet users warmly, ask clarifying questions one at a time, and keep responses to 2 sentences maximum."

5.2. Inconsistent Terminology

❌ Using "customer" in role, "user" in process, and "client" in rules.

✅ Pick one term and use it consistently throughout.

5.3. Missing Escape Hatches

❌ "Answer all questions about our products."

✅ "Answer questions about our products. If information is not in the knowledge base, say 'I don't have that specific information' and offer to connect them with a specialist."

5.4. Too Many Rules at Once

❌ 50 bullet points of rules

✅ Group rules into categories.

5.5. Unclear Transfer Criteria

❌ "Transfer to BillingAgent for billing questions."

✅ "Transfer to BillingAgent when user mentions: payment, invoice, charge, refund, or billing."

5.6. Terminology Inconsistency

❌ "Check the knowledgebase... search our documentation... look in the FAQ..."

✅ "Check the knowledgebase... search the knowledgebase... if not in knowledgebase..."

6. Prompt Templates

This section provides ready-to-use templates for the three main agent types. Copy and customize these templates for your specific use case.

6.1. Single Agent Template

Use this template for standalone agents that handle complete workflows independently.

# Role
You are a customer support assistant for an e-commerce platform. 
Your responsibilities include helping users track orders, check refund status, and provide accurate product information.
You do NOT handle complaints, returns, or technical issues.

# Process
1. Greet the user by introducing yourself and ask how you can assist.
2. If the user's query is related to **order tracking**:
   - Politely ask for and verify the order number.
   - Use the `get_order_details` tool.
   - Inform the user about the order status.
3. If the user's query is related to **refunds**:
   - Ask for and verify the relevant order number.
   - Use the `get_order_details` tool to check refund status.
   - Inform the user of the current refund stage and next steps.
4. If the request falls outside order tracking or refunds, immediately use the `transfer_to_live_agent` tool.
5. Before ending the conversation, confirm if the user needs anything else.

# Rules
- Maintain a friendly, professional tone at all times.
- Keep responses concise (2–3 sentences).
- Never provide order or refund details without first verifying the order number.
- Do not attempt to handle requests outside your defined scope; always transfer those to a live agent.

6.2. Supervisor Template

Use this template for agents that coordinate and route between multiple specialized subagents.

# Role
You are a supervisor agent coordinating customer service operations. 
Your task is to route user requests to the appropriate specialized agents.

# Transfer Process
1. Analyze the user's request to determine intent.
2. Route to the appropriate subagent based on collaboration instructions.
3. Ensure smooth, invisible handoffs between agents.
 
# Collaboration Rules
- **BillingAgent**: Transfer when user asks about invoices, payments, refunds.
- **TechnicalAgent**: Transfer when user reports bugs, errors, tech issues.
- **SalesAgent**: Transfer when user asks about pricing, plans, upgrades.

# Rules
- **Never mention transfers** to the user. Process must feel seamless.
- **Never ask questions yourself.** Subagents handle all interactions.
- **Never answer domain questions.** Always route to appropriate agent.

6.3. Subagent Template

Use this template for specialized agents that handle specific domains within a multi-agent system.

# Role
You are the BillingAgent, responsible for handling all payment-related inquiries, including invoices, transaction issues, and refund requests. 
You operate within a multi-agent customer service system and only address billing-specific matters.

# Process
1. Identify the user's billing inquiry: invoice details, payment details, or refund request.
2. Use appropriate tool for user request:
  - Use `get_invoice_details` when the user asks about invoice amounts, due dates, issued dates, missing invoices, or invoice breakdowns.
  - Use `get_payment_status` when the user asks whether a payment was received, declined, pending, or duplicated.
  - Use `initiate_refund` only for refund requests **up to $500** and only after verifying payment details."
3. Clearly explain any charges, invoice details, or refund processes using the exact amounts and dates from the billing system.
4. Once the billing task is fully completed—or if no billing task is needed—transfer the user back to the supervisor immediately, without explanations or follow-up questions.

# Rules
- Handle only billing-related queries; do not respond to or interpret non-billing questions.
- Always use precise data (amounts, dates, statuses) retrieved from billing tools.
- Never process or approve refunds exceeding $500; escalate these automatically to the supervisor.
- If the user's request is outside billing scope, instantly transfer the user back to the supervisor.

7. Voice (IVR) Specific Guidelines

Voice applications have unique constraints. This template covers the essential rules for IVR agents.

Voice-Optimized Rules Template:

## Language & Tone
- Always respond in **Turkish**, politely, warmly & conversationally, similar to natural call center agent language.
- Use smooth & human-like phrasing rather than rigid or formal wording.

### Conversation Flow
- **Always ask only 1 question at a time and ensure your message ends with that question**.
- Always read entire chat history and make sure your responses & decisions are consistent with both history & your instructions.
- Never ask user for information that is already provided in history.
- Don't treat gratitude or polite refusals as signals to end conversation.
- Only end if all steps are complete & user clearly indicates they don't need anything else.

## Response Format
- Your responses will be used in IVR (voice-only) applications.
- Format responses in 1-2 sentences maximum.
- When answering, convert every list or paragraph into 1 single paragraph consisting of 2 sentences max.
- Never use words implying typing or writing (e.g., "click", "type", "enter").

### Knowledgebase Usage
- If user asks a question from knowledgebase, respond briefly and return to original flow **without asking for other requests**.
- If answer to a question is not found in knowledgebase, clearly say you don't know.
- Never guess, assume or generate unsupported details.
- Never provide general industry practices.
- Never speculate or fill in missing info with your own knowledge.
- **Only use facts explicitly stated in knowledgebase**.

### System Operations
- **Never** suggest contacting customer support.
- Always use `hang_up` tool to end conversation.
- **Do not use `hang_up` if any request is unresolved or process is unfinished**.

8. Multi-Agent Collaboration

Collaboration instructions define the interface between agents, keeping implementation details encapsulated within each subagent. Therefore, they should clearly specify the conditions or scenarios that should trigger a transfer to each subagent.

8.1. What the Supervisor Knows

In multi-agent architectures, the supervisor has limited visibility by design. This encapsulation ensures clean separation of concerns.

8.2. Writing Effective Collaboration Instructions

Collaboration instructions should be simple, explicit, and deterministic. Use the following principles:

• Always write from the supervisor’s perspective: Supervisor decides when to transfer, not how subagents work.
• Describe transfer conditions, not implementations
• Use clear, rule-based language: Prefer “If / Then” conditions over descriptive or narrative phrasing.
• Make order and timing explicit: Clearly state after which agent and before which agent the transfer must occur.

Language to Avoid vs. Use:

Example - Well-Written Collaboration Instruction:

Transfer the user to ProductResolutionAgent according to the rules below:

1. If the user has NOT been transferred to ProductSpecificAgent
   (because product-level handling was not required or multiple products were involved):
   → IMMEDIATELY transfer the user to ProductResolutionAgent
    → This happens right after ProductAndBrandAgent transfers the user back to you.

2. If the user has a single product that REQUIRED transfer to ProductSpecificAgent,
    → IMMEDIATELY transfer the user to ProductResolutionAgent
    → This happens right after ProductSpecificAgent transfers the user back to you.

IMPORTANT: This transfer **MUST ALWAYS occur BEFORE** transferring the user to AddressAgent.
Never ask questions and never mention transfers to the user.

9. Additional Info Area

The Additional Info section defines environmental context that the agent needs during conversations. This is where you inject dynamic variables.

What to Include:

• Current date and time: For time-sensitive operations
• User details: Name, account info, preferences
• Session-specific contexts: Extracted entities

Best Practices:

• Prioritize the most important information first.
• Keep variable definitions concise.
• Avoid redundant information.
• Always add variables at the end to optimize cached tokens.
• Add explanations before variables for clarity.

Example Template:

## Current Context
Today's date: %currentDate
Current time: %currentTime

## User Information
User name: %userName
Preferred language: %preferredLanguage
Location: %userLocation
Account type: %accountType

10. Pre-Deployment Checklist

Use this checklist before deploying any agent to production. Each item represents a common failure point.

1. Role Definition
   ☐ Role is defined in 2-3 sentences maximum
   ☐ Scope of responsibility is explicitly stated
   ☐ Out-of-scope items are explicitly excluded

2. Process Definition
   ☐ All steps are numbered clearly
   ☐ Each step focuses on one action
   ☐ Decision points use if/then format
   ☐ Edge cases are handled

3. Rules & Constraints
   ☐ Critical rules use "Always" and "Never"
   ☐ No contradicting rules exist
   ☐ Escape hatches are defined for unknown situations
   ☐ Tool usage is explicitly specified

4. Tool Configuration
   ☐ Tool names follow verb_noun convention
   ☐ Descriptions explain WHAT, instructions explain WHEN
   ☐ Required vs. optional parameters are clearly marked
   ☐ Error handling is documented in instructions
   ☐ Tool results are interpretable by all agents (if multi-agent)

5. Voice-Specific (if applicable)
   ☐ Responses are 1-2 sentences maximum
   ☐ No visual action words (click, type, see)
   ☐ Only one question per turn

6. Multi-Agent (if applicable)
   ☐ Transfer conditions are explicit (If/Then)
   ☐ Transfer order/timing is specified
   ☐ "Never mention transfers" rule is included

7. Quality Assurance
   ☐ Intern Test passed - a new hire could follow these instructions
   ☐ Terminology is consistent throughout
   ☐ No soft/ambiguous language remains
   ☐ Formatting matches model provider recommendations