node-red-contrib-ai-agent 0.0.3 → 0.0.4

package/README.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-A powerful AI Agent for Node-RED that enables natural language processing and tool integration. This node allows you to create AI-powered flows with support for function calling and external tool integration.
+A powerful AI Agent for Node-RED that enables natural language processing with memory and tool integration. This package provides nodes for creating AI-powered flows with conversation context management and extensible tool integration.
 
 ## ⚠️ Beta Notice
 
@@ -18,42 +18,165 @@ Your feedback and contributions are highly appreciated!
 
 ## Features
 
-- Integration with OpenRouter's AI models
-- Support for function calling and tool execution
-- Easy configuration through Node-RED's interface
-- Conversation context management
-- Extensible with custom tools
+- **AI Agent Node**: Process messages with AI, maintaining conversation context
+- **Memory Nodes**: 
+  - **In-Memory**: Store conversation context in memory (volatile)
+  - **File-based**: Persist conversation context to disk
+- **AI Model Node**: Configure AI models and API settings
+- **Tool Integration**: Extend functionality with custom tools
+- **Stateless Design**: Memory nodes are stateless, making them more reliable and scalable
+- **Context Management**: Automatic conversation history management with configurable retention
 
 ## Getting Started
 
 1. Install the package via the Node-RED palette manager
 2. Add an AI Model node to configure your OpenRouter API key and model
-3. Add AI Tool nodes to define custom functions
-4. Connect to an AI Agent node to process messages
+3. (Optional) Add a Memory node (In-Memory or File-based) to manage conversation context
+4. (Optional) Add AI Tool nodes to define custom functions or HTTP requests
+5. Connect to an AI Agent node to process messages
+6. (Optional) Connect more AI Agent nodes to process messages in a chain
+
+##
+
+## Node Types
+
+### AI Agent
+Processes messages using the configured AI model and maintains conversation context through connected memory nodes.
+
+**Properties:**
+- **Name**: Display name for the node
+- **System Prompt**: Initial instructions for the AI
+- **Response Type**: Format of the response (text or JSON object)
+
+### Memory (In-Memory)
+A configuration node that initializes the conversation context in memory. The agent node uses this configuration to manage the conversation context.
+
+**Properties:**
+- **Max Items**: Maximum number of conversation turns to keep in memory
+- **Name**: Display name for the node
+
+### Memory (File)
+A configuration node that initializes the conversation context with file-based persistence. The agent node uses this configuration to manage the conversation context across restarts.
+
+**Properties:**
+- **Max Items**: Maximum number of conversation turns to keep
+- **File Path**: Path to store the conversation history
+- **Name**: Display name for the node
+
+### AI Model
+Configures the AI model and API settings.
+
+**Properties:**
+- **Model**: The AI model to use (e.g., gpt-4, claude-3-opus)
+- **API Key**: Your OpenRouter API key
+- **Name**: Display name for the node
+
+### AI Tool Function
+Creates a JavaScript function tool that can be used by the AI Agent.
+
+**Properties:**
+- **Name**: Display name for the node
+- **Tool Name**: Name of the tool (used by the AI to identify the tool)
+- **Description**: Description of what the tool does
+- **Function**: JavaScript code to execute when the tool is called
+
+### AI Tool HTTP
+Creates an HTTP request tool that can be used by the AI Agent to make external API calls.
+
+**Properties:**
+- **Name**: Display name for the node
+- **Tool Name**: Name of the tool (used by the AI to identify the tool)
+- **Description**: Description of what the tool does
+- **Method**: HTTP method (GET, POST, PUT, DELETE, etc.)
+- **URL**: The URL to make the request to (supports template variables)
+- **Headers**: JSON object of headers to include in the request
+- **Body**: Content to send in the request body
+
+**Template Variables:**
+You can use template variables in the URL, headers, and body to reference properties from the input object that the AI provides when calling the tool.
+
+Example: `https://api.example.com/users/${input.userId}`
 
-## Example: Today's Joke
+## Example: Basic Usage
 
-Here's an example flow that tells a joke related to today's date using a custom tool:
+Here's how to use the AI Agent:
 
-![Today's Joke Flow](https://raw.githubusercontent.com/lesichkovm/node-red-contrib-ai-agent/refs/heads/main/snapshots/todays-joke-flow.png "Example flow showing the Today's Joke implementation")
+1. Add an AI Agent node to your flow
+2. Configure it with an AI Model node
+3. (Optional) Add a Memory configuration node if you need conversation context
+4. Connect your flow: `[Input] --> [AI Model] --> [AI Agent] --> [Output]`
 
-### Flow Output
+Memory is only required if you need to maintain conversation context between messages or chain multiple agents together. For simple, stateless interactions, you can use the AI Agent without any memory configuration.
 
-When executed, the flow will generate a joke related to the current date:
+## Example: Using AI Tools
 
-![Today's Joke Output](https://raw.githubusercontent.com/lesichkovm/node-red-contrib-ai-agent/refs/heads/main/snapshots/todays-joke.png "Example output showing a date-related joke")
+To extend the AI Agent with custom tools:
 
-## Basic Usage
+1. Add an AI Tool Function or AI Tool HTTP node to your flow
+2. Configure the tool with appropriate settings
+3. Connect the tool to the AI Agent: `[Input] --> [AI Model] --> [AI Tool] --> [AI Agent] --> [Output]`
 
-1. **AI Model Node**: Configure your AI model and API settings
-2. **AI Tool Node**: Define custom functions and tools
-3. **AI Agent Node**: Process messages with AI and tool integration
+The AI Agent will automatically detect and use the tools in its processing. You can add multiple tools to give the AI Agent different capabilities.
+
+### HTTP Tool Example
+
+```
+[AI Tool HTTP] --> |
+                     |--> [AI Agent] --> [Output]
+[AI Tool Function] --> |
+```
+
+In this example, the AI Agent has access to both an HTTP tool for making external API calls and a function tool for custom logic.
+
+## Example: Chained Agents
+
+For more complex scenarios, you can chain multiple agents to process messages in sequence:
+
+1. Create Memory node (it will init the context, it will be shared between agents)
+2. Configure Agent 1
+3. Configure Agent 2
+4. Connect your flow: `[Input] --> [AI Model] --> [AI Memory] --> [Agent 1] --> [Agent 2] --> [Output]`
+
+Each agent will maintain its own conversation context based on its memory configuration.
+
+## Best Practices
+
+### Memory Management
+- Memory nodes are configuration nodes that define how conversation context is managed
+- Each AI Agent node references a memory configuration
+- The memory configuration is instantiated once and can be shared between multiple agents
+- The AI Agent node is responsible for managing and updating the conversation context based on its memory configuration
+- Memory configurations are particularly useful in chained agent scenarios where different agents need different context handling
+- Use **In-Memory** configuration for temporary conversations
+- Use **File-based** configuration for conversations that should persist across restarts
+- Set appropriate `maxItems` to control context length and memory usage
+
+### Error Handling
+- Always handle errors from the AI Agent node
+- Check for API key and model configuration errors
+- Monitor memory usage with large conversation histories
+
+### Performance
+- For high-volume applications, consider using a database-backed memory implementation
+- Be mindful of token usage with large contexts
+- Use appropriate timeouts for API calls
+
+## Advanced: Chaining Agents
+
+You can chain multiple AI Agents with different memory scopes to create complex conversation flows:
+
+```
+[Input] -->[Memory 1] --> [Agent 1] --> [Agent 2] --> [Memory 2] --> [Agent 3] --> [Agent 4] --> [Output]
+```
+
+This allows for complex conversation flows where different agents handle different aspects of the interaction.
 
 ## Advanced Features
 
-- **Tool Integration**: Extend functionality with custom tools
+- **Tool Integration**: Extend functionality with custom tools (Function and HTTP)
 - **Context Management**: Maintain conversation history
 - **Flexible Configuration**: Customize model parameters and behavior
+- **Template Variables**: Use dynamic values in HTTP requests
 
 ## Contributing