Build a scheduled agentic workflow for daily notifications

In an agentic AI system, multiple agents work on their own for managing tasks such as collecting data, making decisions, communicating, and taking actions. But some actions need to happen at the right time, not immediately. Many business processes depend on timing such as running something after a delay, at a specific time, or on a regular schedule. For example:

• Set the Data Backup Agent to run daily at 11:30 PM
• Run this monitoring tool every hour for the next 24 hours

These instructions create the foundation for scheduled agentic workflows. Scheduling agent actions keeps each workflow running smoothly and ensures tasks occur on time. This scheduling capability shifts an agentic system from reactive automation to proactive orchestration, where each agent can think, act, plan, and time its actions in a smart way.

In this tutorial, learn how to:

• Build an automated Daily Quote Scheduler by using IBM watsonx Orchestrate Agent Development Kit (ADK).
• Create reusable tools and combine them into agentic workflows that send a motivational quote to your inbox every morning without writing any cron jobs.
• Use enterprise email servers such as Gmail for email delivery.
• Schedule and monitor the automation in the watsonx Orchestrate user interface (UI), bringing AI orchestration, scheduling, and practical task execution into one place.

Architecture of daily quote scheduler

The architecture shows how a user can schedule events through conversational chat with AI agents.

• The user types “Schedule a daily quote email every day at 7 AM IST” in the web chat. This input triggers the orchestration flow.
• The request is routed to the Daily Quote Agent, which analyzes the request and selects the Send email Tool Flow as the next required action.
• The tool flow is a scheduled event or flow in watsonx Orchestrate. It runs at 7 AM IST every day. The custom email tool in the flow sends an email to the specified recipients.
• This setup is an example of an asynchronous process, useful when a task must run at a specific time, either one time or on a recurring schedule.

Prerequisites

• A local environment running the watsonx Agent Development Kit (ADK) version 1.15 or later. This tutorial was tested with ADK version 1.15.
• Python 3.11 or later. This tutorial was tested with Python 3.13.
• An active watsonx Orchestrate instance. You can create a free trial instance of watsonx Orchestrate SaaS on:
  • IBM Cloud
  • AWS
• An IDE such as Visual Studio Code.
• A mail account with an app password enabled. In this tutorial, you will use Gmail. You can also use SendGrid, Outlook, or IBM SMTP by updating your email tool credentials.

Steps

1. Configure SMTP connections in watsonx Orchestrate
2. Create the tools in watsonx Orchestrate ADK
3. Build an agentic workflow to connect the tools
4. Create the agents in watsonx Orchestrate
5. Import the tools and the agentic workflow into watsonx Orchestrate
6. Verify the agents in the watsonx Orchestrate UI
7. Schedule the agentic flow in the watsonx Orchestrate UI
8. Test the agent execution and verify the email output

Step 1. Configure SMTP connections in watsonx Orchestrate

Set up your Gmail account and create an SMTP connection that is required for the custom email tool.

1. To send email securely, you need the following values:

   • GMAIL_USER: your Gmail address

   • GMAIL_APP_PASSWORD: an app-specific password generated in your google account. To get the GMAIL_APP_PASSWORD, complete the following steps:

     1. Open your google Account.
     2. Select Security & sign in.
     3. Under How you sign in to google, turn on 2-Step Verification.
     4. Open App Passwords).
     5. Create a new app password (for example, Watson Orchestrate).
     6. Copy the generated 16-character password. This is your GMAIL_APP_PASSWORD.

     You will use GMAIL_USER and GMAIL_APP_PASSWORD in the next steps to configure the SMTP connection in watsonx Orchestrate.

2. Create the Gmail connection.

   1. Download the i-oic-wxo-scheduler-agent GitHub project.
   2. Open the project in VS Code.
   3. Locate the file connections/gmail_connection.yaml.

   4. Run the following command from the connections folder.

      ## Import the Connection
      orchestrate connections import -f gmail_connection.yaml

      Copy code

3. To set the credentials for draft and live environments, update the following command with your GMAIL_USER and GMAIL_APP_PASSWORD values and then run the command.

   ### Draft environment
    orchestrate connections set-credentials \
      --app-id gmail_connection \
      --env draft \
      -e 'GMAIL_USER=<your-email@gmail.com>' \
      -e 'GMAIL_APP_PASSWORD=<your-app-password>'

   Copy code

   ### Live environment
    orchestrate connections set-credentials \
      --app-id gmail_connection \
      --env live \
      -e 'GMAIL_USER=<your-email@gmail.com>' \
      -e 'GMAIL_APP_PASSWORD=<your-app-password>'

   Copy code

4. Validate the connection setup in watsonx Orchestrate ADK.

   ## Verify the Connection
   orchestrate connections list

   Copy code

   

Step 2. Create the tools in watsonx Orchestrate ADK

1. Create the custom send_gmail_notification tool. This Python tool sends emails through Gmail using a secure SMTP connection. It enables automated email delivery from watsonx Orchestrate.

   1. Open the agents folder in VS Code and locate the file send_mail_gmail.py.

      

   2. Import this tool into watsonx Orchestrate using the watsonx Orchestrate ADK command line interface (CLI).

      # Import the send_email_notification tool
      orchestrate tools import -k python -f send_gmail_tool.py --app-id gmail_connection

      Copy code

      

2. Create the quote generator tool. This Python tool returns a random motivational quote.

   1. In the same working directory within VS Code, locate the file get_quote_min.py.

      

   2. Import this tool into watsonx Orchestrate using the watsonx Orchestrate ADK CLI.

      # Import the quote generator tool
      orchestrate tools import -k python -f get_quote_min.py

      Copy code

      

      A confirmation message is displayed after the tool is successfully imported.

Step 3. Build an agentic workflow to connect the tools

Create an agentic workflow that links the quote generator tool and the email notification tool. This workflow calls the get_quote_min tool to fetch a quote and then sends that output to the email_test_agent agent for notification delivery.

In the same working directory within VS Code, locate the predefined workflow tools/daily_quote_flow_min.py file.

• The workflow defines a schedulable flow named daily_quote_flow_min. It first runs the get_quote_min tool, then passes the result to an AgentNode called notify_user_via_agent, which sends the quote by using the email_test_agent agent.

• Because schedulable=True, this workflow appears in the watsonx Orchestrate scheduler, allowing users to create time-based triggers without writing additional code.

Step 4. Create the agents in watsonx Orchestrate

1. Create two following agents to complete the workflow setup.

   • Email test agent: The email_test_agent uses the send_email_notification tool so that other workflows or agents can send email notifications through it.

     

   • Scheduler agent: The daily_quote_agent acts as a scheduler. This agent uses both custom tools and intrinsic tools to run and manage scheduled workflows.

     • Custom tools are written in Python and can be modified to fit your use case.
     • Intrinsic tools are provided by the watsonx Orchestrate ADK and cannot be modified. These tools support scheduling, monitoring, and management of workflows.

     The purpose of each tool used by the scheduler agent follows:

     • daily_quote_flow_min: uns the workflow that generates and sends the quote.
     • i__get_flow_status_intrinsic_tool__: Retrieves workflow status and run history.
     • i__get_schedule_intrinsic_tool__: Lists active schedules.
     • i__delete_schedule_intrinsic_tool__: Deletes a schedule using its schedule_id.

     These tools allow the scheduler agent to run, monitor, list, and manage scheduled workflows, enabling recurring automation in watsonx Orchestrate.

2. Import the agents/schedule_daily_quote_agent.yaml scheduler agent by using the watsonx Orchestrate ADK CLI.

   

Step 5. Import the tools and the agentic workflow into watsonx Orchestrate

1. Import the schedulable workflow by running the following command in the terminal from the tools directory in VS Code.

   orchestrate tools import -k flow -f daily_quote_flow_min.py

   Copy code

   This command registers daily_quote_flow_min in the watsonx Orchestrate user interface (UI). The workflow can now be scheduled or used by agents.

   

   A confirmation message is displayed after a successful import.

2. Run the following commands to import the email agent and the scheduler agent:

   # Import the email agent
    orchestrate agents import -f email_test_agent.yaml
   
    # Import the daily quote scheduler agent
    orchestrate agents import -f schedule_daily_quote_agent.yaml

   Copy code

   

   A confirmation message is displayed after both agents are successfully imported.

Step 6. Verify the agents in the watsonx Orchestrate UI

Open the watsonx Orchestrate UI and check Manage Agents to confirm that the imported agents are listed.

You can now run or schedule these agents directly from the watsonx Orchestrate UI.

Step 7. Schedule the agentic flow in the watsonx Orchestrate UI

Use the watsonx Orchestrate UI to schedule the automation.

1. Open the watsonx Orchestrate UI.
2. Search for the daily_quote_agent.

3. Enter a request such as:

   “Schedule a motivational quote to be sent to @gmail.com at 10:00 AM IST every Monday.”

4. Wait for watsonx Orchestrate to confirm the schedule.

   

   

   

   You can view and delete schedules directly from the watsonx Orchestrate UI.

   

Step 8. Test the agent execution and verify the email output

Open your inbox and look for an email with daily quote.

This confirms that the scheduled agent runs completed successfully.

Step 9. Review the schedule creation response

After you create a schedule in watsonx Orchestrate, the API returns a JSON response similar to the following example:

{
  "data": [
    {
      "schedule_data": {},
      "schedule_id": "314c68b7-9ca1-477f-9cc7-49290f3e6c49",
      "schedule_limit": 100,
      "schedule_name": "f020d70d-35da-429d-8782-2877959b3693_every_day_at_10am_Asia_Kolkata_100_times",
      "schedule_pattern": "0 10 * * 1",
      "schedule_time": "Mon Oct 27 2025",
      "schedule_timezone": "Asia/Kolkata"
    }
  ],
  "total": 1
}

Response field summary

• schedule_id: Unique identifier for the schedule. Use this ID to list, update, or delete the schedule.
• schedule_name: Automatically generated name based on the workflow and schedule time.
• schedule_pattern: Cron expression defining when the workflow runs.
  • Example: 0 10 * * 1 runs every Monday at 10 AM.
• schedule_timezone: Time zone that is applied to the schedule (for example, Asia/Kolkata).
• schedule_limit: Maximum number of times the scheduler runs before it stops.
• total: Number of schedules included in the response.

Tip for schedule management

Every schedule in watsonx Orchestrate includes a schedule_id. Use this ID to manage schedules through intrinsic tools:

• iget_schedule_intrinsic_tool: Lists all schedules.
• idelete_schedule_intrinsic_tool: Deletes a specific schedule.

Summary

In this tutorial, you explored the complete workflow for building and running an agent-driven automation. You completed the following tasks:

• Built and tested custom tools for quote generation and email delivery.
• Created an agentic workflow that connects these tools end to end.
• Defined dedicated agents for scheduling and notifications.
• Imported the workflow and agents into watsonx Orchestrate and configured a daily schedule.

You now have a functional automation in watsonx Orchestrate that sends daily inspirational messages.

Acknowledgments

This tutorial was produced as part of the IBM Open Innovation Community initiative: Agentic AI (AI for Developers and Ecosystem).

The authors deeply appreciate the support of Ramya Raghuveera and Bindu Umesh for reviewing and contributing to this tutorial.