Skip to content

Francis - SalesTrackingAgent

A sophisticated AI-powered business coaching workflow that provides personalized guidance to young entrepreneurs in Kenya through WhatsApp and SMS. The system manages user onboarding, tracks daily sales and profit data, provides micro-actions for business improvement, and escalates welfare concerns to Community Education Advisors (CEAs) when needed.

Purpose

No business context provided yet — add a context.md to enrich this documentation.

Based on the workflow implementation, this system appears to serve young entrepreneurs in Kenya's Makueni County as part of the Educate! Kenya program. It helps users track daily business performance, understand profit calculations, manage customer credit, and receive actionable business advice through an AI coach named "Sifa."

How It Works

  1. Message Reception: The workflow receives incoming messages with phone number, query text, and communication channel (WhatsApp/SMS)
  2. User Data Retrieval: Fetches user profile, business records, chat history, and credit information from the database
  3. Intent Routing: An AI router analyzes the message and determines whether to use the main coaching agent or a lighter engagement agent
  4. AI Processing: The selected agent processes the message using extensive business coaching prompts, considering user status, time context, and conversation history
  5. Tool Integration: The AI can call various tools to update user data, record sales information, or save credit tracking details
  6. Response Generation: Generates contextually appropriate responses in the user's preferred language (Swahili, English, or Sheng)
  7. Data Logging: Saves the conversation to chat logs and triggers any necessary alerts to CEAs
  8. Error Handling: Provides fallback responses and logs errors when the AI agents fail

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[Reset Daily Flags]
    B --> C[Get User Record]
    C --> D[Get Profit Data]
    C --> E[Get Credit Record]
    C --> F[Get Pending Daytime Messages]

    D --> G[Get Chat History]
    G --> H[Limit Chat History]
    H --> I[Aggregate Chat History]

    D --> J[Aggregate Business Records]
    E --> K[Aggregate Credit Record]
    F --> L[Aggregate Pending Messages]

    I --> M[Merge Data]
    J --> M
    K --> M
    L --> M

    M --> N[Aggregate All Data]
    N --> O[Chat and Business History]
    O --> P[Intent Router]

    P --> Q{Route Decision}
    Q -->|Main Agent| R[AI Agent]
    Q -->|Engagement Agent| S[Engager Agent]

    R --> T[Extract Messages]
    S --> U[Extract Messages 1]

    T --> V[Insert Chat Log]
    U --> W[Insert Chat Log 2]

    V --> X[Set Output Field]
    W --> Y[Set Output Field 2]

    R -.->|Tools| Z[Daily Sales Data Collection]
    R -.->|Tools| AA[Update User Data Tool]
    R -.->|Tools| BB[Update User Status Tool]
    R -.->|Tools| CC[Save Credit Record Tool]
    R -.->|Tools| DD[Message Templates]
    R -.->|Tools| EE[Think Tool]

    R -->|Error| FF[Log Agent Error]
    S -->|Error| FF
    FF --> GG[Agent Fallback Message]

Trigger

This workflow is triggered by another workflow via the "Execute Workflow Trigger" node. It expects three input parameters: - phoneNumber: User's phone number identifier - query: The message text from the user - channel: Communication channel (WhatsApp, SMS, etc.)

Nodes Used

Node Type Purpose
Execute Workflow Trigger Receives calls from other workflows with user message data
Postgres Retrieves and stores user data, business records, chat history, and credit information
AI Agent Main business coaching agent with comprehensive prompts for user guidance
AI Agent (Engager) Lighter conversational agent for casual interactions
Intent Router AI-powered routing to determine which agent should handle the message
LangChain Memory Maintains conversation context using PostgreSQL storage
Tool Workflow Calls external workflows for data operations and user management
Aggregate Combines multiple data sources into single objects
Merge Combines different data streams
Set Data transformation and field extraction
If Conditional routing based on agent selection
Limit Restricts chat history to recent messages
Code Custom JavaScript for data parsing and formatting

External Services & Credentials Required

  • PostgreSQL Database (PostgresOnSupabase): Stores user data, business records, chat logs, and credit information
  • OpenRouter API (OpenRouter account): Provides access to various AI language models including GPT-5.2 and Claude Sonnet

Environment Variables

No explicit environment variables are defined in this workflow. Configuration is handled through: - Database connection credentials - OpenRouter API credentials - Workflow-specific parameters and prompts

Data Flow

Input: - Phone number (string) - User query/message (string) - Communication channel (string)

Processing: - Retrieves user profile and business history - Analyzes message intent and context - Routes to appropriate AI agent - Generates contextually relevant responses - Updates database records as needed

Output: - Formatted response message for the user - Updated conversation logs - Potential alerts to Community Education Advisors - Error logs if processing fails

Error Handling

The workflow includes comprehensive error handling: - Agent Failures: Both AI agents have error outputs that route to error logging - Fallback Messages: When agents fail, a fallback message is provided to users - Error Logging: Failed interactions are logged to an errorLog table with details - Graceful Degradation: Users always receive a response, even if it's a generic fallback

Known Limitations

Based on the workflow structure: - Requires active PostgreSQL database connection - Dependent on OpenRouter API availability - Complex prompt engineering may need regular updates - SMS character limits (160 chars) require careful message formatting - Multiple language support requires ongoing prompt maintenance

The workflow calls several external workflows as tools: - dailySalesDataCollection (fBc6cSMp9Wz1brlZ): Records daily business data - updateUserDataTool (xVkMVJOCq5ptCOHj): Updates user profile information - updateUserStatusTool (nfVcA8ei8x9dE06Z): Manages user onboarding status - messageTemplates (IIuvQx5MoV7CkTAJ): Provides message templates - saveCreditRecordTool (sHQtICupLdgJd4sK): Manages credit tracking data - create_business_summary_for_youth (Z9ekLMmXz9mHDKut): Generates business summaries

Setup Instructions

  1. Import Workflow: Import the JSON into your n8n instance
  2. Configure Database:
    • Set up PostgreSQL database with required tables
    • Configure PostgresOnSupabase credential
  3. Set Up AI Access:
    • Create OpenRouter account
    • Configure OpenRouter account credential
  4. Deploy Sub-workflows: Ensure all referenced tool workflows are deployed and accessible
  5. Test Integration: Use the manual trigger to test with sample data
  6. Configure Triggers: Set up the calling workflow to trigger this one with proper parameters
  7. Monitor Logs: Check error logs and chat logs to ensure proper operation
  8. Language Customization: Adjust prompts for local language variations if needed

The workflow is designed to be self-contained once properly configured, with extensive error handling and fallback mechanisms to ensure reliable operation in production environments.