Skip to content

Automatically Generate YAML Configurations with Alchemist Agent

Overview

The AlchemistAgent transforms natural language requests into valid YAML configurations for AI Refinery SDK projects. Instead of manually writing complex configurations, describe what you need in plain English and let the Alchemist Agent generate the complete setup.

Goals

This tutorial will show you how to:

  • Set up an Alchemist Agent in your project
  • Use the agent to generate YAML configurations from natural language
  • Create a Distiller Client that runs the Alchemist Agent in interactive mode
  • Generate production-ready configurations for complex agent workflows

Alchemist Workflow

The Alchemist Agent operates in two modes:

YAML Generation Mode (Default)

This is the primary mode for automatically creating complete project configurations:

  1. Query Analysis - The agent analyzes your natural language request to understand the requirements
  2. Documentation Search - Uses an LLMs.txt retriever to search AI Refinery SDK documentation for relevant agents and configurations
  3. YAML Generation - Synthesizes the gathered information into a complete YAML configuration
  4. Validation - Automatically validates the generated YAML and fixes any errors
  5. Output - Returns a production-ready YAML configuration you can use directly

Ideation Mode (Optional)

When you need architectural guidance rather than immediate code, enable ideation mode with only_ideation: true:

  1. Agent Discovery - Identifies relevant utility agents from the SDK documentation
  2. Tutorial Analysis - Finds tutorials and examples that match your use case
  3. Architecture Generation - Creates multiple architectural approaches for your requirement
  4. Recommendation - Provides clear descriptions of each approach with trade-offs

Usage

Steps

1. Configuration File

Create a YAML file (e.g., config.yaml) with the Alchemist Agent configuration. This example demonstrates using two AlchemistAgents in a SuperAgent workflow - one for ideation and one for generating the actual YAML configuration:

# Routes user queries to agents
orchestrator:
  agent_list:
    - agent_name: "Alchemist Super Agent"
  enable_routing: false  # Disable routing - we have only one agent
  decompose: true  # Allow breaking down complex queries

# Orchestrates multiple agents to accomplish tasks
super_agents:
  - agent_class: SuperAgent
    agent_name: "Alchemist Super Agent"
    agent_description: "This super agent uses multiple utility agents to create agent recipes and generate artifacts for the AIR-SDK platform."
    config:
      goal: "Create YAML config files for agents that can solve the user's query using the AIR-SDK platform."

      agent_list:
        - agent_name: "Agent Recipe Maker"  # Generates ideas
        - agent_name: "Artifact Generator"  # Produces YAML

      steps:
        - Ideate agent recipes based on the user's query using the "Agent Recipe Maker" agent.
        - Create YAML config for idea 1 using the "Artifact Generator" agent.

      exit: "Artifact Generator"  # Final agent in workflow
      max_turns: 5  # Maximum number of agent calls to complete the task

# Specialized agents for specific tasks
utility_agents:
  # Generates architectural ideas (ideation mode)
  - agent_class: AlchemistAgent
    agent_name: "Agent Recipe Maker"
    agent_description: "This agent creates agent recipes for the AIR-SDK platform to solve user queries."
    config:
      sdk_home_page: <URL> # Optional. SDK documentation URL (default: https://sdk.airefinery.accenture.com)
      page_usefulness_threshold: 4  # Min relevance score (0-5)
      only_ideation: true  # Generate ideas instead of code

  # Generates actual YAML configurations
  - agent_class: AlchemistAgent
    agent_name: "Artifact Generator"
    agent_description: "This agent creates Super Agent YAML Config based on user queries using the AIR-SDK"
    config:
      sdk_home_page: <URL>  # Optional. SDK documentation URL (default: https://sdk.airefinery.accenture.com)
      # only_ideation defaults to false - this agent generates code

2. Python File

Create a Python file (e.g., alchemist_demo.py) that initializes the Alchemist Agent and runs it in interactive mode:

import os

from air import DistillerClient


def interactive():
    """
    Initialize and run the Alchemist Agent in interactive mode.
    """
    # Initialize the client with environment variables
    distiller_client = DistillerClient(
        api_key=str(os.getenv("API_KEY"))  # Your API key for authentication
    )

    # Create project from config file
    distiller_client.create_project(
        config_path="config.yaml",  # Path to your YAML configuration
        project="example"  # Project name
    )

    # Start interactive session - type queries directly in terminal
    distiller_client.interactive(
        project="example",  # Project name (must match above)
        uuid="test_user",  # Unique session identifier
    )


if __name__ == "__main__":
    print("\nInteractive Mode")
    interactive()

Sample Queries

Query:

I'm trying to stay on top of my classes this semester — is there a way to set up an agent that helps me plan out assignments and deadlines? What would the config for something like that look like? I don't want to use custom agent and custom function.

Sample Output

Here's an example of what the Alchemist Super Agent generates:

%%% AGENT Agent Recipe Maker %%%

- **idea 1:** To help a student plan semester assignments and deadlines, we can create an AIR SDK **SuperAgent** that uses a **PlanningAgent** to generate realistic, time‑boxed schedules, a **VariableMemoryAgent** to store the student’s course list, assignment titles, due dates and exam dates, and optionally a **SearchAgent** to retrieve public university calendars, enabling the collection of all relevant dates, persistent memory of the data, and automatic production of a week‑by‑week markdown or iCal‑compatible schedule that updates whenever the stored information changes.  

- **idea 2:** To assist a student in organizing semester work without custom code, we can build an AIR SDK **FlowSuperAgent** that orchestrates a **HumanAgent** (in Structure Mode) to gather structured course and assignment information, a **PlanningAgent** to transform that data into a conflict‑free chronological plan, and an **AuthorAgent** to polish the plan into a user‑friendly markdown/HTML report, storing the final plan in session memory for follow‑up queries such as “What’s due next week?”.  

- **idea 3:** To provide a flexible student assistant that can perform on‑the‑fly date calculations, we can assemble an AIR SDK **SuperAgent** with a **ToolUseAgent** (using the built‑in `calculate_expression` tool) for date arithmetic, a **PlanningAgent** to build and refresh the semester calendar based on user‑provided assignments and the computed dates, and a **VariableMemoryAgent** to keep the full assignment list and any modifications, allowing the agent to parse requests, update stored data, regenerate up‑to‑date weekly plans, and answer dynamic queries like “How many days left for the CS101 project?”.


%%% AGENT Alchemist Super Agent %%%
Please generate a Super Agent YAML configuration for **idea 1** described by the Agent Recipe Maker: a student assistant that helps plan assignments and deadlines for a semester using only built‑in AIR‑SDK capabilities. The agent should include a PlanningAgent, VariableMemoryAgent, and optionally a SearchAgent, with clear descriptions of purpose, required tools, and interaction flow.


%%% AGENT Artifact Generator %%%
⏳ Starting YAML artifact generation...


%%% AGENT Artifact Generator %%%
📚 Gathering relevant SDK documentation...


%%% AGENT Artifact Generator %%%
✓ Retrieved documentation from 9 relevant pages


%%% AGENT Artifact Generator %%%
⚙️ Generating YAML configuration...


%%% AGENT Artifact Generator %%%
🛠️ Validating and fixing YAML configuration...


%%% AGENT Artifact Generator %%%

super_agents:
  - agent_class: SuperAgent
    agent_name: StudentPlannerOrchestrator
    agent_description: >-
      Coordinates planning, memory storage, and optional web search to create a
      semester schedule for a student.
    config:
      max_turns: 15
      goal: >-
        Generate a complete week‑by‑week assignment and deadline plan for the
        student's semester.
      steps:
        - "Collect course list and assignment details from the user."
        - "If needed, retrieve external calendar or syllabus info via Search Agent."
        - "Generate the semester schedule using Planning Agent."
        - "Return the finalized schedule to the user."
      agent_list:
        - agent_name: "Planning Agent"
        - agent_name: "Search Agent"
      exit: "Planning Agent"

utility_agents:
  - agent_class: PlanningAgent
    agent_name: "Planning Agent"
    agent_description: |
      Creates a chronological plan of assignments, exams, and study blocks based
      on user input and stored data. The result is saved to the variable memory
      module `semester_memory`.
    config:
      output_style: markdown
      contexts:
        - date
        - relevant_chat_history
        - env_variable
      self_reflection_config:
        self_reflection: true
        max_attempts: 3
        response_selection_mode: best

  - agent_class: SearchAgent
    agent_name: "Search Agent"
    agent_description: |
      (Optional) Looks up university calendars, course syllabi, and public holidays
      to enrich the planning data.
    config:
      max_results: 5
      output_style: markdown

memory_config:
  memory_modules:
    - memory_name: semester_memory
      memory_class: VariableMemoryModule
      kwargs:
        variables:
          semester_plan: null          # will hold the generated schedule
          completed_tasks: []          # optional tracking of finished items

orchestrator:
  agent_list:
    - agent_name: StudentPlannerOrchestrator

Query:

Create a simple calculator agent that can perform basic math operations.

Sample Output:

%%% AGENT Agent Recipe Maker %%%

idea 1: To parse natural‑language arithmetic requests and return the computed answer, we can create an AIR SDK SuperAgent that incorporates a ToolUseAgent (and optionally an InterpreterAgent) to detect the expression, invoke the built‑in `calculate_expression` tool, and forward the numeric (or friendly‑sentence) result to the user.  

idea 2: To deliver deterministic calculator results, we can create an AIR SDK SuperAgent that routes the user query to a single UtilityAgent driven by a fixed magic‑prompt that tells the LLM to behave as a calculator and return only the numeric result, then returns that result unchanged to the caller.  

idea 3: To build a modular and extensible calculator, we can create an AIR SDK FlowSuperAgent that first calls a PlanningAgent to classify the operation and extract the two operands, then dispatches the data to the appropriate UtilityAgent (Adder, Subtractor, Multiplier, or Divider) for computation, and finally (optionally) passes the outcome through a Formatter step before responding.


%%% AGENT Alchemist Super Agent %%%
Artifact Generator, please create a Super Agent YAML configuration for the simple calculator described in idea 1 from the Agent Recipe Maker:

- The agent should parse natural‑language arithmetic requests (addition, subtraction, multiplication, division).
- It should detect the arithmetic expression, invoke the built‑in `calculate_expression` tool, and return the computed numeric (or friendly‑sentence) result to the user.
- Use the AIR‑SDK platform components (ToolUseAgent, optional InterpreterAgent) as appropriate.

Provide the complete YAML config ready for deployment.


%%% AGENT Artifact Generator %%%
⏳ Starting YAML artifact generation...


%%% AGENT Artifact Generator %%%
📚 Gathering relevant SDK documentation...


%%% AGENT Artifact Generator %%%
✓ Retrieved documentation from 8 relevant pages


%%% AGENT Artifact Generator %%%
⚙️ Generating YAML configuration...


%%% AGENT Artifact Generator %%%
🛠️ Validating and fixing YAML configuration...


%%% AGENT Artifact Generator %%%

super_agents:
  - agent_class: SuperAgent
    agent_name: SimpleCalculatorSuperAgent
    agent_description: |
      Parses natural‑language arithmetic requests (add, subtract, multiply,
      divide), extracts the expression, calls the built‑in `calculate_expression`
      tool, and returns the result (numeric or a friendly sentence) to the user.
    config:
      goal: >-
        Provide the correct result for any simple arithmetic request expressed in
        natural language.
      steps:
        - "Detect whether the user query contains an arithmetic request."
        - "Extract the pure arithmetic expression (e.g., \"12 / 4\")."
        - "Invoke the `calculate_expression` tool with the extracted expression."
        - "If a friendly reply is desired, format the numeric result into a sentence."
        - "Return the final answer to the user."
      agent_list:
        - agent_name: CalculatorToolAgent
      exit: CalculatorToolAgent
      max_turns: 5

utility_agents:
  - agent_class: ToolUseAgent
    agent_name: CalculatorToolAgent
    agent_description: |
      Executes arithmetic expressions using the built‑in `calculate_expression` tool.
    config:
      wait_time: 30
      enable_interpreter: true          # formats the numeric result into a friendly sentence
      builtin_tools:
        - "calculate_expression"
      custom_tools: []

orchestrator:
  agent_list:
    - agent_name: SimpleCalculatorSuperAgent