How superagent-ai/superagent works
Project Type and Purpose
• This is a full-stack monorepo for “Superagent,” an open-source AI assistant framework and API.
• It provides:
• A Python backend microservice exposing REST endpoints for agents, workflows, memory, tools, vectorstores.
• A Next.js frontend dashboard/UI for user interaction, provisioning agents, viewing logs, billing.
• Infrastructure definitions (Docker Compose orchestrator) for databases, vector stores, observability, and the services themselves.
• API spec and docs generation via the fern/ directory.
• Embeddable JavaScript SDK in libs/embed/.
File-Structure Analysis
• Top-level directories:
• fern/ – API specification (OpenAPI, Fern IDL) and MDX-based documentation.
• libs/.docker/ – docker-compose configs to spin up Supabase (Postgres), Redis, vectorstores (Weaviate), observability (Langfuse), backend, UI, etc.
• libs/embed/ – embeddable JS client for Superagent.
• libs/superagent/ – Python application (app/), ORM schema & migrations (prisma/), prompts, services, Dockerfile.
• libs/ui/ – Next.js (app router) React frontend, server-side routes under app/api, Supabase migrations for auth, UI config for Stripe, SAML, theming, etc.
• Architectural patterns:
• Clean separation of concerns: frontend vs. backend vs. infra.
• Plugin-style modules under app/tools/, app/vectorstores/.
• Microservices/containers orchestrated by Docker Compose.
• API spec-as-code in fern/ driving generators.
Key README Insights
• Features: REST API, memory (Redis, vectorstores), streaming, Python & TypeScript SDKs.
• Supports proprietary & open-source LLMs, third-party vector stores.
• Encourages self-hosted infrastructure via Docker Compose.
Detail Level
• Major directory/module as a component.
• Plugin buckets (app/tools, app/vectorstores) as collections within the backend.
• Don’t over-fragment—group related submodules under a single service block when possible.