Agent Catalyst JavaScript API

The Agent Catalyst provides a versatile JavaScript API for programmatically managing and executing agent-based workflows. This API allows you to define, compile, and run workflows directly in JavaScript or TypeScript applications.

Installation

Install the Agent Catalyst core package using your preferred package manager:

bash # Using npm
npm install @agentsystem/core

# Using yarn
yarn add @agentsystem/core

# Using bun
bun add @agentsystem/core

Usage

Workflow Compilation

In Agent Catalyst, a workflow is represented by an AgentWorkflow instance. It encapsulates structure, metadata, and execution logic. Use the AgentWorkflow.compileSync method to create a workflow instance from a Markdown string:

javascript import { AgentEnvironment, AgentWorkflow } from '@agentsystem/core';

// Initialize an environment with configured agent handlers
const env = new AgentEnvironment({
  agents: {
    // Configure agent handlers here (e.g., text generation, data processing)
  }
});

const markdown = `
# Joke Generator
Tell me the corniest dad joke you can think of.
<GenText as="joke" model="openai:gpt-4" />
`;

const agentWorkflow = AgentWorkflow.compileSync(markdown, env);

Workflow Execution

Workflows are executed step-by-step using the AgentExecutionController. This controller provides real-time events to track progress, handle errors, and manage outputs.

javascript // Create an execution controller with optional initial context
const ctrl = agentWorkflow.createExecution({
  name: { type: 'primitive', value: 'Jane Doe' } // Example initial context
});

// Listen for step-by-step progress
ctrl.on('step', (step, event, cursor) => {
  console.log(`Executing step: ${cursor.toString()}`);

  // Access the result of the step's action, if available
  event.action?.then(({ result }) => {
    console.log('Step result:', result);
  });
});

// Listen for workflow completion
ctrl.on('complete', (output) => {
  console.log('Workflow completed successfully:');
  console.log(output);
});

// Handle errors during execution
ctrl.on('error', (error) => {
  console.error('Error during workflow execution:', error);
});

// Start the workflow execution
await ctrl.runAll();

Features of the Execution Controller

• Event Emission:

  • step: Triggered at the start of each workflow step.

  • complete: Triggered when the workflow finishes successfully.

  • error: Triggered when an error occurs during execution.

• Fine-Grained Control:

  • Pause: Temporarily halt execution at any point.

  • Rewind: Rollback to previous steps for re-execution.

Examples

Basic Workflow Execution

javascript const markdown = `
# Translate a Quote

Translate the following quote into French:

<GenText as="translation" model="openai:gpt-4" />
`;

const agentWorkflow = AgentWorkflow.compileSync(markdown, env);

const ctrl = agentWorkflow.createExecution();
ctrl.on('complete', (output) => {
  console.log('Translation result:', output);
});

await ctrl.runAll();

Dynamic Input Handling

javascript const markdown = `
# Dynamic Quote Translation

<PromptInput as="quote" message="Enter a quote to translate:" />
<GenText as="translation" model="openai:gpt-4" />
`;

const agentWorkflow = AgentWorkflow.compileSync(markdown, env);

const ctrl = agentWorkflow.createExecution();
ctrl.on('step', (step) => {
  if (step.action) {
    console.log(`Current step action: ${step.action.type}`);
  }
});

await ctrl.runAll();

Why Use the Agent Catalyst JavaScript API?

• Flexibility: Execute workflows dynamically within any JavaScript or TypeScript application.

• Real-Time Monitoring: Track progress, handle errors, and retrieve results as they occur.

• Advanced Control: Pause, rewind, or resume workflows as needed.

• Seamless Integration: Directly interact with agent-based systems and external tools.

The Agent Catalyst’s JavaScript API empowers developers to integrate autonomous agent-driven workflows into their applications, enabling robust automation, data processing, and decision-making capabilities.