Schedule autonomous runs

You can schedule an agent to run a specific intervals using Scheduled Runs.

Each agent can have multiple schedules, allowing you to run it the same agent at multiple intervals or for each one of your users.

Each Scheduled Run creates an Agent Run, so you can expect Schedules to work similarly. In fact, the difference between Scheduled Runs and Agent Runs is that Agent Runs run once immediately, while Scheduled Runs run at a cadence. Just like Agent Runs, you can optionally specify a bundle to further tailor the functionality of your agent, as well as a Toolhouse ID metadata.

Getting started with Scheduled Runs

Make sure you have your API Key ready. You can see or create an API key in the API Keys page.

Specifying a cadence

The minimum cadence for a Scheduled Run is every 10 minutes. If you specify a shorter cadence, your agent will still run at the minimum cadence.

You'll need to specify how often you want to agent to run. The minimum cadence is every 10 minutes. To specify a cadence, simply provide a cron expression or a plain text description of the cadence. Scheduled Runs has a dedicated endpoint to translate plain text to cron:

import requests
import json

def send_request(toolhouse_api_key, cadence):
    params = { "cron": cadence }
    url = "https://api.toolhouse.ai/v1/schedules/text-to-cron"
    headers = {
        "Authorization": f"Bearer {toolhouse_api_key}",
    }

    response = requests.get(url, params=params, headers=headers, json=payload)

    return response

# Example usage
if __name__ == "__main__":
    toolhouse_api_key = "YOUR_TOOLHOUSE_API_KEY"
    cadence = "sundays at 5pm UTC"

    response = send_request(toolhouse_api_key, cadence)

    # Check if the request was successful
    if response.status_code == 200:
        print("Request successful. Response:")
        print(response.json())
    else:
        print("Request failed with status code", response.status_code)

This will return a cron expression you can use in subsequent requests.

{
  "data": "0 17 * * 0"
}

Creating a Scheduled Run

  1. Head over to Agent Studio and create a chat. If you're looking for inspiration, you can use this prompt.

  2. Click the Share button, then copy the Chat ID.

  3. Create an Scheduled Run using the Scheduled Runs API:

import requests
import json

def send_request(toolhouse_api_key, chat_id):
    url = "https://api.toolhouse.ai/v1/schedules"
    headers = {
        "Authorization": f"Bearer {toolhouse_api_key}",
        "Content-Type": "application/json"
    }

    # Set the JSON payload
    payload = {
        "chat_id": chat_id,
        "cadence": "0 17 * * 0",
    }

    # Send the POST request
    response = requests.post(url, headers=headers, json=payload)

    return response

# Example usage
if __name__ == "__main__":
    toolhouse_api_key = "YOUR_TOOLHOUSE_API_KEY"
    chat_id = "YOUR_CHAT_ID"

    response = send_request(toolhouse_api_key, chat_id)

    # Check if the request was successful
    if response.status_code == 200:
        print("Request successful. Response:")
        print(response.json())
    else:
        print("Request failed with status code", response.status_code)

Your Scheduled Run entry will be created.

{
  "data": {
    "id": "bcb7e865-9e6c-xxxx-xxxx-c0110fdf5c2e",
    "created_at": "2025-01-15T01:46:23.568338",
    "updated_at": "2025-01-15T01:46:23.568338",
    "cadence": "0 17 * * 0",
    "active": true,
    "bundle": "default",
    "toolhouse_id": "default"
  }
}

Changing the cadence of a Scheduled Run

You can change the cadence of a Scheduled Run at any time.

import requests
import json

def send_request(toolhouse_api_key, schedule_id, cadence):
    url = f"https://api.toolhouse.ai/v1/schedules/{schedule_id}"
    headers = {
        "Authorization": f"Bearer {toolhouse_api_key}",
        "Content-Type": "application/json"
    }

    payload = {
        "cadence": cadence
    }

    response = requests.put(url, headers=headers, json=payload)

    return response

# Example usage
if __name__ == "__main__":
    toolhouse_api_key = "YOUR_TOOLHOUSE_API_KEY"
    schedule_id = "YOUR_SCHEDULE_ID"
    cadence = "0 */3 * * *"

    response = send_request(toolhouse_api_key, schedule_id, cadence)

    # Check if the request was successful
    if response.status_code == 200:
        print("Request successful. Response:")
        print(response.json())
    else:
        print("Request failed with status code", response.status_code)

Pausing or resuming a Scheduled Run

When you pause a Scheduled Run, you interrupt its scheduled cadence without deleting it by setting its activefield to false. This is useful to keep the configuration of your Scheduled Run without deleting it completely. You can resume its execution at any time by changing its activefield back to true.

Any currently active Runs will pause at the end of their execution.

import requests
import json

def send_request(toolhouse_api_key, schedule_id, is_active):
    url = f"https://api.toolhouse.ai/v1/agent-runs/{schedule_id}"
    headers = {
        "Authorization": f"Bearer {toolhouse_api_key}",
        "Content-Type": "application/json"
    }

    payload = {
        "active": is_active
    }

    response = requests.put(url, headers=headers, json=payload)

    return response

# Example usage
if __name__ == "__main__":
    toolhouse_api_key = "YOUR_TOOLHOUSE_API_KEY"
    schedule_id = "YOUR_SCHEDULE_ID"
    is_active = False

    response = send_request(toolhouse_api_key, schedule_id, is_active)

    # Check if the request was successful
    if response.status_code == 200:
        print("Request successful. Response:")
        print(response.json())
    else:
        print("Request failed with status code", response.status_code)

Deleting a Scheduled Run

Lastly, you can completely delete a Scheduled Run. Any currently active Runs will stop running at the end of their execution.

import requests
import json

def send_request(toolhouse_api_key, schedule_id):
    url = f"https://api.toolhouse.ai/v1/agent-runs/{schedule_id}"
    headers = {
        "Authorization": f"Bearer {toolhouse_api_key}",
    }
    
    response = requests.delete(url, headers=headers)

    return response

# Example usage
if __name__ == "__main__":
    toolhouse_api_key = "YOUR_TOOLHOUSE_API_KEY"
    schedule_id = "YOUR_SCHEDULE_ID"

    response = send_request(toolhouse_api_key, schedule_id)

    # Check if the request was successful
    if response.status_code == 200:
        print("Request successful. Response:")
        print(response.json())
    else:
        print("Request failed with status code", response.status_code)

Last updated