@agentic-api

Comprehensive framework for intelligent agent orchestration, document processing, and enterprise workflow management. Inspired by OpenAI Swarm.

Design Philosophy: This project is optimized for specific enterprise problems rather than being a generic framework. It follows a minimalist approach with the OpenAI SDK as the only core dependency. It focuses on features that required too many dependencies with other frameworks like Vercel AI or LangChain.

Core Capabilities

Agent Orchestration

• Multi-agent conversations with automatic transfers and confidence-based escalation
• StateGraph Architecture: Modern conversation state management with automatic persistence
• Context Injection: Profile, instructions, and context-trail for coordination
• Multi-Provider LLM: Support for OpenAI and xAI providers

Document Processing

• MapLLM: Advanced map-reduce pattern for large document analysis
• Structured Outputs: OpenAI JSON schema validation support
• Flexible Loaders: File and string content processing with chunking strategies

RAG (Retrieval-Augmented Generation)

• Multi-RAG Architecture: Multiple indexes for different contexts (stable, draft, user emails, user projects)
• Incremental Fork: 80-90% performance gain by building RAG only on document diff (SHA-based)
• Reactive Updates: Auto-reload after modifications
• Semantic Search: Vector-based search with HNSW indexing

Testing & Validation

• Agent Simulator: Comprehensive testing framework with scenario-based simulations
• Built-in Personas: Authentic user behavior simulation (patient, rushed, frustrated)
• Tool Validation: Ensures tools are used correctly with equal, gte, lte constraints

Enterprise Workflow

A virtuous cycle for company procedures and guidelines: when a result is incorrect, users can correct it and create a validation request to the responsible person.

• Rules Management: Git-based workflow for business rules and procedures
• Pull Request Validation: Structured review and approval processes
• Stable IDs: Unique document identifiers that persist across branches and renames

Installation

npm install @agentic-api

Quick Start

Configuration .env

# LLM Provider (openai | xai)
LLM_PROVIDER=openai

# API Keys
OPENAI_API_KEY=sk-...    # Required for OpenAI + embeddings + whisper
XAI_API_KEY=xai-...      # Required if LLM_PROVIDER=xai

Basic Usage

import { llmInstance, executeAgentSet, AgenticContext } from '@agentic-api';

// Initialize LLM (uses LLM_PROVIDER from .env)
llmInstance();

// Create context with user information
const context: AgenticContext = {
  user: { id: "user123", role: "user" },
  credential: "msal-or-google-delegation-token"  // MSAL or Google delegation token
};

// Execute agent with StateGraph (automatically managed)
const stream = await executeAgentSet(agents, context, {
  query: "Hello, what can you do?",
  home: "welcome",
  verbose: true,
  enrichWithMemory: async (role, agent, context) => {
    // Injects user profile, global/session instructions, and history
    // See "Context Injection" section below for details
    return "";
  }
});

Model Levels

The framework supports multiple LLM providers with unified model levels:

| Level | OpenAI | xAI | Usage | |-------|--------|-----|-------| | LOW | gpt-5-nano | grok-4-fast-non-reasoning | Simple tasks, economical | | LOW-fast | gpt-5-nano | grok-code-fast-1 | Ultra fast | | MEDIUM | gpt-5-mini | grok-4-fast-reasoning | Balanced performance/cost | | HIGH | gpt-5.1 | grok-4 | Advanced reasoning | | SEARCH | gpt-5-mini + web_search | grok-4-fast-reasoning + web_search | Web search | | VISION | gpt-5-mini | grok-4 | Image analysis | | EMBEDDING-small | text-embedding-3-small | OpenAI only | Embeddings | | WHISPER | whisper-1 | OpenAI only | Audio transcription |

import { modelConfig, llmInstance } from '@agentic-api';

// Initialize with explicit configuration
// Note: provider could be a user preference instead of server-side config
const openai = llmInstance({ provider: 'openai', apiKey: process.env.OPENAI_API_KEY });
const xai = llmInstance({ provider: 'xai', apiKey: process.env.XAI_API_KEY });

// Get model config for specific provider
const config = modelConfig("MEDIUM", { provider: 'openai' });
const xaiConfig = modelConfig("HIGH", { provider: 'xai' });
const embedConfig = modelConfig("EMBEDDING-small", { provider: 'openai' });

Custom Agent Creation

import { AgentConfig, injectTransferTools } from '@agentic-api';

// Specialized agent
const haiku: AgentConfig = {
  name: "haiku",
  publicDescription: "Agent that writes haikus.",
  instructions: "Ask the user for a subject, then respond with a haiku.",
  model: 'LOW',  // String alias, converted at runtime
  tools: [],
  maxSteps: 3
};

// Router agent with transfers
const welcome: AgentConfig = {
  name: "welcome",
  publicDescription: "Agent that welcomes users.",
  instructions: "Welcome the user and route to appropriate specialist.",
  model: 'LOW',
  tools: [],
  downstreamAgents: [haiku]
};

// Inject transfer tools automatically
const agents = injectTransferTools([welcome, haiku]);

Agent Transfer System

The multi-agent transfer system enables specialized agents to collaborate:

┌─────────────────┐
│  Router Agent   │ ─── Qualifies and routes
└────────┬────────┘
         │
    ┌────┴────┬────────────┐
    ▼         ▼            ▼
┌────────┐ ┌────────┐ ┌────────┐
│  Info  │ │ Action │ │ Admin  │
└────────┘ └────────┘ └────────┘

Key Features:

• Confidence threshold (0.7) for transfer decisions
• Automatic context preservation via <context-trail>
• Specialized agent tracking for return after temporary transfers

// Transfer tool schema (auto-generated)
{
  rationale_for_transfer: string,  // Why this transfer
  conversation_context: string,    // Context for destination
  destination_agent: string,       // Target agent name
  confidence: number               // >= 0.7 required
}

Documentation: Agent Transfer

Context Injection

Architecture based on OpenAI best practices for profile and memory injection:

| Priority | Tag | Location | Description | |----------|-----|----------|-------------| | 2 (Required) | Agent instructions | System | Non-modifiable by user | | 1 (High) | <profile>, <instructions>, <context> | System/User | User context | | 0 (Low) | <history> | System | Informational only | | Auto | <context-trail> | System | Tool calls and transfers tracking |

import { renderContextInjection, renderUserContextInjection } from '@agentic-api';

// System message injection (profile + instructions)
const systemInjection = renderContextInjection(
  'date: 24/01/2026\nname: John',  // userProfile
  '- Prefers French',               // globalInstructions
  '- Budget max 50k',               // sessionInstructions
  'Previous discussion summary'     // history (optional)
);

// User message injection (attached assets)
const userMessage = renderUserContextInjection(assets) + userQuery;

StateGraph Memory Management

StateGraph manages conversation state across multiple discussions. It enables switching between agent discussions, serializing the state, and exporting a client-safe view:

import { AgentStateGraph, sessionStateGraphGet, sessionStateGraphSet } from '@agentic-api';

// Get or create StateGraph
let stateGraph = sessionStateGraphGet(req) || new AgentStateGraph();

// Create or restore discussion
const discussion = stateGraph.createOrRestore("welcome");

// Add messages
stateGraph.push("welcome", { role: "user", content: "Hello!" });

// Track token usage
stateGraph.updateTokens("welcome", {
  prompt: 10, completion: 20, total: 30, cost: 0.001
});

// Save with gzip compression
sessionStateGraphSet(req, stateGraph);

// Client-safe view (filters system messages and tools)
const clientView = stateGraph.toClientView("welcome");

Documentation: StateGraph

RAG System

Multi-RAG architecture with semantic search:

import { RAGManager } from '@agentic-api';

// Singleton pattern per baseDir
const ragManager = RAGManager.get({
  baseDir: './rag-data',
  maxArchives: 5
});

// Create RAG
await ragManager.create('procedures', { description: 'Validated procedures' });

// Incremental fork (80-90% performance gain)
await ragManager.create('procedures-v2', {
  fork: 'procedures',
  exclude: ['modified-1.md', 'modified-2.md']
});

// Build and search
await ragManager.build('procedures');
const embeddings = ragManager.load('procedures');

if (embeddings.isReady()) {
  const results = await embeddings.semanticSearch('How to validate budget?', {
    neighbors: 5
  });
}

Documentation: RAG Overview | RAG Manager

Agent Simulator

Testing framework with scenario-based simulations:

import { AgentSimulator, PERSONA_PATIENT } from '@agentic-api';

const simulator = new AgentSimulator({
  agents: [welcomeAgent, specialistAgent],
  start: "welcome",
  verbose: true
});

// Define scenario (context)
const scenario = {
  goals: "Verify agent handles requests correctly and transfers when needed.",
  persona: PERSONA_PATIENT
};

// Run test case
const result = await simulator.testCase(scenario, {
  query: "I need help with my heating issue",
  maxExchanges: 5,  // defaults to 1 (oneshot)
  expectedTools: { 'transferAgents': { gte: 1 } }
});

console.log('Success:', result.success);
console.log('Exchanges:', result.exchangeCount);
console.log('Messages:', result.messages.length);

Built-in Personas:

• PERSONA_PATIENT - Patient, polite user
• PERSONA_PRESSE - Rushed user wanting quick solutions
• PERSONA_ENERVE - Frustrated user, 3rd call for same problem

Documentation: Agent Simulator

MapLLM Document Processing

True map-reduce pattern for large documents with structured outputs and callback-driven accumulation:

import { MapLLM, FileNativeLoader, StringNativeLoader } from '@agentic-api';

// Chunking strategies: lines, pages, paragraphs, overlap
const loader = new FileNativeLoader('document.pdf', { type: 'pages', size: 1 });
const mapper = new MapLLM(loader);

const config = {
  digestPrompt: "Analyze this chunk and extract key points.",
  reducePrompt: "Merge this analysis with previous results.",
  reduceModulo: 5  // Optional: reduce every N chunks
};

// Callback controls accumulation and termination
const result = await mapper.reduce(config, (result, currentValue) => {
  // Structured output support
  result.format = { name: "analysis", schema: myJsonSchema, strict: true };
  result.acc = { ...result.acc, ...currentValue };
  
  // Stop conditions
  if (result.metadata.iterations > 20) result.maxIterations = true;
  return result;
}, { acc: {}, model: 'LOW', verbose: true });

Documentation: MapLLM

JobRunner (Plan → Execute → Reduce)

Sequential task execution engine for complex multi-objective requests:

import { JobRunner, jobPlannerPrompt } from '@agentic-api';

// JobRunner workflow:
// 1. Planner: userRequest → JobPlan (list of TaskSpec)
// 2. Executor: TaskSpec + memory → TaskResult
// 3. Reducer: (prevMemory, task, result) → ReducedJobMemory (via MapLLM)

// Features:
// - Strict contracts (structured outputs / schema validation)
// - Context reduction after each task via MapLLM reducer
// - Error policy: 2 attempts max per task, then thrown → synthesis
// - Sequential deterministic execution (V1)

Key Contracts:

• JobPlan: jobId, goal, tasks[]
• TaskSpec: id, title, type, dependsOn[], acceptance[]
• TaskResult: taskId, ok, summary, data, artifacts[], error
• ReducedJobMemory: memory (short canonical), index (stable refs)

Documentation: JobRunner

Rules Management System

Git-based workflow for business documents:

import { RulesWorkflow, gitLoad, RuleStatus } from '@agentic-api';

const workflow = new RulesWorkflow(gitLoad());

// Create rule with auto-generated ID
const rule = await workflow.createRule('procedures/budget.md', {
  title: 'Budget Validation Process',
  tags: ['finance', 'validation'],
  role: 'rule'
}, 'Initial content...');

// Create PR for validation
const prBranch = await workflow.createPullRequest(
  ['procedures/budget.md'],
  'New budget procedure'
);

// Search and filter
const results = await workflow.searchRules('budget', { tags: ['finance'] });
const drafts = await workflow.getRulesByStatus(RuleStatus.EDITING);

Branch-Based Status: | Branch | Status | |--------|--------| | main | PUBLISHED | | rule-editor | EDITING | | rule-validation-* | PULLREQUEST |

Documentation: Rules Overview

Documentation

Complete documentation available in ./docs/:

• Agent Configuration
• Agent Transfer
• StateGraph
• RAG Overview
• Rules Overview
• Troubleshooting

Testing

npm test

License

MIT License - Copyright (c) 2024-2026 [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.