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:
Drop it into the
agents/folderAdd it to the registry in the main agent loader
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