Modelguide

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/modelguide-logo-dark.svg" /> <img src="assets/modelguide-logo-light.svg" height="60" alt="Model Guide" /> </picture> </p> <h3 align="center">Ship support & sales agents with confidence.</h3> <p align="center"> Open-source production harness for AI agents — voice, chat, email, any channel.<br/> SOPs · Connectors · Session Recording · Evals · RBAC — one TypeScript codebase, zero vendor lock-in. </p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>&nbsp; <a href="https://github.com/modelguide/modelguide/actions/workflows/ci.yml"><img src="https://github.com/modelguide/modelguide/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI Status" /></a>&nbsp; <a href="https://cla-assistant.io/modelguide/modelguide"><img src="https://cla-assistant.io/readme/badge/modelguide/modelguide" alt="CLA assistant" /></a> </p> <p align="center"> <a href="#quick-start">Quick Start</a> · <a href="docs/guide/mcp-integration.md">Connect Your Agent</a> · <a href="docs/guide/admin-guide.md">Admin Guide</a> · <a href="#adding-a-connector">Build a Connector</a> · <a href="#roadmap">Roadmap</a> </p>

<a href="https://www.youtube.com/watch?v=melFDGiA6gg" target="_blank"><img src="https://img.youtube.com/vi/melFDGiA6gg/maxresdefault.jpg" alt="ModelGuide Demo" /></a>

The Problem

Your agent handles demos. Production needs session tracking, tool management, evals, SOPs, and integrations with every system your company runs. Every team rebuilds this from scratch.

Today you ship a chat agent. Tomorrow the business wants voice and email — and you're starting over because nothing was built to carry across channels.

The boring stuff between "it works" and "it ships" — that's what kills timelines. Not the AI. SaaS charges $150K+ for this harness. We open-sourced it.

80% of the infrastructure comes ready: auth, sessions, connectors, SOPs, evals, analytics. You customize the 20% that makes your agent yours. The first blueprint — a contact center agent — is shipping now. Fork it, or start fresh for any vertical: healthcare intake, field service, B2B sales, internal ops.

What ModelGuide Does

<video src="https://github.com/user-attachments/assets/811f1756-4948-461e-abdd-7691ee3d9ccc " controls width="100%"></video>

ModelGuide is the infrastructure layer between your AI agents and your business systems. It doesn't run the AI or own the voice stack — it gives you four production-ready layers you'd otherwise build from scratch:

Tool layer — Connectors expose your business systems (orders, tickets, calendars) as tools any AI agent can call via MCP. One integration works with every platform.

Observation layer — Every session recorded with full tool call traces: inputs, outputs, latency, errors, CSAT scores, internal QA. Not just "call duration" — what the agent actually did.

Configuration layer — Agent configs, API keys, tool assignments, per-tool confirmation gates. Swap the voice platform, keep your entire backend.

SOP layer — Define step-by-step procedures, link them to specific tools, and assign them to agents. Agents follow your playbook instead of improvising — consistent behavior across every interaction.

Analytics layer — Resolution rates, escalation trends, CSAT scores, session volume by channel — the metrics you need to prove agents are working, not vanity dashboards.

<table> <tbody> <tr> <td align="center"><strong>Connectors</strong></td> <td align="center"><strong>Sessions</strong></td> <td align="center"><strong>Agents</strong></td> </tr> <tr> <td><a href="./docs/Connectors.png"><img src="./docs/Connectors.png" alt="Connectors" width="260"></a></td> <td><a href="./docs/Converstation.png"><img src="./docs/Converstation.png" alt="Sessions" width="260"></a></td> <td><a href="./docs/Data.png"><img src="./docs/Data.png" alt="Agents" width="260"></a></td> </tr> <tr> <td align="center"><strong>SOPs</strong></td> <td align="center"><strong>Analytics</strong></td> <td></td> </tr> <tr> <td><a href="./docs/SOPs.png"><img src="./docs/SOPs.png" alt="SOPs" width="260"></a></td> <td><a href="./docs/Optimize.png"><img src="./docs/Optimize.png" alt="Analytics" width="260"></a></td> <td></td> </tr> </tbody> </table>

Features

Everything you need to go from demo to production:

✅ Connector System — Code-defined manifests with real HTTP handlers. Ships with a Medusa e-commerce connector as a reference implementation (8 tools: browse products, manage carts, checkout, orders). Build your own — implement the ConnectorManifest interface and add a handler function per tool.

✅ Tool Namespacing — Connector instances get a unique slug. Same connector type, different instances: glowbox_store_add_to_cart and clearhealth_pharmacy_add_to_cart coexist on the same agent.

✅ MCP Protocol — Standard Model Context Protocol over Streamable HTTP. Tool discovery, execution, and resources. Works with any MCP-compatible client.

✅ Confirmation Gates — Flag destructive tools as requiring customer confirmation before execution. The requires_confirmation flag tells the AI agent to verify intent before proceeding (e.g., completing a checkout).

✅ Session Recording — Full message history with roles, timestamps, audio URLs, tool call inputs/outputs. Sequence-numbered for correct ordering.

✅ CSAT + QA — Customer feedback via core_rate_session. Internal quality evaluation by support team with tags and comments. Both stored per session, filterable in dashboard.

✅ Multi-Tenant — PostgreSQL row-level security on every org-scoped table. Separate DB roles: superuser for migrations, app role subject to RLS policies. One deployment, multiple organizations.

✅ Auth — Magic link passwordless login for dashboard users. API key auth (mgk_ prefix, SHA-256 hashed, shown once on creation) for agents. Refresh token rotation with family-based revocation.

✅ RBAC — Granular permissions across admin and support roles. Agents get a separate auth path — they can only access MCP, not REST endpoints.

✅ Auto-Generated API Docs — OpenAPI 3.1 spec generated from Hono route definitions. Scalar UI at /docs.

✅ SOPs (Standard Operating Procedures) — Define agent behavioral contracts: ordered steps with tool references, triggers, and metadata. Fork from reusable templates or create from scratch. Draft/active/archived lifecycle. Assign SOPs to agents. Inactive-tool warnings at read time. See ADR-005.

✅ CI Pipeline — Lint, typecheck, unit tests, integration tests on every PR. Includes MCP protocol tests using the official SDK client.

AI-Assisted Development

ModelGuide is built with AI coding agents, not just for them. We're progressively building a development harness — enforced module boundaries, structured issue specs, mechanical convention enforcement via CI, and agent-to-agent code review — so that any AI coding agent can implement features, write tests, and open PRs with minimal hand-holding. We also use slash commands available to all contributors for common workflows like committing, reviewing PRs, and implementing issues.

We'll keep harness artifacts public.

Quick Start

Prerequisites: Docker 24+, Bun 1.1+, Node 22+

git clone https://github.com/modelguide/modelguide.git
cd modelguide
make quickstart

Then in separate terminals:

make api-dev    # API at http://localhost:3000
make ui-dev     # Dashboard at http://localhost:3001

Open http://localhost:3001. The seed creates three industry-vertical organizations — each with Medusa e-commerce and Zendesk helpdesk connectors, two agents, and ~300 realistic sessions. Log in with delivered+admin-glowbox@resend.dev (magic link printed to API console).

See Seed Data for the full list of organizations and use cases.

API docs are auto-generated at http://localhost:3000/docs.

How It Works

1. Define connectors in code

Each connector is a TypeScript module with a manifest and tool handlers:

// src/features/connectors/catalog/medusa/index.ts
const manifest: ConnectorManifest = {
  name: "Medusa",
  slug: "medusa",
  description: "E-commerce connector for carts, orders, and products",
  connectorType: "api",
  configSchema: {
    baseUrl: { type: "string", required: true },
    publishableKey: { type: "string", required: true },
  },
  authMethods: ["api_key"],
  iconUrl: "/logos/medusa.svg",
  tools: [
    {
      catalog: {
        name: "Add to Cart",
        description: "Add an item to the shopping cart",
        inputSchema: { /* JSON Schema */ },
        defaultRequiresConfirmation: false,
      },
      handler: addToCart,  // actual HTTP call to Medusa API
    },
    // ... 7 more tools
  ],
};

export default manifest;

Run make sync-connectors to sync manifests to the database. Admins configure instances through the dashboard — set the API URL, link encrypted credentials, assign tools to agents.

2. Agents connect via MCP

External AI agents authenticate with an API key (mgk_xxx) and get their tools dynamically:

POST /mcp
Authorization: Bearer mgk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

→ tools/list returns only tools assigned to THIS agent
→ Each tool requires an active session_id
→ Tool names are namespaced: glowbox_store_add_to_cart

The MCP handler creates a fresh server per request, registers only the tools that agent is authorized to use, converts JSON Schema to Zod on the fly, and validates sessions before execution.

3. Sessions capture everything

Core MCP tools handle the session lifecy