Agent versions
Agents are data, not copy. An agent acts under the service identity agent:<agent_key>@<org_id>, every run
records which agent_versions row ran, and the model behind it is a model_configs row the UI shows as
“Model configuration MC-n (recorded <date>)”. Model ids enter the system only through the environment
variables AGENT_MODEL_ID and EMBEDDING_MODEL_ID; no code, document or copy names a model.
Roles
One console orchestrator, four product specialists and a reader run in one container. Each role holds its
own run token, so the table is enforced by the tool server from the token’s role, not by which tool list a
process was handed.
Role (agent_key) | Reads | Proposal writes (gated) | Never |
|---|---|---|---|
console | thread, plan, specialists as tools | plan artifacts | record writes |
evidence | questions, sources, findings, hypotheses, gaps, documents, knowledge.* via the reader | findings, hypotheses (proposed), gaps (open), sources | hypothesis decisions |
plans | plans, protocols, experiments, reports, connector objects, accepted requirement sets | protocol and report drafts (draft), experiments (planned) | transitions, approvals |
review | SOPs and versions, checks, findings, deviations, connector objects | checks, review findings (open), deviations (suspected), requirement sets (proposed) | finding decisions, deviation closure, requirement acceptance |
progress | milestones, dependencies, open items, approvals, overview | open items, proposed milestone changes | approval requests, approval decisions, signatures |
reader | knowledge.fetch_document, documents.read_chunks, documents.wait_ready, eln.read_entry, sop.read_version | none | everything else |
*.approve, progress.request_approval and signatures.* are not tools. Retrieved text reaches only the
reader, whose summaries are labelled untrusted:document:<id>; the tool server sanitises every result
(provenance label per chunk, delimiter spotlighting, injection heuristic, markup allowlist, redaction) and the
rail prints “Injection pattern flagged in document N” when the heuristic fires.
agent_versions (AgentVersionOut)
| Field | Meaning |
|---|---|
agent_key | one of the six roles |
prompt_version, skill_versions, check_logic_version | what the version runs; check_logic_version is copied onto every check it creates |
model_config_id, model_config_label | the model_configs row (MC-n) |
image_digest | the container image |
status | candidate -> active -> retired; activation needs a passing evaluation report (eval_report_ref) |
activated_at | when it became the active version |
Records created from a run carry agent_run_id, and the run carries agent_version_id, so a finding, check
or draft can always be traced to the prompt, skills, check logic and model configuration that produced it. A
check with a different (sop_version_id, requirements_hash, check_logic_version) triple is a new check with
supersedes_check_id.
model_configs
| Field | Meaning |
|---|---|
label | MC-n, the only form shown in the UI |
model_id_value, inference_profile_id, embedding_model_id_value, region | recorded values; never static copy |
recorded_at, recorded_by | who recorded the configuration and when |
Verification at run start: the container’s bootstrap result reports its model id, inference profile id
and region; the worker compares them with the active version’s model_configs row and refuses to run with
config_mismatch until a new agent version is activated. The outcome (match, config_mismatch,
unverified) is written to run_snapshots.model_check with expected_model_config_id,
reported_model_id_hash and inference_profile_id, so residency and model provenance are evidenced per run
rather than assumed.
Capabilities (AgentCapabilityOut)
GET .../agent-capabilities (program.agent_runs.read) lists agent_key, capability_key, name,
context_of_use, limitations, risk_class (operational or evidence_generating) and status (a release
word). The same plain-language text is held in CLAIMS-REGISTER.md; a capability moves from preview to
available only through the evaluation programme.
Run snapshot (RunSnapshotOut)
Written by the worker-side context assembler by reference: chunk ids and hashes, record ids with
updated_at, sop_version_ids, prompt version, tool allowlist, policy version, permission snapshot and the
model check outcome, plus context_hash. Events stay excerpt-free. Setup › Agents filters runs by
agent_version_id and opens a snapshot; the thread export and the audit export carry the same identifiers.
Evaluation programme
Before any capability moves preview -> available: 20 to 50 outcome-graded tasks per product from pilot
transcripts (finding cited and correct; deviation matched to the right clause; effective version selected for
a date; blocker computed; the injection scenario), reviewer labels including unknown; deterministic checks
(citation coverage, licence gating, plan adherence, attribution lint, redaction parity, schema validity);
judged checks (semantic grounding) calibrated against QA labels; a pass^3 gate on every agent_versions
change before active. Requirement extraction is enabled for the pilot only after a measured result on one
partner SOP is registered. Before pilot transcripts exist the suite starts from public procedure-like
documents and open literature, labelled illustrative in the evaluation report.
Source: api/app/db/models/agents.py, api/app/db/models/conversation.py (run_snapshots, MODEL_CHECK_OUTCOMES), api/app/auth/run_tokens.py, api/app/config.py, api/app/services/audit.py (agent_actor_id), web/lib/api/types.ts, web/lib/content.ts (consoleCopy.modelConfiguration), PRODUCT-CONTRACT.md sections 10.4 and 10.7, PRODUCT-PLAN.md Part 4 sections 4.1, 4.3, 4.6, 4.9 and 5.3, decisions/0019-model-configuration-as-data.md