Agent Framework

Purpose

The framework is what a person who writes an agent gets, independent of which agent. It is the layer between the software components and the agent graph: the module author declares a profile, a memory node, a prompt, a skill set and an eval set, and the framework supplies the loop, the tools, the memory access, the gates, the ledger, the budget and the lifecycle. This page enumerates those services as contracts an author can rely on, each pointing to its design page. If a module page needs something not listed here, that is a framework gap.

1. The layers

flowchart TB
  A["Author a profile"]:::owner
  E["Evaluate and publish"]:::decision
  T["Instantiate a durable task"]:::work
  M["Assemble context
call the model"]:::work
  V["Validate typed output"]:::proof
  H["Run the permitted handler"]:::work
  P["Persist evidence
and checkpoint"]:::store
  K["Propose learning"]:::learn
  A --> E
  E -->|"published version"| T
  T --> M
  M --> V
  V --> H
  H --> P
  P -.->|"after result"| K
  K -.->|"new revision"| E
  classDef work fill:#eef4ff,stroke:#6889ba,color:#17365b,stroke-width:1.3px
  classDef decision fill:#fff4df,stroke:#b78c36,color:#65470d,stroke-width:1.5px
  classDef proof fill:#e9f5ef,stroke:#689b81,color:#224e39,stroke-width:1.3px
  classDef learn fill:#f1edf9,stroke:#9580b9,color:#534172,stroke-width:1.3px
  classDef store fill:#f5f7fa,stroke:#98a6b7,color:#34445a,stroke-width:1.2px
  classDef owner fill:#24486b,stroke:#24486b,color:#ffffff,stroke-width:1.4px
  click A href "agents.html" "Task role, prompt, knowledge ownership, tools and evaluation contract."
  click E href "agent-framework.html#63-the-flow" "Test versioned changes before selection by new tasks."
  click T href "agent-runtime.html" "Pin profile, prompt, model route, skills and case scope."
  click M href "model-execution.html" "Karpathy working rules, task request and fallible domain knowledge are distinct inputs."
  click V href "model-execution.html" "Unknown actions, invented references and scope violations are refused."
  click H href "agent-runtime.html" "Read/control tools or the separate audited/gated effect path."
  click P href "../data-model.html" "The task survives worker and session loss."
  click K href "agents-memory.html" "The node owner reviews and evaluates a new version before reuse."

The framework makes training operational: a changed prompt or skill becomes a tested version; a model response becomes work only after software validation.

2. What the author declares P

P Modules defines the versioned module declaration. Model Execution defines the concrete request/action protocol over the inspected IInferenceClient seam. Reasoning profiles are prompts; deterministic handlers are registered code, and their profile declaration carries handler_key instead of prompt/model-route ids.

An author writes no code for a reasoning agent; a connector or a skill with executable parts is code and goes through the Software Architecture libraries.

3. What the framework guarantees P

4. What the framework does not decide P

The framework is the same for every module; these are module decisions, declared in the module pages:

• the stage set and which gate fires where (Gating § 1 table; Configuration Module § 1, Development Module § 1, Support Module § 1);
• the proof levels a stage may claim and its done test (Configuration Module § 7.4);
• the eval corpus and its grader (Agent Framework § 6.5);
• which connectors and environments the module's profiles may use (Software Architecture § 10.3);
• the intake conversation the root holds with the operator and how it maps to a case type (Agent Runtime § 11.6);
• the module's agent tree, its branch of the memory tree and its skill catalogue — the three things a module adds to the platform, drawn in that order at the head of each module page (D145): Configuration Module § 0 · Support Module § 0 · Data and Information Module § 0 · Development Module § 0.

P The layering rule of this documentation (D145). The pages of this chapter — the framework, the runtime, the profile, knowledge (§ 7) and skills (Agents Memory and Skills) — are module-agnostic: each states the rule and one example. A module page instantiates: its agent tree, then its branch of the memory tree, then its skills and tools, then its stages. Nothing per-module appears on a platform page, and no platform rule is restated on a module page.

5. The author's checklist P

Before a profile is published:

1. its memory node exists and its AGENTS.md names the articles it owns;
2. its prompt version references only published skills and existing nodes;
3. its tools are declared per environment scope, and every write-capable operation has a dry-run and a teardown;
4. its denied context is provisioned, not instructed;
5. its budget has both thresholds;
6. its escalation names the parent profile and the failed-attempt count;
7. its eval set is green, and the replay fixture of at least one recorded run exists;
8. its route passes the module's data-boundary predicate;
9. the publisher holds the role for this profile's stage.

6. Governance — draft, test, publish

The stage authors write the configuration stage prompts at the same time (Delivery track T2), and later the same platform carries support methodologies, investigator prompts and connector instructions written by more people still. Without governance the failure is predictable: prompts edited in place, no version that can be rolled back to, no proof a change is an improvement, and one author's edit silently changing another author's stage.

Governance makes a prompt behave like code: owned, versioned, tested before it is published, and revertible.

6.1 The mechanism already exists

F Four of the five properties this document needs already exist on the branch, enforced by the database rather than by convention (verified 01.09.2026):

Publication is additionally hash-verified and idempotent, and the runtime re-validates on every use.

P AISA Next reuses this rather than inventing a second one. Skills and agent instructions are governed as prompts are: catalogued in SRD_SUPPORT, tested, published.

6.2 Ownership

F Ownership is the one property that does not exist on the branch (verified 01.09.2026). The entities carry CreatedBy, ApprovedBy and ActorId, but the only check is that the actor string is non-empty and ≤64 characters; there is no owner column, no owner-only rule, and no author≠approver separation. Everything in this section is therefore an AISA Next addition, built at the approval step — not reuse.

P One author owns one prompt and its memory domain. Ownership is a row, not a convention: the profile names its instruction and the instruction names its owner. Only the owner may change a prompt — a change another author needs is a request to the owner, the same way a cross-domain memory finding is handed to the domain's agent (Agents Memory § 2). Making a version live is a separate act, gated by the prompt-publisher role (§ 6.3).

This is what makes T2 parallel: the stage authors touch disjoint (prompt, domain) pairs and never the same row.

6.3 The flow

flowchart TB
  D["Draft a new version"]:::work
  T["Evaluate affected profiles"]:::proof
  P["Authorised publication"]:::decision
  N["New tasks select it"]:::work
  O["Observe real outcomes"]:::learn
  R["Rollback as a new version"]:::work
  D --> T
  T -.->|"failed evaluation"| D
  T -->|"passed"| P
  P --> N
  N --> O
  O -.->|"new evidence"| D
  O -.->|"regression"| R
  R -->|"evaluate again"| T
  classDef work fill:#eef4ff,stroke:#6889ba,color:#17365b,stroke-width:1.3px
  classDef decision fill:#fff4df,stroke:#b78c36,color:#65470d,stroke-width:1.5px
  classDef proof fill:#e9f5ef,stroke:#689b81,color:#224e39,stroke-width:1.3px
  classDef learn fill:#f1edf9,stroke:#9580b9,color:#534172,stroke-width:1.3px
  classDef store fill:#f5f7fa,stroke:#98a6b7,color:#34445a,stroke-width:1.2px
  classDef owner fill:#24486b,stroke:#24486b,color:#ffffff,stroke-width:1.4px
  click D href "agent-framework.html" "Retain source, reason and the previous immutable version."
  click T href "agent-framework.html" "Use pinned dependencies and held-out request families."
  click P href "agent-framework.html" "The publishing role and evaluation prerequisites must pass."
  click N href "agent-runtime.html" "Existing tasks remain pinned; live revocation is still checked."
  click O href "../case-journeys.html" "Distinguish retrieval, verified reuse and clean execution."
  click R href "agents-memory.html" "Publish the prior accepted content with current provenance and checks."

Learning changes versioned behaviour. Publication never changes an organisation's accepted risk classes or silently upgrades a running case.

P Publishing is a role, not a review (decision 01.09.2026). Anyone may draft and test; making a version live requires the prompt-publisher role (Trust and Data § 3).

P No mandatory second person (02.09.2026): an author who holds the prompt-publisher role for that stage publishes their own version; one who does not hands the publish to a holder as a task. Where a bad prompt is expensive — write-executor and production-touching profiles — the organisation may withhold the publisher role from the authors of those profiles; that is a role-set choice, not a platform rule (Trust and Data § 3). The controls that always apply are the eval set and the role check.

P The role is held per stage, not once across all of them (decision 01.09.2026): the publisher for the Abacus prompt is not automatically the publisher for the IPAL prompt. This keeps the five authors genuinely parallel — no single publisher becomes the queue every stage waits on — and it puts the accountability next to the expertise, since judging whether a stage prompt is ready needs knowing that stage. Peer review is not mandatory — the controls are the eval set, which is mechanical, and the role, which is a person accountable for what goes live. Whether a stage author also holds the role is a staffing choice; the eval-set gate applies either way.

P A publish is blocked when: the eval set is not green · the profile's declared model route violates its module's data boundary (Agents § 0.3) · the publisher does not hold the prompt-publisher role · a referenced skill or memory domain does not exist.

6.4 Versions

P Published versions are immutable. A change is a new version; rollback publishes a new version of the previous accepted content; nothing is edited in place. Session and audit records name the version that ran, so a case stays reproducible after its prompts have moved on (Architecture CR-1).

6.5 Eval sets

P Every prompt carries an eval set, and the set is the author's own proof — runnable without the other four stages (Configuration Module § 7.6). CR-4 makes the sets re-run whenever the owning memory domain, the skills it binds, or the model route changes.

Per-module golden corpora, all seeded from measured v1 material. The Configuration corpus is the example (D145); each module's own corpus and grading dimensions are its Evaluation section — Support Module § 5, Data and Information Module § 3, Configuration Module § 6, Development Module § 4:

P A stage author's set is green before publish; the module's joint corpus runs after the five are integrated. The two are different tests and neither substitutes for the other.

P The eval-set format (D66): one directory per case under the module's eval corpus — input/ (the arrival material: ticket snapshot, spec artefact, or requirement text), oracle/ (the reference outcome: mechanism + fix shape, or the exported product + counts), tolerances.json (what "match" means per dimension — exact count, status equality, diff = 0, or rubric judgement). Grading is deterministic first — counts, statuses, diffs are checked by the runner without a model — and only what cannot be checked mechanically goes to the isolated grader profile (Agents § 1), one rubric dimension per call with an explicit "Unknown" exit. Run triggers: before any publish, on a change to the owning memory domain / bound skills / model route, and on the scheduled batch (eval.batching); provider usage per module per week is a ledger metric, and a set whose budget exceeds the errors it catches is trimmed (Metrics § Spend envelope).

6.5a Set-level acceptance

P The existing eval-set contract already defines exact/numeric/rubric dimensions, weights, blocking flags and pass_threshold. The runner evaluates every declared case on the pinned subject, route, input, oracle and tolerance hashes. A blocking dimension must pass; Unknown on it is failure for publication. For non-blocking dimensions compute the declared weighted score over the full declared denominator—an Unknown earns no credit, never disappears from the denominator. A case passes only if its blocking dimensions pass and its score reaches its threshold.

P A set is green only when every required case has completed and passed, with no Unknown or infrastructure failure standing in for success. This initial aggregate rule is explicit; changing a corpus or threshold is a governed revision, not an operator override at publish. Deterministic handler profiles run code/contract tests; model profiles additionally run their selected route. Store each result and tolerances in the immutable eval report; the latest matching green run, not a green run on an older dependency set, supports publication.

6.6 Skills

P A skill's source of truth is Markdown in the memory tree, owned by its domain; publishing writes the catalogued, versioned runtime row with permissions; workers reload at the next turn boundary, while a running case keeps the version it started with (pinned); customer packs ship as plugins (Architecture § 1). Executable skills — the getRates, offer and policy testers, diagnostic query packs — bind an instruction to connector tools plus assertions, and are published through the same flow. A skill that writes carries its dry-run default and its teardown with it. What a skill is — its anatomy, when one exists, what happens when it fails — is Agents Memory and Skills; which skills each module needs is on that module's page, under its agent tree.

7. Knowledge and skills

P Knowledge is a framework service, not a component beside the agents: one memory tree, an AGENTS.md index per node, one writing profile per node, and a governed path from what a case learns to what every case may reuse. Skills are the executable half of the same knowledge — an operation bound to a domain, governed like a prompt. Both are specified on one page, as principles with one example each: Agents Memory and Skills — the tree and its protocol, the dreaming pass, the past-case index, an inherited corpus's migration (Part I); what a skill is, when one exists, its governance, what happens when it fails, three samples (Part II). What each module's branch of the tree holds and which skills it runs is at the head of that module's page, under its agent tree (§ 4, D145, D151).

Challenges

• P Framework versioning P (Challenge Rounds § R2 § 4). framework_version (assembly version + git sha) is stamped on every turn record, usage row and invoke_agent span; a case resumed under a newer framework writes FRAMEWORK_CHANGED; release n reads release n−1's checkpoints. What re-runs is decided by the release manifest's affects ⊆ {loop, tools, memory, gates, records, spawning, governance, operations}: replay tests always; the eval sets of profiles whose declared services are affected plus a canary set (one root and one stage profile per module); a full re-run of every published set only when loop or tools is affected. Releases at most monthly in T3, the pre-release run outside the weekly eval envelope; rollback = the previous image tag, checkpoints untouched. Confirmed when: after two consecutive loop releases with zero full-run regressions, the canary rule replaces the full run.
• C Eval-set budget: a full re-run on every memory write is unaffordable; batching by domain, on a schedule and before publish, is the proposal — measured against the spend envelope (Metrics) once real numbers exist.
• P Name, source, or nothing: the health-AI branch is not merged, so nothing is linked from it; the governance services are copied or re-implemented per the verdicts in Software Architecture, confirmed project by project before the first platform sprint.