@fractary/forge

Core SDK for AI Agent & Tool Management

@fractary/forge is a comprehensive TypeScript SDK for managing, resolving, and distributing AI agents, tools, and workflows. It provides a flexible resolution system with local, global, and remote registry support.

✨ Features

• 3-Tier Resolution: Local → Global → Remote registries
• Plugin System: Install and distribute agent/tool collections
• Version Management: Semver-based version constraints
• Cache System: TTL-based caching for performance
• Type-Safe: Full TypeScript support with Zod validation
• Export Support: Export to LangChain, Claude Code, n8n
• Fork Workflows: Fork and customize components with upstream merging

📦 Installation

npm install @fractary/forge

Requirements:

• Node.js >= 18.0.0
• TypeScript >= 5.3 (for TypeScript projects)

🚀 Quick Start

Basic Usage

import { ForgeClient } from '@fractary/forge';

// Initialize client
const client = new ForgeClient();

// List available agents
const agents = await client.agents.list();
console.log('Available agents:', agents);

// Get specific agent
const agent = await client.agents.get('my-agent');
console.log('Agent:', agent);

// Install plugin
await client.plugins.install('@fractary/faber-plugin', {
  global: true
});

With Configuration

import { ForgeClient } from '@fractary/forge';

const client = new ForgeClient({
  resolvers: {
    local: {
      enabled: true,
      paths: ['.fractary/agents', '.fractary/tools']
    },
    global: {
      enabled: true,
      path: '~/.fractary/registry'
    },
    remote: {
      enabled: true,
      registries: [
        {
          name: 'fractary-core',
          type: 'manifest',
          url: 'https://raw.githubusercontent.com/fractary/plugins/main/registry.json',
          priority: 1
        }
      ]
    }
  },
  cache: {
    enabled: true,
    ttl: 3600
  }
});

📚 Core API

Agents

// List agents
const agents = await client.agents.list({ source: 'local' });

// Get agent with dependencies
const agent = await client.agents.get('my-agent', {
  includeTools: true
});

// Create agent
await client.agents.create({
  name: 'my-agent',
  version: '1.0.0',
  llm: {
    provider: 'anthropic',
    model: 'claude-3-5-sonnet-20241022',
    temperature: 0.7
  },
  systemPrompt: 'You are a helpful assistant.',
  tools: ['web-search']
});

// Validate agent
const validation = await client.agents.validate('my-agent');

Tools

// List tools
const tools = await client.tools.list();

// Get tool
const tool = await client.tools.get('web-search');

// Create tool
await client.tools.create({
  name: 'my-tool',
  version: '1.0.0',
  description: 'Custom tool',
  parameters: {
    type: 'object',
    properties: {
      query: { type: 'string' }
    }
  },
  implementation: {
    type: 'function',
    handler: './handlers/my-tool.js'
  }
});

Plugins

// Search plugins
const results = await client.plugins.search('faber');

// Install plugin
await client.plugins.install('@fractary/faber-plugin', {
  global: true
});

// List installed
const plugins = await client.plugins.list();

// Uninstall
await client.plugins.uninstall('@fractary/faber-plugin');

Cache

// Get stats
const stats = await client.cache.getStats();

// Clear cache
await client.cache.clear();

// Clear with pattern
await client.cache.clear({ pattern: '@fractary/*' });

🔧 Advanced Features

Custom Resolvers

import { Resolver, ResolvedAsset } from '@fractary/forge';

class CustomResolver implements Resolver {
  name = 'custom';

  async resolve(
    name: string,
    type: 'agent' | 'tool',
    version?: string
  ): Promise<ResolvedAsset | null> {
    // Custom resolution logic
    return null;
  }
}

const client = new ForgeClient({
  customResolvers: [new CustomResolver()]
});

Error Handling

import {
  AssetNotFoundError,
  ValidationError,
  ResolutionError
} from '@fractary/forge';

try {
  const agent = await client.agents.get('my-agent');
} catch (error) {
  if (error instanceof AssetNotFoundError) {
    console.error('Agent not found');
  } else if (error instanceof ValidationError) {
    console.error('Validation failed:', error.errors);
  }
}

TypeScript Support

import type {
  Agent,
  Tool,
  AgentDefinition,
  ToolDefinition
} from '@fractary/forge';

const agentDef: AgentDefinition = {
  name: 'my-agent',
  version: '1.0.0',
  llm: {
    provider: 'anthropic',
    model: 'claude-3-5-sonnet-20241022'
  },
  systemPrompt: 'You are helpful.'
};

📖 Documentation

• Complete Documentation - Full documentation index
• SDK Guide - Detailed SDK usage guide
• API Reference - Complete API documentation
• Examples - Usage examples
• Architecture - System design

🏗️ Architecture

ForgeClient
├── Agents API
├── Tools API
├── Plugins API
└── Cache API
      │
      ▼
Resolution Manager
├── Local Resolver (.fractary/)
├── Global Resolver (~/.fractary/registry/)
└── Remote Resolver (registries)

🛠️ Development

# Clone repository
git clone https://github.com/fractary/forge.git
cd forge/sdk/js

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Watch mode
npm run dev

See Developer Guide for contribution guidelines.

📄 License

MIT © Fractary

🔗 Links

• GitHub - Source code
• NPM - Package registry
• Documentation - Full documentation
• CLI Tool - Command-line interface
• MCP Server - Model Context Protocol server
• Issues - Bug reports

🤝 Related Packages

• @fractary/forge-cli - Command-line interface
• @fractary/forge-mcp - MCP server for Claude Desktop

Made with ❤️ by the Fractary team