Skip to main content

Defining Agents with YAML

Agent Forge offers a powerful and convenient way to define and configure your agents using YAML files. This approach promotes separation of concerns, making your agent definitions easy to read, manage, and modify without changing your core application code.

Why Use YAML for Agent Configuration?​

  • Clarity: Agent characteristics (role, objectives, model, tools) are laid out in a human-readable format.
  • Maintainability: Easily update agent personas or switch LLM models by editing a text file.
  • Reusability: Define agent templates that can be loaded and used in various parts of your application or by different teams.
  • Non-Developer Friendly: Allows team members without deep coding knowledge to understand and potentially adjust agent behaviors.

Structure of an Agent YAML File​

A typical agent YAML file includes the following fields:

# Example: research-agent.yaml
name: ResearchAgent
role: Research Assistant
description: An agent that helps with online research
objective: Find accurate and relevant information based on user queries
model: gpt-4 # Or your preferred model, e.g., gpt-3.5-turbo, claude-3-opus-20240229
temperature: 0.7 # Controls the creativity/randomness of the LLM
# max_tokens: 2048 # Optional: maximum number of tokens the LLM should generate
tools:
  - name: WebSearch
    description: Search the web for information # This description might be used by the agent to understand the tool
  # - name: MyCustomTool
  #   description: A custom tool you have defined and registered

Key Fields Explained:

  • name: A unique identifier for your agent.
  • role: Defines the primary function or persona of the agent (e.g., "Financial Analyst", "Customer Support Bot"). This often forms part of the system prompt sent to the LLM.
  • description: A more detailed explanation of what the agent does.
  • objective: The specific goal or task the agent is designed to achieve.
  • model: Specifies the LLM to be used (e.g., gpt-4, gpt-3.5-turbo). Agent Forge, through its integration with token.js, supports a wide range of models.
  • temperature: A parameter influencing the LLM's output. Higher values (e.g., 0.7-1.0) make output more random/creative, while lower values (e.g., 0.1-0.3) make it more focused and deterministic.
  • max_tokens (optional): You can often specify the maximum number of tokens the LLM should generate in its response.
  • tools: A list of tools the agent is permitted to use. Each tool entry typically includes:
    • name: The registered name of the tool (e.g., WebSearch, MyCustomTool).
    • description: A description that helps the agent (and potentially the LLM) understand what the tool does and when to use it.

Loading an Agent from YAML​

Agent Forge provides a straightforward way to load these YAML definitions into usable Agent objects within your code. The AgentForge instance typically has a method for this.

import { AgentForge, LLM, Agent } from "agent-forge";
import dotenv from 'dotenv';

dotenv.config();

async function loadAndUseAgent() {
  const apiKey = process.env.OPENAI_API_KEY;
  if (!apiKey) {
    console.error("OPENAI_API_KEY is not set. Please set it in your .env file.");
    return;
  }

  const llmProvider = new LLM("openai", { apiKey });
  const forge = new AgentForge(llmProvider);

  // Assuming 'research-agent.yaml' exists in the current directory or a specified path
  // and is a valid agent definition.
  try {
    const agent: Agent = await forge.loadAgent("./research-agent.yaml");
    // console.log(`Agent '${agent.name}' loaded successfully.`);
    // console.log(`Role: ${agent.role}, Objective: ${agent.objective}`);

    // Now you can run the agent, for example:
    // const result = await agent.run("What is the capital of France?");
    // console.log("\\nAgent Result:", result);

  } catch (error) {
    console.error("Failed to load agent:", error);
  }
}

// To run this example:
// loadAndUseAgent();

Key steps:

  1. Initialize your LLM provider and AgentForge instance.
  2. Use the forge.loadAgent("path/to/your/agent.yaml") method.
    • Agent Forge parses the YAML file.
    • It instantiates an Agent object, configured with the properties from the YAML.
    • The default LLM provider from the AgentForge instance is typically assigned to the loaded agent unless overridden in the YAML (behavior might vary based on framework specifics).
    • Tools listed in the YAML are associated with the agent. These tools must be registered with the AgentForge instance (e.g., forge.registerTool(new WebSearchTool())) or made available through other mechanisms like the Model Context Protocol (MCP) for the agent to use them effectively.

Using YAML definitions is a cornerstone of Agent Forge, enabling robust and flexible agent-based application development.

Next Steps​