Defining SimpleSaaS

Before we code, let’s define what we’re building.

SimpleSaaS is a fake subscription management platform. Users can:

• Sign up for plans (Basic, Pro, Enterprise)
• Manage their subscriptions
• Access support

Our agent helps with support questions.

Three Main Tasks

The agent handles three types of requests:

1. Answer FAQs

Questions like:

• “What is SimpleSaaS?”
• “How do I change my plan?”
• “What features are in the Pro plan?”

How it works: Agent searches a knowledge base and answers directly. No tools needed.

2. Check Subscription Status

Questions like:

• “What’s my current plan?”
• “When does my subscription expire?”
• “Is my account active?”

How it works: Agent calls get_subscription_status tool with user_id, then answers based on the result.

3. Escalate to Human

Situations like:

• Billing disputes (“I want a refund”)
• Account deletion requests
• Legal questions
• Angry or frustrated users

How it works: Agent detects sensitive keywords or tone, then escalates immediately.

Inputs and Outputs

Let’s be specific about what goes in and comes out.

Input

{
    "message": "What's my subscription status?",
    "user_id": "user-123"  # Optional, for authenticated users
}

Output

The agent returns one of three things:

Direct Answer:

{
    "type": "answered",
    "reply": "Your current plan is Pro, active until Dec 1, 2025.",
    "tag": "faq"
}

Tool Used:

{
    "type": "tool_used",
    "reply": "Your subscription is active on the Pro plan.",
    "tag": "subscription_check",
    "tool_calls": [...]
}

Escalated:

{
    "type": "escalated",
    "reason": "Billing dispute detected",
    "suggested_reply": "I'm connecting you with our billing team..."
}

Designing Tools

Tools are functions the agent can call. Keep them small and predictable.

Tool 1: get_faq_answer

Purpose: Search the knowledge base for FAQ answers.

Input:

{
    "question": "What is SimpleSaaS?"
}

Output:

{
    "answer": "SimpleSaaS is a subscription management platform...",
    "source": "faq_001"
}

Why it’s safe: Read-only. Can’t change anything.

Tool 2: get_subscription_status

Purpose: Get user’s current subscription info.

Input:

{
    "user_id": "user-123"
}

Output:

{
    "plan": "Pro",
    "status": "active",
    "expires": "2025-12-01",
    "features": ["feature1", "feature2"]
}

Why it’s safe: Read-only. Verifies user_id exists first.

Tool 3: log_escalation

Purpose: Log that we’re escalating to human.

Input:

{
    "user_id": "user-123",
    "message": "I want a refund",
    "reason": "billing_dispute"
}

Output:

{
    "ticket_id": "TICKET-12345",
    "status": "created"
}

Why it’s safe: Only creates a log entry. Doesn’t take action.

What We’re NOT Building

Important: We’re not giving the agent direct database access. Instead:

• Tools are wrappers around safe functions
• Each tool has clear inputs and outputs
• Tools can’t do dangerous things (delete, modify, etc.)

This keeps the agent predictable.

Escalation Rules

The agent escalates when:

1. Sensitive Keywords

Words like:

• “refund”
• “chargeback”
• “cancel”
• “delete account”
• “legal”
• “lawsuit”

2. Billing Disputes

Any message about:

• Unauthorized charges
• Billing errors
• Payment issues

3. Account Deletion

Requests to:

• Delete account
• Remove data
• Cancel permanently

4. Tone Detection

Messages that seem:

• Angry or frustrated
• Threatening
• Extremely urgent

5. Uncertainty

When the agent isn’t confident it can help safely.

Scenario Planning

Let’s map out how the agent handles different scenarios:

Scenario: Simple FAQ

Input: “What is SimpleSaaS?”

Flow:

1. Agent receives message
2. Checks if it’s in knowledge base
3. Finds answer
4. Returns directly

No tools needed.

Scenario: Subscription Check

Input: “What’s my current plan?”

Flow:

1. Agent receives message + user_id
2. Decides it needs subscription data
3. Calls get_subscription_status(user_id)
4. Gets result: {plan: "Pro", status: "active"}
5. Formats answer: “Your current plan is Pro and it’s active.”

One tool call.

Scenario: Billing Dispute

Input: “I want a refund for last month”

Flow:

1. Agent receives message
2. Detects keyword “refund”
3. Immediately escalates (no tool calls)
4. Logs escalation with log_escalation
5. Returns: “I’m connecting you with our billing team…”

Escalation, no answer.

Design Checklist

Before we code, make sure you’ve decided:

• What the agent can do (scope)
• What tools it needs
• When it should escalate
• What inputs it accepts
• What outputs it returns
• Safety boundaries

Interactive: Order the Agent Flow

Put these steps in the correct order for handling a subscription check:

Key Design Principles

Remember these as you build:

1. Keep tools small - One job per tool
2. Make tools safe - Read-only when possible
3. Clear boundaries - Agent knows what it can’t do
4. Escalate early - Better safe than sorry
5. Predictable behavior - Same input should give same output

What’s Next?

Now that we’ve designed the agent, let’s implement it. The next page shows you how to define tools and write the system prompt.