Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Agent Catalyst workflows can leverage input data in two main ways to process and generate meaningful outputs:
Static Data: Predefined and embedded directly in the workflow.
User Input: Dynamically provided by the user at runtime.
Static data is defined in the workflow’s frontmatter metadata using the data field. These values are accessible throughout the workflow during execution.
Example: Static Data
Accessing Data: Reference static data fields like quote or langs using {} syntax, e.g., {quote} or {langs}.
Complex Structures: Data can include simple strings, nested objects, or arrays.
User inputs allow workflows to be reusable by prompting for specific input values during execution. Inputs are defined using the input field in the frontmatter metadata.
Example: User Input
Dynamic Prompts: The user is prompted to input a quote during execution.
Reusability: The workflow adapts to different inputs without modification.
Agent Catalyst supports diverse input types for flexible user interaction. Inputs are specified as key-value pairs under the input field.
1. Text Input
Prompts the user for a single-line or multi-line text.
Example:
2. Select Input
Prompts the user to choose from a list of options.
Example:
3. File Input
Prompts the user to upload a file or specify a file path.
Example:
4. Array Input
Prompts the user to enter multiple text values, which are returned as an array.
Example:
Uniqueness: All variable names (from inputs or actions) must be unique within the workflow. Duplicate names will cause a compilation error.
Nested Scopes: Variables can be reused within nested scopes (e.g., within <Loop /> or <Cond />).
Example of Block Scoping:
In this example:
item and subitem are scoped to their respective loops.
Parent variables must be explicitly passed using provide.
Field
Type
Description
Required
type
string
Must be "text".
✅
message
string
Prompt displayed to the user.
✅
multiline
boolean
Allows multi-line input (default: false).
❌
Field
Type
Description
Required
type
string
Must be "select".
✅
options
array
List of options (strings or objects).
✅
Field
Type
Description
Required
type
string
Must be "file".
✅
fileType
string
File type ("text" or "image").
✅
Field
Type
Description
Required
type
string
Must be "array".
✅
multiline
boolean
Allows multi-line input.
❌
yaml ---
data:
quote: "The only limit to our realization of tomorrow is our doubts of today."
langs:
- Spanish
- Italian
- German
- French
---
<Loop
as="translations"
until={$.index === langs.length}
provide={{ langs, quote }}>
Translate "{quote}" into {langs[$.index]}.
<GenText as="translation" model="openai:gpt-4o" />
</Loop>yaml ---
data:
langs:
- Spanish
- Italian
- German
- French
input:
quote:
type: text
message: "Enter a quote you'd like to translate:"
---
<Loop
as="translations"
until={$.index === langs.length}
provide={{ langs, quote }}>
Translate "{quote}" into {langs[$.index]}.
<GenText as="translation" model="openai:gpt-4o" />
</Loop>yaml quote:
type: text
message: "Enter your favorite quote:"
multiline: false yaml language:
type: select
message: "Select a language for translation:"
options:
- Spanish
- French
- German yaml upload:
type: file
fileType: text
message: "Upload a text file for processing:" yaml languages:
type: array
message: "Enter a list of languages for translation:"
multiline: true yaml <Loop
as="outer"
until={$.index === items.length}
provide={{ item: items[$.index] }}>
Item: {item.name}
<Loop
as="inner"
until={$.index === item.subitems.length}
provide={{ subitem: item.subitems[$.index] }}>
Subitem: {subitem.name}
</Loop>
</Loop>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.
Install the Agent Catalyst core package using your preferred package manager:
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:
Workflows are executed step-by-step using the AgentExecutionController. This controller provides real-time events to track progress, handle errors, and manage outputs.
Event Emission:
step: Triggered at the start of each workflow step.
complete: Triggered when the workflow finishes successfully.
Basic Workflow Execution
Dynamic Input Handling
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.
Agent Catalyst is a modular platform designed for building, managing, and optimizing AI-powered workflows and intelligent systems. By leveraging natural language and Markdown, it empowers users to create scalable, collaborative solutions with minimal technical expertise.
Agent Catalyst enables natural language programming, letting you design workflows in plain language and Markdown. This intuitive approach makes creating intelligent systems accessible while encouraging computational thinking.
Example Workflow:
No coding expertise is required. With basic knowledge of the platform, you can create AI-driven workflows through simple instructions and prompts.
Agent Catalyst equips you with state-of-the-art AI tools to:
Analyze data, generate insights, and extract structured information.
Automate reasoning, decision-making, and collaborative processes.
Integrate seamlessly with top AI providers like OpenAI and Anthropic.
Support local, open-source AI models through flexible integrations.
Extend the power of Agent Catalyst with robust tool support:
Data Connectivity: Integrate with databases, web services, and local files.
Custom Tools: Build specialized tools with JavaScript for bespoke functionalities.
Modular Support: Utilize Vercel’s AI SDK and other frameworks for advanced capabilities.
Agent Catalyst delivers a seamless developer experience:
Intuitive project setup and workflow management through its Command-Line Interface (CLI).
Efficient debugging and iteration tools to optimize workflows.
Built with TypeScript, allowing seamless integration with the JavaScript ecosystem (Node.js, NPM, Yarn, Bun).
Agent Catalyst thrives as open-source software, offering:
Full Control: Deploy workflows on your infrastructure with complete data ownership.
Cost Efficiency: Use your own API keys and control expenses with token-based pricing.
Collaboration: Evolve the platform with community feedback and contributions.
Simplicity: Design intelligent workflows using plain language.
Scalability: Modular architecture adapts to growing needs.
Flexibility: Supports cloud and local AI models for diverse applications.
Customizability: Integrate tailored tools and workflows for unique challenges.
Agent Catalyst bridges the gap between simplicity and sophistication, empowering teams to create, manage, and scale intelligent workflows effortlessly.
bash # Using npm
npm install @agentsystem/core
# Using yarn
yarn add @agentsystem/core
# Using bun
bun add @agentsystem/coremarkdown Analyze the customer reviews and categorize key themes:
{reviews}
<GenText as="themes" model="openai:gpt-4" /> Empowerment: Turn ideas into scalable, impactful AI solutions with ease.
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.
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);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();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();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();The Agent Catalyst CLI is a powerful tool designed to simplify the creation, management, and execution of AI-driven workflows. With intuitive commands, users can seamlessly interact with Agent Catalyst projects directly from their terminal.
If your project was initialized using npm create agent-system, the CLI is already installed locally. You can access it using your package manager (e.g., npx asystem [command] or yarn asystem [command]).
To install the Agent Catalyst CLI globally, use one of the following commands:
init - Create a New Project
Initializes a new Agent Catalyst project in the specified directory.
Arguments:
path (Optional): The directory where the project will be created. Defaults to the current directory.
Options:
-t, --template <name> (Optional): Specifies a project template to use.
list - List Available Workflows
Displays all workflows available in the current project.
This command scans the workflows/ directory and lists:
Workflow IDs
Workflow Titles
exec - Execute a Workflow
Runs a specific workflow from the current project.
Arguments:
workflow (Required): The name of the workflow to execute.
Execution Process:
The CLI prompts for any user inputs defined in the workflow.
Outputs are streamed to the console in real-time.
Logs and generated files are saved to a timestamped directory in /outputs.
Create a New Project
Creates a new project in the my-new-project directory using the basic-template.
List Workflows
Displays all available workflows in the current project.
Execute a Workflow
Ease of Use: Simple commands for creating projects, listing workflows, and executing tasks.
Real-Time Outputs: Monitor progress and view results directly in the console.
Automatic Logging: Save outputs and logs in organized, timestamped directories for easy reference.
The Agent Catalyst CLI is a robust and efficient solution for building, managing, and running AI workflows, streamlining the process of creating AI-driven applications.
translate-quote workflow, streams the progress to the console, and saves the results in the /outputs directory.bash # Using npm
npm install -g @agentsystem/cli
# Using yarn
yarn global add @agentsystem/cli
# Using bun
bun add -g @agentsystem/clibash asystem init [path] [options]
# Alias
asystem i [path] [options]bash asystem list
# Alias
asystem lsbash asystem exec <workflow>
# Alias
asystem x <workflow>bash asystem init my-new-project -t basic-templatebash asystem listbash asystem exec translate-quoteAn Agent Catalyst workflow is a plain text document that defines a process or goal. Written in Markdown with enhanced syntax, it provides a structured, intuitive way to design and execute tasks.
Agent Catalyst workflows are structured into three levels:
Workflow: The overarching program, written in natural language and Markdown.
Phase: Subsections representing mini-programs that can reset or reuse context.
Action: Specific tasks or requests sent to AI models or tools within a phase.
Workflows execute sequentially, processing each phase in order and completing all actions within those phases.
Agent Catalyst enhances standard Markdown with additional capabilities:
Standard Markdown: Fully supported for text formatting.
Horizontal Rules (---): Separate phases within the workflow.
Flow Elements: <GenText />, <Loop />, and others for specific actions.
Phases organize workflows into logical sections. Each phase resets the context unless data is explicitly passed forward.
Single Phase Example
Multiple Phases Example
Use {poem} to pass data between phases. Each phase provides a clean context for new actions.
If the first phase contains no actions, it serves as a description of the workflow’s purpose.
Actions are the building blocks of workflows. Each action performs a task and produces an output that can be referenced later.
Built-In Actions:
AI Generation: <GenText /> for text, <GenObject /> for structured data.
Control Flow: <Loop />, <Cond /> for iteration and conditional logic.
Example:
JavaScript expressions enclosed in {} inject dynamic content into workflows.
In Text:
In Action Attributes:
In Flow Blocks:
Expressions can reference:
Workflow inputs (from frontmatter).
Results of prior actions.
Helper variables provided by actions.
Actions like <Loop /> and <Cond /> provide helper variables accessible via $ or the action's as name.
Nested Loops Example
$ refers to the current loop's helpers.
$outer accesses helpers from the parent loop.
Actions that wrap content (e.g., <Loop />) create nested scopes. Variables can be reused without conflict, and parent state must be explicitly passed using provide.
Example with Nested Scopes
With Agent Catalyst, workflows are flexible, modular, and intuitive, enabling dynamic, context-aware AI solutions tailored to your needs.
JavaScript Expressions ({}): Inject dynamic content or reference results.
Frontmatter: Define input data and metadata at the start of the workflow.
markdown Write a poem about stars.
<GenText as="poem" model="openai:gpt-4o" />
Now translate it to French:
<GenText as="translation" model="openai:gpt-4o" /> markdown # Phase 1: Write a poem
Write a poem about stars.
<GenText as="poem" model="openai:gpt-4o" />
---
# Phase 2: Translate the poem
Translate this poem to French:
{poem}
<GenText as="translation" model="openai:gpt-4o" /> markdown # Workflow: Starry Night Translator
This workflow generates a poem about stars and translates it into French. markdown Write a haiku about the sea.
<GenText as="haiku" model="openai:gpt-4o" />
Translate it to Spanish:
<GenText as="translation" model="openai:gpt-4o" input={haiku} /> markdown Hello {name}! markdown <GenText as="greeting" model="openai:gpt-4o" input={`Hello, ${name}!`} /> markdown {tasks.map(task => `- ${task}`).join('\n')} markdown <Loop as="outer" until={$.index === items.length} provide={{ items }}>
<Loop as="inner" until={$.index === items[$outer.index].subitems.length} provide={{
item: items[$outer.index],
subitem: items[$outer.index].subitems[$.index],
}}>
Item: {item.name}
Subitem: {subitem.name}
</Loop>
</Loop> markdown Write a poem about rivers.
<GenText as="poem" model="openai:gpt-4o" />
<Loop as="translations" until={$.index === langs.length} provide={{
language: langs[$.index],
original: poem,
}}>
Translate this poem to {language}:
{original}
<GenText as="translation" model="openai:gpt-4o" />
</Loop> Agent Catalyst integrates powerful AI models into workflows, enabling seamless text generation, structured data extraction, and reasoning tasks. This functionality empowers users to create dynamic, AI-driven processes tailored to their needs.
Text generation allows users to create various types of content, such as summaries, narratives, or creative texts, using large language models (LLMs).
Example: Generating a Scientific Abstract
Attributes for <GenText />
The generated text is stored in the specified variable (e.g., abstract) and can be reused in later steps.
Structured data generation ensures that AI outputs conform to specific formats, making it ideal for extracting reliable, programmatic data.
Example: Extracting Conference Speakers
Attributes for <GenObject />
Schema Validation: Ensures the output adheres to the specified structure, making it reliable for automated workflows.
Agent Catalyst supports multiple AI providers through integrations with SDKs like OpenAI, Anthropic, and Google. It also works with local open-source models using tools like Ollama.
Provider Configuration Example
Custom Provider Setup
For custom configurations, you can create provider instances:
When using <GenText /> or <GenObject />, the model must be specified in the format providerId:modelId.
Example
yaml <GenText
as="abstract"
model="openai:gpt-4"
message="Based on the following research paper, create a concise and detailed scientific abstract summarizing the findings: {research}" /> tools
array
List of tools the LLM can use.
❌
options
object
LLM-specific options for fine-tuning.
❌
schema
ZodType
Schema defining the data structure.
✅ (if output is object or array)
enum
array
List of possible values (if output is enum).
✅ (if output is enum)
schemaDescription
string
Additional guidance for the AI model.
❌
tools
array
List of tools the LLM can use.
❌
Attribute
Type
Description
Required
as
string
Unique variable name to store the result.
✅
model
string
AI provider and model name.
✅
stream
boolean
Enables response streaming (default: true).
❌
Attribute
Type
Description
Required
as
string
Unique variable name to store the result.
✅
model
string
AI provider and model name.
✅
output
string
Type of output: object, array, enum, or no-schema.
✅
yaml <GenObject
as="speakers"
model="openai:gpt-4"
output="array"
schema={{
$.z.object({
name: $.z.string().describe('Full name of the speaker'),
company: $.z.string().describe('Company name'),
twitter: $.z.string().describe('Twitter profile').optional(),
})
}}
message="Extract all conference speakers and their details from the given webpage: {url}" /> yaml <Loop
as="messages"
until={$.index === speakers.filter(s => !!s.twitter).length}
provide={{ speaker: speakers.filter(s => !!s.twitter)[$.index] }}>
Write a tweet thanking the speaker for their presentation. Make it fun, humorous, and use plenty of emojis.
Speaker: {speaker.name}
Company: {speaker.company}
Twitter: {speaker.twitter}
<GenText as="tweet" model="openai:gpt-4" />
</Loop>javascript import { defineConfig } from '@agentsystem/core';
import { openai } from '@ai-sdk/openai';
import { anthropic } from '@ai-sdk/anthropic';
export default defineConfig({
providers: {
openai,
anthropic,
},
});javascript import { createOpenAI } from '@ai-sdk/openai';
export default defineConfig({
providers: {
openai: createOpenAI({
apiKey: process.env.OPENAI_API_KEY,
compatibility: 'strict',
}),
anotherProvider: createOpenAI({
apiKey: process.env.ANOTHER_API_KEY,
baseURL: 'https://api.example.com',
}),
},
});yaml <GenText
as="outline"
model="openai:gpt-4"
message="Write an outline for a futuristic space adventure novel." /> You don’t need to be a professional programmer to use Agent Catalyst. However, comfort with the command line, a curious mindset, and an interest in solving challenges will help you maximize its potential.
First, ensure you have a JavaScript runtime installed (like Node.js or Bun). Use your preferred package manager to initialize a new Agent Catalyst project. Specify the project name via the command line, or use . to scaffold the project in the current directory.
Using npm
Using yarn
Using bun
Follow the prompts during initialization. Once complete, navigate to the project directory and install the necessary dependencies:
Install Dependencies
Creating a new project initializes the following structure:
Key Files:
📂 flows/: Where all your workflows are created and stored.
📂 outputs/: Stores the results of executed workflows.
.env: Securely stores secrets like API keys for AI providers.
agent-system.config.js: The main configuration file for your project.
1. Configure AI Providers
Add your AI provider settings to the agent-system.config.js file.
2. Add API Keys
Securely store your API keys in the .env file.
In a project with Agent Catalyst installed, you can use the asystem CLI tool to manage, create, and execute workflows. To see a full list of commands, use:
Display Help
When running workflows with the asystem CLI, Agent Catalyst will look for an agent-system.config.js (or .ts) file in the project root. If a .env file is present, it will be loaded first, making its variables available via process.env.
Example Configuration (agent-system.config.js)
bash npm create agent-system@latest my-systembash yarn create agent-system my-systembash bun create agent-system my-systembash cd my-system
npm install bash my-system/
├── flows/ # Your workflows are stored here.
│ └── hello-world.mdx # Example workflow.
├── outputs/ # Execution results are saved here.
├── .env # Store secrets like API keys here.
├── agent-system.config.js # Project configuration file.
└── package.jsonbash npx asystem helpjavascript import { defineConfig } from '@agent-system/core';
import { createOpenAI } from '@ai-sdk/openai';
export default defineConfig({
providers: {
openai: createOpenAI({
apiKey: process.env.MY_OPENAI_KEY,
}),
},
});