@agentforge/cli 0.5.0 → 0.5.2

package/templates/reusable-agent/README.md

@@ -0,0 +1,148 @@
+# {{AGENT_NAME_PASCAL}} Agent
+
+{{AGENT_DESCRIPTION}}
+
+A configurable, reusable AI agent built with AgentForge.
+
+## Features
+
+- ✅ **Factory Function Pattern** - Easy to instantiate with different configurations
+- ✅ **External Prompt Templates** - Prompts stored in `.md` files for easy editing
+- ✅ **Tool Injection** - Add custom tools via ToolRegistry or direct injection
+- ✅ **Feature Flags** - Enable/disable capabilities as needed
+- ✅ **Configuration Validation** - Type-safe configuration with Zod schemas
+- ✅ **Comprehensive Tests** - Full test coverage demonstrating all features
+
+## Installation
+
+```bash
+npm install @agentforge/core @agentforge/patterns @agentforge/tools @langchain/openai zod
+```
+
+## Quick Start
+
+```typescript
+import { create{{AGENT_NAME_PASCAL}}Agent } from './{{AGENT_NAME_KEBAB}}';
+
+// Create with default configuration
+const agent = create{{AGENT_NAME_PASCAL}}Agent();
+
+// Invoke the agent
+const result = await agent.invoke({
+  input: 'Your query here',
+});
+
+console.log(result);
+```
+
+## Configuration
+
+### Basic Configuration
+
+```typescript
+const agent = create{{AGENT_NAME_PASCAL}}Agent({
+  organizationName: 'Acme Corp',
+  temperature: 0.7,
+  maxIterations: 10,
+});
+```
+
+### With Custom Tools
+
+```typescript
+import { toolBuilder, ToolCategory } from '@agentforge/core';
+
+const customTool = toolBuilder()
+  .name('my-custom-tool')
+  .description('Does something specific')
+  .category(ToolCategory.UTILITY)
+  .schema(z.object({
+    input: z.string().describe('Input parameter'),
+  }))
+  .implement(async ({ input }) => {
+    return { result: `Processed: ${input}` };
+  })
+  .build();
+
+const agent = create{{AGENT_NAME_PASCAL}}Agent({
+  customTools: [customTool],
+});
+```
+
+### With Tool Registry
+
+```typescript
+import { ToolRegistry, ToolCategory } from '@agentforge/core';
+
+const registry = new ToolRegistry();
+// ... register tools
+
+const agent = create{{AGENT_NAME_PASCAL}}Agent({
+  toolRegistry: registry,
+  enabledCategories: [ToolCategory.UTILITY],
+});
+```
+
+### Feature Flags
+
+```typescript
+const agent = create{{AGENT_NAME_PASCAL}}Agent({
+  enableExampleFeature: true,  // Enable example feature
+});
+```
+
+## Configuration Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `model` | `BaseLanguageModel` | `ChatOpenAI(gpt-4)` | LLM model to use |
+| `temperature` | `number` | `0.7` | Model temperature (0-2) |
+| `customTools` | `Tool[]` | `[]` | Custom tools to inject |
+| `toolRegistry` | `ToolRegistry` | `undefined` | Tool registry for tool management |
+| `enabledCategories` | `ToolCategory[]` | `undefined` | Filter tools by category |
+| `enableExampleFeature` | `boolean` | `true` | Enable example feature |
+| `maxIterations` | `number` | `10` | Maximum agent iterations |
+| `systemPrompt` | `string` | (from file) | Custom system prompt |
+| `organizationName` | `string` | `undefined` | Organization name for context |
+| `description` | `string` | (default) | Agent description |
+
+## Built-in Tools
+
+### example-action
+Perform an example action.
+
+**Parameters:**
+- `input` (string) - Input for the action
+
+**Returns:**
+- `result` (string) - Processed result
+- `success` (boolean) - Success status
+
+## Prompt Management
+
+Prompts are stored in `prompts/system.md` and support variable substitution:
+
+```markdown
+# {{AGENT_NAME_PASCAL}} Agent
+
+You are working for {{organizationName}}.
+
+{{#if enableExampleFeature}}
+You have access to example features.
+{{/if}}
+```
+
+**Template Syntax:**
+- Simple variables: `{{variableName}}`
+- Conditional blocks: `{{#if variableName}}...{{/if}}`
+
+## Testing
+
+```bash
+npm test
+```
+
+## License
+
+MIT
+

package/templates/reusable-agent/index.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { create{{AGENT_NAME_PASCAL}}Agent, {{AGENT_NAME_PASCAL}}ConfigSchema } from './index.js';
+import { toolBuilder, ToolCategory, ToolRegistry } from '@agentforge/core';
+import { ChatOpenAI } from '@langchain/openai';
+
+describe('{{AGENT_NAME_PASCAL}}Agent', () => {
+  describe('Configuration Validation', () => {
+    it('should accept valid configuration', () => {
+      const config = {
+        temperature: 0.7,
+        organizationName: 'Test Org',
+        enableExampleFeature: true,
+      };
+
+      expect(() => {{AGENT_NAME_PASCAL}}ConfigSchema.parse(config)).not.toThrow();
+    });
+
+    it('should reject invalid temperature', () => {
+      const config = {
+        temperature: 3.0, // Invalid: > 2
+      };
+
+      expect(() => {{AGENT_NAME_PASCAL}}ConfigSchema.parse(config)).toThrow();
+    });
+
+    it('should accept empty configuration', () => {
+      expect(() => {{AGENT_NAME_PASCAL}}ConfigSchema.parse({})).not.toThrow();
+    });
+  });
+
+  describe('Agent Creation', () => {
+    it('should create agent with default configuration', () => {
+      const agent = create{{AGENT_NAME_PASCAL}}Agent();
+      expect(agent).toBeDefined();
+      expect(typeof agent.invoke).toBe('function');
+    });
+
+    it('should create agent with custom model', () => {
+      const customModel = new ChatOpenAI({
+        modelName: 'gpt-3.5-turbo',
+        temperature: 0.3,
+      });
+
+      const agent = create{{AGENT_NAME_PASCAL}}Agent({
+        model: customModel,
+      });
+
+      expect(agent).toBeDefined();
+    });
+
+    it('should create agent with custom temperature', () => {
+      const agent = create{{AGENT_NAME_PASCAL}}Agent({
+        temperature: 0.2,
+      });
+
+      expect(agent).toBeDefined();
+    });
+  });
+
+  describe('Tool Injection', () => {
+    it('should accept custom tools', () => {
+      const customTool = toolBuilder()
+        .name('custom-tool')
+        .description('A custom tool for testing')
+        .category(ToolCategory.UTILITY)
+        .schema(z.object({
+          input: z.string().describe('Test input'),
+        }))
+        .implement(async ({ input }) => ({ result: input }))
+        .build();
+
+      const agent = create{{AGENT_NAME_PASCAL}}Agent({
+        customTools: [customTool],
+      });
+
+      expect(agent).toBeDefined();
+    });
+
+    it('should accept tool registry', () => {
+      const registry = new ToolRegistry();
+      
+      const tool = toolBuilder()
+        .name('registry-tool')
+        .description('A tool from registry')
+        .category(ToolCategory.UTILITY)
+        .schema(z.object({
+          input: z.string().describe('Test input'),
+        }))
+        .implement(async ({ input }) => ({ result: input }))
+        .build();
+
+      registry.register(tool);
+
+      const agent = create{{AGENT_NAME_PASCAL}}Agent({
+        toolRegistry: registry,
+      });
+
+      expect(agent).toBeDefined();
+    });
+
+    it('should filter tools by category', () => {
+      const registry = new ToolRegistry();
+      
+      const utilityTool = toolBuilder()
+        .name('utility-tool')
+        .description('A utility tool')
+        .category(ToolCategory.UTILITY)
+        .schema(z.object({}))
+        .implement(async () => ({ result: 'utility' }))
+        .build();
+
+      registry.register(utilityTool);
+
+      const agent = create{{AGENT_NAME_PASCAL}}Agent({
+        toolRegistry: registry,
+        enabledCategories: [ToolCategory.UTILITY],
+      });
+
+      expect(agent).toBeDefined();
+    });
+  });
+
+  describe('Feature Flags', () => {
+    it('should enable example feature by default', () => {
+      const agent = create{{AGENT_NAME_PASCAL}}Agent();
+      expect(agent).toBeDefined();
+    });
+
+    it('should disable example feature when configured', () => {
+      const agent = create{{AGENT_NAME_PASCAL}}Agent({
+        enableExampleFeature: false,
+      });
+      expect(agent).toBeDefined();
+    });
+  });
+
+  describe('System Prompt Customization', () => {
+    it('should use default system prompt', () => {
+      const agent = create{{AGENT_NAME_PASCAL}}Agent({
+        organizationName: 'Test Org',
+      });
+      expect(agent).toBeDefined();
+    });
+
+    it('should accept custom system prompt', () => {
+      const customPrompt = 'You are a custom agent with specific instructions.';
+      const agent = create{{AGENT_NAME_PASCAL}}Agent({
+        systemPrompt: customPrompt,
+      });
+      expect(agent).toBeDefined();
+    });
+  });
+});
+

package/templates/reusable-agent/index.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { createReActAgent } from '@agentforge/patterns';
+import { toolBuilder, ToolCategory, ToolRegistry } from '@agentforge/core';
+import type { BaseLanguageModel } from '@langchain/core/language_models/base';
+import { ChatOpenAI } from '@langchain/openai';
+import { loadPrompt } from './prompt-loader.js';
+
+/**
+ * Configuration schema for {{AGENT_NAME_PASCAL}}Agent
+ */
+export const {{AGENT_NAME_PASCAL}}ConfigSchema = z.object({
+  // Model configuration
+  model: z.custom<BaseLanguageModel>().optional(),
+  temperature: z.number().min(0).max(2).optional(),
+
+  // Tool configuration
+  customTools: z.array(z.any()).optional(),
+  toolRegistry: z.custom<ToolRegistry>().optional(),
+  enabledCategories: z.array(z.nativeEnum(ToolCategory)).optional(),
+
+  // Feature flags
+  enableExampleFeature: z.boolean().optional(),
+
+  // Behavior configuration
+  maxIterations: z.number().min(1).max(50).optional(),
+  systemPrompt: z.string().optional(),
+
+  // Domain-specific configuration
+  organizationName: z.string().optional(),
+  description: z.string().optional(),
+});
+
+export type {{AGENT_NAME_PASCAL}}Config = z.infer<typeof {{AGENT_NAME_PASCAL}}ConfigSchema>;
+
+/**
+ * Default configuration for {{AGENT_NAME_PASCAL}}Agent
+ */
+const DEFAULT_CONFIG: Partial<{{AGENT_NAME_PASCAL}}Config> = {
+  temperature: 0.7,
+  maxIterations: 10,
+  enableExampleFeature: true,
+};
+
+/**
+ * Build tools for the {{AGENT_NAME_CAMEL}} agent
+ */
+function buildTools(config: {{AGENT_NAME_PASCAL}}Config) {
+  const tools = [];
+
+  // Example built-in tool
+  if (config.enableExampleFeature) {
+    const exampleTool = toolBuilder()
+      .name('example-action')
+      .description('Perform an example action')
+      .category(ToolCategory.UTILITY)
+      .schema(z.object({
+        input: z.string().describe('Input for the action'),
+      }))
+      .implement(async ({ input }) => {
+        return {
+          result: `Processed: ${input}`,
+          success: true,
+        };
+      })
+      .build();
+
+    tools.push(exampleTool);
+  }
+
+  // Add custom tools from registry
+  if (config.toolRegistry) {
+    const registryTools = config.enabledCategories
+      ? config.toolRegistry.getByCategory(config.enabledCategories)
+      : config.toolRegistry.getAll();
+    tools.push(...registryTools);
+  }
+
+  // Add custom tools
+  if (config.customTools) {
+    tools.push(...config.customTools);
+  }
+
+  return tools;
+}
+
+/**
+ * Build system prompt for the {{AGENT_NAME_CAMEL}} agent
+ */
+function buildSystemPrompt(config: {{AGENT_NAME_PASCAL}}Config): string {
+  if (config.systemPrompt) {
+    return config.systemPrompt;
+  }
+
+  // Load prompt from external file with variable substitution
+  return loadPrompt('system', {
+    organizationName: config.organizationName || 'your organization',
+    description: config.description || '{{AGENT_DESCRIPTION}}',
+    enableExampleFeature: config.enableExampleFeature,
+  });
+}
+
+/**
+ * Create a {{AGENT_NAME_CAMEL}} agent
+ * 
+ * @param config - Configuration options for the agent
+ * @returns A configured ReAct agent
+ * 
+ * @example
+ * ```typescript
+ * const agent = create{{AGENT_NAME_PASCAL}}Agent({
+ *   organizationName: 'Acme Corp',
+ *   enableExampleFeature: true,
+ * });
+ * 
+ * const result = await agent.invoke({
+ *   input: 'Your query here',
+ * });
+ * ```
+ */
+export function create{{AGENT_NAME_PASCAL}}Agent(config: {{AGENT_NAME_PASCAL}}Config = {}) {
+  // Validate and merge with defaults
+  const validatedConfig = {{AGENT_NAME_PASCAL}}ConfigSchema.parse({
+    ...DEFAULT_CONFIG,
+    ...config,
+  });
+
+  // Create model
+  const model = validatedConfig.model || new ChatOpenAI({
+    modelName: 'gpt-4',
+    temperature: validatedConfig.temperature,
+  });
+
+  // Build tools
+  const tools = buildTools(validatedConfig);
+
+  // Build system prompt
+  const systemPrompt = buildSystemPrompt(validatedConfig);
+
+  // Create agent
+  return createReActAgent({
+    model,
+    tools,
+    systemPrompt,
+    maxIterations: validatedConfig.maxIterations,
+  });
+}
+

package/templates/reusable-agent/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
+  "description": "{{AGENT_DESCRIPTION}}",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "agentforge",
+    "ai-agent",
+    "llm",
+    "reusable-agent"
+  ],
+  "author": "{{AUTHOR}}",
+  "license": "MIT",
+  "dependencies": {
+    "@agentforge/core": "workspace:*",
+    "@agentforge/patterns": "workspace:*",
+    "@langchain/core": "^1.1.8",
+    "@langchain/openai": "^0.3.14",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  }
+}
+

package/templates/reusable-agent/prompt-loader.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Simple template variable substitution
+ * Supports: {{variable}} and {{#if variable}}...{{/if}}
+ */
+export function renderTemplate(template: string, variables: Record<string, any>): string {
+  let result = template;
+
+  // Replace simple variables: {{variableName}}
+  result = result.replace(/\{\{(\w+)\}\}/g, (match, varName) => {
+    return variables[varName] !== undefined ? String(variables[varName]) : match;
+  });
+
+  // Handle conditional blocks: {{#if variableName}}...{{/if}}
+  result = result.replace(/\{\{#if (\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g, (match, varName, content) => {
+    return variables[varName] ? content : '';
+  });
+
+  return result;
+}
+
+/**
+ * Load a prompt template from the prompts directory
+ */
+export function loadPromptTemplate(name: string): string {
+  const promptPath = join(__dirname, '..', 'prompts', `${name}.md`);
+  return readFileSync(promptPath, 'utf-8');
+}
+
+/**
+ * Load and render a prompt with variables
+ */
+export function loadPrompt(name: string, variables: Record<string, any> = {}): string {
+  const template = loadPromptTemplate(name);
+  return renderTemplate(template, variables);
+}
+

package/templates/reusable-agent/prompts/system.md

@@ -0,0 +1,28 @@
+# {{AGENT_NAME_PASCAL}} Agent
+
+You are a professional AI agent{{#if organizationName}} working for {{organizationName}}{{/if}}.
+
+## Your Role
+
+{{description}}
+
+## Guidelines
+
+- Be helpful, accurate, and professional
+- Use the available tools to accomplish tasks
+- Ask clarifying questions when needed
+- Provide clear explanations of your actions
+
+{{#if enableExampleFeature}}
+## Example Feature
+
+You have access to example actions that can help you accomplish tasks more effectively.
+
+{{/if}}
+
+## Important Notes
+
+- Always verify information before providing it
+- If you're unsure about something, say so
+- Use tools appropriately and explain your reasoning
+

package/templates/reusable-agent/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
+

package/templates/reusable-agent/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['dist/**', '**/*.test.ts', '**/*.config.ts'],
+    },
+  },
+});
+