DEV Community: Sospeter Mong'are

RAG Is Not an AI Agent

Sospeter Mong'are — Fri, 10 Jul 2026 07:11:23 +0000

One of the biggest misconceptions in AI today is treating Retrieval-Augmented Generation (RAG) and AI agents as the same thing.

They're not.

RAG improves an LLM's ability to answer questions using external knowledge. AI agents go a step further by reasoning, planning, making decisions, and taking actions.

Understanding the difference will help you design better AI systems and avoid using the wrong architecture for the job.

What is RAG?

Retrieval-Augmented Generation (RAG) is an architecture that gives an LLM access to information outside its training data.

Instead of relying solely on what the model learned during training, it retrieves relevant documents from a knowledge base and includes them in the prompt before generating a response.

Think of RAG as "open-book AI."

RAG Architecture

          User Question
                 │
                 ▼
        Embed the Question
                 │
                 ▼
         Vector Database
                 │
       Retrieve Documents
                 │
                 ▼
      Prompt + Retrieved Context
                 │
                 ▼
                LLM
                 │
                 ▼
             Final Answer

The LLM does not search the internet by itself or decide what action to take. It simply answers using the retrieved context.

What RAG Does Well

RAG is excellent when your AI needs accurate, up-to-date, or organization-specific information.

Common use cases include:

Internal company knowledge bases
Customer support chatbots
HR policy assistants
Product documentation
Legal document search
Medical reference systems
Financial knowledge assistants

Instead of retraining an LLM every time information changes, you simply update the knowledge base.

Where RAG Ends

This is where many people get confused.

A RAG system can retrieve information and generate an answer.

It cannot inherently:

Decide which tool to use
Execute code
Send emails
Book meetings
Query multiple systems intelligently
Break large tasks into smaller ones
Plan multiple steps
Retry after failures
Decide whether another search is needed

For example:

"Find all unpaid invoices and email each customer."

A RAG system cannot complete this task.

It might explain how to do it, but it won't actually perform the work.

Where AI Agents Begin

AI agents are built for decision-making and action.

Instead of following one fixed pipeline, an agent reasons about the task before deciding what to do next.

A typical agent can:

Understand the objective
Create a plan
Choose the right tool
Execute the tool
Evaluate the result
Try another approach if needed
Continue until the goal is achieved

AI Agent Architecture

              User Request
                    │
                    ▼
                 Planner
                    │
      ┌─────────────┼─────────────┐
      ▼             ▼             ▼
 Search Web     Query Database   Run Code
      │             │             │
      └─────────────┼─────────────┘
                    ▼
              Evaluate Result
                    │
          Need Another Step?
            Yes           No
             │             │
             ▼             ▼
       Choose Next Tool   Final Answer

Notice the difference.

The workflow isn't fixed.

The agent decides what to do while solving the problem.

The Key Difference

A RAG pipeline follows a predefined sequence:

Retrieve → Generate → Respond

An agent follows a reasoning loop:

Think → Plan → Choose Tool → Execute → Observe → Repeat

One retrieves knowledge.

The other solves problems.

Can an AI Agent Use RAG?

Absolutely.

In fact, many production AI agents use RAG as one of their tools.

For example:

                 AI Agent
                     │
     ┌───────────────┼────────────────┐
     ▼               ▼                ▼
     RAG         SQL Database      Calendar API
     │               │                │
     └───────────────┼────────────────┘
                     ▼
              Final Response

Here, RAG is simply one capability among many.

The agent decides when to retrieve documents and when to use other tools.

When Should You Use RAG?

Choose RAG when your goal is to answer questions using trusted knowledge.

Examples:

Company documentation chatbot
University handbook assistant
Product manuals
Insurance policy lookup
Research assistant
FAQ systems

If users mainly ask questions, RAG is often enough.

When Should You Use an AI Agent?

Choose an AI agent when the system needs to make decisions or perform actions.

Examples:

Schedule meetings
Generate reports from multiple systems
Process invoices
Customer service workflows
Software engineering assistants
DevOps automation
Data analysis
Multi-step business processes

If the task involves reasoning, planning, or interacting with multiple tools, an agent is the better fit.

RAG vs AI Agent at a Glance

Feature	RAG	AI Agent
Retrieves knowledge	✅	✅
Answers questions	✅	✅
Uses external tools	Limited	✅
Makes decisions	❌	✅
Plans multiple steps	❌	✅
Executes actions	❌	✅
Adapts workflow dynamically	❌	✅
Retries after failures	❌	✅

Final Thoughts

RAG and AI agents aren't competing technologies.

They're complementary.

RAG gives an AI access to knowledge.

AI agents give an AI the ability to reason, decide, and act.

A useful way to remember it is:

RAG = LLM + Your Data

AI Agent = LLM + Memory + Planning + Tools + State

Production AI = Agent + RAG + Reliable Infrastructure

The most capable AI systems today don't choose between RAG and agents. They combine both. The agent decides what needs to be done, while RAG ensures it has the right information to do it well.

LangChain & LangGraph Concepts You Should Know

Sospeter Mong'are — Fri, 10 Jul 2026 05:58:30 +0000

Here are five foundational LangChain and LangGraph concepts every AI engineer should understand.

1. Chains (The AI Workflow)

A chain is a sequence of steps where the output of one step becomes the input of the next.

Example:

User Question
      ↓
Retrieve Documents
      ↓
LLM Generates Answer
      ↓
Format Response

Think of it as a pipeline for AI tasks.

2. Tools (Giving AI Superpowers)

LLMs only know what was in their training data.

Tools let them interact with the outside world.

Examples include:

Search the web
Query SQL databases
Call REST APIs
Execute Python code
Read PDFs
Send emails

Instead of only generating text, the AI can now do things.

3. Memory (Remembering Conversations)

Memory allows an AI to remember information across interactions.

Without memory:

User: My name is Sam.
...
User: What's my name?

AI: I don't know.

With memory:

AI: Your name is Sam.

Memory can be:

Short-term (current conversation)
Long-term (saved facts)
Semantic memory (knowledge)
Episodic memory (past interactions)

4. Agents (Reason + Choose Tools)

An agent doesn't follow a fixed workflow.

Instead, it:

Understands the goal
Decides what to do
Chooses the right tool
Executes it
Evaluates the result
Repeats until the task is complete

Example:

User:
"Find the latest exchange rate and calculate how much 250 USD is in KES."

Agent:
→ Search exchange rate
→ Use calculator
→ Return final answer

The workflow is dynamic rather than predetermined.

5. Graphs (LangGraph's Superpower)

Traditional chains are linear.

LangGraph introduces graphs, where execution can branch, loop, pause, or resume.

Example:

          Start
             │
             ▼
      Understand Task
        ┌────┴────┐
        ▼         ▼
   Search Web   Query Database
        │         │
        └────┬────┘
             ▼
      Evaluate Results
        ┌────┴────┐
     Good?      No
       │         │
       ▼         │
    Final Answer │
                 │
                 ▼
          Try Another Tool

This makes LangGraph ideal for building autonomous AI agents that can recover from errors, make decisions, and manage complex workflows.

A Simple Way to Remember

LangChain = LLM + tools + workflows
Agents = LangChain + reasoning + tool selection
LangGraph = Agents + state + loops + branching + durable execution

If you're learning modern AI engineering, mastering these five concepts will give you a strong foundation for building production-ready AI applications.

Understanding Integration Runtimes in Azure Data Factory (ADF)

Sospeter Mong'are — Thu, 02 Jul 2026 12:54:49 +0000

When people begin learning Azure Data Factory (ADF), one concept that often causes confusion is the Integration Runtime (IR). Pipelines, datasets, and linked services are fairly intuitive, but many beginners wonder:

"If Azure Data Factory orchestrates everything, what exactly is an Integration Runtime?"

The simplest answer is this:

An Integration Runtime is the compute infrastructure that Azure Data Factory uses to move data, transform data, and execute activities.

Think of Azure Data Factory as the brain that plans the work, while the Integration Runtime is the muscle that carries it out.

Why Do We Need an Integration Runtime?

Imagine you're a logistics manager.

You create a schedule for transporting goods from Nairobi to Mombasa. You know what should be transported, when it should leave, and where it should arrive.

However, without a truck, nothing actually moves.

Azure Data Factory works the same way.

A pipeline defines what should happen, but the Integration Runtime is responsible for actually performing the work.

It is responsible for:

Moving data between different data sources
Running data transformation jobs
Connecting securely to cloud and on-premises systems
Executing activities within your pipeline

Without an Integration Runtime, your pipeline has instructions but no execution engine.

Types of Integration Runtime

Azure Data Factory provides three types of Integration Runtime, each designed for different scenarios.

1. Azure Integration Runtime

This is the default Integration Runtime provided and managed by Microsoft.

You don't install or maintain any servers. Azure automatically provisions and scales the compute resources needed to execute your workloads.

It is ideal when your data resides entirely in the cloud.

Common use cases include:

Copying data from Azure SQL Database to Azure Data Lake
Moving data between cloud storage accounts
Running Mapping Data Flows
Executing cloud-native activities

A typical architecture looks like this:

Azure SQL Database
        │
        ▼
Azure Integration Runtime
        │
        ▼
Azure Data Lake Storage

Advantages

Fully managed by Microsoft
Automatically scales
No infrastructure to maintain
Highly available

For most cloud-to-cloud data movement, Azure Integration Runtime is the recommended choice.

2. Self-hosted Integration Runtime (SHIR)

What happens if your data is not in Azure?

Suppose your organization has an on-premises SQL Server inside a corporate network protected by a firewall.

Azure Data Factory cannot directly access it.

This is where the Self-hosted Integration Runtime comes in.

The Self-hosted IR is software that you install on a Windows machine, virtual machine, or server within your network.

It acts as a secure bridge between Azure and your private environment.

Example architecture:

On-Prem SQL Server
        │
        ▼
Self-hosted Integration Runtime
        │
        ▼
Azure Blob Storage

Because the runtime resides inside your network, it can securely communicate with your local databases while also communicating with Azure Data Factory.

Common use cases

SQL Server
Oracle Database
MySQL
PostgreSQL
SAP
Local file servers
Private APIs
Any data source behind a firewall

This is one of the most commonly used Integration Runtimes in enterprise environments.

3. Azure SSIS Integration Runtime

Many organizations have existing ETL processes built using SQL Server Integration Services (SSIS).

Rather than rebuilding those packages from scratch, Azure allows you to run them in the cloud using Azure SSIS Integration Runtime.

Example:

SSIS Package
      │
      ▼
Azure SSIS Integration Runtime
      │
      ▼
Azure SQL Database

This option is mainly used during cloud migration projects where businesses want to continue using their existing SSIS investments.

A Real-World Example

Imagine you work for a bank.

Every night, customer transactions stored in an on-premises SQL Server need to be copied into Azure Data Lake for reporting and analytics.

The architecture would look something like this:

ADF Pipeline
      │
      ▼
Self-hosted Integration Runtime
      │
      ▼
On-Prem SQL Server
      │
      ▼
Azure Data Lake Storage

Here's what happens:

The pipeline starts according to a schedule.
Azure Data Factory sends the job to the Self-hosted Integration Runtime.
The Self-hosted IR connects to the SQL Server.
It reads the required data.
It securely transfers the data into Azure Data Lake.
The pipeline completes successfully.

Notice that Azure Data Factory never directly connects to the SQL Server. The Self-hosted Integration Runtime performs that task.

Which Integration Runtime Should You Use?

The choice depends on where your data resides and what type of workload you're running.

Scenario	Recommended Integration Runtime
Azure SQL Database to Azure Blob Storage	Azure Integration Runtime
Azure SQL Database to Azure Data Lake	Azure Integration Runtime
SQL Server on-premises to Azure	Self-hosted Integration Runtime
Oracle behind a firewall	Self-hosted Integration Runtime
Local files to Azure Storage	Self-hosted Integration Runtime
Running Mapping Data Flows	Azure Integration Runtime
Running existing SSIS packages	Azure SSIS Integration Runtime

Understanding the Difference Between Pipelines and Integration Runtime

One common misconception among beginners is assuming that pipelines execute the work.

They don't.

A pipeline is simply an orchestration layer.

Think of the relationship this way:

Pipeline decides what should happen.
Activity defines the specific task.
Linked Service stores the connection information.
Dataset represents the data being used.
Integration Runtime performs the actual work.

Without an Integration Runtime, the pipeline has instructions but no execution engine.

A Simple Analogy

Imagine you're running a courier company.

The customer places an order.
The operations manager plans the delivery.
The address tells the driver where to collect and deliver the package.
The package is the data.
The truck transports the package.

In Azure Data Factory:

Customer order = Business requirement
Pipeline = Delivery plan
Activity = Delivery task
Linked Service = Pickup and destination addresses
Dataset = The package
Integration Runtime = The truck

Without the truck, nothing gets delivered.

Final Thoughts

Integration Runtime is one of the most important concepts in Azure Data Factory because it is responsible for executing your data integration workloads.

Choosing the correct Integration Runtime depends on your environment:

Use Azure Integration Runtime for cloud-to-cloud data movement and transformations.
Use Self-hosted Integration Runtime when accessing on-premises or private network resources.
Use Azure SSIS Integration Runtime when migrating or running existing SSIS packages in Azure.

Once you understand the role of the Integration Runtime, Azure Data Factory becomes much easier to visualize. Instead of thinking of it as just another Azure service, you'll see it as a complete orchestration platform where pipelines coordinate the work, and Integration Runtimes provide the execution power that makes everything happen.

How to Install Apache Airflow 3.1.3 on WSL (Windows Subsystem for Linux)

Sospeter Mong'are — Wed, 01 Jul 2026 07:46:51 +0000

What is Apache Airflow?

Apache Airflow is an open-source platform used to programmatically author, schedule, and monitor workflows. It's widely used in data engineering, MLOps, and backend automation pipelines. If you're building ETL pipelines, running scheduled tasks, or orchestrating complex workflows, Airflow is a tool you'll likely encounter.

Airflow 3 is a major upgrade from Airflow 2 - it introduces a new React-based UI, a dedicated API server (replacing the old webserver), improved task isolation via the Task SDK, and better scalability overall.

Prerequisites

Before we begin, make sure you have the following in place:

1. Windows Subsystem for Linux (WSL2) installed

You need WSL 2 with Ubuntu 24.04 (Noble) installed on your Windows machine. If you haven't set it up yet, open PowerShell as Administrator and run:

wsl --install

Restart your machine when prompted, then launch Ubuntu from the Start menu.

Important: Always work inside the Linux home directory (~), not a Windows-mounted path like /mnt/c/.... Performance and file permission issues can occur on mounted drives.

2. MobiXterm or Windows Terminal (optional but recommended)

Either gives you a better terminal experience for working inside WSL.

3. Basic familiarity with the Linux terminal

You don't need to be a Linux expert, but knowing how to navigate directories (cd, ls) and run commands will help.

Step 1: Update Your System

Open your WSL terminal and run:

sudo apt update && sudo apt upgrade -y

This ensures your package lists and installed packages are up to date.

Step 2: Install Python 3 and Check the Version

Ubuntu 24.04 ships with Python 3.12 by default. Verify it's available:

python3 --version

You should see something like Python 3.12.x. Airflow 3.1.3 supports Python 3.10, 3.11, and 3.12 - so you're good.

If Python isn't installed:

sudo apt install python3 python3-dev python3-pip python3-venv -y

Step 3: Set Your AIRFLOW_HOME (Important - Do This First)

Airflow needs a home directory to store its configuration, logs, and database. Set this before installing Airflow so it knows where to store everything:

export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home

To make this permanent so it survives terminal restarts:

echo 'export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home' >> ~/.bashrc
source ~/.bashrc

Why this matters: If you skip this step, Airflow defaults to ~/airflow and may pick up config files from a previous Airflow installation, causing unexpected warnings or errors.

Step 4: Create a Project Directory and Virtual Environment

Create a dedicated folder for your Airflow 3.1.3 installation:

mkdir ~/airflow-3.1.3
cd ~/airflow-3.1.3

Create a virtual environment inside it:

python3 -m venv env

Activate the virtual environment:

source env/bin/activate

Your terminal prompt should now show (env) at the beginning:

(env) user@DESKTOP-XXXX:~/airflow-3.1.3$

Step 5: Upgrade pip

Before installing Airflow, upgrade pip to the latest version:

pip install --upgrade pip

Step 6: Install Apache Airflow 3.1.3 with Constraints

Install Airflow using the official constraints file. This is critical - Airflow has many dependencies, and the constraints file ensures compatible versions are installed together without conflicts:

pip install "apache-airflow==3.1.3" \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

This may take several minutes. Once complete, verify the installation:

airflow version

You should see:

3.1.3

Step 7: Install the FAB Auth Manager Provider

In Airflow 3, user authentication is handled by a separate provider package. Install it now:

pip install apache-airflow-providers-fab \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

Verify it's registered:

airflow providers list | grep fab

You should see:

apache-airflow-providers-fab  |  Flask App Builder ...  |  3.x.x

Step 7b: Set FAB as the Auth Manager (Critical)

This is the most important step that is easy to miss. Airflow 3 ships with a new lightweight SimpleAuthManager as the default. While it works for single-user local setups, it does not expose the airflow users CLI command - meaning you won't be able to create admin users from the terminal.

You must explicitly switch to the FAB auth manager.

Check what auth manager is currently set:

airflow config get-value core auth_manager

If it returns:

airflow.api_fastapi.auth.managers.simple.simple_auth_manager.SimpleAuthManager

You are on the wrong auth manager. Switch it by opening your airflow.cfg:

nano ~/airflow-3.1.3/airflow_home/airflow.cfg

Find the [core] section and change:

[core]
auth_manager = airflow.api_fastapi.auth.managers.simple.simple_auth_manager.SimpleAuthManager

To:

[core]
auth_manager = airflow.providers.fab.auth_manager.fab_auth_manager.FabAuthManager

Save and exit (Ctrl+O, Enter, Ctrl+X). Verify the change:

airflow config get-value core auth_manager

Should now return:

airflow.providers.fab.auth_manager.fab_auth_manager.FabAuthManager

SimpleAuthManager vs FabAuthManager:

SimpleAuthManager - Airflow 3's new default. Lightweight, no CLI user management, suited for single-user or automated setups

FabAuthManager - Full-featured auth manager from Flask AppBuilder. Supports CLI user creation, roles, permissions, and OAuth. Required for proper multi-user setups and for the airflow users command to work

Note: You may see a RemovedInAirflow4Warning about airflow.security.permissions being deprecated. This is harmless in 3.1.3 - it's just a heads-up that some internal FAB APIs will change in Airflow 4.

Step 8: Initialize the Airflow Database

Airflow 3 uses db migrate instead of the old db init command. This creates the metadata database and applies all schema migrations:

airflow db migrate

Step 9: Create an Admin User

airflow users create \
  --username admin \
  --firstname YourFirstName \
  --lastname YourLastName \
  --role Admin \
  --email your@email.com

You will be prompted to set a password. Type it carefully - input is hidden (no asterisks shown) in the terminal. Confirm it when prompted.

Tip: Remember this password - there's no plain-text copy stored anywhere. If you forget it, reset it with airflow users reset-password --username admin.

Step 10: Start the Airflow API Server and Scheduler

Airflow 3 requires three processes running simultaneously - the API server, the scheduler, and optionally the dag-processor (for larger setups). Open separate WSL terminal tabs or windows for each.

Terminal 1 - Start the API server:

cd ~/airflow-3.1.3
source env/bin/activate
export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home
airflow api-server --port 8080

Terminal 2 - Start the scheduler:

cd ~/airflow-3.1.3
source env/bin/activate
export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home
airflow scheduler

Note: In Airflow 3, airflow webserver has been replaced by airflow api-server. This is one of the key architectural changes from Airflow 2.

When the API server starts successfully you will see:

INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

And when the scheduler starts you will see:

INFO:     Starting the scheduler
INFO:     Loaded executor: LocalExecutor

Step 11: Access the Airflow UI

Open your browser and navigate to:

http://localhost:8080

You will see the new Airflow 3 React-based login page. Enter the username and password you created in Step 9.

You should now be inside the Airflow 3 Dashboard - ready to create and manage your DAGs!

Quick Reference: Starting Airflow After a Reboot

Every time you restart your machine and want to use Airflow, run these commands in separate terminals:

# All terminals: navigate, activate venv, and set AIRFLOW_HOME
cd ~/airflow-3.1.3
source env/bin/activate
export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home

# Terminal 1
airflow api-server --port 8080

# Terminal 2
airflow scheduler

If you added AIRFLOW_HOME to your ~/.bashrc in Step 3, the export is automatic and you can skip that line.

Airflow 3 vs Airflow 2 - Key Differences

If you're familiar with Airflow 2, here's what changed:

Airflow 2.x	Airflow 3.x
`airflow webserver`	`airflow api-server`
`airflow db init`	`airflow db migrate`
User management built into core	Requires `apache-airflow-providers-fab` + FAB set as auth manager
SequentialExecutor (default)	LocalExecutor (default)
`execution_date` in DAG context	`logical_date`
Flask-based UI	React-based UI
SubDAGs supported	SubDAGs removed (use TaskGroups)
SLA support	SLAs removed

Troubleshooting

`airflow users` command not found / invalid choice: 'users'

This has two possible causes - fix them in order:

Cause 1 - FAB provider not installed:

pip install apache-airflow-providers-fab \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

Cause 2 - Wrong auth manager set (most common):
Check your current auth manager:

airflow config get-value core auth_manager

If it shows SimpleAuthManager, switch it to FAB in airflow.cfg - see Step 7b above. This is the most common cause of the users command missing even after the FAB provider is installed.

Deprecation warnings about `[webserver]` settings

These occur when Airflow 3 picks up a config file from an old Airflow 2 installation. Make sure AIRFLOW_HOME points to a fresh directory and not ~/airflow (the Airflow 2 default).

`No module named 'airflow.providers.fab'` warning

The FAB provider isn't installed. See Step 7 above.

Forgot your admin password

Reset it without deleting the user:

airflow users reset-password --username admin

Port 8080 already in use

Either stop the other process using port 8080, or start the API server on a different port:

airflow api-server --port 8081

Summary of All Commands

# Set AIRFLOW_HOME (permanent)
echo 'export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home' >> ~/.bashrc
source ~/.bashrc

# Create project directory and virtual environment
mkdir ~/airflow-3.1.3 && cd ~/airflow-3.1.3
python3 -m venv env
source env/bin/activate

# Install Airflow with constraints
pip install --upgrade pip
pip install "apache-airflow==3.1.3" \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

# Install FAB auth manager provider
pip install apache-airflow-providers-fab \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

# Verify Airflow version
airflow version

# Set FAB as auth manager in airflow.cfg (under [core] section)
# auth_manager = airflow.providers.fab.auth_manager.fab_auth_manager.FabAuthManager

# Verify auth manager is set correctly
airflow config get-value core auth_manager

# Initialize database
airflow db migrate

# Create admin user
airflow users create --username admin --firstname YourFirstName \
  --lastname YourLastName --role Admin --email your@email.com

# Start services (separate terminals)
airflow api-server --port 8080    # Terminal 1
airflow scheduler                  # Terminal 2

What's Next?

Now that Airflow 3.1.3 is running, here are some things to explore next:

Write your first DAG - create a Python file in $AIRFLOW_HOME/dags/ to define a workflow
Explore the new UI - Airflow 3 ships with a brand new React-based interface with improved DAG views
Learn about Assets - Airflow 3 introduces Assets (formerly Datasets) for data-aware scheduling
Set up PostgreSQL - replace SQLite with PostgreSQL as the Airflow metadata backend for production use
Use the Task SDK - Airflow 3 ships with a standalone Task SDK for writing tasks in isolation

For the official Airflow 3 Quick Start guide, visit: https://airflow.apache.org/docs/apache-airflow/stable/start.html

Written based on a real installation walkthrough on WSL2 Ubuntu 24.04 (Noble) with MobiXterm.

How to Build an AI Agent (with Python Example)

Sospeter Mong'are — Tue, 30 Jun 2026 08:33:14 +0000

Artificial Intelligence is changing the way we build software. Instead of creating applications that simply follow predefined instructions, developers can now build AI agents that understand goals, make decisions, use tools, and complete tasks with minimal human intervention.

An AI agent is much more than a chatbot. It is a software system that can think through a problem, decide what actions to take, interact with external tools, remember previous interactions, and achieve a specific objective.

This guide walks you through the complete process of building an AI agent using the roadmap outlined below.

What is an AI Agent?

An AI agent is a program that:

Understands a user's request
Plans how to solve it
Uses tools when necessary
Remembers useful information
Returns the best possible answer

For example:

Instead of asking,

"What's today's weather?"

You could ask,

"Check today's weather, then tell me whether I should carry an umbrella and reschedule my outdoor meeting."

An AI agent can:

Understand the goal
Call a weather API
Analyze the forecast
Make a recommendation
Respond naturally

Step 1: Define the Purpose and Scope

Every AI agent starts with one important question:

What problem is this agent solving?

Without a clear purpose, the agent becomes confusing and unreliable.

Ask yourself:

Who will use it?
What tasks should it perform?
What should it never do?
How will success be measured?

Example

Suppose you are building a customer support agent.

Purpose:

Help customers answer common questions about orders.

Success criteria:

Answers within 5 seconds
90% accuracy
Escalates complex issues to humans

Constraints:

Cannot refund orders
Cannot change passwords
Cannot access customer payment information

Step 2: Design the System Prompt

The system prompt is the agent's personality and instruction manual.

It tells the AI:

Who it is
What its job is
What rules it should follow
How it should respond

Example:

You are a customer support assistant.

Your job is to answer customer questions politely.

If you don't know the answer,
say you don't know.

Never invent information.

A good prompt often matters more than choosing a larger model.

Step 3: Choose an LLM

The Large Language Model (LLM) is the agent's brain.

Popular options include:

GPT
Claude
Gemini
Llama
DeepSeek

Things to consider:

Cost

How much does each request cost?

Speed

How quickly does it respond?

Context Window

How much information can it remember in one conversation?

Accuracy

Does it perform well for your task?

For beginners, cloud-hosted models are the easiest place to start.

Step 4: Connect Tools

Without tools, an AI only knows what it has already learned.

With tools, it can:

Search databases
Call APIs
Read documents
Send emails
Execute code
Control applications

Examples:

Weather Agent

Tool:

Weather API

Finance Agent

Tool:

Bank API

Travel Agent

Tool:

Flight API

Programming Agent

Tool:

Python interpreter

Think of tools as giving your AI "hands."

Step 5: Add Memory

Most conversations require remembering previous information.

There are different types of memory.

Conversation Memory

Remember earlier messages.

Example:

User:

"My name is John."

Later...

Agent:

"Hello John."

Working Memory

Temporary memory while solving one task.

Example:

Reading multiple files before producing a report.

Long-Term Memory

Stores information for future conversations.

Example:

Favorite programming language.

Preferred writing style.

Frequently used APIs.

Many AI systems store memory using databases or vector databases.

Step 6: Orchestrate the Workflow

Real AI agents rarely perform just one action.

Instead, they execute a workflow.

Example:

User asks a question

↓

Understand request

↓

Choose tool

↓

Call API

↓

Analyze result

↓

Generate response

Frameworks like LangGraph and CrewAI help manage these workflows.

Step 7: Build a User Interface

Your AI needs a way to interact with users.

Common interfaces include:

Chat applications
Websites
Mobile apps
WhatsApp bots
Slack bots
REST APIs

The AI engine stays the same.

Only the interface changes.

Step 8: Test and Improve

Never assume your AI agent is perfect.

Test:

Wrong inputs
Missing information
Slow APIs
Invalid requests
Unexpected questions

Measure:

Accuracy
Speed
User satisfaction
Cost
Reliability

Then improve continuously.

The AI Agent Architecture

A complete AI agent usually looks like this:

User
   │
   ▼
User Interface
   │
   ▼
System Prompt
   │
   ▼
Large Language Model
   │
   ▼
Decision Making
   │
   ├──── Weather API
   ├──── Database
   ├──── Email Service
   ├──── Search Engine
   └──── Custom Functions
   │
   ▼
Memory
   │
   ▼
Final Response

A Simple AI Agent in Python

Let's build a very simple AI agent using Python and the OpenAI SDK.

First, install the package:

pip install openai

Set your API key:

export OPENAI_API_KEY="your-api-key"

Now create the agent.

from openai import OpenAI

client = OpenAI()

SYSTEM_PROMPT = """
You are a helpful programming assistant.

Explain concepts clearly.

If you don't know something,
say so honestly.
"""

def ask_agent(question):

    response = client.responses.create(
        model="gpt-5.5",
        input=[
            {
                "role": "system",
                "content": SYSTEM_PROMPT
            },
            {
                "role": "user",
                "content": question
            }
        ]
    )

    return response.output_text

while True:

    question = input("You: ")

    if question.lower() == "exit":
        break

    answer = ask_agent(question)

    print("\nAgent:", answer)

Running it:

You:
Explain Python decorators.

Agent:
Decorators are functions that modify the behavior of another function...

Congratulations!

You have built your first AI agent.

Extending the Agent with a Tool

Suppose we want the agent to answer the current time.

Instead of asking the AI to guess, we create a Python function.

from datetime import datetime

def get_current_time():
    return datetime.now().strftime("%H:%M:%S")

The agent can call this function whenever the user asks:

"What time is it?"

Instead of making up the answer, it retrieves the real system time.

This simple idea scales to many real-world tools, such as weather APIs, databases, email services, payment gateways, and search engines.

Real-World AI Agent Ideas

Once you understand the building blocks, you can create agents for almost any industry:

Customer support assistant
WhatsApp chatbot
Fundraising assistant
Medical appointment scheduler
Personal finance advisor
School management assistant
HR recruitment assistant
Sales assistant
Software debugging assistant
Content writing assistant

Each follows the same architecture: define a purpose, guide the model with a clear prompt, connect the right tools, maintain useful memory, orchestrate the workflow, provide an interface, and continuously test and improve.

Final Thoughts

Building an AI agent is not just about connecting an LLM to a chat window. A successful agent is designed around a clear goal, given the right instructions, equipped with tools to interact with the outside world, supported by memory to maintain context, and wrapped in a reliable workflow and user interface.

The good news is that you do not need to build everything at once. Start with a simple conversational agent, then gradually add tools, memory, and automation as your application grows. By following these eight steps, you will have a solid foundation for creating intelligent AI applications that solve real-world problems.

Understanding the Difference between Agents vs Automation

Sospeter Mong'are — Mon, 29 Jun 2026 06:36:05 +0000

Artificial Intelligence has brought the term "AI Agent" into almost every technology conversation. As a result, many people now use the words agent and automation interchangeably. While both are designed to reduce manual work and improve efficiency, they solve problems in fundamentally different ways.

Understanding this distinction is essential if you're building software, automating business processes, or deciding where AI fits into your organization.

What Is Automation?

Automation is designed to execute predefined instructions.

You tell the system exactly what to do, in what order, and under what conditions. Every time those conditions are met, it performs the same sequence of actions.

For example:

A customer submits a form.
An email is automatically sent.
A record is created in the database.
A notification is sent to the sales team.

Every step is predetermined. If the process changes, the workflow must be updated.

Automation excels at repetitive, predictable tasks where consistency is more important than decision-making.

What Is an AI Agent?

An AI agent is not focused on following instructions. It is focused on achieving a goal.

Instead of executing a rigid sequence of steps, an agent observes its environment, evaluates available information, makes decisions, and adjusts its actions as circumstances change.

If one approach fails, it can try another. If new information becomes available, it can revise its strategy without requiring a developer to define every possible scenario in advance.

In simple terms:

Automation asks:

"What steps should I execute?"

An agent asks:

"What is the best way to accomplish this objective?"

This ability to reason and adapt is what makes agents fundamentally different from traditional automation.

A Simple Example

Imagine you're booking a business trip.

An automated workflow might:

Book the airline you specified.
Reserve the hotel you selected.
Email you the itinerary.

It completes exactly what it was programmed to do.

An AI agent, however, could:

Compare multiple flights.
Choose the most cost-effective option.
Avoid long layovers.
Ensure arrival before your meeting.
Rebook automatically if a flight is cancelled.
Notify you of the changes.

The objective isn't to follow a checklist. The objective is to get you to your destination successfully.

When Automation Is the Better Choice

Despite the excitement around AI agents, automation remains the right solution for many business processes.

Choose automation when:

The workflow is predictable.
Business rules rarely change.
Compliance requires consistent execution.
Decisions are straightforward.
Speed and reliability matter more than flexibility.

Payroll processing, invoice generation, scheduled backups, and email notifications are all excellent examples of automation.

When an Agent Makes More Sense

An AI agent becomes valuable when the environment is dynamic and decisions cannot be fully predefined.

Use an agent when your system needs to:

Reason through complex situations.
Adapt to changing conditions.
Work toward goals rather than fixed procedures.
Handle uncertainty.
Decide between multiple possible actions.

Examples include customer support assistants, intelligent research systems, autonomous coding assistants, network troubleshooting agents, and procurement assistants that negotiate between vendors.

The Biggest Mistake

One of the biggest misconceptions in AI today is believing every workflow should become an agent.

It shouldn't.

Replacing a simple, deterministic process with an AI agent often introduces unnecessary complexity, higher costs, and less predictable behavior.

Likewise, trying to solve a complex, ever-changing problem with traditional automation can lead to brittle systems that constantly require manual updates.

The smartest solutions combine both approaches.

Automation handles the repetitive work, while agents take over where reasoning, judgment, and adaptability are required.

Final Thoughts

Automation follows instructions.

Agents pursue outcomes.

Automation delivers consistency through predefined workflows. Agents deliver adaptability through intelligent decision-making.

Neither is universally better. They solve different problems.

The future of software isn't choosing agents over automation. It's understanding when each is the right tool for the job, and combining them to build systems that are both efficient and intelligent.

How to Tell If a Task Needs an Agent or an Automation

Sospeter Mong'are — Sat, 27 Jun 2026 08:18:57 +0000

One of the biggest mistakes businesses make when adopting AI is trying to use an AI agent for every problem.

Not every task needs reasoning. Not every workflow needs an LLM. Sometimes a simple automation is faster, cheaper, and more reliable.

The question isn't "Can AI do this?"

The real question is:

"Does this task require thinking, or just doing?"

Rule #1: If the steps are always the same, automate it.

Traditional automation excels when the workflow is predictable.

Examples include:

Sending a welcome email after signup
Copying files between systems
Moving data from one database to another
Creating invoices every month
Backing up databases
Syncing CRM records

These tasks follow clear rules.

Trigger → Execute Steps → Finish

No decisions.
No reasoning.
No uncertainty.

This is where tools like Power Automate, Azure Logic Apps, n8n, Airflow, Zapier, or simple scripts shine.

Rule #2: If the task requires judgment, use an AI agent.

An agent becomes valuable when there isn't a fixed sequence of actions.

Instead, it has to decide:

What information is needed?
Which tool should I use?
Is the answer sufficient?
Should I ask the user another question?
Do I need to search somewhere else?

For example:

"Analyze this support ticket, search the customer's purchase history, check whether a refund qualifies under company policy, then draft an appropriate response."

Nobody hard-coded every possible path.

The agent reasons about the problem before acting.

Its workflow looks more like:

Goal
 ↓
Reason
 ↓
Choose Tool
 ↓
Observe Results
 ↓
Think Again
 ↓
Take Next Action

Rule #3: If the workflow contains uncertainty, you're entering agent territory.

Ask yourself:

Can I write every step beforehand?

If yes...

Automation.

If no...

An agent may be the better solution.

Consider these examples.

Automation:

"Every invoice goes to Finance."

Agent:

"Read the invoice and determine which department should approve it."

Automation:

"Archive every email older than 90 days."

Agent:

"Read the email and determine whether it's important enough to retain."

Automation:

"Generate a report every Monday."

Agent:

"Review this week's KPIs and explain the biggest business risks."

Rule #4: If the task only follows instructions, don't use AI.

Many teams build expensive AI systems that simply execute fixed logic.

That's overengineering.

If you already know the exact sequence of actions, a workflow engine is usually the better choice.

AI should solve uncertainty, not replace an if-statement.

Rule #5: Sometimes the best solution is both.

The most powerful enterprise systems combine automation with AI agents.

For example:

A customer submits a request.
An automation triggers the workflow.
An AI agent classifies the request.
The agent decides which internal systems to query.
Automation performs the approved actions.
The workflow updates the CRM and sends notifications.

Notice the difference.

Automation handles execution.

The agent handles decision-making.

Each does what it's best at.

A Simple Decision Framework

Before building anything, ask these five questions:

Are the steps predictable every time?
Does the system need to make decisions?
Will the workflow change depending on context?
Does it need to understand natural language?
Does it need to choose between multiple tools or actions?

If your answers are mostly:

Yes to predictable steps -> Automation
Yes to reasoning and decision-making -> Agent

Final Thought

Don't start with AI.

Start with the problem.

If the work is repetitive, automate it.

If the work requires understanding, reasoning, planning, and choosing the next action, build an agent.

The smartest systems aren't the ones with the most AI.

They're the ones that know when not to use it.

How to Apply for a Safaricom Paybill or Till Number

Sospeter Mong'are — Wed, 24 Jun 2026 21:01:58 +0000

If you run a business in Kenya, accepting M-PESA payments is no longer optional - it's a necessity. Whether you're a retailer, school, SACCO, freelancer, or landlord, having your own Paybill or Till number gives you a professional, trackable channel for receiving funds from customers.

This guide walks you through everything: what each product is, what documents you need, and the exact steps to apply - online or in person.

Paybill vs. Till Number - What's the Difference?

Before applying, you need to know which product fits your business.

Paybill Number is a business number that lets organizations collect payments from customers on a regular basis via M-PESA. When a customer pays, they enter both your Paybill number and an account reference (such as a meter number, invoice ID, student name, or membership number). This makes Paybill ideal for businesses that need to identify individual payers - schools, utilities, insurance firms, SACCOs, hospitals, and government agencies.

Till Number (Buy Goods) is a unique code that lets customers pay for goods and services directly into your M-PESA account. The customer only enters your Till number - no account reference needed. It's faster and simpler, and is the go-to choice for retail shops, restaurants, supermarkets, boutiques, fuel stations, and online sellers.

Feature	Paybill	Till Number
Account reference required	Yes	No
Ideal for	Regular collections, utilities, schools	Point-of-sale, retail, services
Settlement	Bank account	Owner's M-PESA or bank
Transaction fee (standard)	Varies by tariff	0.5%, capped at KSh 200

Paybill Products Available

When applying for a Paybill, Safaricom offers two variants:

Long-Term Paybill - The standard product for established businesses, institutions, and government entities. Requires valid business/company registration documents and is intended for ongoing, indefinite use.

Short-Term Paybill - Designed for a specific project or purpose and active for a maximum of six months, after which it is closed. Suitable for contractors, event organizers, or project-based work. A short-term paybill is a product that allows for fundraising of funds for different needs, e.g. medical bills, funerals, weddings, education purposes, and for charity/catastrophes e.g. Fund, Funeral Fund, Education Fund.

What You Need Before Applying

Regardless of which product you choose, there are common prerequisites:

A registered Safaricom line in your name (this becomes your nominated number for receiving SMS notifications and withdrawing funds)
A business bank account with a cancelled cheque or bank letter confirming your account details - this is where your funds will settle
Valid identification documents (National ID, Passport, Alien ID, or Military ID)
A duly filled and signed Safaricom application form

Beyond these basics, the documents required differ by business structure.

Document Requirements by Business Type

Individual / Sole Proprietor

National ID or Passport (front and back)
Business permit or certificate of registration
Cancelled cheque or bank letter with account details
KRA PIN certificate
Signed application form and M-PESA terms and conditions

Note: If your business permit does not match your identification documents, you may also need to provide a Certificate of Business Registration to prove the relationship between you and the business.

Limited Liability Company (LLC)

Certificate of Incorporation
CR12 (must be less than 3 months old for new applications; less than 2 years old for additional tills under an existing account)
KRA PIN certificate for the company
Board resolution authorizing the application and the nominated signatories
Beneficial Ownership Form (BOF1) - required for BRS-registered companies; non-BRS companies complete a Safaricom-issued self-declaration template
National IDs for all directors listed on CR12
Cancelled cheque or bank letter
Signed application form

Partnership

Business registration certificate or business permit
Partnership deed or affidavit
KRA PIN certificates for the partnership and partners
National IDs of all partners
M-PESA Authorization form signed by all partners (required where more than two persons are named as business owners)
Cancelled cheque or bank letter
Signed application form

NGO / Church / Religious Organization

Certificate of Registration from the NGO Coordination Board (for NGOs) or relevant authority (for churches)
Constitution or trust deed
Board resolution authorizing the account
KRA PIN certificate
National IDs of authorized signatories
Cancelled cheque or bank letter

SACCO / Cooperative Society

Certificate of Registration from the Commissioner for Co-operatives
SACCO bylaws
Board resolution
KRA PIN certificate
National IDs of authorized signatories
Cancelled cheque or bank letter

Pro tip: All documents should be in PDF format and hand-filled(not computer-filled). Safaricom accepts up to 10 MB per document. ZIP files are not accepted.

How to Apply Online (Self-Onboarding Portal)- for M-PESA Business Till (Buy Goods Till) or Short-term Paybill

This is the fastest route for most applicants.

Step 1: Visit the Portal
Go to m-pesaforbusiness.co.ke and click Apply Now.

Step 2: Select Your Product

For a Till Number: click M-PESA Business Till (Buy Goods Till), then Apply Now. Choose between Individual Till (funds settle to the owner's M-PESA account) or Business Till (funds settle to a bank account). Select your preferred option.

For a Paybill: Click Short-Term Paybill in the product list. Choose any of the items presented i.e. Medical Fund, Education Fund, Funeral Fund, Wedding Fund, Charity / Catastrophe then Apply Now.

For the Application Form attached here:

Step 3: Fill in the Application Form
Complete all required fields - business name, physical address, nominated mobile number, administrator details, bank account details, and your preferred tariff (for Paybill) and other details required.

Step 4: Choose Your Tariff (Paybill Only)
Safaricom offers three tariff options:

Mgao - fees shared between customer and business; suitable for small startups
Business Bouquet - business absorbs all transaction fees; ideal for e-commerce and service providers
Customer Bouquet - customer pays all fees; typically used by utilities, schools, and SACCOs

Step 5: Upload Documents (Both for Online portal and email)
Attach your required documents based on your business type (see above). All files must be in PDF format, each under 10 MB.

Step 6: Submit
Once submitted, you'll receive a confirmation message acknowledging your application. Processing typically takes 24-72 hours after all documents are successfully submitted and verified.

Step 7: Track Your Application
Log in to the portal at m-pesaforbusiness.co.ke, click on My Applications, and enter the mobile number used during application. Statuses to look out for:

Under Review - application received and being assessed
Pending Documents - more information required from you
Approved - documents accepted, number being processed
Complete - your number is active and ready to receive payments

How to Apply In Person

If you prefer a physical submission or don't have all documents in digital form:

Download and fill the application form
Sign the M-PESA terms and conditions
Attach copies of all required documents
Visit any Safaricom Shop or Care Centre countrywide and submit the package
Alternatively, email your completed application to M-PESABusiness@safaricom.co.ke

Application For Paybill Accepted

Once the application has been accepted you will receive an email confirming that your account has been created

How to Activate Your Till / Paybill After Approval

Once approved, you'll receive your Till/Store number and Operator ID via SMS on your nominated number.

For a Till Number:

Dial *234# from your nominated Safaricom number
Select M-PESA Business Till
Enter your Store number and accept the terms and conditions
You'll receive an SMS with your Operator ID and start key
Dial *234*2# again → go to Account Services → Change PIN
Log into the M-PESA Business App or portal and set a new PIN
You're now live and can receive payments

For a Paybill:

Dial *234*4# from your nominated number
Follow the on-screen prompts to activate and set your PIN
You can also manage your Paybill via the M-PESA portal at org.ke.m-pesa.com - credentials are sent to your administrator email upon account creation

Withdrawing Funds

From a Till Number:

Dial *234# → M-PESA Business Till → Withdraw Funds → choose To the Bank → enter your Till/Store number. Note that you can only withdraw to the bank account provided during registration.

From a Paybill:

Dial *234# → Withdraw Cash → Bank → enter your Paybill number. Again, settlement is only to the bank account registered at onboarding.

Accessing the M-PESA Business Portal (G2 Portal)

After your number is issued, you'll want access to the M-PESA Business Portal for balance checks, transaction statements, and user management. If Safaricom did not create portal access automatically:

Prepare a letter on your company letterhead addressed to Safaricom
Include: organization name, Paybill/Till number, administrator's full name, preferred username, and administrator email
Attach: duly filled and signed Business Administrator Form, company registration certificate(s), and copies of IDs
Email to lipanampesa@safaricom.co.ke with subject: "Request for M-PESA Portal Login"

You should receive your credentials within 24–48 hours.

For Developers: Taking Your Paybill Live on Daraja

If you're integrating M-PESA payments into an application or website, a Paybill number also grants you access to the Safaricom Daraja API. After your Paybill is approved:

Create an account at developer.safaricom.co.ke
Create an app and link your Paybill shortcode
Follow the Go-Live process at https://developer.safaricom.co.ke/dashboard/golive - this includes submitting production credentials and completing a sandbox test run

Once approved, You will receive passkey in the email. You can use the Daraja APIs: STK Push (C2B), B2C, Account Balance, Transaction Status, and more

To learn more on How to Go Live, Click Here

Useful Contacts & Links

Resource	Details
Self-Onboarding Portal	m-pesaforbusiness.co.ke
M-PESA Business Portal	org.ke.m-pesa.com
Daraja Developer Portal	developer.safaricom.co.ke
Email Support	M-PESABusiness@safaricom.co.ke
Portal Access Requests	lipanampesa@safaricom.co.ke
Till/Paybill USSD	`*234#`
Customer Care	100 (Safaricom line)

Final Checklist Before You Apply

[ ] Business registered and permit/certificate available
[ ] Valid ID for all directors/owners
[ ] KRA PIN certificate ready (business and individual)
[ ] Bank letter or cancelled cheque prepared
[ ] Registered Safaricom SIM in your name
[ ] Application form downloaded and fully filled
[ ] All documents in PDF format, under 10 MB each
[ ] Tariff selected (Paybill applicants)

With the right documents in hand, the online process takes less than 30 minutes and approval comes through within 24 hours. Take your time on the paperwork - missing a single document is the most common reason for delays.

Need M-PESA Integration for Your App or System?

Got your Paybill or Till number and now need to integrate it into your website, app, or backend system? I can help.

I offer M-PESA integration services covering:

STK Push (Mpesa Express) -let customers pay directly from your app or website
B2C Payments - send money to customers, suppliers, or staff programmatically
Customer to Business (C2B) - reliably process and confirm M-PESA transactions in real time
Daraja API setup & go-live - from sandbox to production
KCB Buni, PesaLink & other Kenyan and international payment APIs

feel free to reach out:

📧 Email: sosmongare@gmail.com

💬 WhatsApp: Chat on WhatsApp

Let's build something that works.

How to Go Live on the M-Pesa Daraja API

Sospeter Mong'are — Mon, 22 Jun 2026 11:55:42 +0000

Sandbox testing done? Here's the exact, step-by-step process to get real production credentials from the Daraja portal - faster than you think.

If you've built an STK Push integration that works flawlessly in sandbox and you're wondering "what now?" - this guide is for you. The good news: the new Daraja portal has made going live surprisingly self-service. No lengthy email chains, no weeks of waiting. Just a form, an OTP, a product selection, and your production Consumer Key lands in your apps dashboard. Your Passkey lands straight in your inbox.

Let's walk through the whole thing from start to finish.

What "Going Live" on Daraja Actually Means

Safaricom's Daraja portal gives every developer two environments:

Sandbox - fake shortcodes, simulated money, instant access. Perfect for building and breaking things safely.
Production - your real Paybill or Till number, real customer money, real consequences if something breaks.

"Going live" is the process of provisioning a production app against your actual business shortcode. Once done, Safaricom creates a new production app under My Apps, gives you a live Consumer Key and Consumer Secret, and emails you your Passkey - the credentials you'll use to call real M-Pesa endpoints.

Before You Start: Prerequisites You Actually Need

Don't touch the Go Live button until these are in place. Missing any one will stop you cold mid-process.

1. A Daraja Developer Account

Register at developer.safaricom.co.ke as an individual or company if you haven't already. You need to be logged in to access the Go Live menu.

2. A Working Sandbox Integration

The Go Live form doesn't ask you to prove it, but it's implicit - you should have already tested your STK Push, C2B, or B2C flow end-to-end in sandbox, including callback handling. Going live against an untested integration is how you end up with real customer money in a broken system.

3. A Live Safaricom Business Shortcode

This is the most common blocker. Your Paybill or Till number must already be registered with Safaricom's business team - a completely separate process from the developer portal. Apply for this early; it often takes longer than the technical work. The Go Live form will ask for your shortcode, so have it ready.

4. Your M-PESA Portal Username

The form requires your Business Admin or Business Manager username from the M-PESA Business Portal (https://org.ke.m-pesa.com/) - not your Daraja login credentials. This is how Safaricom verifies you're authorized to link that shortcode to a production developer app.

5. Access to Your Registered Phone Number / Email for OTP

Step 2 of the Go Live flow sends an OTP to the contact details registered on your account. Make sure you have access to it.

6. A Live HTTPS Callback URL

For APIs like STK Push (Lipa Na M-Pesa), C2B, and B2C, your ResultURL, ConfirmationURL, and ValidationURL must be publicly accessible over HTTPS with a valid SSL certificate. Localhost and Ngrok tunnels don't belong in production.

Step-by-Step: How to Go Live on the Daraja Portal

Step 1: Click "Go Live" in the Sidebar

Log in to your Daraja account. On the left sidebar, you'll see the Go Live menu item - it sits between Test Credentials and APIs. Click it.

The page opens with a clean two-step form: Organization Information → Enter OTP.

Step 2: Fill in Your Organization Information

The first screen asks for four fields:

Field	What to Enter
Verification Type	Select `Short Code` from the dropdown
Organization ShortCode	Your live Paybill, Till Number, Head Office, B2C, or Store Number
Organization Name	Your company or business name
M-PESA Username	Your Business Admin/Manager username from the M-PESA Business Portal

Accept Safaricom's Terms and Conditions by ticking the checkbox, then click Next.

Pro tip: Your Organization ShortCode and Organization Name must match exactly what's registered on the M-PESA Business Portal. A mismatch is the most common reason this step fails.

Step 3: Enter the OTP

Safaricom sends a One-Time Password to your registered contact (phone or email). Enter it on the second screen to verify your identity and authorize the go-live request.

Didn't receive it? Hit Resend Code - it usually arrives within a minute.

Step 4: Select Your Production APIs

After OTP verification, you'll land on the product selection screen - this is where you tell Safaricom exactly which M-Pesa APIs your app needs in production. The available products include:

Lipa Na M-Pesa Production - STK Push and Query (what most apps need for collecting payments)
C2B v2 - Customer To Business payments with minimized data
B2C - Business To Customer disbursements (e.g. paying out winnings, salaries, refunds)
B2B - Business Buy Goods, Business Pay Bill, and B2C Account Top Up
Transaction Status - Check the status of any M-Pesa transaction
Account Balance - Query your business account balance
Reversal - Reverse a completed transaction
Dynamic QR - Generate QR codes for payments
M-Pesa Ratiba - Recurring/scheduled payment activation
Pull Transactions Prod - Pull transaction records via API
Mobile Number Validation - Validate mobile numbers against M-Pesa

Tick only what you actually need. Don't check everything by default - each API maps specific permissions to your shortcode, and requesting ones you don't need can cause issues, particularly the B2C/C2B split (a C2B shortcode and a B2C shortcode cannot share the same production app).

Once you've made your selections, click Submit.

Step 5: See the Success Screen and Check Your Apps

Daraja immediately shows a "You have successfully applied for production developer app" confirmation. It also tells you:

"Please check your email for production API URLs against your selected products. Next, we will direct you to view your apps."

Click View Your Apps.

Under My Apps, you'll now see your new production app separate from your sandbox apps. Open it and you'll find your:

Consumer Key (production)
Consumer Secret (production)

Your Passkey for Lipa Na M-Pesa (STK Push) is sent directly to your registered email - check your inbox.

Now Update Your Code: The Production Swap Checklist

Getting credentials is one thing. Wiring them up correctly is another. Run through this checklist before you process a single live transaction:

Replace your sandbox Consumer Key and Consumer Secret with the production ones from your new app.
Switch your base URL from https://sandbox.safaricom.co.ke to https://api.safaricom.co.ke.
Update your Shortcode from the sandbox test shortcode (174379 for STK Push) to your real Paybill/Till number.
Replace your Passkey with the one received in your email - it's different from the sandbox passkey.
Regenerate your SecurityCredential using Safaricom's production public certificate (not the sandbox one). Using the wrong certificate is the #1 cause of ResultCode 8006 (Initiator locked) errors for B2C and Account Balance APIs.
Verify your Initiator Name and password in the M-PESA Business Portal under the API User section - they must match exactly what you send in B2C/Account Balance requests.
Confirm your callback URLs are live, HTTPS, publicly accessible, and returning 200 OK with a valid JSON body.

Your First 24 Hours After Go-Live

Production credentials aren't a finish line - they're a starting gun. Do these before you open up to real users:

Run one small real transaction end-to-end. Trigger an STK Push to yourself for KES 1 and confirm the full loop: request → customer prompt → payment → callback → your database updates correctly.
Log everything. Every API request, every response, every callback payload. You'll need this for reconciliation and for any Safaricom support tickets.
Implement retry logic for callbacks. Safaricom's callback delivery isn't guaranteed on the first attempt - networks fail. Build a retry mechanism or use a queue.
Watch your access token expiry. Production tokens expire every 3600 seconds (1 hour). Never hardcode one - always regenerate before it expires.
Set up transaction monitoring. Unusual error rates, repeated ResultCode failures, or missing callbacks should alert you before your customers notice.

Common Issues After Going Live

ResultCode 8006 - Initiator locked
Your SecurityCredential was generated using the sandbox certificate. Regenerate it using the production certificate from the Daraja portal.

STK Push request goes through but no callback arrives
Your callback URL isn't reachable from Safaricom's servers. Check that it's HTTPS, publicly accessible, and not blocked by a firewall or Cloudflare rule.

"Invalid Access Token" errors
Your token expired. Implement automatic token refresh - generate a new one before every request or cache it with an expiry buffer of ~50 minutes.

Sandbox credentials still working, production returning errors
You missed one of the URL swaps. Double-check every URL, not just the base URL - some SDKs construct endpoint paths in ways that can still hit the sandbox host.

Final Thoughts

The Daraja go-live process on the new portal is genuinely self-service and fast - if your prerequisites are in order, you can go from clicking "Go Live" to having a production Consumer Key in your dashboard in under 10 minutes. The bottleneck is almost never the portal itself; it's having your shortcode registered, your M-PESA Portal username ready, and your callbacks deployed to a live server before you sit down to do this.

Get those in place, and going live is just a form, an OTP, and a checkbox away.

If you're looking to integrate M-PESA Daraja into your website, mobile app, ERP, CRM, SACCO system, school system, or any custom platform, feel free to reach out.

Drop your question in the comments or WhatsApp me directly at Chat on WhatsApp. You can also email me at Here.

I'm happy to help you get your integration running smoothly.

Installing and Testing Docker on WSL with MobaXterm on Windows Os

Sospeter Mong'are — Tue, 16 Jun 2026 10:14:19 +0000

Introduction

If you are a developer on Windows who wants to use Docker without installing Docker Desktop, you are in the right place. In this guide, you will learn how to install Docker Engine inside WSL (Windows Subsystem for Linux) using MobaXterm, test it with a real Node.js application, and manage your containers like a pro — all from the command line.

By the end of this article, you will:

Understand what WSL and MobaXterm are and why they work great together
Have Docker Engine installed and running inside Ubuntu on WSL
Test Docker with the official hello-world image
Build and run a real Node.js web app inside a Docker container
Know how to start, stop, and clean up Docker containers

💡 Who is this guide for? Developers who are comfortable with the command line but are new to Docker on WSL. No prior Docker experience required.

1. What Are WSL and MobaXterm?

WSL — Windows Subsystem for Linux

WSL is a feature built into Windows 10 and 11 that lets you run a real Linux environment directly on your Windows machine — no virtual machine, no dual boot. You get a full Ubuntu terminal that shares your file system and network with Windows.

Think of WSL as a thin Linux layer that sits underneath your Windows desktop. It is fast, lightweight, and perfect for running developer tools like Docker, Node.js, Python, and more.

MobaXterm — A Better Terminal for WSL

MobaXterm is a powerful terminal application for Windows that includes built-in SSH, X11 forwarding, and — most importantly — direct access to your WSL sessions. It gives you a much better development experience than the default Windows Terminal for WSL work.

When you open a WSL tab in MobaXterm, you are working inside your Ubuntu environment. That is where all our Docker commands will run.

⚠️ Important Note About WSL and systemd: By default, WSL does not use systemd (the Linux service manager). This means sudo systemctl start docker may not work. Instead, we use sudo service docker start. This guide uses the correct command throughout.

2. Prerequisites

Before we begin, make sure you have the following:

Windows 10 (version 2004 or later) or Windows 11
WSL 2 installed with Ubuntu (Ubuntu 20.04 or 22.04 recommended)
MobaXterm installed — download free from mobaxterm.mobatek.net
A stable internet connection for downloading packages

To verify WSL is installed, open PowerShell and run:

wsl --list --verbose

You should see your Ubuntu distro listed with Version 2. If not, run wsl --set-version Ubuntu 2 to upgrade.

3. Opening Your WSL Session in MobaXterm

Launch MobaXterm and start a WSL session:

Open MobaXterm from your Windows Start menu
Click on Sessions → New Session
Select WSL from the session types
Choose your Ubuntu distribution from the dropdown
Click OK — you now have a Linux terminal open!

Your prompt should look something like this:

sospeter@DESKTOP-ABC123:~$

All commands in this guide are run inside this MobaXterm WSL terminal.

4. Installing Docker Engine on WSL

We will install Docker Engine using the official Docker apt repository. Follow each step carefully.

Step 1: Add Docker's Official GPG Key

First, update your package list and install the required dependencies:

sudo apt update
sudo apt install ca-certificates curl -y

Then create the directory for Docker's GPG key and download it:

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Step 2: Add the Docker Repository

Now add Docker's official package repository to your Ubuntu apt sources:

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

Step 3: Install Docker Packages

Install Docker Engine along with the CLI, containerd runtime, and the Compose plugin:

sudo apt install docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin -y

This may take a few minutes depending on your internet speed.

Step 4: Start Docker

In WSL, we start Docker using the service command:

sudo service docker start

To verify Docker is running:

sudo service docker status

You should see output that includes Docker is running.

🔁 Auto-start tip: Add sudo service docker start > /dev/null 2>&1 to your ~/.bashrc file so Docker starts automatically every time you open MobaXterm.

Step 5: Add Your User to the Docker Group (Optional but Recommended)

By default, Docker commands require sudo. To run Docker without it:

sudo usermod -aG docker $USER

# Apply the group change (or close and reopen your terminal)
newgrp docker

5. Verifying Docker with hello-world

Let us confirm Docker is working with the official test image:

sudo docker run hello-world

You should see output like this:

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from Docker Hub.
 3. The Docker daemon created a new container from that image.
 4. The Docker daemon streamed that output to the Docker client.

If you see that — congratulations! 🎉 Docker is installed and working correctly on your WSL.

6. Building and Running a Real Node.js App

The hello-world image is a good sanity check, but let us go further and run a real web application inside Docker.

Step 1: Create a Project Folder

mkdir ~/docker-test && cd ~/docker-test

Step 2: Create the Application File

Create a file called app.js:

nano app.js

Paste the following code:

const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from Docker on WSL! 🐳\n');
});

server.listen(3000, () => {
  console.log('Server running on port 3000');
});

Save and exit with Ctrl + X, then Y, then Enter.

Step 3: Create the Dockerfile

nano Dockerfile

Paste the following:

# Use the official Node.js Alpine image (small and fast)
FROM node:18-alpine

# Set the working directory inside the container
WORKDIR /app

# Copy our application file into the container
COPY app.js .

# Tell Docker our app listens on port 3000
EXPOSE 3000

# Command to run when the container starts
CMD ["node", "app.js"]

Step 4: Build the Docker Image

sudo docker build -t wsl-test-app .

The -t flag gives the image a name (tag). The . tells Docker to look for the Dockerfile in the current directory.

Step 5: Run the Container

sudo docker run -d -p 3000:3000 --name my-test-app wsl-test-app

What each flag does:

Flag	Meaning
`-d`	Run in the background (detached mode)
`-p 3000:3000`	Map port 3000 on your host to port 3000 in the container
`--name my-test-app`	Give the container a friendly name
`wsl-test-app`	The image name we just built

Step 6: Test the Running App

curl http://localhost:3000

Expected output:

Hello from Docker on WSL! 🐳

You can also open http://localhost:3000 in your Windows browser and see the same result!

7. Managing Your Containers

Command	What It Does
`docker ps`	List all running containers
`docker ps -a`	List all containers including stopped ones
`docker logs my-test-app`	View logs from a container
`docker stop my-test-app`	Stop a running container
`docker start my-test-app`	Start a stopped container
`docker rm my-test-app`	Delete a container
`docker images`	List all images on your machine
`docker rmi wsl-test-app`	Delete an image
`docker exec -it <name> sh`	Open a shell inside a running container

Cleaning Up Your Test App

# Stop the running container
sudo docker stop my-test-app

# Remove the container
sudo docker rm my-test-app

# (Optional) Remove the image
sudo docker rmi wsl-test-app

Stopping Docker Engine

sudo service docker stop

8. Troubleshooting Common Issues

Cannot connect to the Docker daemon
Run sudo service docker start to start the Docker service.

Permission denied running Docker
Either prefix commands with sudo, or add yourself to the docker group (Section 4, Step 5).

Port already in use
Change the port mapping to -p 3001:3000 and visit localhost:3001 instead.

WSL using too much RAM
Create C:\Users\YourName\.wslconfig with:

[wsl2]
memory=4GB
processors=2

9. Quick Reference Cheat Sheet

# Docker service
sudo service docker start        # Start Docker
sudo service docker stop         # Stop Docker
sudo service docker status       # Check status

# Images
sudo docker build -t name .      # Build image from Dockerfile
sudo docker images               # List images
sudo docker rmi image-name       # Delete image

# Containers
sudo docker run -d -p 3000:3000 --name app image   # Run container
sudo docker ps                   # See running containers
sudo docker ps -a                # See all containers
sudo docker logs app             # View logs
sudo docker stop app             # Stop container
sudo docker rm app               # Remove container
sudo docker exec -it app sh      # Shell into container

Conclusion

You have successfully:

✅ Installed Docker Engine on WSL using the official apt repository
✅ Started and verified Docker is running with the hello-world image
✅ Built and deployed a real Node.js application inside a Docker container
✅ Learned how to manage, stop, and clean up containers

Docker on WSL is a powerful setup that gives you all the benefits of Linux containers without leaving your Windows machine. As you grow more comfortable, explore Docker Compose for multi-container applications, volume mounts for persistent data, and container networking for microservices architectures.

Happy coding and containerizing! 🐳

Found this helpful? Share it with fellow developers. Follow me on X for more backend, API, and DevOps content.

How to Install dbt with SQL Server on WSL (Windows Subsystem for Linux)

Sospeter Mong'are — Wed, 10 Jun 2026 13:31:41 +0000

Note: A beginner-friendly, step-by-step guide for data engineers on Windows

What is dbt?

dbt (data build tool) is an open-source transformation tool that lets you write SQL-based data models, test them, and document them — all from the command line. It sits on top of your database and transforms raw data into analytics-ready tables and views.

If you're working with data pipelines, ELT workflows, or data warehouses, dbt is a tool you'll encounter regularly.

Prerequisites

Before starting, make sure you have:

WSL 2 with Ubuntu 24.04 installed on your Windows machine
Python 3.12 available (python3 --version to check)
A virtual environment already created and activated (see the Airflow installation guide if you need to set one up)
Access to a SQL Server instance — remote, Azure SQL, or local

Step 1: Activate Your Virtual Environment

Always work inside a virtual environment to keep your dependencies isolated:

source ~/your-project-folder/env/bin/activate

Your prompt should show (env) at the beginning confirming it's active.

Step 2: Install dbt with the SQL Server Adapter

The SQL Server adapter for dbt is maintained as dbt-sqlserver. Installing it also pulls in dbt-core automatically:

pip install dbt-sqlserver

Verify the installation:

dbt --version

Confirm the adapter is installed:

pip show dbt-sqlserver

You should see:

Name: dbt-sqlserver
Version: 1.x.x
Summary: A Microsoft SQL Server adapter plugin for dbt
Requires: dbt-adapters, dbt-common, dbt-core, pyodbc

Note: dbt --version may not always list plugins explicitly in some environments — pip show dbt-sqlserver is the reliable way to confirm the adapter is present.

Step 3: Install the Microsoft ODBC Driver for SQL Server

dbt-sqlserver uses pyodbc under the hood, which requires Microsoft's ODBC driver to physically connect to SQL Server. Run the following commands one at a time:

Command 1 — Download and register Microsoft's GPG signing key:

curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg

Command 2 — Add Microsoft's package repository:

curl https://packages.microsoft.com/config/ubuntu/24.04/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list

Command 3 — Refresh apt to pick up the new repository:

sudo apt update

Command 4 — Install the ODBC driver:

sudo ACCEPT_EULA=Y apt install -y msodbcsql18 unixodbc-dev

Verify the driver is registered:

odbcinst -q -d -n "ODBC Driver 18 for SQL Server"

You should see:

[ODBC Driver 18 for SQL Server]
Description=Microsoft ODBC Driver 18 for SQL Server
Driver=/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.6.so.2.1
UsageCount=1

This confirms the driver is installed and ready.

Step 4: Clone Your dbt Project Repository

If you have an existing dbt project in a Git repository, clone it:

cd ~
git clone <YOUR_REPO_URL_HERE>
cd <cloned-folder-name>

If the repository is private, authenticate using a GitHub Personal Access Token (PAT):

git clone https://<your-github-username>:<your-PAT>@github.com/org/repo.git

Step 5: Install dbt Project Dependencies

Most dbt projects have a packages.yml file that lists external dbt packages. Install them with:

dbt deps

Step 6: Configure Your `profiles.yml`

dbt connects to your database using a profiles.yml file. By default it lives at ~/.dbt/profiles.yml, but some projects include it locally inside the repo folder.

Create the default profiles directory and file:

mkdir -p ~/.dbt
nano ~/.dbt/profiles.yml

Paste the following template and fill in your actual credentials:

your_project_name:
  target: dev
  outputs:
    dev:
      type: sqlserver
      driver: "ODBC Driver 18 for SQL Server"
      server: your_server_address        # e.g. 192.168.1.10 or myserver.database.windows.net
      port: 1433
      database: your_database_name
      schema: your_schema_name
      user: your_username
      password: your_password
      encrypt: true
      trust_cert: true                   # set to false in production with a valid SSL cert
      login_timeout: 60                  # seconds before connection attempt times out

    prod:
      type: sqlserver
      driver: "ODBC Driver 18 for SQL Server"
      server: your_prod_server_address
      port: 1433
      database: your_prod_database
      schema: your_prod_schema
      user: your_prod_username
      password: your_prod_password
      encrypt: true
      trust_cert: true
      login_timeout: 60

Important: The top-level key (your_project_name) must exactly match the name: field inside the project's dbt_project.yml file.

Save and exit (Ctrl+O, Enter, Ctrl+X).

Step 7: Test the Connection

Run dbt's built-in connection test:

dbt debug --target dev

A successful output looks like:

All checks passed!

If you see a Login timeout expired error, check:

Your server address is correct and reachable
Port 1433 is open on the server's firewall
Your credentials are correct in profiles.yml
You're on the right network (VPN may be required for remote servers)

Test if the server port is reachable from WSL:

nc -zv your_server_address 1433

Step 8: Run Your dbt Models

Once the connection test passes, run a specific model:

dbt run --select model_name --target dev

Run all models:

dbt run --target dev

Run models against production:

dbt run --select model_name --target prod

List all available models in the project:

dbt ls --target dev

Other Database Adapters

dbt supports many databases. Here are the install commands for the most common ones:

Database	Install Command
SQL Server / Azure SQL	`pip install dbt-sqlserver`
PostgreSQL	`pip install dbt-postgres`
BigQuery	`pip install dbt-bigquery`
Snowflake	`pip install dbt-snowflake`
MySQL	`pip install dbt-mysql`
Redshift	`pip install dbt-redshift`
DuckDB	`pip install dbt-duckdb`
Databricks	`pip install dbt-databricks`
Trino	`pip install dbt-trino`

Each adapter has its own profiles.yml format. The type: field changes per adapter. For example:

PostgreSQL:

my_project:
  target: dev
  outputs:
    dev:
      type: postgres
      host: localhost
      port: 5432
      database: my_database
      schema: public
      user: my_user
      password: my_password

BigQuery:

my_project:
  target: dev
  outputs:
    dev:
      type: bigquery
      method: service-account
      project: my_gcp_project
      dataset: my_dataset
      keyfile: /path/to/service-account.json

Snowflake:

my_project:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: my_account
      user: my_user
      password: my_password
      database: my_database
      schema: my_schema
      warehouse: my_warehouse
      role: my_role

Quick Reference: Most Used dbt Commands

dbt debug              # Test database connection
dbt deps               # Install project package dependencies
dbt run                # Run all models
dbt run --select model_name         # Run a specific model
dbt run --target prod               # Run against a specific target
dbt test                            # Run data tests
dbt ls                              # List all models
dbt compile                         # Compile SQL without running
dbt docs generate && dbt docs serve # Generate and view documentation

Summary of Installation Commands

# Activate virtual environment
source ~/your-project/env/bin/activate

# Install dbt with SQL Server adapter
pip install dbt-sqlserver

# Install ODBC Driver (run one at a time)
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
curl https://packages.microsoft.com/config/ubuntu/24.04/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt update
sudo ACCEPT_EULA=Y apt install -y msodbcsql18 unixodbc-dev

# Verify ODBC driver
odbcinst -q -d -n "ODBC Driver 18 for SQL Server"

# Clone project repo
git clone <REPO_URL>
cd <project-folder>

# Install dbt packages
dbt deps

# Configure connection
mkdir -p ~/.dbt && nano ~/.dbt/profiles.yml

# Test connection
dbt debug --target dev

# Run models
dbt run --target dev

Written based on a real dbt + SQL Server setup on WSL2 Ubuntu 24.04 (Noble) with ODBC Driver 18.

How to Install Apache Airflow 2.9.1 on WSL (Windows Subsystem for Linux)

Sospeter Mong'are — Tue, 09 Jun 2026 13:48:58 +0000

Note: A beginner-friendly, step-by-step guide for developers on Windows

What is Apache Airflow?

Prerequisites

Before we begin, make sure you have the following in place:

1. Windows Subsystem for Linux (WSL) installed

You need WSL 2 with Ubuntu 24.04 (Noble) installed on your Windows machine. If you haven't set it up yet, open PowerShell as Administrator and run:

wsl --install

Restart your machine when prompted, then launch Ubuntu from the Start menu.

2. MobiXterm or Windows Terminal (optional but recommended)

MobiXterm or Windows Terminal gives you a better terminal experience for working inside WSL. Either works fine.

3. Basic familiarity with the Linux terminal

You don't need to be a Linux expert, but knowing how to navigate directories (cd, ls) and run commands will help.

Step 1: Update Your System

Open your WSL terminal and run:

sudo apt update && sudo apt upgrade -y

This ensures your package lists and installed packages are up to date.

Step 2: Install Python 3 and Check the Version

Ubuntu 24.04 ships with Python 3.12 by default. Verify it's available:

python3 --version

You should see something like Python 3.12.x. If not, install it:

sudo apt install python3 python3-dev -y

Step 3: Install `python3.12-venv`

Airflow should always be installed inside a virtual environment to avoid dependency conflicts with your system Python.

First, install the venv module:

sudo apt install python3.12-venv -y

Troubleshooting - Network/download errors?
On some networks, apt may time out trying to download packages. If you see a Connection timed out or Connection failed error for python3-pip-whl, use wget to download it manually:
wget -O python3-pip-whl.deb "https://launchpadlibrarian.net/753358547/python3-pip-whl_24.0+dfsg-1ubuntu1.3_all.deb"
sudo dpkg -i python3-pip-whl.deb
sudo dpkg --configure -a
sudo apt --fix-broken install
Then retry the venv install:
sudo apt install python3.12-venv -y

Step 4: Create a Project Directory and Virtual Environment

Create a dedicated folder for your Airflow installation:

mkdir ~/airflow-2.9.1
cd ~/airflow-2.9.1

Now create a virtual environment inside it:

python3 -m venv venv

Activate the virtual environment:

source venv/bin/activate

Your terminal prompt should now show (venv) at the beginning, like:

(venv) user@DESKTOP-XXXX:~/airflow-2.9.1$

This confirms you are inside the virtual environment.

Step 5: Upgrade pip

Before installing Airflow, upgrade pip to the latest version:

pip install --upgrade pip

Step 6: Install Apache Airflow 2.9.1

Install Airflow using the official constraints file. This is important - Airflow has many dependencies, and the constraints file ensures compatible versions are installed together without conflicts.

pip install apache-airflow==2.9.1 \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.9.1/constraints-3.12.txt"

This may take a few minutes. Once complete, verify the installation:

airflow version

You should see:

2.9.1

Step 7: Initialize the Airflow Database

Airflow uses a metadata database to track DAG runs, tasks, logs, and more. Initialize it with:

airflow db init

This creates the default SQLite database and the ~/airflow directory with all necessary config files.

Step 8: Create an Admin User

Create your first admin user to log into the Airflow web UI:

airflow users create \
  --username admin \
  --firstname YourFirstName \
  --lastname YourLastName \
  --role Admin \
  --email your@email.com

You will be prompted to set a password. Enter and confirm it.

Step 9: Start the Airflow Web Server and Scheduler

Airflow requires two processes running simultaneously - the webserver and the scheduler. Open two separate WSL terminal tabs or windows for this.

Terminal 1 - Start the webserver:

cd ~/airflow-2.9.1
source venv/bin/activate
airflow webserver --port 8080

Terminal 2 - Start the scheduler:

cd ~/airflow-2.9.1
source venv/bin/activate
airflow scheduler

Step 10: Access the Airflow UI

Open your browser and navigate to:

http://localhost:8080

You will see the Airflow login page. Enter the username and password you created in Step 8.

You should now be inside the Airflow Dashboard - ready to create and manage your DAGs!

Quick Reference: Starting Airflow After a Reboot

Every time you restart your machine and want to use Airflow, run these commands in two terminals:

# Both terminals: navigate and activate venv
cd ~/airflow-2.9.1
source venv/bin/activate

# Terminal 1
airflow webserver --port 8080

# Terminal 2
airflow scheduler

Summary of All Commands

# Update system
sudo apt update && sudo apt upgrade -y

# Install Python venv
sudo apt install python3.12-venv -y

# Create project directory and venv
mkdir ~/airflow-2.9.1 && cd ~/airflow-2.9.1
python3 -m venv venv
source venv/bin/activate

# Install Airflow
pip install --upgrade pip
pip install apache-airflow==2.9.1 \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.9.1/constraints-3.12.txt"

# Verify
airflow version

# Initialize DB and create user
airflow db init
airflow users create --username admin --firstname YourFirstName \
  --lastname YourLastName --role Admin --email your@email.com

# Start services
airflow webserver --port 8080   # Terminal 1
airflow scheduler               # Terminal 2

What's Next?

Now that Airflow is running, here are some things to explore next:

Write your first DAG - create a Python file in ~/airflow/dags/ to define a workflow
Explore Airflow Operators - BashOperator, PythonOperator, and more
Set up PostgreSQL as the Airflow backend (recommended for production over SQLite)
Use the CeleryExecutor for parallel task execution

DEV Community: Sospeter Mong'are

RAG Is Not an AI Agent

What is RAG?

RAG Architecture

What RAG Does Well

Where RAG Ends

Where AI Agents Begin

AI Agent Architecture

The Key Difference

Can an AI Agent Use RAG?

When Should You Use RAG?

When Should You Use an AI Agent?

RAG vs AI Agent at a Glance

Final Thoughts

LangChain & LangGraph Concepts You Should Know

1. Chains (The AI Workflow)

2. Tools (Giving AI Superpowers)

3. Memory (Remembering Conversations)

4. Agents (Reason + Choose Tools)

5. Graphs (LangGraph's Superpower)

A Simple Way to Remember

Understanding Integration Runtimes in Azure Data Factory (ADF)

Why Do We Need an Integration Runtime?

Types of Integration Runtime

1. Azure Integration Runtime

Advantages

2. Self-hosted Integration Runtime (SHIR)

Common use cases

3. Azure SSIS Integration Runtime

A Real-World Example

Which Integration Runtime Should You Use?

Understanding the Difference Between Pipelines and Integration Runtime

A Simple Analogy

Final Thoughts

How to Install Apache Airflow 3.1.3 on WSL (Windows Subsystem for Linux)

What is Apache Airflow?

Prerequisites

1. Windows Subsystem for Linux (WSL2) installed

2. MobiXterm or Windows Terminal (optional but recommended)

3. Basic familiarity with the Linux terminal

Step 1: Update Your System

Step 2: Install Python 3 and Check the Version

Step 3: Set Your AIRFLOW_HOME (Important - Do This First)

Step 4: Create a Project Directory and Virtual Environment

Step 5: Upgrade pip

Step 6: Install Apache Airflow 3.1.3 with Constraints

Step 7: Install the FAB Auth Manager Provider

Step 7b: Set FAB as the Auth Manager (Critical)

Step 8: Initialize the Airflow Database

Step 9: Create an Admin User

Step 10: Start the Airflow API Server and Scheduler

Step 11: Access the Airflow UI

Quick Reference: Starting Airflow After a Reboot

Airflow 3 vs Airflow 2 - Key Differences

Troubleshooting

airflow users command not found / invalid choice: 'users'

Deprecation warnings about [webserver] settings

No module named 'airflow.providers.fab' warning

Forgot your admin password

Port 8080 already in use

Summary of All Commands

What's Next?

How to Build an AI Agent (with Python Example)

What is an AI Agent?

Step 1: Define the Purpose and Scope

Example

Step 2: Design the System Prompt

Step 3: Choose an LLM

Cost

Speed

Context Window

Accuracy

Step 4: Connect Tools

Step 5: Add Memory

Conversation Memory

Working Memory

Long-Term Memory

Step 6: Orchestrate the Workflow

Step 7: Build a User Interface

Step 8: Test and Improve

`airflow users` command not found / invalid choice: 'users'

Deprecation warnings about `[webserver]` settings

`No module named 'airflow.providers.fab'` warning