iGPT Brief Agent

An email brief agent built on iGPT, with a runnable demo app and a reusable LangGraph base class for building your own iGPT-backed agents.

Overview

This repo contains two pieces:

• src/ - a reusable LangGraph agent library. IGPTAgent is the base class; it handles credential validation, datasource planning, and OAuth so subclasses only define the agent-specific work. IGPTBriefAgent is the reference subclass - a chief-of-staff style brief over the user's inbox with priorities, deadlines, statuses, and next steps. About 40 lines on top of the base.
• app/ - a runnable demo. FastAPI backend, React frontend, SQLite for multi-user auth, all wired through Docker Compose. A user signs up, asks a question, the demo plans which datasource to query, runs OAuth if needed, and streams a structured brief back. A side panel surfaces every iGPT SDK call as it happens, with method, snippet, purpose, and result.

The point of the demo is not the brief - it's that the brief is built on three iGPT SDK calls (datasources.list, connectors.authorize, recall.ask) and a JSON output schema. The rest is orchestration.

Quickstart

Prerequisites

• Docker and Docker Compose
• An iGPT API key - get one at https://igpt.ai/hub/playground
• An OpenAI API key - used for query planning, intent routing, and the topical guard

1. Clone and configure

git clone <your-repo-url>
cd brief-agent
cp .env.example .env

Fill in .env:

IGPT_API_KEY=your_igpt_api_key
OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-4o-mini

2. Run

docker compose up app -d

Open http://localhost:8080, sign up, and ask the agent something like "What's the most important thing in my inbox right now?"

On first run the agent will return an OAuth URL to connect your email through iGPT. Connect, wait a moment for iGPT to sync, then ask again.

Auth state lives in app_data/app.db (SQLite, gitignored). Inspect it with sqlite3 app_data/app.db.

3. Rebuild after changes

# Backend changes
docker compose build app && docker compose up app -d

# Frontend changes
cd app/web && npm run build && cd ../..
docker compose build app && docker compose up app -d

Architecture

Demo (app/)

Each user query passes through three layers before producing output:

        ┌─────────┐      ┌──────────┐      ┌────────┐
query → │  guard  │ ───► │  router  │ ───► │ agent  │ ──► SSE stream
        └─────────┘      └──────────┘      └────────┘
        topical scope    intent + msg     LangGraph subgraph
        (fail-open)      (live registry)  (extends IGPTAgent)

• Guard - an LLM check that the query fits one of the currently registered agents (or is a datasource connection request for one of them) and isn't out-of-scope (general knowledge, role-play, etc.). Pulls the agent menu from the live registry, so registering a new agent updates the guard's understanding with no prompt edits. Fail-open by design.
• Router - an LLM that picks one agent from the live registry and writes the user-facing status message. Adding a new agent extends the menu without router changes.
• Agent - the matched BaseAgent runs its LangGraph subgraph and yields server-sent events to the frontend.

Agent library (src/)

The base class encodes everything an iGPT-backed agent needs to do before its own work:

START → validate_config → plan_datasource → ensure_datasource → execute → END
        (base class)       (LLM picks)        (OAuth if needed)   (subclass)

Each node may short-circuit with a structured status (needs_api_key, needs_connection, error, success). Agents never block or interrupt - they return state.

Subclasses override one method:

class MyAgent(IGPTAgent):
    def _node_execute(self, state):
        client = self._igpt_client(state["igpt_api_user"])
        resp = client.recall.ask(
            user=state["igpt_api_user"],
            input="...",
            output_format=MY_SCHEMA,
        )
        state["status"] = "success"
        state["data"] = resp.get("output")
        return state

Build your own agent

1. Create src/<your_agent>/ with agent.py, prompts.py, schema.py.
2. Subclass IGPTAgent and override _node_execute.
3. Wrap each iGPT SDK call with a dispatch_custom_event("agent:sdk_call", ...) calling/done pair so the side panel populates.
4. Implement a BaseAgent wrapper for the demo backend (see app/server/agents/igpt_brief.py for the pattern).
5. Register it. The intent router picks it up from the live registry - no UI changes needed.

Detailed checklist in CLAUDE.md.

Repo structure

.
├── src/                    # Reusable agent library - import into your own product
│   ├── igpt_agent.py       # IGPTAgent base (validate → plan → ensure → execute)
│   ├── models.py           # Pydantic models (DatasourcePlan, AgentInput, AgentOutput)
│   ├── prompts.py          # Generic recall prompt
│   └── brief/              # IGPTBriefAgent - reference subclass
│       ├── agent.py
│       ├── prompts.py
│       └── schema.py
│
├── app/                    # Demo web app
│   ├── server/             # FastAPI: SSE endpoint, auth, guard, router, agent registry
│   └── web/                # React + Vite + Tailwind frontend
│
├── docker-compose.yml      # app service (one container)
├── .env.example            # Required and optional environment variables
└── CLAUDE.md               # Architecture deep-dive for AI assistants

Stack

• Backend - FastAPI, LangGraph, LangChain, iGPT Python SDK, SQLite, server-sent events
• Frontend - React 19, Vite, Tailwind CSS, React Router, React Query, Zustand, Zod
• Infra - Docker Compose

Resources

• iGPT Playground - interactive query console, get an API key
• iGPT Python SDK - pip install igptai
• iGPT Node.js SDK - npm install igptai
• iGPT API Documentation

License

MIT - see LICENSE. Copyright SpikeApp Inc.