@transquinnftw/ml-agent-loader

Reusable TypeScript package for loading YAML-based agent definitions.

Features

• Load agent configurations from YAML files
• Parse system prompts with YAML frontmatter
• Support mission context presets
• Type-safe agent definitions
• Configurable agents directory
• Built-in caching and reload support

Installation

npm install @transquinnftw/ml-agent-loader

Usage

Basic Usage

import { AgentLoader } from '@transquinnftw/ml-agent-loader';
import * as path from 'path';
import * as os from 'os';

// Create loader with custom directory
const agentsDir = path.join(os.homedir(), '.local/@transquinnftw/my-app/agents');
const loader = new AgentLoader(agentsDir);

// Discover and load all agents
const agents = loader.discoverAgents();
console.log(`Loaded ${agents.length} agents`);

// Get a specific agent
const agent = loader.getAgent('my-agent-id');
if (agent) {
  console.log(`Agent: ${agent.displayName}`);
  console.log(`System prompt: ${agent.systemPrompt.substring(0, 100)}...`);
}

// Get system prompt with mission context injected
const promptWithMission = loader.getSystemPrompt('my-agent-id', 'research');

Agent Directory Structure

Each agent should be structured as:

{agentsDir}/{agentId}/
├── agent.yaml              # Core configuration
├── system-prompt.md        # System prompt with YAML frontmatter
└── missions/
    ├── research.md         # Mission context preset
    └── creative.md         # Another mission preset

agent.yaml Example

id: my-agent
name: my-agent
displayName: My Agent
color: '#3b82f6'
specialties:
  - research
  - analysis

provider:
  type: llamacpp
  modelSelection: auto

personality:
  systemPromptFile: system-prompt.md
  missionPresets:
    research: missions/research.md
    creative: missions/creative.md
  defaultMission: research

knowledge:
  enabled: false
  nodeId: ''
  contextTypes: []

modelSettings:
  temperature: 0.7
  maxTokens: 4096

system-prompt.md Example

---
author: transquinnftw
version: 1.0.0
updated: 2025-12-28
character: my-agent
missionContextMarker: '## Current Mission Context'
---

# My Agent

You are a helpful AI assistant.

## Current Mission Context

[Mission context will be injected here]

## Capabilities

- Research and analysis
- Creative problem solving

API Reference

AgentLoader

Constructor

new AgentLoader(agentsDir: string)

Methods

• getAgentsDir(): string - Get the agents directory path
• agentsDirExists(): boolean - Check if agents directory exists
• discoverAgentIds(): string[] - Discover all agent IDs
• loadAgent(agentId: string): LoadedAgent - Load a single agent
• discoverAgents(): LoadedAgent[] - Discover and load all agents
• getAgent(agentId: string): LoadedAgent | undefined - Get cached agent
• getAllAgents(): LoadedAgent[] - Get all cached agents
• getSystemPrompt(agentId: string, mission?: string): string - Get system prompt with mission context
• reloadAgent(agentId: string): LoadedAgent - Reload a specific agent
• reloadAll(): LoadedAgent[] - Reload all agents
• isInitialized(): boolean - Check if loader is initialized

Types

• AgentDefinition - Agent configuration structure
• LoadedAgent - Agent with resolved content
• SystemPromptFrontmatter - Frontmatter metadata
• AgentProviderConfig - ML provider configuration
• AgentKnowledgeConfig - Knowledge/Redis configuration
• AgentPersonalityConfig - Personality configuration
• ModelSettings - Model inference settings

Errors

• AgentLoadError - Thrown when agent loading fails
• KnowledgeConnectionError - Thrown when Redis connection fails

License

MIT