Carity AI Agent

A powerful AI agent orchestrator designed for n8n workflows with multi-tool call support and intelligent data processing.

Features

• 🤖 Multi-Tool Orchestration: Execute multiple AI tools in sequence based on LLM decisions
• 🔄 Intelligent Data Processing: Automatic data normalization and parsing
• 🛠️ n8n Integration: Seamless integration with n8n LangChain code nodes
• 📊 Flexible Configuration: Customizable field mapping and tool parameters
• 🎯 Error Handling: Robust error handling and detailed error reporting
• 📝 TypeScript Support: Full TypeScript definitions for better development experience

Installation

npm install carity-ai-agent

Quick Start

Basic Usage in n8n LangChain Code Node

Replace your entire code node content with:

const { executeWithMultipleToolCalls } = require('carity-ai-agent');

const result = await executeWithMultipleToolCalls.call(this);
return [{ json: result }];

Input Data Structure

Your n8n workflow should provide input data in this format:

{
  "userPrompt": "Find information about the user and create a summary",
  "systemPrompt": "You are an AI assistant that can use multiple tools. Use TOOL_CALL: {\"tool_name\": \"tool_name\", \"parameters\": {...}} format to call tools.",
  "fieldsConfig": {
    "user_search": {
      "name": "user.name",
      "email": "user.email",
      "status": "user.status"
    }
  }
}

Advanced Usage

Using Individual Utility Functions

const {
  getValueByPath,
  normalizeData,
  findToolByName,
  parseToolResult
} = require('carity-ai-agent');

// Extract nested data
const values = getValueByPath(data, ['users', '[]', 'profile', 'name']);

// Normalize data with field configuration
const normalized = normalizeData('user_tool', rawData, fieldsConfig);

// Find tool by name (with fuzzy matching)
const tool = findToolByName(availableTools, 'user_search');

How It Works

1. Input Processing: Extracts user prompt, system prompt, and field configuration from n8n input
2. LLM Invocation: Calls the connected Language Model with the prompts
3. Tool Call Extraction: Parses TOOL_CALL: statements from LLM response
4. Tool Execution: Executes requested tools with formatted parameters
5. Result Processing: Processes and normalizes tool results
6. Response Formatting: Returns structured response with all tool outputs

Tool Call Format

The LLM should respond with tool calls in this format:

TOOL_CALL: {"tool_name": "search_users", "parameters": {"query": "john doe"}}
TOOL_CALL: {"tool_name": "create_summary", "parameters": {"data": "user information"}}

Configuration

Fields Configuration

Define how to extract and normalize data from tool responses:

const fieldsConfig = {
  "search_users": {
    "name": "results[].user.name",
    "email": "results[].user.email",
    "department": "results[].user.department"
  },
  "get_orders": {
    "order_id": "orders[].id",
    "amount": "orders[].total",
    "status": "orders[].status"
  }
};

Special Tool Types

The agent handles different tool types automatically:

• GraphQL Tools: Automatically formats parameters for GraphQL queries
• Retrieval Tools: Special handling for retrieve_chunks tools
• JSON Tools: Direct JSON parsing for ymmt_cjson tools
• Standard Tools: Generic parameter formatting for other tools

Response Structure

{
  "output": {
    "RetrievalToolResponses": [...], // From retrieval tools
    "response": {
      "tool_name": [...], // Normalized results from other tools
      // or array of multiple tool responses
    }
  }
}

Error Handling

The agent provides detailed error information:

{
  "error": "Tool 'unknown_tool' not available",
  "available_tools": ["search_users", "create_summary"],
  "tool_call": 1
}

Examples

Example 1: User Search and Summary

// Input
{
  "userPrompt": "Find user John Doe and create a summary",
  "systemPrompt": "Use TOOL_CALL format to search for users and create summaries",
  "fieldsConfig": {
    "user_search": {
      "name": "user.name",
      "email": "user.email"
    }
  }
}

// LLM Response
"I'll search for the user first.
TOOL_CALL: {\"tool_name\": \"user_search\", \"parameters\": {\"name\": \"John Doe\"}}

Now I'll create a summary.
TOOL_CALL: {\"tool_name\": \"create_summary\", \"parameters\": {\"user_data\": \"John Doe info\"}}"

Example 2: Multiple Data Sources

// Connect multiple tools in n8n and let the LLM decide which to use
const result = await executeWithMultipleToolCalls.call(this);

// Result might include data from multiple tools:
{
  "output": {
    "response": [
      {"user_search": [{"name": "John Doe", "email": "[email protected]"}]},
      {"order_lookup": [{"order_id": "12345", "amount": "$100"}]}
    ]
  }
}

API Reference

Main Functions

executeWithMultipleToolCalls()

Main orchestrator function. Must be called with n8n context using .call(this).

Returns: Promise<OrchestrationResult>

Utility Functions

getValueByPath(obj, pathParts)

Extract values using path notation including array handling.

normalizeData(toolName, data, configMap)

Normalize data using field configuration mapping.

findToolByName(tools, name)

Find tool by name with fuzzy matching (ignores case, spaces, underscores).

parseToolResult(toolName, raw, configMap)

Parse and normalize tool execution results.

TypeScript Support

Full TypeScript definitions are included:

import { executeWithMultipleToolCalls, FieldsConfig } from 'carity-ai-agent';

const config: FieldsConfig = {
  "user_tool": {
    "name": "user.name",
    "email": "user.email"
  }
};

Requirements

• Node.js >= 14.0.0
• n8n workflow environment
• Connected Language Model in n8n
• Connected AI Tools in n8n

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub issues page.