OpenAgentic

A powerful TypeScript framework for building AI agents with self-contained tool orchestration capabilities. Create intelligent agents that can seamlessly integrate with multiple AI providers and execute complex tasks using a rich ecosystem of built-in tools.

✨ Features

• 🤖 Multi-Provider AI Support - OpenAI, Anthropic, Google, xAI, Perplexity, and more
• 🔧 50+ Built-in Tools - From QR codes to video generation, GitHub integration to web search
• ⚡ Streaming & Non-Streaming - Real-time responses or batch processing
• 🎯 Smart Orchestration - Custom logic and prompt-based orchestrators
• 📝 TypeScript Native - Full type safety with Zod validation
• 🔄 Dynamic Tool Management - Add, remove, and manage tools at runtime
• 📊 Advanced Logging - Comprehensive debugging and performance monitoring
• 🌐 AI SDK Compatible - Works seamlessly with Vercel's AI SDK

🚀 Quick Start

Installation

OpenAgentic is compatible with all major Node.js package managers:

# npm
npm install openagentic

# pnpm  
pnpm add openagentic

# yarn
yarn add openagentic

# bun
bun add openagentic

Basic Usage

import { createAgent, openaiTool, videoGenerationTool } from 'openagentic';

// Create a simple agent
const agent = createAgent({
  model: 'gpt-4o-mini', // Auto-detects OpenAI provider
  tools: [openaiTool, videoGenerationTool], // Specify tool subset to use
  systemPrompt: 'You use OpenAI to enhance video generation prompts (optimized for Veo video generation) before generating the video with the video generation tool.',
});

// Execute a task
const result = await agent.execute(
  'Create a video of a beach sunset in Miami'
);

console.log(result.result);
console.log('Tools used:', result.toolCallsUsed);

Streaming Agent

import { createStreamingAgent, websearchTool, newsdataTool } from 'openagentic';

const streamingAgent = createStreamingAgent({
  model: 'claude-sonnet-4-20250514',
  tools: [websearchTool, newsdataTool],
  onFinish: (result) => {
    console.log('Streaming completed:', result);
  }
});

// Stream responses in real-time
for await (const chunk of streamingAgent.stream('Search for the latest AI news')) {
  process.stdout.write(chunk);
}

🛠️ Built-in Tools

OpenAgentic comes with 50+ pre-built tools organized into categories:

AI & Search Tools (11)

• OpenAI Text Generation - GPT model integration
• Anthropic Chat - Claude model integration
• Gemini Chat - Google's Gemini models
• Grok Chat - xAI's Grok models
• Llama Chat - Meta's Llama models
• Mistral Chat - Mistral AI's models
• Cohere Chat - Cohere AI's models
• Perplexity Search - AI-powered web search
• Web Search - General web search capabilities
• Inception Labs - Advanced AI chat
• Groq - Groq's models

Utility Tools (13)

• GitHub Integration - Repository and file access
• News Search - Real-time news with filtering
• QR Code Generator - Customizable QR code creation
• Image Generation (3) - OpenAI DALL-E, Unsplash, Luma, and Gemini imaging
• Text-to-Speech (2) - ElevenLabs and Gemini TTS
• Video Generation - Google Veo video creation
• HTML Composer - Dynamic web page generation
• Vector Store Search - OpenAI vector store search
• Slack Poster - Post in Slack channels

LangChain Tools (27+)

Usage Example

import { 
  createAgent, 
  githubTool, 
  openaiImageTool
} from 'openagentic';

const multiToolAgent = createAgent({
  model: 'gpt-4o',
  tools: [githubTool, openaiImageTool],
  systemPrompt: 'You are a creative assistant with access to multiple tools.',
});

const result = await multiToolAgent.execute(`
  For the Github repo https://github.com/bitcoin-ui-kit/bitcoin-ui
  1. Summarize the repository's purpose
  2. Create a visual that encapsulates the repository's functionality
`);

☁️ AWS S3 Integration

OpenAgentic includes comprehensive AWS S3 integration for file uploads and management:

S3 Features

• Automatic file organization into categorized directories
• Content type detection and file validation
• Secure credential management via environment variables
• Batch upload support with progress tracking
• File size validation and error handling

File Organization

Files are automatically organized in your S3 bucket:

your-bucket/
├── openagentic/
│   ├── images/         # Image files (.jpg, .png, .gif, etc.)
│   ├── audio/          # Audio files (.mp3, .wav, .ogg, etc.)
│   ├── videos/         # Video files (.mp4, .avi, .mov, etc.)
│   ├── documents/      # Document files (.pdf, .doc, .txt, etc.)
│   ├── websites/       # HTML files (.html, .htm)
│   └── uploads/        # Generic files

🔗 Using LangChain Tools

OpenAgentic provides seamless compatibility with LangChain tools, allowing you to use the vast ecosystem of LangChain tools alongside native OpenAgentic tools.

Auto-Conversion

LangChain tools are automatically detected and converted when passed to createAgent():

import { createAgent } from 'openagentic';
import { DallEAPIWrapper } from '@langchain/openai';
import { SerpAPI } from '@langchain/community/tools/serpapi';

// LangChain tools are automatically converted
const agent = createAgent({
  model: 'gpt-4o-mini',
  tools: [
    new DallEAPIWrapper(), // LangChain tool - auto-converted
    new SerpAPI()          // LangChain tool - auto-converted
  ],
});

const result = await agent.execute('Generate an image of a sunset and search for sunset photography tips');

Manual Conversion

For more control over the conversion process:

import { convertLangchainTool, createAgent } from 'openagentic';
import { DallEAPIWrapper } from '@langchain/openai';

// Create LangChain tool
const dalleTool = new DallEAPIWrapper({
  model: 'dall-e-3',
  n: 1
});

// Convert with custom options
const convertedTool = await convertLangchainTool(dalleTool, {
  toolId: 'custom_dalle',
  useCases: [
    'Generate marketing visuals',
    'Create concept art',
    'Prototype designs'
  ],
  logo: '🎨'
});

const agent = createAgent({
  model: 'gpt-4o-mini',
  tools: [convertedTool]
});

Mixed Tool Usage

Combine LangChain tools with native OpenAgentic tools:

import { createAgent, qrcodeTool, openaiTool } from 'openagentic';
import { DallEAPIWrapper } from '@langchain/openai';

const agent = createAgent({
  model: 'gpt-4o-mini',
  tools: [
    openaiTool,               // Native OpenAgentic tool
    new DallEAPIWrapper(),    // LangChain tool (auto-converted)
    qrcodeTool               // Native OpenAgentic tool
  ]
});

Supported LangChain Tool Types

• Tool - Basic LangChain tools with call() method
• StructuredTool - Advanced tools with schema and invoke() method
• DynamicTool - Dynamically created tools
• Custom Tools - Any tool implementing LangChain's tool interface

🎯 Advanced Features

Multi-Provider Support

// OpenAI
const openaiAgent = createAgent({ model: 'gpt-4o-mini' });

// Anthropic  
const claudeAgent = createAgent({ model: 'claude-sonnet-4-20250514' });

// Google
const geminiAgent = createAgent({ model: 'gemini-1.5-pro' });

// xAI
const grokAgent = createAgent({ model: 'grok-beta' });

// Custom provider configuration
const customAgent = createAgent({
  model: {
    provider: 'openai',
    model: 'gpt-4',
    apiKey: 'your-key',
    temperature: 0.7,
    maxTokens: 1000
  }
});

Dynamic Tool Management

const agent = createAgent({
  model: 'gpt-4o-mini',
  tools: [qrcodeTool] // Start with one tool
});

// Add tools at runtime
agent.addTool(githubTool);
agent.addTool(websearchTool);

// Remove tools
agent.removeTool('qr_code_generator');

// List all tools
const availableTools = agent.getAllTools();
console.log('Available tools:', availableTools.map(t => t.name));

Custom Logic & Orchestrators

const customAgent = createAgent({
  model: 'gpt-4o-mini',
  tools: [qrcodeTool],
  customLogic: async (input, context) => {
    // Pre-process input
    if (input.includes('urgent')) {
      return {
        content: 'This requires immediate attention!',
        priority: 'high'
      };
    }
    return null; // Continue with normal processing
  }
});

// Using orchestrators for advanced control
const orchestratedAgent = createAgent({
  model: 'gpt-4o-mini',
  tools: [openaiTool, openaiImageTool],
  orchestrator: 'enhanced_image_generation' // Built-in orchestrator
});

Message Array Support (AI SDK Compatible)

import type { CoreMessage } from 'openagentic';

const messages: CoreMessage[] = [
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user', content: 'Hello!' },
  { role: 'assistant', content: 'Hi! How can I help you?' },
  { role: 'user', content: 'Create a QR code for my website.' }
];

const result = await agent.execute(messages);

Advanced Logging & Debugging

const debugAgent = createAgent({
  model: 'gpt-4o-mini',
  tools: [qrcodeTool],
  enableDebugLogging: true,
  logLevel: 'detailed',
  enableStepLogging: true,
  enableToolLogging: true,
  enableTimingLogging: true,
  enableStatisticsLogging: true
});

const result = await debugAgent.execute('Create a QR code for this NPM package repository: https://www.npmjs.com/package/openagentic');

// Access execution statistics
console.log('Execution stats:', result.executionStats);
console.log('Token usage:', result.usage);

🔧 API Reference

Core Functions

createAgent(options)

Creates a standard agent for non-streaming execution.

interface AgentOptions {
  model: string | AIModel;
  tools?: Tool[];
  systemPrompt?: string;
  maxIterations?: number;
  customLogic?: (input: string, context: any) => Promise<any>;
  apiKeys?: ApiKeyMap;
  enableDebugLogging?: boolean;
  logLevel?: 'none' | 'basic' | 'detailed';
  // ... additional options
}

createStreamingAgent(options)

Creates a streaming agent for real-time responses.

interface StreamingAgentOptions extends AgentOptions {
  onFinish?: (result: any) => void | Promise<void>;
}

Agent Methods

// Execute tasks
await agent.execute(input: string | CoreMessage[]): Promise<ExecutionResult>

// Streaming execution  
for await (const chunk of agent.stream(input)) { /* handle chunk */ }

// Tool management
agent.addTool(tool: Tool): void
agent.removeTool(toolId: string): void
agent.getAllTools(): Tool[]

// Model management
agent.switchModel(model: string | AIModel): void
agent.getModelInfo(): AIModel

Supported AI Providers

OpenAgentic auto-detects providers from model names:

OpenAI: gpt-4, gpt-4-turbo, gpt-4o, gpt-4o-mini, o3, o3-mini Anthropic: claude-opus-4-20250514, claude-sonnet-4-20250514, claude-haiku-4-20250514 Google: gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash xAI: grok-beta, grok-2-vision-1212 Perplexity: llama-3.1-sonar-small-128k-online, llama-3.1-sonar-large-128k-online

🌍 Environment Setup

Create a .env file with your API keys:

# AI Providers
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key  
GOOGLE_API_KEY=your_google_key
XAI_API_KEY=your_xai_key
PERPLEXITY_API_KEY=your_perplexity_key

# Utility Services
GITHUB_TOKEN=your_github_token
NEWSDATA_API_KEY=your_newsdata_key
ELEVENLABS_API_KEY=your_elevenlabs_key

# AWS/S3 (for media generation)
AWS_ACCESS_KEY_ID=your_aws_key
AWS_SECRET_ACCESS_KEY=your_aws_secret
AWS_REGION=us-east-1
S3_BUCKET_NAME=your-bucket-name

📚 Examples

The package includes comprehensive examples in the examples/ directory:

# Basic agent usage
npm run example:basic

# Streaming responses
npm run example:streaming

# Tool testing and validation
npm run test:tools

# Orchestrator testing and validation
npm run test:orchestrators

# Advanced logging
npm run example:logging

🔍 Tool Development

Create custom tools using the OpenAgentic tool interface:

import { z } from 'zod';
import { toOpenAgenticTool } from 'openagentic/tools';

const customTool = toOpenAgenticTool({
  toolId: 'custom_calculator',
  name: 'Custom Calculator',
  description: 'Performs mathematical calculations',
  useCases: ['Math', 'Calculations'],
  logo: '🧮',
  parameters: z.object({
    expression: z.string().describe('Mathematical expression to evaluate')
  }),
  execute: async ({ expression }) => {
    // Implement your tool logic
    return { result: eval(expression) };
  }
});

// Use in agent
const agent = createAgent({
  model: 'gpt-4o-mini',
  tools: [customTool]
});

🤝 Contributing

This is an open-source, community project - we welcome any and all contributions! Please see our CONTRIBUTING guidelines for more details.

📄 License

MIT License - see the LICENSE file for details.

🔗 Links

• GitHub Repository
• npm Package
• Issues & Bug Reports
• Website

Build powerful AI agents with OpenAgentic 🤖✨