Flow Super Agent

The FlowSuperAgent in the AI Refinery SDK is designed to orchestrate complex workflows composed of multiple agents with defined dependencies. The FlowSuperAgent allows users to define nodes (utility agents or super agents) and edges (dependencies) between them, enabling the creation of flexible and powerful pipelines.

Workflow Overview

The FlowSuperAgent is invoked by the orchestrator for complex tasks that are defined by the user as directed graphs. Upon invocation, the FlowSuperAgent workflow is structured around three essential components:

1. Goal: The overall goal that the FlowSuperAgent needs to accomplish by following the deterministic workflow defining the action steps.

2. Agent List: A FlowSuperAgent has access to a pool of agents. These agents in can be utility agents - e.g., SearchAgent, AuthorAgent - or super agents that it directs to accomplish the overall goal.

3. Workflow Graph Definition: The graph dictating the workflow of the FlowSuperAgent that defines the dependencies between the agents to schedule the task execution.

4. Execution Flow: Once the workflow graph is defined, the agent execution depends on whether Triage and Loops are enabled:

   • Without Triage or Loops – deterministic execution of agents
   • With Triage – conditional execution per agent
   • With Loops - conditional rewind

Execution Flow

Without Triage or Loops

If Triage is not enabled:

• Agents execute deterministically according to the DAG defined in agent_list.
• Every agent runs once its parent agents complete.
• No conditional skipping occurs.

With Triage

The Triage feature enables per-agent conditional execution of downstream steps based on user-defined criteria. Each agent can define its own triage logic independently. Triage is an individual agent feature, not a global workflow setting.

If Triage is enabled:

• Each agent evaluates its next_step conditions.
• If a condition is true, the corresponding child agents are executed.
• If a condition is false, a vote to skip is cast for the corresponding agents.
  • Skip votes may propagate to any nodes further downstream from corresponding agents. However, this only occurs at nodes for which all parents have voted to skip.
  • Similarly, execution of any agent is only skipped if all parents vote to skip.
• If no condition matches, the default step executes. Exactly one default must be specified for every agent that uses triage.
• Triage mode (first-match or all-match) determines how conditions are evaluated:
  • 'all-match' – all conditions are evaluated.
  • 'first-match' – evaluation stops at the first true condition.

Good Triage conditions should:

• Reference only the output of the current agent (agent_name).
• Be clear, quantifiable, and based on measurable aspects.
• Avoid ambiguous or cross-agent dependent conditions.
• Be mutually exclusive or reference different agents to avoid overwriting votes.

Note: Users may enable show_triage_feedback to include condition assessments in the output.

With Loops

The Loop feature enables conditional backward edges in the workflow, allowing the FlowSuperAgent to rewind from a loop tail node to a specified loop head node when certain criteria are not met. Loops are defined per-agent within the next_step field.

A loop tail is defined as a node at which loop conditions are specified, and thus a node at which execution can rewind. A loop head is defined as a node that is rewinded-to from a loop tail. These terms define the tail and head of a loop edge (tail -> head).

If a loop is defined at a node:

• After the loop tail executes, its loop conditions are evaluated using an LLM.
• If a loop condition is true (and the iteration limit has not been reached), execution rewinds to the specified loop head, re-running all descendants of the loop head in the workflow up to the loop tail.
• For any condition, there must be exactly one loop head defined.
• If a loop condition is false, or the maximum iteration count has been exceeded, the loop is ignored and execution continues.
• Any number of conditions under the same loop tail will be evaluated sequentially from top to bottom. At the first true condition, the rewind will trigger and subsequent conditions will be ignored.
• Under a given loop tail, if all conditions evaluate to false or all max_iterations are reached, execution continues normally through the default node. For this reason, exactly one default block must be defined at the end of a loop block.
• Loops require a max_iterations field to prevent infinite execution. Once this limit is reached, the loop condition is ignored and execution proceeds. The maximum possible number for max_iterations is 99.

Constraints:

• The loop head must be upstream of the loop tail (i.e., the node where the condition is defined) and there must be a path connecting both nodes.
• Only one loop tail per depth level is permitted to define loops to avoid race conditions in parallel execution.

Note: Set show_loop_feedback: true in the config block to include loop trigger details (condition evaluation, iteration count, and target node) in the output.

Usage

Flow super agents can be easily integrated into your project by adding the necessary configurations to your project YAML file. Specifically, you need to:

• List your super agents under the super_agents attribute in your project's YAML configuration.
• Ensure the agent_name you chose for your super_agents are listed in the agent_list under orchestrator.
• Ensure that the assistant agents that are available to the FlowSuperAgent are listed in either the utility_agents list or the super_agents list.
• Define the deterministic workflow as a graph with vertices and edges. To do so:
  • Define the vertices as entries in the agent_list of the FlowSuperAgent
  • Define the edges by specifying for each agent_name in the agent_list the next_step that will be taken.
  • Optionally, if triage is desired at a specific agent, all next_step entries must specify either condition and to, or default: true and to.

Note: If using nested super agents, meaning the FlowSuperAgent will be calling other super agents (SuperAgent, EvaluationSuperAgent, FlowSuperAgent), then these agents may not contain circular dependencies. This means that no super agent may reference itself through its agent_list, neither immediately nor through a chain of other super agents. For example, if A calls B, and B calls C, then C cannot call A, B, or any agent that eventually leads back to A or B. See this tutorial for an example usage of nested super agents.

Quickstart

Without Triage or Loops

To quickly set up a project with a FlowSuperAgent, use the following YAML configuration. In this setup, we have a single flow super agent that acts as Strategy Advisor. It has three instances of a SearchAgent and one of the AuthorAgent in its agent pool. You can add more super agents and utility agents as needed.

utility_agents:
  - agent_class: AuthorAgent # AuthorAgent class design
    agent_name: "Brief Writer" # Required. A name that you choose for your AuthorAgent.
    agent_description: "Write the marketing brief" # Required. Description of your AuthorAgent.
    config: # Required. Configuration of this AuthorAgent.
      memory_attribute_key: "plan" # Memory key to store the generated summary.
      title: "Insights Brief" # Title for the draft summary.
      leading_questions: # Guiding questions used by the AuthorAgent to structure the brief.
        - question: "What is the name of the project?" # Required. First guiding question.
          prompt: "Project name. This is usually specified by the background information." # Prompt to guide answering the question.
        - question: "Who is the audience?" # Required. Second guiding question.
          prompt: "Who exactly are we targeting? Detail the specific demographics, industries, or roles we aim to reach, emphasizing how our project aligns with their interests and needs." # Prompt to guide answering the question.
        - question: "What do they want to do and why?" # Required. Third guiding question.
          prompt: "What are the audience's main objectives and motivations? Let's dive into their goals to understand how our project aligns with their needs, rather than focusing on our growth targets." # Prompt to guide answering the question.
        - question: "How can we help them?" # Required. Fourth guiding question.
          prompt: "What specific support or solutions can we offer to meet the audience's needs? Propose a range of options for discussion." # Prompt to guide answering the question.

  - agent_class: SearchAgent # SearchAgent class design
    agent_name: "Competitor Researcher" # Required. A name that you choose for this SearchAgent.
    agent_description: "Find what our competitors have done in the area / industry." # Required. Description of this SearchAgent's research scope.

  - agent_class: SearchAgent # SearchAgent class design
    agent_name: "Campaign Insights Researcher" # Required. A name that you choose for this SearchAgent.
    agent_description: "Find insights and takeaways from other past campaigns that are relevant to this topic." # Required. Description of this SearchAgent's research scope.

  - agent_class: SearchAgent # SearchAgent class design
    agent_name: "Audience Understanding Researcher" # Required. A name that you choose for this SearchAgent.
    agent_description: "Identify the potential audience for this campaign focusing on their desires, concerns, and needs." # Required. Description of this SearchAgent's research scope.

super_agents:
  - agent_class: FlowSuperAgent # FlowSuperAgent class design
    agent_name: "Strategy Advisor" # Required. A name that you choose for your super agent.
    agent_description: | # Required. Description of your super agent.
      The Strategy Advisor can help user write their marketing campaign brief. Only call this agent when the user explicitly asks for a brief.

    config: # Required. Configuration of this super agent.
      goal: | # Required. A high level goal of your super agent.
        The goal is to create an insights brief for a marketing campaign. To create the brief, you will need to call the research agent to do research around the topic. Make sure you have called all the agents (you can track the call history from below) before you call the author agent to draft an insights brief.

      agent_list: # Required. The list of agents to be added in the agent pool. Each agent listed here must be configured under `utility_agents` or `super_agents` in the root of the project YAML file.
        - agent_name: "Competitor Researcher"  # Required.
          next_step: # User design. These are the tasks that depend on this step and will be executed afterward.
            - "Campaign Insights Researcher"
            - "Audience Understanding Researcher"

        - agent_name: "Campaign Insights Researcher"  # Required.
          next_step: # User design. Specifies next steps to run after this agent.
            - "Brief Writer"

        - agent_name: "Audience Understanding Researcher"  # Required.
          next_step: # User design. Specifies next steps to run after this agent.
            - "Brief Writer"

        - agent_name: "Brief Writer"  # Required. Exit agent that produces the summary output.

With Triage

If Triage is desired at a certain agent, the Layout for the next_step field of that agent changes:

agent_list:
  - agent_name: 'Agent 1'       # The name of this agent/node in the FlowSuperAgent workflow. Must be defined in utiliy_agents
    mode: 'first-match'         # Triage evaluation mode for this agent. Can be 'first-match' or 'all-match'
    next_step:                   # List of conditional next steps for this agent
      - condition: 'Agent 1 output is 0'  # A logical condition based on the output of Agent 1
        to: ['Agent 2']                    # If the condition is true, execute Agent 2 next
      - condition: 'Agent 1 output is 10' # Another condition based on Agent 1 output
        to: ['Agent 3']                    # If this condition is true, execute Agent 3 next
      - default: true                       # Default fallback step if no conditions above are true
        to: ['Agent 4']                    # Execute Agent 4 if all conditions fail

This flexible structure maintains compatibility with FlowSuperAgent projects that do not include Triage.

Here is a sample super_agents configuration for this example incorporating Triage. Any agents used here must be defined previously in utility_agents:

super_agents:
  - agent_class: FlowSuperAgent             # Specifies the agent class used (FlowSuperAgent)
    agent_name: "Flow"                      # Name of this super agent instance
    agent_description: |                    # Description of what this super agent does
      Some Description
    config:
      goal: |                              # High-level goal that the FlowSuperAgent should accomplish
        Some Goal      
      show_triage_feedback: True           # Enables detailed triage condition feedback in output
      agent_list:                          # List of agents in the workflow graph
        - agent_name: 'Agent 1'            # Name of an agent in the workflow
          mode: 'all-match'                # Required for Triage.
          next_step:                       # List of conditional next steps that depend on Agent 1's output
            - condition: 'Agent 1 output is 0'  # Condition that triggers the following next steps
              to: ['Agent 2']             # If condition true, vote to execute Agent 2
            - default: true                # Exactly 1 Required: Default fallback
              to: ['Agent 3']             # If no conditions matched, execute Agent 3

        - agent_name: 'Agent 2' # Required to use this agent
        - agent_name: 'Agent 3' # Required to use this agent

In this example:

• Triage assessments will appear in the output.
• Conditions relate only to 'Agent 1'’s output.
• If 'Agent 1'’s output is 0, 'Agent 2' executes.
• If not, 'Agent 1' votes to skip 'Agent 2' and its children.
• 'Agent 2' will only execute if it has other parents who do not vote to skip it.

With Loops

If a loop is desired at a certain agent, this agent (which is now a loop tail) must specify the loop in its next_step field. Any agents used here must be defined in the utility_agents section of the workflow.

super_agents:
  - agent_class: FlowSuperAgent             # Specifies the agent class used (FlowSuperAgent)
    agent_name: "Flow"                      # Name of this super agent instance
    agent_description: |                    # Description of what this super agent does
      Some Description
    config:
      goal: |                              # High-level goal that the FlowSuperAgent should accomplish
        Some Goal      
      show_loop_feedback: True           # Enables detailed loop condition feedback in output
      agent_list:
        - agent_name: 'Agent A'          # Loop head — execution rewinds to here
          next_step:
            - 'Agent C'
        - agent_name: 'Agent B'          # Loop head — execution rewinds to here
          next_step:
            - 'Agent C'

        - agent_name: 'Agent C'          # Loop tail — defines the backward edge
          next_step:
            - condition: 'Agent C output is 0'   # Condition evaluated after Agent B runs
              loop:
                to: ['Agent A']                  # Rewind target (must be upstream of Agent C and reachable)
                max_iterations: 3                # Maximum number of times this loop can trigger
            - condition: 'Agent C output is 10'  # Condition evaluated after Agent B runs
              loop:
                to: ['Agent B']                  # Rewind target (must be upstream of Agent C)
                max_iterations: 3                # Maximum number of times this loop can trigger
            - default: true                      # Fallback reached when all loop conditions are false or all iteration limits reached
              to: ['Agent D']

        - agent_name: 'Agent D'

In this example:

• Loop feedback will appear in the output.
• 'Agent A' and 'Agent B' run in parallel, both feeding into 'Agent C'.
• There are 3 depth-levels in this graph: level 1 (Agents A, B), level 2 (Agent C), and level 3 (Agent D).
• There is only 1 loop tail node at depth level 2 - 'Agent C'.
• After 'Agent C' completes, its loop conditions are evaluated sequentially.
• If 'Agent C''s output is 0, execution rewinds to 'Agent A' and re-runs Agents A, and C (up to 3 times).
• If 'Agent C''s output is 10, execution also rewinds to 'Agent B' and re-runs Agents B, and C (up to 3 times).
• If neither condition is true, or all iteration limits are reached, 'Agent D' executes.

Template YAML Configuration of FlowSuperAgent

Without Triage or Loops

In addition to the configurations mentioned for the example above, the FlowSuperAgent supports several other configurable options. See the template YAML configuration below for all available settings for each super agent.

super_agents:
  - agent_class: FlowSuperAgent  # The class must be FlowSuperAgent
    agent_name: <A name that you choose for your super agent>  # Required
    agent_description: <Description of your super agent>  # Required

    config:  # Required. Configuration of this super agent
      goal: <A high level goal of your super agent>  # Required

      agent_list:  # Required. Each agent listed here must exist in utility_agents or super_agents
        - agent_name: <Name of Agent 1>  # Required
          next_step:  # Optional: tasks that depend on Agent 1
            - <Name of Agent 2>
            - <Name of Agent 3>

        - agent_name: <Name of Agent 2>  # Required
          next_step: <Name of Agent 3>  # Optional

  # Nested super agents are allowed (agent_list can reference other super agents)
  # Circular dependencies are not permitted. No agent may reference itself directly or indirectly.

With Triage

The following represents a generic template for a configuration involving Triage:

super_agents:
  - agent_class: FlowSuperAgent  # Specifies the agent class used
    agent_name: <A name that you choose for your super agent>  # Required
    agent_description: <Description of your super agent>  # Required

    config:  # Required. Configuration of this super agent
      goal: <A high level goal of your super agent>  # Required
      show_triage_feedback: <True or False>  # Optional: enables triage feedback

      agent_list:  # Required. Each agent listed here must exist in utility_agents or super_agents
        - agent_name: <Name of Agent 1>  # Name of agent
          mode: <'all-match' or 'first-match'>  # Required for Triage
          next_step:  # Required for Triage
            - condition: <Some condition>  # Condition that triggers next steps
              to: [<Name of Agent 2>, <Name of Agent 3>]  # Agents to run if condition true
            - default: true  # Exactly 1 required
              to: [<Name of Agent 4>]  # Fallback if no conditions matched

        - agent_name: <Name of Agent 2>  # Required
        - agent_name: <Name of Agent 3>  # Required
        - agent_name: <Name of Agent 4>  # Required

With Loops

The following represents a generic template for a configuration involving Loops:

super_agents:
  - agent_class: FlowSuperAgent  # Specifies the agent class used
    agent_name: <A name that you choose for your super agent>  # Required
    agent_description: <Description of your super agent>  # Required

    config:  # Required. Configuration of this super agent
      goal: <A high level goal of your super agent>  # Required
      show_loop_feedback: <True or False>   # Optional: enable loop info in output

      agent_list:  # Required. Each agent listed here must exist in utility_agents or super_agents
        - agent_name: <Name of Agent 1>  # Name of agent
          next_step:
            - <Name of Agent 2>

        - agent_name: <Name of Agent 2>          # Loop conditions evaluated here
          next_step:
            - condition: <Some Condition>        # Condition that triggers the loop
              loop:                              # Loop block
                to: [<Name of Agent 1>]          # Must be upstream of this agent
                max_iterations: <integer < 100>  # Required: prevents infinite loops
            - default: true                      # Exactly 1 required
              to: [<Name of Agent 3>]         # Fallback when loops max out or no conditions match

        - agent_name: <Name of Agent 3>