Run and Manage Agent Sessions

Learn how to start, execute, monitor, resume, and manage individual conversational interaction sessions with Custom Agents in MoEngage.

A session represents a single, conversational interaction with an agent to complete a specific task. Test runs and Live runs are functionally identical; both operate on real workspace data and are managed as sessions. Every time you initiate a run, MoEngage opens a new session, assigns it a unique Session ID (e.g., sess_a1b2c3...), and permanently logs the complete transcript within the agent’s All tasks history for auditing and future reference.

Start a New Session

You can initiate a new session from three distinct locations in the platform:

• From the Gallery: Click the Run (▶) icon on the right edge of any Live agent card.
• From the Agent Details Page: Open the specific agent and click Run in the top-right corner.
• From the Agent Builder: While creating a Draft or editing a Live agent.
  • Click Test agent to start a trial run. This session will be explicitly tagged as Test in the agent’s history.
  • Click *Make live” to start a live run. This session will be explicitly tagged as Live in the agent’s history.

When a session opens, the side panel slides out. Depending on where you initiated the session, the UI will display distinct terminology:

Live Run

Test Run

• Live Runs: The panel is titled Run agent. The left sidebar allows you to initiate a + New run and logs your chat history under Past runs.
• Test Runs: The panel is titled Test agent. The left sidebar allows you to initiate a + New test and logs your chat history under Past test runs.

Both interfaces present a chat window with an input box at the bottom. Enter your request, such as a specific campaign ID to audit, a creative brief, or a direct question.

Agents rely entirely on your instructions and the context you provide. Supplying necessary IDs, dates, or reference briefs in your very first message prevents unnecessary back-and-forth and improves output accuracy.

Test vs. Live Runs

The primary distinction between a Test run and a Live run is how the task is logged within the system. Functionally, both execution modes are identical: they operate on real workspace data and utilize the exact same tool permissions.

Feature	Test Run	Live Run
Data Accessed	Real MoEngage workspace data.	Real MoEngage workspace data.
Write Operations	Executes real changes if write tools are assigned.	Executes real changes if write tools are assigned.
Run History Logging	Tagged as Test in the All tasks tab.	Tagged as Live in the All tasks tab.

Because Test runs interact directly with live data and will execute real write operations, they must never be treated as a risk-free or isolated sandbox. Use Test mode strictly to validate agent behavior and refine instructions before promoting the agent to your team, not as a safe alternative to a live run.

The Execution Lifecycle and Interaction

Sessions are conversational and asynchronous. When you submit a prompt, the following execution sequence occurs:

1. The agent reads its core instructions to establish its role and objectives.
2. It acknowledges your prompt and begins executing its defined steps, calling assigned tools sequentially (e.g., fetching a campaign, generating a personalization preview, synthesizing a report).
3. Each tool call is logged in the transcript with its specific context parameters and execution time.
4. The agent synthesizes the retrieved data and generates a final, structured output.

• As runs can take anywhere from a few seconds to several minutes depending on data volume and tool complexity, they operate entirely in the background. You do not need to keep the session window open; you can safely navigate away and return to the All tasks tab later to view the final output. Additionally, write-enabled agents can create or modify real drafts during a session. Always review the agent’s actions before considering the task complete.
• You can send follow-up messages at any point during an open session to request a deeper analysis, ask for a different output format, or instruct the agent to refer to and analyze a different campaign.

Anatomy of a Session Transcript

When viewing an active or past session in the side panel, the transcript displays the following elements from top to bottom:

• Header and Instructions: Display the Session ID (with a one-click copy icon), the email of the user who invoked the run, and the initial prompt that kicked off the task.
• Agent Steps (Tool Calls): Expandable cards detailing each tool the agent used. By default, these are collapsed for scannability but can be expanded to view full inputs and outputs. Each card includes:
  • A status icon (e.g., ✓ for success)
  • The tool name (e.g., search_campaigns)
  • Truncated parameter previews
  • Total execution time (e.g., 4.9s)
• Agent Reasoning: Brief, natural-language updates generated between tool calls, explaining the agent’s logic and next steps (e.g., “Campaign confirmed as Push channel. I need to run the personalization preview…”).
• Generated Files: Any downloadable artifacts produced by the agent (e.g., HTML reports, CSVs). These appear as inline cards showing the filename, type, size, and a download button. Files you attach to your own prompts appear similarly.
• Response: The structured output, typically formatted in Markdown. Each message block includes a copy icon (content_copy) so you can easily export the report to external documents or messaging tools.

Monitor the All Tasks History

Every initiated session, whether Live or Test, is recorded on the agent’s detail page under the All tasks tab. As shown in the interface, this tab provides a comprehensive audit trail specific to that agent.

Filtering and Search

Use the filter row above the table to narrow the displayed sessions:

• Search by Task ID: Paste a specific Session ID to locate an exact run.
• Status and Date Filters: Use the dropdown menus or the combined funnel icon to filter by specific execution outcomes or timeframes.

Table Columns Overview

Column	Description
Task ID	The unique Session ID. Click the ID to open the full transcript in the right-side panel.
Run status	The current state of the execution (see Run Status Values below). The various run status values include: • Running: The agent is actively executing instructions and calling tools. • Idle: The run has completed successfully. Sessions remain “Idle” because they are always resumable; they are never marked “done.” • Failed: The run encountered a critical error and terminated prematurely.
Run time	The exact date and timestamp when the session was initiated.
Run type	The operational mode of the session (Live or Test).

Resume and Share Sessions

Resume a Session

Sessions are persistent and do not permanently close. Because each session retains a localized memory, the agent stores the complete context of all preceding instructions, tool outputs, and generated files within that specific run. To resume a previous conversation:

1. Open the All tasks tab on the agent’s detail page.
2. Click the desired session row to open the transcript in the side panel.
3. Type a new message in the input box. The agent will retain all prior context, tool outputs, and generated files, picking up exactly where it left off.

Share a Session

To share a specific session transcript with a colleague in your workspace:

1. Open the session.
2. Click the copy icon next to the Session ID at the top of the panel.
3. Share the ID. Your colleague can paste it into the Search by Task ID filter on the agent’s All tasks tab to immediately view the transcript.

Session Boundaries and Technical Limitations

Keep the following operational boundaries in mind when running agents:

• No Auto-Send Capabilities: Even with write tools enabled, an agent can only create or pause campaign drafts. It cannot publish campaigns directly. Final publishing of a campaign must always be executed manually through the standard MoEngage campaign builder using the draft ID generated by the agent.
• Workspace Privacy: Sessions are strictly private to your specific workspace and cannot be shared across different organizations.
• Immutable History and 30-Day Inactivity Limit: Sessions cannot be deleted, and their transcripts remain permanently in the agent’s history for you to view. However, a session is only active for 30 days. You can resume and continue chatting within a specific session within that 30-day window. Once the 30 days have passed, the history remains visible, but you must initiate a new session to perform further tasks.
• Archiving Agents: To prevent accumulating sessions on an obsolete agent, you must archive the agent entirely, which removes its history from gallery access.

FAQs

Do I need to keep the dashboard open while an agent is executing a task?

No. Custom Agents operate asynchronously as long-running background processes. You can safely navigate away from the session window while the agent works. Once you are ready, return to the All tasks tab on the agent’s detail page to review the completed steps and final output.

Does the agent remember my past instructions and files?

Yes. Every session features a persistent, localized memory. The agent retains the complete context of all preceding chat history, tool outputs, and attached files within a specific Session ID. You can reopen any Idle session from the All tasks tab to resume a complex workflow right where you left off.

My agent's task says 'Idle.' Did it get stuck or fail?

No, “Idle” actually means the task was completed successfully! MoEngage uses the term “Idle” because agent sessions act like continuous chat threads. The agent is simply waiting idly for you to ask a follow-up question or give it a new command based on the data it just provided.