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 agentconst 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 identityawait 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 agentsconst 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: stringUnique identifier (e.g., 'sales-assistant-v1')
name: stringHuman-readable name (e.g., 'Sales Assistant')
role: stringAgent's purpose (e.g., 'CRM automation')
description: stringDetailed description of what the agent does
version: stringSemantic version (e.g., '1.0.0', '2.1.3-beta')
metadata: AgentMetadataRich 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 agentconst 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 agentsconst salesAgents = registry.query({ tags: ['sales'] }); // Find agents with email capabilityconst emailAgents = registry.query({ capabilities: ['email'] }); // Find agents by roleconst supportAgents = registry.query({ role: 'support' }); // Search in name and descriptionconst automationAgents = registry.query({ search: 'automation' }); // Combine multiple filtersconst results = registry.query({ tags: ['sales'], capabilities: ['email', 'calendar'], author: 'YourCompany', limit: 10}); // Get specific agentconst agent = registry.get('sales-assistant-v1');if (agent) { console.log(`Found: ${agent.identity.name} v${agent.identity.version}`);}Update an Agent
// Update agent identityawait registry.update('sales-assistant-v1', { identity: { version: '1.1.0', description: 'Enhanced with AI-powered lead scoring' }}); // Update agent configurationawait registry.update('sales-assistant-v1', { config: { maxSteps: 10, temperature: 0.7 }});Delete an Agent
// Delete an agentconst deleted = registry.delete('old-agent-v1');if (deleted) { console.log('Agent deleted successfully');} // Check if agent existsif (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 JSONconst json = registry.export();await fs.writeFile('agents-backup.json', json); // Import agents from JSONconst json = await fs.readFile('agents-backup.json', 'utf-8');const imported = registry.import(json);console.log(`Imported ${imported} agents`); // Import with overwriteconst 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 globallyawait globalAgentRegistry.register(identity, config, type); // Access from anywhere in your applicationconst 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 Agentconst 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 Agentconst 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 Generatorconst 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 agentsconst salesTeam = globalAgentRegistry.query({ tags: ['sales'] });console.log(`Sales team has ${salesTeam.length} agents`); // Find agents that depend on lead qualifierconst 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 Identityinterface AgentIdentity { id: string; name: string; role: string; description: string; version: string; createdAt: Date; updatedAt: Date; metadata: AgentMetadata;} // Agent Metadatainterface AgentMetadata { tags: string[]; capabilities: string[]; dependencies?: string[]; author?: string; license?: string; custom?: Record<string, unknown>;} // Registered Agentinterface RegisteredAgent { identity: AgentIdentity; config: AgentConfig; type: 'react' | 'plan-and-execute' | 'openai-functions' | 'structured-chat' | 'custom'; instance?: unknown;} // Query Optionsinterface 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