diff --git a/documentation/mainfolder/docs/3_CustomAgents/3_agents/2_custom-agent.md b/documentation/mainfolder/docs/3_CustomAgents/3_agents/2_custom-agent.md index 2ce1b2cc..de854749 100644 --- a/documentation/mainfolder/docs/3_CustomAgents/3_agents/2_custom-agent.md +++ b/documentation/mainfolder/docs/3_CustomAgents/3_agents/2_custom-agent.md @@ -1,16 +1,231 @@ # Creating Custom Agents -This comprehensive guide will walk you through creating custom agents tailored to your specific development needs. Whether you want to automate code reviews, generate documentation, or implement custom workflows, this guide provides everything you need to build powerful, intelligent agents. +This guide walks you through creating custom agents using the `@codebolt/agent` framework. ## Introduction -Custom agents are the key to unlocking Codebolt's full potential. While built-in agents handle common scenarios, custom agents can be tailored to your exact requirements, coding standards, and workflow preferences. +Custom agents allow you to tailor Codebolt's capabilities to your exact requirements, coding standards, and workflow preferences. By the end of this guide, you'll know how to: -- Design effective agent architectures -- Implement agents using multiple approaches -- Configure triggers and actions -- Handle complex workflows -- Debug and optimize agent performance +- Create agents using `CodeboltAgent` and `Agent` classes +- Add custom tools to agents +- Configure processors for enhanced behavior +- Handle errors and debug agents +## Quick Start +### Basic Agent + +```typescript +import { CodeboltAgent, createTool } from '@codebolt/agent/unified'; +import { z } from 'zod'; + +// Create a tool +const greetTool = createTool({ + id: 'greet', + description: 'Greet a user by name', + inputSchema: z.object({ + name: z.string() + }), + execute: async ({ input }) => { + return { message: `Hello, ${input.name}!` }; + } +}); + +// Create an agent +const agent = new CodeboltAgent({ + instructions: 'You are a friendly assistant that greets users.', + tools: [greetTool] +}); + +// Use the agent +const result = await agent.execute({ + role: 'user', + content: 'Please greet John' +}); + +console.log(result); +``` + +### Using Factory Function + +```typescript +import { createCodeboltAgent, createTool } from '@codebolt/agent/unified'; + +const agent = createCodeboltAgent({ + systemPrompt: 'You are a helpful assistant.', + tools: [myTool] +}); +``` + +## Adding Processors + +Processors customize agent behavior at different execution stages. + +```typescript +import { CodeboltAgent } from '@codebolt/agent/unified'; +import { + EnvironmentContextModifier, + DirectoryContextModifier, + ToolValidationModifier, + ConversationCompactorModifier, + LoopDetectionModifier +} from '@codebolt/agent/processor-pieces'; + +const agent = new CodeboltAgent({ + instructions: 'You are an enhanced assistant.', + tools: [myTools], + + // Add context to messages + messageModifiers: [ + new EnvironmentContextModifier(), + new DirectoryContextModifier() + ], + + // Detect infinite loops + postInferenceProcessors: [ + new LoopDetectionModifier({ maxIterations: 10 }) + ], + + // Validate tool calls + preToolCallProcessors: [ + new ToolValidationModifier() + ], + + // Manage conversation length + postToolCallProcessors: [ + new ConversationCompactorModifier({ maxConversationLength: 30 }) + ] +}); +``` + +## Creating Custom Tools + +```typescript +import { createTool } from '@codebolt/agent/unified'; +import { z } from 'zod'; + +const searchTool = createTool({ + id: 'search', + description: 'Search for information', + inputSchema: z.object({ + query: z.string(), + maxResults: z.number().optional().default(10) + }), + execute: async ({ input, context }) => { + // Implement search logic + const results = await performSearch(input.query, input.maxResults); + return { results }; + } +}); + +const agent = new CodeboltAgent({ + instructions: 'You help users find information.', + tools: [searchTool] +}); +``` + +## Error Handling + +```typescript +const result = await agent.execute({ + role: 'user', + content: 'Do something complex' +}); + +if (!result.success) { + console.error('Agent execution failed:', result.error); + // Handle the error appropriately +} else { + console.log('Result:', result.result); +} +``` + +## Using the Base Agent Class + +For more control over agent configuration: + +```typescript +import { Agent } from '@codebolt/agent/unified'; +import { ToolValidationModifier } from '@codebolt/agent/processor-pieces'; + +const agent = new Agent({ + name: 'My Custom Agent', + instructions: 'You are a specialized assistant.', + tools: [myTools], + + preToolCallProcessors: [ + new ToolValidationModifier({ strictMode: true }) + ] +}); + +const result = await agent.execute({ + role: 'user', + content: 'Help me with a task' +}); +``` + +## Debugging Agents + +Use `ChatRecordingModifier` to log conversations: + +```typescript +import { ChatRecordingModifier } from '@codebolt/agent/processor-pieces'; + +const agent = new CodeboltAgent({ + instructions: 'You are a debug agent.', + tools: [myTools], + + messageModifiers: [ + new ChatRecordingModifier({ + enabled: true, + outputPath: './debug-logs' + }) + ] +}); +``` + +## Best Practices + +1. **Clear Instructions**: Write specific, actionable system instructions +2. **Appropriate Tools**: Only include tools relevant to the agent's purpose +3. **Error Handling**: Always check `result.success` before using results +4. **Use Processors**: Add processors for validation and conversation management +5. **Test Thoroughly**: Test with various inputs and edge cases + +## Available Imports + +```typescript +// Core classes and functions +import { + Agent, + CodeboltAgent, + createCodeboltAgent, + Tool, + createTool, + Workflow, + AgentStep, + InitialPromptGenerator, + ResponseExecutor +} from '@codebolt/agent/unified'; + +// Processors +import { + EnvironmentContextModifier, + CoreSystemPromptModifier, + DirectoryContextModifier, + IdeContextModifier, + AtFileProcessorModifier, + ArgumentProcessorModifier, + MemoryImportModifier, + ToolInjectionModifier, + ChatRecordingModifier, + ChatHistoryMessageModifier, + ChatCompressionModifier, + LoopDetectionModifier, + ToolParameterModifier, + ToolValidationModifier, + ConversationCompactorModifier, + ShellProcessorModifier +} from '@codebolt/agent/processor-pieces'; +``` diff --git a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/4-ProcessorPattern/2-MessageModifer.md b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/4-ProcessorPattern/2-MessageModifer.md index ccaf6338..41db770e 100644 --- a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/4-ProcessorPattern/2-MessageModifer.md +++ b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/4-ProcessorPattern/2-MessageModifer.md @@ -1,5 +1,9 @@ # Message Modifier +> **Note**: This document describes a planned pattern. Some modifiers referenced below (like `BaseContextMessageModifier`, `WorkingDirectoryMessageModifier`, `BaseSystemInstructionMessageModifier`, `HandleUrlMessageModifier`, `ImageAttachmentMessageModifier`, `AddToolsListMessageModifier`) are not yet implemented. See the [Roadmap](../5-unified/6-roadmap.md) for current status. +> +> For currently available message modifiers, see the [Processors documentation](../5-unified/4-processors.md). + The Message Modifier class is similar to [[2-InitialPromptBuilder]] but Instead of using builder pattern of . it uses the Processor Pattern. The Processor Allow for much more control of the Modification as you can add custom processors. diff --git a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/4-ProcessorPattern/3-LLMAgentStep.md b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/4-ProcessorPattern/3-LLMAgentStep.md index cacda288..c0537a5b 100644 --- a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/4-ProcessorPattern/3-LLMAgentStep.md +++ b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/4-ProcessorPattern/3-LLMAgentStep.md @@ -1,5 +1,9 @@ # LLM Agent Step +> **Note**: This document describes a planned pattern. Some processors referenced below (like `AdvancedLoopDetectionProcessor`, `TokenManagementProcessor`, `ResponseValidationProcessor`, `TelemetryProcessor`) are not yet implemented. See the [Roadmap](../5-unified/6-roadmap.md) for current status. +> +> For currently available APIs, see the [Unified Agent Framework](../5-unified/README.md) documentation. + This is the main LLMAgentStep that takes various Processors as Input and output. This helps it to control the internal processing. This is slightly differnet from [[3_CustomAgents/agentPatterns/2-ComposablePattern/Agent|Agent]] Where we are configuring only based on parameters. This seems to be more scalable but might need to write some more Code. diff --git a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/1-unified.md b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/1-unified.md index a5d71edd..c6d3fc9c 100644 --- a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/1-unified.md +++ b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/1-unified.md @@ -1,6 +1,6 @@ # Unified Agent Framework -The **Unified Agent Framework** is a comprehensive, self-contained system for building sophisticated AI agents with advanced capabilities. It provides a complete toolkit for creating agents that can handle complex workflows, multi-step processes, and dynamic orchestration of resources. +The **Unified Agent Framework** is a comprehensive, self-contained system for building sophisticated AI agents with advanced capabilities. It provides a complete toolkit for creating agents that can handle complex workflows, multi-step processes, and tool execution. ## Table of Contents @@ -11,28 +11,26 @@ The **Unified Agent Framework** is a comprehensive, self-contained system for bu 5. [Agents](#agents) 6. [Tools](#tools) 7. [Workflows](#workflows) -8. [Orchestrators](#orchestrators) -9. [Processors](#processors) -10. [Examples](#examples) -11. [Best Practices](#best-practices) +8. [Processors](#processors) +9. [Examples](#examples) +10. [Best Practices](#best-practices) ## Overview The Unified Agent Framework consolidates multiple agent patterns into a single, powerful system that provides: -- **🤖 Intelligent Agents** - High-level agents with conversation management and tool execution -- **🔧 Advanced Tools** - Type-safe tool creation with validation and error handling -- **📋 Structured Workflows** - Multi-step processes with dependencies and parallel execution -- **🎯 Smart Orchestration** - Dynamic coordination of agents, workflows, and tools -- **⚙️ Extensible Processors** - Pluggable components for customizing behavior -- **🔒 Type Safety** - Full TypeScript support with comprehensive type definitions +- **Intelligent Agents** - High-level agents with conversation management and tool execution +- **Advanced Tools** - Type-safe tool creation with validation and error handling +- **Structured Workflows** - Multi-step processes with context management +- **Extensible Processors** - Pluggable components for customizing behavior +- **Type Safety** - Full TypeScript support with comprehensive type definitions ### Key Benefits - **Self-Contained**: All dependencies are internal - no external package dependencies - **Modular Design**: Use individual components or the complete system - **Extensible**: Add custom processors, tools, and workflows -- **Production Ready**: Comprehensive error handling, logging, and monitoring +- **Production Ready**: Comprehensive error handling and logging - **Developer Friendly**: Intuitive APIs with extensive documentation and examples ## Architecture @@ -41,44 +39,48 @@ The Unified Framework follows a layered architecture: ``` ┌─────────────────────────────────────────────────────────────┐ -│ ORCHESTRATOR LAYER │ -│ Dynamic coordination of agents, workflows, and tools │ -├─────────────────────────────────────────────────────────────┤ │ WORKFLOW LAYER │ -│ Structured multi-step processes with dependencies │ +│ Structured multi-step processes with context management │ ├─────────────────────────────────────────────────────────────┤ │ AGENT LAYER │ -│ Intelligent agents with conversation management │ +│ Intelligent agents with conversation management │ ├─────────────────────────────────────────────────────────────┤ │ TOOL LAYER │ │ Individual functions and capabilities │ ├─────────────────────────────────────────────────────────────┤ │ PROCESSOR LAYER │ -│ Extensible components for customizing behavior │ +│ Extensible components for customizing behavior │ └─────────────────────────────────────────────────────────────┘ ``` ## Core Components ### 1. **Agent** - High-Level Intelligence + ```typescript -import { createAgent, createTool } from '@codebolt/agent/unified'; +import { CodeboltAgent, createCodeboltAgent, createTool } from '@codebolt/agent/unified'; + +// Using the factory function +const agent = createCodeboltAgent({ + systemPrompt: 'You are a helpful research assistant.', + tools: [/* custom tools */] +}); -const agent = createAgent({ - name: 'Research Assistant', +// Or using the class directly +const agent = new CodeboltAgent({ instructions: 'You are a helpful research assistant.', - tools: [/* custom tools */], - defaultProcessors: true + tools: [/* custom tools */] }); ``` ### 2. **Tool** - Specific Functions + ```typescript import { createTool } from '@codebolt/agent/unified'; +import { z } from 'zod'; const calculatorTool = createTool({ id: 'calculator', - name: 'Calculator', description: 'Perform mathematical calculations', inputSchema: z.object({ expression: z.string() }), execute: async ({ input }) => ({ result: eval(input.expression) }) @@ -86,13 +88,14 @@ const calculatorTool = createTool({ ``` ### 3. **Workflow** - Structured Processes + ```typescript -import { createWorkflow, createAgentStep } from '@codebolt/agent/unified'; +import { Workflow, AgentStep } from '@codebolt/agent/unified'; -const workflow = createWorkflow({ +const workflow = new Workflow({ name: 'Research Pipeline', steps: [ - createAgentStep({ + new AgentStep({ id: 'research', name: 'Research Phase', agent: researchAgent, @@ -102,19 +105,6 @@ const workflow = createWorkflow({ }); ``` -### 4. **Orchestrator** - Dynamic Coordination -```typescript -import { createOrchestrator } from '@codebolt/agent/unified'; - -const orchestrator = createOrchestrator({ - name: 'Smart Coordinator', - instructions: 'Coordinate resources intelligently', - agents: { researcher, analyst }, - workflows: { researchPipeline }, - tools: { calculator, summarizer } -}); -``` - ## Getting Started ### Installation @@ -130,20 +120,19 @@ pnpm add @codebolt/agent ### Basic Example ```typescript -import { createAgent, createTool } from '@codebolt/agent/unified'; +import { CodeboltAgent, createTool } from '@codebolt/agent/unified'; import { z } from 'zod'; // Create a simple tool const weatherTool = createTool({ id: 'weather', - name: 'Get Weather', description: 'Get current weather for a location', inputSchema: z.object({ location: z.string() }), execute: async ({ input }) => { // Your weather API logic here - return { + return { location: input.location, temperature: '72°F', condition: 'Sunny' @@ -152,13 +141,76 @@ const weatherTool = createTool({ }); // Create an agent with the tool -const weatherAgent = createAgent({ - name: 'Weather Assistant', +const weatherAgent = new CodeboltAgent({ instructions: 'You help users get weather information.', tools: [weatherTool] }); // Use the agent -const result = await weatherAgent.execute('What\'s the weather in New York?'); -console.log(result.response); -``` \ No newline at end of file +const result = await weatherAgent.execute({ + role: 'user', + content: 'What\'s the weather in New York?' +}); +console.log(result); +``` + +## Available Exports + +### From `@codebolt/agent/unified` + +**Classes:** +- `Agent` - Base agent class +- `CodeboltAgent` - Full-featured Codebolt agent +- `Tool` - Tool wrapper class +- `Workflow` - Workflow orchestration +- `AgentStep` - Workflow step definition +- `InitialPromptGenerator` - Message preprocessing +- `ResponseExecutor` - Tool execution handler + +**Factory Functions:** +- `createCodeboltAgent()` - Create a CodeboltAgent instance +- `createTool()` - Create a Tool instance +- `createDefaultMessageProcessor()` - Create default message processor + +**Types:** +- `UnifiedAgentConfig`, `UnifiedMessageOutput`, `UnifiedStepInput`, `UnifiedStepOutput` +- `UnifiedResponseInput`, `UnifiedResponseOutput`, `UnifiedAgentInput`, `UnifiedAgentOutput` +- `UnifiedMessageModifier`, `UnifiedResponseExecutor` +- `UnifiedAgentEvent`, `UnifiedAgentEventHandler`, `UnifiedAgentEventType` +- `OpenAIMessage`, `OpenAITool`, `ToolResult`, `CodeboltAPI` +- `AgentExecutionResult`, `StreamChunk`, `StreamCallback`, `LLMConfig` + +**Error Types:** +- `UnifiedAgentError` +- `UnifiedMessageProcessingError` +- `UnifiedStepExecutionError` +- `UnifiedResponseExecutionError` +- `UnifiedToolExecutionError` + +### From `@codebolt/agent/processor-pieces` + +**Message Modifiers:** +- `EnvironmentContextModifier` - Add environment context +- `CoreSystemPromptModifier` - Core system prompt handling +- `DirectoryContextModifier` - Working directory context +- `IdeContextModifier` - IDE integration context +- `AtFileProcessorModifier` - Process @file references +- `ArgumentProcessorModifier` - Process command arguments +- `MemoryImportModifier` - Import memory context +- `ToolInjectionModifier` - Inject tools into prompts +- `ChatRecordingModifier` - Record chat history +- `ChatHistoryMessageModifier` - Include chat history + +**PreToolCall Processors:** +- `ToolParameterModifier` - Modify tool parameters +- `ToolValidationModifier` - Validate tool calls + +**PostToolCall Processors:** +- `ConversationCompactorModifier` - Compact long conversations +- `ShellProcessorModifier` - Process shell commands + +**PreInference Processors:** +- `ChatCompressionModifier` - Compress chat history + +**PostInference Processors:** +- `LoopDetectionModifier` - Detect execution loops diff --git a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/2-agents.md b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/2-agents.md index b407adcb..eade4b25 100644 --- a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/2-agents.md +++ b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/2-agents.md @@ -4,109 +4,62 @@ Agents are the primary interface for building intelligent AI systems. They handl ## Creating Agents -```typescript -import { createAgent } from '@codebolt/agent/unified'; - -const agent = createAgent({ - name: 'Customer Support Agent', - instructions: 'You are a helpful customer support representative.', - description: 'Handles customer inquiries and support requests', - - // Tools the agent can use - tools: [searchTool, ticketTool, emailTool], - - // Configuration options - maxIterations: 10, - maxConversationLength: 50, - enableLogging: true, - - // LLM configuration - llmConfig: { - model: 'gpt-4', - temperature: 0.7, - maxTokens: 2000 - }, - - // Custom processors - processors: { - followUpConversation: [new ConversationCompactorProcessor()], - preToolCall: [new ToolValidationProcessor()] - } -}); -``` +The framework provides two main ways to create agents: -## Agent Execution +### Using CodeboltAgent (Recommended) ```typescript -// Simple execution -const result = await agent.execute('Help me with my order #12345'); - -// Advanced execution with options -const result = await agent.execute('Complex query', { - maxIterations: 5, - includeHistory: true, - context: { userId: '123', sessionId: 'abc' } -}); +import { CodeboltAgent, createCodeboltAgent } from '@codebolt/agent/unified'; -console.log({ - success: result.success, - response: result.response, - iterations: result.iterations, - toolsUsed: result.toolResults?.length || 0 +// Using the factory function +const agent = createCodeboltAgent({ + systemPrompt: 'You are a helpful customer support representative.', + tools: [searchTool, ticketTool, emailTool] }); -``` - -## Agent as a Tool -Agents can be converted to tools for use by other agents or orchestrators: - -```typescript -// Convert agent to tool -const agentTool = agent.toTool(); - -// Use in another agent -const supervisorAgent = createAgent({ - name: 'Supervisor', - instructions: 'You coordinate multiple specialist agents.', - tools: [agentTool] +// Or using the class directly +const agent = new CodeboltAgent({ + instructions: 'You are a helpful customer support representative.', + tools: [searchTool, ticketTool, emailTool] }); - -// OpenAI-compatible tool format -const openAITool = agent.toOpenAITool(); ``` -## Managing Agent Tools +### Using Base Agent Class -```typescript -// Add tools dynamically -agent.addTool(newTool); +For more control, you can use the base `Agent` class: -// Remove tools -agent.removeTool('tool-id'); +```typescript +import { Agent } from '@codebolt/agent/unified'; +import { + ToolValidationModifier, + ConversationCompactorModifier +} from '@codebolt/agent/processor-pieces'; -// List tools -const tools = agent.listTools(); +const agent = new Agent({ + name: 'Customer Support Agent', + instructions: 'You are a helpful customer support representative.', + tools: [searchTool, ticketTool, emailTool], -// Clear all tools -agent.clearTools(); + // Custom processors + preToolCallProcessors: [new ToolValidationModifier()], + postToolCallProcessors: [new ConversationCompactorModifier()] +}); ``` -## Agent Workflows - -Agents can execute workflows: +## Agent Execution ```typescript -// Add workflow to agent -agent.addWorkflow('research-pipeline', researchWorkflow); - -// Execute workflow -const result = await agent.executeWorkflow('research-pipeline', { - topic: 'AI trends', - depth: 'comprehensive' +// Execute with a message +const result = await agent.execute({ + role: 'user', + content: 'Help me with my order #12345' }); -// List workflows -const workflows = agent.listWorkflows(); +console.log({ + success: result.success, + result: result.result, + error: result.error +}); ``` ## Agent Configuration Options @@ -114,113 +67,73 @@ const workflows = agent.listWorkflows(); ### Basic Configuration ```typescript -const agent = createAgent({ - name: 'My Agent', // Required: Agent name - instructions: 'You are helpful.', // Required: System instructions - description: 'Agent description', // Optional: Agent description - - // Execution limits - maxIterations: 10, // Max tool execution iterations - maxConversationLength: 50, // Max conversation history length - - // Logging and debugging - enableLogging: true, // Enable console logging - logLevel: 'info', // Log level: 'debug', 'info', 'warn', 'error' - - // Default processors - defaultProcessors: true, // Use sensible default processors -}); -``` - -### LLM Configuration +const agent = new CodeboltAgent({ + instructions: 'You are helpful.', // System instructions + tools: [myTool], // Array of tools -```typescript -const agent = createAgent({ - name: 'Configured Agent', - instructions: 'You are a helpful assistant.', - - llmConfig: { - model: 'gpt-4-turbo', // LLM model to use - temperature: 0.7, // Response creativity (0-1) - maxTokens: 4000, // Maximum response tokens - topP: 0.9, // Nucleus sampling parameter - frequencyPenalty: 0.0, // Frequency penalty (-2 to 2) - presencePenalty: 0.0, // Presence penalty (-2 to 2) - stopSequences: ['END'], // Stop generation at these sequences - - // Advanced options - stream: false, // Enable streaming responses - timeout: 30000, // Request timeout in milliseconds - retries: 3, // Number of retry attempts - } + // Optional: Custom processors + messageModifiers: [], + preInferenceProcessors: [], + postInferenceProcessors: [], + preToolCallProcessors: [], + postToolCallProcessors: [] }); ``` -### Processor Configuration +### Adding Processors ```typescript import { - ConversationCompactorProcessor, - ToolValidationProcessor, - TelemetryProcessor -} from '@codebolt/agent/unified'; + ConversationCompactorModifier, + ToolValidationModifier, + LoopDetectionModifier, + ChatCompressionModifier +} from '@codebolt/agent/processor-pieces'; -const agent = createAgent({ - name: 'Enhanced Agent', +const agent = new CodeboltAgent({ instructions: 'You are an enhanced agent.', - - processors: { - // Follow-up conversation processors - followUpConversation: [ - new ConversationCompactorProcessor({ - maxConversationLength: 30, - compactionThreshold: 0.8 - }), - new TelemetryProcessor({ - enableMetrics: true - }) - ], - - // Pre-tool call processors - preToolCall: [ - new ToolValidationProcessor({ - strictMode: true, - enableInputValidation: true - }) - ] - } -}); -``` + tools: [myTool], -## Advanced Agent Features + // Post-tool call processors + postToolCallProcessors: [ + new ConversationCompactorModifier({ + maxConversationLength: 30 + }) + ], -### Context Management + // Pre-tool call processors + preToolCallProcessors: [ + new ToolValidationModifier({ + strictMode: true + }) + ], -```typescript -// Execute with context -const result = await agent.execute('Query', { - context: { - userId: 'user123', - sessionId: 'session456', - preferences: { - language: 'en', - timezone: 'UTC' - }, - customData: { - department: 'support', - priority: 'high' - } - } + // Pre-inference processors + preInferenceProcessors: [ + new ChatCompressionModifier() + ], + + // Post-inference processors + postInferenceProcessors: [ + new LoopDetectionModifier({ + maxIterations: 10 + }) + ] }); +``` + +## Context Management -// Access context in tools +```typescript +// Tools can access context const contextAwareTool = createTool({ id: 'context-tool', - name: 'Context Aware Tool', + description: 'A context-aware tool', + inputSchema: z.object({ query: z.string() }), execute: async ({ input, context }) => { const userId = context?.userId; const preferences = context?.preferences; - + return { message: `Hello user ${userId}`, language: preferences?.language || 'en' @@ -229,58 +142,17 @@ const contextAwareTool = createTool({ }); ``` -### Error Handling +## Error Handling ```typescript -const result = await agent.execute('User message'); +const result = await agent.execute({ + role: 'user', + content: 'User message' +}); if (!result.success) { console.error('Agent failed:', result.error); - - // Check specific error types - if (result.error?.includes('timeout')) { - // Handle timeout - } else if (result.error?.includes('validation')) { - // Handle validation error - } } - -// Access detailed execution info -console.log({ - iterations: result.iterations, - conversationHistory: result.conversationHistory, - toolResults: result.toolResults, - executionTime: result.executionTime -}); -``` - -### Conversation History - -```typescript -// Get conversation history -const history = agent.getConversationHistory(); - -// Clear conversation history -agent.clearConversationHistory(); - -// Execute with history included -const result = await agent.execute('Follow-up question', { - includeHistory: true -}); - -// Manage conversation length -const agent = createAgent({ - name: 'History Manager', - maxConversationLength: 20, // Keep last 20 messages - processors: { - followUpConversation: [ - new ConversationCompactorProcessor({ - maxConversationLength: 20, - preserveRecentMessages: 5 // Always keep last 5 messages - }) - ] - } -}); ``` ## Agent Patterns @@ -289,181 +161,90 @@ const agent = createAgent({ ```typescript // Create domain-specific agents -const researchAgent = createAgent({ - name: 'Research Specialist', +const researchAgent = new CodeboltAgent({ instructions: 'You are an expert researcher with access to academic databases and web search.', - tools: [webSearchTool, academicSearchTool, citationTool], - llmConfig: { - temperature: 0.3, // Lower temperature for factual accuracy - maxTokens: 3000 - } + tools: [webSearchTool, academicSearchTool, citationTool] }); -const analysisAgent = createAgent({ - name: 'Data Analyst', - instructions: 'You are a data analysis expert specializing in statistical analysis and visualization.', - tools: [dataAnalysisTool, chartTool, statisticsTool], - llmConfig: { - temperature: 0.2, // Very low temperature for analytical work - maxTokens: 2500 - } +const analysisAgent = new CodeboltAgent({ + instructions: 'You are a data analysis expert specializing in statistical analysis.', + tools: [dataAnalysisTool, chartTool, statisticsTool] }); -const creativeAgent = createAgent({ - name: 'Creative Writer', - instructions: 'You are a creative writing expert specializing in storytelling and content creation.', - tools: [grammarTool, thesaurusTool, styleGuideTool], - llmConfig: { - temperature: 0.8, // Higher temperature for creativity - maxTokens: 4000 - } +const creativeAgent = new CodeboltAgent({ + instructions: 'You are a creative writing expert specializing in storytelling.', + tools: [grammarTool, thesaurusTool, styleGuideTool] }); ``` -### Supervisor Agents +### Agents with Message Modifiers ```typescript -// Create a supervisor that coordinates specialist agents -const supervisorAgent = createAgent({ - name: 'Task Supervisor', - instructions: `You are a supervisor that coordinates specialist agents: - - - For research tasks, use the research specialist - - For data analysis, use the data analyst - - For creative writing, use the creative writer - - For complex tasks, coordinate multiple specialists`, - - tools: [ - researchAgent.toTool(), - analysisAgent.toTool(), - creativeAgent.toTool() +import { + EnvironmentContextModifier, + DirectoryContextModifier, + ToolInjectionModifier +} from '@codebolt/agent/processor-pieces'; + +const enhancedAgent = new CodeboltAgent({ + instructions: 'You are a file system assistant.', + tools: [fileTools], + + messageModifiers: [ + new EnvironmentContextModifier(), + new DirectoryContextModifier(), + new ToolInjectionModifier() ] }); - -// Use supervisor for complex tasks -const result = await supervisorAgent.execute( - 'Research AI trends, analyze the data, and write a creative summary report' -); ``` -### Multi-Modal Agents +## Available Processors -```typescript -import { ImageAttachmentMessageModifier } from '@codebolt/agent/unified'; - -const multiModalAgent = createAgent({ - name: 'Multi-Modal Assistant', - instructions: 'You can process text, images, and other media types.', - - tools: [ - imageAnalysisTool, - textExtractionTool, - documentProcessingTool - ], - - processors: { - messageModifiers: [ - new ImageAttachmentMessageModifier({ - maxSize: 10 * 1024 * 1024, // 10MB - supportedFormats: ['jpg', 'png', 'pdf', 'docx'] - }) - ] - } -}); -``` +### Message Modifiers +Transform user messages into prompts: +- `EnvironmentContextModifier` - Add environment variables and system info +- `CoreSystemPromptModifier` - Handle core system prompt +- `DirectoryContextModifier` - Add working directory context +- `IdeContextModifier` - Add IDE integration context +- `AtFileProcessorModifier` - Process @file references +- `ArgumentProcessorModifier` - Process command arguments +- `MemoryImportModifier` - Import memory/context from previous sessions +- `ToolInjectionModifier` - Inject tool descriptions into prompts +- `ChatRecordingModifier` - Record chat for persistence +- `ChatHistoryMessageModifier` - Include conversation history -## Agent Monitoring and Debugging +### PreInference Processors +Run before LLM calls: +- `ChatCompressionModifier` - Compress chat history to save tokens -### Telemetry +### PostInference Processors +Run after LLM calls: +- `LoopDetectionModifier` - Detect and prevent infinite loops -```typescript -import { TelemetryProcessor } from '@codebolt/agent/unified'; - -const monitoredAgent = createAgent({ - name: 'Monitored Agent', - instructions: 'You are a monitored agent.', - - processors: { - followUpConversation: [ - new TelemetryProcessor({ - enableMetrics: true, - enableTracing: true, - metricsEndpoint: 'https://metrics.example.com', - - // Custom metrics - customMetrics: { - 'agent.execution.duration': (context) => context.executionTime, - 'agent.tool.usage': (context) => context.toolResults?.length || 0, - 'agent.conversation.length': (context) => context.conversationHistory?.length || 0 - } - }) - ] - } -}); -``` +### PreToolCall Processors +Validate and modify tool calls before execution: +- `ToolParameterModifier` - Transform tool parameters +- `ToolValidationModifier` - Validate tool inputs -### Logging +### PostToolCall Processors +Process tool results: +- `ConversationCompactorModifier` - Compact long conversations +- `ShellProcessorModifier` - Process shell command results + +## Debugging ```typescript -import { ChatRecordingProcessor } from '@codebolt/agent/unified'; +import { ChatRecordingModifier } from '@codebolt/agent/processor-pieces'; -const debugAgent = createAgent({ - name: 'Debug Agent', +const debugAgent = new CodeboltAgent({ instructions: 'You are a debug agent.', - enableLogging: true, - logLevel: 'debug', - - processors: { - followUpConversation: [ - new ChatRecordingProcessor({ - enableRecording: true, - storageLocation: './agent-logs', - includeMetadata: true, - - // Custom log format - logFormat: 'json', - includeTimestamps: true, - includeContext: true - }) - ] - } -}); -``` - -### Performance Monitoring + tools: [myTools], -```typescript -import { - TokenManagementProcessor, - ResponseValidationProcessor -} from '@codebolt/agent/unified'; - -const optimizedAgent = createAgent({ - name: 'Optimized Agent', - instructions: 'You are an optimized agent.', - - processors: { - followUpConversation: [ - new TokenManagementProcessor({ - maxTokens: 3000, - reserveTokens: 500, - enableCompression: true, - compressionRatio: 0.7 - }), - - new ResponseValidationProcessor({ - enableContentValidation: true, - enableFormatValidation: true, - maxResponseLength: 2000, - - customValidators: [ - (response) => ({ - isValid: response.length > 10, - reason: response.length <= 10 ? 'Response too short' : undefined - }) - ] - }) - ] - } + messageModifiers: [ + new ChatRecordingModifier({ + enabled: true, + outputPath: './agent-logs' + }) + ] }); ``` diff --git a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/3-tools.md b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/3-tools.md index 9655794d..625e2613 100644 --- a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/3-tools.md +++ b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/3-tools.md @@ -1,6 +1,6 @@ # Tools -Tools are the building blocks that provide specific functionality to agents. The framework provides a comprehensive tool creation system with type safety and validation. +Tools are the building blocks that provide specific functionality to agents. The framework provides a comprehensive tool creation system with type safety and validation using Zod schemas. ## Creating Tools @@ -12,7 +12,6 @@ import { z } from 'zod'; const basicTool = createTool({ id: 'text-processor', - name: 'Text Processor', description: 'Process and transform text', inputSchema: z.object({ text: z.string(), @@ -25,7 +24,7 @@ const basicTool = createTool({ }), execute: async ({ input, context }) => { let result = input.text; - + switch (input.operation) { case 'uppercase': result = input.text.toUpperCase(); @@ -37,7 +36,7 @@ const basicTool = createTool({ result = input.text.split('').reverse().join(''); break; } - + return { result, originalLength: input.text.length, @@ -47,304 +46,106 @@ const basicTool = createTool({ }); ``` -### Specialized Tool Creators +### Using the Tool Class -#### Text Tools ```typescript -// Text-based tool -const textTool = createTextTool({ - id: 'summarizer', - name: 'Text Summarizer', - description: 'Summarize long text content', - execute: (text) => `Summary: ${text.substring(0, 100)}...` -}); +import { Tool } from '@codebolt/agent/unified'; +import { z } from 'zod'; -// Advanced text processing -const advancedTextTool = createTextTool({ - id: 'advanced-text-processor', - name: 'Advanced Text Processor', - description: 'Advanced text processing with multiple operations', - operations: ['summarize', 'translate', 'sentiment', 'keywords'], - execute: async (text, operation) => { - switch (operation) { - case 'summarize': - return { summary: `Summary of: ${text.substring(0, 50)}...` }; - case 'translate': - return { translation: `Translated: ${text}` }; - case 'sentiment': - return { sentiment: 'positive', confidence: 0.85 }; - case 'keywords': - return { keywords: text.split(' ').slice(0, 5) }; - default: - return { result: text }; +const tool = new Tool({ + id: 'calculator', + description: 'Perform basic math operations', + inputSchema: z.object({ + a: z.number(), + b: z.number(), + operation: z.enum(['add', 'subtract', 'multiply', 'divide']) + }), + executionFunction: async ({ input }) => { + switch (input.operation) { + case 'add': return { result: input.a + input.b }; + case 'subtract': return { result: input.a - input.b }; + case 'multiply': return { result: input.a * input.b }; + case 'divide': return { result: input.a / input.b }; } } }); ``` -#### File Tools -```typescript -// File operation tool -const fileTool = createFileTool({ - id: 'file-reader', - name: 'File Reader', - description: 'Read file contents', - operation: 'read', - execute: async (filePath) => { - // File reading logic - return await fs.readFile(filePath, 'utf-8'); - } -}); - -// Multiple file operations -const fileManagerTool = createFileTool({ - id: 'file-manager', - name: 'File Manager', - description: 'Comprehensive file management', - operations: ['read', 'write', 'delete', 'copy', 'move'], - execute: async (operation, filePath, content) => { - switch (operation) { - case 'read': - return await fs.readFile(filePath, 'utf-8'); - case 'write': - await fs.writeFile(filePath, content); - return { success: true, message: 'File written successfully' }; - case 'delete': - await fs.unlink(filePath); - return { success: true, message: 'File deleted successfully' }; - // ... other operations - } - } -}); -``` +## Tool Configuration -#### HTTP Tools -```typescript -// HTTP request tool -const httpTool = createHttpTool({ - id: 'api-client', - name: 'API Client', - description: 'Make HTTP requests', - method: 'GET', - baseUrl: 'https://api.example.com', - execute: async (endpoint, options) => { - // HTTP request logic - return await fetch(`${baseUrl}${endpoint}`, options); - } -}); +### Required Fields -// REST API client -const restApiTool = createHttpTool({ - id: 'rest-client', - name: 'REST API Client', - description: 'Full REST API client with all HTTP methods', - methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], - baseUrl: 'https://api.example.com', - headers: { - 'Content-Type': 'application/json', - 'Authorization': 'Bearer ${API_TOKEN}' - }, - execute: async (method, endpoint, data, headers) => { - const response = await fetch(`${baseUrl}${endpoint}`, { - method, - headers: { ...defaultHeaders, ...headers }, - body: data ? JSON.stringify(data) : undefined - }); - - return { - status: response.status, - statusText: response.statusText, - data: await response.json(), - headers: Object.fromEntries(response.headers.entries()) - }; - } -}); -``` +- `id` - Unique identifier for the tool +- `description` - What the tool does (shown to the LLM) +- `inputSchema` - Zod schema defining expected inputs +- `execute` or `executionFunction` - The function to execute -#### Validation Tools -```typescript -// Validation tool -const validationTool = createValidationTool({ - id: 'email-validator', - name: 'Email Validator', - description: 'Validate email addresses', - schema: z.string().email(), - execute: (email) => ({ isValid: true, email }) -}); +### Optional Fields -// Complex validation -const dataValidatorTool = createValidationTool({ - id: 'data-validator', - name: 'Data Validator', - description: 'Validate complex data structures', - schemas: { - user: z.object({ - id: z.string().uuid(), - email: z.string().email(), - age: z.number().min(0).max(120), - preferences: z.object({ - theme: z.enum(['light', 'dark']), - notifications: z.boolean() - }) - }), - product: z.object({ - name: z.string().min(1), - price: z.number().positive(), - category: z.string(), - inStock: z.boolean() - }) - }, - execute: (data, schemaName) => { - const schema = schemas[schemaName]; - if (!schema) { - return { isValid: false, error: 'Unknown schema' }; - } - - try { - const validated = schema.parse(data); - return { isValid: true, data: validated }; - } catch (error) { - return { isValid: false, error: error.message }; - } - } -}); -``` - -#### Transform Tools -```typescript -// Transform tool -const transformTool = createTransformTool({ - id: 'data-transformer', - name: 'Data Transformer', - description: 'Transform data structures', - inputSchema: z.object({ data: z.array(z.unknown()) }), - outputSchema: z.object({ transformed: z.array(z.unknown()) }), - execute: (data) => ({ transformed: data.map(item => ({ ...item, processed: true })) }) -}); - -// Advanced data transformation -const advancedTransformTool = createTransformTool({ - id: 'advanced-transformer', - name: 'Advanced Data Transformer', - description: 'Advanced data transformation with multiple operations', - transformations: { - normalize: (data) => data.map(item => ({ ...item, normalized: true })), - aggregate: (data) => ({ count: data.length, items: data }), - filter: (data, condition) => data.filter(condition), - sort: (data, key) => data.sort((a, b) => a[key] - b[key]), - group: (data, key) => data.reduce((groups, item) => { - const group = item[key]; - groups[group] = groups[group] || []; - groups[group].push(item); - return groups; - }, {}) - }, - execute: (data, operation, ...args) => { - const transform = transformations[operation]; - if (!transform) { - throw new Error(`Unknown transformation: ${operation}`); - } - return { result: transform(data, ...args) }; - } -}); -``` +- `outputSchema` - Zod schema for output validation ## Tool Execution -```typescript -// Execute tool directly -const result = await executeTool(tool, { text: 'Hello World', operation: 'uppercase' }); - -// Execute with context -const result = await executeTool(tool, input, codeboltAPI); - -// Execute with error handling -try { - const result = await executeTool(tool, input); - console.log('Tool result:', result); -} catch (error) { - console.error('Tool execution failed:', error); -} -``` - -## Tool Conversion +Tools can be executed directly: ```typescript -// Convert to OpenAI format -const openAITools = toolsToOpenAIFormat([tool1, tool2, tool3]); - -// Use in agent -const agent = createAgent({ - name: 'Tool User', - tools: openAITools -}); - -// Convert single tool -const openAITool = tool.toOpenAITool(); +// Direct execution +const result = await tool.execute( + { text: 'Hello World', operation: 'uppercase' }, + context // optional context +); + +console.log(result); +// { success: true, result: { result: 'HELLO WORLD', ... } } +// or +// { success: false, error: 'Error message' } ``` -## Built-in Tools +## OpenAI Format Conversion -The framework includes several built-in tools from the processor-pieces library: +Tools can be converted to OpenAI function format for use with LLM APIs: -### File Tools ```typescript -import { - FileReadTool, - FileWriteTool, - FileDeleteTool, - FileMoveTool, - FileCopyTool -} from '@codebolt/agent/unified'; - -// Use built-in file tools -const agent = createAgent({ - name: 'File Manager Agent', - instructions: 'You help users manage files.', - tools: [ - new FileReadTool(), - new FileWriteTool(), - new FileDeleteTool(), - new FileMoveTool(), - new FileCopyTool() - ] -}); +// Convert a single tool +const openAITool = tool.toOpenAITool(); -// Example usage -const result = await agent.execute('Read the contents of config.json'); +console.log(openAITool); +// { +// type: 'function', +// function: { +// name: 'calculator', +// description: 'Perform basic math operations', +// parameters: { ... JSON Schema ... } +// } +// } ``` -### Web Tools -```typescript -// Web scraping and URL handling -const webAgent = createAgent({ - name: 'Web Assistant', - instructions: 'You help users with web-related tasks.', - processors: { - messageModifiers: [ - new HandleUrlMessageModifier({ - extractContent: true, - includeMetadata: true, - maxContentLength: 10000 - }) - ] - } -}); +## Supported Schema Types -// The agent can now automatically handle URLs in messages -const result = await webAgent.execute('Summarize the content from https://example.com/article'); -``` +The tool system supports the following Zod types for automatic JSON Schema conversion: + +- `z.string()` - String values +- `z.number()` - Numeric values +- `z.boolean()` - Boolean values +- `z.array()` - Arrays +- `z.object()` - Objects with nested properties +- `z.enum()` - Enumerated values +- `z.literal()` - Literal values +- `z.union()` - Union types +- `z.optional()` - Optional fields +- `z.nullable()` - Nullable fields ## Advanced Tool Features ### Tool Chaining +Create tools that work together: + ```typescript -// Create tools that work together const dataFetchTool = createTool({ id: 'data-fetcher', - name: 'Data Fetcher', description: 'Fetch data from API', + inputSchema: z.object({ url: z.string() }), execute: async ({ input }) => { const response = await fetch(input.url); return await response.json(); @@ -353,8 +154,10 @@ const dataFetchTool = createTool({ const dataProcessorTool = createTool({ id: 'data-processor', - name: 'Data Processor', description: 'Process fetched data', + inputSchema: z.object({ + data: z.array(z.unknown()) + }), execute: async ({ input }) => { return { processed: input.data.map(item => ({ @@ -365,61 +168,18 @@ const dataProcessorTool = createTool({ } }); -const dataVisualizerTool = createTool({ - id: 'data-visualizer', - name: 'Data Visualizer', - description: 'Create visualizations from processed data', - execute: async ({ input }) => { - return { - chart: `Chart for ${input.processed.length} items`, - type: 'bar', - data: input.processed - }; - } -}); - // Agent can chain these tools automatically -const dataAgent = createAgent({ - name: 'Data Analysis Agent', - instructions: 'You fetch, process, and visualize data.', - tools: [dataFetchTool, dataProcessorTool, dataVisualizerTool] -}); -``` - -### Conditional Tools - -```typescript -// Tools with conditional execution -const conditionalTool = createTool({ - id: 'conditional-processor', - name: 'Conditional Processor', - description: 'Process data based on conditions', - inputSchema: z.object({ - data: z.unknown(), - condition: z.string(), - trueAction: z.string(), - falseAction: z.string() - }), - execute: async ({ input }) => { - // Evaluate condition (simplified) - const conditionMet = eval(input.condition); - - if (conditionMet) { - return { action: input.trueAction, result: 'Condition met' }; - } else { - return { action: input.falseAction, result: 'Condition not met' }; - } - } +const dataAgent = new CodeboltAgent({ + instructions: 'You fetch and process data.', + tools: [dataFetchTool, dataProcessorTool] }); ``` ### Async Tools ```typescript -// Long-running async tool const longRunningTool = createTool({ id: 'long-runner', - name: 'Long Running Process', description: 'Execute long-running processes', inputSchema: z.object({ task: z.string(), @@ -428,7 +188,7 @@ const longRunningTool = createTool({ execute: async ({ input }) => { // Simulate long-running process await new Promise(resolve => setTimeout(resolve, input.duration)); - + return { task: input.task, completed: true, @@ -437,44 +197,13 @@ const longRunningTool = createTool({ }; } }); - -// Tool with progress reporting -const progressTool = createTool({ - id: 'progress-reporter', - name: 'Progress Reporter', - description: 'Tool that reports progress during execution', - execute: async ({ input, context }) => { - const steps = 10; - const results = []; - - for (let i = 0; i < steps; i++) { - // Simulate work - await new Promise(resolve => setTimeout(resolve, 100)); - - // Report progress (if context supports it) - if (context?.reportProgress) { - context.reportProgress({ - step: i + 1, - total: steps, - percentage: ((i + 1) / steps) * 100 - }); - } - - results.push(`Step ${i + 1} completed`); - } - - return { results, completed: true }; - } -}); ``` ### Error Handling in Tools ```typescript -// Tool with comprehensive error handling const robustTool = createTool({ id: 'robust-tool', - name: 'Robust Tool', description: 'Tool with comprehensive error handling', inputSchema: z.object({ operation: z.string(), @@ -486,20 +215,17 @@ const robustTool = createTool({ if (!input.operation) { throw new Error('Operation is required'); } - + // Perform operation const result = await performOperation(input.operation, input.data); - + return { success: true, result, operation: input.operation }; - + } catch (error) { - // Log error for debugging - console.error('Tool execution failed:', error); - // Return structured error response return { success: false, @@ -510,63 +236,26 @@ const robustTool = createTool({ } } }); - -async function performOperation(operation: string, data: unknown) { - switch (operation) { - case 'process': - return { processed: data }; - case 'validate': - return { valid: true, data }; - default: - throw new Error(`Unknown operation: ${operation}`); - } -} ``` -### Tool Middleware +### Context-Aware Tools ```typescript -// Tool with middleware-like functionality -const middlewareTool = createTool({ - id: 'middleware-tool', - name: 'Middleware Tool', - description: 'Tool with pre/post processing', +const contextAwareTool = createTool({ + id: 'context-tool', + description: 'Tool that uses context', + inputSchema: z.object({ query: z.string() }), execute: async ({ input, context }) => { - // Pre-processing - const startTime = Date.now(); - console.log('Tool execution started:', input); - - try { - // Main processing - const result = await mainProcess(input); - - // Post-processing - const endTime = Date.now(); - const duration = endTime - startTime; - - return { - ...result, - metadata: { - executionTime: duration, - timestamp: new Date().toISOString(), - success: true - } - }; - - } catch (error) { - // Error post-processing - const endTime = Date.now(); - const duration = endTime - startTime; - - return { - error: error.message, - metadata: { - executionTime: duration, - timestamp: new Date().toISOString(), - success: false - } - }; - } + // Access context passed from agent + const userId = context?.userId; + const sessionId = context?.sessionId; + + return { + query: input.query, + userId, + sessionId, + timestamp: Date.now() + }; } }); ``` @@ -574,72 +263,66 @@ const middlewareTool = createTool({ ## Tool Testing ```typescript -// Test tools in isolation +import { createTool } from '@codebolt/agent/unified'; +import { z } from 'zod'; + describe('Text Processor Tool', () => { const tool = createTool({ id: 'test-tool', - name: 'Test Tool', + description: 'Test tool', inputSchema: z.object({ text: z.string() }), execute: async ({ input }) => ({ result: input.text.toUpperCase() }) }); - + it('should convert text to uppercase', async () => { - const result = await executeTool(tool, { text: 'hello world' }); - expect(result.result).toBe('HELLO WORLD'); - }); - - it('should handle empty input', async () => { - const result = await executeTool(tool, { text: '' }); - expect(result.result).toBe(''); + const result = await tool.execute({ text: 'hello world' }, {}); + expect(result.success).toBe(true); + expect(result.result.result).toBe('HELLO WORLD'); }); -}); -// Integration testing with agents -describe('Agent with Tools', () => { - const agent = createAgent({ - name: 'Test Agent', - instructions: 'You are a test agent.', - tools: [textProcessorTool] - }); - - it('should use tools correctly', async () => { - const result = await agent.execute('Convert "hello world" to uppercase'); + it('should handle empty input', async () => { + const result = await tool.execute({ text: '' }, {}); expect(result.success).toBe(true); - expect(result.response).toContain('HELLO WORLD'); + expect(result.result.result).toBe(''); }); }); ``` ## Tool Performance Optimization +### Caching Results + ```typescript -// Cached tool results +const cache = new Map(); + const cachedTool = createTool({ id: 'cached-tool', - name: 'Cached Tool', description: 'Tool with result caching', + inputSchema: z.object({ query: z.string() }), execute: async ({ input }) => { const cacheKey = JSON.stringify(input); - + // Check cache if (cache.has(cacheKey)) { return { ...cache.get(cacheKey), fromCache: true }; } - + // Perform expensive operation const result = await expensiveOperation(input); - + // Cache result cache.set(cacheKey, result); - + return { ...result, fromCache: false }; } }); +``` -// Batched tool execution +### Batched Execution + +```typescript const batchTool = createTool({ id: 'batch-tool', - name: 'Batch Tool', description: 'Tool that processes items in batches', inputSchema: z.object({ items: z.array(z.unknown()), @@ -648,7 +331,7 @@ const batchTool = createTool({ execute: async ({ input }) => { const { items, batchSize } = input; const results = []; - + for (let i = 0; i < items.length; i += batchSize) { const batch = items.slice(i, i + batchSize); const batchResults = await Promise.all( @@ -656,8 +339,22 @@ const batchTool = createTool({ ); results.push(...batchResults); } - + return { results, totalProcessed: items.length }; } }); ``` + +## Best Practices + +1. **Clear Descriptions**: Write clear, concise descriptions that help the LLM understand when to use the tool. + +2. **Strict Input Schemas**: Use specific Zod schemas to validate inputs and catch errors early. + +3. **Meaningful IDs**: Use descriptive, unique IDs that indicate the tool's purpose. + +4. **Error Handling**: Always handle errors gracefully and return meaningful error messages. + +5. **Type Safety**: Leverage TypeScript and Zod for full type safety. + +6. **Single Responsibility**: Each tool should do one thing well. diff --git a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/4-processors.md b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/4-processors.md index b21fa0f5..a0d952ef 100644 --- a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/4-processors.md +++ b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/4-processors.md @@ -1,842 +1,407 @@ # Processors -Processors are extensible components that customize and enhance the behavior of agents, workflows, and orchestrators. The framework includes a comprehensive set of built-in processors from the `@processor-pieces` library. +Processors are extensible components that customize and enhance the behavior of agents at different stages of execution. They are imported from `@codebolt/agent/processor-pieces`. ## Processor Categories -### 1. Message Processors -Modify and enhance messages before they're processed by agents. +The framework organizes processors into five categories based on when they execute: -#### HandleUrlMessageModifier -Automatically extracts content from URLs in messages. +1. **Message Modifiers** - Transform user messages before processing +2. **PreInference Processors** - Run before LLM calls +3. **PostInference Processors** - Run after LLM calls, before tool execution +4. **PreToolCall Processors** - Validate/modify tool calls before execution +5. **PostToolCall Processors** - Process tool results and update prompts -```typescript -import { HandleUrlMessageModifier } from '@codebolt/agent/unified'; - -const urlModifier = new HandleUrlMessageModifier({ - extractContent: true, // Extract webpage content - includeMetadata: true, // Include page metadata - maxContentLength: 10000, // Max content length to extract - timeout: 30000, // Request timeout - userAgent: 'CodeboltAgent', // Custom user agent - followRedirects: true // Follow HTTP redirects -}); +## Message Modifiers -const agent = createAgent({ - name: 'Web Assistant', - instructions: 'You can process web content from URLs.', - processors: { - messageModifiers: [urlModifier] - } -}); +Transform user messages into prompts. These run during the initial prompt generation phase. -// Usage: Agent automatically processes URLs -await agent.execute('Summarize the content from https://example.com/article'); -``` +### EnvironmentContextModifier -#### BaseContextMessageModifier -Adds contextual information to messages. +Adds environment context (system info, environment variables) to messages. ```typescript -import { BaseContextMessageModifier } from '@codebolt/agent/unified'; - -const contextModifier = new BaseContextMessageModifier({ - includeTimestamp: true, // Add current timestamp - includeUserInfo: true, // Include user information - includeSessionInfo: true, // Include session details - customContext: { // Custom context data - environment: 'production', - version: '1.0.0' - } -}); +import { EnvironmentContextModifier } from '@codebolt/agent/processor-pieces'; -const agent = createAgent({ - name: 'Context-Aware Agent', - processors: { - messageModifiers: [contextModifier] - } +const modifier = new EnvironmentContextModifier({ + // Configuration options }); ``` -#### WorkingDirectoryMessageModifier -Adds working directory context to messages. +### CoreSystemPromptModifier + +Handles core system prompt configuration. ```typescript -import { WorkingDirectoryMessageModifier } from '@codebolt/agent/unified'; - -const workdirModifier = new WorkingDirectoryMessageModifier({ - includePath: true, // Include current working directory - includeFileList: false, // Include file listing (optional) - maxFiles: 50, // Max files to list - excludePatterns: [ // Patterns to exclude - 'node_modules', - '.git', - '*.log' - ] -}); +import { CoreSystemPromptModifier } from '@codebolt/agent/processor-pieces'; -const agent = createAgent({ - name: 'File System Agent', - instructions: 'You help users with file system operations.', - processors: { - messageModifiers: [workdirModifier] - } +const modifier = new CoreSystemPromptModifier({ + // Configuration options }); ``` -#### BaseSystemInstructionMessageModifier -Enhances system instructions with additional context. +### DirectoryContextModifier + +Adds working directory context to messages. ```typescript -import { BaseSystemInstructionMessageModifier } from '@codebolt/agent/unified'; - -const systemModifier = new BaseSystemInstructionMessageModifier({ - instructions: `Additional system context: - - Current date: ${new Date().toISOString()} - - Available tools: file operations, web search, calculations - - Response format: Always provide clear, actionable responses`, - - appendToExisting: true, // Append to existing instructions - priority: 'high' // Instruction priority +import { DirectoryContextModifier } from '@codebolt/agent/processor-pieces'; + +const modifier = new DirectoryContextModifier({ + // Configuration options }); ``` -#### ImageAttachmentMessageModifier -Processes image attachments in messages. +### IdeContextModifier -```typescript -import { ImageAttachmentMessageModifier } from '@codebolt/agent/unified'; +Adds IDE integration context (open files, workspace info). -const imageModifier = new ImageAttachmentMessageModifier({ - maxSize: 10 * 1024 * 1024, // 10MB max file size - supportedFormats: [ // Supported image formats - 'jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp' - ], - enableOCR: true, // Enable text extraction from images - enableAnalysis: true, // Enable image analysis - compressionQuality: 0.8 // Image compression quality -}); +```typescript +import { IdeContextModifier } from '@codebolt/agent/processor-pieces'; -const multiModalAgent = createAgent({ - name: 'Multi-Modal Agent', - instructions: 'You can analyze images and extract text from them.', - processors: { - messageModifiers: [imageModifier] - } +const modifier = new IdeContextModifier({ + // Configuration options }); ``` -#### AddToolsListMessageModifier -Adds available tools list to messages. +### AtFileProcessorModifier + +Processes @file references in messages, expanding them to file contents. ```typescript -import { AddToolsListMessageModifier } from '@codebolt/agent/unified'; - -const toolsModifier = new AddToolsListMessageModifier({ - includeDescriptions: true, // Include tool descriptions - formatAsMarkdown: true, // Format as markdown - groupByCategory: true, // Group tools by category - showOnlyRelevant: false, // Show only relevant tools - maxToolsToShow: 20 // Maximum tools to display -}); +import { AtFileProcessorModifier } from '@codebolt/agent/processor-pieces'; -const agent = createAgent({ - name: 'Tool-Aware Agent', - tools: [calculatorTool, weatherTool, fileReadTool], - processors: { - messageModifiers: [toolsModifier] - } +const modifier = new AtFileProcessorModifier({ + // Configuration options }); ``` -### 2. Conversation Management Processors -Handle conversation flow, compression, and continuity. +### ArgumentProcessorModifier -#### ConversationCompactorProcessor -Compacts long conversations to stay within token limits. +Processes command-line style arguments in messages. ```typescript -import { ConversationCompactorProcessor } from '@codebolt/agent/unified'; - -const compactorProcessor = new ConversationCompactorProcessor({ - maxConversationLength: 50, // Max messages to keep - compactionThreshold: 0.8, // When to trigger compaction (80% of max) - preserveRecentMessages: 10, // Always keep last 10 messages - enableSummarization: true, // Summarize removed messages - enableSmartRemoval: true, // Intelligently remove less important messages - - // Advanced options - priorityMessages: [ // Message types to prioritize - 'system', 'error', 'important' - ], - compressionRatio: 0.6, // Target compression ratio - semanticSimilarityThreshold: 0.8 // Remove similar messages -}); +import { ArgumentProcessorModifier } from '@codebolt/agent/processor-pieces'; -const agent = createAgent({ - name: 'Long Conversation Agent', - maxConversationLength: 100, - processors: { - followUpConversation: [compactorProcessor] - } +const modifier = new ArgumentProcessorModifier({ + // Configuration options }); ``` -#### FollowUpConversationProcessor -Enhances follow-up conversations with context and suggestions. +### MemoryImportModifier + +Imports memory/context from previous sessions. ```typescript -import { FollowUpConversationProcessor } from '@codebolt/agent/unified'; - -const followUpProcessor = new FollowUpConversationProcessor({ - enhanceToolResults: true, // Enhance tool result presentation - addGuidedPrompts: true, // Add suggested follow-up questions - includeContextualHints: true, // Include contextual hints - maxSuggestions: 3, // Max follow-up suggestions - - // Customization options - suggestionTemplates: [ // Custom suggestion templates - "Would you like me to {action} the {object}?", - "Should I also {action}?", - "Do you need help with {related_topic}?" - ], - contextWindow: 5, // Messages to consider for context - enablePersonalization: true // Personalize based on user history -}); +import { MemoryImportModifier } from '@codebolt/agent/processor-pieces'; -const agent = createAgent({ - name: 'Helpful Assistant', - processors: { - followUpConversation: [followUpProcessor] - } +const modifier = new MemoryImportModifier({ + // Configuration options }); ``` -#### ConversationContinuityProcessor -Maintains conversation continuity and resolves references. +### ToolInjectionModifier + +Injects tool descriptions into prompts. ```typescript -import { ConversationContinuityProcessor } from '@codebolt/agent/unified'; - -const continuityProcessor = new ConversationContinuityProcessor({ - enableContextLinking: true, // Link related conversation parts - enableReferenceResolution: true, // Resolve pronouns and references - enableGapDetection: true, // Detect conversation gaps - maxContextWindow: 20, // Max messages for context - - // Reference resolution - pronounResolution: true, // Resolve "it", "this", "that" - entityTracking: true, // Track mentioned entities - topicTracking: true, // Track conversation topics - - // Gap detection - timeGapThreshold: 300000, // 5 minutes gap detection - topicChangeThreshold: 0.7 // Topic change detection threshold -}); +import { ToolInjectionModifier } from '@codebolt/agent/processor-pieces'; -const agent = createAgent({ - name: 'Continuous Conversation Agent', - processors: { - followUpConversation: [continuityProcessor] - } +const modifier = new ToolInjectionModifier({ + // Configuration options }); ``` -#### ChatCompressionProcessor -Compresses chat history using various strategies. +### ChatRecordingModifier + +Records chat history for persistence and debugging. ```typescript -import { ChatCompressionProcessor } from '@codebolt/agent/unified'; - -const compressionProcessor = new ChatCompressionProcessor({ - compressionRatio: 0.6, // Target compression ratio - preserveImportantMessages: true, // Keep important messages - useSemanticCompression: true, // Use semantic similarity - - // Compression strategies - strategies: [ - 'remove_duplicates', // Remove duplicate messages - 'summarize_blocks', // Summarize message blocks - 'remove_filler', // Remove filler words/messages - 'merge_similar' // Merge semantically similar messages - ], - - // Advanced options - importanceThreshold: 0.7, // Importance score threshold - semanticSimilarityThreshold: 0.8, // Semantic similarity threshold - maxCompressionPasses: 3 // Max compression iterations +import { ChatRecordingModifier } from '@codebolt/agent/processor-pieces'; + +const modifier = new ChatRecordingModifier({ + enabled: true, + outputPath: './chat-logs' }); ``` -### 3. Tool Execution Processors -Enhance and control tool execution behavior. +### ChatHistoryMessageModifier -#### LocalToolInterceptorProcessor -Intercepts and handles custom local tools. +Includes conversation history in messages. ```typescript -import { LocalToolInterceptorProcessor } from '@codebolt/agent/unified'; - -const interceptorProcessor = new LocalToolInterceptorProcessor({ - localTools: new Map([ - ['calculator', { - name: 'Local Calculator', - description: 'Local math operations', - execute: async (input) => { - // Custom local implementation - return { result: eval(input.expression) }; - } - }], - ['file-reader', { - name: 'Local File Reader', - description: 'Read files locally', - execute: async (input) => { - const fs = require('fs').promises; - return { content: await fs.readFile(input.path, 'utf-8') }; - } - }] - ]), - - enableInterception: true, // Enable tool interception - fallbackToOriginal: true, // Fallback to original if local fails - interceptAll: false, // Intercept all tools (not recommended) - - // Interception rules - interceptRules: [ - { - toolName: 'calculator', - condition: (input) => input.expression.length < 100, - priority: 'high' - } - ] -}); +import { ChatHistoryMessageModifier } from '@codebolt/agent/processor-pieces'; -const agent = createAgent({ - name: 'Local Tool Agent', - processors: { - preToolCall: [interceptorProcessor] - } +const modifier = new ChatHistoryMessageModifier({ + // Configuration options }); ``` -#### ToolValidationProcessor -Validates tool inputs and outputs. +## PreInference Processors -```typescript -import { ToolValidationProcessor } from '@codebolt/agent/unified'; - -const validationProcessor = new ToolValidationProcessor({ - enableInputValidation: true, // Validate tool inputs - enableOutputValidation: true, // Validate tool outputs - strictMode: false, // Strict validation mode - - // Custom validators - customValidators: new Map([ - ['email-tool', { - validateInput: (input) => ({ - isValid: /\S+@\S+\.\S+/.test(input.email), - error: 'Invalid email format' - }), - validateOutput: (output) => ({ - isValid: output.success !== undefined, - error: 'Missing success field' - }) - }] - ]), - - // Validation rules - globalRules: [ - { - rule: 'no_empty_strings', - message: 'String inputs cannot be empty' - }, - { - rule: 'max_input_size', - limit: 10000, - message: 'Input too large' - } - ] -}); +Run before the LLM is called. Used for optimizing prompts. -const agent = createAgent({ - name: 'Validated Agent', - processors: { - preToolCall: [validationProcessor] - } -}); -``` +### ChatCompressionModifier -#### ToolParameterModifierProcessor -Modifies tool parameters before execution. +Compresses chat history to reduce token usage. ```typescript -import { ToolParameterModifierProcessor } from '@codebolt/agent/unified'; - -const parameterProcessor = new ToolParameterModifierProcessor({ - enableParameterTransformation: true, // Enable parameter transformation - enableParameterEnrichment: true, // Enable parameter enrichment - - // Parameter transformations - transformations: [ - { - toolName: 'search-tool', - parameterName: 'query', - transformation: (value) => `Enhanced: ${value}`, - condition: (value) => value.length < 50 - }, - { - toolName: 'file-tool', - parameterName: 'path', - transformation: (value) => path.resolve(value), - description: 'Convert to absolute path' - } - ], - - // Parameter enrichment - enrichments: [ - { - toolName: 'api-tool', - enrichWith: { - timestamp: () => new Date().toISOString(), - userAgent: 'CodeboltAgent/1.0' - } - } - ], - - // Global transformations - globalTransformations: { - trim_strings: (value) => typeof value === 'string' ? value.trim() : value, - normalize_paths: (value, paramName) => - paramName.includes('path') ? path.normalize(value) : value - } +import { ChatCompressionModifier } from '@codebolt/agent/processor-pieces'; + +const modifier = new ChatCompressionModifier({ + // Configuration options }); ``` -### 4. System Monitoring Processors -Monitor performance, detect issues, and collect telemetry. +## PostInference Processors + +Run after the LLM responds but before tool execution. Used for response validation and loop detection. + +### LoopDetectionModifier -#### LoopDetectionProcessor Detects and prevents infinite loops in agent execution. ```typescript -import { LoopDetectionProcessor } from '@codebolt/agent/unified'; - -const loopDetector = new LoopDetectionProcessor({ - maxIterations: 10, // Max allowed iterations - detectionWindow: 5, // Window size for loop detection - similarityThreshold: 0.8, // Similarity threshold for loop detection - - // Detection strategies - enableTextSimilarity: true, // Detect text similarity loops - enableActionSimilarity: true, // Detect action pattern loops - enableOutputSimilarity: true, // Detect output similarity loops - - // Response strategies - onLoopDetected: 'stop', // 'stop', 'warn', 'modify' - loopBreakingStrategies: [ - 'add_randomness', // Add randomness to break loops - 'modify_prompt', // Modify the prompt - 'change_temperature' // Adjust LLM temperature - ] -}); +import { LoopDetectionModifier } from '@codebolt/agent/processor-pieces'; -const agent = createAgent({ - name: 'Loop-Safe Agent', - processors: { - followUpConversation: [loopDetector] - } +const modifier = new LoopDetectionModifier({ + maxIterations: 10, + // Additional configuration options }); ``` -#### AdvancedLoopDetectionProcessor -Advanced loop detection with semantic analysis. +## PreToolCall Processors -```typescript -import { AdvancedLoopDetectionProcessor } from '@codebolt/agent/unified'; - -const advancedLoopDetector = new AdvancedLoopDetectionProcessor({ - enableSemanticAnalysis: true, // Use semantic similarity - enablePatternDetection: true, // Detect behavioral patterns - maxLoopLength: 5, // Max loop sequence length - confidenceThreshold: 0.9, // Detection confidence threshold - - // Semantic analysis - embeddingModel: 'text-embedding-ada-002', - semanticThreshold: 0.85, // Semantic similarity threshold - - // Pattern detection - patternTypes: [ - 'repetitive_actions', // Same actions repeated - 'circular_reasoning', // Circular logic patterns - 'oscillating_behavior' // Back-and-forth behavior - ], - - // Advanced features - learningEnabled: true, // Learn from detected loops - adaptiveThresholds: true, // Adapt thresholds over time - contextAware: true // Consider conversation context -}); -``` +Run before tool calls are executed. Used for validation and parameter modification. + +### ToolParameterModifier -#### TokenManagementProcessor -Manages token usage and implements compression strategies. +Modifies tool parameters before execution. ```typescript -import { TokenManagementProcessor } from '@codebolt/agent/unified'; - -const tokenManager = new TokenManagementProcessor({ - maxTokens: 4000, // Max tokens allowed - reserveTokens: 500, // Reserve tokens for response - enableCompression: true, // Enable automatic compression - compressionRatio: 0.7, // Target compression ratio - - // Token counting - tokenCounter: 'tiktoken', // Token counting method - model: 'gpt-4', // Model for accurate counting - - // Compression strategies - compressionStrategies: [ - 'remove_redundancy', // Remove redundant content - 'summarize_history', // Summarize old messages - 'truncate_content', // Truncate long content - 'prioritize_recent' // Prioritize recent messages - ], - - // Monitoring - enableTokenTracking: true, // Track token usage - warningThreshold: 0.8, // Warn at 80% usage - alertCallback: (usage) => { - console.log(`Token usage: ${usage.used}/${usage.max}`); - } +import { ToolParameterModifier } from '@codebolt/agent/processor-pieces'; + +const modifier = new ToolParameterModifier({ + // Configuration options }); ``` -#### ResponseValidationProcessor -Validates agent responses for quality and safety. +### ToolValidationModifier + +Validates tool calls before execution. ```typescript -import { ResponseValidationProcessor } from '@codebolt/agent/unified'; - -const responseValidator = new ResponseValidationProcessor({ - enableContentValidation: true, // Validate response content - enableFormatValidation: true, // Validate response format - enableSafetyCheck: true, // Check for unsafe content - - // Content validation - minResponseLength: 10, // Minimum response length - maxResponseLength: 2000, // Maximum response length - requiredElements: [ // Required response elements - 'greeting', 'answer', 'conclusion' - ], - - // Format validation - allowedFormats: [ // Allowed response formats - 'text', 'markdown', 'json' - ], - validateMarkdown: true, // Validate markdown syntax - validateJSON: true, // Validate JSON syntax - - // Safety checks - safetyFilters: [ - 'profanity', // Filter profanity - 'harmful_content', // Filter harmful content - 'personal_info' // Filter personal information - ], - - // Custom validators - customValidators: [ - (response) => ({ - isValid: response.length > 10, - reason: response.length <= 10 ? 'Response too short' : undefined - }), - (response) => ({ - isValid: !response.includes('ERROR'), - reason: response.includes('ERROR') ? 'Contains error message' : undefined - }) - ] +import { ToolValidationModifier } from '@codebolt/agent/processor-pieces'; + +const modifier = new ToolValidationModifier({ + strictMode: true, + // Additional configuration options }); ``` -#### TelemetryProcessor -Collects telemetry data and metrics. +## PostToolCall Processors -```typescript -import { TelemetryProcessor } from '@codebolt/agent/unified'; - -const telemetryProcessor = new TelemetryProcessor({ - enableMetrics: true, // Enable metrics collection - enableTracing: true, // Enable execution tracing - enableLogging: true, // Enable detailed logging - - // Metrics configuration - metricsEndpoint: 'https://metrics.example.com', - metricsInterval: 60000, // Send metrics every minute - batchSize: 100, // Batch size for metrics - - // Custom metrics - customMetrics: { - 'agent.execution.duration': (context) => context.executionTime, - 'agent.tool.usage': (context) => context.toolResults?.length || 0, - 'agent.conversation.length': (context) => context.conversationHistory?.length || 0, - 'agent.success.rate': (context) => context.success ? 1 : 0 - }, - - // Tracing - tracingEndpoint: 'https://tracing.example.com', - sampleRate: 0.1, // Sample 10% of traces - - // Privacy settings - excludePersonalData: true, // Exclude personal information - hashUserIds: true, // Hash user identifiers - dataRetentionDays: 30 // Retain data for 30 days -}); -``` +Run after tool calls complete. Used for processing results and managing conversation. -#### ChatRecordingProcessor -Records chat conversations for analysis and debugging. +### ConversationCompactorModifier + +Compacts long conversations to stay within token limits. ```typescript -import { ChatRecordingProcessor } from '@codebolt/agent/unified'; - -const chatRecorder = new ChatRecordingProcessor({ - enableRecording: true, // Enable chat recording - storageLocation: './chat-logs', // Storage directory - includeMetadata: true, // Include conversation metadata - compressionEnabled: true, // Compress stored chats - - // File management - fileFormat: 'json', // Storage format: 'json', 'csv', 'txt' - rotationPolicy: 'daily', // Rotation: 'daily', 'weekly', 'monthly' - maxFileSize: 10 * 1024 * 1024, // Max file size (10MB) - - // Content filtering - excludeSystemMessages: false, // Exclude system messages - excludeToolCalls: false, // Exclude tool calls - excludePersonalInfo: true, // Exclude personal information - - // Privacy and security - encryptionEnabled: true, // Encrypt stored data - encryptionKey: process.env.CHAT_ENCRYPTION_KEY, - accessControl: { - allowedUsers: ['admin', 'developer'], - requireAuth: true - }, - - // Custom processing - preprocessor: (message) => { - // Custom message preprocessing - return { - ...message, - processed: true, - timestamp: new Date().toISOString() - }; - } +import { ConversationCompactorModifier } from '@codebolt/agent/processor-pieces'; + +const modifier = new ConversationCompactorModifier({ + maxConversationLength: 50, + // Additional configuration options }); ``` -### 5. Context Management Processors -Manage context, memory, and state across conversations. +### ShellProcessorModifier -#### ContextManagementProcessor -Comprehensive context management across conversations. +Processes shell command outputs. ```typescript -import { ContextManagementProcessor } from '@codebolt/agent/unified'; - -const contextManager = new ContextManagementProcessor({ - enableContextPersistence: true, // Persist context across sessions - maxContextSize: 10000, // Max context size in tokens - enableContextCompression: true, // Compress context when needed - contextTTL: 3600000, // Context TTL (1 hour) - - // Context storage - storageType: 'memory', // 'memory', 'file', 'database' - storageLocation: './context', // Storage location - - // Context organization - enableSemanticSearch: true, // Enable semantic context search - contextCategories: [ // Context categories - 'user_preferences', - 'conversation_history', - 'task_context', - 'domain_knowledge' - ], - - // Context retrieval - retrievalStrategy: 'hybrid', // 'recency', 'relevance', 'hybrid' - maxRetrievalItems: 20, // Max items to retrieve - relevanceThreshold: 0.7, // Relevance threshold - - // Context updates - updateStrategy: 'incremental', // 'full', 'incremental', 'selective' - conflictResolution: 'merge', // 'overwrite', 'merge', 'keep_existing' - - // Advanced features - enableContextLearning: true, // Learn from context usage - enableContextSuggestions: true, // Suggest relevant context - enableContextValidation: true // Validate context integrity -}); +import { ShellProcessorModifier } from '@codebolt/agent/processor-pieces'; + +const modifier = new ShellProcessorModifier(); ``` -## Using Processors +## Using Processors in Agents + +### With CodeboltAgent -### In Agents ```typescript -const agent = createAgent({ - name: 'Enhanced Agent', - instructions: 'You are an enhanced agent with custom processors.', - processors: { - followUpConversation: [ - new ConversationCompactorProcessor(), - new FollowUpConversationProcessor() - ], - preToolCall: [ - new ToolValidationProcessor(), - new LocalToolInterceptorProcessor() - ] - } -}); +import { CodeboltAgent } from '@codebolt/agent/unified'; +import { + EnvironmentContextModifier, + DirectoryContextModifier, + ToolValidationModifier, + ConversationCompactorModifier, + ChatCompressionModifier, + LoopDetectionModifier +} from '@codebolt/agent/processor-pieces'; + +const agent = new CodeboltAgent({ + instructions: 'You are an enhanced agent.', + tools: [myTool], + + // Message modifiers - transform initial message + messageModifiers: [ + new EnvironmentContextModifier(), + new DirectoryContextModifier() + ], -// Add processors dynamically -agent.addFollowUpProcessor(new ConversationContinuityProcessor()); -agent.addPreToolCallProcessor(new ToolParameterModifierProcessor()); -``` + // Pre-inference - before LLM call + preInferenceProcessors: [ + new ChatCompressionModifier() + ], -### In Workflows -```typescript -const workflow = createWorkflow({ - name: 'Enhanced Workflow', - processors: [ - new TelemetryProcessor(), - new LoopDetectionProcessor() + // Post-inference - after LLM call + postInferenceProcessors: [ + new LoopDetectionModifier({ maxIterations: 10 }) ], - steps: [/* workflow steps */] -}); -``` -### In Orchestrators -```typescript -const orchestrator = createOrchestrator({ - name: 'Enhanced Orchestrator', - processors: [ - new ContextManagementProcessor(), - new ResponseValidationProcessor() + // Pre-tool call - before executing tools + preToolCallProcessors: [ + new ToolValidationModifier({ strictMode: true }) ], - agents: { /* agents */ }, - workflows: { /* workflows */ } + + // Post-tool call - after tool execution + postToolCallProcessors: [ + new ConversationCompactorModifier({ maxConversationLength: 30 }) + ] }); ``` -## Custom Processors - -Create custom processors by extending the base processor classes: +### With Base Agent Class ```typescript -import { BaseProcessor, ProcessorInput, ProcessorOutput } from '@codebolt/agent/unified'; - -class CustomAnalyticsProcessor extends BaseProcessor { - constructor(private config: { analyticsEndpoint: string }) { - super(); - } - - async processInput(input: ProcessorInput): Promise { - // Custom analytics logic - const analytics = { - messageLength: input.message.messages[0].content.length, - timestamp: new Date().toISOString(), - userId: input.context?.userId - }; - - // Send to analytics service - await this.sendAnalytics(analytics); - - return [ - this.createEvent('AnalyticsCollected', analytics) - ]; - } - - private async sendAnalytics(data: any) { - try { - await fetch(this.config.analyticsEndpoint, { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(data) - }); - } catch (error) { - console.error('Failed to send analytics:', error); - } - } -} - -// Use custom processor -const customProcessor = new CustomAnalyticsProcessor({ - analyticsEndpoint: 'https://analytics.example.com' -}); +import { Agent } from '@codebolt/agent/unified'; +import { + ToolValidationModifier, + ConversationCompactorModifier +} from '@codebolt/agent/processor-pieces'; -const agent = createAgent({ - name: 'Analytics-Enabled Agent', - processors: { - followUpConversation: [customProcessor] - } +const agent = new Agent({ + name: 'Custom Agent', + instructions: 'You are a custom agent.', + tools: [myTool], + + preToolCallProcessors: [new ToolValidationModifier()], + postToolCallProcessors: [new ConversationCompactorModifier()] }); ``` -## Processor Configuration Best Practices +## Processor Execution Flow + +``` +User Message + │ + ▼ +┌─────────────────────────┐ +│ Message Modifiers │ ← Transform message to prompt +└─────────────────────────┘ + │ + ▼ +┌─────────────────────────┐ +│ PreInference Processors │ ← Optimize before LLM call +└─────────────────────────┘ + │ + ▼ +┌─────────────────────────┐ +│ LLM Inference │ +└─────────────────────────┘ + │ + ▼ +┌─────────────────────────┐ +│PostInference Processors │ ← Validate response, detect loops +└─────────────────────────┘ + │ + ▼ +┌─────────────────────────┐ +│ PreToolCall Processors │ ← Validate tool calls +└─────────────────────────┘ + │ + ▼ +┌─────────────────────────┐ +│ Tool Execution │ +└─────────────────────────┘ + │ + ▼ +┌─────────────────────────┐ +│PostToolCall Processors │ ← Process results, compact conversation +└─────────────────────────┘ + │ + ▼ + Next Iteration or Response +``` + +## Best Practices ### Development vs Production + ```typescript const isDevelopment = process.env.NODE_ENV === 'development'; -const agent = createAgent({ - name: 'Configurable Agent', - processors: { - followUpConversation: [ - // Always include essential processors - new ConversationCompactorProcessor(), - - // Development-specific processors - ...(isDevelopment ? [ - new ChatRecordingProcessor({ storageLocation: './dev-logs' }), - new TelemetryProcessor({ enableLogging: true }) - ] : []), - - // Production-specific processors - ...(!isDevelopment ? [ - new TelemetryProcessor({ - metricsEndpoint: 'https://prod-metrics.com', - enableLogging: false - }), - new ResponseValidationProcessor({ enableSafetyCheck: true }) - ] : []) - ] - } +const agent = new CodeboltAgent({ + instructions: 'You are a configurable agent.', + tools: [myTool], + + messageModifiers: [ + // Always include + new EnvironmentContextModifier(), + + // Development only + ...(isDevelopment ? [ + new ChatRecordingModifier({ outputPath: './dev-logs' }) + ] : []) + ], + + postToolCallProcessors: [ + new ConversationCompactorModifier() + ] }); ``` ### Performance Optimization + ```typescript -// Lightweight processor configuration for performance -const performanceAgent = createAgent({ - name: 'Performance Agent', - processors: { - followUpConversation: [ - new ConversationCompactorProcessor({ - maxConversationLength: 20, // Smaller conversation window - enableSummarization: false, // Disable expensive summarization - enableSmartRemoval: false // Disable complex analysis - }), - new TokenManagementProcessor({ - maxTokens: 2000, // Lower token limit - enableCompression: true, // Enable compression - compressionRatio: 0.8 // Aggressive compression - }) - ], - preToolCall: [ - new ToolValidationProcessor({ - strictMode: false, // Less strict validation - enableOutputValidation: false // Skip output validation - }) - ] - } +// Lightweight configuration for performance-critical applications +const performanceAgent = new CodeboltAgent({ + instructions: 'You are an optimized agent.', + tools: [myTool], + + postToolCallProcessors: [ + new ConversationCompactorModifier({ + maxConversationLength: 20 // Smaller conversation window + }) + ], + + preToolCallProcessors: [ + new ToolValidationModifier({ + strictMode: false // Less strict for performance + }) + ] }); ``` + +## Available Processors Summary + +| Category | Processor | Purpose | +|----------|-----------|---------| +| Message Modifiers | `EnvironmentContextModifier` | Add environment context | +| Message Modifiers | `CoreSystemPromptModifier` | Core system prompt handling | +| Message Modifiers | `DirectoryContextModifier` | Working directory context | +| Message Modifiers | `IdeContextModifier` | IDE integration context | +| Message Modifiers | `AtFileProcessorModifier` | Process @file references | +| Message Modifiers | `ArgumentProcessorModifier` | Process arguments | +| Message Modifiers | `MemoryImportModifier` | Import memory context | +| Message Modifiers | `ToolInjectionModifier` | Inject tool descriptions | +| Message Modifiers | `ChatRecordingModifier` | Record chat history | +| Message Modifiers | `ChatHistoryMessageModifier` | Include chat history | +| PreInference | `ChatCompressionModifier` | Compress chat history | +| PostInference | `LoopDetectionModifier` | Detect execution loops | +| PreToolCall | `ToolParameterModifier` | Modify tool parameters | +| PreToolCall | `ToolValidationModifier` | Validate tool calls | +| PostToolCall | `ConversationCompactorModifier` | Compact conversations | +| PostToolCall | `ShellProcessorModifier` | Process shell output | diff --git a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/5-examples-and-best-practices.md b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/5-examples-and-best-practices.md index 1fc11e3c..b1191c14 100644 --- a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/5-examples-and-best-practices.md +++ b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/5-examples-and-best-practices.md @@ -7,24 +7,17 @@ This section provides comprehensive examples and best practices for using the Un ### 1. Customer Support System ```typescript +import { CodeboltAgent, createTool } from '@codebolt/agent/unified'; import { - createAgent, - createTool, - createWorkflow, - createOrchestrator, - createAgentStep, - createToolStep, - ConversationCompactorProcessor, - ToolValidationProcessor, - TelemetryProcessor, - ChatRecordingProcessor -} from '@codebolt/agent/unified'; + ConversationCompactorModifier, + ToolValidationModifier, + ChatRecordingModifier +} from '@codebolt/agent/processor-pieces'; import { z } from 'zod'; // Create specialized tools const ticketSearchTool = createTool({ id: 'ticket-search', - name: 'Ticket Search', description: 'Search customer support tickets', inputSchema: z.object({ query: z.string(), @@ -45,7 +38,6 @@ const ticketSearchTool = createTool({ const knowledgeBaseTool = createTool({ id: 'knowledge-base', - name: 'Knowledge Base Search', description: 'Search knowledge base articles', inputSchema: z.object({ query: z.string(), @@ -63,7 +55,6 @@ const knowledgeBaseTool = createTool({ const escalationTool = createTool({ id: 'escalate-ticket', - name: 'Escalate Ticket', description: 'Escalate ticket to human agent', inputSchema: z.object({ ticketId: z.string(), @@ -79,128 +70,42 @@ const escalationTool = createTool({ } }); -// Create specialized agents -const supportAgent = createAgent({ - name: 'Customer Support Agent', +// Create specialized agent +const supportAgent = new CodeboltAgent({ instructions: `You are a helpful customer support agent. Your role is to: 1. Understand customer issues clearly 2. Search for relevant tickets and knowledge base articles 3. Provide accurate and helpful solutions 4. Escalate complex issues when necessary 5. Maintain a friendly and professional tone`, - + tools: [ticketSearchTool, knowledgeBaseTool, escalationTool], - - processors: { - followUpConversation: [ - new ConversationCompactorProcessor({ - maxConversationLength: 30, - preserveRecentMessages: 5 - }), - new TelemetryProcessor({ - enableMetrics: true, - customMetrics: { - 'support.ticket.searches': (context) => - context.toolResults?.filter(r => r.toolName === 'ticket-search').length || 0, - 'support.escalations': (context) => - context.toolResults?.filter(r => r.toolName === 'escalate-ticket').length || 0 - } - }) - ], - preToolCall: [ - new ToolValidationProcessor({ - strictMode: true, - enableInputValidation: true - }) - ] - } -}); -// Create support workflow -const supportWorkflow = createWorkflow({ - name: 'Customer Support Workflow', - description: 'Comprehensive customer support process', - steps: [ - createAgentStep({ - id: 'initial-assessment', - name: 'Initial Assessment', - agent: supportAgent, - message: 'Assess this customer issue: {{customerMessage}}', - outputMapping: { - assessment: 'agentResult.response', - suggestedActions: 'agentResult.toolResults' - } - }), - createToolStep({ - id: 'knowledge-search', - name: 'Knowledge Base Search', - tool: knowledgeBaseTool, - input: (context) => ({ - query: context.data.customerMessage, - category: context.data.category - }), - outputMapping: { - knowledgeArticles: 'toolResult.articles' - } - }), - createAgentStep({ - id: 'solution-generation', - name: 'Generate Solution', - agent: supportAgent, - message: 'Based on the assessment {{assessment}} and knowledge articles {{knowledgeArticles}}, provide a solution for: {{customerMessage}}', - dependencies: ['initial-assessment', 'knowledge-search'], - outputMapping: { - solution: 'agentResult.response' - } + postToolCallProcessors: [ + new ConversationCompactorModifier({ + maxConversationLength: 30 + }) + ], + preToolCallProcessors: [ + new ToolValidationModifier({ + strictMode: true }) ] }); -// Create support orchestrator -const supportOrchestrator = createOrchestrator({ - name: 'Customer Support Orchestrator', - instructions: `You coordinate customer support operations intelligently: - - - For simple questions: Use knowledge base search - - For account issues: Search tickets and provide direct help - - For complex problems: Use the full support workflow - - For urgent issues: Escalate immediately`, - - agents: { - 'support-agent': supportAgent - }, - - workflows: { - 'support-workflow': supportWorkflow - }, - - tools: { - 'ticket-search': ticketSearchTool, - 'knowledge-base': knowledgeBaseTool, - 'escalate-ticket': escalationTool - }, - - limits: { - maxSteps: 8, - maxExecutionTime: 120000 // 2 minutes - } -}); - // Usage example async function handleCustomerSupport() { const customerMessage = "I can't log into my account and I have an important meeting in 30 minutes"; - - const result = await supportOrchestrator.loop(customerMessage); - + + const result = await supportAgent.execute({ + role: 'user', + content: customerMessage + }); + console.log('Support Result:', { success: result.success, - response: result.response, - stepsExecuted: result.executionSteps.length, - resourcesUsed: { - agents: result.metrics.agentsExecuted, - workflows: result.metrics.workflowsExecuted, - tools: result.metrics.toolsExecuted - } + result: result.result, + error: result.error }); } ``` @@ -208,14 +113,15 @@ async function handleCustomerSupport() { ### 2. Content Creation Pipeline ```typescript -// Research and content creation system -const researchAgent = createAgent({ - name: 'Research Specialist', +import { CodeboltAgent, createTool, Workflow, AgentStep } from '@codebolt/agent/unified'; +import { z } from 'zod'; + +// Research agent +const researchAgent = new CodeboltAgent({ instructions: 'You are an expert researcher who gathers comprehensive information on any topic.', tools: [ createTool({ id: 'web-search', - name: 'Web Search', description: 'Search the web for information', inputSchema: z.object({ query: z.string(), @@ -230,7 +136,6 @@ const researchAgent = createAgent({ }), createTool({ id: 'academic-search', - name: 'Academic Search', description: 'Search academic papers and journals', inputSchema: z.object({ query: z.string(), @@ -245,13 +150,11 @@ const researchAgent = createAgent({ ] }); -const writerAgent = createAgent({ - name: 'Content Writer', +const writerAgent = new CodeboltAgent({ instructions: 'You are a skilled content writer who creates engaging, well-structured content.', tools: [ createTool({ id: 'style-checker', - name: 'Style Checker', description: 'Check content style and readability', inputSchema: z.object({ content: z.string(), @@ -266,13 +169,11 @@ const writerAgent = createAgent({ ] }); -const editorAgent = createAgent({ - name: 'Content Editor', +const editorAgent = new CodeboltAgent({ instructions: 'You are a meticulous editor who refines and polishes content.', tools: [ createTool({ id: 'grammar-check', - name: 'Grammar Checker', description: 'Check grammar and spelling', inputSchema: z.object({ content: z.string() }), execute: async ({ input }) => ({ @@ -284,61 +185,29 @@ const editorAgent = createAgent({ ] }); -// Content creation workflow -const contentWorkflow = createWorkflow({ - name: 'Content Creation Pipeline', - steps: [ - createAgentStep({ - id: 'research-phase', - name: 'Research Phase', - agent: researchAgent, - message: 'Research comprehensive information about: {{topic}}. Focus on {{focus_areas}}.', - outputMapping: { - researchData: 'agentResult.response', - sources: 'agentResult.toolResults' - } - }), - createAgentStep({ - id: 'writing-phase', - name: 'Writing Phase', - agent: writerAgent, - message: 'Write a {{content_type}} about {{topic}} using this research: {{researchData}}. Target audience: {{audience}}. Length: {{length}}.', - dependencies: ['research-phase'], - outputMapping: { - draft: 'agentResult.response', - styleAnalysis: 'agentResult.toolResults' - } - }), - createAgentStep({ - id: 'editing-phase', - name: 'Editing Phase', - agent: editorAgent, - message: 'Edit and polish this content: {{draft}}. Ensure it meets {{quality_standards}}.', - dependencies: ['writing-phase'], - outputMapping: { - finalContent: 'agentResult.response', - qualityReport: 'agentResult.toolResults' - } - }) - ], - initialData: { - topic: 'Artificial Intelligence in Healthcare', - content_type: 'blog post', - audience: 'healthcare professionals', - length: '1500 words', - focus_areas: ['current applications', 'future trends', 'challenges'], - quality_standards: 'professional, accurate, engaging' - } -}); - // Usage async function createContent() { - const result = await contentWorkflow.execute(); - - if (result.success) { + // Execute research + const researchResult = await researchAgent.execute({ + role: 'user', + content: 'Research comprehensive information about AI in Healthcare' + }); + + // Execute writing + const writingResult = await writerAgent.execute({ + role: 'user', + content: `Write a blog post about AI in Healthcare using this research: ${researchResult.result}` + }); + + // Execute editing + const editingResult = await editorAgent.execute({ + role: 'user', + content: `Edit and polish this content: ${writingResult.result}` + }); + + if (editingResult.success) { console.log('Content created successfully!'); - console.log('Final content:', result.data.finalContent); - console.log('Quality report:', result.data.qualityReport); + console.log('Final content:', editingResult.result); } } ``` @@ -346,14 +215,15 @@ async function createContent() { ### 3. Data Analysis System ```typescript +import { CodeboltAgent, createTool } from '@codebolt/agent/unified'; +import { z } from 'zod'; + // Multi-agent data analysis system -const dataCollectorAgent = createAgent({ - name: 'Data Collector', +const dataCollectorAgent = new CodeboltAgent({ instructions: 'You collect and validate data from various sources.', tools: [ createTool({ id: 'api-connector', - name: 'API Connector', description: 'Connect to various APIs and collect data', inputSchema: z.object({ endpoint: z.string(), @@ -366,7 +236,6 @@ const dataCollectorAgent = createAgent({ }), createTool({ id: 'data-validator', - name: 'Data Validator', description: 'Validate data quality and completeness', inputSchema: z.object({ data: z.array(z.unknown()), @@ -382,13 +251,11 @@ const dataCollectorAgent = createAgent({ ] }); -const dataAnalystAgent = createAgent({ - name: 'Data Analyst', +const dataAnalystAgent = new CodeboltAgent({ instructions: 'You perform statistical analysis and generate insights from data.', tools: [ createTool({ id: 'statistical-analysis', - name: 'Statistical Analysis', description: 'Perform statistical analysis on datasets', inputSchema: z.object({ data: z.array(z.unknown()), @@ -406,7 +273,6 @@ const dataAnalystAgent = createAgent({ }), createTool({ id: 'visualization', - name: 'Data Visualization', description: 'Create charts and visualizations', inputSchema: z.object({ data: z.array(z.unknown()), @@ -420,13 +286,11 @@ const dataAnalystAgent = createAgent({ ] }); -const reportGeneratorAgent = createAgent({ - name: 'Report Generator', +const reportGeneratorAgent = new CodeboltAgent({ instructions: 'You create comprehensive reports from analysis results.', tools: [ createTool({ id: 'report-builder', - name: 'Report Builder', description: 'Build structured reports', inputSchema: z.object({ data: z.record(z.unknown()), @@ -441,31 +305,28 @@ const reportGeneratorAgent = createAgent({ ] }); -// Data analysis orchestrator -const dataOrchestrator = createOrchestrator({ - name: 'Data Analysis Orchestrator', - instructions: `You coordinate data analysis workflows: - - 1. For data collection tasks → use data collector - 2. For analysis tasks → use data analyst - 3. For reporting → use report generator - 4. For end-to-end analysis → coordinate all agents`, - - agents: { - 'collector': dataCollectorAgent, - 'analyst': dataAnalystAgent, - 'reporter': reportGeneratorAgent - } -}); - // Usage async function analyzeData() { - const result = await dataOrchestrator.loop( - 'Collect sales data from our API, analyze trends, and generate a comprehensive report' - ); - - console.log('Analysis completed:', result.success); - console.log('Report:', result.response); + // Collect data + const collectionResult = await dataCollectorAgent.execute({ + role: 'user', + content: 'Collect sales data from our API' + }); + + // Analyze data + const analysisResult = await dataAnalystAgent.execute({ + role: 'user', + content: `Analyze trends in this data: ${collectionResult.result}` + }); + + // Generate report + const reportResult = await reportGeneratorAgent.execute({ + role: 'user', + content: `Generate a comprehensive report from: ${analysisResult.result}` + }); + + console.log('Analysis completed:', reportResult.success); + console.log('Report:', reportResult.result); } ``` @@ -473,65 +334,36 @@ async function analyzeData() { ### 1. Agent Design Principles -#### ✅ Good: Focused, Specialized Agents +#### Good: Focused, Specialized Agents ```typescript // Specialized agents with clear responsibilities -const emailAgent = createAgent({ - name: 'Email Specialist', +const emailAgent = new CodeboltAgent({ instructions: 'You handle email-related tasks with expertise in email protocols and best practices.', - tools: [emailSendTool, emailValidationTool, templateTool], - llmConfig: { - temperature: 0.3, // Lower temperature for accuracy - maxTokens: 1500 - } + tools: [emailSendTool, emailValidationTool, templateTool] }); -const calculationAgent = createAgent({ - name: 'Math Specialist', +const calculationAgent = new CodeboltAgent({ instructions: 'You perform mathematical calculations and solve numerical problems.', - tools: [calculatorTool, statisticsTool, graphingTool], - llmConfig: { - temperature: 0.1, // Very low for mathematical accuracy - maxTokens: 1000 - } + tools: [calculatorTool, statisticsTool, graphingTool] }); ``` -#### ❌ Avoid: Generic, Unfocused Agents +#### Avoid: Generic, Unfocused Agents ```typescript // Avoid overly generic agents -const genericAgent = createAgent({ - name: 'Generic Agent', +const genericAgent = new CodeboltAgent({ instructions: 'You do everything and anything.', - tools: [/* 20+ unrelated tools */], // Too many tools - llmConfig: { - temperature: 0.7, // Not optimized for any specific task - maxTokens: 4000 - } + tools: [/* 20+ unrelated tools */] // Too many tools }); ``` ### 2. Tool Organization -#### ✅ Good: Logical Tool Grouping +#### Good: Logical Tool Grouping ```typescript -// Group related tools -const fileOperationTools = [ - createFileTool({ operation: 'read', id: 'file-read' }), - createFileTool({ operation: 'write', id: 'file-write' }), - createFileTool({ operation: 'delete', id: 'file-delete' }) -]; - -const apiTools = [ - createHttpTool({ method: 'GET', id: 'api-get' }), - createHttpTool({ method: 'POST', id: 'api-post' }), - createValidationTool({ schema: apiResponseSchema, id: 'api-validate' }) -]; - // Clear, descriptive tool definitions const calculatorTool = createTool({ id: 'advanced-calculator', - name: 'Advanced Calculator', description: 'Perform complex mathematical calculations including trigonometry, logarithms, and statistical functions', inputSchema: z.object({ expression: z.string().describe('Mathematical expression to evaluate'), @@ -543,187 +375,97 @@ const calculatorTool = createTool({ }); ``` -#### ❌ Avoid: Poor Tool Organization +#### Avoid: Poor Tool Organization ```typescript // Avoid unclear tool definitions const badTool = createTool({ id: 'tool1', // Non-descriptive ID - name: 'Tool', // Generic name description: 'Does stuff', // Vague description inputSchema: z.any(), // No input validation execute: async ({ input }) => input // No actual functionality }); ``` -### 3. Workflow Design - -#### ✅ Good: Clear Dependencies and Error Handling -```typescript -const robustWorkflow = createWorkflow({ - name: 'Data Processing Pipeline', - description: 'Robust data processing with error handling', - steps: [ - createValidationStep({ - id: 'validate-input', - name: 'Input Validation', - schema: inputSchema, - stopOnFailure: true, // Stop if validation fails - errorMessage: 'Input validation failed' - }), - createToolStep({ - id: 'process-data', - name: 'Data Processing', - tool: processingTool, - dependencies: ['validate-input'], - retry: { - maxAttempts: 3, - delay: 1000, - backoff: 'exponential' - }, - onError: 'continue' // Continue with next step on error - }), - createConditionalStep({ - id: 'quality-check', - name: 'Quality Check', - condition: (context) => context.data.processedData?.quality > 0.8, - trueSteps: [ - createToolStep({ - id: 'finalize', - name: 'Finalize Processing', - tool: finalizeTool - }) - ], - falseSteps: [ - createToolStep({ - id: 'reprocess', - name: 'Reprocess Data', - tool: reprocessTool - }) - ] - }) - ], - continueOnError: false, // Stop workflow on critical errors - timeout: 300000 // 5 minute timeout -}); -``` +### 3. Processor Configuration -#### ❌ Avoid: Fragile Workflow Design +#### Good: Environment-Specific Configuration ```typescript -const fragileWorkflow = createWorkflow({ - name: 'Fragile Workflow', - steps: [ - createToolStep({ - id: 'step1', - tool: unreliableTool - // No error handling, no retries, no validation - }), - createToolStep({ - id: 'step2', - tool: anotherTool, - dependencies: ['step1'] - // Will fail if step1 fails - }) - ] - // No timeout, no error handling configuration -}); -``` - -### 4. Processor Configuration +import { + ConversationCompactorModifier, + ChatRecordingModifier, + ToolValidationModifier, + LoopDetectionModifier +} from '@codebolt/agent/processor-pieces'; -#### ✅ Good: Environment-Specific Configuration -```typescript const isDevelopment = process.env.NODE_ENV === 'development'; const isProduction = process.env.NODE_ENV === 'production'; -const agent = createAgent({ - name: 'Configurable Agent', +const agent = new CodeboltAgent({ instructions: 'You are a well-configured agent.', - - processors: { - followUpConversation: [ - // Always include essential processors - new ConversationCompactorProcessor({ - maxConversationLength: isDevelopment ? 10 : 30, - enableSummarization: !isDevelopment // Disable expensive operations in dev - }), - - // Development-specific processors - ...(isDevelopment ? [ - new ChatRecordingProcessor({ - storageLocation: './dev-logs', - includeMetadata: true - }) - ] : []), - - // Production-specific processors - ...(isProduction ? [ - new TelemetryProcessor({ - metricsEndpoint: process.env.METRICS_ENDPOINT, - enableMetrics: true, - enableLogging: false // Reduce noise in production - }), - new ResponseValidationProcessor({ - enableSafetyCheck: true, - strictMode: true - }) - ] : []) - ], - - preToolCall: [ - new ToolValidationProcessor({ - strictMode: isProduction, // Strict validation in production - enableInputValidation: true, - enableOutputValidation: isProduction - }), - - ...(isDevelopment ? [ - new LoopDetectionProcessor({ - maxIterations: 5 // Lower limit for development - }) - ] : []) - ] - } + tools: [myTool], + + messageModifiers: [ + // Development-specific processors + ...(isDevelopment ? [ + new ChatRecordingModifier({ + outputPath: './dev-logs' + }) + ] : []) + ], + + postToolCallProcessors: [ + // Always include essential processors + new ConversationCompactorModifier({ + maxConversationLength: isDevelopment ? 10 : 30 + }) + ], + + preToolCallProcessors: [ + new ToolValidationModifier({ + strictMode: isProduction // Strict validation in production + }) + ], + + postInferenceProcessors: [ + ...(isDevelopment ? [ + new LoopDetectionModifier({ + maxIterations: 5 // Lower limit for development + }) + ] : []) + ] }); ``` -### 5. Error Handling +### 4. Error Handling -#### ✅ Good: Comprehensive Error Handling +#### Good: Comprehensive Error Handling ```typescript -async function executeWithErrorHandling(agent: Agent, message: string) { +async function executeWithErrorHandling(agent: CodeboltAgent, message: string) { try { - const result = await agent.execute(message, { - maxIterations: 5, - timeout: 30000 + const result = await agent.execute({ + role: 'user', + content: message }); - + if (!result.success) { // Log structured error information console.error('Agent execution failed:', { - error: result.error, - iterations: result.iterations, - lastToolResult: result.toolResults?.[result.toolResults.length - 1], - conversationLength: result.conversationHistory?.length + error: result.error }); - + // Return user-friendly error message return { success: false, - message: 'I encountered an issue processing your request. Please try rephrasing or contact support if the problem persists.', + message: 'I encountered an issue processing your request. Please try again.', errorCode: 'AGENT_EXECUTION_FAILED' }; } - + return { success: true, - response: result.response, - metadata: { - iterations: result.iterations, - toolsUsed: result.toolResults?.length || 0, - executionTime: result.executionTime - } + response: result.result }; - + } catch (error) { // Log unexpected errors console.error('Unexpected error during agent execution:', { @@ -732,12 +474,7 @@ async function executeWithErrorHandling(agent: Agent, message: string) { message, timestamp: new Date().toISOString() }); - - // Send to error tracking service - if (process.env.NODE_ENV === 'production') { - await sendToErrorTracking(error, { message, agentName: agent.config.name }); - } - + return { success: false, message: 'I\'m experiencing technical difficulties. Please try again later.', @@ -745,301 +482,107 @@ async function executeWithErrorHandling(agent: Agent, message: string) { }; } } - -async function sendToErrorTracking(error: unknown, context: Record) { - // Implementation for error tracking service -} ``` -### 6. Performance Optimization +### 5. Performance Optimization -#### ✅ Good: Resource Management +#### Good: Resource Management ```typescript -// Optimized orchestrator configuration -const optimizedOrchestrator = createOrchestrator({ - name: 'Optimized Orchestrator', - instructions: 'You coordinate resources efficiently.', - - // Resource limits - limits: { - maxSteps: 8, // Reasonable step limit - maxExecutionTime: 60000, // 1 minute timeout - maxMemoryUsage: 100 * 1024 * 1024 // 100MB memory limit - }, - - // Decision optimization - decisionConfig: { - confidenceThreshold: 0.8, // Higher threshold for faster decisions - explainDecisions: false, // Disable in production for speed - askConfirmation: false - }, - - // Memory optimization - memory: { - persistent: false, // Disable persistence if not needed - maxSize: 100, // Limit memory entries - ttl: 300000 // 5 minute TTL - }, - - agents: { /* optimized agents */ }, - workflows: { /* optimized workflows */ } -}); +import { ConversationCompactorModifier } from '@codebolt/agent/processor-pieces'; -// Parallel workflow execution -const parallelWorkflow = createWorkflow({ - name: 'Parallel Processing Workflow', - steps: [ - // These steps can run in parallel - createAgentStep({ - id: 'task1', - name: 'Task 1', - agent: agent1, - parallel: true - }), - createAgentStep({ - id: 'task2', - name: 'Task 2', - agent: agent2, - parallel: true - }), - createAgentStep({ - id: 'task3', - name: 'Task 3', - agent: agent3, - parallel: true - }), - - // This step waits for all parallel tasks - createAgentStep({ - id: 'summary', - name: 'Summarize Results', - agent: summaryAgent, - dependencies: ['task1', 'task2', 'task3'] +// Optimized agent configuration +const optimizedAgent = new CodeboltAgent({ + instructions: 'You are an optimized agent.', + tools: [myTool], + + // Use conversation compaction to manage memory + postToolCallProcessors: [ + new ConversationCompactorModifier({ + maxConversationLength: 20 // Keep conversation manageable }) - ], - maxParallelSteps: 3 // Allow up to 3 parallel steps + ] }); ``` -### 7. Testing Strategies +### 6. Testing Strategies -#### ✅ Good: Comprehensive Testing +#### Good: Comprehensive Testing ```typescript +import { createTool, CodeboltAgent } from '@codebolt/agent/unified'; +import { z } from 'zod'; + // Unit testing for tools describe('Calculator Tool', () => { const calculatorTool = createTool({ id: 'calculator', - name: 'Calculator', + description: 'Calculator', inputSchema: z.object({ expression: z.string() }), execute: async ({ input }) => ({ result: eval(input.expression) }) }); - + it('should perform basic arithmetic', async () => { - const result = await executeTool(calculatorTool, { expression: '2 + 2' }); - expect(result.result).toBe(4); + const result = await calculatorTool.execute({ expression: '2 + 2' }, {}); + expect(result.success).toBe(true); + expect(result.result.result).toBe(4); }); - + it('should handle complex expressions', async () => { - const result = await executeTool(calculatorTool, { expression: 'Math.sqrt(16)' }); - expect(result.result).toBe(4); - }); - - it('should handle invalid expressions gracefully', async () => { - await expect(executeTool(calculatorTool, { expression: 'invalid' })) - .rejects.toThrow(); + const result = await calculatorTool.execute({ expression: 'Math.sqrt(16)' }, {}); + expect(result.success).toBe(true); + expect(result.result.result).toBe(4); }); }); // Integration testing for agents describe('Math Agent Integration', () => { - const mathAgent = createAgent({ - name: 'Math Agent', + const calculatorTool = createTool({ + id: 'calculator', + description: 'Calculator', + inputSchema: z.object({ expression: z.string() }), + execute: async ({ input }) => ({ result: eval(input.expression) }) + }); + + const mathAgent = new CodeboltAgent({ instructions: 'You solve mathematical problems.', tools: [calculatorTool] }); - - it('should solve math problems', async () => { - const result = await mathAgent.execute('What is 15 * 7?'); - expect(result.success).toBe(true); - expect(result.response).toContain('105'); - }); - - it('should handle multiple calculations', async () => { - const result = await mathAgent.execute('Calculate both 10 + 5 and 20 - 8'); - expect(result.success).toBe(true); - expect(result.toolResults).toHaveLength(2); - }); -}); -// End-to-end testing for workflows -describe('Data Processing Workflow E2E', () => { - it('should process data end-to-end', async () => { - const workflow = createWorkflow({ - name: 'Test Workflow', - steps: [ - createToolStep({ - id: 'collect', - tool: dataCollectionTool - }), - createToolStep({ - id: 'process', - tool: dataProcessingTool, - dependencies: ['collect'] - }) - ] + it('should solve math problems', async () => { + const result = await mathAgent.execute({ + role: 'user', + content: 'What is 15 * 7?' }); - - const result = await workflow.execute(); - expect(result.success).toBe(true); - expect(result.stepResults).toHaveLength(2); - expect(result.data.processedData).toBeDefined(); }); }); ``` -### 8. Monitoring and Observability +### 7. Debugging -#### ✅ Good: Comprehensive Monitoring +#### Good: Using ChatRecordingModifier for debugging ```typescript -// Production monitoring setup -const productionAgent = createAgent({ - name: 'Production Agent', - instructions: 'You are a production-ready agent.', - - processors: { - followUpConversation: [ - new TelemetryProcessor({ - enableMetrics: true, - enableTracing: true, - metricsEndpoint: process.env.METRICS_ENDPOINT, - - // Custom metrics for business insights - customMetrics: { - 'agent.success_rate': (context) => context.success ? 1 : 0, - 'agent.response_time': (context) => context.executionTime, - 'agent.tool_usage': (context) => context.toolResults?.length || 0, - 'agent.conversation_length': (context) => context.conversationHistory?.length || 0, - 'agent.user_satisfaction': (context) => context.userFeedback?.rating || 0 - }, - - // Performance monitoring - performanceThresholds: { - maxResponseTime: 30000, // 30 seconds - maxMemoryUsage: 100 * 1024 * 1024, // 100MB - maxTokenUsage: 4000 - } - }), - - new ResponseValidationProcessor({ - enableContentValidation: true, - enableSafetyCheck: true, - - // Quality metrics - qualityMetrics: [ - 'response_length', - 'readability_score', - 'sentiment_appropriateness', - 'factual_accuracy' - ] - }) - ] - } -}); - -// Health check endpoint -async function healthCheck() { - try { - const testResult = await productionAgent.execute('Hello, are you working?', { - maxIterations: 1, - timeout: 5000 - }); - - return { - status: testResult.success ? 'healthy' : 'degraded', - timestamp: new Date().toISOString(), - responseTime: testResult.executionTime, - version: process.env.APP_VERSION - }; - } catch (error) { - return { - status: 'unhealthy', - error: error instanceof Error ? error.message : String(error), - timestamp: new Date().toISOString() - }; - } -} -``` +import { ChatRecordingModifier } from '@codebolt/agent/processor-pieces'; -## Migration Guide +const debugAgent = new CodeboltAgent({ + instructions: 'You are a debug agent.', + tools: [myTools], -### From Other Agent Patterns - -#### From ComposableAgent -```typescript -// Old ComposableAgent pattern -const oldAgent = new ComposableAgent({ - name: 'Research Agent', - instructions: 'You conduct research', - tools: [researchTool], - processors: [compressionProcessor] -}); - -// New Unified Agent -const newAgent = createAgent({ - name: 'Research Agent', - instructions: 'You conduct research', - tools: [researchTool], - processors: { - followUpConversation: [compressionProcessor] - }, - defaultProcessors: true // Adds sensible defaults -}); -``` - -#### Migration Steps - -1. **Update Imports** -```typescript -// Old imports -import { ComposableAgent } from '@codebolt/agent/composable'; -import { SomeProcessor } from '@codebolt/agent/processor-pieces'; - -// New imports -import { createAgent, SomeProcessor } from '@codebolt/agent/unified'; -``` - -2. **Convert Agent Creation** -```typescript -// Replace constructor calls with factory functions -const agent = createAgent({ /* config */ }); -const workflow = createWorkflow({ /* config */ }); -const orchestrator = createOrchestrator({ /* config */ }); -``` - -3. **Update Processor Usage** -```typescript -// Old: Manual processor management -agent.addProcessor(processor); - -// New: Structured processor configuration -const agent = createAgent({ - processors: { - followUpConversation: [processor1, processor2], - preToolCall: [processor3] - } + messageModifiers: [ + new ChatRecordingModifier({ + enabled: true, + outputPath: './debug-logs' + }) + ] }); ``` ## Conclusion -The Unified Agent Framework provides a comprehensive, production-ready system for building sophisticated AI applications. By following these best practices and examples, you can create robust, scalable, and maintainable AI systems that grow with your needs. +The Unified Agent Framework provides a comprehensive, production-ready system for building sophisticated AI applications. By following these best practices and examples, you can create robust, scalable, and maintainable AI systems. Key takeaways: - **Start Simple**: Begin with basic agents and tools, then add complexity as needed -- **Design for Scale**: Use proper error handling, monitoring, and resource management +- **Design for Scale**: Use proper error handling and resource management - **Test Thoroughly**: Implement comprehensive testing at all levels -- **Monitor Everything**: Use telemetry and observability for production systems +- **Use Processors**: Add processors for validation and conversation management - **Follow Patterns**: Use established patterns for common use cases -- **Optimize Performance**: Consider resource usage and execution time -- **Plan for Growth**: Design systems that can evolve and expand diff --git a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/6-roadmap.md b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/6-roadmap.md new file mode 100644 index 00000000..ece121a6 --- /dev/null +++ b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/6-roadmap.md @@ -0,0 +1,292 @@ +# Roadmap: Future Features + +This document describes planned features that are not yet implemented in the Unified Agent Framework. These features are under development and may change before release. + +> **Note**: The APIs described in this document are **not currently available**. Do not attempt to import or use these features as they will result in errors. + +## Orchestrator System + +The orchestrator system will provide dynamic coordination of multiple agents, workflows, and tools. + +### Planned API + +```typescript +// FUTURE - NOT YET IMPLEMENTED +import { createOrchestrator } from '@codebolt/agent/unified'; + +const orchestrator = createOrchestrator({ + name: 'Smart Coordinator', + instructions: 'Coordinate resources intelligently', + agents: { researcher, analyst }, + workflows: { researchPipeline }, + tools: { calculator, summarizer } +}); +``` + +### Planned Features + +- Dynamic agent selection based on task requirements +- Workflow orchestration with conditional branching +- Resource management and load balancing +- Cross-agent communication + +## Specialized Tool Creators + +Convenience functions for creating common tool types. + +### Planned APIs + +```typescript +// FUTURE - NOT YET IMPLEMENTED + +// Text processing tool +const textTool = createTextTool({ + id: 'summarizer', + description: 'Summarize text content', + execute: (text) => `Summary: ${text.substring(0, 100)}...` +}); + +// File operation tool +const fileTool = createFileTool({ + id: 'file-reader', + operation: 'read', + execute: async (filePath) => { + return await fs.readFile(filePath, 'utf-8'); + } +}); + +// HTTP request tool +const httpTool = createHttpTool({ + id: 'api-client', + baseUrl: 'https://api.example.com', + execute: async (endpoint, options) => { + return await fetch(`${baseUrl}${endpoint}`, options); + } +}); + +// Validation tool +const validationTool = createValidationTool({ + id: 'email-validator', + schema: z.string().email(), + execute: (email) => ({ isValid: true, email }) +}); + +// Transform tool +const transformTool = createTransformTool({ + id: 'data-transformer', + execute: (data) => ({ transformed: data.map(item => ({ ...item, processed: true })) }) +}); +``` + +### Planned Helper Functions + +```typescript +// FUTURE - NOT YET IMPLEMENTED + +// Execute tool directly +const result = await executeTool(tool, input, context); + +// Convert multiple tools to OpenAI format +const openAITools = toolsToOpenAIFormat([tool1, tool2, tool3]); +``` + +## Advanced Processors + +Additional processors planned for future releases. + +### System Monitoring Processors + +```typescript +// FUTURE - NOT YET IMPLEMENTED + +// Telemetry collection +const telemetryProcessor = new TelemetryProcessor({ + enableMetrics: true, + enableTracing: true, + metricsEndpoint: 'https://metrics.example.com', + customMetrics: { + 'agent.execution.duration': (context) => context.executionTime, + 'agent.tool.usage': (context) => context.toolResults?.length || 0 + } +}); + +// Token management +const tokenManager = new TokenManagementProcessor({ + maxTokens: 4000, + reserveTokens: 500, + enableCompression: true +}); + +// Response validation +const responseValidator = new ResponseValidationProcessor({ + enableContentValidation: true, + enableSafetyCheck: true, + maxResponseLength: 2000 +}); +``` + +### Conversation Management Processors + +```typescript +// FUTURE - NOT YET IMPLEMENTED + +// Follow-up conversation enhancement +const followUpProcessor = new FollowUpConversationProcessor({ + enhanceToolResults: true, + addGuidedPrompts: true, + maxSuggestions: 3 +}); + +// Conversation continuity +const continuityProcessor = new ConversationContinuityProcessor({ + enableContextLinking: true, + enableReferenceResolution: true, + maxContextWindow: 20 +}); + +// Context management +const contextManager = new ContextManagementProcessor({ + enableContextPersistence: true, + maxContextSize: 10000, + storageType: 'memory' +}); +``` + +### Advanced Loop Detection + +```typescript +// FUTURE - NOT YET IMPLEMENTED + +const advancedLoopDetector = new AdvancedLoopDetectionProcessor({ + enableSemanticAnalysis: true, + enablePatternDetection: true, + maxLoopLength: 5, + confidenceThreshold: 0.9, + patternTypes: [ + 'repetitive_actions', + 'circular_reasoning', + 'oscillating_behavior' + ] +}); +``` + +### Tool Execution Processors + +```typescript +// FUTURE - NOT YET IMPLEMENTED + +// Local tool interception +const interceptorProcessor = new LocalToolInterceptorProcessor({ + localTools: new Map([ + ['calculator', { + name: 'Local Calculator', + execute: async (input) => ({ result: eval(input.expression) }) + }] + ]), + enableInterception: true, + fallbackToOriginal: true +}); +``` + +## Advanced Message Modifiers + +```typescript +// FUTURE - NOT YET IMPLEMENTED + +// URL content extraction +const urlModifier = new HandleUrlMessageModifier({ + extractContent: true, + includeMetadata: true, + maxContentLength: 10000 +}); + +// Base context injection +const contextModifier = new BaseContextMessageModifier({ + includeTimestamp: true, + includeUserInfo: true, + customContext: { environment: 'production' } +}); + +// Working directory context +const workdirModifier = new WorkingDirectoryMessageModifier({ + includePath: true, + includeFileList: false, + excludePatterns: ['node_modules', '.git'] +}); + +// System instruction enhancement +const systemModifier = new BaseSystemInstructionMessageModifier({ + instructions: 'Additional context...', + appendToExisting: true +}); + +// Image attachment processing +const imageModifier = new ImageAttachmentMessageModifier({ + maxSize: 10 * 1024 * 1024, + supportedFormats: ['jpg', 'png', 'pdf'], + enableOCR: true +}); + +// Tools list injection +const toolsModifier = new AddToolsListMessageModifier({ + includeDescriptions: true, + formatAsMarkdown: true, + groupByCategory: true +}); +``` + +## Built-in Tools + +Pre-built tools for common operations. + +```typescript +// FUTURE - NOT YET IMPLEMENTED +import { + FileReadTool, + FileWriteTool, + FileDeleteTool, + FileMoveTool, + FileCopyTool +} from '@codebolt/agent/unified'; + +const agent = new CodeboltAgent({ + instructions: 'You help users manage files.', + tools: [ + new FileReadTool(), + new FileWriteTool(), + new FileDeleteTool(), + new FileMoveTool(), + new FileCopyTool() + ] +}); +``` + +## Contributing + +If you're interested in contributing to any of these features, please: + +1. Check the GitHub issues for related discussions +2. Review the existing codebase in `packages/agent/src/` +3. Submit a pull request with your implementation + +## Status Tracking + +| Feature | Status | Target Version | +|---------|--------|----------------| +| Orchestrator System | Planned | TBD | +| Specialized Tool Creators | Planned | TBD | +| TelemetryProcessor | Planned | TBD | +| TokenManagementProcessor | Planned | TBD | +| ResponseValidationProcessor | Planned | TBD | +| FollowUpConversationProcessor | Planned | TBD | +| ConversationContinuityProcessor | Planned | TBD | +| ContextManagementProcessor | Planned | TBD | +| AdvancedLoopDetectionProcessor | Planned | TBD | +| LocalToolInterceptorProcessor | Planned | TBD | +| HandleUrlMessageModifier | Planned | TBD | +| BaseContextMessageModifier | Planned | TBD | +| WorkingDirectoryMessageModifier | Planned | TBD | +| BaseSystemInstructionMessageModifier | Planned | TBD | +| ImageAttachmentMessageModifier | Planned | TBD | +| AddToolsListMessageModifier | Planned | TBD | +| Built-in File Tools | Planned | TBD | diff --git a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/README.md b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/README.md index 522a8c5a..2a3be643 100644 --- a/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/README.md +++ b/documentation/mainfolder/docs/3_CustomAgents/agentPatterns/5-unified/README.md @@ -2,65 +2,59 @@ Welcome to the comprehensive documentation for the **Unified Agent Framework** - a powerful, self-contained system for building sophisticated AI agents with advanced capabilities. -## 📚 Documentation Structure +## Documentation Structure ### [1. Introduction & Overview](./1-unified.md) - **What is the Unified Framework?** - Core concepts and benefits - **Architecture Overview** - Layered system design -- **Core Components** - Agents, Tools, Workflows, Orchestrators +- **Core Components** - Agents, Tools, Workflows - **Getting Started** - Installation and basic examples -- **Key Benefits** - Why choose the Unified Framework +- **Available Exports** - Complete list of available APIs ### [2. Agents](./2-agents.md) -- **Creating Agents** - Agent configuration and setup -- **Agent Execution** - Running agents with various options -- **Agent as a Tool** - Converting agents for use by other agents -- **Managing Agent Tools** - Dynamic tool management -- **Agent Workflows** - Workflow integration -- **Advanced Features** - Context management, error handling, monitoring -- **Agent Patterns** - Specialist, supervisor, and multi-modal agents +- **Creating Agents** - Using `CodeboltAgent` and `Agent` classes +- **Agent Execution** - Running agents with messages +- **Agent Configuration** - Tools and processor setup +- **Agent Patterns** - Specialist agents and best practices +- **Available Processors** - Complete list of processors by category ### [3. Tools](./3-tools.md) -- **Creating Tools** - Basic and specialized tool creation -- **Tool Types** - Text, file, HTTP, validation, and transform tools +- **Creating Tools** - Using `createTool()` and `Tool` class +- **Tool Configuration** - Input schemas with Zod - **Tool Execution** - Direct execution and error handling -- **Built-in Tools** - File operations, web tools, and more -- **Advanced Features** - Tool chaining, conditional execution, async operations -- **Tool Testing** - Unit and integration testing strategies -- **Performance Optimization** - Caching, batching, and optimization techniques +- **OpenAI Format** - Converting tools for LLM APIs +- **Advanced Features** - Tool chaining, async tools, caching ### [4. Processors](./4-processors.md) -- **Processor Categories** - Message, conversation, tool, monitoring, and context processors -- **Message Processors** - URL handling, context enhancement, image processing -- **Conversation Management** - Compaction, continuity, and follow-up enhancement -- **Tool Execution Processors** - Validation, interception, and parameter modification -- **System Monitoring** - Loop detection, token management, telemetry -- **Context Management** - Persistent context and memory management -- **Custom Processors** - Creating your own processors -- **Configuration Best Practices** - Environment-specific setups +- **Processor Categories** - Message modifiers, inference processors, tool processors +- **Available Processors** - Complete reference for all processors +- **Using Processors** - Configuration in agents +- **Execution Flow** - How processors interact ### [5. Examples & Best Practices](./5-examples-and-best-practices.md) - **Complete Applications** - Customer support, content creation, data analysis -- **Best Practices** - Agent design, tool organization, workflow patterns -- **Error Handling** - Comprehensive error management strategies -- **Performance Optimization** - Resource management and parallel execution -- **Testing Strategies** - Unit, integration, and end-to-end testing -- **Monitoring & Observability** - Production monitoring and health checks -- **Migration Guide** - Moving from other agent patterns +- **Best Practices** - Agent design, tool organization, error handling +- **Testing Strategies** - Unit and integration testing +- **Debugging** - Using ChatRecordingModifier -## 🚀 Quick Start +### [6. Roadmap](./6-roadmap.md) +- **Future Features** - Planned but not yet implemented APIs +- **Orchestrator System** - Coming soon +- **Advanced Processors** - Coming soon +- **Built-in Tools** - Coming soon + +## Quick Start ```typescript -import { createAgent, createTool } from '@codebolt/agent/unified'; +import { CodeboltAgent, createTool } from '@codebolt/agent/unified'; import { z } from 'zod'; // Create a simple tool const weatherTool = createTool({ id: 'weather', - name: 'Get Weather', description: 'Get current weather for a location', inputSchema: z.object({ location: z.string() }), - execute: async ({ input }) => ({ + execute: async ({ input }) => ({ location: input.location, temperature: '72°F', condition: 'Sunny' @@ -68,143 +62,84 @@ const weatherTool = createTool({ }); // Create an agent -const weatherAgent = createAgent({ - name: 'Weather Assistant', +const weatherAgent = new CodeboltAgent({ instructions: 'You help users get weather information.', tools: [weatherTool] }); // Use the agent -const result = await weatherAgent.execute('What\'s the weather in New York?'); -console.log(result.response); +const result = await weatherAgent.execute({ + role: 'user', + content: 'What\'s the weather in New York?' +}); +console.log(result); ``` -## 🏗️ Framework Architecture +## Framework Architecture -The Unified Framework is built on a layered architecture that provides maximum flexibility and scalability: +The Unified Framework is built on a layered architecture: ``` ┌─────────────────────────────────────────────────────────────┐ -│ ORCHESTRATOR LAYER │ -│ 🎯 Dynamic coordination of agents, workflows, and tools │ -├─────────────────────────────────────────────────────────────┤ │ WORKFLOW LAYER │ -│ 📋 Structured multi-step processes with dependencies │ +│ Structured multi-step processes with context management │ ├─────────────────────────────────────────────────────────────┤ │ AGENT LAYER │ -│ 🤖 Intelligent agents with conversation management │ +│ Intelligent agents with conversation management │ ├─────────────────────────────────────────────────────────────┤ │ TOOL LAYER │ -│ 🔧 Individual functions and capabilities │ +│ Individual functions and capabilities │ ├─────────────────────────────────────────────────────────────┤ │ PROCESSOR LAYER │ -│ ⚙️ Extensible components for customizing behavior │ +│ Extensible components for customizing behavior │ └─────────────────────────────────────────────────────────────┘ ``` -## 🔧 Available Processors - -The framework includes comprehensive processors from the `@processor-pieces` library: - -### Message Processors -- **HandleUrlMessageModifier** - Extract content from URLs -- **BaseContextMessageModifier** - Add contextual information -- **WorkingDirectoryMessageModifier** - Include directory context -- **BaseSystemInstructionMessageModifier** - Enhance system instructions -- **ImageAttachmentMessageModifier** - Process image attachments -- **AddToolsListMessageModifier** - Add available tools list - -### Conversation Management -- **ConversationCompactorProcessor** - Compact long conversations -- **FollowUpConversationProcessor** - Enhance follow-up conversations -- **ConversationContinuityProcessor** - Maintain conversation continuity -- **ChatCompressionProcessor** - Compress chat history - -### Tool Execution -- **LocalToolInterceptorProcessor** - Intercept and handle custom tools -- **ToolValidationProcessor** - Validate tool inputs and outputs -- **ToolParameterModifierProcessor** - Modify tool parameters - -### System Monitoring -- **LoopDetectionProcessor** - Detect and prevent infinite loops -- **AdvancedLoopDetectionProcessor** - Advanced semantic loop detection -- **TokenManagementProcessor** - Manage token usage -- **ResponseValidationProcessor** - Validate response quality -- **TelemetryProcessor** - Collect telemetry and metrics -- **ChatRecordingProcessor** - Record conversations - -### Context Management -- **ContextManagementProcessor** - Comprehensive context management - -### Built-in Tools -- **FileReadTool, FileWriteTool, FileDeleteTool** - File operations -- **FileMoveTool, FileCopyTool** - File management - -## 🎯 Key Features - -### ✅ **Self-Contained** -- All dependencies are internal -- No external package dependencies -- Works out of the box - -### ✅ **Type-Safe** -- Full TypeScript support -- Comprehensive type definitions -- Runtime validation with Zod - -### ✅ **Extensible** -- Custom processors -- Custom tools -- Custom workflows -- Plugin architecture - -### ✅ **Production-Ready** -- Comprehensive error handling -- Performance monitoring -- Resource management -- Health checks - -### ✅ **Developer-Friendly** -- Intuitive APIs -- Extensive documentation -- Rich examples -- Testing utilities - -## 🛠️ Use Cases - -The Unified Framework is perfect for: - -- **Customer Support Systems** - Multi-agent support with escalation -- **Content Creation Pipelines** - Research, writing, and editing workflows -- **Data Analysis Platforms** - Collection, analysis, and reporting -- **Multi-Domain Applications** - Specialized agents for different domains -- **Complex Orchestration** - Dynamic resource coordination -- **Workflow Automation** - Structured multi-step processes - -## 📖 Learning Path +## Available Processors -1. **Start Here**: Read the [Introduction & Overview](./1-unified.md) -2. **Build Your First Agent**: Follow the [Agents](./2-agents.md) guide -3. **Add Custom Tools**: Learn about [Tools](./3-tools.md) -4. **Enhance with Processors**: Explore [Processors](./4-processors.md) -5. **Build Complete Systems**: Study [Examples & Best Practices](./5-examples-and-best-practices.md) +All processors are imported from `@codebolt/agent/processor-pieces`: + +### Message Modifiers +- `EnvironmentContextModifier` - Add environment context +- `CoreSystemPromptModifier` - Core system prompt handling +- `DirectoryContextModifier` - Working directory context +- `IdeContextModifier` - IDE integration context +- `AtFileProcessorModifier` - Process @file references +- `ArgumentProcessorModifier` - Process arguments +- `MemoryImportModifier` - Import memory context +- `ToolInjectionModifier` - Inject tool descriptions +- `ChatRecordingModifier` - Record chat history +- `ChatHistoryMessageModifier` - Include chat history -## 🤝 Support +### PreInference Processors +- `ChatCompressionModifier` - Compress chat history -- **Documentation**: Comprehensive guides and examples -- **Examples**: Real-world application examples -- **Best Practices**: Production-ready patterns -- **Migration Guide**: Moving from other frameworks +### PostInference Processors +- `LoopDetectionModifier` - Detect execution loops -## 🔄 Migration +### PreToolCall Processors +- `ToolParameterModifier` - Modify tool parameters +- `ToolValidationModifier` - Validate tool calls -Moving from other agent patterns? Check out our [Migration Guide](./5-examples-and-best-practices.md#migration-guide) for step-by-step instructions on migrating from: +### PostToolCall Processors +- `ConversationCompactorModifier` - Compact conversations +- `ShellProcessorModifier` - Process shell output -- ComposableAgent pattern -- Builder pattern -- Processor pattern -- Custom implementations +## Key Features + +- **Self-Contained** - All dependencies are internal +- **Type-Safe** - Full TypeScript support with Zod validation +- **Extensible** - Custom processors, tools, and workflows +- **Production-Ready** - Comprehensive error handling + +## Learning Path + +1. **Start Here**: Read the [Introduction & Overview](./1-unified.md) +2. **Build Your First Agent**: Follow the [Agents](./2-agents.md) guide +3. **Add Custom Tools**: Learn about [Tools](./3-tools.md) +4. **Enhance with Processors**: Explore [Processors](./4-processors.md) +5. **Build Complete Systems**: Study [Examples & Best Practices](./5-examples-and-best-practices.md) --- -**Ready to build powerful AI agents?** Start with the [Introduction & Overview](./1-unified.md) and begin your journey with the Unified Agent Framework! +**Ready to build powerful AI agents?** Start with the [Introduction & Overview](./1-unified.md)! diff --git a/documentation/mainfolder/docs/3_CustomAgents/processors/1_processorTypes.md b/documentation/mainfolder/docs/3_CustomAgents/processors/1_processorTypes.md index 9c81061e..5056e64e 100644 --- a/documentation/mainfolder/docs/3_CustomAgents/processors/1_processorTypes.md +++ b/documentation/mainfolder/docs/3_CustomAgents/processors/1_processorTypes.md @@ -1,61 +1,165 @@ # Processor Types -There are multiple types of processors: -1. **Message Modifiers**: These are the ones that modify the message from the user Message to the prompt. - - This is a single Type as it is simple Prompt type. - - This has the format of calling ***modify*** function and passing - ``` - {originalRequest, createdMessage, and some Context - ``` - This returns: - ``` - createdMessage - ``` - - This is called by the InitialPromptGenerator - -2. **PreInferenceProcessors**: This is called before the Agent calls the LLM. - - This is Called by AgentStep - - Called before the LLM Calling Step - - The ***Modify*** function is called which gets: - ``` - IntialUserMessage, currentMessage, exitEvent - ``` - This returns: - ``` - currentMessage - ``` - -3. **PostInferenceProcessors**: This is called by Agent after the LLM is called and we have gotten the response. This is before the actual Tool Call is done. - - This is Called after Inference Processor. - - This is Mostly used for things like Response Validation - - The Modify function is called which gets: - ``` - llmmessagesent, llmresponsemessage, nextprompt, context - ``` - - This will give output: - ``` - nextprompt, context - ``` - - The lllminferencetriggerEvent is an event that triggers the recalling of the LLM Inference. This is usually for cases where lets say the llm has not given a proper response. We need to send the updated message along with the llminferenceTriggerEvent. - - The Exit Event is an event that exists the system and sends an error. This is in case lets say the inference is in loop, or other things. In that Case the next Step is not able to proceed. - -1. **PreToolCallProcessors**: This is the processor called before the Tool Call. This is used to check if the Tool Call is proper. This is also used to handle the Local Tool Interceptor or any other custom exotic tool Processor. - - This will get the inputs: - ``` - llmMessagesent, llmresponsemessage, nextprompt context - ``` - - This will give the result as - ``` - nextpromt, context, shouldexit - ``` -2. **PostToolCallProcessors**: This is the Processor called after the Tool Call. This can help in checking the tool Calls Result and also adding it to the llmMessage. This LLM Message will be used as prompt for the next time. - - This will ge the inputs: - ``` - userMessage, llmmessageSent, llmresponsemessage,nextprompt, context - ``` - - This will give result - ``` - nextprompt, context - ``` \ No newline at end of file +Processors are extensible components that modify behavior at different stages of agent execution. All processors use the `*Modifier` suffix and are imported from `@codebolt/agent/processor-pieces`. + +## Types of Processors + +### 1. Message Modifiers + +Transform user messages into prompts. Called by the `InitialPromptGenerator`. + +**Interface:** +```typescript +// Input +{ + originalRequest, + createdMessage, + context +} + +// Output +{ + createdMessage +} +``` + +**Available Modifiers:** +- `EnvironmentContextModifier` - Add environment context +- `CoreSystemPromptModifier` - Core system prompt handling +- `DirectoryContextModifier` - Working directory context +- `IdeContextModifier` - IDE integration context +- `AtFileProcessorModifier` - Process @file references +- `ArgumentProcessorModifier` - Process arguments +- `MemoryImportModifier` - Import memory context +- `ToolInjectionModifier` - Inject tool descriptions +- `ChatRecordingModifier` - Record chat history +- `ChatHistoryMessageModifier` - Include chat history + +### 2. PreInference Processors + +Run before the LLM is called. Called by `AgentStep`. + +**Interface:** +```typescript +// Input +{ + initialUserMessage, + currentMessage, + exitEvent +} + +// Output +{ + currentMessage +} +``` + +**Available Processors:** +- `ChatCompressionModifier` - Compress chat history to reduce tokens + +### 3. PostInference Processors + +Run after LLM response, before tool execution. Called by `AgentStep`. + +**Interface:** +```typescript +// Input +{ + llmMessageSent, + llmResponseMessage, + nextPrompt, + context +} + +// Output +{ + nextPrompt, + context +} +``` + +Special events: +- `llmInferenceTriggerEvent` - Triggers re-calling the LLM (e.g., for invalid responses) +- `exitEvent` - Exits the system with an error (e.g., for detected loops) + +**Available Processors:** +- `LoopDetectionModifier` - Detect and prevent infinite loops + +### 4. PreToolCall Processors + +Run before tool execution. Called by `ResponseExecutor`. + +**Interface:** +```typescript +// Input +{ + llmMessageSent, + llmResponseMessage, + nextPrompt, + context +} + +// Output +{ + nextPrompt, + context, + shouldExit +} +``` + +**Available Processors:** +- `ToolParameterModifier` - Modify tool parameters before execution +- `ToolValidationModifier` - Validate tool calls before execution + +### 5. PostToolCall Processors + +Run after tool execution. Called by `ResponseExecutor`. + +**Interface:** +```typescript +// Input +{ + userMessage, + llmMessageSent, + llmResponseMessage, + nextPrompt, + context +} + +// Output +{ + nextPrompt, + context +} +``` + +**Available Processors:** +- `ConversationCompactorModifier` - Compact long conversations +- `ShellProcessorModifier` - Process shell command outputs + +## Import Example + +```typescript +import { + // Message Modifiers + EnvironmentContextModifier, + CoreSystemPromptModifier, + DirectoryContextModifier, + ToolInjectionModifier, + ChatRecordingModifier, + + // PreInference Processors + ChatCompressionModifier, + + // PostInference Processors + LoopDetectionModifier, + + // PreToolCall Processors + ToolParameterModifier, + ToolValidationModifier, + + // PostToolCall Processors + ConversationCompactorModifier, + ShellProcessorModifier +} from '@codebolt/agent/processor-pieces'; +``` diff --git a/documentation/mainfolder/docs/3_CustomAgents/processors/2_Functions.md b/documentation/mainfolder/docs/3_CustomAgents/processors/2_Functions.md index 761ee316..61cb39d9 100644 --- a/documentation/mainfolder/docs/3_CustomAgents/processors/2_Functions.md +++ b/documentation/mainfolder/docs/3_CustomAgents/processors/2_Functions.md @@ -1,55 +1,146 @@ -There will be three functions: -1. **Initial Prompt Generator** - This is the Initial Prompt Generator Function that Converts the input Message by the user into a prompt that can be sent to the user. - - This uses one type of Processor: - - **Message Modifiers** This is the modifier that converts the userMessage to the Initial Prompt. - - This has the following input: - - UserMessage - Initial Message the User has sent - - Context - This is important for Inter-Processor Communication. In case one Processor wants to communicate with another processor, then it should use this context to pass the variables to the processor. - - BaseSystemPrompt - This is a base system prompt that is used to create the initial message - - MessageModifierPrompts - This is the list of Message Modifiers that are to be applied to the InitialMessage - - Output: - - Created Message - This is the message that is usually sent to the LLM. (There will be additional PreLLMProcessors that the Agent Step may Apply before sending to the LLM) - - Context - This is a Broader Context Object for Inter Step and Inter Processor Communication - -2. **AgentStep** - This is the Agent Step that takes the User Message and then passes it to the LLM and then gives the LLM Output. - - This uses two Processors: - - **PreInferenceProcessors** - The PreInference Processor is the processor that runs before the Inference is called. - - **PostInferenceProcessors** - This is the processor that is called after the inference is run. This is primarily used for testing. - - This has the following Input: - - InitialUserMessage - Although this is not used too much, but still it can be passed so that any Processor can use it. - - Created Message - This is the output of the Initial Prompt Generator Function, or if this is calling the second time then this is the prompt result of the first step. - - PreInferenceProcessors - This is the list of PreInferenceProcessors that have to be applied. - - PostInferenceProcessors - This is the postInferenceProcessors that have to be applied. - - LLMConfig - This is the LLM Config that can be added like temperature etc. - - This has the following output: - - rawLLMOutput - This is the actual Raw LLM output - - nextMessage - This is the basic nextMessage. Although this does not has the Tool Call but this gives some basic Data. - - context - This is the Context that is passed across - - -3. ResponseExecutor - This is the Executor Function that handles the Tool Execution. This executes the tools and then gives the output prompt by combining the tool Call Results and the initial prompt. - - This uses two Processors: - - **PreToolCallProcessors** - This is the processor that is called before the Tool Call. This is primarily used for checking if the tool call Requirement is proper and correct. - - **PostToolCallProcessors** - This is the processor that is called after the tool Call. This is where it will process the output of the Tool Call and update the prompt Message based on that Tool Call Result. - - This has the following input: - - UserMessage - - RawLLMOutput - - NextMessage - Here the NextMessage Should ideally contain the message that was sent to the llm. So we need not - - PreToolCallProcessors - - PostToolCallProcessors - - This has the following output: - - NextPrompt - This is the actual next prompt that has to be passed next time to the agent - - context - the running context - \ No newline at end of file +# Core Functions + +The agent framework uses three core functions that handle the execution pipeline. Each function uses specific processor types. + +## 1. InitialPromptGenerator + +Converts the user's input message into a prompt that can be sent to the LLM. + +**Uses:** Message Modifiers + +### Input +- **UserMessage** - Initial message from the user +- **Context** - Object for inter-processor communication +- **BaseSystemPrompt** - Base system prompt to build upon +- **MessageModifiers** - List of Message Modifiers to apply + +### Output +- **CreatedMessage** - The prompt to send to the LLM (may be modified by PreInference Processors before sending) +- **Context** - Updated context object + +### Available Message Modifiers + +```typescript +import { + EnvironmentContextModifier, + CoreSystemPromptModifier, + DirectoryContextModifier, + IdeContextModifier, + AtFileProcessorModifier, + ArgumentProcessorModifier, + MemoryImportModifier, + ToolInjectionModifier, + ChatRecordingModifier, + ChatHistoryMessageModifier +} from '@codebolt/agent/processor-pieces'; +``` + +## 2. AgentStep + +Handles the LLM inference step. Takes the prompt and passes it to the LLM. + +**Uses:** PreInference Processors, PostInference Processors + +### Input +- **InitialUserMessage** - Original user message (available for processors) +- **CreatedMessage** - Output from InitialPromptGenerator (or previous step) +- **PreInferenceProcessors** - Processors to run before LLM call +- **PostInferenceProcessors** - Processors to run after LLM call +- **LLMConfig** - Configuration for the LLM (temperature, etc.) + +### Output +- **RawLLMOutput** - Raw response from the LLM +- **NextMessage** - Processed message for next step +- **Context** - Updated context object + +### Available Processors + +```typescript +import { + // PreInference + ChatCompressionModifier, + + // PostInference + LoopDetectionModifier +} from '@codebolt/agent/processor-pieces'; +``` + +## 3. ResponseExecutor + +Handles tool execution and updates the prompt based on tool results. + +**Uses:** PreToolCall Processors, PostToolCall Processors + +### Input +- **UserMessage** - Original user message +- **RawLLMOutput** - Response from the LLM +- **NextMessage** - The message that was sent to the LLM +- **PreToolCallProcessors** - Processors to validate/modify tool calls +- **PostToolCallProcessors** - Processors to process tool results + +### Output +- **NextPrompt** - Updated prompt for the next iteration +- **Context** - Updated context object + +### Available Processors + +```typescript +import { + // PreToolCall + ToolParameterModifier, + ToolValidationModifier, + + // PostToolCall + ConversationCompactorModifier, + ShellProcessorModifier +} from '@codebolt/agent/processor-pieces'; +``` + +## Execution Flow + +``` +User Message + │ + ▼ +┌─────────────────────────────────────┐ +│ InitialPromptGenerator │ +│ (applies Message Modifiers) │ +└─────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ AgentStep │ +│ 1. PreInference Processors │ +│ 2. LLM Call │ +│ 3. PostInference Processors │ +└─────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ ResponseExecutor │ +│ 1. PreToolCall Processors │ +│ 2. Tool Execution │ +│ 3. PostToolCall Processors │ +└─────────────────────────────────────┘ + │ + ▼ + Next Iteration (back to AgentStep) + or Final Response +``` + +## Context Object + +The context object enables inter-processor and inter-step communication: + +```typescript +interface Context { + // Built-in fields + userId?: string; + sessionId?: string; + + // Custom fields added by processors + [key: string]: unknown; +} +``` + +Processors can read from and write to the context to share state.