Skip to content

ADR#0025: Agent Definition Data Ownership ​

Context ​

ADR#0024 separates the agent registry record from the proposal workflow. Activation mints an immutable revision, sessions pin a revision, and rejected or withdrawn proposals never enter the registry history. That topology deliberately does not answer the next question: what data is part of the agent, what data is part of an activated revision, and what merely influences one execution?

ADR#0024 and this decision form one prerequisite architecture boundary for the agent lifecycle implementation. Neither decision is sufficient without the other.

The agent-platform research found one stable decomposition across otherwise different products: a durable definition, an execution or session, and memory are separate resources. Managed products version the definition and resolve it into a session, while memory, environment, credentials, implementation state, and hosting state follow independent lifecycles. The decision record then refined the platform boundary further: the agent owns its facts and dependency declarations; another party's permission, judgment, funding, scheduling, routing, or observation stays beside the agent on its own plane.

This ADR defines the agent entity and its configuration, and nothing else. The scope follows the strongest infrastructure model in the study, Bedrock AgentCore: a bare entity made of identity and immutable numbered revisions, with everything else detachable; the newest revision is what runs, and reverting mints a new revision from a prior configuration. Sessions, memory, work, and tools appear here only as boundary references; their own shapes are separate, later decisions.

The research also exposes why a field inventory alone is insufficient:

  • Jido calls its mutable in-process state validator a schema.
  • ADK uses input and output schemas for the payload handled by one invocation.
  • Tool schemas describe a reusable tool's invocation interface.
  • Prompt variables describe values that a caller must bind when starting a session.
  • Rubrics judge whether an outcome is good, not whether its data has the expected shape.

Putting any of these behind a generic schema field would erase who owns the contract, when it binds, and which change must mint a revision. The same problem appears outside schemas. An exact model selection, a live tool grant, a memory selection, a budget ceiling, and an observed success rate can all influence a run, but they have different authors, consistency rules, security properties, and change cadences.

The first lifecycle contract draft makes this ambiguity visible. It models a partial charter and a digest for a larger configuration, while instructions, turn wrappers, variables, skills, and description appear only in a changed-field inventory. Without a complete logical AgentConfiguration and an explicit AgentRevision binding, the digest has no normative content, the changed-field inventory can drift from the artifact it describes, and the lifecycle contract can accidentally become the definition contract.

This decision must preserve four properties:

  1. An agent can evolve its behavior without acquiring authority over policy, secrets, or evaluation.
  2. Revisions change only when agent behavior changes, not when memory, policy, work, or observations change.
  3. Reusable contracts stay with the resource that owns them instead of being copied into every agent.
  4. Every execution is traceable to the exact revision it ran, by reference and digest, so verification results remain meaningful.

Decision ​

Place each datum with the resource whose invariants and change cadence it describes.

Under draft ADR#0062, the general configuration binds an exact runtime to one runtime-owned typed settings message. Platform-owned dependency declarations remain common typed values when the selected adapter supports those integrations. The logical inventory below does not require every runtime to accept the platform harness's native model, instruction, or context controls.

A datum belongs to an AgentConfiguration only when all three statements are true:

  1. It is the agent's own behavior or dependency declaration.
  2. Every session pinned to that revision should begin with the same declaration.
  3. Changing it should invalidate behavioral verification and require a new proposal and activation.

If the datum expresses another resource owner's stance, one work item supplies it, a session resolves it, or execution merely observes it, the datum does not belong to the revision. A human may author agent instructions; authorship alone does not change which resource owns the declaration.

1. Model the agent as four records ​

This is the normative implementation handoff, and it is deliberately small: the agent is four records. The model defines logical records and ownership, not protobuf field spelling, physical storage, or event envelopes. Large immutable values may live outside an event, but the event must preserve their reference and digest. Identifier types, field cardinalities, canonical serialization, and command or event envelopes remain contract-design work; that work may not move data across the ownership boundaries decided here.

The distinction hidden by the earlier draft is explicit in this model: an AgentConfiguration exists before activation, while an AgentRevision does not. AgentRevision is the numbered binding created by provisioning or activation.

text
Agent
  agent_id
  name
  parent -> Hierarchy node
    (placement; recorded at provisioning, moves are hierarchy operations)
  latest_revision -> AgentRevision
    (derived: the highest minted revision, what new sessions run by
     default; not a stored pointer)
  lifecycle_state
  annotations

AgentRevision
  agent_id
  revision_number
  configuration_ref -> AgentConfiguration
  configuration_digest
  source = provisioning | proposal_id | revert_of_revision

AgentConfiguration
  description
  runtime -> AgentImplementation
    implementation_version_ref -> AgentImplementationVersion
      (exact typed implementation kind + immutable version)
    implementation_definition_digest
  settings -> one google.protobuf.Any
    (the complete settings message accepted by that exact runtime version;
     native models, parameters, instructions, and context controls live here)
  variables_schema
    (when the platform owns the caller-facing variable interface)
  skills
  required_tool_declarations + optional_tool_declarations
  required_delegate_declarations + optional_delegate_declarations
  required_memory_declarations + optional_memory_declarations
    (selectors by kind, never an instance reference)
  selectable_labels
  interface
    (advertised skills, default media types, interaction capabilities)
  execution_subject

Proposal
  proposal_id
  agent_id
  base_revision -> AgentRevision
  candidate_configuration_ref -> AgentConfiguration
  candidate_configuration_digest
  canonical_typed_difference | difference_ref + difference_digest
  derived_change_class
  author
  evidence
  terminal? = verdict | withdrawal
  verdict = decision + verifier + rationale
            + evaluation_result_refs + evaluation_result_digests
  withdrawal = author
  supersedes?

parent is the only placement fact and everything contextual derives from it. AgentProvisioned records it at birth; after that, moves are hierarchy operations, so the hierarchy domain owns the current value and the Agent record projects it. Ownership and authority are policy-plane bindings on the hierarchy, inherited and evaluated live at each protected action, never registry fields. The customer an agent belongs to is fixed by its creation placement and never changes; whether customers share infrastructure or receive dedicated cells is a deployment decision, and no location or physical topology appears in this model.

Agent owns no selectable label map. AgentConfiguration.selectable_labels owns every selector key, including family, because changing one can alter routing, evaluation binding, and comparison groups. An Agent projection may expose the latest revision's labels, and a session resolves labels from its pinned revision, but neither projection is an independent writable copy.

text
Proposal.candidate_configuration_ref -> AgentConfiguration
AgentRevision.configuration_ref      -> the exact same AgentConfiguration

Activation assigns the revision number and records provenance. It never rebuilds the candidate. configuration_digest is the revision digest and remains unchanged through activation; the revision number and provenance are not part of the configuration digest. The digest commits transitively to the exact runtime version, implementation definition, settings type and admitted bytes, common platform declarations, and every configuration-owned artifact. Model selections or instructions enter that digest through the runtime's settings when its contract exposes them. A platform-managed model capability may derive typed selections from those settings; it does not create a second authored model configuration.

2. Keep adjacent resources behind references ​

This ADR does not define the shape of sessions, memory, work, or tools. For each adjacent resource it decides only three things: the resource is separate, which datum it owns, and how it references the agent. Their full contracts are future decisions in their own domains, and those decisions may not move data across the boundary fixed here.

  • Session. A session pins exactly one AgentRevision at start, by reference and digest. Its immutable SessionExecutionPlan copies the revision's exact implementation version and definition digest and binds the exact settings. When platform-managed model access is required, a pinned adapter derives verifiable primary and auxiliary ModelSelection values from those settings and admission records them in the plan. It never selects a newer implementation or substitutes another declared model. The plan resolves external facts: ResolvedModelRoute values for that admitted capability, variable bindings, tool versions, memory selections, work input, and other dependencies under ADR#0031. Session-owned ExecutionAttempt facts separately record behavior-neutral hosting, placement, restart, and attestation evidence without changing the plan. The AgentConfiguration is not the literal model input; the pinned AgentImplementation adapter assembles input from the configuration plus session-resolved facts, and the session must record enough references and digests to reconstruct what the model saw. The revision digest answers "what did the agent declare?"; any session-side digest answers "what did the model see?"; they are never the same field. Activation never changes an in-flight session's pin.
  • Memory. Its own resource and lifecycle under hierarchy and policy. The configuration declares memory dependencies by kind selector, never by instance; a session resolves those declarations against its hierarchy context under live policy, possibly to several memories or none, and records each selection as reference and digest. Memory writes never mint revisions, and sharing an agent never moves memory across hierarchy or policy contexts. Memory's internal structure is a memory-domain decision.
  • ToolDefinition. A versioned reusable tool that owns its input schema. An AgentConfiguration declares tool dependencies by selector or exact pin; it never copies a tool's schema. Versions resolve at session start.
  • WorkContract. A versioned contract that owns the input and result schemas for one kind of work, separate from the agent because one agent performs many kinds of work and many agents can satisfy one contract. A session resolves and pins the selected contract; the work resource owns the payload, and the session records the work input as an immutable reference and digest.

Memory can still be accessed through a tool ​

The separation above is an ownership and lifecycle boundary, not a claim that Memory and tools are mutually exclusive runtime mechanisms. It matters because a memory write must not mint an AgentRevision, sharing an Agent must not share memory across hierarchy or policy contexts, and a session must record which memory influenced its execution. It does not require the runtime to give Memory a special invocation mechanism.

The terms answer different questions:

TermMeaning
MemoryDurable data with its own scope, policy, provenance, and lifecycle.
ToolDefinitionA reusable, versioned callable interface and the schema for its accepted arguments.
Tool callOne execution of a resolved ToolDefinition with concrete arguments.

A ToolDefinition is therefore closer to a function signature than to one function call. The logical example below is illustrative only; it does not propose wire fields, an SDK convention, or the future tool contract.

yaml
tool_definition:
  name: search-memory
  version: 1
  input_schema:
    query:
      type: string
      required: true
    limit:
      type: integer
      required: false

tool_call:
  call_id: call-17
  resolved_tool: search-memory@1
  arguments:
    query: release note conventions
    limit: 5

search-memory@1 is the reusable definition. call-17 is one specific call, and its arguments are validated against that definition's input_schema. Another call can use the same definition with different arguments. The session execution record owns the call and its outcome; the Memory resource still owns the records the operation reads or writes.

A runtime may resolve Memory during session-start assembly, expose operations over Memory as tools during execution, or support both. The exact call result, error, authorization, endpoint-binding, and wire shapes remain future Tool and Session decisions.

Everything else remains with its existing owner:

  • hierarchy owns parent, placement, moves, derived scope, and visibility;
  • policy and security own grants, access shares, credential bindings, secret material, budgets, ceilings, and authorization;
  • evaluation and Outcome own rubrics, bindings, verdict policy, and scores;
  • scheduling and routing own triggers, channels, destinations, and routing;
  • work and environment resources own work payloads and workspace contents;
  • the pinned AgentImplementation owns loop-state semantics, while the session owns transcripts and recorded implementation checkpoints;
  • the Session launch and deployment planes own process, container, isolation, network, filesystem, hosting authentication, and execution-lifecycle facts; and
  • skill resources own skill content, while an AgentConfiguration owns exact pins.

A common declaration is not proof that a runtime can consume it. Admission checks the pinned adapter's supported integrations before resolving declared skills, tools, delegates, memories, or platform variables. Optionality permits an absent resource under the declared resolution rules; it does not permit silently ignoring a declaration the adapter cannot interpret. Native runtime mechanisms without a platform integration stay in that runtime's settings and do not inherit platform management or authorization guarantees.

The revision boundary is therefore mechanical:

ChangeOwner and effectNew AgentRevision?
Runtime-owned instructions or wrappers, or common descriptionAgentConfiguration proposalYes
Runtime version, definition, settings type, or settings bytesAgentConfiguration proposalYes
Runtime-owned model settings or platform-owned variables_schemaAgentConfiguration proposalYes
Skill pins or tool/delegate/memory declarationsAgentConfiguration proposalYes
Selectable labelsAgentConfiguration proposalYes
Skill contentSkill resource; a revision changes only when its pin changesNo by itself
Memory contentMemory writeNo
Variable bindings, work input, or resolved dependenciesSession start factsNo
Exact implementation and model pins copied from AgentRevisionSession start recordNo
ResolvedModelRoute or behavior-neutral hosting factSession or deployment factNo
Transcript, actions, resolved delegates, or outcomesSession execution recordNo
Tool schema or work schemaToolDefinition or WorkContract versionNo
Parent, placement, scope, or visibilityHierarchy operationNo
Ownership or authorityPolicy plane binding on hierarchyNo
AnnotationsAgent metadata operationNo
Agent idImmutable Agent identityNo
NameImmutable Agent factNo
Grants, secrets, budgets, evaluation, routing, or schedulesExternal planeNo

Worked example: one proposal becomes revision 2 ​

The following values use the logical names above. They are not proposed protobuf field names or an SDK settings contract. This example assumes a platform-harness settings type with model and instruction controls, and a pinned adapter supporting the shown platform declarations and semantic differences. Each field path in the canonical typed difference names a difference category first and a native field inside the runtime's own settings message second. The platform defines the categories; the registered classifier for the pinned runtime resolves everything past the first segment, so runtime_settings never becomes a platform-owned namespace over the settings envelope.

RecordConcrete binding
Proposal prop-7f3acandidate configuration-pr-reviewer-v2
AgentRevision 2configuration configuration-pr-reviewer-v2
Complete logical example data
yaml
agent:
  agent_id: agent-pr-reviewer
  name: pr-reviewer
  parent: project-example
  latest_revision:
    revision_number: 2
  lifecycle_state: active
  annotations:
    display_name: Pull Request Reviewer

agent_configurations:
  - configuration_ref: configuration-pr-reviewer-v1
    configuration_digest: "sha256:0101010101010101010101010101010101010101010101010101010101010101"
    content:
      description: Reviews pull requests for correctness and maintainability.
      runtime:
        implementation_version_ref:
          kind: platform_harness
          version: 3
        implementation_definition_digest: "sha256:0202020202020202020202020202020202020202020202020202020202020202"
      settings:
        type: illustrative-platform-harness-settings-v1
        context_strategy: rolling-summary-v2
        max_tool_iterations: 24
        primary_model_selection:
          model_version_ref:
            model_id: model-reviewer
            version: 1
          model_definition_digest: "sha256:0404040404040404040404040404040404040404040404040404040404040404"
          deterministic_parameters:
            temperature: 0.2
            max_output_tokens: 4096
        auxiliary_model_selections: []
        instructions:
          - Report correctness defects with file and line evidence.
          - Separate blocking findings from suggestions.
        turn_wrappers:
          - wrapper-repository-context-v1
      variables_schema:
        review_depth:
          type: string
          allowed_values: [standard, strict]
          required: true
        output_language:
          type: string
          required: false
      skills:
        - skill_id: skill-code-review
          version: 3
          content_digest: "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
      required_tool_declarations:
        - selector:
            name: repository-read
      optional_tool_declarations:
        - selector:
            name: ci-status
      required_delegate_declarations: []
      optional_delegate_declarations:
        - selector:
            labels:
              family: security-review
      required_memory_declarations: []
      optional_memory_declarations:
        - selector:
            kind: project-conventions
      selectable_labels:
        family: code-review
        language: any

  - configuration_ref: configuration-pr-reviewer-v2
    configuration_digest: "sha256:1111111111111111111111111111111111111111111111111111111111111111"
    content:
      description: Reviews pull requests for correctness and maintainability.
      runtime:
        implementation_version_ref:
          kind: platform_harness
          version: 3
        implementation_definition_digest: "sha256:0202020202020202020202020202020202020202020202020202020202020202"
      settings:
        type: illustrative-platform-harness-settings-v1
        context_strategy: rolling-summary-v2
        max_tool_iterations: 24
        primary_model_selection:
          model_version_ref:
            model_id: model-reviewer
            version: 1
          model_definition_digest: "sha256:0404040404040404040404040404040404040404040404040404040404040404"
          deterministic_parameters:
            temperature: 0.2
            max_output_tokens: 4096
        auxiliary_model_selections: []
        instructions:
          - Report correctness defects with file and line evidence.
          - Treat missing regression coverage as blocking when behavior changes.
          - Separate blocking findings from suggestions.
        turn_wrappers:
          - wrapper-repository-context-v1
      variables_schema:
        review_depth:
          type: string
          allowed_values: [standard, strict]
          required: true
        output_language:
          type: string
          required: false
      skills:
        - skill_id: skill-code-review
          version: 4
          content_digest: "sha256:1515151515151515151515151515151515151515151515151515151515151515"
      required_tool_declarations:
        - selector:
            name: repository-read
      optional_tool_declarations:
        - selector:
            name: ci-status
      required_delegate_declarations: []
      optional_delegate_declarations:
        - selector:
            labels:
              family: security-review
      required_memory_declarations: []
      optional_memory_declarations:
        - selector:
            kind: project-conventions
      selectable_labels:
        family: code-review
        language: any

agent_revisions:
  - agent_id: agent-pr-reviewer
    revision_number: 1
    configuration_ref: configuration-pr-reviewer-v1
    configuration_digest: "sha256:0101010101010101010101010101010101010101010101010101010101010101"
    source: provisioning

  - agent_id: agent-pr-reviewer
    revision_number: 2
    configuration_ref: configuration-pr-reviewer-v2
    configuration_digest: "sha256:1111111111111111111111111111111111111111111111111111111111111111"
    source: prop-7f3a

proposal:
  proposal_id: prop-7f3a
  agent_id: agent-pr-reviewer
  base_revision:
    agent_id: agent-pr-reviewer
    revision_number: 1
    configuration_ref: configuration-pr-reviewer-v1
    configuration_digest: "sha256:0101010101010101010101010101010101010101010101010101010101010101"
  candidate_configuration_ref: configuration-pr-reviewer-v2
  candidate_configuration_digest: "sha256:1111111111111111111111111111111111111111111111111111111111111111"
  canonical_typed_difference:
    - field: runtime_settings.instructions
      interpreter: pinned-runtime-semantic-difference-adapter
      operation: replace
      before_digest: "sha256:1212121212121212121212121212121212121212121212121212121212121212"
      after_digest: "sha256:1313131313131313131313131313131313131313131313131313131313131313"
    - field: skills.skill-code-review
      operation: replace
      before_version: 3
      before_content_digest: "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
      after_version: 4
      after_content_digest: "sha256:1515151515151515151515151515151515151515151515151515151515151515"
  derived_change_class: learned-layer
  author: principal-curator
  evidence:
    - outcome_ref: outcome-review-missed-test-42
      outcome_digest: "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  terminal:
    verdict:
      decision: approved
      verifier: principal-verifier
      rationale: Candidate catches the missed regression without new authority.
      evaluation_result_refs:
        - evaluation-result-108
      evaluation_result_digests:
        - "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
  supersedes: prop-b804

The equal configuration_ref and configuration_digest values are the load-bearing part of the example: Proposal prop-7f3a was verified against exactly the bytes that AgentRevision 2 later references. Activation added the number and provenance; it did not rebuild the candidate.

After this activation:

ChangeResult
Write a new project convention to MemoryMemory changes; no revision 3
Revoke a tool authorizationNext call is denied live; no revision 3
Publish a new WorkContract versionWork plane changes; no revision 3
Publish skill-code-review v5No revision 3 until a proposal changes the pin
Propose different instructions or a new skill pinNew configuration; activation may mint revision 3
Publish AgentImplementationVersion 4No revision 3 until a proposal changes the exact pin
Propose implementation version 4, different implementation config, or another modelCharter-class configuration change; activation may mint revision 3
Move the same pinned implementation to another conforming hostDeployment changes; no revision 3

Boundary rationale ​

The Agent registry owns stable identity and lifecycle. Hierarchy owns placement and derives visibility; Agent projections may expose parent, but the registry stream and revision do not own it. Ownership and authority are policy bindings on the hierarchy, evaluated live: a move requires rights on both source and destination, and taking authority over an agent is a policy change, never a registry write. There is no independent scope field. Annotations are opaque record metadata and never affect selection, model input, implementation behavior, hosting behavior, or the configuration digest.

AgentConfiguration.runtime binds the exact implementation version and definition digest. Its single settings envelope contains the complete typed configuration accepted by that version. These are behavior, not placement. A newer implementation version is never selected automatically. Changing the implementation kind, version, definition digest, configuration, or configuration digest creates a candidate AgentConfiguration and requires the normal Proposal, verification, and activation workflow. The same Agent may therefore evolve its implementation through controlled revisions without mutating an existing revision or replacing the stable Agent identity.

The stable Agent contains neither an implementation binding nor a model selection. Both are behavior facts owned by its immutable configurations.

Model and parameter vocabularies belong to each runtime's settings contract. A runtime may expose one model, several roles, or no caller-controlled model selection. The absence of such controls does not establish that the runtime uses no models. Native defaults are reproducible only to the extent that the pinned runtime contract fixes their meaning.

When a Session requires platform-managed model access, the exact adapter must derive verifiable ModelSelection values from the admitted settings and prove that execution can honor them. Admission rejects unsupported or hidden model choices for that capability. The SessionExecutionPlan records this derived projection and resolves a ResolvedModelRoute for each exact model under ADR#0032. It never adds a model role, substitutes a model, or creates another authored selection source. Attempt-scoped grants remain live authorization outside the plan. The provider driver is a Session fact because it adapts an already-pinned model to an external provider; its exact pin remains part of verification evidence. Other Session modes cannot claim these managed-model guarantees merely because their Agent configuration is valid.

Process, container, microVM, remote host, placement, isolation, network, filesystem, lifecycle, cancellation, recovery, and hosting authentication are Session launch or deployment facts. They do not enter AgentConfiguration and do not mint a revision while they remain behaviorally transparent. If a host setting changes model-visible input, tools, loop decisions, model selection, or terminal semantics, it is not merely hosting. The behaviorally relevant setting must become part of the exact AgentImplementation definition or typed AgentConfiguration before use.

Verification evidence records what it actually exercised: AgentRevision and configuration digests, the exact implementation version and configuration digests, any admitted model selections and ResolvedModelRoute values, tool versions, and memory snapshots. A revision's score is always interpretable as "under these resolved facts", never as a context-free claim.

An AgentConfiguration is content-addressed and never edited. Its digest commits transitively to every configuration-owned artifact, so implementation and skill pins commit to immutable content rather than only mutable version labels.

Proposal facts explain why a candidate did or did not become a revision; they are not behavior content. Change classification comes from the canonical difference between the pinned base and immutable candidate. Caller-supplied changed fields may express intent but cannot be authoritative. A verdict binds the candidate already fixed by ProposalOpened without duplicating its reference or digest. It references evaluation results rather than copying them.

Activation requires the Proposal base to match the Agent's latest AgentRevision. A stale Proposal must be rebased, differenced, digested, and verified again.

Using the illustrative names from ADR#0024, the lifecycle contracts preserve the model:

  • AgentProvisioned records Agent facts and the complete immutable reference and digest for revision 1.
  • ProposalOpened records the base, candidate, typed difference, and evidence, but no revision number.
  • RevisionActivated records Proposal provenance plus the candidate reference and digest.
  • Reverting is RevisionActivated minting a new revision from a previously activated configuration; digest equality proves the revert exact.
  • AgentArchived blocks activation but never deletes referenced artifacts.

Actor identities on commands and events are provenance facts, not behavior content. Authentication owns principal kind and authorization policy.

Routing a new session uses selectable_labels from the latest revision's AgentConfiguration; an existing session keeps the labels of its pinned revision. Recorded capabilities never become entitlements: policy remains live at every protected action and is evaluated against the session's pinned behavior facts.

3. Treat charter and learned layer as governance classes ​

The charter and learned layer classify changes; they are not two mutable documents and do not create competing sources of truth. Every activation still produces an AgentRevision bound to one complete AgentConfiguration.

  • Learned-layer changes include runtime instructions or wrappers only when a pinned semantic difference adapter can prove that classification; common description, skill pins, optional tool, delegate, or memory declarations, and selectable labels that do not alter a well-known routing or comparison group.
  • Charter-class changes include runtime version, definition digest, or settings contract; model selections and parameters identified by the runtime adapter; settings changes without a supported semantic classification; required tool, delegate, or memory declarations; well-known grouping labels such as family; and the variables_schema.
  • Name is an immutable agent fact. Implementation and model evolution use proposals for new revisions. Placement changes are hierarchy or deployment operations and authority changes are policy operations, never proposals for behavior revisions.

Full validation of the runtime's settings is mandatory even when semantic change classification is unsupported. An opaque but validated settings change defaults to charter-class; it cannot claim to be an instruction-only learned-layer edit. This avoids treating every settings edit as equivalent while preserving a conservative path for runtimes without semantic diff support.

For v1, the platform-owned variable schema is charter-class because it is an interface offered to session callers. Adding or removing a binding, changing a type, or changing requiredness can make previously valid session starts invalid. The agent may freely evolve how existing variables are used inside learned-layer instructions, but it may not silently rewrite the caller's contract.

This refines the research record's earlier classification of all variable changes as learned-layer changes.

4. Put every schema on the contract it validates ​

There is no generic schema field on Agent, AgentRevision, or AgentConfiguration.

The product corpus does not converge on structured work schema placement. ADK, OpenAI, and Vercel attach structured input or result configuration to an agent-like code object, while Devin binds its structured result schema when creating a session. This platform chooses a separate WorkContract because work is reusable across agents and an agent is reusable across kinds of work. That is a TrogonAI ownership decision, not an industry invariant.

  • AgentConfiguration.variables_schema, when present, declares the names, types, and requiredness of session-start values in the platform-owned caller interface. Its use requires a supported runtime integration. Runtime-native input controls stay inside settings when the platform does not own that interface. Bound variable values belong to the session.
  • ToolDefinition.input_schema declares the input accepted by that version of a reusable tool.
  • WorkContract.input_schema and WorkContract.result_schema declare the structured input and successful result for one kind of work.
  • An AgentImplementation loop-state or checkpoint schema belongs to the exact implementation version and the session contract. Jido's state schema is this kind of contract, not evidence for a generic Agent schema.
  • Rubrics and quality scores remain in EvaluationBinding and OutcomeRecorded. Shape validity is not outcome quality.

Use explicit names and versioned references or digests. Prefer result_schema to an overloaded output_schema. Generic conversational sessions may omit work input and result schemas and use text input and result.

Validate variable bindings and work input before creating the session. Validate tool arguments at the Tool boundary. Validate the final result before recording successful completion.

5. Keep external stances and observations beside the agent ​

The following data never enters an AgentConfiguration:

  • grants, access shares, credential bindings, secret references, and secret material, consistent with ADR#0023;
  • budget, token, turn, concurrency, and delegation ceilings;
  • rubrics, evaluation bindings, verdict policy, and outcome scores;
  • schedules, triggers, channel bindings, delivery destinations, and routing policy;
  • ownership policy and authorization principal kinds;
  • inbound identity: who may invoke the agent is authentication and policy, never configuration;
  • behavior-neutral hosting configuration: processes, containers, remote hosts, placement, isolation, filesystem, network, environment variables, hosting authentication, and lifecycle belong to Session launch or deployment;
  • success rates, usage counts, cost, priority, and fitness projections;
  • environment contents, workspace contents, memory records, transcripts, implementation checkpoints, and hosting state; and
  • work payloads, WorkContracts, and tool invocation schemas.

An AgentConfiguration declares what it needs. External planes decide what it may use, what work it receives, how it is judged, and what happened. Changes on those planes do not mint agent revisions. If observed evidence justifies a behavior change, a curator turns that evidence into a Proposal through the ADR#0024 workflow.

Definitions pin; authorization never pins. Grants and revocations are evaluated live at each protected action, and credential rotation remains a live security operation rather than a behavior revision. Credential values are never model context: a dependency declaration may say that a tool is needed, while grants, credential bindings, and secret resolution authorize and equip the tool call outside the prompt.

Consequences ​

  • The definition contract stays small enough to hand to another engineer: four records, one membership test, and one revision-boundary table.
  • The agent platform needs typed contracts for Agent, AgentConfiguration, AgentRevision, Proposal, an exact runtime binding, runtime-owned settings, and supported platform declarations. One Any preserves a different complete settings type for each runtime without making its payload unvalidated.
  • Draft ADR#0062 resolves model-setting ownership in favor of the runtime. The typed selections needed by ADR#0032 are a derived capability projection from those settings. Model admission and no-substitution guarantees apply only where the pinned adapter can prove that projection and enforce it; a valid Agent schema does not promise every runtime that capability.
  • The definition records alone answer which agent existed, which revision ran, and which proposal justified it. What the model saw and what was authorized are answered by the session and policy domains through the references this boundary requires them to record.
  • Session, memory, and work contracts are deliberately not designed here. Each gets its own decision when its domain is built, and none of those decisions may move data across the ownership boundary fixed here.
  • Registry and proposal events may remain small. Large prompt and skill content can live outside the event stream when canonical serialization, immutable retrieval, and digest verification are defined.
  • Proposal change class and changed fields must come from the typed canonical revision difference. They cannot depend only on duplicate metadata supplied independently of the candidate artifact.
  • Activation rejects a proposal based on a revision that is no longer the latest. Rebase changes the candidate and therefore requires a new digest and verification.
  • Tool and work schemas evolve once at their owning resource. Agents and sessions pin versioned references instead of copying those schemas and allowing them to drift.
  • Memory, policy, and evaluation can evolve without polluting revision history. This adds joins to read models, but each resource or plane now enforces one owner's invariants and changes at its natural cadence.
  • Treating variable-schema changes as charter-class slows autonomous changes to that interface, but prevents the evolution loop from silently breaking callers.
  • Exact prompt ordering, provider-specific message roles, compression algorithms, and wrapper cadence remain decisions of the implementation adapter pinned by AgentConfiguration. This ADR fixes ownership and binding time rather than one universal prompt format.

Released under the Apache License 2.0.