Scheduled Task Management

Use this skill to create, list, inspect, update, and delete magic-service scheduled tasks.

How it works

Scheduled task capabilities are exposed as Code Mode tools (scheduled_task_*). They are not directly callable as standalone tool calls. Invoke them through run_sdk_snippet and sdk.tool.call:

run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call("scheduled_task_list")
print(result.content)
""")

tool.call(name, params) returns:

Use the Code Mode tools below for every scheduled-task operation.

Available Tools

The tools automatically read topic_id, project_id, and current model_id from the current session. Do not pass those IDs yourself.

Schedule Types

time is always required and must be HH:MM.

deadline is optional for recurring tasks. Use YYYY-MM-DD HH:MM:SS; YYYY-MM-DD is normalized to YYYY-MM-DD 00:00:00.

Agent Modes

agent_mode is optional. Omit it by default; the scheduled task will use the current running mode.

Use agent_mode only when the user explicitly asks for a mode. Built-in values:

The tool maps these friendly values to the corresponding magic-service mode identifiers internally.

If the user gives a custom employee identifier/code, pass that value as agent_mode. The tool maps it internally.

Create

run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call("scheduled_task_create", {
    "task_name": "Daily Briefing",
    "message_content": "Generate today's briefing",
    "schedule_type": "daily_repeat",
    "time": "09:00"
})
print(result.content)
""")

For long content, pass a Python triple-quoted string. Do not write a temp script:

run_sdk_snippet(python_code="""
from sdk.tool import tool

message = \"\"\"Read ops/source.json in the current article directory, visit the bound publishedUrl, and update only these operations files:
- ops/metrics.json
- ops/comments.json
- ops/review.html
Do not generate an AI Card.\"\"\"

result = tool.call("scheduled_task_create", {
    "task_name": "[Article Sync] Example Article",
    "message_content": message,
    "schedule_type": "daily_repeat",
    "time": "09:00",
    "specify_topic": 0
})
print(result.content)
""")

For custom employees, keep this parameter contract:

run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call("scheduled_task_create", {
    "task_name": "Custom Employee Task",
    "message_content": "Process this task with the custom employee",
    "schedule_type": "daily_repeat",
    "time": "09:00",
    "agent_mode": "SMA-custom-agent"
})
print(result.content)
""")

specify_topic

Pass specify_topic=1 only when both conditions hold:

1. The task is recurring: daily_repeat, weekly_repeat, or monthly_repeat.
2. The next run time or trigger depends on the current or previous run result, such as "run again 3 days after each completion" or "decide next time based on last result".

For one-time tasks, or fixed schedules that do not depend on previous results, keep specify_topic=0.

List

run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call("scheduled_task_list", {
    "page": 1,
    "page_size": 50,
    "task_name": "briefing",
    "enabled": 1,
    "completed": 0
})
print(result.content)
""")

The list is scoped to the current project.

Get

run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call("scheduled_task_get", {
    "id": "<scheduled_task_id>"
})
print(result.content)
""")

Update

Only pass fields that should change. When changing time configuration, pass schedule_type and time together.

run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call("scheduled_task_update", {
    "id": "<scheduled_task_id>",
    "enabled": 0
})
print(result.content)
""")

run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call("scheduled_task_update", {
    "id": "<scheduled_task_id>",
    "message_content": "Updated task details",
    "schedule_type": "daily_repeat",
    "time": "10:00"
})
print(result.content)
""")

Delete

run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call("scheduled_task_delete", {
    "id": "<scheduled_task_id>"
})
print(result.content)
""")

Rules

1. Never create scheduler scripts or ask the shell to run cron scripts.
2. Always call scheduled_task_list when the user asks what scheduled tasks exist.
3. After scheduled_task_create, keep the returned id; use it for get/update/delete.
4. Check result.ok before relying on result.content or result.data.
5. Surface tool errors directly; do not silently retry with guessed workspace, topic, or project IDs.