agente-toolkit

A modern TypeScript library for building AI agents with native tool calling and intelligent orchestration patterns. Features both single-agent execution and intelligent manager agents that automatically discover and route to specialized agents.

🚀 Key Features

Native Tool Calling Support

• Claude Native Integration: Leverages Anthropic's built-in tool calling for optimal performance
• Automatic Fallback: Gracefully falls back to traditional planning when native tools aren't available
• Adapter-Driven: Clean abstraction that works with multiple LLM providers

Intelligent Agent Architecture

• Single-agent execution with memory, tools, and conversational responses
• Intelligent Manager pattern via enhanced ManagerAgent with dynamic agent discovery
• Smart routing using agent keywords, capabilities, and examples for better delegation
• Clean Architecture: Separated concerns with ExecutionEngine, ResponseProcessor, and Planner

Advanced Capabilities

• Conversational Responses: Automatic post-processing converts raw tool results into natural language
• Memory Management: Context-aware memory with relevance scoring
• Retrieval-Augmented Generation (RAG): Optional pluggable retrieval system to ground responses in external knowledge
• Safety Guardrails: Max steps, max duration, stop-on-first-error
• Comprehensive Logging: Detailed execution tracking with step-level timings

🏗️ Architecture Overview

Agent (Coordinator)
├── ExecutionEngine (Execution Orchestration)
│   ├── Native tool calling (when supported)
│   ├── Fallback to planned execution
│   └── ResponseProcessor (Conversational formatting)
└── Planner (Traditional step-by-step execution)
    ├── Plan creation and validation
    └── Tool coordination and execution

🎯 Enhanced ManagerAgent

The ManagerAgent intelligently manages any registered agents with automatic discovery:

• Dynamic Discovery: Automatically finds and creates tools for all registered agents
• Keyword-based Routing: Uses agent keywords to match user requests to appropriate agents
• Capability Awareness: Leverages task types, examples, and limitations for smart delegation
• Native Tool Integration: Benefits from both native tool calling and conversational responses

Quick Example

import { ManagerAgent, registerAgent, ClaudeAdapter } from 'agente-toolkit';

// For this example, you'll need to copy the example agents from the GitHub repository
// See: https://github.com/LordShiroe/agente-toolkit/tree/main/examples/agents
// import { CalculatorAgent, WeatherAgent } from './your-agents-directory';

// For demonstration, let's create simple agents inline
class CalculatorAgent extends Agent {
  constructor() {
    super();
    this.addTool({
      name: 'add',
      description: 'Add two numbers',
      paramsSchema: Type.Object({
        a: Type.Number(),
        b: Type.Number(),
      }),
      action: async params => (params.a + params.b).toString(),
    });
  }

  static metadata = {
    metadata: {
      id: 'calculator',
      name: 'Calculator Agent',
      description: 'Performs arithmetic calculations',
      categories: ['math'],
      keywords: ['calculate', 'math', 'add'],
      priority: 5,
    },
    capabilities: {
      taskTypes: ['arithmetic'],
      examples: ['What is 15 + 27?'],
      limitations: [],
    },
  };
}

// Register agents with their metadata
registerAgent('calculator', new CalculatorAgent(), CalculatorAgent.metadata);

// Create adapter with native tool support
const adapter = new ClaudeAdapter(process.env.ANTHROPIC_API_KEY);

// Create intelligent manager that routes based on keywords and capabilities
const manager = new ManagerAgent(adapter);

// The manager routes: "Calculate 15+27" → Calculator agent
const result = await manager.run('Calculate 15 + 27', adapter);
console.log(result); // "The result is 42"

Note: Full example agents (Calculator, Weather) are available in the GitHub repository but not included in the npm package. Copy them to your project as needed.

📦 Installation

From NPM (Recommended)

npm install agente-toolkit

Or using yarn:

yarn add agente-toolkit

Or using pnpm:

pnpm add agente-toolkit

Requirements

• Node.js: >= 18.0.0
• TypeScript: >= 4.9.0 (for TypeScript projects)

From Source (Development)

git clone https://github.com/LordShiroe/agente-toolkit.git
cd agente-toolkit
npm install
npm run build

🚀 Quick Start

1. Set up your API key

export ANTHROPIC_API_KEY="your-api-key-here"
# or for OpenAI
export OPENAI_API_KEY="your-api-key-here"

2. Create your first agent

import { Agent, ClaudeAdapter } from 'agente-toolkit';

// Create agent
const agent = new Agent();
agent.setPrompt('You are a helpful assistant.');

// Create adapter
const adapter = new ClaudeAdapter(process.env.ANTHROPIC_API_KEY);

// Run!
const result = await agent.run('Hello! What can you help me with?', adapter);
console.log(result);

3. Add custom tools

import { Agent, ClaudeAdapter } from 'agente-toolkit';
import { Type } from '@sinclair/typebox';

const agent = new Agent();

// Add a custom tool
agent.addTool({
  name: 'get_time',
  description: 'Get the current time',
  paramsSchema: Type.Object({}),
  action: async () => new Date().toLocaleTimeString(),
});

const adapter = new ClaudeAdapter(process.env.ANTHROPIC_API_KEY);
const result = await agent.run('What time is it?', adapter);
console.log(result); // "The current time is 2:30:45 PM"

Programmatic Usage

Basic Agent with Native Tool Support

import { Agent, ClaudeAdapter } from 'agente-toolkit';

// Create agent with native tool calling support
const agent = new Agent();
agent.setPrompt('You are a helpful assistant.');
// agent.addTool(...) - Add your custom tools

// Claude adapter automatically uses native tools when available
const adapter = new ClaudeAdapter(process.env.ANTHROPIC_API_KEY);

// Get conversational responses regardless of execution method
const result = await agent.run('Hello!', adapter, {
  maxSteps: 8,
  stopOnFirstToolError: true,
});
console.log(result); // Natural, conversational response

Intelligent Manager Agent with Native Tools

import { ManagerAgent, registerAgent, ClaudeAdapter, Agent } from 'agente-toolkit';
import { Type } from '@sinclair/typebox';

// Create specialized agents
class CalculatorAgent extends Agent {
  constructor() {
    super();
    this.addTool({
      name: 'add',
      description: 'Add two numbers',
      paramsSchema: Type.Object({
        a: Type.Number({ description: 'First number' }),
        b: Type.Number({ description: 'Second number' }),
      }),
      action: async params => (params.a + params.b).toString(),
    });
  }

  static metadata = {
    metadata: {
      id: 'calculator',
      name: 'Calculator Agent',
      description: 'Performs arithmetic calculations',
      categories: ['math'],
      keywords: ['calculate', 'add', 'subtract', 'multiply', 'divide'],
      priority: 5,
    },
    capabilities: {
      taskTypes: ['arithmetic', 'calculations'],
      examples: ['What is 15 + 27?', 'Calculate 144 divided by 12'],
      limitations: ['Cannot handle complex mathematical functions'],
    },
  };
}

// Register agents with rich metadata
const calc = new CalculatorAgent();

registerAgent('calculator', calc, CalculatorAgent.metadata);

// Create adapter with native tool calling support
const adapter = new ClaudeAdapter(process.env.ANTHROPIC_API_KEY);

// Create manager that intelligently routes and provides conversational responses
const manager = new ManagerAgent(adapter);

// The manager intelligently routes with natural responses:
// "Calculate 15 + 27" → Calculator agent → "The result is 42"
// "What's 50 divided by 2?" → Calculator agent → "50 divided by 2 equals 25"

const result = await manager.run('What is 25 * 4?', adapter);
// Returns: "25 multiplied by 4 equals 100"

Pro Tip: Check out the examples directory for complete Calculator and Weather agent implementations.

Architecture Benefits

// Native tool calling (when supported)
const result1 = await agent.run('Weather in Paris', claudeAdapter);
// → Uses Claude's native tools → Conversational response

// Automatic fallback (when native tools fail or unavailable)
const result2 = await agent.run('Weather in Paris', basicAdapter);
// → Uses traditional planner → Converts to conversational response

// Both paths provide natural, user-friendly responses!

Custom Agent with Modern Architecture

import { Agent, AgentRegistration, ClaudeAdapter } from 'agente-toolkit';

class CustomAgent extends Agent {
  static readonly metadata: AgentRegistration = {
    metadata: {
      id: 'custom',
      name: 'Custom Agent',
      description: 'Handles custom tasks with native tool support',
      categories: ['utility', 'custom'],
      keywords: ['custom', 'utility', 'helper', 'process'],
      priority: 3,
    },
    capabilities: {
      taskTypes: ['data processing', 'utility functions'],
      examples: ['Process this data', 'Help with utility task'],
      limitations: ['Cannot handle real-time data'],
    },
  };

  constructor() {
    super();
    this.setPrompt('I am a helpful custom utility agent.');
    // Add custom tools that benefit from native calling...
  }
}

// Register and use with ManagerAgent (gets native tool benefits automatically)
registerAgent('custom', new CustomAgent(), CustomAgent.metadata);
const manager = new ManagerAgent(new ClaudeAdapter(process.env.ANTHROPIC_API_KEY));

🔧 Technical Highlights

Execution Flow

1. Agent receives request → Memory retrieval → Context building
2. ExecutionEngine decides → Native tools (if supported) OR Traditional planner
3. Native path: Direct tool calling → Immediate conversational response
4. Planned path: Step-by-step execution → ResponseProcessor → Conversational response
5. Result: Always natural, user-friendly responses regardless of execution method

Adapter Support

• ClaudeAdapter: Full native tool calling support with automatic fallback
• Future adapters: Can implement native tools or rely on traditional planning
• Graceful degradation: System works with any adapter capability level

📝 Notes

• Native tool calling provides faster, more natural interactions when available
• Automatic fallback ensures reliability across different model capabilities
• Conversational responses are generated for all execution paths
• ManagerAgent automatically benefits from native tools for all registered agents
• Example agents (Calculator, Weather) are available in the GitHub repository for reference
• API Keys: Ensure you have valid API keys for your chosen provider (Claude, OpenAI, Ollama)

📚 Documentation

See the docs for guides and references:

• Getting Started: Installation · Quick Start · Configuration
• Guides: Building Agents · Tool Development · RAG Integration
• Providers: Claude · OpenAI · Ollama

Reference: CHANGELOG · CONTRIBUTING · SECURITY · LOGGING · Examples · RAG Example

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• npm Package
• GitHub Repository
• Issue Tracker
• Example Agents