Skip to content

Understanding Agents

Jump to bottom
Alessio Rocchi edited this page Jan 29, 2026 · 2 revisions

Understanding Agents

Complete guide to aistack's 11 specialized agent types.

What is an Agent?

An agent in aistack is a specialized AI entity with:

  • Unique purpose - Specific role (coder, tester, reviewer, etc.)
  • System prompt - Specialized instructions that define behavior
  • Capabilities - Declared skills and expertise
  • State - Lifecycle status (idle, running, completed, failed, stopped)
  • Context - Optional session and metadata association

Agents are ephemeral - they exist in memory during runtime and are spawned on-demand.

The 11 Agent Types

Quick Reference

Agent Type Primary Role Best For
Coder Write and modify code Implementation tasks
Researcher Gather information Code exploration, documentation review
Tester Write and run tests Test creation, quality assurance
Reviewer Code review Quality checks, best practices
Adversarial Break code Security testing, edge case discovery
Architect System design Technical decisions, architecture
Coordinator Orchestrate agents Multi-agent workflows
Analyst Analyze data Performance analysis, metrics
DevOps Infrastructure CI/CD, containers, deployment
Documentation Write docs API docs, guides, tutorials
Security Auditor Security audit Vulnerability scanning, compliance

Agent Lifecycle

stateDiagram-v2
    [*] --> Spawned: agent_spawn()
    Spawned --> Idle: Ready for work
    Idle --> Running: Task assigned
    Running --> Idle: Task complete
    Running --> Failed: Error occurred
    Running --> Stopped: agent_stop()
    Idle --> Stopped: agent_stop()
    Failed --> [*]
    Stopped --> [*]
Loading

States Explained

  • Spawned: Agent created, initializing
  • Idle: Ready to accept tasks
  • Running: Actively processing a task
  • Completed: Task finished successfully
  • Failed: Task encountered an error
  • Stopped: Agent manually terminated

How Agents Work

1. Spawning

// Via MCP
{
  "tool": "agent_spawn",
  "arguments": {
    "type": "coder",
    "name": "my-coder",
    "sessionId": "optional-session-id",
    "metadata": { "project": "awesome-app" }
  }
}

// Via TypeScript API
import { spawnAgent } from '@blackms/aistack';

const agent = spawnAgent('coder', {
  name: 'my-coder',
  sessionId: 'session-123',
  metadata: { project: 'awesome-app' }
});

What Happens:

  1. Agent definition loaded from registry
  2. Unique ID generated (UUID v4)
  3. System prompt prepared
  4. Agent added to active agents pool
  5. Status set to 'idle'

2. Task Execution

When an agent receives a task:

sequenceDiagram
    participant User
    participant Agent
    participant LLM
    participant Memory

    User->>Agent: Execute task
    Agent->>Agent: Set status: running
    Agent->>Memory: Retrieve context
    Memory-->>Agent: Relevant data
    Agent->>LLM: Send prompt + context
    LLM-->>Agent: Response
    Agent->>Memory: Store results
    Agent->>Agent: Set status: idle
    Agent-->>User: Return results
Loading

3. Context & Memory

Agents can access:

  • Session context - Shared with other agents in same session
  • Memory entries - Persistent storage via SQLite + FTS5
  • Metadata - Custom data passed at spawn time

Agent Capabilities

Each agent declares capabilities:

// Example: Coder agent
{
  type: 'coder',
  capabilities: [
    'write-code',
    'edit-code',
    'refactor',
    'debug',
    'implement-features'
  ]
}

Why Capabilities Matter

  1. Self-documentation - Agents declare what they can do
  2. Task routing - Coordinators assign tasks based on capabilities
  3. User guidance - Users know what to expect from each agent

Detailed Agent Breakdown

1. Coder Agent

Purpose: Write, edit, and refactor code

Capabilities:

  • Write new code from specifications
  • Edit existing code
  • Refactor for better quality
  • Debug issues
  • Implement features

Best Practices:

// Good: Specific task
"Implement a JWT validation function with TypeScript"

// Bad: Vague request
"Do some coding"

Example Use Cases:

  • Implement new features
  • Fix bugs
  • Refactor legacy code
  • Add error handling
  • Optimize algorithms

2. Researcher Agent

Purpose: Gather information from code and docs

Capabilities:

  • Search codebase
  • Read documentation
  • Analyze patterns
  • Gather requirements
  • Explore architecture

Best Practices:

// Good: Focused research
"Find all authentication-related functions in the codebase"

// Bad: Unfocused
"Tell me about the code"

Example Use Cases:

  • Understand existing code
  • Find usage patterns
  • Gather requirements
  • Identify dependencies
  • Map system architecture

3. Tester Agent

Purpose: Write and run tests

Capabilities:

  • Write unit tests
  • Write integration tests
  • Run test suites
  • Identify edge cases
  • Coverage analysis
  • Test debugging

Best Practices:

// Good: Complete test request
"Write comprehensive tests for the JWT validation function, including edge cases"

// Bad: Incomplete
"Write tests"

Example Use Cases:

  • Create test suites
  • Improve coverage
  • Test edge cases
  • Debug failing tests
  • Performance testing

4. Reviewer Agent

Purpose: Review code for quality and best practices

Capabilities:

  • Code review
  • Security review
  • Performance review
  • Best practices check
  • Provide feedback

Best Practices:

// Good: Specific review scope
"Review the authentication module for security and best practices"

// Bad: Too broad
"Review everything"

Example Use Cases:

  • Pre-commit reviews
  • Pull request reviews
  • Security checks
  • Performance optimization
  • Code quality audits

5. Adversarial Agent

Purpose: Aggressively try to break code

Capabilities:

  • Adversarial review
  • Security audit
  • Edge case analysis
  • Attack vector identification

Best Practices:

// Used in review loops
{
  "tool": "review_loop_start",
  "arguments": {
    "code": "function authenticate(user, pass) { ... }",
    "maxIterations": 3
  }
}

Example Use Cases:

  • Security-critical code
  • API endpoints
  • Authentication systems
  • Data validation
  • Payment processing

6. Architect Agent

Purpose: Design systems and make technical decisions

Capabilities:

  • System design
  • Technical decisions
  • Architecture review
  • Documentation
  • Trade-off analysis

Best Practices:

// Good: Clear design problem
"Design a scalable user notification system supporting email, SMS, and push notifications"

// Bad: Unclear scope
"Design a system"

Example Use Cases:

  • New feature architecture
  • System design reviews
  • Technology selection
  • Scalability planning
  • Migration strategies

7. Coordinator Agent

Purpose: Orchestrate multi-agent workflows

Capabilities:

  • Task decomposition
  • Agent coordination
  • Progress tracking
  • Result synthesis
  • Workflow management

Best Practices:

// Good: Complex multi-step task
"Build a complete user registration system with tests and documentation"

// Coordinator decomposes:
// 1. Architect: Design the system
// 2. Coder: Implement registration
// 3. Tester: Create tests
// 4. Security Auditor: Security review
// 5. Documentation: Write API docs

Example Use Cases:

  • Complex features
  • End-to-end workflows
  • Multi-component systems
  • Large refactorings
  • System migrations

8. Analyst Agent

Purpose: Analyze data and performance

Capabilities:

  • Data analysis
  • Performance profiling
  • Metrics collection
  • Trend analysis
  • Reporting

Best Practices:

// Good: Specific analysis
"Analyze API response times over the last week and identify bottlenecks"

// Bad: Vague
"Analyze performance"

Example Use Cases:

  • Performance profiling
  • Code complexity analysis
  • Usage pattern analysis
  • Benchmark comparison
  • Trend identification

9. DevOps Agent

Purpose: Manage infrastructure and deployment

Capabilities:

  • CI/CD setup
  • Containerization
  • Kubernetes deployment
  • Infrastructure automation
  • Monitoring setup
  • Security hardening
  • Cloud deployment
  • Performance optimization

Best Practices:

// Good: Specific infrastructure task
"Create a GitHub Actions CI/CD pipeline with testing, build, and deploy stages"

// Bad: Too broad
"Set up DevOps"

Example Use Cases:

  • Docker containerization
  • Kubernetes manifests
  • CI/CD pipelines
  • Infrastructure as code
  • Monitoring configuration
  • Cloud deployment

10. Documentation Agent

Purpose: Create comprehensive documentation

Capabilities:

  • API documentation
  • User guides
  • Tutorials
  • Code documentation
  • Architecture docs
  • Runbooks
  • README creation
  • Documentation review

Best Practices:

// Good: Specific doc type
"Create API documentation for the user authentication endpoints with examples"

// Bad: Generic
"Write docs"

Example Use Cases:

  • API reference docs
  • Getting started guides
  • Architecture documentation
  • Inline code comments
  • README files
  • Tutorial creation

11. Security Auditor Agent

Purpose: Comprehensive security analysis

Capabilities:

  • Vulnerability scanning
  • Code security review
  • Penetration testing
  • Compliance checking
  • Dependency audit
  • Threat modeling
  • Security documentation
  • Remediation planning

Best Practices:

// Good: Specific security scope
"Audit the user authentication system for OWASP Top 10 vulnerabilities"

// Bad: Too vague
"Check security"

Example Use Cases:

  • OWASP compliance checks
  • Dependency vulnerability scans
  • Security code reviews
  • Threat modeling
  • PCI DSS compliance
  • HIPAA compliance

Agent Composition Patterns

Pattern 1: Sequential Chain

Researcher → Coder → Tester → Reviewer

Use Case: Feature implementation

  1. Researcher gathers requirements
  2. Coder implements feature
  3. Tester creates tests
  4. Reviewer validates quality

Pattern 2: Parallel Execution

         ┌─ Coder (Frontend)
Task ──┼─ Coder (Backend)
         └─ Documentation

Use Case: Full-stack feature

  • Frontend and backend developed in parallel
  • Documentation written concurrently

Pattern 3: Iterative Loop

Coder ←→ Adversarial

Use Case: Security-critical code

  1. Coder implements
  2. Adversarial finds issues
  3. Coder fixes
  4. Repeat until approved

Pattern 4: Hierarchical

Coordinator
    ├─ Architect (Design)
    ├─ Coder (Implement)
    ├─ Tester (Test)
    └─ Security Auditor (Audit)

Use Case: Complex system

  • Coordinator manages overall workflow
  • Specialized agents handle specific tasks

Agent Communication

Direct

// User directly interacts with agent
spawnAgent('coder', { name: 'my-coder' });
// Give task to my-coder

Via Message Bus

import { getMessageBus } from '@blackms/aistack';

const bus = getMessageBus();

// Agent A sends message to Agent B
bus.send(agentA.id, agentB.id, 'task:assign', {
  task: { /* task data */ }
});

// Agent B receives and processes
bus.subscribe(agentB.id, (message) => {
  if (message.type === 'task:assign') {
    // Handle task
  }
});

Via Coordinator

// Coordinator orchestrates multiple agents
const coordinator = new HierarchicalCoordinator({
  maxWorkers: 5,
  sessionId: 'session-123'
});

await coordinator.submitTask({
  type: 'build-feature',
  description: 'Complete user authentication'
});

// Coordinator breaks down and assigns to agents

Best Practices

Naming Conventions

✓ GOOD:
  "auth-coder"
  "api-tester"
  "security-reviewer"

✗ BAD:
  "agent1"
  "test"
  "temp"

Task Granularity

✓ GOOD:
  "Implement JWT token validation with error handling"

✗ BAD:
  "Build authentication system"

Break complex tasks into smaller, focused tasks.

Context Sharing

Use sessions for shared context:

// Start session
const session = await memory.createSession({
  project: 'user-auth'
});

// Spawn agents in same session
const coder = spawnAgent('coder', { sessionId: session.id });
const tester = spawnAgent('tester', { sessionId: session.id });

// Both agents share session context

Error Handling

Always handle agent failures:

try {
  const result = await agent.execute(task);
} catch (error) {
  console.error('Agent failed:', error);
  // Retry or use alternative agent
}

Performance Considerations

Concurrent Agents

{
  "agents": {
    "maxConcurrent": 10  // Adjust based on resources
  }
}
  • More agents = more parallelism
  • But: Higher memory and API costs

Agent Reuse

// ✓ GOOD: Reuse agent for multiple tasks
const coder = spawnAgent('coder', { name: 'persistent-coder' });
await coder.execute(task1);
await coder.execute(task2);
await coder.execute(task3);

// ✗ BAD: Spawn new agent for each task
for (const task of tasks) {
  const coder = spawnAgent('coder');
  await coder.execute(task);
}

Resource Cleanup

// Stop agents when done
await stopAgent(agent.id);

// End sessions to free resources
await memory.endSession(session.id);

Agent Identity

While agents are ephemeral by default (existing only in memory during runtime), Agent Identity provides persistent, trackable identities that survive across sessions.

Ephemeral vs Persistent Agents

Aspect Ephemeral Agent Agent Identity
Lifetime Single session Permanent
State In-memory only Persisted to SQLite
Tracking Runtime only Full audit trail
Versioning None Capabilities versioned

Identity Lifecycle

stateDiagram-v2
    [*] --> Created: identity_create()
    Created --> Active: identity_activate()
    Created --> Active: autoActivate=true
    Active --> Dormant: identity_deactivate()
    Dormant --> Active: identity_activate()
    Active --> Retired: identity_retire()
    Dormant --> Retired: identity_retire()
    Retired --> [*]
Loading

Creating an Identity

// Via MCP
{
  "tool": "identity_create",
  "arguments": {
    "agentType": "coder",
    "displayName": "Primary Backend Coder",
    "description": "Handles all backend feature development",
    "capabilities": [
      { "name": "write-typescript", "version": "5.0", "enabled": true },
      { "name": "write-tests", "version": "1.0", "enabled": true }
    ],
    "metadata": { "team": "backend", "project": "api" },
    "autoActivate": true
  }
}

Identity Status

Status Description Transitions
created Just created, not yet active → active
active Available for use → dormant, retired
dormant Temporarily deactivated → active, retired
retired Permanently retired (terminal)

Working with Identities

// List active identities
{
  "tool": "identity_list",
  "arguments": { "status": "active", "agentType": "coder" }
}

// Get identity by name
{
  "tool": "identity_get",
  "arguments": { "displayName": "Primary Backend Coder" }
}

// Deactivate during maintenance
{
  "tool": "identity_deactivate",
  "arguments": {
    "agentId": "uuid",
    "reason": "Scheduled maintenance"
  }
}

// View audit trail
{
  "tool": "identity_audit",
  "arguments": { "agentId": "uuid", "limit": 50 }
}

Audit Trail

All identity changes are logged:

{
  "entries": [
    {
      "action": "status_change",
      "previousStatus": "created",
      "newStatus": "active",
      "actorId": "user-123",
      "timestamp": "2026-01-29T10:00:00Z"
    },
    {
      "action": "metadata_update",
      "actorId": "user-456",
      "metadata": { "changedFields": ["capabilities"] },
      "timestamp": "2026-01-29T11:00:00Z"
    }
  ]
}

When to Use Identities

Use Identities When:

  • You need persistent tracking across sessions
  • Audit compliance is required
  • Managing a team of specialized agents
  • Capabilities need versioning

Use Ephemeral Agents When:

  • Quick one-off tasks
  • Temporary exploratory work
  • No audit requirements

See Identity Tools for complete tool reference.

Advanced Topics

Custom Agent Types

Create your own specialized agents:

import { registerAgent } from '@blackms/aistack';

registerAgent({
  type: 'my-custom-agent',
  name: 'Custom Agent',
  description: 'Does custom things',
  systemPrompt: `You are a specialized agent that...`,
  capabilities: ['custom-capability']
});

See Custom Agent Types for details.

Plugin-Provided Agents

Plugins can register new agent types:

// In plugin
export function initialize(config) {
  registerAgent({
    type: 'plugin-agent',
    // ... definition
  });
}

Next Steps

Related:

Home

Getting Started

Core Concepts

Agent Guides

MCP Tools

Recipes

Advanced

Reference

Clone this wiki locally