Agent Profiles

Agent profiles let you define specialized sub-agents that the primary agent can delegate to using the nb__delegate tool. Each profile specifies a purpose, system prompt, tool access, and optional resource limits.

Defining agents

Add an agents object to your nimblebrain.json. Each key is the agent name, and the value is the profile configuration.

{
  "agents": {
    "researcher": {
      "description": "Searches RFP databases and summarizes findings",
      "systemPrompt": "You are a research agent. Search for relevant RFPs and summarize the key requirements, deadlines, and evaluation criteria.",
      "tools": ["rfpsearch__*", "nb__*"],
      "maxIterations": 8,
      "model": "claude-sonnet-4-5-20250929"
    },
    "writer": {
      "description": "Drafts proposal sections from research notes",
      "systemPrompt": "You are a technical writer. Given research notes, draft clear and persuasive proposal sections. Use active voice and concrete examples.",
      "tools": ["filesystem__*"],
      "maxIterations": 5
    },
    "analyst": {
      "description": "Analyzes data using SQL queries",
      "systemPrompt": "You are a data analyst. Write and run SQL queries to answer questions. Return results as markdown tables.",
      "tools": ["postgres__*", "nb__*"],
      "maxIterations": 12
    }
  }
}

Profile fields

Field	Type	Required	Default	Description
description	string	Yes	—	Human-readable description of the agent’s purpose. The primary agent sees this when deciding which agent to delegate to.
systemPrompt	string	Yes	—	System prompt injected when this agent runs. Defines the agent’s behavior and constraints.
tools	string[]	Yes	—	Tool name glob patterns the agent can access. Only matching tools are available to the child agent.
maxIterations	integer	No	10	Maximum iterations for this agent. Range: 1—25. Capped at the parent agent’s remaining iteration budget minus 1.
model	string	No	Workspace default	Model override for this agent. Use this to assign cheaper models to simpler tasks.

Tool glob patterns

The tools array uses glob patterns to filter which tools the child agent can access. Each pattern is matched against the full tool name (in the format servername__toolname).

Pattern	Matches
rfpsearch__*	All tools from the rfpsearch server
nb__*	All system tools (nb__discover_tools, nb__delegate, etc.)
postgres__query	Only the query tool from the postgres server
*__search	Any tool named search from any server
*	All tools (no filtering)

Tip

Include nb__* in the tools array if you want the child agent to discover additional tools or delegate further. Omit it to create a tightly scoped agent that can only use the tools you explicitly allow.

How delegation works

When the primary agent calls nb__delegate, NimbleBrain:

1. Looks up the named agent profile from the config
2. Creates a child AgentEngine run with the profile’s system prompt
3. Filters the available tools to only those matching the tools globs
4. Caps the child’s iteration budget at min(profile.maxIterations, parent.remaining - 1)
5. Runs the child agent to completion and returns its response to the parent

Multiple delegations in the same turn run concurrently via Promise.all(). The primary agent can delegate to different agents in parallel for independent sub-tasks.

Iteration budget

The child agent’s iteration budget is the lesser of:

• The maxIterations value in the agent profile (default 10)
• The parent agent’s remaining iterations minus 1

This prevents child agents from consuming the parent’s entire budget. If the parent has 3 iterations remaining, the child gets at most 2, regardless of the profile’s maxIterations setting.

Example: research and write workflow

This config defines a two-agent workflow where a researcher gathers information and a writer produces content:

{
  "agents": {
    "researcher": {
      "description": "Searches the web and internal databases for information",
      "systemPrompt": "You are a research agent. Search for information relevant to the user's question. Return structured notes with sources.",
      "tools": ["websearch__*", "rfpsearch__*", "nb__*"],
      "maxIterations": 10
    },
    "writer": {
      "description": "Writes polished content from research notes",
      "systemPrompt": "You are a writer. Transform research notes into clear, well-structured prose. Cite sources. Use active voice.",
      "tools": ["filesystem__write_file", "filesystem__read_file"],
      "maxIterations": 5,
      "model": "claude-sonnet-4-5-20250929"
    }
  }
}

The primary agent orchestrates by delegating research tasks to researcher, then passing the results to writer for final output.