@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

``bash
npm install @fractary/forge
`

Requirements:
- Node.js >= 18.0.0
- TypeScript >= 5.3 (for TypeScript projects)

🚀 Quick Start

$3

`typescript
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
});
`

$3

`typescript
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

$3

`typescript
// 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');
`

$3

`typescript
// 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'
}
});
`

$3

`typescript
// 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');
`

$3

`typescript
// 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

$3

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

class CustomResolver implements Resolver {
name = 'custom';

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

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

$3

`typescript
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);
}
}
`

$3

`typescript
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

`bash

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