Agent System Overview
How agents, roles, skills, modes, and MCP integration work together in Nenjo.
Agents are the core execution units of the Nenjo platform. Each agent is powered by a large language model and configured through a layered system of roles, skills, modes, and tool access.
Resource Hierarchy
The agent system follows a clear hierarchy:
Agent (LLM instance)
└── Role (behavior definition)
├── Prompt Config (system prompt, templates, memory profile)
├── Skills (instruction packs with optional API tools)
├── Modes (activatable overlays that modify behavior)
├── Platform Scopes (Nenjo resource access)
└── MCP Servers (external tool connections)An agent is a named LLM instance (model + provider). A role defines everything about how that agent behaves -- its prompts, what tools it can use, and what platform resources it can access. Agents are assigned roles, and roles carry the full configuration.
Per-User Role Copies
Nenjo ships with system template roles that define sensible defaults. When a user first accesses the platform, the system automatically copies these templates into per-user role instances. This means:
- Every user gets their own editable copy of each system role
- Edits to prompts, skills, and mode assignments are private to the user
- New system roles added by migrations are automatically copied on next login
- Users can reset a role back to the system template at any time
The source_role_id field on a role tracks which system template it was copied from. Custom roles created by the user have no source_role_id.
System Templates vs Custom Roles
| Property | System Template | User Copy | Custom Role |
|---|---|---|---|
is_system | true | false | false |
source_role_id | null | points to template | null |
created_by | null | user ID | user ID |
| Editable | No | Yes | Yes |
| Deletable | No | Yes (re-created on next login) | Yes |
| Auto-created | By migration | On user bootstrap | By user |
What Happens at Runtime
When an agent executes a task, the worker assembles the full configuration:
- Prompt assembly -- The role's system prompt, developer prompt, and task-specific template are rendered with context variables
- Tool selection -- Built-in tools are filtered by the understanding profile (read-only by default); modes can unlock write tools
- Platform tools -- MCP tools from the Nenjo backend are filtered by the role's
platform_scopes - External tools -- External MCP server tools are loaded based on role assignments and mode activations
- Skill instructions -- Assigned skill instructions are injected into the system prompt
- Memory -- The role's memory profile guides what the agent remembers and retrieves