# 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
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
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
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
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
markdown Hello {name}!  
```

**In Action Attributes:**

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

**In Flow Blocks:**

```markdown
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
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
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://deusai.gitbook.io/agent-catalyst/workflow-structure-with-agent-catalyst.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.