konveyor / konveyor/agentic-controller

Workflow determinism: snapshot or generation-pin the Agent definition per stage

Open
#180 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
2
Forks
12
Avg merge
2d 5h
Merged PRs (30d)
41

Description

### Background

#87 (landing in #169) snapshots the **AgentWorkflow** definition onto `AgentWorkflowRun.status` at init — the stage list, each stage's `agentRef`/`instructions`/`execution`, the `guide`, and the workflow-level `params` — and executes from that snapshot. So editing the **AgentWorkflow** mid-run cannot change stages already planned.

### Gap

We snapshot the workflow, but **not the Agent definitions** the stages reference. The stage snapshot records only `agentRef` (the name). Each stage's AgentRun is created *as the workflow progresses*, and at that point the AgentRun controller reads the **live Agent** by name (`prompt`, agent-level `params`, `skillCards`, `execution`). No Agent `generation` is recorded anywhere.

Result: **editing the *Agent* mid-run affects not-yet-created stages.** Example: a 3-stage run on Agent-A; while stage 1 runs, someone edits Agent-A's prompt; stage 2 (also Agent-A) is created later and picks up the edited prompt. The workflow is frozen; the agents behind it are not.

(Note: a *running* stage is already immune in effect — its prompt/params are rendered and baked into the pod at sandbox creation. #169 also tightens the AgentRun to validate/read its Agent exactly once, at creation. This issue is specifically about **later, not-yet-created** stages.)

### Options

1. **Snapshot the Agent definition** per stage (like we do for the workflow) → immune to edits, but larger status payload and a second snapshot to reason about.
2. **Generation-pin**: record each Agent's `metadata.generation` on the stage/AgentRun and detect drift → smaller, but detection is not immunity (need a policy: refuse? warn? proceed?).

Decision (snapshot vs pin, and the drift policy) to be made here, likely with an ADR note extending 0018.

### Related
- #87 (workflow-def snapshot), #169 (controller params/execution/succeeded), ADR 0018.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading ADR 0018 and tracing the AgentRun controller's creation path, including how later workflow stages resolve their Agent definitions. Compare the snapshot and generation-pin options, then document the chosen approach and drift policy; done means later stages follow that recorded policy rather than silently using changed Agent definitions.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, kubernetes
Domain
backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.