diff --git a/content/manuals/agentic-platform/_index.md b/content/manuals/agentic-platform/_index.md index e26099a48164..379a591b6c8a 100644 --- a/content/manuals/agentic-platform/_index.md +++ b/content/manuals/agentic-platform/_index.md @@ -26,6 +26,10 @@ grid: description: Access, pause, resume, and delete your sandboxes. icon: command-line link: /agentic-platform/sandboxes/ + - title: Schedules + description: Run recurring tasks in a fresh sandbox. + icon: clock + link: /agentic-platform/schedules/ - title: MCP description: Connect predefined or custom MCP servers. icon: cpu-chip diff --git a/content/manuals/agentic-platform/schedules.md b/content/manuals/agentic-platform/schedules.md new file mode 100644 index 000000000000..b7da3ca30ceb --- /dev/null +++ b/content/manuals/agentic-platform/schedules.md @@ -0,0 +1,113 @@ +--- +title: Run tasks on a schedule +linkTitle: Schedules +description: Schedule recurring agent tasks in Docker Agentic Platform, with a fresh sandbox for each run, MCP tools for external services, and a time limit for cleanup. +keywords: docker agentic platform, schedules, cron, sandboxes, automation, mcp +weight: 25 +--- + +Schedules run a prompt or command in a sandbox at a recurring time. Use them +for recurring development work such as reviewing dependencies, triaging issues, +or summarizing pull requests, without starting an agent manually or keeping a +sandbox running between tasks. + +Each run creates a fresh sandbox with the kit, compute size, credentials, and +tools saved in the schedule. When the task finishes, the sandbox is deleted. +The time limit also deletes the sandbox if the task hasn't finished. + +## Prepare tools and credentials + +Choose a [kit](kits.md) that can run your task without interactive input. Save +the credentials you need in [Secrets](secrets.md), including model provider +API keys, service tokens, or custom secrets. + +If you need to connect to external services, connect and authorize the relevant +[MCP servers](mcp.md) before creating the schedule. You can select these tools +for scheduled runs, including custom servers connected through the MCP gateway. +If the predefined servers don't cover your service, create your own MCP server +and [add its remote endpoint](mcp.md#add-a-server-by-url). The endpoint must +support streamable HTTP. + +If you need credentials for a custom CLI or API integration, use the schedule +API to select [custom secrets](secrets.md#add-a-custom-secret). The Console +schedule form doesn't offer custom-secret selection. +Use an MCP server for integrations you configure through this form. When you +configure a schedule through the API, include the required CLI in your kit and use the +secret's placeholder where the client expects a credential. Check that your +[network policy](policies.md) permits access to the service. Don't put secret +values in the task's prompt. + +## Create a schedule + +1. Open **Schedules** in the Console and select **New schedule**. +2. Enter a **Name** and, optionally, a **Description**. +3. Under **Agent**, choose a kit and check its credential status. Add any + missing credentials through **Secrets**. +4. Under **Sandbox**, choose the network **Policy**, **Tools**, and **Compute** + size for each run. Connect or reconnect selected tools if prompted. +5. Choose a **Time limit** for each sandbox. This time to live (TTL) limits + how long a task can run. The available choices are 1, 4, 8, and 24 hours. + A task still running at expiry is stopped, its sandbox is deleted, and the + run counts as failed. +6. Under **Schedule**, select a **Runs** preset and **Timezone**. For a cron + expression, choose **Custom**. Review **Next runs** to check the timing. +7. In **Prompt**, enter the prompt for an agent kit, or the command for a + command kit such as Shell. Specify where the task should save or send its + results, because files left in the sandbox are deleted with it. +8. Select **Save schedule**. + +Custom cron expressions have five fields: minute, hour, day of month, month, +and day of week. For example, `0 9 * * 1-5` runs at 09:00 every weekday in the +selected time zone. + +## Use a custom kit + +If you use a custom agent kit, configure its prompt template to run the agent +without interactive input. Docker Agentic Platform uses this template to build +the command for each scheduled run, substituting the prompt you entered into +the template's arguments. The image's `ENTRYPOINT` or `CMD` alone doesn't define +how a scheduled prompt is passed to the agent. + +## Example: Weekly issue triage + +To reduce time spent asking for missing details in bug reports, schedule an +agent to review issues and request reproduction steps. Connect an MCP server +that can read GitHub issues and comments and add comments to issues. Authorize +access to the repository, then select the server under **Tools**. If the +predefined servers don't provide these tools, add a custom remote server. + +Choose an agent kit, set the cadence to `0 9 * * 1`, and select your team's +time zone to run every Monday at 09:00. Use a prompt such as: + +```text +Use the connected GitHub tools to review open issues labeled "bug" in +OWNER/REPOSITORY. For each issue, read its description and comments and +check whether it includes reproduction steps, expected behavior, actual +behavior, and version information. +If details are missing and no comment has already requested them, add one +comment asking for the specific missing details. Skip issues awaiting a +response to an earlier request. Don't close issues or change their labels. +If a tool fails, stop and report the error instead of guessing. +``` + +Replace `OWNER/REPOSITORY` with your repository and `bug` with the label your +team uses for bug reports. The comments stay with the issues after the sandbox +is deleted, so reporters can respond and maintainers can follow up. The +connected server must provide tools to read issues and their comments and +add comments. Test the task with **Run now** before relying on its cadence. + +## Manage schedules and review runs + +Open a schedule to review its settings in **Overview** and its run history in +**Runs**. The history shows when each run started, its result, and duration. +Use **Run now** to trigger a run without waiting for the next scheduled time. + +Use **Edit schedule** to change the task or its sandbox settings. Pause a +schedule to suspend future scheduled runs, and resume it when needed. You can +also duplicate a schedule or delete it when you no longer need it. + +The schedule saves the kit and selected resources when you save its settings. +After adding credentials, updating a kit, or changing a custom MCP server's +URL, edit and save the schedule to use those changes. If a run fails, check +its reported error and confirm that its credentials, tools, and network access +are still valid.