Custom Agents

​

Overview

​

Use Cases

• Quality Control (QC): Auditing campaign drafts for errors or inconsistencies.
• Localization: Executing bulk language translations.
• Data Analysis: Acting as an automated marketing analyst to process campaign data.
• Campaign Drafting: Generating new campaign drafts based on creative briefs.
• Performance Auditing: Reviewing past campaign metrics to surface top and bottom performers.

​

Capabilities of Custom Agents

• Automate Workflows: Execute routine, cross-campaign tasks (for example, QA, drafting, localization) to eliminate manual effort.
• Native Integration: Process live campaign and segment data directly within MoEngage, bypassing third-party AI security risks.
• Plain-Text Configuration: Define agent behaviors using plain text. Start from a predefined template, or use the Merlin Agent Builder for custom use cases.
• Secure Execution: Enforce strict read/write boundaries. Write-enabled agents are restricted to drafting and cannot auto-publish campaigns.
• Workspace Collaboration: Share agent configurations publicly with your team. Run history on a public agent is visible workspace-wide; only continuing a task you didn’t start is restricted.
• Asynchronous Execution: Run complex, data-heavy tasks in the background without keeping the active task window open.
• Persistent Tasks: Pause and resume a workflow at any time. Each task retains the full context of prior prompts, tool outputs, and attached files, and an agent also keeps facts between runs in its own and your workspace’s memory stores. Refer to Agent Memory.
• Scheduled Execution: Set an agent to run automatically on a recurring schedule (daily, weekly, or monthly) and receive an email when a scheduled run finishes or fails. The email gives the run’s outcome, Task ID, run date, duration, and next run time, and you turn it off with the Email toggle on the agent. Refer to Set a Trigger.
• Summary Emails: Request a summary email of what a task produced, with up to 5 attachments, so that an unattended task can report its outcome to your inbox. Refer to Send Summary Emails.
• Flexible Model Tiers: Select a model capability tier (Fast, Balanced, or Expert) matching the complexity of each agent’s task. Refer to Choose a Mode.
• Multi-Agent Delegation: Attach existing agents to one coordinator agent as sub-agents, so a single task distributes a multi-step workflow across specialists and consolidates the result. Refer to Build Multi-Agent Workflows.
• External Applications: Connect applications outside MoEngage so the agents you run work with them alongside your campaign data in a single run. The Connectors page lists the applications available to your workspace. Refer to Connect External Apps to Custom Agents and, for a worked example, Import Figma Designs into MoEngage with Custom Agents.
• Creative Generation: Generate campaign creatives from a text prompt during a run, and review them using a separate image analysis tool. Refer to Generate and Analyze Images.

​

Agent Scope

​

Limitations

​

Configuration Limits

​

Behavioral Limits

• Only the creator manages an agent. Editing, publishing, pausing, resuming, deleting, and scheduling are restricted to the user who created the agent. A colleague runs or duplicates a public agent instead.
• Deleting an agent is permanent. MoEngage provides no recovery flow. To retire an agent you may need later, turn the Private toggle on rather than deleting the agent.
• A scheduled run uses a standard prompt. MoEngage sends the agent a fixed prompt when a schedule fires, and the prompt cannot be customized.
• A scheduled run uses no memory. The run neither reads what an earlier run stored nor stores anything for a later run. Refer to Agent Memory.
• Test runs are not a sandbox. A test run reads and writes real workspace data, and an agent with write tools makes real changes during a test.
• The description is generated. MoEngage writes the agent’s description from your instructions, and provides no manual description editor.

​

Best Practices

• Give each agent one well-defined job. An agent performs most reliably when its instructions cover a single task. For a workflow with several stages, attach specialists to a coordinator agent rather than building one agent that does everything. Refer to Build Multi-Agent Workflows.
• Assign only the tools the agent needs. Granting unnecessary tools increases the risk of unintended actions, and write tools let the agent change real workspace data.
• Write instructions with exact parameters. Precise instructions produce consistent output, so state the data to fetch, the window to cover, and the format to return instead of a general direction such as “analyze data”.
• Review what Merlin AI drafts for you. The Agent Builder’s assistant generates instructions and tool selections that you confirm before publishing.
• Test before you publish, and treat the test as live. A test run verifies that the agent reads its instructions correctly and calls the tools you expect.
• Duplicate a colleague’s agent rather than asking them to change it. A duplicate is an independent Draft that you own and edit.
• Ask a scheduled agent to report back. Adding a request for a summary email to the agent’s instructions sends each run’s outcome to your inbox. Refer to Send Summary Emails.

​

The All Custom Agents Page

• Hover over Merlin AI in the left menu and click Custom Agents.
• Click View all beside Custom agents in the left pane of the Merlin AI Agents hub.

​

Page Interface Elements

• Search by usecase: Find an agent by its name.
• My draft agents: Show your own agents that are still under construction and not yet published.
• My live agents: Show your own agents that are published and ready to run.
• More filters: The filter icon opens a panel holding Triggers, with Manual and Scheduled, and Visibility, with Public and Private. Click Apply to apply your selection, or Reset all to clear the panel.
• Sort: The sort icon orders the cards by Newest first, Oldest first, or Most runs.
• Agent Cards: Each card shows the agent’s icon, name, and a short description, which reads No description generated when the agent has none. A live agent also shows its run count and, once it has run, how long ago it last ran. A draft agent shows Draft in place of the run details.
• + New custom agent: Opens the template gallery, where you pick a template or select Create from scratch to open the builder.

​

Create a Custom Agent

​

Open the Template Gallery

1. On the left navigation menu in the MoEngage dashboard, go to Merlin AI > Custom Agents.
2. On the Custom agents page, click + New custom agent. MoEngage opens the template gallery.

​

Kickstart Using Templates

• Segmentation Assistant
• Push Campaign Drafter
• Analytics Agent
• Template Marketing Analyst
• Email Campaign Creator
• Campaign QC Agent
• Jinja Generator (Personalization Writer)
• Template_Language Translation (Bulk)
• Daily Segment Report Generator
• Segment Discovery & Recommendation
• Channel Funnel Reporter
• Day/Channel Report
• Daily Campaign Calendar Orchestrator
• Failure Reports Aggregator

1. Select a template from the gallery. The detail panel describes what the template does and shows a sample conversation.
2. Click Try now. MoEngage prompts you to name the agent.
3. Name the agent and confirm. MoEngage creates the agent, publishes the agent, and opens the Run panel so you can start using the agent immediately.

​

Create from Scratch

​

Configure Your Custom Agent

• Name the agent: Click the agent name field located at the top of the configuration screen. By default, this field displays Untitled or the name of your selected template. Give the agent a clear, action-oriented name that states its purpose to your team (for example, Pre-send Push QA or EMEA Email Translator). The agent name supports up to 120 characters.
• Agent description: MoEngage generates the agent’s description automatically from your instructions, using the AI builder or the selected template. The description supports up to 500 characters. MoEngage does not provide a manual description editor. The builder shows the agent’s name and the Private toggle above the right panel, and Publish at the top right. The builder consists of the following components:
  
• Agent builder: An AI chat interface on the left that drafts instructions and recommends tools from your plain-text prompts.
• Configuration tab: The right panel, where you assign tools, set a trigger, choose an agent mode, attach sub-agents and reference files, and write the agent’s instructions in the Instructions editor.
• Test agent tab: The tab beside Configuration, where you run the agent before you publish it. Refer to Test Agent.

​

Define Agent Parameters

• Configure your Agent’s Instructions
• Assign Tools
• Generate and Analyze Images
• Assign Sub-Agents
• Select an Agent Mode
• Set a Trigger
• Attach Files
• Set Visibility
• Configure Notifications

​

Configure Your Agent’s Instructions

• By Template: If you started with a template, the editor is pre-filled with a tested playbook. You can edit it or leave it as is.
• By Merlin AI Agent Builder: Use the chat assistant to automatically draft the instructions and assign tools based on a plain-English prompt.
• By Hand: Write or edit the instructions manually directly within the text editor.

​

Core Components of a Well-Structured Agent

• Role: Who the agent is and its specific area of expertise.
• Objective and Workflow: The primary goal of the task and a numbered, ordered list of steps the agent must follow to complete the job.
• Rules and Guardrails: Strict operational boundaries, detailing exactly what the agent must always do and what it must never do.
• Output Format: The exact structure the agent should use when returning its final response (for example, a formatted table, a bulleted list, or a summarized report).

​

Example Instruction Structure

## Role
You are a [description] agent that specializes in [core capability].

## Objective
In each run, you will [state the primary goal].

## Rules
- Always [mandatory action].
- Never [restricted action].

## Steps
1. [First action]
2. [Second action]
3. [Third action]

## Output format
[Describe the expected output structure, e.g., "Return the findings in a two-column table."]

​

Use the Merlin AI Agent Builder (Optional)

1. Provide a Prompt: In the text input field at the bottom of the left panel, type a sentence or two describing what you want your agent to accomplish using plain English.
   You can attach reference files directly to your message to help Merlin AI generate the initial instructions (for example, uploading an example output format you want the agent to mimic). However, these files are not persisted. Only the resulting text instructions are saved to the agent’s core knowledge for future tasks.
2. Generate Draft: Submit your prompt. Merlin AI processes the request and populates the Configuration tab with drafted instructions and recommended tools.
3. Review and Refine: Manually edit the generated instructions and tool selections to ensure they align perfectly with your exact use case.

• Give me ideas to build
• Role of instructions and tools
• Explore capabilities
• How to proceed?

​

Assign Tools

​

Add and Remove Tools

1. Click the + icon next to the Tools heading in the Configuration tab to open the tool picker dialog box.
2. Uncheck any tool the agent doesn’t need, or select the checkbox next to a tool to add it (for example, Read campaign data or Read campaign analytics).

• Use the Search to select bar at the top of the dialog to quickly locate specific tools.
• To remove every tool at once, click Clear all.

3. Click Apply to confirm and save your tool assignments. After selection, tools appear as individual chips within the Tools section of the configuration panel.
4. To remove an assigned tool, click the × icon on its corresponding chip. If you select a tool you don’t have permission to use, MoEngage removes the tool from the agent silently when you save, so your agent’s tool access always matches your own MoEngage permissions.

​

Connectors

​

Generate and Analyze Images

• Image generation produces creatives from the prompt that you or the agent’s instructions supply. Request more than one creative in a single prompt, and specify the aspect ratio or size you require.
• Image analysis reads an image, which allows an agent to review a creative against your requirements or to work from an image you attach to a run.

​

Send Summary Emails

​

Request a Summary Email

• The agent’s instructions, which cover every task the agent performs. Instructions suit a scheduled agent, because each scheduled task then reports back without further input from you.
• The prompt that starts a task, which covers that single task.

After you complete the weekly report, email me a summary with the subject "Weekly Campaign Review".
Use these sections: What I checked, Key metrics, Issues found, and Recommended actions.
Attach the report as a spreadsheet.
If you cannot complete the report, email me what blocked you instead.

• “Mail it to me.”
• “Email me the results when you are done.”
• “QC yesterday’s push campaigns and email me the findings with the subject ‘Daily Push QC’.”
• “Export the segment overlap to a spreadsheet and email it to me with a one-paragraph summary.”

​

What the Summary Email Contains

• Status banner: Task complete, Needs review, or Update, with the agent’s name below it. The agent sets the banner at the time of sending, and applies Update in the absence of a status.
• Subject line: The subject you specified in your instructions or prompt.
• Outcome: A one-line statement of what the task achieved, under an Outcome label at the top of the email body.
• Summary sections: The sections you defined, such as the work completed, the agent’s findings, key metrics, and open items. Each section title you requested appears as a heading above its content.
• Task details: A table listing the Task ID, the time the task Finished, and the address the email was Sent to.
• Open this run: A button that opens the task that produced the email.
• Attachments: The files the agent attached, delivered as standard email attachments.

​

Attachments in a Summary Email

• An agent attaches up to 5 files to a single summary email.
• The 3.5 MB limit applies to all attachments combined, rather than to each file individually.
• Attachments support document and spreadsheet formats, including PDF, DOCX, XLSX, CSV, Markdown, and TXT.
• An agent attaches only the files it created during the same task.
• Request attachments in the same instruction or prompt that requests the email.
• When the attachments exceed the file count or the combined size limit, the agent sends no email and names the file that caused the problem in the task transcript.

​

Summary Email Recipients and Limits

• Fixed recipient: MoEngage sends each summary email to the person who ran the task, and to no one else. You cannot add recipients, a distribution list, or an external address.
  • Public agents: When a teammate runs your public agent, that teammate receives the summary for their own task, and you receive no copy. Refer to Set Visibility.
  • Scheduled tasks: The agent’s creator receives every summary the schedule produces, because the task executes under the creator’s credentials. Refer to Scheduled Run Behavior.
• English template text: Banners, button labels, and footers appear in English, regardless of your dashboard language.

​

Assign Sub-Agents

​

Select an Agent Mode

​

Set a Trigger

• Run manually (Default): The agent only runs when you or a teammate starts a run.
• Run on schedule: The agent runs automatically on a recurring schedule you define.

1. Select Run on schedule.
2. Choose a recurrence: Daily, Weekly, or Monthly. For a Daily recurrence, set the repeat interval from 1 to 999 days. Weekly and Monthly recurrences repeat every 1 week or 1 month; MoEngage does not support a longer repeat interval for these recurrences.
3. Set a start date and an end condition (never, on a specific date, or after a set number of occurrences).
4. Set the timezone for the schedule. The schedule’s timezone defaults to your dashboard’s timezone.

​

Attach Files

1. Click the + icon in the Files section.
2. Select a file from your device.

​

Set Visibility

• Private OFF (Default): The agent is visible to all users in your workspace. To list public agents, open More filters on the All custom agents page and set Visibility to Public. Any teammate can run or duplicate the agent. Only you (the creator) can edit, pause, resume, or delete the agent.
• Private ON: The agent is restricted. Only you can view, access, and run the agent. MoEngage does not show the agent to any other user, or reveal that the agent exists.

​

Configure Notifications

​

Test Agent

​

Initiate a Test Run

1. Click the Test agent tab beside Configuration.
2. In the text box at the bottom of the tab, type a test scenario or select one of the suggested quick-start prompts:
   • Run now: Executes the agent immediately using its default instructions.
   • Show capabilities: Prompts the agent to summarize what it is configured to do.
   • What tools can you access?: Lists the tools currently assigned to the agent.
   • Walk me through a scenario: Asks the agent to narrate a sample execution.
   
3. Press Enter or click the send button to initiate the task.

• Start a New Test: Click New test under Past test runs in the left sidebar to clear the current chat window and initiate a fresh test run.
• Cancel a Running Test: Click Cancel while a test is in progress to stop the run immediately.
• Review Past Test Runs: The left sidebar logs your testing history under the Past test runs section, organized by date and time (for example, 4 Nov, 12:49 pm). Click on any timestamp to reopen that specific test run and review the agent’s previous responses or tool calls.
• Attach Test Files: Click the + icon located inside the message input box at the bottom of the screen to attach up to 5 files to your test prompt. Use this to give the agent sample data, specific documents, or reference files to process during the test run.
• Get Notified When a Test Finishes: Under Notifications at the bottom of the left sidebar, turn on Notify on task completion to receive a system alert when the test run completes.
• Return to the Configuration: To leave the test and edit the agent, click the Configuration tab.

​

Interpret Test Results

• Tool calls: Each time the agent uses a tool, the interface displays the tool name, the context parameters (e.g., get_campaign_meta context="Finding all sent/active campaigns"), and the execution time.
• Agent reasoning: Intermediate messages explaining the agent’s logic as it works through the assigned steps.
• Final output: The structured result returned upon completing the task.
• Iterate on Feedback: If the agent calls the wrong tools or misinterprets your prompt, switch to the Configuration tab, return to the Instructions editor, and clarify the steps. Be highly specific about what data the agent should fetch and how it should format it.

​

Publish the Agent

​

Manage Custom Agents

• The agent’s creator: Edit, Pause or Resume, Duplicate, Delete, and Pin to sidebar.
• Every other user: Pin to sidebar and Duplicate.
  

​

Edit an Agent

1. From the All custom agents page, click anywhere on the agent’s card to open its detail page.
2. Click the Manage dropdown menu located in the top-right corner and select Edit.
3. The configuration builder opens with all existing fields pre-populated. Make your required updates.
4. Review the instructions and start a Test agent run to verify its behavior.
5. Click Publish to save and deploy the changes.

​

Make a Draft Agent Operational

1. From the Custom Agents dashboard, click the Draft agent’s card to open the builder.
2. Run a test run to verify the agent’s behavior.
3. Click Publish to publish the agent for production use.

​

Pause or Resume an Agent

1. Open the agent’s detail page.
2. Click the Manage dropdown menu and select Pause (or Resume for a paused agent).

​

Duplicate an Agent

1. Open the published agent’s detail page.
2. Click the Manage dropdown menu and select Duplicate.

​

Characteristics of a Duplicated Agent:

• Draft Status: The duplicate opens in the builder as a Draft named Duplicate_<Original name>. Rename it before you publish, if you’d like.
• Inheritance: The duplicate inherits the source agent’s instructions, assigned tools, visibility setting, and trigger configuration.
• Run History: It begins with a fresh, empty task history.
• Eligibility: Duplicate is a Manage action, so it applies to any published agent you can open. A Draft has no detail page and therefore no Manage dropdown: publish the Draft first if you need a copy of it. Deleted agents cannot be duplicated.

​

Delete an Agent

1. Open the agent’s detail page.
2. Click the Manage dropdown menu and select Delete.

​

Characteristics of a Deleted Agent:

• Visibility: MoEngage immediately removes the agent from the All custom agents page. MoEngage also removes the agent from every user’s pinned list, and its tasks stop appearing in task lists.
• Restrictions: It can no longer be executed, edited, or duplicated.
• Audit Trail: MoEngage preserves its task history for auditing, but the history is no longer accessible through the standard gallery interface.
• Memory: MoEngage archives the agent’s own memory store along with its task history. Anything that agent contributed to workspace memory stays in place and remains readable by your other agents. Nothing records which agent contributed a given fact, so those contributions cannot be removed selectively.

​

FAQs

​

Next Steps