OrkaJS
Orka.JS

Agent Platform

Build, deploy and manage your AI agent workforce like microservices.Agent Identity, Registry, and Discovery forenterprise-scale AI systems.

OrkaJS Agent Platform transforms agents from simple tools into first-class citizens of your AI infrastructure. Each agent has a unique identity, metadata, and can be discovered, shared, and managed across your organization.

Agent Identity

Every agent has id, name, role, version, and rich metadata

Central Registry

Register, discover, and manage agents across your organization

Advanced Discovery

Query agents by tags, capabilities, role, or search text

Rich Metadata

Tags, capabilities, dependencies, author, license, and custom fields

Version Management

Semantic versioning with creation and update timestamps

Import/Export

Backup, migrate, and share agent configurations as JSON

# Quick Start

Register your first agent with identity and metadata:

import { globalAgentRegistry, ReActAgent } from '@orka-js/agent';
import { OpenAIAdapter } from '@orka-js/openai';
 
// Create an agent
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY });
const agent = new ReActAgent({
goal: 'Qualify leads and schedule follow-ups',
tools: [emailTool, calendarTool, crmTool],
}, llm);
 
// Register with identity
await globalAgentRegistry.register(
{
id: 'sales-assistant-v1',
name: 'Sales Assistant',
role: 'CRM automation',
description: 'Handles lead qualification and follow-ups',
version: '1.0.0',
metadata: {
tags: ['sales', 'crm', 'automation'],
capabilities: ['email', 'calendar', 'database'],
author: 'YourCompany',
license: 'MIT'
}
},
agent.config,
'react'
);
 
// Discover agents
const salesAgents = globalAgentRegistry.query({ tags: ['sales'] });
console.log(`Found ${salesAgents.length} sales agents`);

# Agent Identity

Every agent in OrkaJS has a unique identity with rich metadata. This makes agents discoverable, reusable, and manageable at scale.

Identity Fields

id: string

Unique identifier (e.g., 'sales-assistant-v1')

name: string

Human-readable name (e.g., 'Sales Assistant')

role: string

Agent's purpose (e.g., 'CRM automation')

description: string

Detailed description of what the agent does

version: string

Semantic version (e.g., '1.0.0', '2.1.3-beta')

metadata: AgentMetadata

Rich metadata for discovery and filtering

# Agent Metadata

Metadata provides rich information for agent discovery, categorization, and management.

const metadata = {
// Tags for categorization
tags: ['sales', 'crm', 'automation', 'lead-qualification'],
 
// Agent capabilities
capabilities: ['email', 'calendar', 'database', 'reporting'],
 
// Dependencies on other agents or services
dependencies: ['email-service', 'crm-database'],
 
// Author information
author: 'YourCompany',
 
// License
license: 'MIT',
 
// Custom fields
custom: {
department: 'Sales',
costCenter: 'SALES-001',
supportEmail: 'support@company.com'
}
};

# Agent Registry

The Agent Registry is a central repository for managing all your agents. It provides registration, discovery, versioning, and lifecycle management.

Register an Agent

import { AgentRegistry } from '@orka-js/agent';
 
const registry = new AgentRegistry();
 
// Register an agent
const registered = await registry.register(
{
id: 'support-bot-v1',
name: 'Support Bot',
role: 'Customer support',
description: 'Handles tier-1 support tickets and escalations',
version: '1.0.0',
metadata: {
tags: ['support', 'customer-service', 'tickets'],
capabilities: ['chat', 'ticketing', 'knowledge-base'],
author: 'Support Team',
license: 'proprietary'
}
},
agentConfig,
'react'
);
 
console.log(`Registered agent: ${registered.identity.name}`);

Query Agents

Find agents using powerful filtering options:

// Find all sales agents
const salesAgents = registry.query({ tags: ['sales'] });
 
// Find agents with email capability
const emailAgents = registry.query({ capabilities: ['email'] });
 
// Find agents by role
const supportAgents = registry.query({ role: 'support' });
 
// Search in name and description
const automationAgents = registry.query({ search: 'automation' });
 
// Combine multiple filters
const results = registry.query({
tags: ['sales'],
capabilities: ['email', 'calendar'],
author: 'YourCompany',
limit: 10
});
 
// Get specific agent
const agent = registry.get('sales-assistant-v1');
if (agent) {
console.log(`Found: ${agent.identity.name} v${agent.identity.version}`);
}

Update an Agent

// Update agent identity
await registry.update('sales-assistant-v1', {
identity: {
version: '1.1.0',
description: 'Enhanced with AI-powered lead scoring'
}
});
 
// Update agent configuration
await registry.update('sales-assistant-v1', {
config: {
maxSteps: 10,
temperature: 0.7
}
});

Delete an Agent

// Delete an agent
const deleted = registry.delete('old-agent-v1');
if (deleted) {
console.log('Agent deleted successfully');
}
 
// Check if agent exists
if (registry.has('sales-assistant-v1')) {
console.log('Agent exists');
}

# Registry Statistics

Get insights about your agent ecosystem:

const stats = registry.getStats();
 
console.log(`Total agents: ${stats.totalAgents}`);
console.log('Agents by type:', stats.agentsByType);
console.log('Popular tags:', stats.popularTags);
console.log('Popular capabilities:', stats.popularCapabilities);
 
// Example output:
// Total agents: 15
// Agents by type: { react: 8, 'plan-and-execute': 5, 'openai-functions': 2 }
// Popular tags: [
// { tag: 'sales', count: 6 },
// { tag: 'support', count: 4 },
// { tag: 'automation', count: 8 }
// ]

# Import & Export

Backup, migrate, or share agent configurations:

// Export all agents as JSON
const json = registry.export();
await fs.writeFile('agents-backup.json', json);
 
// Import agents from JSON
const json = await fs.readFile('agents-backup.json', 'utf-8');
const imported = registry.import(json);
console.log(`Imported ${imported} agents`);
 
// Import with overwrite
const imported = registry.import(json, true); // Overwrites existing agents

# Global Registry

Use the global registry for application-wide agent management:

import { globalAgentRegistry } from '@orka-js/agent';
 
// Register agents globally
await globalAgentRegistry.register(identity, config, type);
 
// Access from anywhere in your application
const agents = globalAgentRegistry.query({ tags: ['production'] });
 
// Clear all agents (useful for testing)
globalAgentRegistry.clear();

# Real-World Example: Sales Team

Build a complete sales automation system with multiple specialized agents:

import { globalAgentRegistry, ReActAgent } from '@orka-js/agent';
import { OpenAIAdapter } from '@orka-js/openai';
 
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY });
 
// 1. Lead Qualification Agent
const leadAgent = new ReActAgent({
goal: 'Qualify incoming leads based on BANT criteria',
tools: [crmTool, emailTool]
}, llm);
 
await globalAgentRegistry.register(
{
id: 'lead-qualifier-v1',
name: 'Lead Qualifier',
role: 'Lead qualification',
description: 'Qualifies leads using BANT framework',
version: '1.0.0',
metadata: {
tags: ['sales', 'lead-gen', 'qualification'],
capabilities: ['crm', 'email', 'scoring'],
author: 'Sales Team'
}
},
leadAgent.config,
'react'
);
 
// 2. Follow-up Agent
const followUpAgent = new ReActAgent({
goal: 'Schedule and manage follow-up communications',
tools: [calendarTool, emailTool]
}, llm);
 
await globalAgentRegistry.register(
{
id: 'follow-up-v1',
name: 'Follow-up Manager',
role: 'Follow-up automation',
description: 'Manages follow-up schedule and communications',
version: '1.0.0',
metadata: {
tags: ['sales', 'follow-up', 'scheduling'],
capabilities: ['calendar', 'email', 'reminders'],
dependencies: ['lead-qualifier-v1']
}
},
followUpAgent.config,
'react'
);
 
// 3. Proposal Generator
const proposalAgent = new ReActAgent({
goal: 'Generate customized sales proposals',
tools: [crmTool, documentTool]
}, llm);
 
await globalAgentRegistry.register(
{
id: 'proposal-gen-v1',
name: 'Proposal Generator',
role: 'Proposal creation',
description: 'Creates customized proposals based on lead data',
version: '1.0.0',
metadata: {
tags: ['sales', 'proposals', 'documents'],
capabilities: ['document-generation', 'crm', 'templates'],
dependencies: ['lead-qualifier-v1']
}
},
proposalAgent.config,
'react'
);
 
// Discover all sales agents
const salesTeam = globalAgentRegistry.query({ tags: ['sales'] });
console.log(`Sales team has ${salesTeam.length} agents`);
 
// Find agents that depend on lead qualifier
const dependentAgents = globalAgentRegistry.list().filter(agent =>
agent.identity.metadata.dependencies?.includes('lead-qualifier-v1')
);
console.log(`${dependentAgents.length} agents depend on lead qualifier`);

# Best Practices

Use Semantic Versioning

Follow semver (1.0.0, 1.1.0, 2.0.0) for agent versions to track breaking changes

Descriptive IDs

Use descriptive IDs like 'sales-assistant-v1' instead of generic 'agent-1'

Rich Metadata

Add comprehensive tags and capabilities for better discoverability

Document Dependencies

Track agent dependencies to understand your agent ecosystem

Regular Backups

Export your registry regularly for backup and disaster recovery

Use Global Registry

Use globalAgentRegistry for application-wide agent management

# TypeScript Types

// Agent Identity
interface AgentIdentity {
id: string;
name: string;
role: string;
description: string;
version: string;
createdAt: Date;
updatedAt: Date;
metadata: AgentMetadata;
}
 
// Agent Metadata
interface AgentMetadata {
tags: string[];
capabilities: string[];
dependencies?: string[];
author?: string;
license?: string;
custom?: Record<string, unknown>;
}
 
// Registered Agent
interface RegisteredAgent {
identity: AgentIdentity;
config: AgentConfig;
type: 'react' | 'plan-and-execute' | 'openai-functions' | 'structured-chat' | 'custom';
instance?: unknown;
}
 
// Query Options
interface AgentQueryOptions {
tags?: string[];
capabilities?: string[];
role?: string;
author?: string;
search?: string;
limit?: number;
}

🚀 What's Next?

Agent Platform is the foundation for building enterprise-scale AI systems. Coming soon:

  • Permissions & Access Control (RBAC)
  • Multi-Agent Collaboration & Orchestration
  • Agent Deployment (Slack, API, Webhooks)
  • Agent Marketplace & Templates