How to Set Up 5 AI Agents to Build a Complete API (From Spec to Test)

Stop using one generic AI assistant for everything. Set up 5 specialized agents to build a complete API: Backend Architect designs the system, Database Optimizer reviews schema, Frontend Developer builds the client, Code Reviewer checks security, and Reality Checker validates before ship.

You need to build an API fast. The temptation: ask one AI to do everything. It will design the database, write the endpoints, build the frontend, review the code, and test the result.

Here’s what happens: the database lacks indexes, the endpoints have security gaps, the frontend ignores error states, and testing consists of “looks good to me.”

Specialized agents fix this. Each agent knows their domain. Each agent has checklists. Each agent produces specific deliverables. The Backend Architect thinks about scale. The Database Optimizer spots missing indexes. The Code Reviewer finds vulnerabilities. The Reality Checker requires proof.

In this tutorial, you’ll set up 5 agents from The Agency collection and run a complete API build workflow. You’ll integrate with Apidog for API testing and documentation, ensuring your endpoints are validated against OpenAPI specs before deployment.

The 5 Agents You’ll Use

Install the agents:

# Clone The Agency repo
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

# Copy agents to Claude Code
cp engineering/engineering-backend-architect.md ~/.claude/agents/
cp engineering/engineering-database-optimizer.md ~/.claude/agents/
cp engineering/engineering-frontend-developer.md ~/.claude/agents/
cp engineering/engineering-code-reviewer.md ~/.claude/agents/
cp testing/testing-reality-checker.md ~/.claude/agents/

Step 1: Backend Architect Designs the System

Start a new Claude Code session:

Activate Backend Architect mode.

Design a REST API for an e-commerce platform with:
- User authentication (JWT with refresh tokens)
- Product catalog with categories and filtering
- Shopping cart management
- Order processing with status tracking
- Payment webhook integration

Output:
1. OpenAPI 3.0 specification
2. PostgreSQL database schema with relationships
3. Project folder structure (Express.js + TypeScript)
4. Authentication flow diagram

Expected deliverables:

The Backend Architect will output:

OpenAPI Spec (partial):

openapi: 3.0.0
info:
  title: E-commerce API
  version: 1.0.0
paths:
  /auth/login:
    post:
      summary: User login
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string, format: email }
                password: { type: string, minLength: 8 }
      responses:
        '200':
          description: JWT tokens
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken: { type: string }
                  refreshToken: { type: string }

Database Schema:

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE products (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    description TEXT,
    price DECIMAL(10, 2) NOT NULL CHECK (price >= 0),
    category_id UUID REFERENCES categories(id),
    inventory_count INTEGER DEFAULT 0,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    total_amount DECIMAL(10, 2) NOT NULL,
    status VARCHAR(50) DEFAULT 'pending',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Folder Structure:

src/
├── controllers/
│   ├── auth.controller.ts
│   ├── products.controller.ts
│   └── orders.controller.ts
├── middleware/
│   ├── auth.middleware.ts
│   └── validation.middleware.ts
├── routes/
│   ├── auth.routes.ts
│   ├── products.routes.ts
│   └── orders.routes.ts
├── services/
│   ├── auth.service.ts
│   ├── products.service.ts
│   └── orders.service.ts
├── models/
│   ├── User.ts
│   ├── Product.ts
│   └── Order.ts
└── index.ts

Save the output. You’ll pass it to the next agent.

Step 2: Database Optimizer Reviews Schema

Open a new session:

Activate Database Optimizer mode.

Review this PostgreSQL schema for an e-commerce API:

[Paste the schema from Step 1]

Check for:
1. Missing indexes on foreign keys and frequently queried columns
2. Query performance on product search (name, category, price range)
3. Proper constraints for data integrity
4. Missing tables for common e-commerce features (reviews, wishlists)
5. Soft delete patterns for audit trails

Output specific ALTER TABLE statements and new table definitions.

Expected deliverables:

Index Recommendations:

-- Add indexes on foreign keys
CREATE INDEX idx_products_category_id ON products(category_id);
CREATE INDEX idx_orders_user_id ON orders(user_id);

-- Add index for product search
CREATE INDEX idx_products_name_search ON products USING gin(to_tsvector('english', name));
CREATE INDEX idx_products_price ON products(price) WHERE inventory_count > 0;

-- Add composite index for category filtering
CREATE INDEX idx_products_category_price ON products(category_id, price);

Missing Tables:

CREATE TABLE reviews (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    product_id UUID REFERENCES products(id),
    user_id UUID REFERENCES users(id),
    rating INTEGER CHECK (rating >= 1 AND rating <= 5),
    comment TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(product_id, user_id)
);

CREATE TABLE cart_items (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    product_id UUID REFERENCES products(id),
    quantity INTEGER DEFAULT 1 CHECK (quantity > 0),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(user_id, product_id)
);

Constraints to Add:

-- Email format validation
ALTER TABLE users ADD CONSTRAINT chk_email_format
    CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$');

-- Soft delete column
ALTER TABLE products ADD COLUMN deleted_at TIMESTAMP WITH TIME ZONE NULL;
CREATE INDEX idx_products_deleted_at ON products(deleted_at) WHERE deleted_at IS NULL;

Apply these recommendations to your schema.

Step 3: Frontend Developer Builds the Client

Open a new session:

Activate Frontend Developer mode.

Build a React dashboard for this e-commerce API:

[Paste OpenAPI spec from Step 1]

Requirements:
- TypeScript with strict mode
- React Query for server state management
- Product list with filters (category, price range, search)
- Shopping cart with real-time updates
- Order history with status tracking
- Proper error handling and loading states
- Responsive design (mobile, tablet, desktop)

Output:
1. Project setup (Vite + React + TypeScript)
2. API client with React Query hooks
3. Core components (ProductList, ProductCard, Cart, OrderHistory)
4. Error boundary and loading skeletons

Expected deliverables:

API Client:

// src/lib/api-client.ts
import { QueryClient, useQuery, useMutation } from '@tanstack/react-query';

const API_BASE = 'http://localhost:3000/api';

async function fetcher<T>(endpoint: string, options?: RequestInit): Promise<T> {
  const response = await fetch(`${API_BASE}${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...options?.headers,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Request failed');
  }

  return response.json();
}

export function useProducts(filters?: ProductFilters) {
  const params = new URLSearchParams(filters as Record<string, string>);
  return useQuery({
    queryKey: ['products', filters],
    queryFn: () => fetcher<Product[]>(`/products?${params}`),
  });
}

export function useAddToCart() {
  return useMutation({
    mutationFn: (item: CartItem) =>
      fetcher<CartItem>('/cart', {
        method: 'POST',
        body: JSON.stringify(item),
      }),
  });
}

Product List Component:

// src/components/ProductList.tsx
import { useProducts } from '@/lib/api-client';
import { ProductCard } from './ProductCard';
import { FilterSidebar } from './FilterSidebar';
import { Skeleton } from './ui/skeleton';

export function ProductList() {
  const [filters, setFilters] = useState<ProductFilters>({});
  const { data: products, isLoading, error } = useProducts(filters);

  if (error) {
    return <Alert variant="destructive">{error.message}</Alert>;
  }

  return (
    <div className="flex gap-4">
      <FilterSidebar filters={filters} onFilterChange={setFilters} />
      <div className="flex-1 grid grid-cols-1 md:grid-cols-3 gap-4">
        {isLoading ? (
          Array.from({ length: 6 }).map((_, i) => (
            <Skeleton key={i} className="h-64" />
          ))
        ) : products?.length === 0 ? (
          <EmptyState message="No products found" />
        ) : (
          products?.map(product => (
            <ProductCard key={product.id} product={product} />
          ))
        )}
      </div>
    </div>
  );
}

Error Boundary:

// src/components/ErrorBoundary.tsx
export class ErrorBoundary extends React.Component<
  { children: React.ReactNode },
  { hasError: boolean; error: Error | null }
> {
  constructor(props: { children: React.ReactNode }) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error: Error) {
    return { hasError: true, error };
  }

  render() {
    if (this.state.hasError) {
      return (
        <div className="p-4 bg-red-50 border border-red-200 rounded">
          <h2 className="text-lg font-semibold text-red-800">Something went wrong</h2>
          <p className="text-red-600">{this.state.error?.message}</p>
          <Button onClick={() => window.location.reload()} className="mt-2">
            Reload
          </Button>
        </div>
      );
    }

    return this.props.children;
  }
}

Step 4: Code Reviewer Checks Everything

Open a new session:

Activate Code Reviewer mode.

Review this codebase for:

1. Security vulnerabilities:
   - SQL injection risks
   - XSS vulnerabilities
   - CSRF protection
   - Authentication bypass possibilities

2. TypeScript strict mode compliance:
   - No implicit any
   - Proper type definitions
   - Null/undefined handling

3. Error handling gaps:
   - Uncaught promise rejections
   - Missing try/catch blocks
   - Silent failures

[Paste the code from Steps 1-3]

Output a report with severity ratings (Critical, High, Medium, Low) and specific fixes.

Expected deliverables:

Security Report:

## Critical Issues

### 1. SQL Injection in Product Search
**Location:** `src/controllers/products.controller.ts:24`
**Issue:** User input concatenated directly into SQL query
```typescript
// VULNERABLE
const query = `SELECT * FROM products WHERE name LIKE '%${search}%'`;

Fix: Use parameterized queries

const query = 'SELECT * FROM products WHERE name LIKE $1';
await db.query(query, [`%${search}%`]);

High Issues

2. Missing CSRF Protection

Location: src/index.tsIssue: No CSRF middleware for state-changing operations Fix: Add csurf middleware

import csrf from 'csurf';
app.use(csrf({ cookie: true }));

Medium Issues

3. Implicit Any in API Response

Location: src/lib/api-client.ts:8Issue: Generic any type for fetcher function Fix: Add proper type constraints

async function fetcher<T extends Record<string, unknown>>(
  endpoint: string,
  options?: RequestInit
): Promise<T> { ... }

**Type Safety Report:**
```markdown
## TypeScript Violations

1. `products.controller.ts:45` - Missing return type annotation
2. `auth.middleware.ts:12` - Implicit any in catch block
3. `orders.service.ts:78` - Object possibly undefined

Run `tsc --noEmit` to see full list. Fix before deployment.

Apply fixes before proceeding.

Step 5: Reality Checker Validates Before Ship

Open a new session:

Activate Reality Checker mode.

This e-commerce API is ready for production validation.

Run your mandatory reality check process:

1. Verify files exist
2. Cross-reference claimed features with actual code
3. Require screenshot evidence from Playwright tests
4. Review test-results.json for performance metrics

Project URL: http://localhost:3000
Test results: ./public/qa-screenshots/test-results.json

Output: PASS or NEEDS WORK with specific blocking issues.

Expected deliverables:

Reality Check Commands:

# 1. Verify files exist
ls -la src/controllers/ src/services/ src/routes/
ls -la src/components/ src/lib/

# 2. Cross-reference claimed features
grep -r "jwt\|jsonwebtoken" . --include="*.ts" || echo "NO JWT FOUND"
grep -r "bcrypt\|argon2" . --include="*.ts" || echo "NO PASSWORD HASHING FOUND"
grep -r "rateLimit\|express-rate-limit" . --include="*.ts" || echo "NO RATE LIMITING FOUND"

# 3. Run Playwright screenshot capture
npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"

# 4. Review test results
cat public/qa-screenshots/test-results.json

Validation Report:

## Reality Check Results

### File Verification: PASS
- All controller files present
- All component files present

### Feature Verification: NEEDS WORK
- JWT authentication: FOUND
- Password hashing: FOUND
- Rate limiting: NOT FOUND (blocking)

### Screenshot Evidence: NEEDS WORK
- Desktop layout: PASS
- Tablet layout: PASS
- Mobile layout: FAIL (product grid broken at 375px)

### Performance Metrics: NEEDS WORK
- Average load time: 2.3s (target: <1s)
- Console errors: 3 (target: 0)
- Failed network requests: 1 (target: 0)

## Final Status: NEEDS WORK

### Blocking Issues:
1. Rate limiting not implemented
2. Mobile layout broken on product list
3. 3 console errors to fix
4. Load time exceeds 1s target

### Non-Blocking:
- Add loading skeletons to order history
- Improve error messages

Fix the blocking issues and run Reality Checker again.

Workflow Summary

┌─────────────────────────────────────────────────────────────────┐
│  Backend Architect                                              │
│  → OpenAPI spec, database schema, folder structure              │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Database Optimizer                                             │
│  → Index recommendations, missing tables, constraints           │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Frontend Developer                                             │
│  → React components, API client, error handling                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Code Reviewer                                                  │
│  → Security audit, type safety, error handling gaps             │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Reality Checker                                                │
│  → Evidence-based validation, screenshot proof, PASS/FAIL       │
└─────────────────────────────────────────────────────────────────┘

Parallel Agent Execution (Advanced)

Run agents in parallel to reduce total time:

# Terminal 1: Backend Architect
claude "Activate Backend Architect. Design e-commerce API..."

# Terminal 2: Database Optimizer (wait for schema output)
claude "Activate Database Optimizer. Review this schema..."

# Terminal 3: Frontend Developer (wait for API spec)
claude "Activate Frontend Developer. Build React dashboard..."

# Terminal 4: Code Reviewer (wait for code)
claude "Activate Code Reviewer. Review this codebase..."

# All terminals: Reality Checker (final validation)
claude "Activate Reality Checker. Run mandatory checks..."

With parallel execution, you can complete the workflow in 2-4 hours instead of 6-8 hours.

What You Built

Next Steps

Deploy the API:

• Set up production PostgreSQL with connection pooling
• Configure environment variables for secrets
• Add health check endpoints
• Set up monitoring (Prometheus, Grafana)

Extend the workflow:

• Add Performance Benchmarker agent for load testing
• Add Technical Writer agent for documentation
• Add DevOps Automator agent for CI/CD pipeline

Reuse the pattern:

• Save prompts as templates
• Create a workflow script that chains agent sessions
• Share with your team

Five specialized agents. One complete API. No generic advice.

That’s the power of specialization. Each agent knows their domain. Each agent has checklists. Each agent produces specific deliverables.

Your turn: pick a project, activate the agents, and ship faster.

Key Takeaways

• Specialized agents outperform generic assistants — Each agent has domain expertise, checklists, and specific deliverables
• Sequential workflow ensures quality — Backend Architect designs, Database Optimizer reviews, Frontend Developer builds, Code Reviewer audits, Reality Checker validates
• Evidence-based approval prevents bugs — Reality Checker requires screenshot proof, grep results, and performance metrics before PASS certification
• Parallel execution reduces total time — Run 4 terminals simultaneously to complete in 2-4 hours instead of 6-8 hours
• Save prompts as templates — Reuse the same agent activations for consistent results across projects

FAQ

What are AI agents for developers?AI agents are specialized AI assistants with domain expertise. Unlike generic chatbots, agents like Backend Architect or Code Reviewer have specific checklists and produce consistent deliverables.

How do I install agents from The Agency?Clone the repo at github.com/msitarzewski/agency-agents, then copy .md files to ~/.claude/agents/ for Claude Code or use the install script for other tools.

What is the Reality Checker agent?Reality Checker is an evidence-based QA agent that refuses to approve work without proof. It requires screenshots, grep results, and performance metrics before giving PASS certification.

Can I run multiple agents in parallel?Yes. Open multiple terminals and activate different agents in each. Pass deliverables by copying output or using MCP memory for automatic handoffs.

How do I pass context between agents?Copy output from one agent and paste it as input for the next. For automatic handoffs, use MCP memory to store deliverables that the next agent can recall.

What if an agent says NEEDS WORK?Fix the blocking issues the agent identified, then re-run the agent. The Reality Checker specifically lists what needs to be fixed before PASS certification.

Do I need all 5 agents for every project?No. Start with Backend Architect and Code Reviewer for API projects. Add Database Optimizer for complex schemas, Frontend Developer for UI work, and Reality Checker before shipping.