1. Getting Started & Core Concepts

Welcome to Sutra — the open-source platform that lets you build and run autonomous AI organizations. Forget simple chatbots. With Sutra, you create specialized AI agents that collaborate like a real team: they debate ideas, delegate tasks, use tools, write code, and execute complex workflows — all while keeping you in control of the decisions that matter.

This guide covers everything you need to go from zero to a running Sutra instance: the core concepts behind the platform, how authentication works, and a walkthrough of the dashboard you'll use every day.

Introduction to Sutra

At its core, Sutra is built on the philosophy that AI should be orchestratable, observable, and safe.

What makes an Autonomous Organization?

  • Specialized Personas: Instead of one monolithic AI, you create multiple agents with distinct roles (e.g., a "Senior Developer" agent, a "QA Tester" agent, and a "Project Manager" agent).
  • Tool Use (Agents taking action): Agents are equipped with tools. They can browse the web, run shell commands, query databases, or read files from Google Drive.
  • Hierarchical Collaboration: Agents can route tasks to one another. A manager agent can break down a high-level goal into smaller tasks and delegate them to worker agents.
  • Persistent Memory: Agents maintain context across sessions. They remember past interactions, user preferences, and previous mistakes using a sophisticated three-tier memory system.

Think of it this way: instead of one AI assistant doing everything, you build a team of specialists — each with the right tools, the right context, and clear reporting lines. The result is dramatically better output quality and the ability to handle tasks that would overwhelm a single model.

Platform Architecture Overview

Sutra consists of a high-performance FastAPI (Python) backend utilizing LangGraph and LangChain for agent orchestration, backed by a PostgreSQL database (with pgvector for semantic search). The frontend is a modern Next.js application featuring real-time WebSocket updates and visual canvas interfaces.

Placeholder: Architecture Diagram

Here's a quick breakdown of the key components:

  • Backend (FastAPI + Python): Handles all API requests, agent orchestration, and background task processing. Fully async for high concurrency.
  • Agent Engine (LangChain + LangGraph): Manages the ReAct reasoning loop — agents think, decide which tools to use, execute them, and iterate until the task is complete.
  • Database (PostgreSQL + pgvector): Stores all platform data plus vector embeddings for semantic search across your knowledge base and agent memory.
  • Task Queue (Redis + Celery): Powers background jobs, scheduled workflows, and batch processing without blocking the main API.
  • Frontend (Next.js 14): A responsive dashboard with 30+ pages, real-time WebSocket updates, and a visual workflow builder.
  • Deployment (Docker Compose): Everything runs in containers. One command spins up the entire stack — PostgreSQL, Redis, Celery workers, backend, and frontend.

Authentication & User Management

Security is the foundation of Sutra. All sensitive data, such as API keys and credentials, are encrypted at rest using Fernet symmetric encryption.

First-Time Login

When you first access Sutra, you will be prompted to authenticate. - Local Setup: If running locally for development, Sutra uses standard email/password authentication. - Google OAuth: Sutra supports Google OAuth 2.0 for authentication, configured via GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in your environment variables.

Placeholder: Login Screen

Role-Based Access Control (RBAC)

Not every user should have the ability to spend LLM credits or execute shell commands. Users are assigned roles: - Owner: Full access to system configuration, billing, and global rate limits. - Admin: Can create agents, design workflows, and approve high-risk actions. - Operator: Can chat with agents, trigger workflows, and view monitoring dashboards. - Viewer: Read-only access to dashboards and conversation history.

Tip: Start with the Owner role during initial setup. Once your agents and workflows are configured, create Operator accounts for team members who only need to chat with agents and trigger existing workflows — this keeps your system secure without slowing anyone down.

The Dashboard

The Dashboard is your operational command center. It provides an immediate, real-time snapshot of your autonomous organization's health and activity.

Placeholder: Dashboard Screenshot

1. System Health Indicators

Located at the top of the dashboard, these indicators verify that your infrastructure is operating correctly: - Database: Connection status to PostgreSQL. - Vector Store: Status of pgvector indexing capabilities. - Task Queue: Status of the Redis instance and Celery workers, critical for background jobs and workflow execution.

2. Active Agents Overview

This portlet displays a live view of your agents. - Agent Identity: Shows the agent's name and custom avatar. - Execution Status: A live dot indicator (Green = Running, Yellow = Starting, Red = Error, Gray = Stopped) shows what the agent is currently doing. - Routing Purpose: Instead of just showing the underlying model (like "gpt-4o"), Sutra displays the agent's Purpose (e.g., "Complex Reasoning" or "Fast Drafting"). This reflects Sutra's smart-routing capabilities.

3. Quick Actions & Navigation

The left sidebar provides instant access to all modules—from agent configuration (/agents) to visual workflows (/workflows) and system logs (/logs). Quick action buttons on the dashboard allow you to instantly spawn a new chat or review pending human approvals.

4. Recent Activity Feed

A live timeline of everything happening across your organization — agent responses, workflow executions, completed tasks, and approval requests. Each entry links directly to the relevant conversation or workflow run, so you can jump into context with a single click.

5. Cost & Usage Summary

A quick snapshot of your current token consumption and estimated costs, broken down by provider. If you've set budget limits, you'll see how much headroom remains — no surprises at the end of the month.

6. Pending Approvals

If any agents are waiting for human sign-off on a high-risk action (sending an email, executing a database query, deploying code), they appear here. One click to review the payload, approve, modify, or reject — keeping your autonomous workflows moving without compromising safety.