Architecture

Nebflow organizes AI work into three layers: Agents, Teams, and Flows. Each layer answers a different question:

• Agents — what can be done (capabilities)
• Teams — who owns a project (persistent collaboration)
• Flows — how a fixed process runs (repeatable pipelines)

The Three Layers

Agents

An Agent is a single, self-contained AI worker defined by agent.json and a system prompt. Agents are:

• Stateless — a fresh agent instance carries no conversation history between invocations
• General-purpose — any agent can be directly delegated a one-off task by name: Mail("Explorer", "find the file and summarize it")
• The unit of delegation — standalone agents (category standalone) can be invoked directly by the orchestrator

Agents live in agents/.

Teams

A Team is a persistent project-level collaboration unit. A team:

• Has a lead and members, each backed by a persistent session
• Maintains memory (rules, project knowledge) across sessions
• Contains its own team-scoped agents that only exist within the team
• Can invoke flows as part of its workflow

Teams live in teams/<name>/. Each team has team.json, rules.md, and its own agents/ directory.

Flows

A Flow is a fixed, repeatable DAG pipeline. A flow:

• Defines nodes (each backed by a flow-scoped agent) and the edges between them
• Runs with structured routing — node outputs can goto, switch, or return
• Reuses the same agent definitions every run, with input templating

Flows live in flows/<name>/, with flow.json plus flow-scoped agents in agents/.

Permission Relationship

Team > Agent = Flow

• A Team is composed of Agents and may invoke Flows
• An Agent can be standalone, team-scoped, or flow-scoped
• Flows cannot contain teams; they contain flow-scoped agents
• Team-scoped agents are reachable only through the owning team
• Flow-scoped agents are reachable only through the owning flow

Directory Layout

nebflow/
├── agents/                    # Global (standalone) agents
│   └── <name>/
│       ├── agent.json
│       └── system.md
├── teams/
│   └── <name>/
│       ├── team.json          # name, lead, members, flows
│       ├── rules.md           # injected into every member
│       └── agents/            # Team-scoped agents (self-contained)
├── flows/
│   └── <name>/
│       ├── flow.json          # DAG definition
│       └── agents/            # Flow-scoped agents (output = JSON)
└── nebflow.json               # Global config (providers, MCP, ...)

Choosing a Layer

| Need | Use | |------|-----| | One-off task, no state needed | Agent (Mail("Explorer", ...)) | | Long-running project with memory | Team | | Fixed multi-step process, repeatable | Flow | | Personal knowledge across sessions | Memory (see Memory) |