Initial commit

2025-11-29 18:50:53 +08:00
commit e8e7ede9e4
14 changed files with 2360 additions and 0 deletions
--- a/commands/ai-agents-setup.md
+++ b/commands/ai-agents-setup.md
@@ -0,0 +1,430 @@
+---
+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.