From d1c95dc48058086130bac1b151034540cbf2b640 Mon Sep 17 00:00:00 2001 From: openhands Date: Wed, 26 Mar 2025 13:52:35 +0000 Subject: [PATCH] Add documentation for scheduled tool execution feature --- .../schedule-tool-execution/schedule_tool.js | 51 ++++ .../schedule-tool-execution/schedule_tool.py | 41 ++++ pages/home/use-tools/_meta.ts | 1 + .../use-tools/schedule-tool-execution.mdx | 232 ++++++++++++++++++ 4 files changed, 325 insertions(+) create mode 100644 examples/code/home/use-tools/schedule-tool-execution/schedule_tool.js create mode 100644 examples/code/home/use-tools/schedule-tool-execution/schedule_tool.py create mode 100644 pages/home/use-tools/schedule-tool-execution.mdx diff --git a/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.js b/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.js new file mode 100644 index 00000000..64157703 --- /dev/null +++ b/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.js @@ -0,0 +1,51 @@ +import { Arcade } from '@arcade-ai/arcade'; + +// Initialize the Arcade client +const arcade = new Arcade(); + +// Schedule a tool execution for 1 hour in the future +const futureTime = new Date(); +futureTime.setHours(futureTime.getHours() + 1); + +// Schedule the GitHub.CreateIssue tool to run at the specified time +async function scheduleToolExecution() { + try { + const scheduledExecution = await arcade.tools.schedule({ + toolName: 'Github.CreateIssue', + input: { + owner: 'ArcadeAI', + repo: 'Docs', + title: 'Scheduled issue creation', + body: 'This issue was created by a scheduled tool execution' + }, + runAt: futureTime, + userId: 'user@example.com' // Optional: specify the user ID for attribution + }); + + console.log(`Scheduled execution ID: ${scheduledExecution.id}`); + console.log(`Status: ${scheduledExecution.status}`); + console.log(`Will run at: ${scheduledExecution.runAt}`); + + // List all scheduled tool executions + const scheduledTools = await arcade.tools.listScheduled(); + console.log(`Total scheduled executions: ${scheduledTools.items.length}`); + + // Get details of a specific scheduled execution + const executionDetails = await arcade.tools.getScheduled(scheduledExecution.id); + console.log(`Tool: ${executionDetails.toolName}`); + console.log(`Status: ${executionDetails.executionStatus}`); + + // After execution, you can check the attempts and output + if (executionDetails.attempts && executionDetails.attempts.length > 0) { + const latestAttempt = executionDetails.attempts[0]; + console.log(`Success: ${latestAttempt.success}`); + if (latestAttempt.success) { + console.log(`Output: ${JSON.stringify(latestAttempt.output)}`); + } + } + } catch (error) { + console.error('Error scheduling tool execution:', error); + } +} + +scheduleToolExecution(); \ No newline at end of file diff --git a/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.py b/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.py new file mode 100644 index 00000000..233be54c --- /dev/null +++ b/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.py @@ -0,0 +1,41 @@ +from arcade import Arcade +from datetime import datetime, timedelta, timezone + +# Initialize the Arcade client +arcade = Arcade() + +# Schedule a tool execution for 1 hour in the future +future_time = datetime.now(timezone.utc) + timedelta(hours=1) + +# Schedule the GitHub.CreateIssue tool to run at the specified time +scheduled_execution = arcade.tools.schedule( + tool_name="Github.CreateIssue", + input={ + "owner": "ArcadeAI", + "repo": "Docs", + "title": "Scheduled issue creation", + "body": "This issue was created by a scheduled tool execution" + }, + run_at=future_time, + user_id="user@example.com" # Optional: specify the user ID for attribution +) + +print(f"Scheduled execution ID: {scheduled_execution.id}") +print(f"Status: {scheduled_execution.status}") +print(f"Will run at: {scheduled_execution.run_at}") + +# List all scheduled tool executions +scheduled_tools = arcade.tools.list_scheduled() +print(f"Total scheduled executions: {len(scheduled_tools.items)}") + +# Get details of a specific scheduled execution +execution_details = arcade.tools.get_scheduled(scheduled_execution.id) +print(f"Tool: {execution_details.tool_name}") +print(f"Status: {execution_details.execution_status}") + +# After execution, you can check the attempts and output +if execution_details.attempts: + latest_attempt = execution_details.attempts[0] + print(f"Success: {latest_attempt.success}") + if latest_attempt.success: + print(f"Output: {latest_attempt.output}") \ No newline at end of file diff --git a/pages/home/use-tools/_meta.ts b/pages/home/use-tools/_meta.ts index 1c4af08a..144fa7c3 100644 --- a/pages/home/use-tools/_meta.ts +++ b/pages/home/use-tools/_meta.ts @@ -1,6 +1,7 @@ export default { "tools-overview": "Introduction", "call-tools-directly": "Tool execution", + "schedule-tool-execution": "Scheduled execution", "call-tools-with-models": "Tool Augmented Generation", "tool-choice": "Tool Choice", "specify-tools": "Selecting tools", diff --git a/pages/home/use-tools/schedule-tool-execution.mdx b/pages/home/use-tools/schedule-tool-execution.mdx new file mode 100644 index 00000000..1a078307 --- /dev/null +++ b/pages/home/use-tools/schedule-tool-execution.mdx @@ -0,0 +1,232 @@ +--- +title: "Schedule tool execution" +description: "Learn how to schedule tools to run at a future time with Arcade.dev" +--- + +import { Steps, Tabs } from "nextra/components"; + +# Schedule tool execution + +In this guide, you'll learn how to schedule tools to run at a future time with Arcade.dev. + +Scheduled tool execution allows you to set up tools to run automatically at a specific time in the future. This is useful for tasks like sending notifications, generating reports, or performing maintenance operations on a schedule. + + + +### Prerequisites + +- [Set up Arcade.dev](/home/quickstart) +- Create an Arcade.dev [API key](/home/api-keys), if you haven't already +- Understand how to [call tools directly](/home/use-tools/call-tools-directly) + +### Set environment variables + +You can find your Arcade.dev API key in one of these locations: + +- [Arcade.dev Dashboard](https://api.arcade.dev/dashboard/api-keys) under API Keys +- `~/.arcade/credentials.yaml` + +Export your Arcade.dev API key as an environment variable: +```bash +export ARCADE_API_KEY= +``` + +### Initialize the client + +Import and initialize the Arcade.dev client. The client automatically uses the `ARCADE_API_KEY` environment variable. + + + +```python file=/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.py#L1-L3 +``` + + +```js file=/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.js#L1-L3 +``` + + +```bash +# No client initialization needed for REST API +# Just include your API key in the Authorization header +``` + + + +### Schedule a tool execution + +Let's schedule the `Github.CreateIssue` tool to run at a future time. You'll need to specify: + +1. The tool name +2. The input parameters for the tool +3. The time when the tool should run +4. Optionally, a user ID for attribution + + + +```python file=/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.py#L5-L19 +``` + + +```js file=/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.js#L5-L19 +``` + + +```bash +# Schedule tool execution +curl -X POST "https://api.arcade.dev/v1/tools/execute" \ + -H "Authorization: Bearer $ARCADE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "user_id": "user@example.com", + "tool_name": "Github.CreateIssue", + "input": { + "owner": "ArcadeAI", + "repo": "Docs", + "title": "Scheduled issue creation", + "body": "This issue was created by a scheduled tool execution" + }, + "run_at": "2025-01-09T15:00:00-08:00" + }' +``` + +Response: +```json +{ + "id": "te_2ur7QJuXu2eEHZWvPb6QBmEN76D", + "execution_id": "tc_2ur7QLXCUFsbo0HDY5ZAaM3mwei", + "execution_type": "scheduled", + "run_at": "2025-01-09T15:00:00-08:00", + "status": "pending", + "success": true +} +``` + + + +The response includes an ID that you can use to check the status of the scheduled execution later. + +### List scheduled tool executions + +You can retrieve a list of all scheduled tool executions to monitor their status. + + + +```python file=/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.py#L21-L23 +``` + + +```js file=/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.js#L21-L23 +``` + + +```bash +# List scheduled tool executions +curl -X GET "https://api.arcade.dev/v1/scheduled_tools" \ + -H "Authorization: Bearer $ARCADE_API_KEY" +``` + +Response: +```json +{ + "items": [ + { + "id": "te_2ur7QJuXu2eEHZWvPb6QBmEN76D", + "created_at": "2025-03-26T13:13:41Z", + "updated_at": "2025-03-26T13:13:42Z", + "execution_type": "scheduled", + "execution_status": "success", + "tool_name": "Github.CreateIssue", + "toolkit_name": "Github", + "user_id": "user@example.com", + "run_at": "2025-01-09T15:00:00-08:00", + "started_at": "2025-03-26T13:13:42Z", + "finished_at": "2025-03-26T13:13:42Z" + } + ], + "limit": 25, + "offset": 0, + "page_count": 1, + "total_count": 1 +} +``` + + + +### Get details of a scheduled execution + +You can retrieve detailed information about a specific scheduled execution using its ID. + + + +```python file=/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.py#L25-L34 +``` + + +```js file=/examples/code/home/use-tools/schedule-tool-execution/schedule_tool.js#L25-L36 +``` + + +```bash +# Get details of a scheduled tool execution +curl -X GET "https://api.arcade.dev/v1/scheduled_tools/te_2ur7QJuXu2eEHZWvPb6QBmEN76D" \ + -H "Authorization: Bearer $ARCADE_API_KEY" +``` + +Response: +```json +{ + "id": "te_2ur7QJuXu2eEHZWvPb6QBmEN76D", + "created_at": "2025-03-26T13:13:41Z", + "updated_at": "2025-03-26T13:13:42Z", + "execution_type": "scheduled", + "execution_status": "success", + "tool_name": "Github.CreateIssue", + "toolkit_name": "Github", + "user_id": "user@example.com", + "run_at": "2025-01-09T15:00:00-08:00", + "started_at": "2025-03-26T13:13:42Z", + "finished_at": "2025-03-26T13:13:42Z", + "input": { + "owner": "ArcadeAI", + "repo": "Docs", + "title": "Scheduled issue creation", + "body": "This issue was created by a scheduled tool execution" + }, + "attempts": [ + { + "id": "ta_2ur7QPkwaPgfh6DCemcQ9Nmxj5z", + "started_at": "2025-03-26T13:13:42Z", + "finished_at": "2025-03-26T13:13:42Z", + "success": true, + "output": { + "value": "{JSON containing result details}" + } + } + ] +} +``` + + + +The response includes detailed information about the scheduled execution, including: + +- The execution status +- The input parameters +- The time it was scheduled to run +- The time it actually ran (if it has run) +- The output of the execution (if it has run) +- Any attempts that were made to run the tool + +### Use cases for scheduled tool execution + +Let's explore some common use cases for scheduled tool execution: + +1. **Automated reporting**: Schedule tools to generate and send reports at regular intervals +2. **Maintenance tasks**: Schedule cleanup operations or database maintenance during off-peak hours +3. **Delayed notifications**: Schedule notifications to be sent at appropriate times +4. **Workflow automation**: Trigger the next step in a workflow after a specified delay +5. **Scheduled content updates**: Automatically update content or publish posts at optimal times + +By scheduling tool executions, you can automate repetitive tasks and ensure they run at the most appropriate times. + + \ No newline at end of file