Skip to main content

AgentManager API

The AgentManager class provides registry-based agent lifecycle management. It loads agent configurations from a registry file and creates agent instances programmatically.

import { AgentManager } from '@dexto/agent-management';
When to use AgentManager

AgentManager - Registry-based. Use when you have a registry.json with multiple predefined agents.

Constructor​

constructor​

Creates a new AgentManager instance pointing to a registry file.

constructor(registryPath: string)
ParameterTypeDescription
registryPathstringPath to registry.json file (absolute or relative)

Example:

// Project-local registry
const manager = new AgentManager('./agents/registry.json');

// Absolute path
const manager = new AgentManager('/path/to/registry.json');

Methods​

loadRegistry​

Loads the registry from file. Must be called before using sync methods like listAgents() or hasAgent().

async loadRegistry(): Promise<Registry>

Returns: Promise<Registry> - The loaded registry object

Example:

const manager = new AgentManager('./registry.json');
await manager.loadRegistry();

// Now sync methods work
const agents = manager.listAgents();
note

loadAgent() automatically calls loadRegistry() if not already loaded.

listAgents​

Returns metadata for all agents in the registry.

listAgents(): AgentMetadata[]

Returns: AgentMetadata[] - Array of agent metadata objects

interface AgentMetadata {
  id: string;          // Unique identifier
  name: string;        // Display name
  description: string; // What the agent does
  author?: string;     // Creator
  tags?: string[];     // Categorization tags
}

Example:

const manager = new AgentManager('./registry.json');
await manager.loadRegistry();

const agents = manager.listAgents();
console.log(agents);
// [
//   { id: 'coding-agent', name: 'Coding Assistant', description: '...', tags: ['coding'] },
//   { id: 'support-agent', name: 'Support Assistant', description: '...', tags: ['support'] }
// ]

// Filter by tag
const codingAgents = agents.filter(a => a.tags?.includes('coding'));

hasAgent​

Checks if an agent exists in the registry.

hasAgent(id: string): boolean
ParameterTypeDescription
idstringAgent ID to check

Returns: boolean - True if agent exists

Example:

const manager = new AgentManager('./registry.json');
await manager.loadRegistry();

if (manager.hasAgent('coding-agent')) {
  const agent = await manager.loadAgent('coding-agent');
}

loadAgent​

Loads a DextoAgent instance from the registry. Loads the agent's YAML config, enriches it with runtime paths, and returns an unstarted agent.

async loadAgent(id: string): Promise<DextoAgent>
ParameterTypeDescription
idstringAgent ID from registry

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

Throws:

  • DextoRuntimeError if agent not found or config loading fails
  • DextoValidationError if agent config validation fails

Example:

const manager = new AgentManager('./registry.json');
const agent = await manager.loadAgent('coding-agent');
await agent.start();

// Use the agent
const session = await agent.createSession();
const response = await agent.generate('Write a function to reverse a string', session.id);

console.log(response.content);
await agent.stop();

Registry Format​

The registry file is a JSON file that describes available agents:

{
  "agents": [
    {
      "id": "coding-agent",
      "name": "Coding Assistant",
      "description": "Expert coding assistant for development tasks",
      "configPath": "./coding-agent.yml",
      "author": "Your Team",
      "tags": ["coding", "development"]
    },
    {
      "id": "support-agent",
      "name": "Support Assistant",
      "description": "Friendly customer support agent",
      "configPath": "./support-agent.yml",
      "tags": ["support", "customer-service"]
    }
  ]
}
FieldTypeRequiredDescription
idstringYesUnique identifier (used in loadAgent())
namestringYesHuman-readable display name
descriptionstringYesWhat this agent does
configPathstringYesPath to YAML config (relative to registry.json)
authorstringNoCreator of the agent
tagsstring[]NoCategorization tags

Complete Example​

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

async function main() {
  // Initialize manager
  const manager = new AgentManager('./agents/registry.json');
  await manager.loadRegistry();

  // List available agents
  console.log('Available agents:');
  for (const agent of manager.listAgents()) {
    console.log(`  - ${agent.name} (${agent.id}): ${agent.description}`);
  }

  // Create and use an agent
  if (manager.hasAgent('coding-agent')) {
    const agent = await manager.loadAgent('coding-agent');
    await agent.start();

    const session = await agent.createSession();
    const response = await agent.generate('Hello!', session.id);
    console.log(response.content);

    await agent.stop();
  }
}

main();

Error Handling​

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

try {
  const manager = new AgentManager('./registry.json');
  const agent = await manager.loadAgent('non-existent-agent');
} catch (error) {
  if (error.code === 'AGENT_NOT_FOUND') {
    console.log('Agent not found in registry');
  } else if (error.name === 'DextoValidationError') {
    console.log('Agent config validation failed:', error.issues);
  }
}

See Also​