Agent

An Agent is a self-contained AI worker. It is the smallest unit of delegation in Nebflow — you can hand it a task by name, and it will work autonomously using its tools.

Directory Layout

Each agent lives in its own directory:

agents/<name>/
├── agent.json     # Definition (required)
└── system.md      # System prompt (optional, recommended)

Team-scoped agents live in teams/<team>/agents/<name>/, flow-scoped agents in flows/<flow>/agents/<short-name>/. The agent.json schema is identical at every scope.

agent.json

{
  "name": "explorer",
  "description": "Scans the codebase and answers questions about project structure.",
  "useWhen": "User asks about code structure, file layout, or where something lives.",
  "tools": ["Read", "Grep", "Glob", "Bash"],
  "category": "standalone",
  "mcpServers": ["github"],
  "model": {
    "preferred": "USTC/glm-4.6",
    "fallbacks": ["USTC/glm-4.5"]
  },
  "voice": "female"
}

Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Unique agent identifier | | description | string | Yes | One-line summary used for routing | | useWhen | string | No | When the orchestrator should delegate to this agent | | tools | string[] | No | Allowed tools (empty = only built-in read-only) | | category | string | No | standalone (default), team, or flow | | mcpServers | string[] | No | MCP servers this agent may use (see Tools) | | voice | string | No | Voice preset for TTS output | | model | object | No | Per-agent model preference + fallbacks |

category

| Category | Scope | Invocation | |----------|-------|------------| | standalone | Global (agents/) | Directly delegatable: Mail("Explorer", ...) | | team | Inside a team (teams/<t>/agents/) | Only through the owning team | | flow | Inside a flow (flows/<f>/agents/) | Only as a flow node |

An agent with no category defaults to standalone. Team- and flow-scoped agents are not directly delegatable — they are reached through their owning entity, which provides the necessary context.

Tools

An agent can use three kinds of tools, all exposed through the same uniform interface (name + input schema + text result):

1. Built-in tools — implemented in Scala: Read, Write, Edit, Bash, Grep, Glob, Mail, WebSearch, WebFetch, Card, and more.
2. External tools — JSON + script in $TOOL_DIR (see Tools).
3. MCP tools — mcp__<server>__<tool> references. An agent may only call MCP tools from servers listed in its mcpServers field.

system.md

The system prompt shapes how the agent behaves. Keep it focused:

• Role — who the agent is and what it owns
• Rules — hard constraints (e.g. "never edit main directly", "prefer vanilla JS")
• Style — output style, tone, format preferences
• Process — step-by-step workflow for typical tasks

Example system.md:

You are the frontend agent. You own all JS/CSS/HTML in this project.

Rules:
- No frameworks — vanilla JS only
- Never use raw hex colors — use CSS custom properties
- Verify UI changes with a screenshot before reporting done

Style:
- Concise, design-conscious output
- Show before/after diffs when modifying CSS

The system prompt is a prompt — not a sandbox. It guides the agent's behavior but does not enforce it; enforce critical boundaries at the tool level.

Delegation

Standalone agents are invoked with Mail:

Mail("Explorer", "Find where restoreTabs is defined and summarize its logic")

The orchestrator routes by matching description and useWhen against the incoming task. Give every agent a precise useWhen to improve routing.