V4 - CoachingAgent - Warenga¶

An AI-powered coaching agent that provides personalized business mentorship to young Kenyan entrepreneurs through natural conversation in Sheng, Swahili, and English. The agent adapts its coaching style based on session type and maintains conversation history while offering tools for point rewards, crisis alerts, and micro-action management.

Purpose¶

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

Based on the workflow implementation, this appears to be part of a youth entrepreneurship coaching platform called SIFA that: - Provides 24/7 business coaching to young Kenyan entrepreneurs (18-35 years old) - Delivers culturally relevant guidance in local languages (Sheng/Swahili/English mix) - Tracks daily business activities and assigns actionable micro-tasks - Offers crisis intervention and peer support systems - Gamifies engagement through a points-based reward system

How It Works¶

Trigger Reception: The workflow receives a coaching request with user details, query, and session context
Prompt Construction: A comprehensive system prompt is built based on the session type (general, evening coaching, credit coaching, profit coaching, or midday check-in)
AI Processing: The AI agent processes the user's message using the constructed prompt, conversation history, and available tools
Memory Integration: Previous conversations are retrieved from PostgreSQL to maintain context across sessions
Tool Execution: The agent can award points, trigger crisis alerts, or save new micro-actions as needed
Response Formatting: The AI's response is formatted and returned with success status and metadata

Workflow Diagram¶

graph TD
    A[When Executed by Another Workflow] --> B[Build System Prompt]
    B --> C[AI Agent]
    C --> D[Format Output]

    E[Postgres Chat Memory] --> C
    F[OpenRouter Chat Model] --> C
    G[awardPoints Tool] --> C
    H[triggerCeaAlert Tool] --> C
    I[saveMicroaction Tool] --> C

Trigger¶

Type: Execute Workflow Trigger

Required Inputs: - phoneNumber - User's phone number for session identification - query - User's message or question - channel - Communication channel (default: whatsapp) - firstName - User's first name (default: rafiki) - sessionType - Type of coaching session (general, evening_coaching, credit_coaching, profit_coaching, midday_coaching) - sessionContext - JSON string containing user context and session data

Nodes Used¶

Node Type	Purpose
Execute Workflow Trigger	Receives coaching requests from other workflows
Code (Build System Prompt)	Constructs dynamic system prompts based on session type and user context
AI Agent	Processes user queries using LangChain with tools and memory
Postgres Chat Memory	Maintains conversation history across sessions
OpenRouter Chat Model	Provides Google Gemini 2.5 Flash LLM capabilities
Workflow Tools (3x)	awardPoints, triggerCeaAlert, saveMicroaction
Code (Format Output)	Standardizes response format for calling workflows

External Services & Credentials Required¶

OpenRouter API: - Credential: sifa_dev_env - Model: google/gemini-2.5-flash - Used for: AI language processing

PostgreSQL Database: - Credential: sifaV4Dev - Used for: Chat history storage and retrieval

Connected Workflows: - Award Points Workflow (ID: JmJObsTea34h5bjX) - CEA Alert Workflow (ID: 18JMmGhWiZKvjhS8) - Save Micro-action Workflow (ID: cNnkBA3Cuks1p1wi)

Environment Variables¶

No explicit environment variables are defined in this workflow. Configuration is handled through: - n8n credential system for API keys - Workflow input parameters for dynamic configuration - Database connections for persistent storage

Data Flow¶

Input:

{
  "phoneNumber": "string",
  "query": "string", 
  "channel": "string",
  "firstName": "string",
  "sessionType": "string",
  "sessionContext": "JSON string"
}

Output:

{
  "output": "string",
  "outputType": "plain",
  "outputOptions": [],
  "success": true,
  "message": "string",
  "phoneNumber": "string",
  "sessionType": "string"
}

Error Handling¶

OpenRouter Model: Configured with retry logic (3 attempts, 1.5s intervals)
Fallback Response: Returns "Samahani, kuna tatizo. Jaribu tena baadaye." if AI processing fails
Context Parsing: Gracefully handles malformed JSON in sessionContext with empty object fallback
Tool Failures: Individual tool failures don't break the main conversation flow

Known Limitations¶

Maximum 250 words per response to maintain WhatsApp compatibility
Context window limited to 30 previous messages
Session memory tied to phone number (single device assumption)
Crisis intervention limited to business hours (Mon-Fri 8AM-5PM) for human support
Language model dependent on OpenRouter service availability

This workflow integrates with several other workflows: - Award Points System: Manages gamification and user engagement tracking - CEA Alert System: Handles crisis intervention and human escalation - Micro-action Management: Saves and tracks daily business tasks - Parent Orchestration Workflows: Likely triggered by WhatsApp or web interfaces

Setup Instructions¶

Import Workflow: Import the JSON into your n8n instance
Configure Credentials:
- Create OpenRouter API credential named sifa_dev_env
- Set up PostgreSQL credential named sifaV4Dev with chat history table access
Set Up Connected Workflows:
- Import and configure the three tool workflows (awardPoints, triggerCeaAlert, saveMicroaction)
- Update workflow IDs in the tool nodes if they differ
Database Setup:
- Ensure PostgreSQL has the n8n_chat_histories table for memory storage
- Verify database permissions for read/write operations
Test Configuration:
- Execute with sample inputs to verify all tools and memory work correctly
- Test different session types to ensure prompt generation works properly
Integration:
- Connect this workflow to your messaging platform or web interface
- Ensure calling workflows pass all required input parameters