Concepts - NinjaStack Docs
Description: Schema-first agentic backend framework documentation

Skip to content

# Core Concepts

## Agentic Schema Definition (ASD)

The ASD is NinjaStack's single source of truth. It's a typed, composable schema that describes:

- Entities — Your data models (tables, collections, nodes)
- Fields — Typed columns with constraints, indexes, and embedding configs
- Relationships — Hard (FK), soft (semantic), and graph edges between entities
- Domains — Logical groupings of entities under one expert agent
- Agent Configs — Model, reasoning level, temperature per domain

    erDiagram
        AgenticSchema ||--o{ EntitySchema : contains
        AgenticSchema ||--o{ RelationshipSchema : contains
        AgenticSchema ||--o{ DomainSchema : contains
        DomainSchema ||--|| AgentConfig : has
        EntitySchema ||--o{ FieldSchema : has
        FieldSchema ||--o| EmbeddingConfig : may_have
        FieldSchema ||--o| FieldConstraint : may_have

## Agent Hierarchy

NinjaStack organizes agents in a three-tier hierarchy:

### Data Agents

- Extend ADK `BaseAgent`
- Deterministic — no LLM calls
- Own one entity, scoped CRUD tools
- Fast, predictable, testable

### Domain Agents

- Wrap ADK `LlmAgent`
- LLM-powered — use Gemini for reasoning
- Own one business domain (group of entities)
- Delegate to data agents for execution
- Configurable reasoning level (none → low → medium → high)

### Coordinator Agent

- Top-level ADK `LlmAgent`
- Routes requests to the right domain
- Synthesizes cross-domain results
- Intent classification via LLM

## Reasoning Levels

Level | Model | Use Case
--- | --- | ---
`NONE` | — | Deterministic only (data agents)
`LOW` | gemini-2.0-flash | Simple completions
`MEDIUM` | gemini-2.5-flash | Multi-step reasoning
`HIGH` | gemini-2.5-pro | Full chain-of-thought

## Tool Scoping

Every agent only sees its own tools. A Book data agent cannot call Customer tools. A Catalog domain agent cannot access Commerce entities. The coordinator routes across domains but never executes tools directly.

This prevents tool leaking, reduces hallucination surface, and enforces clear ownership boundaries.

## Storage Engines

Entities declare their storage engine:

Engine | Backend | Use Case
--- | --- | ---
`SQL` | PostgreSQL, SQLite | Structured relational data
`MONGO` | MongoDB | Document-oriented data
`GRAPH` | Neo4j | Connected/relationship-heavy data
`VECTOR` | ChromaDB, Pinecone | Semantic search, embeddings

The unified persistence layer handles routing to the correct backend.