feat(scheduledrun): add cron-based agent execution by 0xLeo258 · Pull Request #2097 · kagent-dev/kagent

0xLeo258 · 2026-06-29T07:05:50Z

Adds the v1alpha2 ScheduledRun CRD, controller scheduler, REST API, metrics, and UI flow for creating, listing, viewing, updating, and manually triggering scheduled agent runs.

ScheduledRun targets resolve through a shared same-namespace Agent/SandboxAgent reference path. Suspended runs do not schedule next executions and cannot be manually triggered until resumed.

RunStatus unifies dispatch and outcome into a single enum (DispatchFailed/Pending/Succeeded/Failed/Timeout); RunHistoryEntry is StartTime, EndTime, SessionID, Status, Message. The outcome poller is restart-safe: Pending entries are resumed on Start so a pod restart between dispatch and terminal resolution does not leave entries stuck Pending.

CRD admission pattern annotations enforce DNS-label constraints, so duplicate handler-side DNS validators are removed. Service creation is enabled for agents.x-k8s.io Sandboxes so SandboxAgent A2A endpoints are reachable in real e2e deployments.

Includes CRD/Helm generation plus focused unit and e2e coverage.

Copilot

Pull request overview

Introduces a new v1alpha2 ScheduledRun capability to execute Agents/SandboxAgents on a cron schedule, spanning CRD + controller scheduler, REST API endpoints, UI creation/list/detail flows, and supporting metrics/RBAC updates.

Changes:

Adds ScheduledRun CRD/types plus controller scheduler/controller logic and Prometheus metrics.
Adds REST API surface for ScheduledRuns (list/get/create/update/delete/trigger) and UI pages/components to manage schedules and view run history.
Updates RBAC and agent listing to support schedulable agent selection and ScheduledRun resource access.

Reviewed changes

Copilot reviewed 35 out of 37 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
ui/src/types/index.ts	Adds frontend types for ScheduledRun CRD, status, and run history.
ui/src/lib/scheduledRuns.ts	UI helpers for rendering ScheduledRun target refs and display status.
ui/src/lib/formatDateTime.ts	Adds a shared datetime formatting helper for schedule/run history views.
ui/src/components/schedules/ScheduledRunList.tsx	New schedules list view with trigger/edit/delete actions.
ui/src/components/schedules/RunHistoryTable.tsx	New run-history table for ScheduledRun detail page.
ui/src/components/Header.tsx	Adds navigation entries for Scheduled Runs and “New Scheduled Run”.
ui/src/components/DeleteAgentButton.tsx	Adds toast feedback for agent deletion success/failure.
ui/src/app/schedules/page.tsx	Adds `/schedules` route entrypoint.
ui/src/app/schedules/new/page.tsx	Adds create/edit ScheduledRun form page.
ui/src/app/schedules/[namespace]/[name]/page.tsx	Adds ScheduledRun detail page with run history and trigger/suspend actions.
ui/src/app/actions/scheduledRuns.ts	Adds server actions to call ScheduledRun REST endpoints and revalidate UI paths.
ui/src/app/actions/agents.ts	Adds `getSchedulableAgents()` to list agents without AgentHarness rows.
helm/kagent/templates/rbac/writer-role.yaml	Grants write permissions for ScheduledRun resources/finalizers.
helm/kagent/templates/rbac/getter-role.yaml	Grants get/list/watch and status access for ScheduledRuns.
helm/kagent-crds/templates/kagent.dev_scheduledruns.yaml	Helm-templated ScheduledRun CRD manifest.
go/go.mod	Adds robfig/cron dependency for scheduler and API validation.
go/go.sum	Records robfig/cron module checksums.
go/core/test/e2e/scheduledrun_api_test.go	Adds end-to-end REST API lifecycle tests for ScheduledRuns.
go/core/pkg/app/app.go	Wires ScheduledRun scheduler/controller into manager and HTTP server.
go/core/internal/scheduledrun/target.go	Shared utilities for resolving/validating ScheduledRun targets.
go/core/internal/metrics/scheduledrun.go	Adds Prometheus metrics for dispatch/outcomes/durations/active schedules.
go/core/internal/httpserver/server.go	Adds ScheduledRuns routes and handler wiring in HTTP server.
go/core/internal/httpserver/handlers/test_helpers_test.go	Registers ScheduledRun types in handler test scheme.
go/core/internal/httpserver/handlers/scheduledruns.go	Implements ScheduledRuns REST handlers + schedule validation + trigger endpoint.
go/core/internal/httpserver/handlers/scheduledruns_test.go	Adds unit tests for ScheduledRuns handler behaviors.
go/core/internal/httpserver/handlers/handlers.go	Adds ScheduledRuns handler to handlers bundle (conditional on trigger availability).
go/core/internal/httpserver/handlers/agents.go	Adds query param to exclude AgentHarness rows from agent list responses.
go/core/internal/httpserver/handlers/agents_test.go	Adds tests for excluding AgentHarness and ScheduledRun interactions with deletions.
go/core/internal/controller/scheduledrun_scheduler.go	Implements cron scheduling, dispatch, run-history recording, and outcome polling.
go/core/internal/controller/scheduledrun_scheduler_test.go	Adds scheduler unit tests for scheduling and runOnce behavior.
go/core/internal/controller/scheduledrun_controller.go	Adds ScheduledRun controller reconcile logic (validation, nextRunTime, Accepted condition).
go/core/internal/controller/scheduledrun_controller_test.go	Adds controller unit tests for acceptance/rejection scenarios.
go/core/internal/a2a/agent_client_registry.go	Adds route-key based send method for A2A client registry lookups.
go/core/internal/a2a/a2a_handler_mux.go	Exposes helpers to compute route keys for Agent vs SandboxAgent.
go/api/v1alpha2/zz_generated.deepcopy.go	Updates generated deep-copy code for new ScheduledRun API types.
go/api/v1alpha2/scheduledrun_types.go	Adds ScheduledRun API types, validation markers, and constants.
go/api/config/crd/bases/kagent.dev_scheduledruns.yaml	Adds controller-gen base CRD for ScheduledRun.

Files not reviewed (1)

go/api/v1alpha2/zz_generated.deepcopy.go: Generated file

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

EItanya

This PR is looking good overall, but there are definitely a few really important pieces that need looking at. I also haven't had a chance to dive deep on the cron logic yet, which I will do.

I will leave UI review here to @peterj

EItanya · 2026-06-29T15:08:11Z

+	// AgentRef is a reference to the Agent or SandboxAgent to execute. If
+	// Namespace is empty it defaults to the ScheduledRun's namespace.
+	// +required
+	AgentRef AgentReference `json:"agentRef"`


Can we use a TypedObjectReference here so that we can potentially support more in the future?

Hi @EItanya,
Do you mean that we can have MCP crons in the future? Would love to change so

EItanya · 2026-07-01T13:44:30Z

+	// +optional
+	// +kubebuilder:validation:MaxLength=63
+	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
+	Namespace string `json:"namespace,omitempty"`


Why do we accept Namespace if we don't actually allow cross namespace references? I think we should omit it until we decide we want it

Hi @EItanya,
Do you think it valuable that we allow cross-namespace references?

We now use TypedObjectReference. I think keeping the namespace semantics within the reference makes the API more extensible, but the question is whether we actually want to support it.

What we can do it use a LocalObjectReference which means we can always add it later if we want

EItanya · 2026-07-01T13:53:16Z

@@ -68,7 +68,8 @@ func (h *AgentsHandler) handleListAgents(w ErrorResponseWriter, r *http.Request,
 		return
 	}

-	agentsWithID, err := h.listAgentResponses(r.Context(), log, opts...)
+	includeAgentHarness := r.URL.Query().Get("includeAgentHarness") != "false"


If we are going to add filters to this page I would much rather do it generically than using oneoff filters like this. Can you omit this from this PR and do a separate one with that change?

0xLeo258 · 2026-07-02T00:20:56Z

Hi @EItanya, thanks for the dedicated review.
I will do a comprehensive improvement for this PR.

0xLeo258 · 2026-07-21T05:59:50Z

Hi @EItanya,
Looking forward to your review of the field definitions.
Then I shall continue refining the cron logic

EItanya · 2026-07-21T19:11:06Z

Hi @EItanya, Looking forward to your review of the field definitions. Then I shall continue refining the cron logic

Hey there, sorry for taking so long, We had an offsite last week and then i had a couple days PTO, just getting back to it now

EItanya

Things are looking great overall, I want to dig into the scheduler itself which I will do next :)

EItanya · 2026-07-21T19:34:42Z

+	// +optional
+	StartTime metav1.Time `json:"startTime"`


Why is this optional?

EItanya · 2026-07-21T19:35:49Z

+// DefaultScheduledRunMaxRunHistory is used when spec.maxRunHistory is omitted.
+const DefaultScheduledRunMaxRunHistory = 10


Do we also store the rest in the DB so they're available if the user specifically wants to check them for any reason?

EItanya · 2026-07-21T19:38:16Z

+	// are still allowed.
+	// +optional
+	// +kubebuilder:default=false
+	Suspend bool `json:"suspend,omitempty"`


Suspended? This describes a state

EItanya · 2026-07-21T19:54:17Z

+	if err := scheduledrun.ValidateTargetNamespaceAccess(ctx, r.Kube, sr.Namespace, target); err != nil {
+		if errors.Is(err, scheduledrun.ErrTargetAccessDenied) {
+			return ctrl.Result{}, r.rejectScheduledRun(ctx, &sr, scheduledRunReasonTargetReferenceNotAllowed, err.Error())
+		}
+		return ctrl.Result{}, fmt.Errorf("failed to validate target namespace access: %w", err)
+	}


Same comment about using LocalObjectReference

EItanya · 2026-07-21T19:58:04Z

+	// policy to permit the ScheduledRun's namespace.
+	// +required
+	// +kubebuilder:validation:XValidation:rule="has(self.apiGroup) && self.apiGroup == 'kagent.dev'",message="targetRef.apiGroup must be kagent.dev"
+	TargetRef corev1.TypedObjectReference `json:"targetRef"`


LocalObjectReference

EItanya · 2026-07-21T19:59:04Z

 		t := true
 		resp.ReadOnly = &t
 	}
+	if scheduledRunReadOnly {


Maybe read-only should actually be defined on the ScheduledRun. Seems to me that a user could interact

Read-only behavior is now defined by ScheduledRun.spec.allowSessionInteraction, defaulting to false. I think that's more extensible.

EItanya · 2026-07-21T20:03:41Z

+	}
+	normalizeScheduledRun(&sr)
+
+	if apiErr := h.validateScheduledRunObject(r, &sr); apiErr != nil {


I don't think we need to do this, it's really a premature optimization. We can reuse the logic from the controller if we really want, but I think it's also fine to just try and create and then surface errors from the object to the user, or let them check the object after it's been created. I'd rather start smaller

EItanya · 2026-07-21T20:04:32Z

+		}
+		existing.Spec = updatedSpec
+
+		if err := h.KubeClient.Update(r.Context(), existing); err != nil {


Any reason not to use server side apply here? This is also skipping metadata updates to things like labels or annotations

0xLeo258 · 2026-07-22T05:21:09Z

Things are looking great overall, I want to dig into the scheduler itself which I will do next :)

Hi, thanks for the review!
I'll submit an updated version soon.
Let me address the scheduler issues first before requesting another review.

peterj · 2026-07-28T14:51:54Z

+        getScheduledRun(name, namespace),
+        getScheduledRunExecutions(name, namespace, undefined, undefined, EXECUTIONS_PAGE_SIZE),
+      ]);
+      if (response.error || !response.data) {


do we need to check for errors from executionsResponse?

Now it checks executionsResponse.error and surface it through the page error handling.

peterj · 2026-07-28T14:56:22Z

+    const key = executionKey(execution);
+    if (!merged.has(key)) merged.set(key, execution);
+  }
+  return [...merged.values()].sort(


return the existing array if there we're no changes; otherwise you're always returning the new array here and re-triggering the useEffect on line 109

peterj · 2026-07-28T14:59:26Z

+  };
+
+  const handleDelete = async () => {
+    try {


set the isDeleting and show a deleting spinner in the dialog/disable the delete button while in progress

The dialog now tracks isDeleting, disables both actions while deletion is in progress, and shows a spinner with “Deleting...”

peterj · 2026-07-28T15:16:40Z

+
+  const isFormDisabled = state.isSubmitting || state.isLoading;
+
+  if (state.isSubmitting) {


you probably don't need this check here as you're using isFormDisabled in the form below to disable controls

peterj · 2026-07-28T15:23:02Z

i tried scheduling a run -- it worked. then I manually triggered it and also waited for the schedule to trigger it, however in both cases I see empty chats.

Might be this (from the controller):

ddr":"10.244.0.28:55926","status":200,"duration":0.002538917}
{"level":"debug","ts":"2026-07-28T15:21:50Z","logger":"http","msg":"Request started","method":"GET","path":"/api/sessions/019fa94f-b100-7c5d-954a-fdd5151ae779/shares","remote_addr":"10.244.0.28:55926"}
2026/07/28 15:21:50 http: panic serving 10.244.0.28:55926: runtime error: invalid memory address or nil pointer dereference
goroutine 14969 [running]:
net/http.(*conn).serve.func1()
	/usr/lib/go/src/net/http/server.go:1907 +0xac
panic({0x1be17e0?, 0x39e6f70?})
	/usr/lib/go/src/runtime/panic.go:860 +0x12c
github.com/kagent-dev/kagent/go/core/internal/httpserver/handlers.(*SessionSharesHandler).HandleListSessionShares(0x0, {0xffff3a3654b8, 0x2454db7ce468}, 0x2454db9552c0)
	/workspace/core/internal/httpserver/handlers/session_shares.go:115 +0x208
github.com/kagent-dev/kagent/go/core/internal/httpserver.(*HTTPServer).setupRoutes.adaptHandler.func19({0x21a2d60?, 0x2454db7ce468?}, 0x2454db9552c0?)
	/workspace/core/internal/httpserver/server.go:402 +0x98
net/http.HandlerFunc.ServeHTTP(0x2454dc0fcf08?, {0x21a2d60?, 0x2454db7ce468?}, 0x1fb23a0?)
	/usr/lib/go/src/net/http/server.go:2286 +0x38
github.com/kagent-dev/kagent/go/core/internal/httpserver.errorHandlerMiddleware.func1({0x21a2d90, 0x2454db7ce438}, 0x2454db9552c0)
	/workspace/core/internal/httpserver/middleware_error.go:24 +0x8c
net/http.HandlerFunc.ServeHTTP(0x21b71f8?, {0x21a2d90?, 0x2454db7ce438?}, 0x20173c4?)
	/usr/lib/go/src/net/http/server.go:2286 +0x38
github.com/kagent-dev/kagent/go/core/internal/httpserver.loggingMiddleware.func1({0x21a68b0, 0x2454dbb186c0}, 0x2454db955180)
	/workspace/core/internal/httpserver/middleware.go:40 +0x490
net/http.HandlerFunc.ServeHTTP(0x1e32b00?, {0x21a68b0?, 0x2454dbb186c0?}, 0xc?)
	/usr/lib/go/src/net/http/server.go:2286 +0x38
github.com/kagent-dev/kagent/go/core/internal/httpserver.contentTypeMiddleware.func1({0x21a68b0?, 0x2454dbb186c0?}, 0x2454db955180?)
	/workspace/core/internal/httpserver/middleware.go:94 +0x11c
net/http.HandlerFunc.ServeHTTP(0x2454dbce0dc4?, {0x21a68b0?, 0x2454dbb186c0?}, 0x94d3c?)
	/usr/lib/go/src/net/http/server.go:2286 +0x38
github.com/kagent-dev/kagent/go/core/internal/httpserver.(*HTTPServer).scheduledRunSessionMiddleware-fm.(*HTTPServer).scheduledRunSessionMiddleware.func1({0x21a68b0, 0x2454dbb186c0}, 0x2454db955180)
	/workspace/core/internal/httpserver/middleware.go:200 +0x80
net/http.HandlerFunc.ServeHTTP(0x2454dc0fd338?, {0x21a68b0?, 0x2454dbb186c0?}, 0x94d3c?)
	/usr/lib/go/src/net/http/server.go:2286 +0x38
github.com/kagent-dev/kagent/go/core/internal/httpserver.(*HTTPServer).shareTokenMiddleware-fm.(*HTTPServer).shareTokenMiddleware.func1({0x21a68b0, 0x2454dbb186c0}, 0x2454db955180)
	/workspace/core/internal/httpserver/middleware.go:107 +0x410
net/http.HandlerFunc.ServeHTTP(0x2454db955040?, {0x21a68b0?, 0x2454dbb186c0?}, 0x2454dbcf1d00?)
	/usr/lib/go/src/net/http/server.go:2286 +0x38
github.com/kagent-dev/kagent/go/core/internal/httpserver.(*HTTPServer).setupRoutes.AuthnMiddleware.func83.1({0x21a68b0, 0x2454dbb186c0}, 0x2454db955040)
	/workspace/core/pkg/auth/auth.go:92 +0x168
net/http.HandlerFunc.ServeHTTP(0x2454dbe2a7e0?, {0x21a68b0?, 0x2454dbb186c0?}, 0x36a5e4?)
	/usr/lib/go/src/net/http/server.go:2286 +0x38
github.com/kagent-dev/kagent/go/core/internal/httpserver.wsAuthQueryMiddleware.func1({0x21a68b0, 0x2454dbb186c0}, 0x2454db955040)
	/workspace/core/internal/httpserver/server.go:396 +0x1bc
net/http.HandlerFunc.ServeHTTP(0x2454db954f00?, {0x21a68b0?, 0x2454dbb186c0?}, 0x0?)
	/usr/lib/go/src/net/http/server.go:2286 +0x38
github.com/gorilla/mux.(*Router).ServeHTTP(0x2454dacfc540, {0x21a68b0, 0x2454dbb186c0}, 0x2454db954dc0)
	/root/go/pkg/mod/github.com/gorilla/mux@v1.8.1/mux.go:212 +0x188
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp.(*middleware).serveHTTP(0x2454dad5a0c0, {0x21a2710, 0x2454dbcf8870}, 0x2454db954c80, {0x2186e20, 0x2454dacfc540})
	/root/go/pkg/mod/go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp@v0.69.0/handler.go:185 +0xf50
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp.NewMiddleware.func2.1({0x21a2710?, 0x2454dbcf8870?}, 0x2454dab771a8?)
	/root/go/pkg/mod/go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp@v0.69.0/handler.go:67 +0x3c
net/http.HandlerFunc.ServeHTTP(0x0?, {0x21a2710?, 0x2454dbcf8870?}, 0x2454dc0fdb50?)
	/usr/lib/go/src/net/http/server.go:2286 +0x38
net/http.serverHandler.ServeHTTP({0x2454db7d5a80?}, {0x21a2710?, 0x2454dbcf8870?}, 0x6?)
	/usr/lib/go/src/net/http/server.go:3311 +0xb0
net/http.(*conn).serve(0x2454daad75f0, {0x21a9d10, 0x2454daf73b60})

onematchfox · 2026-08-04T07:56:59Z

Might be this (from the controller):

That nil reference error should be resolved by #2363

0xLeo258 · 2026-08-04T08:02:50Z

Might be this (from the controller):

That nil reference error should be resolved by #2363

Thanks @onematchfox !
We're currently refining the implementation and will update this rebased PR over the next couple of days.

Signed-off-by: 0xLeo258 <noixe0312@gmail.com>

Signed-off-by: JacksonWang <jackson.wang03@sap.com>

Copilot AI review requested due to automatic review settings June 29, 2026 07:05

0xLeo258 requested review from EItanya, ilackarms, iplay88keys, jmhbh, peterj, supreme-gg-gg and yuval-k as code owners June 29, 2026 07:05

github-actions Bot added the enhancement New feature or request label Jun 29, 2026

Copilot started reviewing on behalf of 0xLeo258 June 29, 2026 07:06 View session

Copilot AI reviewed Jun 29, 2026

View reviewed changes

Comment thread go/core/internal/controller/scheduledrun_scheduler.go Outdated

Comment thread go/core/internal/httpserver/handlers/scheduledruns.go Outdated

Comment thread ui/src/lib/formatDateTime.ts

0xLeo258 force-pushed the feat/scheduled-run branch from f91aa90 to 71b93d8 Compare June 29, 2026 07:17

0xLeo258 mentioned this pull request Jun 29, 2026

[FEATURE] Add cronjob for agents #1821

Open

3 tasks

0xLeo258 force-pushed the feat/scheduled-run branch from 9442180 to a8fdf4b Compare June 29, 2026 23:17

EItanya reviewed Jul 1, 2026

View reviewed changes

0xLeo258 requested a review from a team as a code owner July 13, 2026 22:53

0xLeo258 force-pushed the feat/scheduled-run branch 2 times, most recently from 2aeaa73 to 20bad21 Compare July 13, 2026 23:13

0xLeo258 requested a review from EItanya July 21, 2026 05:56

EItanya reviewed Jul 21, 2026

View reviewed changes

0xLeo258 force-pushed the feat/scheduled-run branch from 260ff9c to f9de17f Compare July 28, 2026 08:01

0xLeo258 requested a review from Charlesthebird as a code owner July 28, 2026 08:01

peterj reviewed Jul 28, 2026

View reviewed changes

0xLeo258 force-pushed the feat/scheduled-run branch from f9de17f to 06bd48a Compare August 10, 2026 05:28

feat: add ScheduledRun support

7e6ad0d

Signed-off-by: 0xLeo258 <noixe0312@gmail.com>

0xLeo258 force-pushed the feat/scheduled-run branch from 06bd48a to 7e6ad0d Compare August 10, 2026 07:59

EItanya and others added 4 commits August 10, 2026 10:44

Merge branch 'main' into feat/scheduled-run

f13c8de

Merge branch 'main' into feat/scheduled-run

41d4138

Merge remote-tracking branch 'upstream/main' into feat/scheduled-run

e78c303

fix: remove scheduled run test lint error

e348a34

Signed-off-by: JacksonWang <jackson.wang03@sap.com>

		// DefaultScheduledRunMaxRunHistory is used when spec.maxRunHistory is omitted.
		const DefaultScheduledRunMaxRunHistory = 10


		const isFormDisabled = state.isSubmitting \|\| state.isLoading;

		if (state.isSubmitting) {

Uh oh!

Conversation

0xLeo258 commented Jun 29, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

EItanya left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

0xLeo258 commented Jul 2, 2026

Uh oh!

0xLeo258 commented Jul 21, 2026

Uh oh!

EItanya commented Jul 21, 2026

Uh oh!

EItanya left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xLeo258 commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

0xLeo258 commented Jul 22, 2026 •

edited

Loading