SuperCharged-Claude-Code-Upgrade/dexto/docs/api/sdk/agent-factory.md

sidebar_position

sidebar_position
7

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>

Parameter	Type	Description
config	AgentConfig	Agent configuration object
options.agentId	string	(Optional) Override agent ID (affects log/storage paths)
options.isInteractiveCli	boolean	(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>

Parameter	Type	Description
agentId	string	Agent ID from bundled registry
options.agentsDir	string	(Optional) Custom agents directory

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

What Happens During Installation

1. Agent files are copied from bundled location to ~/.dexto/agents/{agentId}/
2. Agent is added to the user's registry (~/.dexto/agents/registry.json)
3. User preferences are applied at runtime for the bundled coding-agent only

---

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>

Parameter	Type	Description
agentId	string	Unique ID for the custom agent
sourcePath	string	Absolute path to agent YAML file or directory
metadata.name	string	(Optional) Display name (defaults to agentId)
metadata.description	string	Description of what the agent does
metadata.author	string	Creator of the agent
metadata.tags	string[]	Categorization tags
options.agentsDir	string	(Optional) Custom agents directory

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>

Parameter	Type	Description
agentId	string	Agent 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;
}

---

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

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

---

See Also

• AgentManager API - Registry-based agent lifecycle management
• Config Utilities - Lower-level config loading functions
• Agent Orchestration Tutorial - Step-by-step guide