schedule-management

Schedule Management

This skill provides guidance for managing agentapi-proxy schedules that automatically create sessions at specified times or intervals.

Overview

Schedules enable automatic session creation at specific times or on recurring intervals. Each schedule has:

• Name: Descriptive name for the schedule
• Execution Type: One-time (scheduled_at) or recurring (cron_expr)
• Session Config: Environment variables, tags, and initial messages for created sessions
• Status: Active, paused, or completed
• Scope: User-level or team-level access

Core Workflows

Creating a Schedule

One-Time Delayed Execution

First, create a JSON file with your schedule configuration:

cat > schedule.json <<'EOF'
{
  "name": "Code Review Session",
  "scheduled_at": "2025-01-15T14:00:00Z",
  "session_config": {
    "tags": {
      "repository": "org/repo",
      "task": "code-review"
    },
    "params": {
      "message": "Review all open PRs"
    }
  }
}
EOF

agentapi-proxy client schedule create -f schedule.json

Recurring Execution (Cron)

cat > schedule-cron.json <<'EOF'
{
  "name": "Daily Standup Bot",
  "cron_expr": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "session_config": {
    "tags": {
      "repository": "org/standup-bot",
      "type": "standup"
    },
    "params": {
      "message": "Generate daily standup report"
    },
    "environment": {
      "SLACK_WEBHOOK": "https://hooks.slack.com/..."
    }
  }
}
EOF

agentapi-proxy client schedule create -f schedule-cron.json

Timezone Support:

• timezone: IANA timezone name (e.g., "America/New_York", "Europe/London", "Asia/Tokyo")
• Default: "Asia/Tokyo"
• The cron expression is evaluated in the specified timezone

Common Cron Expressions:

• 0 9 * * 1-5 - Every weekday at 9:00 AM
• 0 */6 * * * - Every 6 hours
• 0 0 * * 0 - Every Sunday at midnight
• 30 14 1 * * - First day of every month at 2:30 PM

Response:

{
  "id": "schedule-abc123",
  "name": "Daily Standup Bot",
  "status": "active",
  "cron_expr": "0 9 * * 1-5",
  "created_at": "2024-01-01T12:00:00Z",
  "next_run": "2024-01-02T09:00:00Z"
}

Listing Schedules

# List all schedules
agentapi-proxy client schedule list

# Note: Filtering by status, scope, or team is done by the API automatically
# based on your authentication and permissions

Getting a Specific Schedule

agentapi-proxy client schedule get SCHEDULE_ID

Updating a Schedule

# Update specific fields using apply (patch)
echo '{"status":"paused"}' | agentapi-proxy client schedule apply SCHEDULE_ID

# Or update multiple fields
cat > update.json <<'EOF'
{
  "name": "Updated Schedule Name",
  "status": "paused",
  "cron_expr": "0 10 * * 1-5"
}
EOF

cat update.json | agentapi-proxy client schedule apply SCHEDULE_ID

Deleting a Schedule

agentapi-proxy client schedule delete SCHEDULE_ID

Manually Triggering a Schedule

Note: The trigger command is not yet implemented in the CLI client. Use the API directly if you need to manually trigger a schedule:

curl -X POST https://api.example.com/schedules/SCHEDULE_ID/trigger \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "triggered_at": "2024-01-02T15:30:00Z"
}

Use Cases

1. Daily Reports

{
  "name": "Daily Team Report",
  "cron_expr": "0 17 * * 1-5",
  "session_config": {
    "tags": {
      "type": "report",
      "team": "engineering"
    },
    "params": {
      "message": "Generate end-of-day team report"
    }
  }
}

2. Weekly Code Reviews

{
  "name": "Weekly PR Review",
  "cron_expr": "0 10 * * 1",
  "session_config": {
    "tags": {
      "repository": "org/main-repo",
      "type": "code-review"
    },
    "params": {
      "message": "Review all open PRs from last week"
    }
  }
}

3. Incident Response Drills

{
  "name": "Monthly Incident Drill",
  "cron_expr": "0 14 1 * *",
  "session_config": {
    "tags": {
      "type": "incident-drill",
      "team": "sre"
    },
    "params": {
      "message": "Run incident response drill"
    }
  }
}

4. Delayed Task Execution

{
  "name": "Deploy After Hours",
  "scheduled_at": "2025-01-15T22:00:00Z",
  "session_config": {
    "tags": {
      "repository": "org/production",
      "type": "deployment"
    },
    "params": {
      "message": "Deploy version 2.0 to production"
    }
  }
}

Schedule Status

• active: Schedule is enabled and will execute at the specified time
• paused: Schedule is temporarily disabled
• completed: One-time schedule that has already executed

Access Control

• User Scope: Only the creating user can access and manage the schedule
• Team Scope: All team members can access and manage the schedule
• Admin: Can view and manage all schedules

Template Variables

For schedule sessions, the memory_key map values support Go template rendering with schedule context variables:

• {{.schedule_id}}: Unique identifier of the schedule
• {{.schedule_name}}: Human-readable name of the schedule
• {{.timezone}}: Schedule timezone (IANA format, e.g., Asia/Tokyo)

Example:

{
  "memory_key": {
    "schedule_ref": "{{.schedule_id}}",
    "schedule_name": "{{.schedule_name}}"
  }
}

Note: The params.message field uses static text for schedules, not template rendering. Use the memory_key for dynamic references.

For the complete template variables reference including all available functions, see TEMPLATE_VARIABLES.md.

Reference Documentation

For complete API endpoint documentation and permissions, see:

• API_REFERENCE.md - Complete schedule API reference
• PERMISSIONS.md - Role-based access control details
• TEMPLATE_VARIABLES.md - Go template variables reference