@majkapp/plugin-kit 3.7.2 → 3.7.4

package/docs/AGENTS.md

@@ -0,0 +1,641 @@
+# Agents API - AI Agent Management
+
+The Agents API provides programmatic access to create, manage, and interact with AI agents in MAJK. Agents are AI assistants with configurable models, system prompts, and MCP server access that can be used to automate tasks and provide specialized AI capabilities.
+
+## Quick Start
+
+```typescript
+import { PluginContext } from '@majkapp/plugin-kit';
+
+async function exampleAgentUsage(ctx: PluginContext) {
+  // Create a new agent
+  const agent = await ctx.majk.agents.create({
+    name: 'Code Reviewer',
+    description: 'Specialized agent for reviewing code quality and security',
+    systemPrompt: 'You are an expert code reviewer. Focus on security, performance, and best practices.',
+    model: 'claude-3-sonnet-20240229',
+    temperature: 0.1,
+    maxTokens: 4000,
+    tags: ['code', 'review', 'security']
+  });
+
+  // Test the agent
+  const testResult = await ctx.majk.agents.test(agent.id, 'Review this function for potential issues');
+
+  // Clone the agent with modifications
+  const clonedAgent = await ctx.majk.agents.clone(agent.id, {
+    name: 'Senior Code Reviewer',
+    temperature: 0.05
+  });
+
+  console.log('Created agent:', agent.name);
+  console.log('Test successful:', testResult.success);
+  console.log('Cloned agent:', clonedAgent.name);
+}
+```
+
+## Core Concepts
+
+### Agents vs Teammates
+
+- **Agents**: Raw AI models with system prompts and configuration
+- **Teammates**: Agents enhanced with skills, project assignments, and specialized roles
+- Agents are the foundation; teammates build upon agents with additional context
+
+### Agent Configuration
+
+Agents support extensive configuration:
+- **Model Selection**: Choose from available AI models
+- **System Prompts**: Define the agent's personality and instructions
+- **Temperature**: Control randomness in responses (0.0 = deterministic, 1.0 = creative)
+- **Token Limits**: Set maximum response length
+- **MCP Servers**: Grant access to external tools and data sources
+
+## API Reference
+
+### create(data: CreateAgentRequest): Promise<AgentHandle>
+
+Creates a new AI agent with the specified configuration.
+
+```typescript
+const agent = await ctx.majk.agents.create({
+  name: 'Data Analyst',
+  description: 'Specialized in data analysis and visualization',
+  systemPrompt: 'You are a data analyst expert. Provide clear insights and actionable recommendations.',
+  model: 'claude-3-sonnet-20240229',
+  temperature: 0.2,
+  maxTokens: 8000,
+  mcpServerIds: ['data-tools-server'],
+  configuration: {
+    streaming: true,
+    timeout: 30000,
+    rateLimiting: {
+      requestsPerMinute: 60,
+      tokensPerMinute: 50000
+    }
+  },
+  tags: ['data', 'analysis'],
+  isActive: true
+});
+
+console.log('Agent created:', agent.id);
+```
+
+**Parameters**:
+- `name` (string): Display name for the agent
+- `description` (string, optional): Brief description of the agent's purpose
+- `systemPrompt` (string): Instructions that define the agent's behavior
+- `model` (string): AI model identifier (e.g., 'claude-3-sonnet-20240229')
+- `temperature` (number, optional): Response randomness (0.0-1.0)
+- `maxTokens` (number, optional): Maximum tokens in responses
+- `mcpServerIds` (string[], optional): MCP servers the agent can access
+- `configuration` (object, optional): Advanced settings
+- `tags` (string[], optional): Tags for organization
+- `isActive` (boolean, optional): Whether the agent is active (default: true)
+
+### get(id: string): Promise<AgentHandle | null>
+
+Retrieves an agent by ID.
+
+```typescript
+const agent = await ctx.majk.agents.get('agent-123');
+if (agent) {
+  console.log('Found agent:', agent.name);
+  console.log('Model:', agent.model);
+  console.log('Active:', agent.isActive);
+} else {
+  console.log('Agent not found');
+}
+```
+
+### list(filter?: AgentFilter): Promise<AgentHandle[]>
+
+Lists agents with optional filtering.
+
+```typescript
+// List all agents
+const allAgents = await ctx.majk.agents.list();
+
+// Filter by active agents
+const activeAgents = await ctx.majk.agents.list({ isActive: true });
+
+// Filter by model
+const claudeAgents = await ctx.majk.agents.list({
+  model: 'claude-3-sonnet-20240229'
+});
+
+// Filter by tags
+const codeAgents = await ctx.majk.agents.list({
+  tags: ['code', 'review']
+});
+
+console.log('Total agents:', allAgents.length);
+console.log('Active agents:', activeAgents.length);
+```
+
+**Filter Options**:
+- `isActive` (boolean): Filter by active status
+- `model` (string): Filter by AI model
+- `tags` (string[]): Filter by tags (agent must have all specified tags)
+
+### update(id: string, updates: AgentUpdate): Promise<AgentHandle>
+
+Updates an existing agent's configuration.
+
+```typescript
+const updatedAgent = await ctx.majk.agents.update('agent-123', {
+  name: 'Advanced Code Reviewer',
+  temperature: 0.15,
+  maxTokens: 6000,
+  tags: ['code', 'review', 'security', 'advanced'],
+  configuration: {
+    streaming: true,
+    timeout: 45000
+  }
+});
+
+console.log('Agent updated:', updatedAgent.name);
+```
+
+### delete(id: string): Promise<boolean>
+
+Deletes an agent permanently.
+
+```typescript
+const deleted = await ctx.majk.agents.delete('agent-123');
+if (deleted) {
+  console.log('Agent deleted successfully');
+} else {
+  console.log('Agent not found or could not be deleted');
+}
+```
+
+### exists(id: string): Promise<boolean>
+
+Checks if an agent exists.
+
+```typescript
+const agentExists = await ctx.majk.agents.exists('agent-123');
+console.log('Agent exists:', agentExists);
+```
+
+### count(filter?: AgentFilter): Promise<number>
+
+Counts agents matching the filter criteria.
+
+```typescript
+const totalAgents = await ctx.majk.agents.count();
+const activeAgents = await ctx.majk.agents.count({ isActive: true });
+const codeAgents = await ctx.majk.agents.count({ tags: ['code'] });
+
+console.log(`Total: ${totalAgents}, Active: ${activeAgents}, Code: ${codeAgents}`);
+```
+
+### test(agentId: string, message: string): Promise<TestResult>
+
+Tests an agent with a message to verify it's working correctly.
+
+```typescript
+const testResult = await ctx.majk.agents.test('agent-123',
+  'Hello! Can you help me review this code snippet?'
+);
+
+if (testResult.success) {
+  console.log('Agent responded:', testResult.response);
+  console.log('Response time:', testResult.duration, 'ms');
+} else {
+  console.error('Agent test failed:', testResult.error);
+}
+```
+
+**TestResult Properties**:
+- `success` (boolean): Whether the test succeeded
+- `response` (string, optional): The agent's response
+- `error` (string, optional): Error message if test failed
+- `duration` (number, optional): Response time in milliseconds
+
+### clone(agentId: string, modifications?: Partial<CreateAgentRequest>): Promise<AgentHandle>
+
+Creates a copy of an existing agent with optional modifications.
+
+```typescript
+// Simple clone
+const clonedAgent = await ctx.majk.agents.clone('agent-123');
+
+// Clone with modifications
+const modifiedClone = await ctx.majk.agents.clone('agent-123', {
+  name: 'Enhanced Code Reviewer',
+  temperature: 0.05,
+  maxTokens: 8000,
+  tags: ['code', 'review', 'enhanced'],
+  systemPrompt: 'You are an expert senior code reviewer with 10+ years experience...'
+});
+
+console.log('Cloned agent:', modifiedClone.name);
+```
+
+### channel(): any
+
+Returns an event channel for real-time agent events.
+
+```typescript
+const channel = ctx.majk.agents.channel();
+// Use for subscribing to agent creation, updates, deletion events
+```
+
+## Agent Handle Methods
+
+When you retrieve an agent, you get an `AgentHandle` with additional methods:
+
+```typescript
+const agent = await ctx.majk.agents.get('agent-123');
+
+// Test the agent directly
+const testResult = await agent.test('Test message');
+
+// Clone the agent
+const clone = await agent.clone({ name: 'Agent Clone' });
+
+// Update the agent
+await agent.update({ temperature: 0.3 });
+
+// Delete the agent
+await agent.delete();
+
+// Get MCP servers
+const mcpServers = await agent.getMCPServers();
+
+// Manage MCP servers
+await agent.addMCPServer('new-server-id');
+await agent.removeMCPServer('old-server-id');
+
+// Event handlers
+const unsubscribe = agent.onChange((updatedAgent) => {
+  console.log('Agent updated:', updatedAgent.name);
+});
+
+agent.onDelete(() => {
+  console.log('Agent was deleted');
+});
+
+// Convert to entity
+const entity = agent.toEntity();
+```
+
+## Examples
+
+### Creating a Specialized Code Review Agent
+
+```typescript
+async function createCodeReviewAgent(ctx: PluginContext) {
+  const agent = await ctx.majk.agents.create({
+    name: 'Security Code Reviewer',
+    description: 'Focuses on security vulnerabilities and best practices',
+    systemPrompt: `You are a security-focused code reviewer with expertise in:
+- OWASP Top 10 vulnerabilities
+- Secure coding practices
+- Authentication and authorization
+- Input validation and sanitization
+- Cryptography best practices
+
+When reviewing code:
+1. Identify potential security vulnerabilities
+2. Suggest specific fixes with code examples
+3. Explain the security implications
+4. Prioritize issues by severity (Critical, High, Medium, Low)
+5. Be thorough but practical in your recommendations`,
+    model: 'claude-3-sonnet-20240229',
+    temperature: 0.1,
+    maxTokens: 6000,
+    tags: ['security', 'code-review', 'vulnerabilities'],
+    configuration: {
+      streaming: true,
+      timeout: 60000,
+      rateLimiting: {
+        requestsPerMinute: 30,
+        tokensPerMinute: 40000
+      }
+    }
+  });
+
+  // Test with a sample security issue
+  const testResult = await agent.test(`
+    Review this authentication function:
+
+    function authenticate(username, password) {
+      const query = "SELECT * FROM users WHERE username='" + username +
+                   "' AND password='" + password + "'";
+      return database.query(query);
+    }
+  `);
+
+  console.log('Security review result:', testResult.response);
+  return agent;
+}
+```
+
+### Creating Multiple Specialized Agents
+
+```typescript
+async function createDevelopmentTeam(ctx: PluginContext) {
+  const agents = [];
+
+  // Code Reviewer
+  const reviewer = await ctx.majk.agents.create({
+    name: 'Code Reviewer',
+    systemPrompt: 'Expert at code quality, best practices, and architectural review.',
+    model: 'claude-3-sonnet-20240229',
+    temperature: 0.2,
+    tags: ['code', 'review']
+  });
+  agents.push(reviewer);
+
+  // Documentation Writer
+  const documenter = await ctx.majk.agents.create({
+    name: 'Documentation Writer',
+    systemPrompt: 'Specialized in creating clear, comprehensive technical documentation.',
+    model: 'claude-3-sonnet-20240229',
+    temperature: 0.3,
+    tags: ['documentation', 'writing']
+  });
+  agents.push(documenter);
+
+  // Test Engineer
+  const tester = await ctx.majk.agents.create({
+    name: 'Test Engineer',
+    systemPrompt: 'Expert at designing comprehensive test suites and quality assurance.',
+    model: 'claude-3-sonnet-20240229',
+    temperature: 0.15,
+    tags: ['testing', 'qa']
+  });
+  agents.push(tester);
+
+  console.log(`Created ${agents.length} specialized agents`);
+  return agents;
+}
+```
+
+### Agent Testing and Validation
+
+```typescript
+async function validateAgents(ctx: PluginContext) {
+  const agents = await ctx.majk.agents.list({ isActive: true });
+  const results = [];
+
+  for (const agent of agents) {
+    console.log(`Testing agent: ${agent.name}`);
+
+    const testResult = await agent.test(
+      'Please introduce yourself and describe your capabilities.'
+    );
+
+    results.push({
+      agentId: agent.id,
+      agentName: agent.name,
+      testPassed: testResult.success,
+      responseTime: testResult.duration,
+      error: testResult.error
+    });
+
+    if (testResult.success) {
+      console.log(`✅ ${agent.name} - Response time: ${testResult.duration}ms`);
+    } else {
+      console.log(`❌ ${agent.name} - Error: ${testResult.error}`);
+    }
+  }
+
+  return results;
+}
+```
+
+### Agent Cloning for Variations
+
+```typescript
+async function createAgentVariations(ctx: PluginContext) {
+  const baseAgent = await ctx.majk.agents.create({
+    name: 'Base Code Reviewer',
+    systemPrompt: 'You are a code reviewer.',
+    model: 'claude-3-sonnet-20240229',
+    temperature: 0.2,
+    tags: ['code', 'review']
+  });
+
+  // Create conservative variation
+  const conservativeReviewer = await ctx.majk.agents.clone(baseAgent.id, {
+    name: 'Conservative Code Reviewer',
+    temperature: 0.05,
+    systemPrompt: 'You are a very thorough and conservative code reviewer. Be strict about best practices.',
+    tags: ['code', 'review', 'conservative']
+  });
+
+  // Create creative variation
+  const creativeReviewer = await ctx.majk.agents.clone(baseAgent.id, {
+    name: 'Creative Code Reviewer',
+    temperature: 0.4,
+    systemPrompt: 'You are a creative code reviewer who suggests innovative solutions and modern approaches.',
+    tags: ['code', 'review', 'creative']
+  });
+
+  return [baseAgent, conservativeReviewer, creativeReviewer];
+}
+```
+
+## Best Practices
+
+### Agent Design
+
+1. **Clear Purpose**: Give each agent a specific, well-defined role
+2. **Appropriate Temperature**: Use low values (0.0-0.2) for analytical tasks, higher (0.3-0.6) for creative work
+3. **Descriptive Names**: Use names that clearly indicate the agent's function
+4. **Comprehensive Prompts**: Provide detailed system prompts with examples and guidelines
+5. **Proper Tagging**: Use consistent tags for organization and filtering
+
+### System Prompt Guidelines
+
+```typescript
+// Good system prompt example
+const systemPrompt = `You are a senior software architect with 15+ years of experience.
+
+Your role:
+- Review code architecture and design patterns
+- Suggest improvements for scalability and maintainability
+- Identify potential technical debt
+- Recommend appropriate design patterns
+
+When reviewing:
+1. Focus on high-level architecture first
+2. Consider long-term maintainability
+3. Suggest specific improvements with rationale
+4. Prioritize issues by impact
+5. Provide code examples when helpful
+
+Your expertise includes:
+- Microservices architecture
+- Domain-driven design
+- SOLID principles
+- Design patterns (GoF, Enterprise)
+- Cloud-native architectures`;
+```
+
+### Testing and Validation
+
+1. **Regular Testing**: Test agents periodically to ensure they're functioning correctly
+2. **Performance Monitoring**: Monitor response times and success rates
+3. **Prompt Iteration**: Refine system prompts based on actual usage patterns
+4. **Version Control**: Keep track of prompt changes and their impact
+
+### Resource Management
+
+1. **Token Limits**: Set appropriate token limits based on use case
+2. **Rate Limiting**: Configure rate limits to prevent abuse
+3. **Cleanup**: Delete unused agents to reduce resource consumption
+4. **Monitoring**: Track agent usage and performance metrics
+
+## Error Handling
+
+```typescript
+async function robustAgentOperation(ctx: PluginContext) {
+  try {
+    const agent = await ctx.majk.agents.create({
+      name: 'Test Agent',
+      systemPrompt: 'You are a helpful assistant.',
+      model: 'claude-3-sonnet-20240229'
+    });
+
+    // Test the agent with error handling
+    try {
+      const testResult = await agent.test('Hello, are you working?');
+      if (!testResult.success) {
+        console.error('Agent test failed:', testResult.error);
+        // Handle test failure (retry, alert, etc.)
+      }
+    } catch (testError) {
+      console.error('Error testing agent:', testError);
+    }
+
+    return agent;
+  } catch (createError) {
+    console.error('Error creating agent:', createError);
+
+    // Check if it's a model availability issue
+    if (createError.message.includes('model')) {
+      console.log('Trying with different model...');
+      // Retry with different model
+    }
+
+    throw createError;
+  }
+}
+```
+
+## Integration with Other APIs
+
+### Using Agents with Tasks
+
+```typescript
+// Create agent and use it for task automation
+const agent = await ctx.majk.agents.create({
+  name: 'Task Processor',
+  systemPrompt: 'You process and analyze task requirements.',
+  model: 'claude-3-sonnet-20240229'
+});
+
+// Use agent in task processing
+const task = await ctx.majk.tasks.start({
+  title: 'Process user feedback',
+  message: 'Analyze the attached feedback and provide insights',
+  agentId: agent.id,
+  workingDirectory: '/project/feedback'
+});
+```
+
+### Converting Agents to Teammates
+
+```typescript
+// Create agent first
+const agent = await ctx.majk.agents.create({
+  name: 'Code Expert',
+  systemPrompt: 'Expert in software development.',
+  model: 'claude-3-sonnet-20240229'
+});
+
+// Convert to teammate with additional capabilities
+const teammate = await ctx.majk.teammates.create({
+  name: agent.name,
+  role: 'Software Developer',
+  skills: {
+    primary: ['JavaScript', 'Python', 'React'],
+    secondary: ['Docker', 'AWS', 'Testing'],
+    languages: ['JavaScript', 'Python', 'TypeScript'],
+    frameworks: ['React', 'Node.js', 'Express'],
+    tools: ['Git', 'VSCode', 'Jest']
+  },
+  systemPrompt: agent.systemPrompt,
+  model: agent.model,
+  expertise: ['Web Development', 'API Design', 'Code Review']
+});
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Agent Creation Fails**
+- Check if the specified model is available
+- Verify system prompt is not empty
+- Ensure required fields are provided
+
+**Test Failures**
+- Check agent is active (`isActive: true`)
+- Verify model is responding (check provider status)
+- Test with simple message first
+
+**Performance Issues**
+- Adjust temperature for faster/more deterministic responses
+- Reduce maxTokens if responses are too long
+- Check rate limiting configuration
+
+**Memory Usage**
+- Delete unused agents regularly
+- Monitor agent count with `ctx.majk.agents.count()`
+- Use filtering to manage large numbers of agents
+
+### Debugging
+
+```typescript
+async function debugAgent(ctx: PluginContext, agentId: string) {
+  const agent = await ctx.majk.agents.get(agentId);
+  if (!agent) {
+    console.log('Agent not found');
+    return;
+  }
+
+  console.log('Agent Details:', {
+    id: agent.id,
+    name: agent.name,
+    model: agent.model,
+    isActive: agent.isActive,
+    temperature: agent.temperature,
+    maxTokens: agent.maxTokens,
+    tags: agent.tags
+  });
+
+  // Test basic functionality
+  const testResult = await agent.test('Hello');
+  console.log('Basic test:', testResult.success ? 'PASS' : 'FAIL');
+  if (!testResult.success) {
+    console.log('Test error:', testResult.error);
+  }
+
+  // Check MCP servers
+  const mcpServers = await agent.getMCPServers();
+  console.log('MCP Servers:', mcpServers.length);
+}
+```
+
+## Related APIs
+
+- [Tasks API](./TASKS.md) - Use agents for automated task processing
+- [Teammates API](./TEAMMATES.md) - Enhanced agents with skills and project assignments
+- [AI API](./AI.md) - Lower-level AI model access
+- [MCP Servers](./SERVICES.md) - External tools and data sources for agents