Agent Management

This guide covers the complete lifecycle of a custom agent: from initial creation and testing, through version control and publishing, to ongoing management and advanced integration features.

Feature	Description
Creating an Agent	Set up a new custom agent from scratch or using the Marketplace.
Testing an Agent	Validate and refine agent behavior in a controlled environment before deployment.
Version Control	Manage draft and published agent versions to keep production stable while iterating.
Agent Options	Export, delete, share, and modify agents after publication.
Schedulers	Create, manage, and monitor automated schedules for agents, flows, and platform modes.
Schedule Trigger	Automate agent execution at predefined intervals without manual intervention.
Handling Alert Tasks	Pause and resume conversations using hold templates and correlation IDs.
Notify API	Send interactive notifications with action buttons to users via API.

Creating an Agent

The agent creation feature provides a streamlined interface that enables the creation of new agents. The system adapts its behavior based on workspace access and permissions.

Create Agent Button

• Users with appropriate permissions see the Create Agent button in the Agents and Flows section.
• The system hides the Create Agent button from users who lack Personal Workspace access and have no shared workspace access.
• The interface hides filter options (My Agents and Shared Agents) for users who haven’t created any agents.

Agent Creation Process

1. Navigate to the Agent and Flow section and click Manage.

2. Click Create Agent to display a list of available agent types.
3. Select the desired agent type.

4. Choose Create from Scratch or Use Marketplace.
5. Select a preferred creation method.

Workspace Routing

Scenario	Behavior
Single Workspace	The system navigates directly to your Personal Workspace in a new tab with the selected agent type pre-selected.
Multiple Workspaces	A workspace selection modal appears, including My Workspace (Personal Workspace) as an option.

---

Testing an Agent

The Agent Testing feature provides a controlled environment for testing and refining agents before deployment, ensuring optimal performance in production environments.

Accessing the Testing Panel

The Test button becomes active after administrators complete the agent basic details step. Clicking it opens the Agent Testing Panel with a compose bar scoped strictly to the selected agent. Administrators cannot change agents or add attachments within this testing mode.

Testing Capabilities

• The panel provides default sample queries for one-click execution.
• Users can manually enter custom queries.
• Responses for both query types are displayed within the panel for comprehensive testing.
• Administrators can submit multiple queries per session to thoroughly evaluate agent performance.
• Clear Chat resets the chat history and input field for a new session.

Agent Improvement Workflow

Out-of-scope queries trigger an Improve Purpose based on Query button that opens a modal displaying the current agent purpose alongside the problematic query. Administrators can generate a revised purpose based on the query and save the updated configuration directly to the agent.

Agent responses with submission actions show disabled execution buttons in testing mode to prevent unintended actions.

Response Management

The panel includes utility features for response management, including copy functionality for agent responses, export options for test results, and configurable follow-up capabilities that administrators can disable as needed during testing scenarios.

---

Version Control

The Agent Version Control system allows you to safely develop and test agent configurations without affecting your live, published agents. This dual-version approach ensures production stability while enabling continuous improvement and experimentation.

Two-Version System

Every agent maintains two distinct versions:

Version	Description
Draft Version	Contains your latest edits and modifications.
Published Version	The live version accessible to end users.

This separation ensures that experimental changes do not impact the production environment until you are ready to deploy them.

Making Changes

When you edit a published agent:

1. Your changes are automatically saved to the Draft Version.
2. The Published Version remains unchanged.
3. An Unpublished Changes banner appears at the top of your screen.

Unpublished Changes Banner

The banner displays: You have unpublished changes that haven’t been applied to the published agent.

Available actions:

• Discard Changes — Remove all draft modifications.
• Publish — Deploy your changes to the live version.

Discarding Changes

To abandon draft modifications:

1. Click Discard Changes in the banner.
2. A confirmation pop-up appears with the following options:
   • Confirm — Permanently discard all changes and revert to the published version.
   • Cancel — Keep your changes and dismiss the popup.

Publishing Changes

To deploy your draft modifications:

1. Click Publish in the banner.
2. You are redirected to the Publish screen.
3. Review the Include unpublished changes for publishing checkbox:
   • Checked (Default) — Publishes your draft version with all modifications.
   • Unchecked — Only applies user list updates, keeping draft changes separate.

---

Agent Options

Manage your agent’s deployment, data, and availability post-publication. Agent options are enabled after publishing your agent.

Available Actions

Action	Description
Export Agent	Download agent configuration and associated data.
Delete Agent	Permanently remove the application.
Share	Grant workspace members access to collaborate on and manage the agent.

Modifying an Agent

To edit an existing agent:

1. Navigate to the desired agent list page and locate the agent you wish to modify.

2. Click the three-dot icon next to the agent’s name. A menu appears with the following options:
   • Edit — Open and modify the agent’s details.
   • Publish/Unpublish — Change the agent’s status.
   • Delete — Permanently remove the agent.
3. Select the required option and complete the modifications as needed.

Sharing an Agent

Agent Sharing lets workspace members collaborate on and manage agents through granular access controls, flexible sharing, and clear ownership.

Click Share to access and manage agent sharing settings.

Default visibility: All agents are visible to workspace collaborators. The creator has full edit access; others have view-only access.

Access levels:

Level	Permissions
Viewer	Can view but not change configurations.
Editor	Full control over settings and can add collaborators.
Remove Access	Confirms the agent exists but prevents viewing or editing.

Collaboration rules:

• Creators and editors can assign Editor or Viewer access at the individual or workspace level.
• Only workspace members can be invited to collaborate.

---

Schedulers

The Schedulers feature provides a centralized location to create, manage, and monitor automated schedules for agents, flows, and platform modes.

Access Schedulers Tab → Create Scheduler → Configure & Save → Manage Schedules

Accessing Schedulers

1. On the homepage, click Agents and Flows.
2. Navigate to the Schedulers tab.

The tab displays all schedulers you have created, along with any admin-enforced schedulers assigned to you.

Creating a Scheduler

1. On the Schedulers tab, click Create.

2. In the Agent field, select one of the following:

   • An agent you have access to
   • A flow you have access to
   • A mode: Work, Web, or AI Model
   

3. Set the schedule timing and frequency: Once, Hourly, Daily, Weekly, Monthly, Custom, or Cron.

4. In the Trigger Query field, enter the instructions for the agent or flow to execute on each run.

5. Select an Execution Mode:

   • Ask before running — The platform sends a notification at the scheduled time and runs the agent only after you approve.
   • Run automatically — The platform runs the agent on schedule without approval and notifies you when complete.

6. Click Save.

The scheduler is enabled by default after saving.

Managing Schedulers

You can toggle any scheduler on or off at any time. Changes take effect immediately.

Edit a scheduler

Click an existing scheduler to open its configuration. Update the agent or flow selection, schedule timing, or query as needed, then save. Changes take effect immediately.

Delete a scheduler

Select the scheduler and click Delete. The platform removes it immediately.

Use the same agent across multiple schedulers

You can assign the same agent to different schedulers. Each scheduler operates independently with its own timing, frequency, and query.

Admin-Enforced Schedulers

Administrators can create and assign schedulers that appear automatically in your Schedulers tab. Admins configure this from the Admin Console under Assist Configuration > Scheduler Settings, where they can:

• Enable the Scheduler feature for the workspace.
• Set a scheduling limit per user (5, 10, 20, or 30 schedulers).
• Enable Workspace Owner Scheduler Permissions to allow workspace owners to publish agents with pre-configured schedules that run automatically for end users.

When Workspace Owner Scheduler Permissions are enabled, workspace owners can add schedulers during agent creation and publish agents with active schedules.

Admin-enforced schedulers follow these rules:

• If you have available capacity, they are enabled by default. If you have reached your limit, they appear disabled.
• You can enable or disable them.
• You cannot edit their configuration — they appear in view-only mode.
• You cannot delete them.

---

Schedule Trigger

The Schedule Trigger feature enables automated execution of agentic flows at predefined intervals. By configuring a schedule, you can automate routine tasks without manual intervention, allowing the agent to run autonomously based on your specified timing and frequency.

The Schedule Trigger is optional and disabled by default. When enabled, it provides end users with the ability to configure and manage automated executions.

Configuring a Schedule Trigger

Step 1 — Allow Schedule Trigger for Agent

Toggle the Allow Schedule Trigger for Agent option to enable scheduling. When enabled, end users can see, set up, and activate schedules. Disabling it hides all scheduling options from them.

Step 2 — Set Default Schedule

Click Default Schedule to set the initial automation schedule. Available schedule types:

Type	Description
Once	Runs a single time at a specified date and time.
Hourly	Repeats every hour.
Daily	Repeats each day at a set time.
Weekly	Repeats on selected days of the week.
Monthly	Repeats on a specified day each month.
Custom	User-defined recurrence.
Cron	Precise schedule using cron expression syntax.

After selecting a type, specify the start and end dates and times, then select a timezone. You can choose a standard timezone or set it to End User Specific, which bases the trigger on each user’s geolocation. For Weekly schedules, you must also select the specific days when the automation should run.

If you enable the schedule trigger without specific configuration, the system defaults to a daily run at 8:00 AM.

Step 3 — Instructions to Agent

Enter clear instructions describing what the agent should accomplish during its scheduled execution. Well-defined instructions help ensure the agent performs the intended tasks accurately.

Step 4 — Configure Behavior Settings

Configure notification preferences to control how the system communicates with users about scheduled executions.

Setting	Mode	Behavior
Notify on Start	User-Triggered	Sends a notification when the agent is ready to begin execution. The agent waits for user confirmation before running.
Notify on Completion	Auto-Triggered	Sends a notification once the agent has finished executing. The agent runs automatically and informs users of the results.

Schedule Trigger configuration becomes available only when scheduling is enabled by an administrator. To understand the required admin-level controls, see Scheduler Settings.

---

Handling Alert Tasks

The Bot, Workflow, and Autonomous Agents module allows developers to integrate conversation hold and resume functionality within AI for Service Bots. This section describes how the system handles brief pauses (holds) and subsequent resumption of conversations.

Core Concepts

Conversation Hold

A conversation hold represents a temporary pause in the dialogue flow, typically initiated when waiting for an external alert or event. The system maintains conversation context throughout the pause using a unique identifier: conversation_reference_id.

Hold Template

A hold template is a structured message displayed to users during a conversation pause. It contains a title and description explaining the reason for the interruption.

Customizable fields include:

• Title — A concise title describing the reason for the pause.
• Description — A more detailed explanation of the pause and potential next steps.

Prerequisites

Before implementing conversation hold and resume:

• Hold Trigger Mechanism — Implement a mechanism to send a predefined hold template message to the user when a conversation needs to be paused.
• Resume Mechanism — Define how alerts or messages will trigger the resumption of the paused conversation using the conversation_reference_id.
• Correlation ID — Ensure both the hold template and the resuming alert include the same conversation_reference_id for proper matching.

Triggering a Conversation Hold

When the bot encounters a situation requiring a pause (for example, awaiting an alert), send a hold template message to the user.

Required parameters:

Parameter	Type	Required/Optional	Description
type	string	Required	Action type (e.g., "hold_conversation")
title	string	Required	Title of the hold message.
description	string	Required	Description of the hold message.
conversation_reference_id	string	Required	The unique identifier for this specific conversation.

Example hold template:

let sessionId = context.<uniqConversationId>;
let response = {
  "type": "template",
  "payload": {
    "template_type": "hold_conversation",
    "title": "Request is being processed...",
    "description": "You will be notified as soon as it is ready!",
    "conversation_reference_id": sessionId // e.g., "abc123"
  }
};
response = JSON.stringify(response);
print(response);

Upon receiving the hold template, the user interface:

• Pauses the ongoing conversation.
• Displays the hold template to the user, including the customized title and description.

You must first activate the alert service before displaying the hold template.

Resuming a Conversation

The resume response removes the hold template and continues the conversation with the alert or message content.

Required parameters:

Parameter	Type	Required/Optional	Description
conversation_reference_id	string	Required	The unique identifier of the paused conversation.
text	string	Required	Response content to display upon resumption.

Example resume response:

let response = {
  "conversation_reference_id": id, // e.g., "abc123"
  "text": result
};
response = JSON.stringify(response);
print(response);

Once the resume response is received:

• The hold template is removed from the user interface.
• The new alert or message is displayed to the user.

The conversation_reference_id ensures that the response is correctly associated with the paused conversation. Any text or template that includes conversation_reference_id can be used as an alert response or message to start a new conversation.

Key Points

• Customization — Leverage the flexibility of the hold template to provide contextually relevant messages to users.
• Mandatory Correlation ID — The conversation_reference_id is critical for ensuring seamless conversation flow during pauses and resumes.
• Alert/Message Flexibility — Support various response formats, including plain text and custom bot templates, for optimal user experience.

---

Notify API

The Notify API enables developers to send interactive notifications to users. These notifications can include customizable response options and action buttons.

Applicable only for Bot, Autonomous, and Workflow Agents.

Endpoint Reference

Property	Value
Method	POST
Endpoint	https://{{host}}/api/public/agents/{agentId}/notify
Content-Type	application/json
Authorization	authorization: <authToken> — The access token obtained from the agent settings page.
API Scope	Notification

Path Parameters

Parameter	Required/Optional	Description
host	Required	Environment URL, for example https://work.example.ai
agentId	Required	The unique identifier of the agent. Replace {agentId} in the URL with the actual agent ID, obtained from the Post URL field while creating an agent.

Sample Request

curl --location --request POST 'https://work.example.ai/api/1.1/public/agents/ag-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/notify' \
--header 'authorization: <YOUR_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "to": "[e-mail]",
    "message": {
        "title": "Agent Update",
        "body": "Notification description"
    },
    "category": "agent",
    "actions": [
        {
            "title": "LaptopRequest",
            "type": "postback",
            "utterance": "submit action 1",
            "payload": {
                "transactionId": "tx-qwe2cd11",
                "sessionId": "s-hr3wx21rt",
                "event": "laptopRequest"
            }
        }
    ]
}'

Request Body Parameters

Parameter	Type	Required/Optional	Description
to	string	Required	Email address of the application user (single recipient).
message	object	Required	Contains notification title and body text.
message.title	string	Required	Notification title.
message.body	string	Required	Notification message body.
category	string	Required	Category of the notification (e.g., "agent").
actions	array	Required	Array of interactive response buttons.
actions[].title	string	Required	Button label text.
actions[].type	string	Required	Action type (e.g., "postback").
actions[].utterance	string	Required	Text sent when the button is clicked.
actions[].payload	object	Required	Custom data passed with the action.

Sample Response

{
    "notify": "success"
}

Key Points

• The to email address must belong to a valid application user.
• Use custom payload data for tracking and response handling.
• The to key accepts a single email address in the initial implementation.
• Include actions in the request payload to present users with interactive buttons.

---