Yesterday, backend-reviewer inspected pull requests with one model, read only the repository and public documentation, and stopped for human approval before proposing any change.
Today it has exactly the same name. The model has changed, the system instructions have been rewritten, incident history is now available as a context source, memory persists between tasks, and database migration changes no longer require approval before they are proposed.
The dashboard still shows the same team member. The engineer responsible for quality and risk is looking at a different agent.
The identifier stayed. The behavior moved.
That distinction is what NexFlow, an open specification for AI developer teams, is trying to make visible. The project does not currently provide a production runtime, a production CLI, or model-provider integrations. Its present job is narrower and, in my view, more important: give teams a language for reviewing agent changes before anything executes.
A name answers the wrong question
Agent names are useful to people. They distinguish a code reviewer from a documentation writer and establish a long-lived role inside the team.
A name says very little about the configuration that produced a particular result.
A model change can affect code quality, cost, latency, and the way uncertainty is handled. New instructions alter the order of analysis and the criteria for an acceptable answer. An additional source expands both available knowledge and the exposure surface. Memory carries the consequences of one task into another. A new permission changes more than output style: it changes what an error can damage.
For audit purposes, “Which agent did the work?” is therefore incomplete. A second question matters just as much: which version of that agent's definition was active?
In draft RFC-0004, NexFlow separates stable agent identity from a versioned agent definition. Identity contains the role, description, and long-lived responsibility. The definition captures a behavioral release: the collection of components that can materially change an agent's output or authority.
What belongs in a behavioral release
An agent definition can reference a model profile, a prompt set, and retrieval rules. It also identifies context access, memory scopes, capabilities, permissions, autonomy, and extensions.
Each component changes the agent in a different way.
A model profile describes selection constraints, cost, latency, data handling, and audit expectations. A prompt set records instruction revisions and review metadata. A retrieval profile covers sources, freshness, citations, and exclusions. Context and memory policies define information boundaries. Capabilities describe technical actions, while permissions decide whether those actions are authorized. Autonomy establishes where the agent must stop.
Embedding every detail in one oversized agent record would make manifests hard to review. Approved components would be copied across agents, and a consequential change could disappear among dozens of unrelated lines.
RFC-0004 instead proposes an agent definition that references versioned components. The current draft shape looks roughly like this:
id: backend_reviewer_2026_07
agentRef: backend-reviewer
definitionVersion: "2026.07.0"
status: draft
owner: human-tech-lead
description: Backend reviewer for API, migration, and pull request work.
components:
modelProfileRef: backend_reviewer_model
promptSetRef: backend_reviewer_prompts
retrievalProfileRef: backend_reviewer_retrieval
permissionRefs:
- backend_review_permissions
capabilityRefs:
- read_repository
- propose_changes
contextSourceRefs:
- repository
- incident_history
memoryScopes:
- task
extensionRefs:
- github_basic
autonomyLevel: ask_before_changes
changeSummary: Adds incident context and narrows migration permissions.
replaces: backend_reviewer_2026_06
review:
required: true
approvers:
- human-tech-lead
The fields may still change. RFC-0004 remains a draft, and NexFlow itself is at 0.1 draft. The important part is the structure: a stable agent can have distinct behavioral releases, each reviewable as an engineering change.
A reference selects a component; it does not grant authority
Versioned configuration can create a dangerous illusion. If an agent definition references a permission set or a memory scope, it is tempting to treat that reference as access.
NexFlow keeps those concerns separate.
Draft RFC-0014 states the central rule clearly: agent definitions select reviewed behavior, while policy manifests authorize and constrain it. A capability reference does not permit an action. A context reference does not override data classification. A task-level setting must not silently raise autonomy.
This separation becomes especially important when comparing versions. A prompt revision may need a normal review. Broader memory access or removal of an approval gate changes the risk surface and deserves stronger scrutiny. Both changes can remain structurally valid under the same JSON Schema even though their consequences are very different.
Floating versions hide behavioral changes
Pinning every component forever is not always practical. A team may want “the latest approved small coding model” or the current version of a documentation index.
That policy reduces manual updates and makes reproduction harder. The same backend-reviewer may use different models or corpora in June and July without a change to its own manifest.
A floating reference should therefore resolve to a concrete value that is recorded in an event or audit log. Without that record, an incident investigation is left with the name of a policy and no reliable account of the configuration that actually ran.
A pinned reference favors predictability. A floating reference allows controlled updates. Either can work when the project records the resolved choice and defines which changes require another review.
Git history is valuable, but it is not an agent version
One reasonable objection is that the repository already records every change. Git can show which lines moved and who approved them.
An event, artifact, or handoff still needs a portable reference to the behavioral release that produced it. Otherwise, investigators must reconstruct the active commit, branch, external component versions, and runtime choices from indirect evidence.
An agent definition version connects the result to its configuration directly:
agent:
id: backend-reviewer
definitionRef: backend_reviewer_2026_07
definitionVersion: "2026.07.0"
modelProfileRef: backend_reviewer_model
promptSetRef: backend_reviewer_prompts
retrievalProfileRef: backend_reviewer_retrieval
A future runtime may also record the resolved provider model and provider-specific details when doing so is safe. Those values belong to the execution layer. The core specification can remain provider-neutral while still requiring enough identity to reconstruct the meaning of an event.
Versioning helps before an agent can run
This approach does not need to wait for a production runtime.
Agent definitions can live beside the code and be reviewed in pull requests. A reviewer can see that a release adds a context source, changes a prompt set, or raises autonomy. The change gets an owner, a summary, and an explicit predecessor.
Lifecycle becomes visible as well. A draft is not normal operating configuration. An active release has passed the project's review process. A deprecated release remains valid during migration. A retired release should no longer be selected for new work.
For NexFlow, this is specification vocabulary rather than implemented runtime behavior. The vocabulary still improves the review itself. “We updated the agent a little” becomes a set of concrete changes: a new model profile, a revised prompt set, broader context, different memory, or a weaker approval boundary.
The same identifier can no longer disguise different operating conditions.
An agent name tells us who participates in the team. Its definition version tells us which participant the team trusted with this result.
Top comments (0)