Workflow Structure with Agent Catalyst

An 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 Workflow Organization

Agent Catalyst workflows are structured into three levels:

1. Workflow: The overarching program, written in natural language and Markdown.

2. Phase: Subsections representing mini-programs that can reset or reuse context.

3. 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.

---

Markdown Syntax in Workflows

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.

• JavaScript Expressions ({}): Inject dynamic content or reference results.

• Frontmatter: Define input data and metadata at the start of the workflow.

---

Phases

Phases organize workflows into logical sections. Each phase resets the context unless data is explicitly passed forward.

Single Phase Example

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" />  

Multiple Phases Example

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" />  

Use {poem} to pass data between phases. Each phase provides a clean context for new actions.

---

Workflow Descriptions

If the first phase contains no actions, it serves as a description of the workflow’s purpose.

markdown # Workflow: Starry Night Translator  
This workflow generates a poem about stars and translates it into French.  

---

Actions

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:

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} />  

---

Expressions

JavaScript expressions enclosed in {} inject dynamic content into workflows.

In Text:

markdown Hello {name}!  

In Action Attributes:

markdown <GenText as="greeting" model="openai:gpt-4o" input={`Hello, ${name}!`} />  

In Flow Blocks:

markdown {tasks.map(task => `- ${task}`).join('\n')}  

Expressions can reference:

• Workflow inputs (from frontmatter).

• Results of prior actions.

• Helper variables provided by actions.

---

Action Helpers

Actions like <Loop /> and <Cond /> provide helper variables accessible via $ or the action's as name.

Nested Loops Example

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>  

• $ refers to the current loop's helpers.

• $outer accesses helpers from the parent loop.

---

Block Scoping

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

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>  

With Agent Catalyst, workflows are flexible, modular, and intuitive, enabling dynamic, context-aware AI solutions tailored to your needs.