apowerb

Agentic framework for building and deploying AI agents: flexible orchestration, custom tool integration, RAG, Text-to-SQL, webhooks and scheduled runs.

This repository is the open-source core. Some capabilities named in the product — billing, usage metering, prospection, identity-provider sign-in, multi-factor authentication, agent evaluation, the administration panel — ship as separate commercial bricks and are absent here. Where the core holds a hook for one, it is documented as such. A 404 on those routes means "not in this edition", not "object not found".

Full documentation: docs.apowerb.com.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Running
• CLI
• Architecture
• API Reference
• Available Tools
• Integrations
• Webhooks
• RAG (Retrieval-Augmented Generation)
• Text-to-SQL
• SSE Streaming
• Credits and billing
• Scheduled runs
• Agent Hub
• Development
• Troubleshooting

Features

• REST API based on FastAPI with automatic OpenAPI documentation
• Google ADK (Agent Development Kit) for agent management and execution
• LiteLLM for multi-model compatibility (Anthropic, OpenAI, Mistral, Google, OVHcloud, etc.)
• Multi-pattern orchestration: base, parallel, sequential, loop
• Sub-agents: hierarchical agent composition
• Modular tool system with 31 tool modules (Google Workspace, Microsoft 365, databases, RAG, etc.)
• RAG as a Service: index files, URLs, databases, and S3 into knowledge bases
• Text-to-SQL: natural language to SQL query conversion
• Webhooks: Gmail (Pub/Sub) and Outlook (Graph API) push notifications to trigger agents
• OAuth integrations: GitHub, Google, Microsoft, LinkedIn
• SSE streaming: real-time agent responses, RAG progress, and notifications
• Artifact generation: agents can create and execute code files
• Agent Hub: publish and clone agents across organizations
• Scheduled runs: cron-based agent execution, driven by an external orchestrator
• Supervision: an auditable session list, scoped to what the caller may read
• Revocable sessions: a per-account cut-off that refuses tokens minted before it
• Persistent sessions with conversation context
• PostgreSQL database with auto-migrations
• Encryption for API keys, tokens, and sensitive data
• Full CLI for agent and server management

Prerequisites

• Python 3.13+
• PostgreSQL
• UV (package manager)

Installation

1. Install UV and create virtual environment:

pip install uv
uv venv

2. Activate the virtual environment:

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

3. Install dependencies:

uv sync
uv pip install .

4. Configure environment:

cp .env.example .env

Configuration

Required Variables

Optional Variables

Security & JWT

CORS

OAuth — User Login

OAuth — Workspace Integrations

Gmail Pub/Sub Webhooks

RAG & Webhooks

Stripe (billing brick)

settings still declares these, and user still carries stripe_customer_id, but the billing routes and the credit logic live in the billing brick. Setting them changes nothing in a core-only install.

S3 Storage (optional)

Orchestrator (scheduled runs, optional)

Two backends drive scheduled runs. ORCHESTRATOR selects one; the code still defaults to mage, the historical backend, so an instance that wants th2etl must say so explicitly.

With ORCHESTRATOR=th2etl:

With ORCHESTRATOR=mage:

Extensions

Installing a brick and loading it are two different steps: a package present in the environment but absent from TH2_EXTENSIONS behaves exactly like one that was never installed. Check the loaded set, not the installed set, when a capability seems missing.

Running

Via CLI

apowerb serve

Via Uvicorn

uv run uvicorn apowerb.main:app --reload

Server starts at http://127.0.0.1:8000/

/docs, /redoc and /openapi.json are removed from the served routes by default: they hand the full route inventory to an unauthenticated caller, which is enough to fingerprint a deployment from the outside. Opt in with PUBLISH_API_SCHEMA=true for a browsable Swagger; WORKING_MODE=production overrides that flag as a second lock.

The published reference is at docs.apowerb.com.

CLI

# Start server
apowerb serve --host 0.0.0.0 --port 8000

# Manage agents
apowerb agents list
apowerb agents create
apowerb agents delete <agent_id>

# Manage tools
apowerb tools list

# Manage runs
apowerb runs list

Architecture

apowerb/
├── src/apowerb/
│   ├── main.py              FastAPI entry point, middleware, router mounting, startup
│   ├── models.py            SQLAlchemy ORM models
│   │
│   ├── auth/                Email/password login, JWT dependencies, session cut-off
│   ├── users/               User CRUD
│   ├── routers/             HTTP endpoints, one module per family
│   ├── core/                Business logic behind the routers
│   │   ├── adk_runner.py        ADK execution
│   │   ├── adk_agent_builder.py agent Python file generation
│   │   ├── extensions/         brick loader and registry hooks
│   │   ├── guardrails.py       input/output guardrails
│   │   ├── run_gate.py         admission control for runs
│   │   └── history_compaction.py  conversation trimming
│   ├── tools_store/         Tool registry + portfolio of tool modules
│   ├── skills_store/        Reusable agent skills
│   ├── agent_store/         Agent templates and seeds
│   ├── bi/                  Charts, dashboards, datasets
│   ├── sqlgen/              Text-to-SQL generation
│   ├── integrations/        OAuth workspace integrations
│   ├── artifacts/           Artifact storage and execution
│   ├── scheduler/           Orchestrator clients (th2etl, mage), background workers
│   ├── storage/             Local and S3 storage abstraction
│   ├── middleware/          Request middleware
│   ├── helpers/             Database, security, encryption, notification bus, migrations
│   ├── schema/              Pydantic schemas
│   ├── configs/             Settings and logging
│   └── cli/                 Typer CLI (`apowerb`)
│
├── agents_pool/             Generated agent code (runtime)
├── artifacts_store/         Artifacts written by agents (runtime, local mode)
├── uploads/                 Uploaded files (runtime, local mode)
├── tests/
└── pyproject.toml

Routers not to look for here — they arrive with the bricks: billing, usage, prospection, identity-provider sign-in, MFA, evaluation, administration.

Startup Sequence

On application start, apowerb:

1. Creates required directories (agents_pool/, artifacts_store/, uploads/)
2. Runs auto-migrations (ensure_* functions) for all database tables
3. Generates agent Python modules from database
4. Starts the webhook renewal background task (every 6 hours)
5. Mounts the Google ADK FastAPI sub-application

API Reference

The full reference — every route, parameter and response shape — is generated from the code and published at docs.apowerb.com/api-reference. It is not duplicated here: a hand-maintained route table in this file went stale within two weeks last time, and a stale reference is worse than none.

Route families in this edition, all under /api unless noted:

Absent from this edition, provided by bricks: billing, usage, prospection, campaigns, MFA (/api/auth/mfa/*), identity-provider sign-in (/api/users/{github,google,microsoft,linkedin}), evaluation, administration. They answer 404 here.

Available Tools

Google Workspace

Microsoft 365

Data & Database

RAG & Knowledge

Communication

Utilities

Integrations

OAuth Providers

apowerb supports two categories of OAuth:

1. User Login — Sign up / log in via OAuth (GitHub, Google, Microsoft, LinkedIn)
2. Workspace Integrations — Connect external services as tools for agents

Connecting a Workspace Integration

1. User calls GET /api/integrations/{provider}/{service}/connect to get the OAuth URL
2. User authorizes the app on the provider's consent screen
3. Provider redirects to POST /api/integrations/{provider}/callback
4. apowerb stores the access/refresh tokens encrypted in the integrations table
5. Agent tools can now use the integration tokens

Supported Services

Webhooks

apowerb can automatically trigger agents when events occur in connected services (new email, etc.). Two providers are supported: Gmail (via Google Pub/Sub) and Outlook (via Microsoft Graph subscriptions).

How It Works

Email arrives → Provider pushes notification → apowerb receives it
     → Fetches new email content → Runs associated agent → Logs result

Webhook Subscription API

Create a subscription:

POST /api/webhooks/subscriptions
{
  "provider": "google_gmail",
  "resource": "INBOX",
  "agent_id": "AGENT_ID",
  "change_type": "created",
  "agent_message_template": "New email from {{ sender }}: {{ subject }}\n\n{{ body }}"
}

Automatic Renewal

• Gmail watches expire after 7 days
• Outlook subscriptions expire after 3 days
• A background task runs every 6 hours and renews subscriptions expiring within 12 hours

Gmail Webhook Setup (Pub/Sub)

Architecture

Gmail  ──push──▶  Google Pub/Sub  ──HTTP POST──▶  apowerb
                  (topic)                         /api/webhooks/gmail/notifications
                                                        │
                                                        ▼
                                                  Fetch new emails via Gmail API
                                                        │
                                                        ▼
                                                  Run associated agent

Prerequisites

• A Google Cloud project with billing enabled
• Gmail API and Cloud Pub/Sub API enabled
• A Google OAuth 2.0 application for workspace integration
• A publicly accessible URL for apowerb

Step 1 — Enable Google APIs

gcloud services enable gmail.googleapis.com pubsub.googleapis.com \
  --project=YOUR_PROJECT_ID

Step 2 — Create a Pub/Sub Topic

gcloud pubsub topics create gmail-notifications \
  --project=YOUR_PROJECT_ID

Step 3 — Grant Gmail Permission to Publish

Gmail uses the service account gmail-api-push@system.gserviceaccount.com to push notifications. Grant it the Pub/Sub Publisher role:

gcloud pubsub topics add-iam-policy-binding gmail-notifications \
  --project=YOUR_PROJECT_ID \
  --member="serviceAccount:gmail-api-push@system.gserviceaccount.com" \
  --role="roles/pubsub.publisher"

Note: In the Google Cloud Console UI, the "Publisher" role may not appear in the dropdown by default — type "publisher" in the search bar to find it, or use the CLI command above.

Step 4 — Create a Push Subscription

gcloud pubsub subscriptions create gmail-notifications-push \
  --topic=gmail-notifications \
  --push-endpoint=https://YOUR_DOMAIN/api/webhooks/gmail/notifications \
  --project=YOUR_PROJECT_ID

Step 5 — Configure OAuth 2.0

In Google Cloud Console → Credentials:

1. Create an OAuth 2.0 Client ID (type: Web application)
2. Add authorized redirect URI: https://YOUR_DOMAIN/integrations/google/callback
3. Add scope: https://www.googleapis.com/auth/gmail.readonly

Step 6 — Set Environment Variables

GOOGLE_INTEGRATION_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_INTEGRATION_CLIENT_SECRET=GOCSPX-xxxxxxxxxx
GOOGLE_INTEGRATION_REDIRECT_URI=https://YOUR_DOMAIN/integrations/google/callback

GMAIL_PUBSUB_PROJECT_ID=your-gcp-project-id
GMAIL_PUBSUB_TOPIC=gmail-notifications

PUBLIC_BASE_URL=https://YOUR_DOMAIN

Step 7 — Connect Gmail Account

In the apowerb-ui UI: Integrations → Connect Google (Gmail)

Step 8 — Create Webhook Subscription

Via UI (Webhook Manager) or API:

curl -X POST https://YOUR_DOMAIN/api/webhooks/subscriptions \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google_gmail",
    "resource": "INBOX",
    "agent_id": "AGENT_ID",
    "change_type": "created"
  }'

Outlook Webhook Setup

Prerequisites

• A registered Microsoft Azure AD application
• Microsoft Graph API permissions: Mail.Read
• A publicly accessible HTTPS URL

Setup

1. Configure MICROSOFT_INTEGRATION_* environment variables
2. Connect Outlook integration in the UI
3. Create a webhook subscription with "provider": "microsoft_outlook"

The Outlook handler uses Microsoft Graph change notifications with clientState validation.

Webhook Troubleshooting

RAG (Retrieval-Augmented Generation)

RAG lets agents answer questions based on documents you provide — PDFs, web pages, database exports, or S3 files.

How It Works

Upload documents → Documents get indexed (via th2llm) → Agent searches them when answering

Indexing Sources

Tracking Progress

• Poll: GET /api/rag/status/{knowledge_id}
• Stream (SSE): GET /api/rag/stream/{agent_id}?session_id=xxx

Security

• Path traversal prevention on session/agent IDs
• SSRF protection on URL indexing (blocks localhost, private IPs)
• Session ownership validation
• HMAC-SHA256 signature verification on th2llm webhooks

Text-to-SQL

Agents can connect to relational databases and convert natural language questions into SQL queries.

1. Create a database tool config with connection parameters
2. Create an agent with text_to_sql tool enabled
3. Ask questions — the agent introspects the schema, generates SQL, executes it, and returns results

SSE Streaming

Three SSE streaming channels are available:

Credits and billing

Not in this edition. The user row carries a credit balance and transactions / credit_purchases exist in the schema, but the packages, the Stripe checkout and the crediting logic belong to the billing brick. /api/billing/* answers 404 here.

The llm_usage table is declared here, but nothing in the core writes to it: the metering is the usage brick's job. A core-only install has the table and leaves it empty.

Scheduled runs

Agent runs can be automated on a schedule. The core does not run the cron itself: it registers the schedule with an external orchestrator, selected by ORCHESTRATOR (th2etl, or the historical mage which is still the code default).

POST /api/adk/schedule_run
{
  "agent_id": "agent42",
  "user_id": "user@example.com",
  "session_id": "session_scheduled",
  "new_message": {
    "role": "user",
    "parts": [{ "text": "Generate the daily report" }]
  },
  "schedule_interval": "@daily",
  "start_time": "2026-03-10T08:00:00"
}

Schedule Presets

Agent Hub

Agents can be published to a shared Hub and cloned by other users:

• POST /api/hub/publish — Publish an agent (copies config, tools, instructions)
• POST /api/hub/clone — Clone a Hub agent into your workspace
• GET /api/hub — Browse available agents

Database Models

Sessions, events and ADK artifacts live in the tables Google ADK owns (sessions, events), which supervision reads directly rather than fanning out one HTTP call per agent.

Some columns here serve bricks rather than the core: credits, stripe_customer_id, mfa_* and the transactions / credit_purchases / llm_usage tables are declared so a brick can use them, and stay untouched without one.

Supported Models

Via LiteLLM, all major model providers are supported:

• Anthropic: anthropic/claude-sonnet-4-5-20250929, anthropic/claude-3-haiku-20240307
• OpenAI: openai/gpt-4o, openai/gpt-4, openai/gpt-3.5-turbo
• Mistral: mistral/mistral-large-latest
• Google: gemini/gemini-pro
• OVHcloud: ovhcloud/DeepSeek-R1-Distill-Llama-70B
• And more...

Development

# Install development dependencies
uv sync --group dev

# Run tests
pytest

# Linting
ruff check .
ruff format .

Troubleshooting

Common Errors

Detailed API Guide

Guides, quickstart and the generated API reference are at docs.apowerb.com. Their source lives in apowerb/apowerb-docs.

Support

For questions or contributions, contact the thaink² team.

License

Proprietary - thaink² 2025