DEV Community: Siddick FOFANA

My AI Agents as First-Class NestJS Citizens

Siddick FOFANA — Wed, 08 Apr 2026 14:58:06 +0000

Stop wiring AI agents by hand. With @orka-js/nestjs, your agents live in the DI container, respond to events, protect routes semantically, and run as microservices — all with NestJS idioms you already know.

You've spent months building a clean NestJS architecture.

DI everywhere. CQRS for complex domains. Event-driven with @nestjs/event-emitter. Microservices on Redis. Guards for access control.

Then your AI agent arrives — and none of that applies to it.

The agent lives in a service file, instantiated by hand, injected as a raw class, called directly. It doesn't participate in your architecture. It's a guest that doesn't respect the house rules.

@orka-js/nestjs fixes that. Your agents become actual NestJS citizens — DI-injectable, event-driven, guarded, pipeable, CQRS-aware.

Install

npm install @orka-js/nestjs @orka-js/agent @orka-js/openai @nestjs/common @nestjs/core reflect-metadata rxjs

1. `OrkaModule` — Register Agents in the DI Container

import { Module } from '@nestjs/common'
import { OrkaModule } from '@orka-js/nestjs'
import { StreamingToolAgent } from '@orka-js/agent'
import { OpenAIAdapter } from '@orka-js/openai'

const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! })

@Module({
  imports: [
    OrkaModule.forRoot({
      agents: {
        assistant: new StreamingToolAgent({ goal: 'Helpful assistant', tools: [] }, llm),
        analyst:   new StreamingToolAgent({ goal: 'Data analyst', tools: [] }, llm),
      },
      path: 'ai', // mounts HTTP routes under /ai
    }),
  ],
})
export class AppModule {}

This single forRoot() call gives you:

GET  /ai               → list registered agents
GET  /ai/:agent        → agent info
POST /ai/:agent        → run agent (blocking)
POST /ai/:agent/stream → run agent (SSE streaming)

No controllers to write. No routing logic to maintain. Same API contract as @orka-js/express and @orka-js/hono.

2. `forRootAsync` — Config from `ConfigService`

Production apps read API keys from environment. Here's how to do it the NestJS way:

import { ConfigModule, ConfigService } from '@nestjs/config'
import { OrkaModule } from '@orka-js/nestjs'

@Module({
  imports: [
    ConfigModule.forRoot(),
    OrkaModule.forRootAsync({
      imports: [ConfigModule],
      path: 'ai',
      useFactory: (config: ConfigService) => ({
        agents: {
          assistant: new StreamingToolAgent(
            { goal: 'Helpful assistant', tools: [] },
            new OpenAIAdapter({ apiKey: config.get('OPENAI_API_KEY')! })
          ),
        },
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

The factory resolves asynchronously — your agents are configured after all environment variables and secrets are loaded.

3. `@InjectAgent` — Use Agents Anywhere

Once registered, agents are DI-injectable throughout your application:

import { Injectable } from '@nestjs/common'
import { InjectAgent } from '@orka-js/nestjs'
import type { BaseAgent } from '@orka-js/agent'

@Injectable()
export class OrderService {
  constructor(
    @InjectAgent('assistant') private agent: BaseAgent,
    private readonly db: OrderRepository,
  ) {}

  async summarize(orderId: string): Promise<string> {
    const order = await this.db.findById(orderId)
    const result = await this.agent.run(JSON.stringify(order))
    return result.output
  }
}

The token is deterministic — @InjectAgent('assistant') is equivalent to @Inject('ORKA_AGENT:assistant'). You can inspect it, override it in tests, and swap implementations without touching consumers.

4. `@AgentReact` — Event-Driven Agents

The most underused pattern in NestJS AI apps: reacting to domain events with an agent.

Without @AgentReact, you write this boilerplate on every event handler:

@OnEvent('order.created')
async onOrderCreated(payload: OrderCreatedEvent) {
  const agent = this.fulfillmentAgent
  if (!agent?.run) throw new Error('...')
  await agent.run(JSON.stringify(payload))
}

With @AgentReact, the method body is entirely replaced at decoration time:

import { Injectable } from '@nestjs/common'
import { OnEvent } from '@nestjs/event-emitter'
import { InjectAgent, AgentReact } from '@orka-js/nestjs'
import type { BaseAgent } from '@orka-js/agent'

@Injectable()
export class OrderEventHandler {
  constructor(
    @InjectAgent('fulfillment') private agent: BaseAgent,
    @InjectAgent('churn')       private churnAgent: BaseAgent,
  ) {}

  // Awaited — the event emitter waits for the agent to finish
  @OnEvent('order.created')
  @AgentReact()
  async onOrderCreated(payload: OrderCreatedEvent) {}

  // Fire-and-forget — returns immediately, agent runs in background
  @OnEvent('customer.churned')
  @AgentReact({ agent: 'churnAgent', async: true })
  onChurnDetected(payload: ChurnEvent): void {}
}

The async: true option is critical for high-frequency events: the event emitter doesn't block, the agent processes in background. Use it for analytics, notifications, logging — anything that doesn't need a synchronous response.

5. `OrkaSemanticGuard` — LLM as a Security Layer

Traditional guards check JWT claims, roles, IP ranges. OrkaSemanticGuard checks intent.

import { Module } from '@nestjs/common'
import { APP_GUARD } from '@nestjs/core'
import { OrkaSemanticGuard } from '@orka-js/nestjs'

// Applied to a specific controller
@UseGuards(new OrkaSemanticGuard(llm, 'Only allow requests from authenticated admin users managing their own data'))
@Controller('admin')
export class AdminController {
  @Get('users')
  listUsers() { /* ... */ }
}

// Or globally via module
@Module({
  providers: [
    {
      provide: APP_GUARD,
      useValue: new OrkaSemanticGuard(
        llm,
        'Block any request that attempts to access data belonging to other users, perform bulk operations, or export raw data'
      ),
    },
  ],
})
export class AppModule {}

The guard sends method, URL, body (truncated), and authorization headers to the LLM. It asks for ALLOW or DENY. If the LLM throws or is unavailable, it fails closed — denies access by default. Security > availability.

Use it for:

Rate-limit evasion detection ("this looks like a scraping attempt")
Prompt injection prevention ("this input is trying to jailbreak the API")
Business rule enforcement ("admins can't delete other admins")

6. `AgentValidationPipe` — NLP → DTO

Your API consumers don't always send clean structured data. Sometimes they send natural language:

POST /products/search
{ "input": "show me red sneakers under 100 euros size 42" }

AgentValidationPipe transforms this into a typed DTO using your LLM:

import { z } from 'zod'
import { Controller, Post, Body } from '@nestjs/common'
import { AgentValidationPipe } from '@orka-js/nestjs'

const ProductSearchSchema = z.object({
  color:    z.string().optional(),
  maxPrice: z.number().optional(),
  size:     z.number().optional(),
  category: z.string().optional(),
})

type ProductSearch = z.infer<typeof ProductSearchSchema>

@Controller('products')
export class ProductController {
  @Post('search')
  async search(
    @Body(new AgentValidationPipe(ProductSearchSchema, llm))
    filters: ProductSearch,
  ) {
    // filters = { color: 'red', maxPrice: 100, size: 42, category: 'sneakers' }
    return this.productService.search(filters)
  }
}

The pipe handles three input shapes:

{ input: "natural language description" } → LLM extracts the DTO
Structured object → validated directly with schema.safeParse(); LLM only called as fallback
Validation failure → BadRequestException with clear error message

Your API accepts both human-readable and machine-readable inputs. Same endpoint. No if/else branching.

7. CQRS Integration

If your app uses @nestjs/cqrs, agents plug directly into the query/command bus:

npm install @nestjs/cqrs

import { IQuery } from '@nestjs/cqrs'
import { AgentQueryHandler, OrkaQueryHandler, InjectAgent } from '@orka-js/nestjs/cqrs'
import type { BaseAgent } from '@orka-js/agent'

// Define your query
export class SearchProductsQuery implements IQuery {
  constructor(public readonly filters: ProductSearch) {}
}

// Handler — extends OrkaQueryHandler, registered via @AgentQueryHandler
@AgentQueryHandler(SearchProductsQuery)
export class SearchProductsHandler extends OrkaQueryHandler<SearchProductsQuery> {
  constructor(@InjectAgent('search') protected agent: BaseAgent) {
    super()
  }
}

OrkaQueryHandler serializes the query to JSON and passes it to the agent. The handler registers itself on the query bus. You call it like any other CQRS handler:

@Controller('products')
export class ProductController {
  constructor(private readonly queryBus: QueryBus) {}

  @Post('search')
  async search(@Body() filters: ProductSearch) {
    return this.queryBus.execute(new SearchProductsQuery(filters))
  }
}

Your agent is now part of the command/query pipeline. Observable, testable, replaceable.

8. Agent as Microservice

When your AI workload gets heavy, isolate it behind a NestJS microservice transport:

npm install @nestjs/microservices

The agent microservice (separate process):

import { NestFactory } from '@nestjs/core'
import { Transport } from '@nestjs/microservices'
import { OrkaModule } from '@orka-js/nestjs'

async function bootstrap() {
  const module = await OrkaModule.forMicroservice({
    agents: { assistant: assistantAgent, analyst: analystAgent },
  })

  const app = await NestFactory.createMicroservice(
    { module: class AppModule {}, imports: [module] },
    { transport: Transport.REDIS, options: { host: 'localhost', port: 6379 } }
  )

  await app.listen()
  console.log('Agent microservice listening on Redis')
}
bootstrap()

The consumer (your main API):

import { OrkaClientModule, InjectAgentClient } from '@orka-js/nestjs/microservice'
import type { AgentClient } from '@orka-js/nestjs/microservice'

@Module({
  imports: [
    OrkaClientModule.forRoot({
      clients: [{
        name: 'ai',
        transport: Transport.REDIS,
        options: { host: 'localhost', port: 6379 },
      }],
    }),
  ],
})
export class AppModule {}

@Injectable()
export class OrderService {
  constructor(@InjectAgentClient('ai') private client: AgentClient) {}

  async process(order: Order): Promise<AgentResult> {
    return this.client.run('assistant', JSON.stringify(order))
  }
}

Your main API stays thin. The AI workload scales independently. Add more microservice instances as load grows.

Putting It Together: A Real Feature

Here's a complete order processing flow — event-driven, validated, and CQRS-aware:

// 1. Order submitted via HTTP — NLP input normalized to DTO
@Post('orders')
async createOrder(
  @Body(new AgentValidationPipe(OrderSchema, llm))
  order: OrderDTO,
) {
  return this.commandBus.execute(new CreateOrderCommand(order))
}

// 2. Order created — fulfillment agent reacts asynchronously
@OnEvent('order.created')
@AgentReact({ agent: 'fulfillmentAgent', async: true })
onOrderCreated(payload: OrderCreatedEvent): void {}

// 3. Order queried — search agent handles the query bus
@AgentQueryHandler(FindSimilarOrdersQuery)
class FindSimilarOrdersHandler extends OrkaQueryHandler<FindSimilarOrdersQuery> {
  constructor(@InjectAgent('search') protected agent: BaseAgent) { super() }
}

// 4. Admin routes protected by semantic guard
@UseGuards(new OrkaSemanticGuard(llm, 'Only authenticated admins can access order management'))
@Controller('admin/orders')
class AdminOrderController { /* ... */ }

Each piece uses a NestJS primitive you already know. The agents slot in where domain logic lives — not alongside it.

The Complete Feature Set

Feature	NestJS Primitive	OrkaJS Addition
HTTP routes	`@Controller`	`OrkaModule.forRoot({ path })`
DI injection	`@Inject`	`@InjectAgent('name')`
Event handling	`@OnEvent`	`@AgentReact({ async })`
Access control	`CanActivate`	`OrkaSemanticGuard`
Input validation	`PipeTransform`	`AgentValidationPipe`
CQRS	`IQueryHandler`	`OrkaQueryHandler`
Transport	`@MessagePattern`	`OrkaModule.forMicroservice`

Every feature is opt-in. You pick what you need. The rest of your architecture stays unchanged.

Testing

In tests, replace agents with mocks at the DI level:

const moduleRef = await Test.createTestingModule({
  imports: [
    OrkaModule.forRoot({
      agents: {
        assistant: {
          run: vi.fn().mockResolvedValue({ output: 'mocked response', steps: 1 })
        } as unknown as BaseAgent,
      },
    }),
  ],
  providers: [OrderService],
}).compile()

No mocking frameworks needed. The DI container swaps the real agent for your mock. Your service tests remain fast and deterministic.

OrkaJS — Build production AI agents in TypeScript.

Docs: orkajs.com
npm: npm install @orka-js/nestjs
GitHub: github.com/orka-ai/orkajs

What NestJS architecture pattern do you wish AI frameworks supported natively? Drop it in the comments — the next OrkaJS feature might be yours.

How to Build a Durable AI Agent in 10 Lines of TypeScript

Siddick FOFANA — Mon, 06 Apr 2026 08:19:29 +0000

Your AI agent crashes after 2 minutes of work. You lose everything. It doesn't have to be this way.

I've seen it happen in every production AI project.

You build a beautiful agent. It works perfectly in local. You ship it.
Then it runs for 90 seconds, hits a timeout, crashes — and all context is gone.
Your user stares at a spinner. Your logs show nothing useful.

The problem isn't your LLM. It's your architecture.

AI agents are stateful, long-running processes. And we've been treating them like stateless HTTP handlers.

Let me show you how to fix this in 10 lines.

The Problem: Agents Are Ephemeral by Default

// Standard agent — everything lives in RAM
const agent = new StreamingToolAgent({ goal: 'Research assistant' }, llm)
const result = await agent.run('Research the top 10 AI papers of 2025')
// If this crashes at step 8/10... you restart from zero.

The issue is that AI agent state lives only in memory. The moment the process dies — OOM, timeout, deployment, network blip — you lose everything.

The Solution: `@orka-js/durable`

import { DurableAgent, MemoryDurableStore } from '@orka-js/durable'
import { StreamingToolAgent } from '@orka-js/agent'
import { OpenAIAdapter } from '@orka-js/openai'

const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! })
const agent = new StreamingToolAgent({ goal: 'Research assistant', tools: [] }, llm)
const store = new MemoryDurableStore()
const durable = new DurableAgent(agent, store, { maxRetries: 3 })

// That's it. Your agent is now durable.
const job = await durable.run('job-001', 'Research the top 10 AI papers of 2025')
console.log(job.status)  // 'completed'
console.log(job.result)  // The full research

That's literally 10 lines. Let me break down what just happened.

What `DurableAgent` Actually Does

1. Every job has a persistent ID

const job = await durable.run('job-001', 'Research AI papers')

The job-001 identifier is the key insight. If this job already ran and completed, calling run('job-001', ...) again returns the cached result immediately — no LLM call made.

This is idempotency. It's the foundation of reliable distributed systems, now applied to AI agents.

2. Automatic retry with backoff

const durable = new DurableAgent(agent, store, {
  maxRetries: 3,
  retryDelayMs: 2000, // wait 2s between retries
})

If your agent fails (rate limit, network error, LLM timeout), DurableAgent retries automatically. No try/catch soup. No manual retry loops.

3. Human-in-the-loop: pause and resume

This is where it gets genuinely powerful.

// Start a long research job
const job = await durable.run('analysis-42', 'Analyze Q4 financial reports')

// Pause it — maybe you need human approval before continuing
await durable.pause('analysis-42')

// Hours later, after your manager reviews the intermediate output...
const resumed = await durable.resume('analysis-42')
console.log(resumed.result)

You can build approval workflows where an agent pauses waiting for a human decision, then resumes exactly where it left off. No state reconstruction. No prompt re-injection hacks.

Production: Switch to Redis in One Line

MemoryDurableStore is great for local dev. For production:

import { RedisDurableStore } from '@orka-js/durable'
import { createClient } from 'redis'

const redis = createClient({ url: process.env.REDIS_URL })
await redis.connect()

const store = new RedisDurableStore(redis) // <- one line change
const durable = new DurableAgent(agent, store, { maxRetries: 3 })

Your agent jobs now survive:

Server restarts
Deployments
OOM crashes
Cloud instance preemptions

Scheduled Agents: Cron for AI

One more thing. You can schedule an agent to run on a cron:

const durable = new DurableAgent(agent, store)

// Run every day at 9am
durable.schedule('daily-briefing', '0 9 * * *', 'Generate the daily news summary')

No cron infrastructure to set up. No separate worker process. Just declare it and forget it.

Stream Events While Persisting State

If your agent supports streaming (it should), DurableAgent preserves it:

const stream = durable.stream('job-002', 'Write a full market analysis')

for await (const event of stream) {
  if (event.type === 'text') process.stdout.write(event.content)
  if (event.type === 'tool_call') console.log('Using tool:', event.name)
  if (event.type === 'done') console.log('Job saved:', event.jobId)
}

The user sees a streaming response. The job state is persisted in the background. Best of both worlds.

The Mental Model Shift

Before	After
Agent = function call	Agent = persistent job
Failure = start over	Failure = resume from checkpoint
Long tasks = scary	Long tasks = no problem
Human review = impossible	Human review = pause/resume
Cron = separate infra	Cron = built-in

Get Started

npm install @orka-js/durable @orka-js/agent @orka-js/openai

import { DurableAgent, MemoryDurableStore } from '@orka-js/durable'
import { StreamingToolAgent } from '@orka-js/agent'
import { OpenAIAdapter } from '@orka-js/openai'

const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! })
const agent = new StreamingToolAgent({ goal: 'Assistant', tools: [] }, llm)
const durable = new DurableAgent(agent, new MemoryDurableStore(), { maxRetries: 2 })

const job = await durable.run('my-first-durable-job', 'Hello, world!')
console.log(job.status, job.result)

That's it. Your agents are now production-grade.

OrkaJS is a TypeScript-first framework for building production AI agents. Modular, typed, and provider-agnostic.

GitHub: github.com/orka-ai/orkajs
Docs: orkajs.com
npm: npm install orka-js/<package>

If this solved a problem you've had, share it — other devs are fighting the same battle right now.

I built Design Canvas like lovable with Orka AI

Siddick FOFANA — Sat, 28 Mar 2026 14:12:45 +0000

"AI Design Canvas" transforms your ideas into editable, professional designs: presentations, social media posts, documents, and diagrams.

✨ Key Features:

AI Design Agent - Thinks step by step with ReActAgent

Brand Awareness - Automatically applies your guidelines

Multiple Design Types - Slides, Social, Documents, Diagrams, UI

Intelligent Suggestions - AI improves your designs

Iterative Refinement - Improve with natural language feedback

Real-Time Thinking - Observe the AI's reasoning

🏗️ OrkaJS Architecture:

- @orka-js/agent - ReActAgent for reasoning
- @orka-js/openai - GPT-4 type-safe integration
- @orka-js/observability - Tracing and debugging

Documentation: https://www.orkajs.com/
Join the Discord: https://discord.com/invite/DScfpuPysP
Repo GitHub: https://github.com/Orka-Community/ai-design-canvas

🤖 Building Advanced Agent-to-Agent (A2A) Systems with OrkaJS: A Complete Architecture Guide

Siddick FOFANA — Wed, 18 Mar 2026 08:47:04 +0000

Introduction
The world of AI is evolving from single-agent systems to complex Agent-to-Agent (A2A) architectures where multiple specialized AI agents collaborate to solve sophisticated problems. Think of it as building a team of AI specialists, each with unique capabilities, working together seamlessly.

Orka.JS, the TypeScript framework for building production-ready LLM systems, provides native support for A2A architectures with powerful orchestration, communication, and monitoring capabilities.

Docs OrkaJS (Agent): https://discord.com/invite/DScfpuPysP
Discord: https://discord.com/invite/DScfpuPysP

In this comprehensive guide, we'll explore how to design and implement enterprise-grade A2A systems using OrkaJS, from basic concepts to advanced deployment strategies.

What Are A2A Systems?
Agent-to-Agent systems are architectures where multiple AI agents communicate, collaborate, and coordinate to achieve complex goals that would be difficult or impossible for a single agent to accomplish alone.

Key Benefits:

Specialization: Each agent excels at specific tasks
Parallel Processing: Multiple agents work simultaneously
Collective Intelligence: Combined knowledge and capabilities
Resilience: System continues working even if some agents fail
Scalability: Easy to add new agents and capabilities
The Complete A2A Architecture

The Complete A2A Architecture
Let's design a production-ready A2A system using OrkaJS. Here's the high-level architecture:

Core Infrastructure Setup

A2A System Foundation

typescript
import { createOrka } from '@orka-js/core';
import { ReActAgent } from '@orka-js/agent';
import { OpenAIAdapter } from '@orka-js/openai';
import { trace } from '@orka-js/collector';

export class A2ASystem {
  private orchestrator: A2AOrchestrator;
  private messageQueue: MessageQueueService;
  private sharedMemory: SharedMemoryService;
  private monitoring: A2AMonitoringService;

  constructor(config: A2AConfig) {
    this.initializeInfrastructure(config);
    this.setupAgents();
    this.establishCommunicationProtocols();
  }

  async initializeInfrastructure(config: A2AConfig) {
    // Shared Memory Layer - The "brain" of our A2A system
    this.sharedMemory = new SharedMemoryService({
      vectorStore: new PineconeAdapter(config.pinecone),
      cache: new RedisCache(config.redis),
      persistence: new PostgreSQLAdapter(config.postgres)
    });

    // Message Queue System - The "nervous system"
    this.messageQueue = new MessageQueueService({
      broker: new RabbitMQAdapter(config.rabbitmq),
      routing: new A2ARoutingStrategy(),
      reliability: new AtLeastOnceDelivery()
    });

    // Monitoring & Observability - The "health monitor"
    this.monitoring = new A2AMonitoringService({
      tracer: new TraceCollector(),
      metrics: new PrometheusMetrics(),
      alerts: new AlertManager()
    });
  }
}

Agent Registry System

class AgentRegistry {
  private agents: Map<string, AgentConfig> = new Map();
  private capabilities: Map<string, string[]> = new Map();

  register(agent: AgentConfig): void {
    this.agents.set(agent.id, agent);
    this.capabilities.set(agent.id, agent.capabilities);

    console.log(`🤖 Agent registered: ${agent.name} with capabilities: ${agent.capabilities.join(', ')}`);
  }

  findAgents(capability: string): AgentConfig[] {
    return Array.from(this.agents.values())
      .filter(agent => agent.capabilities.includes(capability));
  }

  getHealthStatus(): AgentHealth[] {
    return Array.from(this.agents.values()).map(agent => ({
      id: agent.id,
      name: agent.name,
      status: agent.isHealthy() ? 'healthy' : 'unhealthy',
      lastActivity: agent.lastActivity,
      load: agent.getCurrentLoad()
    }));
  }

  route(task: Task): AgentConfig {
    const capableAgents = this.findAgents(task.requiredCapability);
    return this.selectBestAgent(capableAgents, task);
  }
}

Creating Specialized Agents

Research Agent - The Information Gatherer

class ResearcherAgent extends ReActAgent {
  constructor(config: AgentConfig) {
    super({
      llm: new OpenAIAdapter({ 
        apiKey: process.env.OPENAI_API_KEY!,
        model: 'gpt-4'
      }),
      tools: [
        new WebSearchTool(),
        new DocumentAnalysisTool(),
        new DataExtractionTool()
      ],
      system: `You are a specialized research agent. Your role is to:
      1. Gather comprehensive information on given topics
      2. Verify sources and credibility
      3. Extract key insights and data points
      4. Organize findings for further analysis`,
      memory: config.sharedMemory
    });
  }

  @Trace({ type: 'research', name: 'comprehensive_research' })
  async conductResearch(query: string): Promise<ResearchResult> {
    const session = trace.session('research_session', {
      query,
      agent: 'researcher',
      timestamp: Date.now()
    });

    try {
      // Multi-source research
      const webResults = await this.tools.webSearch.execute(query);
      const docResults = await this.tools.documentAnalysis.execute(query);
      const extractedData = await this.tools.dataExtraction.execute(webResults);

      const result = {
        sources: [...webResults.sources, ...docResults.sources],
        keyFindings: extractedData.insights,
        confidence: this.calculateConfidence(webResults, docResults),
        metadata: {
          query,
          timestamp: Date.now(),
          agent: 'researcher'
        }
      };

      trace.end(session, result);
      return result;

    } catch (error) {
      trace.error(session, error);
      throw error;
    }
  }
}

Analyst Agent - The Data Interpreter

class AnalystAgent extends ReActAgent {
  constructor(config: AgentConfig) {
    super({
      llm: new OpenAIAdapter({ 
        apiKey: process.env.OPENAI_API_KEY!,
        model: 'gpt-4'
      }),
      tools: [
        new StatisticalAnalysisTool(),
        new VisualizationTool(),
        new PatternRecognitionTool()
      ],
      system: `You are a data analysis specialist. Your role is to:
      1. Analyze research data for patterns and insights
      2. Create statistical models and visualizations
      3. Identify trends and correlations
      4. Generate actionable insights from data`,
      memory: config.sharedMemory
    });
  }

  @Trace({ type: 'analysis', name: 'data_analysis' })
  async analyzeData(researchData: ResearchResult): Promise<AnalysisResult> {
    const analysis = await this.tools.statisticalAnalysis.execute(researchData);
    const visualizations = await this.tools.visualization.execute(analysis);
    const patterns = await this.tools.patternRecognition.execute(analysis);

    return {
      analysis,
      visualizations,
      patterns,
      insights: this.generateInsights(patterns),
      confidence: analysis.confidence,
      recommendations: this.generateRecommendations(patterns)
    };
  }
}

Writer Agent - The Content Creator

class WriterAgent extends ReActAgent {
  constructor(config: AgentConfig) {
    super({
      llm: new OpenAIAdapter({ 
        apiKey: process.env.OPENAI_API_KEY!,
        model: 'gpt-4'
      }),
      tools: [
        new ContentGenerationTool(),
        new FormattingTool(),
        new ReviewTool()
      ],
      system: `You are a professional content writer. Your role is to:
      1. Create engaging, well-structured content
      2. Ensure clarity and readability
      3. Follow best practices for the target format
      4. Incorporate insights from research and analysis`,
      memory: config.sharedMemory
    });
  }

  @Trace({ type: 'writing', name: 'content_creation' })
  async createContent(analysis: AnalysisResult, format: 'article' | 'report' | 'summary'): Promise<ContentResult> {
    const content = await this.tools.contentGeneration.execute({
      analysis,
      format,
      style: 'professional'
    });

    const formatted = await this.tools.formatting.execute(content, format);
    const reviewed = await this.tools.review.execute(formatted);

    return {
      content: reviewed,
      format,
      wordCount: content.wordCount,
      readabilityScore: reviewed.readability,
      metadata: {
        createdAt: Date.now(),
        agent: 'writer',
        version: '1.0'
      }
    };
  }
}

Agent Communication Protocol

Message System Architecture

interface A2AMessage {
  id: string;
  from: AgentId;
  to: AgentId;
  type: 'request' | 'response' | 'broadcast';
  payload: TaskPayload;
  priority: 'low' | 'medium' | 'high' | 'critical';
  timestamp: number;
  metadata: MessageMetadata;
}

class A2ACommunicationProtocol {
  async sendMessage(message: A2AMessage): Promise<void> {
    // Message validation
    this.validateMessage(message);

    // Route determination
    const route = await this.determineRoute(message);

    // Delivery with retry logic
    await this.messageQueue.publish(route.topic, message);

    // Tracking and monitoring
    await this.monitoring.trackMessage(message);
  }

  async createCollaboration(
    primaryAgent: AgentId,
    supportingAgents: AgentId[],
    task: ComplexTask
  ): Promise<CollaborationSession> {
    const session = new CollaborationSession({
      id: generateId(),
      participants: [primaryAgent, ...supportingAgents],
      task,
      communicationProtocol: this
    });

    // Setup communication channels
    await this.setupCollaborationChannels(session);

    // Initialize shared context
    await this.sharedMemory.createSharedContext(session.id, task.context);

    return session;
  }
}

Real-time Agent Collaboration

class AgentCollaboration {
  async executeCollaborativeTask(task: ComplexTask): Promise<TaskResult> {
    const session = await this.communication.createCollaboration(
      task.primaryAgent,
      task.supportingAgents,
      task
    );

    try {
      // Phase 1: Research
      const researchResults = await this.executePhase('research', session);

      // Phase 2: Analysis (parallel with research if possible)
      const analysisResults = await this.executePhase('analysis', session, researchResults);

      // Phase 3: Content Creation
      const contentResults = await this.executePhase('writing', session, analysisResults);

      // Phase 4: Quality Assurance
      const validatedResults = await this.executePhase('validation', session, contentResults);

      return {
        result: validatedResults,
        session: session.id,
        metrics: this.collectSessionMetrics(session),
        timeline: this.getSessionTimeline(session)
      };

    } finally {
      await this.cleanupSession(session);
    }
  }

  private async executePhase(
    phase: string, 
    session: CollaborationSession, 
    input?: any
  ): Promise<PhaseResult> {
    const agents = this.getAgentsForPhase(phase, session);
    const tasks = this.createPhaseTasks(phase, input);

    // Execute tasks in parallel when possible
    const results = await Promise.allSettled(
      agents.map(agent => this.executeAgentTask(agent, tasks))
    );

    return this.consolidatePhaseResults(results);
  }
}

📊 Workflow Orchestration with Graph

Graph-based A2A Workflows

import { Graph } from 'orkajs';

class A2AWorkflowEngine {
  private graph: Graph;
  private executionEngine: WorkflowExecutionEngine;

  constructor() {
    this.graph = new Graph();
    this.setupWorkflowNodes();
    this.defineExecutionPaths();
  }

  private setupWorkflowNodes() {
    // Research Pipeline
    this.graph.addNode('research_start', {
      agent: 'researcher',
      condition: (data) => data.requiresResearch,
      parallel: true,
      timeout: 300000 // 5 minutes
    });

    this.graph.addNode('data_analysis', {
      agent: 'analyst',
      condition: (data) => data.hasData,
      dependencies: ['research_start'],
      parallel: false,
      timeout: 180000 // 3 minutes
    });

    this.graph.addNode('content_creation', {
      agent: 'writer',
      condition: (data) => data.needsContent,
      dependencies: ['data_analysis'],
      parallel: false,
      timeout: 240000 // 4 minutes
    });

    // Validation Pipeline (can run in parallel with content creation)
    this.graph.addNode('fact_check', {
      agent: 'factChecker',
      condition: (data) => data.requiresValidation,
      dependencies: ['data_analysis'],
      parallel: true,
      timeout: 120000 // 2 minutes
    });

    this.graph.addNode('quality_review', {
      agent: 'validator',
      condition: (data) => data.needsReview,
      dependencies: ['content_creation', 'fact_check'],
      parallel: false,
      timeout: 180000 // 3 minutes
    });
  }

  async executeWorkflow(workflowId: string, input: WorkflowInput): Promise<WorkflowResult> {
    const execution = this.executionEngine.create(workflowId, input);

    try {
      const result = await this.executionEngine.run(execution, {
        coordination: 'a2a',
        monitoring: 'full',
        fallback: 'graceful',
        retryPolicy: 'exponential'
      });

      await this.monitoring.recordWorkflowMetrics(execution, result);
      return result;

    } catch (error) {
      await this.handleWorkflowError(execution, error);
      throw error;
    }
  }
}

Advanced Monitoring & Observability

A2A-Specific Monitoring

class A2AMonitoringService {
  private tracer: TraceCollector;
  private metrics: MetricsCollector;
  private alerts: AlertManager;

  async trackAgentInteraction(
    fromAgent: string,
    toAgent: string,
    interaction: AgentInteraction
  ): Promise<void> {
    const trace = this.tracer.start('a2a_interaction', 'agent_communication', {
      fromAgent,
      toAgent,
      interactionType: interaction.type,
      taskComplexity: interaction.complexity
    });

    try {
      const startTime = Date.now();
      const result = await this.executeInteraction(interaction);
      const latency = Date.now() - startTime;

      // Record performance metrics
      this.metrics.record('a2a_communication_latency', latency, {
        fromAgent,
        toAgent,
        interactionType: interaction.type
      });

      // Track success rates
      this.metrics.increment('a2a_communications_success', {
        fromAgent,
        toAgent
      });

      this.tracer.end(trace, result, {
        latency,
        success: true,
        dataSize: result.size
      });

    } catch (error) {
      this.tracer.error(trace, error);
      this.metrics.increment('a2a_communication_errors', {
        fromAgent,
        toAgent,
        errorType: error.constructor.name
      });

      // Trigger alert for critical errors
      if (interaction.priority === 'critical') {
        await this.alerts.trigger('critical_a2a_error', {
          fromAgent,
          toAgent,
          error: error.message,
          timestamp: Date.now()
        });
      }
    }
  }

  async generateA2ADashboard(): Promise<A2ADashboard> {
    const metrics = await this.collectA2AMetrics();

    return {
      agentHealth: await this.getAgentHealthStatus(),
      communicationFlows: await this.analyzeCommunicationPatterns(),
      performanceMetrics: metrics.performance,
      collaborationInsights: await this.analyzeCollaborationPatterns(),
      resourceUtilization: await this.getResourceUtilization(),
      activeWorkflows: await this.getActiveWorkflows(),
      errorRates: await this.getErrorRates()
    };
  }
}

Real-time Dashboard

class A2ADashboard {
  async displayRealTimeMetrics(): Promise<void> {
    const dashboard = await this.monitoring.generateA2ADashboard();

    console.log(`
🤖 A2A System Dashboard
========================

Agent Health:
${dashboard.agentHealth.map(agent => 
  `  ${agent.name}: ${agent.status} (Load: ${agent.load}%)`
).join('\n')}

Active Workflows:
${dashboard.activeWorkflows.map(workflow => 
  `  ${workflow.id}: ${workflow.status} (${workflow.progress}%)`
).join('\n')}

Performance Metrics:
  - Avg Communication Latency: ${dashboard.performanceMetrics.avgLatency}ms
  - Success Rate: ${(dashboard.performanceMetrics.successRate * 100).toFixed(1)}%
  - Throughput: ${dashboard.performanceMetrics.requestsPerSecond}/sec

Communication Flows:
${dashboard.communicationFlows.map(flow => 
  `  ${flow.from} → ${flow.to}: ${flow.messageCount} messages (${flow.avgLatency}ms)`
).join('\n')}
    `);
  }
}

Production Deployment

Complete System Configuration

interface A2ASystemConfig {
  // Infrastructure Configuration
  infrastructure: {
    llm: {
      providers: [
        { name: 'openai', model: 'gpt-4', weight: 0.7 },
        { name: 'anthropic', model: 'claude-3', weight: 0.3 }
      ];
      poolSize: 10;
      fallbackStrategy: 'cascade';
    };
    storage: {
      vectorStore: {
        provider: 'pinecone',
        environment: 'us-west1',
        indexName: 'a2a-knowledge'
      };
      cache: {
        provider: 'redis',
        url: process.env.REDIS_URL,
        ttl: 3600
      };
      database: {
        provider: 'postgresql',
        url: process.env.DATABASE_URL
      };
    };
    messaging: {
      broker: {
        provider: 'rabbitmq',
        url: process.env.RABBITMQ_URL
      };
      queueSize: 1000;
      retryPolicy: {
        maxAttempts: 3,
        backoff: 'exponential'
      };
    };
  };

  // Agents Configuration
  agents: {
    specialized: [
      {
        id: 'researcher-001',
        name: 'Research Agent Alpha',
        capabilities: ['research', 'data_collection', 'analysis'],
        maxConcurrentTasks: 5
      },
      {
        id: 'analyst-001', 
        name: 'Analyst Agent Beta',
        capabilities: ['analysis', 'modeling', 'visualization'],
        maxConcurrentTasks: 3
      },
      {
        id: 'writer-001',
        name: 'Writer Agent Gamma', 
        capabilities: ['writing', 'formatting', 'editing'],
        maxConcurrentTasks: 4
      }
    ];
    orchestration: {
      supervisor: {
        strategy: 'hierarchical',
        decisionTimeout: 30000
      };
      coordinator: {
        routing: 'intelligent',
        loadBalancing: 'least_loaded'
      };
    };
    scaling: {
      autoScale: true,
      minInstances: 2,
      maxInstances: 10,
      targetCpuUtilization: 70
    };
  };

  // Security Configuration
  security: {
    authentication: {
      method: 'jwt',
      secretKey: process.env.JWT_SECRET
    };
    authorization: {
      rbac: true,
      policies: ['agent-to-agent', 'human-supervisor']
    };
    audit: {
      logLevel: 'info',
      retention: '90d',
      encryption: true
    };
  };
}

Deployment Script

class A2ADeployment {
  async deploy(config: A2ASystemConfig): Promise<DeploymentResult> {
    console.log('🚀 Deploying A2A System...');

    try {
      // 1. Infrastructure Setup
      await this.setupInfrastructure(config.infrastructure);
      console.log('✅ Infrastructure ready');

      // 2. Agent Deployment
      await this.deployAgents(config.agents);
      console.log('✅ Agents deployed');

      // 3. Communication Channels
      await this.establishCommunication(config.messaging);
      console.log('✅ Communication established');

      // 4. Monitoring Setup
      await this.setupMonitoring(config.monitoring);
      console.log('✅ Monitoring active');

      // 5. Health Checks
      await this.runHealthChecks();
      console.log('✅ Health checks passed');

      return {
        status: 'deployed',
        endpoints: this.getEndpoints(),
        health: 'healthy',
        timestamp: Date.now()
      };

    } catch (error) {
      console.error('❌ Deployment failed:', error);
      await this.rollback();
      throw error;
    }
  }

  private async setupInfrastructure(infra: InfrastructureConfig): Promise<void> {
    // Setup vector store
    await this.setupVectorStore(infra.storage.vectorStore);

    // Setup cache
    await this.setupCache(infra.storage.cache);

    // Setup database
    await this.setupDatabase(infra.storage.database);

    // Setup message broker
    await this.setupMessageBroker(infra.messaging.broker);
  }
}

🎯 Real-World Use Cases
Use Case 1: Research Content Pipeline

// Example: Automated Research Report Generation
const researchPipeline = new A2AWorkflowEngine();

const report = await researchPipeline.executeWorkflow('research_report', {
  topic: 'AI Trends in 2024',
  requirements: {
    researchDepth: 'comprehensive',
    analysisType: 'statistical',
    contentFormat: 'executive_summary',
    validationLevel: 'high'
  }
});

console.log('📊 Research Report Generated:', report);

Use Case 2: Customer Support System

// Example: Multi-Agent Customer Support
const supportSystem = new A2ASystem(supportConfig);

const ticket = await supportSystem.handleCustomerTicket({
  query: 'How to integrate OrkaJS with our existing system?',
  priority: 'high',
  customerTier: 'enterprise',
  language: 'en'
});

console.log('🎫 Ticket Resolved:', ticket.resolution);

Use Case 2: Customer Support System

// Example: Multi-Agent Customer Support
const supportSystem = new A2ASystem(supportConfig);

const ticket = await supportSystem.handleCustomerTicket({
  query: 'How to integrate OrkaJS with our existing system?',
  priority: 'high',
  customerTier: 'enterprise',
  language: 'en'
});

console.log('🎫 Ticket Resolved:', ticket.resolution);

Best Practices & Tips
Performance Optimization
Load Balancing: Distribute tasks evenly across agents
Caching: Cache frequent communications and results
Parallel Execution: Run independent tasks simultaneously
Resource Management: Monitor and optimize resource usage
Error Handling
Graceful Degradation: Continue with available agents if some fail
Retry Logic: Implement exponential backoff for failed communications
Fallback Strategies: Have backup agents for critical tasks
Circuit Breakers: Prevent cascade failures
Security Considerations
Authentication: Secure agent-to-agent communications
Authorization: Control what agents can access
Audit Logging: Track all agent interactions
Data Privacy: Protect sensitive information shared between agents

Monitoring & Analytics
Track these key metrics for your A2A system:

Communication Latency: Time between agent messages
Success Rate: Percentage of successful agent interactions
Throughput: Number of tasks completed per hour
Agent Utilization: How busy each agent is
Error Rates: Frequency of failed communications
Collaboration Patterns: Which agents work best together

🎉 Conclusion
Building A2A systems with OrkaJS opens up incredible possibilities for creating sophisticated, intelligent applications that can tackle complex problems through agent collaboration.

The combination of OrkaJS's native A2A capabilities, powerful orchestration tools, and comprehensive monitoring makes it the ideal choice for production-ready multi-agent systems.

Whether you're building automated research pipelines, customer support systems, or content creation platforms, OrkaJS provides the foundation you need to create robust, scalable, and intelligent A2A architectures.

The TypeScript Framework That Makes LLM Development Actually Simple

Siddick FOFANA — Wed, 04 Mar 2026 20:11:42 +0000

OrkaJS (Orchestration Knowledge & Agent)

If you've tried building an LLM-powered application recently, you know the pain. The ecosystem is fragmented, frameworks are complex, and you're often locked into specific providers. After months of frustration, I built OrkaJS to solve these problems.

The Problem

Let me paint a picture. You want to add RAG (Retrieval-Augmented Generation) to your app. Simple, right?

Reality check:

Learn a framework-specific API (steep learning curve)
Get locked into one LLM provider
Manually handle retries, caching, and error handling
Write custom code for each vector database
Spend weeks on infrastructure instead of features

What you actually want:

const result = await orka.ask({
  question: 'How do I reset my password?',
  knowledge: 'support-docs'
});

That's it. That's OrkaJS.

What is OrkaJS?

OrkaJS is a progressive TypeScript framework for building production-ready LLM systems. It's designed with three core principles:

Universal Compatibility - Works with ANY JS/TS framework (Next.js SSR, Express, NestJS, Fastify, AdonisJS, KoaJS, Hono...)
Pluggable Architecture - Swap LLMs or vector databases in 3 lines of code
Production-Ready - Resilience, caching, evaluation, and observability built-in

Quick Start (Literally 2 Minutes)

Installation

npm install orkajs

Basic RAG in 10 Lines

import { createOrka, OpenAIAdapter, MemoryVectorAdapter } from 'orkajs';

const orka = createOrka({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
  vectorDB: new MemoryVectorAdapter(),
});

// Create knowledge base
await orka.knowledge.create({
  name: 'docs',
  source: ['OrkaJS is a TypeScript framework for LLM systems.'],
});

// Ask with RAG
const result = await orka.ask({
  knowledge: 'docs',
  question: 'What is OrkaJS?',
});

console.log(result.answer);

That's it. No complex configuration, no boilerplate, no vendor lock-in.

Why OrkaJS is Different

1. Works Everywhere

Same code, any framework:

// Next.js API Route
export async function POST(req: Request) {
  const { question } = await req.json();
  const answer = await orka.ask({ question, knowledge: 'docs' });
  return Response.json({ answer });
}

// Express.js
app.post('/ask', async (req, res) => {
  const { question } = req.body;
  const answer = await orka.ask({ question, knowledge: 'docs' });
  res.json({ answer });
});

// NestJS
@Post('ask')
async ask(@Body() body: AskDto) {
  return this.orka.ask({ question: body.question, knowledge: 'docs' });
}

2. Swap Providers in Seconds

// Development: Use Ollama locally
const orka = createOrka({
  llm: new OllamaAdapter({ model: 'llama2' }),
  vectorDB: new MemoryVectorAdapter(),
});

// Production: Switch to OpenAI + Pinecone
const orka = createOrka({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
  vectorDB: new PineconeAdapter({ 
    apiKey: process.env.PINECONE_API_KEY,
    indexHost: process.env.PINECONE_HOST 
  }),
});

Same API. Zero code changes.

3. Production Patterns Built-In

Automatic Retries with Exponential Backoff

import { ResilientLLM } from 'orkajs/resilience';

const llm = new ResilientLLM(
  new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
  { maxRetries: 3, backoffMs: 1000 }
);

Multi-Provider Fallback

import { FallbackLLM } from 'orkajs/resilience';

const llm = new FallbackLLM([
  new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
  new AnthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }),
  new OllamaAdapter({ model: 'llama2' }), // Local fallback
]);

Intelligent Caching

import { CachedLLM } from 'orkajs/cache';
import { RedisCache } from 'orkajs/cache/redis';

const llm = new CachedLLM(
  new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
  new RedisCache({ url: process.env.REDIS_URL })
);

Advanced Features

🤖 Intelligent Agents

OrkaJS includes multiple agent architectures:

ReAct Agent (Reasoning + Acting):

import { ReActAgent } from 'orkajs/agent/react';

const agent = new ReActAgent({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
  tools: [searchTool, calculatorTool],
  maxIterations: 5,
});

const result = await agent.run('What is the weather in Paris and what is 25 * 4?');

Plan & Execute Agent:

import { PlanAndExecuteAgent } from 'orkajs/agent/plan-and-execute';

const agent = new PlanAndExecuteAgent({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
  tools: [webSearchTool, calculatorTool, weatherTool],
});

const result = await agent.run('Research competitors and create a pricing strategy');

🔄 Multi-Model Orchestration

Router (route queries to specialized models):

import { RouterLLM } from 'orkajs/orchestration';

const router = new RouterLLM({
  router: new OpenAIAdapter({ model: 'gpt-4o-mini' }), // Fast router
  routes: [
    {
      name: 'code',
      llm: new OpenAIAdapter({ model: 'gpt-4o' }),
      condition: (prompt) => prompt.includes('code') || prompt.includes('function'),
    },
    {
      name: 'creative',
      llm: new AnthropicAdapter({ model: 'claude-3-5-sonnet-20241022' }),
      condition: (prompt) => prompt.includes('story') || prompt.includes('creative'),
    },
  ],
  fallback: new OpenAIAdapter({ model: 'gpt-4o-mini' }),
});

Consensus (multiple models vote):

import { ConsensusLLM } from 'orkajs/orchestration';

const consensus = new ConsensusLLM({
  llms: [
    new OpenAIAdapter({ model: 'gpt-4o' }),
    new AnthropicAdapter({ model: 'claude-3-5-sonnet-20241022' }),
    new MistralAdapter({ model: 'mistral-large-latest' }),
  ],
  strategy: 'majority', // or 'unanimous'
});

📊 Built-in Evaluation

import { TestRunner } from 'orkajs/evaluation';

const runner = new TestRunner(orka);

await runner.test('RAG Quality', async () => {
  const result = await orka.ask({
    question: 'How do I reset my password?',
    knowledge: 'support-docs',
    includeContext: true,
  });

  runner.assert.relevance(result.answer, result.context, 0.8);
  runner.assert.faithfulness(result.answer, result.context, 0.9);
  runner.assert.noHallucination(result.answer, result.context);
});

await runner.run();

🔍 Advanced Retrievers

import { MultiQueryRetriever } from 'orkajs/retrievers';

const retriever = new MultiQueryRetriever({
  vectorDB: new PineconeAdapter({ /* config */ }),
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
  numQueries: 3, // Generate 3 variations of the query
});

const chunks = await retriever.retrieve('How to reset password?');
// Generates: "reset password", "change password", "password recovery"
// Returns combined unique results

Real-World Example: Customer Support Bot

Here's a complete example of a production-ready support bot:

import { createOrka, OpenAIAdapter, PineconeAdapter } from 'orkajs';
import { ResilientLLM } from 'orkajs/resilience';
import { CachedLLM } from 'orkajs/cache';
import { RedisCache } from 'orkajs/cache/redis';

// 1. Setup with production patterns
const llm = new CachedLLM(
  new ResilientLLM(
    new OpenAIAdapter({ 
      apiKey: process.env.OPENAI_API_KEY,
      model: 'gpt-4o-mini',
    }),
    { maxRetries: 3, backoffMs: 1000 }
  ),
  new RedisCache({ url: process.env.REDIS_URL })
);

const orka = createOrka({
  llm,
  vectorDB: new PineconeAdapter({
    apiKey: process.env.PINECONE_API_KEY,
    indexHost: process.env.PINECONE_HOST,
  }),
});

// 2. Index your documentation
await orka.knowledge.create({
  name: 'support-docs',
  source: { path: './docs' }, // Auto-loads all files
  chunkSize: 1000,
  chunkOverlap: 200,
});

// 3. Handle user questions
export async function handleSupportQuestion(question: string) {
  const { answer, context } = await orka.ask({
    question,
    knowledge: 'support-docs',
    systemPrompt: 'You are a helpful support agent. Be concise and friendly.',
    topK: 5,
    includeContext: true,
  });

  return {
    answer,
    sources: context.map(c => ({
      content: c.content.slice(0, 100),
      score: c.score,
    })),
  };
}

Framework Comparison

Feature	OrkaJS	LangChain	LlamaIndex
Learning Curve	⭐⭐⭐⭐⭐ Low	⭐⭐ High	⭐⭐⭐ Medium
TypeScript-First	✅ Native	⚠️ Port	⚠️ Python-first
Framework Agnostic	✅ All JS/TS	⚠️ Limited	⚠️ Limited
Pluggable Providers	✅ 3 lines	⚠️ Complex	⚠️ Complex
Production Patterns	✅ Built-in	❌ Manual	❌ Manual
Tree-shaking	✅ Optimized	❌ No	❌ No
Bundle Size	🟢 Small	🔴 Large	🔴 Large

Architecture Philosophy

OrkaJS is built on three pillars:

1. Intent-Based API

Focus on what you want, not how to do it:

// ✅ OrkaJS - Intent-based
await orka.ask({ question, knowledge: 'docs' });

// ❌ Other frameworks - Implementation-based
const vectorStore = await loadVectorStore();
const retriever = vectorStore.asRetriever();
const chain = RetrievalQAChain.fromLLM(llm, retriever);
const result = await chain.call({ query: question });

2. Adapter Pattern

Every external dependency is an adapter implementing a simple interface:

interface LLMAdapter {
  generate(prompt: string, options?: GenerateOptions): Promise<string>;
  embed(texts: string[]): Promise<number[][]>;
}

interface VectorDBAdapter {
  upsert(chunks: Chunk[]): Promise<void>;
  search(query: number[], topK: number): Promise<ChunkResult[]>;
}

Swap implementations without changing your code.

3. Progressive Enhancement

Start simple, add complexity only when needed:

// Day 1: Simple RAG
const answer = await orka.ask({ question, knowledge: 'docs' });

// Week 2: Add caching
const llm = new CachedLLM(baseAdapter, cache);

// Month 3: Add multi-provider fallback
const llm = new FallbackLLM([primary, secondary, local]);

// Month 6: Add custom evaluation
await runner.test('Quality', async () => { /* tests */ });

Check out the Quick Start Guide and build your first LLM-powered feature in 10 minutes.

Why I use Typetify: A Type-Safe Alternative to Lodash

Siddick FOFANA — Sat, 07 Feb 2026 12:28:45 +0000

Runtime TypeScript helpers that actually protect you when it matters most.

Why I Built Typetify: A Type-Safe Alternative to Lodash

TL;DR: I built Typetify — a zero-dependency utility library for TypeScript that provides runtime safety, not just compile-time types. Think Lodash, but TypeScript-first.

npm install typetify

The Problem with Lodash + TypeScript

Lodash is great. I've used it for years. But when you add TypeScript to the mix, something feels... off.

Example: The `_.pick()` Trap

import _ from 'lodash'

const user = {
  id: 1,
  name: 'John',
  email: 'john@example.com',
  password: 'secret123'
}

// TypeScript says this is fine 🤷
const safe = _.pick(user, ['id', 'name', 'emial']) // Typo!
//                                        ^^^^^^

// Runtime: { id: 1, name: 'John', emial: undefined }
// No error, no warning, just silent failure

TypeScript can't catch this because Lodash's types are too permissive. The keys are typed as string[], not the actual keys of the object.

Example: The `_.isString()` Trap

function processValue(value: unknown) {
  if (_.isString(value)) {
    return value.toUpperCase()
    //     ^^^^^ TS Error: Object is of type 'unknown'
  }
}

Lodash's type guards don't narrow types properly. You get runtime safety, but TypeScript still doesn't trust the check.

The Solution: TypeScript-First Design

Typetify solves these issues by being designed for TypeScript, not retrofitted to it.

Type-Safe `pick()`

import { pick } from 'typetify/object'

const user = {
  id: 1,
  name: 'John',
  email: 'john@example.com',
  password: 'secret123'
}

const safe = pick(user, ['id', 'name'])
// Type: { id: number; name: string }

// This won't compile:
const invalid = pick(user, ['id', 'emial'])
//                                ^^^^^^^ TS Error: 'emial' is not a key of user

The keys are actually type-checked. No typos, no silent failures.

Proper Type Narrowing

import { isString } from 'typetify/guards'

function processValue(value: unknown) {
  if (isString(value)) {
    return value.toUpperCase() // ✅ TypeScript knows it's a string
  }
}

Type guards that actually work with TypeScript's control flow analysis.

5 Real-World Use Cases

1. API Response Validation

import { hasKeys, awaitTo } from 'typetify'

async function fetchUser(id: string) {
  const [error, response] = await awaitTo(fetch(`/api/users/${id}`))
  if (error) return { error: 'Network error' }

  const data = await response.json()

  // Runtime validation with type safety
  if (!hasKeys(data, ['id', 'name', 'email'])) {
    return { error: 'Invalid response' }
  }

  // TypeScript now knows data has these keys
  return { data }
}

2. Error Handling Without try/catch

import { awaitTo, retry, withTimeout } from 'typetify/async'

async function fetchWithRetry(url: string) {
  const [error, data] = await awaitTo(
    retry(
      () => withTimeout(fetch(url), 5000),
      { attempts: 3, delay: 1000 }
    )
  )

  if (error) {
    console.error('Failed after retries:', error)
    return null
  }

  return data
}

No more nested try/catch blocks. Clean, readable error handling.

3. Form Data Processing

import { parseNumber, parseBoolean, compact, defaults } from 'typetify/input'

function processFormData(formData: FormData) {
  return {
    age: parseNumber(formData.get('age')), // number | undefined
    newsletter: parseBoolean(formData.get('newsletter')), // boolean
    tags: compact(formData.getAll('tags')), // string[]
    bio: defaults(formData.get('bio'), 'No bio provided'), // string
  }
}

Parse external data safely with proper TypeScript types.

4. Filtering Arrays

import { isDefined } from 'typetify/core'

// Problem: TypeScript doesn't narrow this
const items = [1, null, 2, undefined, 3]
const numbers = items.filter(x => x != null) // (number | null | undefined)[]

// Solution: Proper type guard
const numbers = items.filter(isDefined) // number[] ✅

5. Safe JSON Parsing

import { safeJsonParse } from 'typetify/input'

const result = safeJsonParse(jsonString)

if (result.ok) {
  console.log(result.data.name) // Type-safe access
} else {
  console.error(result.error) // Handle error
}

// No try/catch needed

The Design Philosophy

1. Runtime First

Types are great, but they disappear at runtime. Typetify gives you both.

import { assert } from 'typetify/core'

function getUser(id: string) {
  const user = findUser(id) // User | null

  assert(user, `User ${id} not found`)
  // TypeScript now knows user is User (not null)

  return user.name // Safe!
}

2. No Magic

Every function does exactly what it says. No hidden behavior, no gotchas.

import { pipe } from 'typetify/flow'

const result = pipe(
  5,
  n => n * 2,    // 10
  n => n + 1,    // 11
  n => `Result: ${n}` // 'Result: 11'
)

Simple composition. No magic.

3. Tree-Shakable

Only bundle what you use.

// Import specific functions
import { pick } from 'typetify/object'
import { retry } from 'typetify/async'

// Or import from specific modules
import * as object from 'typetify/object'

Your bundler will only include what you import.

4. Zero Dependencies

$ npm ls typetify
typetify@2.1.0
└── (no dependencies)

No bloat. No supply chain risks. Just pure TypeScript.

Comparing to Alternatives

Feature	Lodash	Ramda	Typetify
TypeScript-first	❌	❌	✅
Runtime safety	❌	❌	✅
Type narrowing	❌	❌	✅
Zero dependencies	❌	✅	✅
Tree-shakable	⚠️ Partial	✅	✅
Modern syntax	❌	⚠️	✅
Active maintenance	⚠️ Slowing	✅	✅

The Complete Feature Set

Typetify includes 18 modules covering:

Core - isDefined, assert, noop, identity
Guards - isString, isNumber, isObject, hasKey
Object - pick, omit, mapObject, get, set
Async - awaitTo, retry, debounce, throttle
Collection - unique, groupBy, partition, chunk
Input - safeJsonParse, parseNumber, parseBoolean
Flow - pipe, tap, match, tryCatch
String - String manipulation utilities
Math - Math utilities
Result - Result type pattern
Iterator - Iterator utilities
Decorator - TypeScript decorators
Logic - Logic utilities
Narrowing - Advanced type narrowing
Schema - Schema validation
DX - debug, invariant, measure, todo
Typed - Type utilities and branded types
Fn - Function utilities

See full documentation

Getting Started

npm install typetify

import { isDefined, pick, awaitTo } from 'typetify'

// Or use the Lodash-style _ namespace
import { _ } from 'typetify'
const safe = _.pick(user, ['id', 'name'])

What's Next?

I'd love to hear your feedback! Some areas I'm exploring:

🔍 More schema validation utilities (like Zod-lite)
🎯 Performance benchmarks vs Lodash/Ramda
📦 Plugin system for custom utilities
🧪 More real-world examples and recipes

Try It Out

🔗 GitHub: github.com/CodeSenior/typetify

📦 npm: npmjs.com/package/typetify

📚 Docs: typetify.hosby.io

Give it a try and let me know what you think! Stars ⭐ on GitHub are always appreciated.

Join the Discussion

What utility functions do you wish existed in TypeScript? Drop a comment below! 👇

P.S. We hit 477 downloads in the first 48 hours! 🚀 Thank you to everyone who's trying it out.

🚀 Hosby is online: the backend designed for front-end developers

Siddick FOFANA — Wed, 20 Aug 2025 07:48:58 +0000

Do you develop on the front end with Next.js, React, Vue, Svelte… but get stuck when it comes to backend management?
That's exactly why I created Hosby.

With Hosby, you can:

Create a project in two steps: Project → Table.

Instantly generate secure REST APIs (GET, POST, PUT, DELETE).

Store and manipulate your data without writing a single line of backend.

Focus solely on your front end, Hosby takes care of the rest.

💡 Hosby is designed for front-end developers who want to ship quickly, without struggling with server configuration or the database.

👉 Discover Hosby here: https://hosby.io/en

🚀 Stop Building Backends: Instantly Get Secure, Customizable APIs with Hosby

Siddick FOFANA — Tue, 20 May 2025 17:04:10 +0000

If you’ve ever built a frontend app and thought:

"Ugh, now I have to set up a backend just to store some data?"

This is for you.

Hosby lets you skip the backend boilerplate and gives you production-ready APIs instantly, without writing a single line of backend code.

💡 What is Hosby?

Hosby is an API-first backend-as-a-service designed for front-end developers.

You define your data models → Hosby generates a complete set of secure API routes to query, insert, update, and delete data.

It's like Firebase Firestore — but with REST endpoints, auth, webhooks, and zero vendor lock-in.

⚙️ How it works

1. Create a table (resource):

{ "name": "posts", "fields": { "title": "string", "content": "text", "authorId": "string" } }

Hosby instantly gives you REST API routes like:
| Method | Route | Description |
| ------ | -------------------------------- | -------------------------- |
| POST | /api/posts/insertOne | Insert a new post |
| GET | /api/posts/findBy?authorId=xyz | Find all posts by authorId |
| GET | /api/posts/findOne?id=... | Find one post by ID |
| PATCH | /api/posts/update | Update one or many posts |
| DELETE | /api/posts/deleteBy?id=... | Delete post by ID |

You don’t write any backend logic.
Just call the APIs from your frontend like you would with Axios, fetch, or TanStack Query.

🔐 Security by default
🌐 Each API key has its own permissions

🔑 Public vs private API key separation

🔄 Built-in auth support (email, Google, Facebook)

🧠 Rate limiting and access rules (coming soon)

🛠 Built for dev workflows
✅ Test everything locally before going live

📦 Deploy your API instantly to production (no config)

🔧 Webhooks: plug into Stripe, SendGrid, or your own services

📘 Auto-generated API docs (Postman / Swagger style)

*Example: using Hosby from the frontend *

// Create a post
await fetch("https://api.hosby.io/project/posts/insertOne", { method: "POST", headers: { "Authorization": "Bearer YOUR_PUBLIC_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ title: "Hello Dev.to!", content: "This was created via Hosby 🎉", authorId: "abc123" }) });
No backend. No middleware. No database setup.
Just clean, ready-to-use APIs.

Ideal for:
Front-end developers building projects fast

Indie hackers validating MVPs

Bootcamp students or junior devs who don’t want to touch backend yet

Agencies & freelancers with tight deadlines

https://hosby.io

DEV Community: Siddick FOFANA

My AI Agents as First-Class NestJS Citizens

Install

1. OrkaModule — Register Agents in the DI Container

2. forRootAsync — Config from ConfigService

3. @InjectAgent — Use Agents Anywhere

4. @AgentReact — Event-Driven Agents

5. OrkaSemanticGuard — LLM as a Security Layer

6. AgentValidationPipe — NLP → DTO

7. CQRS Integration

8. Agent as Microservice

Putting It Together: A Real Feature

The Complete Feature Set

Testing

How to Build a Durable AI Agent in 10 Lines of TypeScript

The Problem: Agents Are Ephemeral by Default

The Solution: @orka-js/durable

What DurableAgent Actually Does

1. Every job has a persistent ID

2. Automatic retry with backoff

3. Human-in-the-loop: pause and resume

Production: Switch to Redis in One Line

Scheduled Agents: Cron for AI

Stream Events While Persisting State

The Mental Model Shift

Get Started

I built Design Canvas like lovable with Orka AI

🤖 Building Advanced Agent-to-Agent (A2A) Systems with OrkaJS: A Complete Architecture Guide

The TypeScript Framework That Makes LLM Development Actually Simple

OrkaJS (Orchestration Knowledge & Agent)

The Problem

What is OrkaJS?

Quick Start (Literally 2 Minutes)

Installation

Basic RAG in 10 Lines

Why OrkaJS is Different

1. Works Everywhere

2. Swap Providers in Seconds

3. Production Patterns Built-In

Automatic Retries with Exponential Backoff

Multi-Provider Fallback

Intelligent Caching

Advanced Features

🤖 Intelligent Agents

🔄 Multi-Model Orchestration

📊 Built-in Evaluation

🔍 Advanced Retrievers

Real-World Example: Customer Support Bot

Framework Comparison

Architecture Philosophy

1. Intent-Based API

2. Adapter Pattern

3. Progressive Enhancement

Why I use Typetify: A Type-Safe Alternative to Lodash

Why I Built Typetify: A Type-Safe Alternative to Lodash

The Problem with Lodash + TypeScript

Example: The _.pick() Trap

Example: The _.isString() Trap

The Solution: TypeScript-First Design

Type-Safe pick()

Proper Type Narrowing

5 Real-World Use Cases

1. API Response Validation

2. Error Handling Without try/catch

3. Form Data Processing

4. Filtering Arrays

5. Safe JSON Parsing

The Design Philosophy

1. Runtime First

2. No Magic

3. Tree-Shakable

4. Zero Dependencies

Comparing to Alternatives

The Complete Feature Set

Getting Started

What's Next?

Try It Out

Join the Discussion

🚀 Hosby is online: the backend designed for front-end developers

🚀 Stop Building Backends: Instantly Get Secure, Customizable APIs with Hosby

1. `OrkaModule` — Register Agents in the DI Container

2. `forRootAsync` — Config from `ConfigService`

3. `@InjectAgent` — Use Agents Anywhere

4. `@AgentReact` — Event-Driven Agents

5. `OrkaSemanticGuard` — LLM as a Security Layer

6. `AgentValidationPipe` — NLP → DTO

The Solution: `@orka-js/durable`

What `DurableAgent` Actually Does

Example: The `_.pick()` Trap

Example: The `_.isString()` Trap

Type-Safe `pick()`