Agents

The agent system allows Nilux AI to delegate complex, multi-step tasks to specialized subagents. Instead of handling everything in the main conversation, the primary agent can launch autonomous subagents that work independently and return summarized results. This keeps the main conversation focused while enabling deep, parallel work.

Why Agents?

When a task requires many tool calls — searching dozens of files, running multiple commands, or exploring an unfamiliar codebase — doing it all in the main conversation would consume context and slow you down. Subagents solve this by:

Running in isolation — Each subagent has its own context window and tool loop
Working in parallel — Multiple subagents can run simultaneously
Returning summaries — Results are condensed before returning to the main conversation
Using specialized toolsets — Each agent type has a tailored set of available tools

Built-in Agent Types

Explore Agent

A fast, read-only agent specialized for codebase exploration.

Tools: Read, Glob, Grep, Bash
Disallowed: Write, Edit, MultiEdit, NotebookEdit, Task
Use for: Finding files by pattern, searching code for keywords, answering questions about the codebase, tracing imports, understanding project structure
Safety: Cannot modify any files

> Find all authentication-related code in this project

Agent launches Explore subagent:
  prompt: "Find all files and code related to authentication:
          login, logout, token refresh, session management.
          Search for auth, login, logout, token, session keywords.
          Return a structured summary of the authentication flow."

Result:
  Authentication is implemented across 8 files:
  1. src/auth/login.ts — Main login handler
  2. src/auth/tokens.ts — Token management
  3. src/middleware.ts — Route protection
  4. src/lib/api.ts — Auth header injection
  5. src/lib/auth-context.tsx — React auth context
  6. src/components/LoginForm.tsx — Login UI
  7. src/auth/refresh.ts — Token refresh logic
  8. src/auth/logout.ts — Session cleanup

  Flow: LoginForm → login.ts → tokens stored → middleware checks → api.ts injects → refresh on 401

Task Agent

A full-access general-purpose agent for complex, multi-step tasks.

Tools: All tools (Read, Write, Edit, Glob, Grep, Bash, Web Search)
Use for: Multi-file refactors, implementing features, running test suites and fixing failures, complex debugging sessions
Safety: Shows diffs for approval before applying changes

> Refactor all API calls to use the new error handling pattern

Agent launches Task subagent:
  prompt: "Replace all instances of try-catch in src/lib/api.ts
          and src/lib/services/*.ts with the new handleApiError()
          utility. Run tests after changes and fix any failures."

Result:
  ✓ Refactored 3 files:
    - src/lib/api.ts (4 instances updated)
    - src/lib/services/user-service.ts (2 instances updated)
    - src/lib/services/data-service.ts (1 instance updated)
  ✓ Tests passing (12/12)

Specialized Agent Types

Beyond the two built-in agents, Nilux AI can be configured with specialized agent types for specific domains. Here are the supported specializations:

Architect Agent

Designs system architecture, API schemas, and component hierarchies.

Best for: Planning new features, designing database schemas, defining API contracts
Tools: Read, Glob, Grep, Bash (read-only commands)
Output: Architecture documents, diagrams (Mermaid), schema definitions

Code Reviewer Agent

Reviews code for bugs, security issues, and best practice violations.

Best for: Pre-commit review, security audits, performance analysis
Tools: Read, Grep, Glob
Output: Review comments with severity levels and fix suggestions

Test Writer Agent

Writes and maintains unit, integration, and end-to-end tests.

Best for: Adding test coverage, writing tests for new features, fixing flaky tests
Tools: Read, Write, Edit, Grep, Bash
Output: Test files with complete coverage

Debugger Agent

Traces bugs through the codebase, isolates root causes, and proposes fixes.

Best for: Reproducing and fixing complex bugs, analyzing error logs
Tools: Read, Grep, Bash, Edit
Output: Bug analysis with root cause and fix

Documentation Agent

Generates and maintains code documentation, READMEs, and API docs.

Best for: Documenting APIs, writing JSDoc/TSDoc comments, creating README files
Tools: Read, Write, Edit, Glob, Grep
Output: Documentation files and inline doc comments

Refactoring Agent

Performs large-scale code transformations safely.

Best for: Renaming symbols across the codebase, extracting shared utilities, migrating to new patterns
Tools: Read, Edit, Write, Grep, Glob, Bash
Output: Refactored code with minimal diff

Dependency Agent

Manages package dependencies, audits for vulnerabilities, and resolves conflicts.

Best for: Upgrading packages, resolving version conflicts, auditing security advisories
Tools: Read, Bash, Edit, Web Search
Output: Updated lockfiles and dependency reports

Database Agent

Designs and modifies database schemas, writes migrations, and optimizes queries.

Best for: Creating migrations, optimizing slow queries, designing indexes
Tools: Read, Write, Edit, Bash, Grep
Output: Migration files and query optimizations

DevOps Agent

Manages CI/CD pipelines, Docker configurations, and deployment scripts.

Best for: Setting up GitHub Actions, writing Dockerfiles, configuring deployment
Tools: Read, Write, Edit, Bash, Grep
Output: Pipeline configurations and deployment manifests

Security Agent

Performs security-focused code analysis and vulnerability scanning.

Best for: Finding XSS, SQL injection, and authentication vulnerabilities
Tools: Read, Grep, Glob, Web Search
Output: Security report with prioritized findings

Launching Agents

The main agent decides when to launch subagents based on task complexity. You can also explicitly request them:

> Use a subagent to review all my recent changes for security issues

> Launch an Explore agent to find where error handling is implemented

> Have two agents work in parallel: one finding bugs, one writing tests

Parallel Execution

Multiple agents can run simultaneously. The main agent can launch several agents in a single message:

Agent launches 3 Explore agents in parallel:

Agent 1: "Find all API route handlers"
Agent 2: "Find all database queries"
Agent 3: "Find all authentication checks"

All three run concurrently and return results independently.

Tip: Parallel agents are significantly faster for broad codebase analysis. Use them when you need to search for multiple unrelated patterns.

Background Agents

Long-running agents can be launched in the background. The main agent receives a notification when the background agent completes:

> Run a Task agent in the background to refactor the entire utils directory

Agent launches background Task:
  description: Refactor utils directory
  run_in_background: true

[Agent continues working on other tasks...]

Task agent completed: Refactor utils directory
Output saved to: /tmp/nilux-agent-output-abc123.json

Agent Configuration

Each agent type is defined by:

Property	Description
`agent_type`	Identifier: Explore, Task, or a specialized type
`tools`	List of tools the agent can use (`*` for all)
`disallowed_tools`	Tools explicitly blocked for this agent
`model`	LLM model to use (or `inherit` for the main agent's model)
`critical_reminder`	Custom instruction injected into the agent's context
`disallow_background`	Whether background execution is blocked

Agent Results

Subagent results are not directly visible to you — the main agent receives the output, summarizes it, and presents the relevant findings. This keeps the conversation focused and avoids dumping raw agent output.

For background agents, the output is written to a file. The main agent reads this file when the agent completes.

Best Practices

Be specific in your prompts — The more detailed the subagent's task description, the better the results
Use Explore for search — It's faster and safer for codebase exploration
Use Task for changes — Full tool access for implementation work
Run in parallel when possible — Independent searches benefit from concurrency
Review agent changes — Subagent edits show diffs for your approval

Warning: Subagents are stateless. Each invocation is independent. If you need an agent to continue previous work, provide sufficient context in the prompt.

Next Steps

Tools Overview — Tools available to agents
MCP Overview — Extending with custom tools
Skills — Reusable prompt templates
Quickstart — Start using Nilux AI