Core SDK for Forge asset management with multi-resolver architecture
npm install @fractary/forge@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.
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
``