Skip to main content

AgentFactory API

The AgentFactory namespace provides static methods for agent creation, installation, and management. Use these functions to create agents from inline configs, install agents from the bundled registry, install custom agents, and manage installed agents.

import { AgentFactory } from '@dexto/agent-management';

createAgent​

Creates a DextoAgent from an inline configuration object. Use this when you have a config from a database, API, or constructed programmatically and don't need a registry file.

async function AgentFactory.createAgent(
  config: AgentConfig,
  options?: CreateAgentOptions
): Promise<DextoAgent>
ParameterTypeDescription
configAgentConfigAgent configuration object
options.agentIdstring(Optional) Override agent ID (affects log/storage paths)
options.isInteractiveCliboolean(Optional) If true, disables console logging

Returns: Promise<DextoAgent> - Agent instance (not started)

Example:

import { AgentFactory } from '@dexto/agent-management';

// Create from inline config
const agent = await AgentFactory.createAgent({
  llm: {
    provider: 'openai',
    model: 'gpt-4o',
    apiKey: process.env.OPENAI_API_KEY
  },
  systemPrompt: 'You are a helpful assistant.'
});
await agent.start();

// With custom agent ID (affects log/storage paths)
const agent = await AgentFactory.createAgent(config, { agentId: 'my-custom-agent' });

// From database
const configFromDb = await db.getAgentConfig(userId);
const agent = await AgentFactory.createAgent(configFromDb, { agentId: `user-${userId}` });
await agent.start();

listAgents​

Lists all installed and available agents from the bundled registry.

async function AgentFactory.listAgents(): Promise<{
  installed: AgentInfo[];
  available: AgentInfo[];
}>

Returns: Object with installed and available agent arrays

interface AgentInfo {
  id: string;          // Unique identifier
  name: string;        // Display name
  description: string; // What the agent does
  author: string;      // Creator
  tags: string[];      // Categorization tags
  type: 'builtin' | 'custom';
}

Example:

import { AgentFactory } from '@dexto/agent-management';

const { installed, available } = await AgentFactory.listAgents();

console.log('Installed agents:');
installed.forEach(agent => {
  console.log(`  - ${agent.name} (${agent.id})`);
});

console.log('\nAvailable to install:');
available.forEach(agent => {
  console.log(`  - ${agent.name}: ${agent.description}`);
});

installAgent​

Installs an agent from the bundled registry to the local agents directory (~/.dexto/agents/).

async function AgentFactory.installAgent(
  agentId: string,
  options?: InstallOptions
): Promise<string>
ParameterTypeDescription
agentIdstringAgent ID from bundled registry
options.agentsDirstring(Optional) Custom agents directory
options.injectPreferencesboolean(Optional) Inject global preferences (default: true)

Returns: Promise<string> - Path to installed agent's main config file

Throws: DextoRuntimeError if agent not found or installation fails

Example:

import { AgentFactory } from '@dexto/agent-management';

// Install a bundled agent
const configPath = await AgentFactory.installAgent('coding-agent');
console.log(`Installed to: ${configPath}`);

// Install without injecting preferences
const configPath = await AgentFactory.installAgent('research-agent', {
  injectPreferences: false
});

What Happens During Installation​

  1. Agent files are copied from bundled location to ~/.dexto/agents/{agentId}/
  2. Global user preferences (LLM provider, API keys) are injected into the config
  3. Agent is added to the user's registry (~/.dexto/agents/registry.json)

installCustomAgent​

Installs a custom agent from a local file or directory path.

async function AgentFactory.installCustomAgent(
  agentId: string,
  sourcePath: string,
  metadata: {
    name?: string;
    description: string;
    author: string;
    tags: string[];
  },
  options?: InstallOptions
): Promise<string>
ParameterTypeDescription
agentIdstringUnique ID for the custom agent
sourcePathstringAbsolute path to agent YAML file or directory
metadata.namestring(Optional) Display name (defaults to agentId)
metadata.descriptionstringDescription of what the agent does
metadata.authorstringCreator of the agent
metadata.tagsstring[]Categorization tags
options.injectPreferencesboolean(Optional) Inject global preferences (default: true)

Returns: Promise<string> - Path to installed agent's main config file

Throws:

  • DextoRuntimeError if agent ID conflicts with bundled agent
  • DextoRuntimeError if agent ID already exists
  • DextoRuntimeError if source path doesn't exist

Example:

import { AgentFactory } from '@dexto/agent-management';

// Install from a single YAML file
const configPath = await AgentFactory.installCustomAgent(
  'my-support-agent',
  '/path/to/support-agent.yml',
  {
    description: 'Custom support agent for our product',
    author: 'My Team',
    tags: ['support', 'custom']
  }
);

// Install from a directory (for agents with multiple files)
const configPath = await AgentFactory.installCustomAgent(
  'my-complex-agent',
  '/path/to/agent-directory/',
  {
    name: 'Complex Agent',
    description: 'Agent with knowledge files and multiple configs',
    author: 'My Team',
    tags: ['complex', 'custom']
  }
);

Directory Structure for Multi-File Agents​

When installing from a directory:

my-agent/
├── agent.yml           # Main config (required, or specify custom name)
├── knowledge/
│   ├── docs.md
│   └── faq.md
└── prompts/
    └── system.txt

uninstallAgent​

Removes an installed agent from disk and the user registry.

async function AgentFactory.uninstallAgent(agentId: string): Promise<void>
ParameterTypeDescription
agentIdstringAgent ID to uninstall

Throws: DextoRuntimeError if agent is not installed

Example:

import { AgentFactory } from '@dexto/agent-management';

// Uninstall an agent
await AgentFactory.uninstallAgent('my-custom-agent');
console.log('Agent uninstalled');

What Happens During Uninstallation​

  1. Agent directory is removed from ~/.dexto/agents/{agentId}/
  2. Agent entry is removed from user registry (~/.dexto/agents/registry.json)
caution

Uninstallation is permanent. All agent files including conversation history (if stored locally) will be deleted.

InstallOptions​

Options for installation functions:

interface InstallOptions {
  /** Directory where agents are stored (default: ~/.dexto/agents) */
  agentsDir?: string;

  /** Whether to inject global preferences into agent config (default: true) */
  injectPreferences?: boolean;
}

Complete Example​

import { AgentFactory } from '@dexto/agent-management';
import { AgentManager } from '@dexto/agent-management';

async function setupAgents() {
  // List what's available
  const { installed, available } = await AgentFactory.listAgents();
  console.log(`${installed.length} installed, ${available.length} available`);

  // Install a bundled agent if not already installed
  if (!installed.some(a => a.id === 'coding-agent')) {
    await AgentFactory.installAgent('coding-agent');
    console.log('Installed coding-agent');
  }

  // Install a custom agent
  await AgentFactory.installCustomAgent(
    'team-agent',
    './my-agents/team-agent.yml',
    {
      description: 'Our team\'s custom agent',
      author: 'Engineering Team',
      tags: ['internal', 'custom']
    }
  );

  // Now use AgentManager to work with installed agents
  const manager = new AgentManager('~/.dexto/agents/registry.json');
  await manager.loadRegistry();

  const agent = await manager.loadAgent('team-agent');
  await agent.start();

  // ... use the agent ...

  await agent.stop();
}

File Locations​

ResourcePath
Agents directory~/.dexto/agents/
User registry~/.dexto/agents/registry.json
Per-agent configs~/.dexto/agents/{agentId}/
Bundled registryBundled with @dexto/agent-management package

See Also​