Skip to content

utils_overview.md

Latest commit

 

History

History
88 lines (59 loc) · 3.74 KB

utils_overview.md

File metadata and controls

88 lines (59 loc) · 3.74 KB
Raw

Utilities Overview

Introduction

This is an advanced utilities reference.

Use it after the beginner Agent and Cog path, when you need logger, parsing, prompt handling, Discord, or compatibility helpers directly.

In AgentForge, utility classes make building and extending agents easier. Each utility focuses on a specific aspect of agent functionality—handling everything from logging, prompt rendering, and parsing structured data and Discord integration.

Available Utilities

The core utility modules (found under agentforge/utils/) are summarized below. For more details on each, see the linked individual guides.

1. Discord Client

  • Guide: Discord Guide
  • Description: Connects agents to Discord, enabling bots to send/receive messages, post embeds, manage threads, and more.
  • Use Cases:
    • Building real-time chat interfaces for agents on Discord servers.
    • Enabling interactive command-based bots or multi-agent discussions.

2. Logger

  • Guide: Logger Guide
  • Description: A robust logging system to track agent actions, debug processes, and store audit trails. Supports multiple log files and configurable levels.
  • Use Cases:
    • Debugging agent behaviors.
    • Monitoring system health, errors, and warnings.
    • Maintaining detailed logs for compliance or review.

3. Parsing

  • Guide: ParsingUtils Guide
  • Description: Methods for extracting code blocks and parsing common data formats (YAML, JSON, XML, INI, CSV, Markdown). Useful for agents that embed structured information in outputs or require configuration data from text.
  • Use Cases:
    • Parsing agent responses that include code-fenced JSON or YAML.
    • Converting user-supplied text into Python data structures.

4. Prompt Handling

  • Guide: PromptHandling Guide
  • Description: Manages the rendering and validation of prompt templates. Substitutes placeholders ({var_name}) with actual data, checks formatting, and ensures non-empty results.
  • Use Cases:
    • Dynamically generating prompts based on user input or agent context.
    • Maintaining multi-section prompts (like system vs. user) without manual string concatenation.
    • Overriding default prompt rendering logic for advanced customization.

5. Tool Utils

ToolUtils supports the legacy dynamic tool execution surface. Use it only with trusted project-owned tool definitions.

  • Guide: ToolUtils Guide
  • Description: Facilitates dynamic importing and execution of tool modules or built-in functions, plus formatting those tools for display. Enables flexible, pluggable functionality so agents can call new or external code.
  • Use Cases:
    • Letting agents choose from multiple "actions" at runtime, referencing user-defined modules.
    • Dynamically expanding an agent's capabilities without redeploying the entire application.

Notes

  1. Modularity
    Each utility is standalone—import only what you need, where you need it.
  2. Extendibility
    If you have specialized requirements (e.g., advanced prompt placeholders), you can override or subclass these utilities.
  3. Documentation
    Each utility is documented in its own guide. Refer to those guides for usage details.

Conclusion

These AgentForge utilities provide foundational functionality to handle everything from logs and prompts to Discord interactions and tool execution. By combining them, you can create more intelligent, modular, and maintainable agents that adapt to various scenarios.

Need Help?