Creating Custom Agents

Forge is built to be modular. That means you’re not limited to the default agents like TokenAgent or WalletAgent. If you have a specific use case, behavior pattern, or data stream you want to analyze, you can build your own agent from scratch.

This page covers how custom agents work, how to create them, and how they plug into the existing Forge ecosystem.


What Is a Custom Agent?

A custom agent is a user-defined module that listens for events, pulls on-chain data, and generates a response using its own logic and prompt structure.

Each agent has:

  • A name and purpose

  • Trigger conditions (what it listens for)

  • A context builder (how it fetches data)

  • A prompt template (how it speaks)

  • An output method (chat, chart, modal, etc.)

You can use this to create tools like:

  • A “WhaleAgent” that watches wallets moving 1000+ SOL

  • A “RepeatDeployerAgent” that flags wallets launching more than 3 tokens in 24 hours

  • A “KOLJoinAgent” that alerts when deployers join high-signal Telegram groups


When to Build One

Create a custom agent if:

  • You’re repeating the same query pattern often

  • You have unique data inputs no other agent is using

  • You want a specific style of reply or workflow

  • You’re working on private forks of Forge for research or trading

Agents can be used solo or combined into multi-agent chains for deeper logic.

Trigger Conditions

Agents can be triggered by:

  • Token creation

  • Wallet movement

  • LP changes

  • Time-based intervals

  • External API feeds (Telegram, Twitter, etc.)

You define the logic that determines when your agent should wake up and do its job.


Context Builder

This is the part where the agent gathers the data it needs. You can pull from:

  • Forge’s real-time index

  • Historical data

  • External APIs

  • Custom tracking databases

The better your context builder, the more accurate and useful the agent’s reply will be.


Prompt Template

Just like core agents, you define how your agent speaks. You can:

  • Set tone and voice

  • Include structured facts

  • Limit to key points or go deep

  • Output in markdown, plain text, or JSON

You control the final message structure.


Output Options

Agents can return:

  • A single chat message

  • A detailed modal (like a token breakdown card)

  • A chart or stat block

  • A trigger to other agents

You can even set up cascading agents — one agent’s output becomes the input for another.


Deploying the Agent

Once your agent is written:

  1. Drop it into the agents/ folder

  2. Add it to the registry in the main agent loader

  3. Restart the Forge backend

It will now activate automatically when its conditions are met, and show up in agent logs just like any core agent.


Testing and Debugging

During testing, you can:

  • Manually simulate events to trigger the agent

  • View agent logs in the console or UI

  • Compare outputs with expected behavior

  • Refine thresholds or context logic

Forge is built to make this fast and iterative.

Last updated