Framework-agnostic SDK for building AI agents
Features • Installation • Quick Start • Documentation • Examples
Build AI Agent SDK is a powerful, framework-agnostic library for building intelligent AI agents. It provides a clean, type-safe API for creating agents with tools, flows, and custom capabilities.
Perfect for:
- 🤖 Building chatbots and virtual assistants
- 🔄 Creating automated workflows
- 🛠️ Integrating LLMs into existing applications
- 🎯 Developing custom AI-powered tools
- 🎯 Framework Agnostic - Works with React, Vue, Svelte, Angular, Express, or vanilla JS
- 🔧 Extensible - Easy to add custom tools, flows, and providers
- 🧪 Type-Safe - Full TypeScript support with comprehensive type definitions
- 📦 Modular - Use only what you need with tree-shakeable exports
- 🚀 Production Ready - Built-in error handling, retries, and circuit breakers
- 🔒 Secure - Built-in encryption, hashing, and security utilities
- 💾 Storage - File storage with concurrency locking
- 🎨 Templates - Jinja2-like template rendering for prompts
- 🔄 Streaming - Real-time streaming responses
- 🧠 Memory - Conversation context and memory management
- ⚡ Fast - Optimized bundle size (~120KB)
npm install @tajwal/build-ai-agent ai zod
# or
pnpm add @tajwal/build-ai-agent ai zod
# or
yarn add @tajwal/build-ai-agent ai zodThe SDK requires:
ai^4.1.54 - Vercel AI SDKzod^3.23.8 - Schema validation@ai-sdk/openai^0.0.42 (for OpenAI provider)ollama-ai-provider^1.2.0 (for Ollama provider)
import{AgentBuilder,AgentType}from'@tajwal/build-ai-agent';constagent=newAgentBuilder().setType(AgentType.SmartAssistant).setName('Customer Support Agent').setPrompt('You are a helpful customer support assistant.').addTool('http',{tool: 'httpRequest',options: {method: 'GET'}}).build();import{createMockRepositories}from'@tajwal/build-ai-agent';// For development/testingconstrepositories=createMockRepositories();// For production with Drizzle ORMimport{createDrizzleRepositories}from'@tajwal/build-ai-agent-drizzle';constrepositories=createDrizzleRepositories(db);import{AgentExecutor}from'@tajwal/build-ai-agent';constexecutor=newAgentExecutor({
agent,sessionId: 'session-123',
repositories,llmProvider: myLLMProvider});// Simple executionconstresult=awaitexecutor.execute({messages: [{role: 'user',content: 'Hello!'}]});console.log(result.response);// Agent's response// Streaming executionconststream=awaitexecutor.executeStream({messages: [{role: 'user',content: 'Tell me a story'}]});forawait(constchunkofstream){process.stdout.write(chunk.content);}Agents are the core abstraction. They combine:
- Type: Determines behavior (SmartAssistant, Workflow, DataAnalyst, etc.)
- Prompt: System instructions
- Tools: Available capabilities
- Flows: Structured workflows
- Memory: Conversation history
Tools extend agent capabilities:
import{ToolRegistry}from'@tajwal/build-ai-agent';constregistry=newToolRegistry();// Register a custom toolregistry.register({name: 'weather',description: 'Get weather information',parameters: z.object({location: z.string(),units: z.enum(['celsius','fahrenheit'])}),execute: async({ location, units })=>{// Your implementationreturn{temperature: 72,conditions: 'sunny'};}});Flows orchestrate multi-step workflows:
import{FlowBuilder,FlowNodeType}from'@tajwal/build-ai-agent';constflow=newFlowBuilder().addNode({id: 'start',type: FlowNodeType.LLM,data: {prompt: 'Analyze user input'}}).addNode({id: 'decide',type: FlowNodeType.Conditional,data: {condition: 'output.sentiment === "positive"'}}).addEdge('start','decide').build();Support for multiple LLM providers:
import{LLMProviderRegistry}from'@tajwal/build-ai-agent';// OpenRouter - Access 100+ models from multiple providersconstopenrouter=LLMProviderRegistry.create('openrouter',{apiKey: process.env.OPENROUTER_API_KEY,defaultModel: 'openai/gpt-4o-mini'});// OpenAI - Direct OpenAI integrationconstopenai=LLMProviderRegistry.create('openai',{apiKey: process.env.OPENAI_API_KEY,defaultModel: 'gpt-4'});// Ollama - Local LLM supportconstollama=LLMProviderRegistry.create('ollama',{baseURL: 'http://localhost:11434',defaultModel: 'llama3.1'});import{EncryptionUtils,sha256}from'@tajwal/build-ai-agent';constencryption=newEncryptionUtils('your-secret-key');constencrypted=awaitencryption.encrypt('sensitive data');constdecrypted=awaitencryption.decrypt(encrypted);consthash=awaitsha256('password','salt');import{StorageService}from'@tajwal/build-ai-agent';conststorage=newStorageService('user-123','attachments');awaitstorage.saveFile('document.pdf',buffer);constfile=awaitstorage.readFile('document.pdf');awaitstorage.deleteFile('document.pdf');import{renderTemplate}from'@tajwal/build-ai-agent';consttemplate='Hello {{ name }}! You have {{ count }} messages.';constresult=renderTemplate(template,{name: 'Alice',count: 5});// "Hello Alice! You have 5 messages."import{MemoryManager}from'@tajwal/build-ai-agent';constmemory=newMemoryManager({maxMessages: 10,summarizeAfter: 20});memory.addMessage({role: 'user',content: 'Hello'});memory.addMessage({role: 'assistant',content: 'Hi there!'});constcontext=memory.getContext();// Recent conversationimport{AgentBuilder,AgentExecutor,OpenAIProvider}from'@tajwal/build-ai-agent';// Configureconstagent=newAgentBuilder().setType('chatbot').setPrompt('You are a helpful assistant.').build();constexecutor=newAgentExecutor({
agent,sessionId: 'chat-1',llmProvider: newOpenAIProvider({apiKey: process.env.OPENAI_API_KEY})});// Executeconstresponse=awaitexecutor.execute({messages: [{role: 'user',content: 'What is the capital of France?'}]});console.log(response.response);// "The capital of France is Paris."import{AgentBuilder,AgentExecutor,ToolRegistry}from'@tajwal/build-ai-agent';// Register toolsconsttools=newToolRegistry();tools.register({name: 'calculator',description: 'Perform calculations',parameters: z.object({expression: z.string()}),execute: async({ expression })=>eval(expression)});// Build agent with toolsconstagent=newAgentBuilder().setType('smart-assistant').setPrompt('You are a math assistant. Use the calculator tool when needed.').addTool('calculator',{tool: 'calculator'}).build();constexecutor=newAgentExecutor({
agent,sessionId: 'math-1',toolRegistry: tools});constresponse=awaitexecutor.execute({messages: [{role: 'user',content: 'What is 25 * 37?'}]});import{FlowBuilder,FlowExecutor}from'@tajwal/build-ai-agent';constflow=newFlowBuilder().addNode({id: '1',type: 'llm',data: {prompt: 'Generate ideas'}}).addNode({id: '2',type: 'llm',data: {prompt: 'Evaluate ideas'}}).addNode({id: '3',type: 'llm',data: {prompt: 'Select best idea'}}).addEdge('1','2').addEdge('2','3').build();constexecutor=newFlowExecutor({ flow, llmProvider });constresult=awaitexecutor.execute({input: 'Product ideas'});- AgentBuilder - Build and configure agents
- AgentExecutor - Execute agent conversations
- ToolRegistry - Manage available tools
- FlowBuilder - Build workflow graphs
- FlowExecutor - Execute workflows
- MemoryManager - Manage conversation context
- OpenRouterProvider - Access 100+ models from OpenAI, Anthropic, Google, Meta, and more
- OpenAIProvider - Direct OpenAI integration
- OllamaProvider - Local LLM support
- MockProvider - Testing provider
- EncryptionUtils - Encryption/decryption
- StorageService - File storage
- renderTemplate - Template rendering
- validateTokenQuotas - Quota validation
For detailed API documentation, see the TypeScript definitions.
The SDK follows clean architecture principles:
┌─────────────────────────────────────┐
│ Your Application │
│ (React, Vue, Express, etc.) │
└──────────────┬──────────────────────┘
│
┌──────────────▼──────────────────────┐
│ @tajwal/build-ai-agent │
│ ┌────────────────────────────┐ │
│ │ AgentBuilder/Executor │ │
│ ├────────────────────────────┤ │
│ │ Tools │ Flows │ Memory │ │
│ ├────────────────────────────┤ │
│ │ Core Engine │ │
│ └────────────────────────────┘ │
└──────────────┬──────────────────────┘
│
┌──────────────▼──────────────────────┐
│ Your Data Layer & LLM Provider │
│ (Database, OpenAI, Ollama, etc.) │
└─────────────────────────────────────┘
# Run tests
pnpm test# With coverage
pnpm test:coverage
# Type checking
pnpm typecheckContributions are welcome! Please see CONTRIBUTING.md for guidelines.
- Additional LLM providers (Anthropic Claude, Google Gemini)
- More database adapters (Prisma, MongoDB)
- Advanced flow patterns
- Multi-agent collaboration
- Plugin system
MIT © Build AI Agent