Skip to content

Alchemist Agent

The AlchemistAgent is a built-in utility agent in the AI Refinery SDK designed to generate valid YAML configurations for AIR SDK projects from natural language requests. It acts as an intelligent assistant that understands your project requirements and automatically produces the configuration needed to build super agents with the appropriate utility agents.

Example natural language queries:

  • “I need an agent to help with email draft generation”
  • “I need an agent that can search the web for current events and news”

Workflow Overview

The workflow of AlchemistAgent comprises two main operational modes:

1. YAML Generation Mode (Default)

This is the primary mode where the agent generates complete, validated YAML configurations:

  • SDK Documentation Retrieval: Uses an LLMs.txt retriever to search the AI Refinery SDK documentation based on the query.

  • YAML Generation: Uses the gathered information to generate a YAML configuration.

  • Validation and Fixing: Validates and fixes (if there are errors) the generated YAML for up to a configurable number of attempts.

2. Ideation Mode (Optional)

When enabled via only_ideation: true, the agent focuses on generating architectural ideas rather than code:

  • Agent and Tutorial Identification: Identifies pages with agents (e.g., SearchAgent, AuthorAgent) and tutorials that are most relevant to the query.

  • Page Filtering: Filters identified pages based on a configurable usefulness threshold.

  • Page Analysis: Summarizes key points, steps, examples, or explanations relevant to the query.

  • Idea Generation: Generates three distinct architectural ideas for the query.

  • Sentence Descriptions: Converts ideas into clear, self-contained sentences.

By following these workflows, the AlchemistAgent efficiently produces either well-structured YAML configurations or architectural ideas tailored to your requirements.

Usage

As a built-in utility agent in the AI Refinery SDK, AlchemistAgent can be easily integrated into your project by adding the necessary configurations to your project YAML file. Specifically, ensure the following configurations are included:

  • Add a utility agent with agent_class: AlchemistAgent under utility_agents.
  • Ensure the agent_name you chose for your AlchemistAgent is listed in the agent_list under orchestrator or a super agent.

Quickstart

To quickly set up a project with an AlchemistAgent, use the following YAML configuration. You can customize the settings as needed. 

utility_agents:
  - agent_class: AlchemistAgent
    agent_name: "YAML Config Generator"  # Required. User-defined name for the Alchemist agent. Must be referenced iin the orchestrator.

orchestrator:
  agent_list:
    - agent_name: "YAML Config Generator"  # Name of the AlchemistAgent defined above.

Example Usage:

After setting up the configuration, you can interact with the Alchemist Agent by sending queries like:

  • Create a SuperAgent that can search the web and write a report
  • I need a configuration for analyzing customer feedback and generating summaries
  • Build a SuperAgent that can perform research and store findings in a database

The agent will analyze the SDK documentation and generate a complete, validated YAML configuration that you can use directly.

Template YAML Configuration of AlchemistAgent

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

agent_class: AlchemistAgent
agent_name: <name of the agent>  # Required. A descriptive name for your alchemist agent.
config:
  sdk_home_page: <URL>
  # Optional. Home page URL of the AIR SDK documentation for retrieval.
  # Defaults to "https://sdk.airefinery.accenture.com".

  page_usefulness_threshold: <0-5>
  # Optional. Minimum usefulness score (0-5) required for a page to be included.
  # Pages scoring below this value are ignored.
  # Default: 4

  max_validation_attempts: <number>
  # Optional. Maximum attempts to validate and fix the generated YAML.
  # Must be at least 1. Defaults to 5.

  only_ideation: <true or false>
  # Optional. If true, generate architectural ideas instead of YAML configuration.
  # Defaults to false.

  llm_config:
    # Optional. Custom LLM configuration for the alchemist agent.
    model: <model_name>
    temperature: <0.0-1.0>