Skip to content

Flow Super Agent

The FlowSuperAgent in the AI Refinery SDK is designed to orchestrate complex workflows composed of multiple utility agents with defined dependencies. The FlowSuperAgent allows users to define nodes (utility 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 utility agents (e.g., SearchAgent, AuthorAgent, etc.) 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 utility agents to schedule the task execution.

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

Execution Flow

Without Triage

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 and their descendants.
  • Agents are skipped only 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.

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 as agents in the utility_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.

Quickstart

Without Triage

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` 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 utility agents in the workflow graph
        - agent_name: 'Agent 1'            # Name of a utility 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.

Template YAML Configuration of FlowSuperAgent

Without Triage

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

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
        - agent_name: <Name of Agent 1>  # Name of agent from utility_agents
          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