Architecture Design

The enterprise AI team you will build in this capstone consists of a CEO orchestrator plus seven department agents. This chapter designs the overall system architecture and how the agents communicate with each other.

Overall Architecture

                    [Users / Executives]
                          ↓
              [CEO Orchestrator Agent]
              task analysis → routing → integration
                          ↓
    ┌─────────────────────────────────────────────────┐
    │                                                 │
  [Marketing] [HR] [Dev] [Finance] [Sales] [Legal] [CS]│
    │                                                 │
    └─────────────────────────────────────────────────┘
                          ↓
              [Result integration & report]

Defining Agent Roles

Agent	Core role	Main tools
CEO Orchestrator	Task analysis, department routing, result integration	All tools
Marketing	Content creation, campaign analysis, SEO	Read, Write
HR	Recruiting, onboarding, performance management	Read, Write
Dev	Code review, tech debt, PR analysis	Read, Grep, Bash
Finance	Budget analysis, spend reporting, forecasting	Read, Bash
Sales	CRM updates, proposals, pipeline	Read, Write
Legal	Contract review, compliance	Read
CS	Ticket handling, FAQ, escalation	Read, Write

Project Structure

enterprise-ai-team/
├── src/
│   ├── orchestrator/
│   │   ├── ceo.ts          — CEO orchestrator
│   │   └── router.ts       — department routing logic
│   ├── agents/
│   │   ├── marketing.ts
│   │   ├── hr.ts
│   │   ├── dev.ts
│   │   ├── finance.ts
│   │   ├── sales.ts
│   │   ├── legal.ts
│   │   └── cs.ts
│   ├── shared/
│   │   ├── types.ts        — shared type definitions
│   │   ├── utils.ts        — utilities such as extractText
│   │   └── config.ts       — agent configuration
│   └── index.ts            — entry point
├── prompts/
│   ├── ceo-system.md
│   └── ...                 — system prompt for each agent
├── package.json
└── .env

Shared Type Definitions

// src/shared/types.ts

export type Department =
  | "marketing" | "hr" | "dev"
  | "finance" | "sales" | "legal" | "cs";

export interface AgentRequest {
  task: string;
  context?: string;
  priority?: "urgent" | "normal" | "low";
  requestedBy?: string;
}

export interface AgentResponse {
  department: Department;
  result: string;
  confidence: "high" | "medium" | "low";
  actionItems?: string[];
  escalationNeeded?: boolean;
}

export interface OrchestratorResult {
  summary: string;
  departmentResults: AgentResponse[];
  actionItems: string[];
  executiveReport: string;
}

Shared Utilities

// src/shared/utils.ts
import { SDKMessage } from "@anthropic-ai/claude-agent-sdk";

export function extractText(messages: SDKMessage[]): string {
  return messages
    .filter(m => m.type === "assistant")
    .flatMap(m => m.content)
    .filter(c => c.type === "text")
    .map(c => c.text)
    .join("\n");
}

export function parseJSON<T>(text: string, fallback: T): T {
  try {
    const match = text.match(/\{[\s\S]*\}|\[[\s\S]*\]/);
    return match ? JSON.parse(match[0]) : fallback;
  } catch {
    return fallback;
  }
}

export function log(agent: string, message: string) {
  const ts = new Date().toISOString().slice(11, 19);
  console.log(`[${ts}] [${agent.toUpperCase()}] ${message}`);
}

Default Agent Configuration

// src/shared/config.ts
import { Department } from "./types";

export interface AgentConfig {
  systemPrompt: string;
  maxTurns: number;
  tools: string[];
}

export const AGENT_CONFIGS: Record<Department, AgentConfig> = {
  marketing: {
    systemPrompt: `You are a marketing strategist and content creator.
      You build data-driven marketing strategies and produce high-quality content.`,
    maxTurns: 12,
    tools: ["Read", "Write", "Glob"]
  },
  hr: {
    systemPrompt: `You are an HR specialist.
      You have expertise in recruiting, onboarding, performance management, and strengthening organizational culture.`,
    maxTurns: 10,
    tools: ["Read", "Write"]
  },
  dev: {
    systemPrompt: `You are a senior software engineer.
      You specialize in reviewing code quality, architecture, security, and performance.`,
    maxTurns: 15,
    tools: ["Read", "Glob", "Grep", "Bash"]
  },
  finance: {
    systemPrompt: `You are a financial analyst.
      You handle budget planning, cost analysis, and financial forecasting.`,
    maxTurns: 8,
    tools: ["Read", "Bash"]
  },
  sales: {
    systemPrompt: `You are a sales strategist.
      You specialize in CRM management, writing proposals, and pipeline optimization.`,
    maxTurns: 10,
    tools: ["Read", "Write"]
  },
  legal: {
    systemPrompt: `You are a corporate legal specialist.
      You perform contract review, risk analysis, and compliance checks.
      Legal advice is for reference only, and actual legal decisions require confirmation from an attorney.`,
    maxTurns: 10,
    tools: ["Read"]
  },
  cs: {
    systemPrompt: `You are a customer success specialist.
      You resolve customer issues quickly and courteously and raise customer satisfaction.`,
    maxTurns: 8,
    tools: ["Read", "Write"]
  }
};

Data Flow

1. User request comes in
   ↓
2. CEO orchestrator analyzes the request
   → Which departments are needed?
   → Sequential or parallel processing?
   ↓
3. Run the relevant department agents
   → Single department: run directly
   → Multiple departments: run in parallel with Promise.all()
   ↓
4. CEO integrates the results
   → Summarize each department's result
   → Extract action items
   → Write the executive report
   ↓
5. Return the final result

Architecture design principles

• Single entry point: users only ever deal with the CEO agent
• Loose coupling: each department agent can be replaced or upgraded independently
• Failure isolation: one department's failure does not affect the whole system
• Extensibility: new department agents can be added easily