Skip to content

Super Agent

The SuperAgent in the AI Refinery SDK is designed to manage complex, multi-step tasks. It can decompose a complex task into several subtasks, assigning each to the appropriate utility agents (e.g., ResearchAgent, PlanningAgent). For instance, if asked, "Can you write me a brief for our marketing campaign?", the SuperAgent will break down the task into several subtasks, process them sequentially, and then provide the final response. This documentation outlines the workflow and configurations needed to use the SuperAgent.

Workflow Overview

The SuperAgent is invoked by the orchestrator for complex tasks that require multuple steps. Upon invocation, the SuperAgent workflow is structured around four essential components:

  1. Task Checklist: The SuperAgent uses a to-do checklist to manage complex tasks. You can optionally provide a list of preliminary tasks (e.g., gathering relevant information) that the SuperAgent needs to complete before tackling the main task.

    • If you provide this list, it will be used to initialize the to-do checklist. Once these initial tasks are completed, the SuperAgent can focus on the main task.
    • If you do not provide this list, the SuperAgent directly focuses on the main task.

    Once the SuperAgent focuses on the main task, it breaks it down to multiple sub-tasks and adds them to the to-do list to be completed sequentially.

  2. Agent Pool: A SuperAgent has access to a pool of utility agents (e.g., SearchAgent, PlanningAgent, etc.) that it leverages to accomplish each task in the checklist.

  3. Task Routing: For each task in the checklist, the SuperAgent takes one of the following actions:

    • Assigns a utility agent from its pool to complete the task.
    • Requests additional information from the human user if no suitable utility agent is available.
    • Upon completion of all tasks in the checklist, a pre-specified utility agent finalizes the response to the user.

  4. Iterative Task Completion: The tasks in the checklist are completed iteratively. In each iteration, the SuperAgent attempts to complete one task from the checklist. In doing so, if the task is routed to a utility agent, it works on the task and outputs a response. The response is then evaluated, resulting in one of the following outcomes:

    • If the response is satisfactory, the task is marked as complete, and the SuperAgent moves on to the next task in the following iteration.
    • If the response is not satisfactory, the SuperAgent reattempts the task in the next iteration.

    The iterations are continued until all tasks are completed or a pre-defined maximum number of iterations is reached.

Usage

Super agents can be easily integrated into your project by adding the necessary configurations to your project YAML file. Specifically, you can list your super agents under the super_agents attribute in your project's YAML configuration.

Quickstart

To quickly set up a project with a SuperAgent, use the following YAML configuration. In this setup, we have a single super agent which has a SearchAgent and an AuthorAgent in its agent pool. You can add more super agents and utility agents as needed.

super_agents:  # Required if you want to use super agents. Contains a list of super agents.
  - agent_class: SuperAgent # The class must be SuperAgent
    agent_name: Halloween Party Agent # Required. A name that you choose for your super agent.
    agent_description: # Optional. Description of your super agent.
      The Halloween Party Agent is a specialists in elaborating Halloween parties, 
      taking care of all the details, including food, decoration, and music recommendation. Don't call this agent for things that are not Halloween-party-related.
    config: # Required. Configuration of this super agent.
      goal: You'll provide the user with a comprehensive plan for hosting a successful Halloween party. # Required. A high level goal of your super agent.
      steps: # Required. The steps your super agent should follow to complete the task. This is given the the super agent as a guideline.
        - Obtain food recommendation
        - Obtain music recommendation
        - Obtain decoration recommendation
        - Create a guide to help the user plan the party
      agent_list: # Required. The list of agents to be added in the agent pool. Each agent listed here must be configured under `utility_agents` (see below).
        - agent_name: Recommender Agent 
        - agent_name: Author Agent
      exit: Author Agent # Required. This agent generates the final output once all tasks in the checklist is completed. Must be one of the agents in the agent pool i.e., `agent_list` (see below).
      max_turns: 10 # Required. Maximum number iterations to complete the tasks in the to-do checklist.

utility_agents:
# The utility agents in your project. Visit the Agent Marketplace to learn more about how to configure each utility agent.
  - agent_class: SearchAgent
    agent_name: Recommender Agent
    agent_description: The Recommender Agent is an expert in searching the Web for cool item recommendations for a party. This includes food, decorations, songs, costumes, etc.

  - agent_class: AuthorAgent
    agent_name: Author Agent
    agent_description: This AI agent is specialized into creating a guide based on available chat conversations.
    config:
      memory_attribute_key: "plan"
      leading_questions:
        - question: Food and drink menu
          prompt: Provide an itemized list of the food that will be served in the party and also a recommendation of where to get them from
        - question: Decoration shopping list
          prompt: Describe the decoration recommendation with enough details for the organizer to purchase the items
        - question: Party soundtrack
          prompt: This section should contain a list of sounds to be played during the party along with a time suggestion


orchestrator: # Required
  agent_list: # Required. List of uitlity agents that orchestrator has access to. The super agents do not need to be added here. They are added automatically
    - agent_name: "Recommender Agent" 
    - agent_name: "Author Agent"

Template YAML Configuration of SuperAgent

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

agent_class: SuperAgent # The class must be SuperAgent
agent_name: <A name that you choose for your super agent.> # Required. 
agent_description: <Description of your super agent.> # Optional.

config: # Required. Configuration of this super agent.
  max_turns: <Maximum number iterations to complete the tasks in the checklist.> # Required. 
  goal: <A high level goal of your super agent.> # Required
  steps: <The steps that should to be followed by the super agent.> # Required
  exit: <The name of the exit agent> # This agent generates the final output once all tasks in the checklist is completed. Must be one of the agents in the agent pool i.e., `agent_list` (see below).

  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 project YAML file.
    - agent_name: <Name of agent 1>  # Requried. 
      requirements: # Optional. If provided, these will be the preliminary tasks that must be completed (i.e., the pre-specified todo list) before the super agent focuses on the main task. 
        - <Task 1>
        - <Task 2>

    - agent_name: <Name of agent 2>  # Required. 
      requirements: # Optional. If provided, these will be the preliminary tasks that must be completed (i.e., the pre-specified todo list) before the super agent focuses on the main task.
        - <Task 1>
        - <Task 2>
        - <Task 3>

  llm_config:
  # Optional. Customized llm config (if you want the super agent to use a different LLM than the on in your base config)
    model: <model_name>