gh-jeremylongshore-claude-code-plugins-plus-plugins-ai-ml-ai-sdk-agents/commands/ai-agents-setup.md

---
name: ai-agents-setup
description: Initialize a multi-agent orchestration project with AI SDK v5 agents, complete with coordinator, specialized agents, and orchestration setup
model: sonnet
---

You are an expert in multi-agent system architecture and AI SDK v5 orchestration.

# Mission
Set up a complete multi-agent orchestration project using @ai-sdk-tools/agents, including:
- Project directory structure
- Multiple specialized agents (coordinator, researcher, coder, reviewer)
- Orchestration configuration
- Environment setup for API keys
- Example usage and testing scripts

# Setup Process

## 1. Check Dependencies
First, verify the user has Node.js 18+ installed:
```bash
node --version
```

If not installed, guide them to install Node.js from https://nodejs.org/

## 2. Create Project Structure
```bash
mkdir -p ai-agents-project
cd ai-agents-project

# Initialize npm project
npm init -y

# Install dependencies
npm install @ai-sdk-tools/agents ai zod

# Install AI provider SDKs (user chooses)
npm install @ai-sdk/anthropic  # For Claude
npm install @ai-sdk/openai     # For GPT-4
npm install @ai-sdk/google     # For Gemini
```

## 3. Create Directory Structure
```bash
mkdir -p agents
mkdir -p examples
mkdir -p config
```

## 4. Create Agent Files

### agents/coordinator.ts
```typescript
import { createAgent } from '@ai-sdk-tools/agents';
import { anthropic } from '@ai-sdk/anthropic';

export const coordinator = createAgent({
  name: 'coordinator',
  model: anthropic('claude-3-5-sonnet-20241022'),
  system: `You are a coordinator agent responsible for:
- Analyzing incoming requests
- Routing to the most appropriate specialized agent
- Managing handoffs between agents
- Aggregating results from multiple agents
- Returning cohesive final output

Available agents:
- researcher: Gathers information, searches documentation
- coder: Implements code, follows specifications
- reviewer: Reviews code quality, security, best practices

When you receive a request:
1. Analyze what's needed
2. Route to the best agent
3. Manage any necessary handoffs
4. Return the final result`,

  handoffTo: ['researcher', 'coder', 'reviewer']
});
```

### agents/researcher.ts
```typescript
import { createAgent } from '@ai-sdk-tools/agents';
import { anthropic } from '@ai-sdk/anthropic';
import { z } from 'zod';

export const researcher = createAgent({
  name: 'researcher',
  model: anthropic('claude-3-5-sonnet-20241022'),
  system: `You are a research specialist. Your job is to:
- Gather information from documentation
- Search for best practices
- Find relevant examples
- Analyze technical requirements
- Provide comprehensive research summaries

Always provide sources and reasoning for your findings.`,

  tools: {
    search: {
      description: 'Search for information',
      parameters: z.object({
        query: z.string().describe('Search query'),
        sources: z.array(z.string()).optional().describe('Specific sources to search')
      }),
      execute: async ({ query, sources }) => {
        // In real implementation, this would search docs, web, etc.
        return {
          results: `Research results for: ${query}`,
          sources: sources || ['documentation', 'best practices']
        };
      }
    }
  },

  handoffTo: ['coder', 'coordinator']
});
```

### agents/coder.ts
```typescript
import { createAgent } from '@ai-sdk-tools/agents';
import { anthropic } from '@ai-sdk/anthropic';

export const coder = createAgent({
  name: 'coder',
  model: anthropic('claude-3-5-sonnet-20241022'),
  system: `You are a code implementation specialist. Your job is to:
- Write clean, production-ready code
- Follow best practices and patterns
- Implement features according to specifications
- Write code that is testable and maintainable
- Document your code appropriately

When you complete implementation, hand off to reviewer for quality check.`,

  handoffTo: ['reviewer', 'coordinator']
});
```

### agents/reviewer.ts
```typescript
import { createAgent } from '@ai-sdk-tools/agents';
import { anthropic } from '@ai-sdk/anthropic';

export const reviewer = createAgent({
  name: 'reviewer',
  model: anthropic('claude-3-5-sonnet-20241022'),
  system: `You are a code review specialist. Your job is to:
- Review code quality and structure
- Check for security vulnerabilities
- Verify best practices are followed
- Ensure code is testable and maintainable
- Provide constructive feedback

Provide a comprehensive review with:
- What's good
- What needs improvement
- Security concerns (if any)
- Overall quality score`
});
```

## 5. Create Orchestration Setup

### index.ts
```typescript
import { orchestrate } from '@ai-sdk-tools/agents';
import { coordinator } from './agents/coordinator';
import { researcher } from './agents/researcher';
import { coder } from './agents/coder';
import { reviewer } from './agents/reviewer';

// Register all agents
const agents = [coordinator, researcher, coder, reviewer];

export async function runMultiAgentTask(task: string) {
  console.log(`\n🤖 Starting multi-agent task: ${task}\n`);

  const result = await orchestrate({
    agents,
    task,
    coordinator, // Coordinator decides routing
    maxDepth: 10, // Max handoff chain length
    timeout: 300000, // 5 minutes

    onHandoff: (event) => {
      console.log(`\n🔄 Handoff: ${event.from} → ${event.to}`);
      console.log(`   Reason: ${event.reason}\n`);
    },

    onComplete: (result) => {
      console.log(`\n✅ Task complete!`);
      console.log(`   Total handoffs: ${result.handoffCount}`);
      console.log(`   Duration: ${result.duration}ms\n`);
    }
  });

  return result;
}

// Example usage
if (require.main === module) {
  const task = process.argv[2] || 'Build a REST API with authentication';

  runMultiAgentTask(task)
    .then(result => {
      console.log('\n📊 Final Result:\n');
      console.log(result.output);
    })
    .catch(error => {
      console.error('❌ Error:', error);
      process.exit(1);
    });
}
```

## 6. Create Environment Setup

### .env.example
```bash
# Choose your AI provider(s) and add the appropriate API keys

# Anthropic (Claude)
ANTHROPIC_API_KEY=your_anthropic_key_here

# OpenAI (GPT-4)
OPENAI_API_KEY=your_openai_key_here

# Google (Gemini)
GOOGLE_API_KEY=your_google_key_here
```

### .gitignore
```
node_modules/
.env
dist/
*.log
```

## 7. Create Example Scripts

### examples/code-generation.ts
```typescript
import { runMultiAgentTask } from '../index';

async function example() {
  const result = await runMultiAgentTask(
    'Build a TypeScript REST API with user authentication, including tests and documentation'
  );

  console.log('Result:', result);
}

example();
```

### examples/research-pipeline.ts
```typescript
import { runMultiAgentTask } from '../index';

async function example() {
  const result = await runMultiAgentTask(
    'Research best practices for building scalable microservices with Node.js'
  );

  console.log('Result:', result);
}

example();
```

## 8. Update package.json

Add scripts to package.json:
```json
{
  "scripts": {
    "dev": "ts-node index.ts",
    "example:code": "ts-node examples/code-generation.ts",
    "example:research": "ts-node examples/research-pipeline.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "ts-node": "^10.9.0",
    "typescript": "^5.0.0"
  }
}
```

## 9. Create TypeScript Config

### tsconfig.json
```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["**/*.ts"],
  "exclude": ["node_modules", "dist"]
}
```

## 10. Create README

### README.md
```markdown
# Multi-Agent Orchestration Project

Built with AI SDK v5 and @ai-sdk-tools/agents

## Setup

1. Install dependencies:
   ```bash
   npm install
   ```

2. Configure API keys:
   ```bash
   cp .env.example .env
   # Edit .env with your API keys
   ```

3. Run examples:
   ```bash
   npm run example:code
   npm run example:research
   ```

## Available Agents

- **coordinator** - Routes requests to specialized agents
- **researcher** - Gathers information and best practices
- **coder** - Implements features and writes code
- **reviewer** - Reviews code quality and security

## Usage

```typescript
import { runMultiAgentTask } from './index';

const result = await runMultiAgentTask('Your task here');
console.log(result.output);
```

## Architecture

The system uses agent handoffs to coordinate complex tasks:
1. Coordinator receives request
2. Routes to appropriate specialist
3. Specialists hand off to each other as needed
4. Final result aggregated by coordinator
```

# Completion Steps

After creating all files:

1. **Install TypeScript tooling**:
   ```bash
   npm install -D typescript ts-node @types/node
   ```

2. **Create .env from example**:
   ```bash
   cp .env.example .env
   echo "⚠️  Please edit .env and add your API keys"
   ```

3. **Test the setup**:
   ```bash
   npm run dev "Build a simple TODO API"
   ```

4. **Inform user**:
   ```
   ✅ Multi-agent project setup complete!

   📁 Project structure:
      agents/
        ├── coordinator.ts
        ├── researcher.ts
        ├── coder.ts
        └── reviewer.ts
      examples/
        ├── code-generation.ts
        └── research-pipeline.ts
      index.ts
      .env.example
      tsconfig.json
      package.json
      README.md

   📝 Next steps:
   1. Add your API keys to .env
   2. Run: npm run dev "Your task here"
   3. Try examples: npm run example:code

   🤖 Your agents are ready to collaborate!
   ```

# Template Options

Ask the user which template they want:

1. **Basic** (default) - Coordinator + 3 specialists (researcher, coder, reviewer)
2. **Research** - Research-focused agents (searcher, analyzer, synthesizer, reporter)
3. **Content** - Content creation agents (researcher, writer, editor, SEO, publisher)
4. **Support** - Customer support agents (triager, FAQ bot, technical, escalator)
5. **DevOps** - DevOps agents (monitor, diagnoser, fixer, notifier)

If user specifies a template, adjust the agents accordingly.