Agent System Architecture¶

Technical architecture of Nova AI's multi-agent orchestration system.

Overview¶

Nova AI implements a hierarchical agent system with specialized agents coordinated by an orchestrator:

graph TB
    O[Orchestrator Agent] --> A[Architect]
    O --> I[Implementer]
    O --> R[Code-Reviewer]
    O --> T[Tester]
    O --> D[Debugger]

    A --> P[Architecture Decisions]
    I --> C[Code Implementation]
    R --> S[Security Review]
    T --> V[Test Validation]
    D --> E[Error Analysis]

    style O fill:#3f51b5,color:#fff

Agent Hierarchy¶

Tier 1: Orchestrator¶

Role: Multi-agent coordination and workflow management

Responsibilities:

Task decomposition and planning
Agent selection and delegation
Session management and state tracking
Quality gate enforcement
Knowledge base search
User interaction and approval

Key Features:

Model: Sonnet 4.5 (agentic workflows)
Tools: All (Read, Write, Edit, Grep, Bash, MCP)
Session: Maintains state across transitions
Cost: Optimized with prompt caching

Decision Logic:

def select_agent(task: str) -> str:
    """Select appropriate agent based on task type."""
    if "architecture" in task or "design" in task:
        return "architect"
    elif "review" in task or "security" in task:
        return "code-reviewer"
    elif "test" in task or "coverage" in task:
        return "tester"
    elif "debug" in task or "error" in task:
        return "debugger"
    else:
        return "implementer"

Tier 2: Specialists¶

Architect¶

Purpose: System design and architecture decisions

Capabilities:

Design microservices architecture
Evaluate technology trade-offs
Create architecture diagrams
Database schema design
Scalability planning

Output:

Architecture diagrams (Mermaid)
Component specifications
Trade-off analysis
Implementation recommendations

Implementer¶

Purpose: Feature implementation and code writing

Capabilities:

Write production-ready code
Create comprehensive tests (>80% coverage)
Add type hints and docstrings
Follow project patterns
Document implementations

Quality Gates:

✅ Type hints on all functions
✅ Google-style docstrings
✅ >80% test coverage
✅ Error handling and validation
✅ Logging at appropriate levels

Code-Reviewer¶

Purpose: Security, correctness, and maintainability review

Review Checklist:

🔒 Security: SQL injection, XSS, secrets
✅ Correctness: Logic errors, edge cases
📚 Maintainability: Code clarity, docs
⚡ Performance: N+1 queries, inefficiencies
🧪 Testing: Coverage, test quality

Blocking Issues:

Security vulnerabilities
Data loss risks
Missing critical error handling
Hardcoded secrets or credentials

Tester¶

Purpose: Test execution and validation

Test Types:

Unit tests (individual functions)
Integration tests (component interactions)
Performance tests (speed, efficiency)
Security tests (vulnerability checks)

Validation:

All tests passing
Coverage >80%
Type hints complete (mypy clean)
Linting clean (ruff clean)

Debugger¶

Purpose: Error analysis and debugging

Process:

Analyze Error - Parse stack trace
Reproduce - Create minimal case
Root Cause - Identify issue
Fix - Implement solution
Test - Verify and add regression tests

Agent Communication¶

State Passing¶

Agents communicate through compressed session state:

@dataclass
class SessionState:
    session_id: str
    agent_name: str
    plan_summary: str
    key_decisions: list[str]
    latest_artifacts: list[str]
    metrics: SessionMetrics

Session Continuation¶

Without session continuation:

orchestrator → implementer: 680ms overhead
implementer → code-reviewer: 280ms overhead
code-reviewer → tester: 280ms overhead
Total: 1,240ms overhead

With session continuation:

orchestrator → implementer: 45ms overhead (93% reduction)
implementer → code-reviewer: 15ms overhead (95% reduction)
code-reviewer → tester: 12ms overhead (96% reduction)
Total: 72ms overhead (94% reduction)

Workflow Patterns¶

Pattern 1: Feature Implementation¶

sequenceDiagram
    participant U as User
    participant O as Orchestrator
    participant I as Implementer
    participant R as Code-Reviewer
    participant T as Tester

    U->>O: /novaai implement feature X
    O->>O: Search KB
    O->>O: Create plan
    O->>U: Present plan
    U->>O: Approve
    O->>I: Implement feature
    I-->>O: Code + tests
    O->>R: Review security
    R-->>O: Review passed
    O->>T: Run tests
    T-->>O: Tests passed
    O->>U: Summary

Pattern 2: Code Review¶

sequenceDiagram
    participant U as User
    participant O as Orchestrator
    participant R as Code-Reviewer
    participant I as Implementer

    U->>O: /novaai review PR #123
    O->>R: Review code
    R-->>O: Issues found
    alt Critical Issues
        O->>I: Fix issues
        I-->>O: Fixes applied
        O->>R: Re-review
        R-->>O: Approved
    end
    O->>U: Review summary

Pattern 3: Bug Fix¶

sequenceDiagram
    participant U as User
    participant O as Orchestrator
    participant D as Debugger
    participant I as Implementer
    participant T as Tester

    U->>O: /novaai fix bug in auth
    O->>D: Analyze error
    D-->>O: Root cause found
    O->>I: Implement fix
    I-->>O: Fix + tests
    O->>T: Run regression tests
    T-->>O: Tests passed
    O->>U: Summary

Agent Configuration¶

YAML Structure¶

# .claude/agents/implementer.yaml
name: implementer
description: Feature implementation specialist
model: claude-sonnet-4-5-20250929
tools:
  - Read
  - Write
  - Edit
  - Grep
  - Bash

Tool Permissions¶

Agent	Tools	Rationale
orchestrator	All	Full coordination
architect	Read, Grep	Read-only analysis
implementer	Read, Write, Edit, Grep, Bash	Implementation + testing
code-reviewer	Read, Grep	Read-only review
tester	Read, Bash	Testing + validation
debugger	Read, Grep, Bash	Analysis + debugging

Model Selection¶

All agents use Sonnet 4.5 following Anthropic's recommendation:

"For agentic workflows, Sonnet 4.5 provides the best balance of intelligence, speed, and cost. Use Sonnet 4.5 for all agents unless specific requirements dictate otherwise."

Why Sonnet 4.5?

✅ Optimized for agentic workflows
✅ Fast response times (< 1s)
✅ Good cost/performance ratio
✅ Reliable tool usage
✅ Context window: 200K tokens

Performance Optimizations¶

1. Prompt Caching (90% Savings)¶

# Automatic prompt caching
executor = ClaudeSDKExecutor(
    agent_name="orchestrator",
    use_sdk_mcp=True  # Enables caching
)

# Result: 90% cost reduction on repeated context

2. Session Continuation (88-95% Overhead Reduction)¶

# First task
result1 = await executor.run_task("task 1")

# Reuse session (88-95% faster)
executor2 = ClaudeSDKExecutor(
    agent_name="implementer",
    session_id=result1.session_id
)
result2 = await executor2.run_task("task 2")

3. SDK MCP (10-100x Speedup)¶

stdio MCP:

KB search: 850ms (subprocess + serialization)
GitHub API: 450ms
Memory store: 120ms

SDK MCP:

KB search: 8ms (direct Python import)
GitHub API: 45ms
Memory store: 2ms

4. Parallel Execution¶

from src.orchestrator.parallel_executor import ParallelAgentExecutor

executor = ParallelAgentExecutor(max_parallel=3)
results = await executor.run_parallel(tasks)

Quality Gates¶

Pre-Commit Gates¶

Required before all commits:

Code Review - Security, correctness, maintainability
Test Execution - All tests passing
Coverage Check - >80% coverage
Type Checking - mypy clean
Linting - ruff clean

Implementation Gates¶

Required for implementer:

✅ Type hints on all functions
✅ Google-style docstrings
✅ >80% test coverage
✅ Error handling and validation
✅ Logging at appropriate levels
✅ No hardcoded secrets
✅ Security best practices

Review Gates¶

Blocking issues for code-reviewer:

🔴 Security vulnerabilities (SQL injection, XSS, etc.)
🔴 Data loss risks (missing transactions, etc.)
🔴 Missing critical error handling
🔴 Hardcoded secrets or credentials

Monitoring and Observability¶

Cost Tracking¶

from src.orchestrator.cost_tracker import track_agent_call

async with track_agent_call(agent_name="implementer", task="Feature X"):
    result = await executor.run_task("implement feature X")

# Automatically tracked:
# - Token usage (input, output, cached)
# - Cost calculation
# - Agent attribution
# - Time-series data

LangFuse Integration¶

export LANGFUSE_PUBLIC_KEY="your-key"
export LANGFUSE_SECRET_KEY="your-secret"
export LANGFUSE_HOST="https://cloud.langfuse.com"

Dashboard Features:

Real-time cost tracking
Token usage graphs
Agent performance comparison
Trace inspection
Cost alerts

Next Steps¶

Agent Guardrails MCP Architecture Agent Usage Guide