Agents
How an agent is built — system (soul) prompt, developer prompt, memory profile, runtime templates, modes, and heartbeat schedules.
Agents are the primary behavioral units in Nenjo, and the composite that assembles every other primitive. An agent defines a role: how work is interpreted, what prompt context matters, which capabilities it can access, and how it behaves across runtime modes.
How an agent is built
An agent's behavior comes from a layered prompt configuration plus a memory profile:
system_prompt— the agent's soul: stable identity, voice, and core principles. This is what abilities inherit and domains build on; it should not change between runs or modes.developer_prompt— tactical behavior: routing, response discipline, and tool-use guidance. This is the layer abilities replace and domains append to.- Memory profile — which memory scopes the agent draws from (
core_focus,project_focus,shared_focus). - Runtime templates — mode-specific wrappers that inject the right variables for each kind of execution.
Put stable identity in the system prompt, tactical behavior in the developer prompt, and reusable framing in context blocks. Runtime templates should supply mode-specific input, not define a different public voice for each mode.
Runtime modes and templates
The identity and memory profile stay stable across modes; the mode changes the template and the injected variables.
| Mode | Description | Template |
|---|---|---|
chat | Conversational interaction with a user | templates.chat |
task | Routine agent-step execution with full context | templates.task |
gate | Evaluation of prior output against acceptance criteria | templates.gate |
heartbeat | Periodic autonomous check | templates.heartbeat |
council | Council member or leader work | templates.task, adapted by the runtime |
Prefer short runtime templates that include a reusable runtime context block (for example {{ pkg.nenjo_ai.packages.context.runtime.task_execution }}) instead of duplicating task, gate, and heartbeat framing across agents.
Heartbeat schedules
An agent can carry an optional heartbeat schedule — a recurring autonomous run for checks and maintenance loops. Heartbeat runs use templates.heartbeat and the heartbeat template variables ({{ heartbeat.instructions }}, {{ heartbeat.previous_output }}, {{ heartbeat.last_run_at }}, {{ heartbeat.next_run_at }}), so each run can follow its configured instructions and reason about what happened last time and when it runs next.
Assigned capability surface
An agent gains capabilities through explicit assignments:
- Abilities — agent-invoked specialist behaviors
- Domains — user-activated execution modes
- MCP servers — external tool integrations
- Script tools — package or native script-backed tools
- Model — the LLM that runs the role
- Platform scopes — permission refs (assigned by users or platform policy, never self-granted)
Start with a clear role and the smallest useful capability set. Add tools, scopes, domains, knowledge, and memory focus deliberately as the agent's responsibility grows. Prefer assigning a focused ability over broadening the base prompt.
Once you have agents, workflows orchestrate several of them into repeatable processes.