Framework Integration

Seamless OrkaJS integration for web frameworks

Build production-ready agent APIs with Express or Hono. Get automatic routing, middleware, streaming support, and edge compatibility.

Express

Node.js standard — battle-tested, rich ecosystem, middleware support

✓ Full Node.js compatibility
✓ Extensive middleware ecosystem
✓ Session management

Hono

Edge-first — ultrafast, Cloudflare Workers, Deno, Bun compatible

✓ Edge runtime support
✓ Zero dependencies
✓ TypeScript-first

@orka-js/express — Express Middleware

Add OrkaJS agents to your Express applications with zero configuration.

Installation

npm install @orka-js/express express
# or
pnpm add @orka-js/express express

Basic Usage

express-basic.ts

import express from 'express';
import { createAgentMiddleware } from '@orka-js/express';
import { StreamingToolAgent } from '@orka-js/agent';
import { OpenAIAdapter } from '@orka-js/openai';
 
const app = express();
app.use(express.json());
 
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! });
 
const supportAgent = new StreamingToolAgent({
  goal: 'Help customers with their questions',
  tools: [searchKB, createTicket],
}, llm);
 
// Add agent middleware
app.use('/api/agent', createAgentMiddleware(supportAgent, {
  streaming: true,        // Enable SSE streaming
  cors: true,             // Enable CORS
  rateLimit: {
    windowMs: 60000,      // 1 minute
    max: 10,              // 10 requests per minute
  },
}));
 
app.listen(3000, () => console.log('Server running on port 3000'));
 
// POST /api/agent/chat
// { "message": "How do I reset my password?" }

Multi-Agent Router

express-advanced.ts

import express from 'express';
import { createAgentRouter } from '@orka-js/express';
import { Memory } from '@orka-js/memory-store';
 
const app = express();
 
// Multiple agents with different routes
const agents = {
  support: supportAgent,
  sales: salesAgent,
  technical: technicalAgent,
};
 
// Session memory per user
const sessions = new Map<string, Memory>();
 
const router = createAgentRouter(agents, {
  streaming: true,
  getMemory: (req) => {
    const sessionId = req.headers['x-session-id'] as string;
    if (!sessions.has(sessionId)) {
      sessions.set(sessionId, new Memory());
    }
    return sessions.get(sessionId)!;
  },
  onError: (err, req, res) => {
    console.error('Agent error:', err);
    res.status(500).json({ error: 'Agent failed' });
  },
});
 
app.use('/api/agents', router);
 
// POST /api/agents/support/chat
// POST /api/agents/sales/chat
// POST /api/agents/technical/chat
 
app.listen(3000);

@orka-js/hono — Hono Integration

Edge-compatible agent APIs with Hono (Cloudflare Workers, Deno, Bun).

Installation

npm install @orka-js/hono hono
# or
pnpm add @orka-js/hono hono

Basic Usage

hono-basic.ts

import { Hono } from 'hono';
import { createAgentApp } from '@orka-js/hono';
import { StreamingToolAgent } from '@orka-js/agent';
import { OpenAIAdapter } from '@orka-js/openai';
 
const app = new Hono();
 
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! });
 
const agent = new StreamingToolAgent({
  goal: 'Answer questions about our products',
  tools: [searchProducts, getProductDetails],
}, llm);
 
// Mount agent routes
const agentApp = createAgentApp(agent, {
  streaming: true,
  path: '/agent',
});
 
app.route('/', agentApp);
 
// Deploy to Cloudflare Workers, Deno, or Bun
export default app;
 
// POST /agent/chat
// { "message": "Show me wireless headphones under $200" }

Multi-Agent App

hono-multi-agent.ts

import { Hono } from 'hono';
import { createMultiAgentApp } from '@orka-js/hono';
 
const app = new Hono();
 
const agents = {
  support: supportAgent,
  sales: salesAgent,
  docs: docsAgent,
};
 
const agentApp = createMultiAgentApp(agents, {
  streaming: true,
  basePath: '/api',
  cors: {
    origin: '*',
    credentials: true,
  },
});
 
app.route('/', agentApp);
 
export default app;
 
// POST /api/support/chat
// POST /api/sales/chat
// POST /api/docs/chat

Streaming Support

streaming.ts

// ─── Express SSE Streaming ────────────────────────────────────────────────────
import { createAgentMiddleware } from '@orka-js/express';
 
app.use('/api/agent', createAgentMiddleware(agent, {
  streaming: true, // Enable Server-Sent Events
}));
 
// Client-side (browser)
const eventSource = new EventSource('/api/agent/chat', {
  method: 'POST',
  body: JSON.stringify({ message: 'Hello' }),
});
 
eventSource.addEventListener('token', (e) => {
  const data = JSON.parse(e.data);
  process.stdout.write(data.token);
});
 
eventSource.addEventListener('done', (e) => {
  const data = JSON.parse(e.data);
  console.log('\nFinal:', data.content);
  eventSource.close();
});
 
// ─── Hono Streaming ───────────────────────────────────────────────────────────
import { createAgentApp } from '@orka-js/hono';
 
const agentApp = createAgentApp(agent, { streaming: true });
 
// Hono automatically handles SSE streaming for edge runtimes

Authentication & Authorization

auth.ts

// ─── Express Authentication ───────────────────────────────────────────────────
import { createAgentMiddleware } from '@orka-js/express';
 
app.use('/api/agent', createAgentMiddleware(agent, {
  authenticate: async (req) => {
    const token = req.headers.authorization?.replace('Bearer ', '');
    if (!token) throw new Error('Missing token');
 
    const user = await verifyJWT(token);
    return { userId: user.id, role: user.role };
  },
  authorize: (user, agentName) => {
    // Only admins can use the technical agent
    if (agentName === 'technical' && user.role !== 'admin') {
      throw new Error('Unauthorized');
    }
    return true;
  },
}));
 
// ─── Hono Authentication ──────────────────────────────────────────────────────
import { createAgentApp } from '@orka-js/hono';
import { jwt } from 'hono/jwt';
 
const agentApp = createAgentApp(agent);
 
// Add JWT middleware
agentApp.use('/*', jwt({ secret: process.env.JWT_SECRET! }));
 
agentApp.post('/chat', async (c) => {
  const user = c.get('jwtPayload');
  // user is available in context
});

Cloudflare Workers Deployment

cloudflare-worker.ts

// wrangler.toml
name = "orka-agent-api"
main = "src/index.ts"
compatibility_date = "2024-01-01"
 
[vars]
OPENAI_API_KEY = "sk-..."
 
// src/index.ts
import { Hono } from 'hono';
import { createAgentApp } from '@orka-js/hono';
import { StreamingToolAgent } from '@orka-js/agent';
import { OpenAIAdapter } from '@orka-js/openai';
 
const app = new Hono();
 
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! });
 
const agent = new StreamingToolAgent({
  goal: 'Customer support agent',
  tools: [],
}, llm);
 
const agentApp = createAgentApp(agent, { streaming: true });
app.route('/api', agentApp);
 
export default app;
 
// Deploy: npx wrangler deploy

When to Use Which?

Express: Traditional Node.js apps, existing Express codebases, need for extensive middleware
Hono: Edge deployments, Cloudflare Workers, Deno/Bun, need for ultra-low latency