glaivio-ai

# Glaivio

**The framework for building AI agents you can actually trust in production.**

Not just agents that demo well — agents that remember users, recover from mistakes, escalate when stuck, and get smarter over time.

[![PyPI version](https://img.shields.io/pypi/v/glaivio-ai)](https://pypi.org/project/glaivio-ai/)
[![Python](https://img.shields.io/pypi/pyversions/glaivio-ai)](https://pypi.org/project/glaivio-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/tavyy/glaivio-ai?style=social)](https://github.com/tavyy/glaivio-ai)

⭐ If this saves you time, [give it a star](https://github.com/tavyy/glaivio-ai) — it helps other developers find it.

Rails did it for web apps. Next.js did it for React. Glaivio does it for AI agents.

```python
from glaivio import Agent, skill

@skill
def book_appointment(patient_name: str, patient_phone: str, date: str, time: str) -> str:
    """Book an appointment. patient_phone: use the current user's ID from context."""
    # call your calendar API here
    return f"Booked {patient_name} on {date} at {time}"

agent = Agent(
    instructions="prompts/system.md",
    skills=[book_appointment],
    learn_from_feedback=True,
    privacy=True,
)

agent.run(channel="whatsapp")
```

That's it. Your agent is live on WhatsApp — with memory, PII redaction, and self-improvement.


https://github.com/user-attachments/assets/e28e1a8c-95e9-4dcc-9cc6-930b7ba6a1be


---

## Install

```bash
pip install glaivio-ai
```

---

## What ships out of the box

**Persistent memory** — conversation history survives restarts. Zero config in development, one line to switch to Postgres in production.

**Self-improvement** — when a user corrects the agent, it stores the lesson and applies it to all future conversations. No prompt editing required.

**Human handoff** — when the agent is stuck, it notifies a human operator and holds the conversation until they take over.

**PII redaction** — sensitive identifiers are redacted before reaching the LLM and re-hydrated in the reply, so users still get personalised responses.

**Multi-channel** — the same agent runs on WhatsApp or Gmail. Each channel can have its own prompt — formal for email, concise for WhatsApp.

**Multi-model** — Claude, GPT, Gemini, or local models via Ollama. Swap with one param.

---

## Why Glaivio?

An **AI agent** is an LLM that can take actions, remember things, and talk to users through a channel. Building one from scratch means solving the same problems every time:

- Which LLM? How do I swap between them?
- How do I give it memory across conversations?
- How do I connect it to WhatsApp or email?
- How do I pass the user's identity into a tool call?
- How do I redact sensitive data before it hits the LLM?
- How do I escalate to a human when it gets stuck?
- How do I deploy it?

There are no standard answers. Every team solves these differently, from scratch, every time.

LangChain gives you the primitives — a way to call LLMs, define tools, chain them together. But you still wire everything else yourself. It's powerful, but it's not a framework. It's Lego with no instructions.

**Glaivio makes the decisions for you.**

| | LangChain | Glaivio |
|---|---|---|
| Define a tool | ✅ | ✅ |
| Swap LLM providers | ✅ | ✅ |
| Memory across sessions | You build it | Built in |
| WhatsApp / Gmail channels | You build it | Built in |
| User ID in every skill | You build it | Built in |
| PII redaction | You build it | One flag |
| Human handoff | You build it | One line |
| Agent self-improvement | You build it | One flag |
| Deployment | You figure it out | One command |

```
Web era     → Rails      (2004)  — one way to build web apps
Frontend    → Next.js    (2016)  — one way to build React apps
Agent era   → Glaivio    (2026)  — one way to build AI agents
```

Convention over configuration — the same philosophy that made Rails dominate web development for a decade. If you want full control — use LangChain. If you want to ship in hours not weeks — use Glaivio.

---

## How it works

```
                    ┌──────────────────────┐
                    │   prompts/system.md  │  ← who the agent is
                    └──────────┬───────────┘
                               │
                    ┌──────────▼───────────┐
                    │     🧠  LLM          │  ← the brain
                    │  Claude/GPT/Gemini   │    decides what to do
                    └──────────┬───────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
┌───────▼────────┐  ┌──────────▼──────────┐  ┌───────▼────────┐
│  @skill        │  │  @skill             │  │  @skill        │  ← the arms
│  search_db()   │  │  send_email()       │  │  book_slot()   │    what it can do
└───────┬────────┘  └──────────┬──────────┘  └───────┬────────┘
        │                      │                      │
        └──────────────────────▼──────────────────────┘
                               │
                    ┌──────────▼───────────┐
                    │  📱 WhatsApp / Gmail  │  ← the mouth
                    └──────────┬───────────┘    talks to users
                               │
                    ┌──────────▼───────────┐       ┌──────────────────────┐
                    │        User          │       │   👤 Human operator  │
                    │  "that's wrong,      ├──────►│   notified when      │
                    │   I meant X not Y"   │ stuck │   agent is confused  │
                    └──────────┬───────────┘       │                      │
                               │ correction        │  replies "learned:   │
                    ┌──────────▼───────────┐       │   always confirm X"  │
                    │  💡 Self-improvement  │◄──────┘                     │
                    │  agent gets smarter  │                              │
                    │  with every mistake  │                              │
                    └──────────────────────┘
```

---

## Quickstart

```bash
pip install glaivio-ai
glaivio new my-agent
cd my-agent
cp .env.example .env   # add your ANTHROPIC_API_KEY
glaivio run
```

Your agent is running. Open `prompts/system.md` to change its instructions. Open `skills/example.py` to add capabilities.

For a full real-world example — an AI receptionist that books appointments over WhatsApp — see the [full quickstart](#full-quickstart) below.

---

## Prerequisites

- Python 3.10+
- An API key for your chosen LLM:
  - **Anthropic Claude** (default) — `ANTHROPIC_API_KEY` from [console.anthropic.com](https://console.anthropic.com/)
  - **OpenAI GPT** — `OPENAI_API_KEY`, install with `pip install glaivio-ai[openai]`
  - **Google Gemini** — `GOOGLE_API_KEY`, install with `pip install glaivio-ai[gemini]`
  - **Ollama** (local, free) — no API key needed, install with `pip install glaivio-ai[ollama]`
- For WhatsApp: a [Twilio account](https://twilio.com) with a WhatsApp-enabled number
- For Gmail: a Google Cloud project with the Gmail API enabled

---

## Full Quickstart

An AI receptionist that books appointments over WhatsApp.

**1. Scaffold**

```bash
glaivio new my-receptionist
cd my-receptionist
cp .env.example .env   # add your ANTHROPIC_API_KEY
```

**2. Write your prompt** — `prompts/system.md`

```markdown
You are an AI receptionist for Bright Smile Dental.

Your job is to help patients via WhatsApp. Keep replies SHORT — this is a text message.
Max 2 sentences. Never use bullet points or markdown.

When booking: ask for name, date and time. Always call check_availability first.
If the slot is taken, offer the alternatives the tool returns.
If medical or urgent, tell them to call the office directly.
```

**3. Define your skills**

```python
# skills/check_availability.py
from glaivio import skill

@skill
def check_availability(date: str, time: str) -> str:
    "

[truncated…]