Repository navigation
ADR 0036 Files reach models through views
github-actions[bot] edited this page Nov 16, 2026
·
1 revision
Status: accepted (#899). Builds on #859 (A2A files) and #120 (PII policies and guardrails).
An agent that takes documents over A2A has to see them in its model. Until #899 a model never saw a file's
bytes, and the base64 inline of an A2AFileDto was rendered into prompts, tool results and records as text.
Who sees a file, from where, in which form, and what privacy rules do to it each differ per application.
-
Bytes are never text. Every boundary renderer shows
{ mediaType, filename?, sizeBytes, sha256, source }(redactedFileOf), always on. A model message carries a file as a part; one place (toWireRequest) writes it for the wire. -
An agent opts in, field by field.
files: ModelFiles.of({ sources, views, limits, … })overdefaults.filesover the skills' limits. Without it, no byte reaches the model. - Sources × views are the model's contract. Sources: input, tool results, history. Views: original, redacted, transcription — any set, every file in every view, one heading each.
-
A policy decides what is allowed. A transcription is masked by the rules like any text; a redacted copy
has every kind the rules name blacked out; the original goes to the model only where every applying policy
says
AllowOriginal, else the application does not start. PII never reads bytes. -
Redaction is a contract.
FileRedactorandFileTranscriberhave built-ins on a cheap vision model and a project's own; a built-in that cannot do its job (nosharp, a type it does not take) is a start error. Anything that goes wrong in a redaction fails closed: the unredacted file never goes to the model in its place, and what a model wrote never enters an error message, a log or a cause. A block rule refuses an image whole unless the policy saysPiiFileAction.RedactWithModel: a model's judgement of an image is a guardrail, not a guarantee. The exact PII values go to a redaction model only on the agent's own provider, or onRedactionValues.Always. - The guards see what the model sees. Input guardrails, judges and output guardrails read the same files in the same views, masked as the agent's model reads them.
-
One guarded read, pinned. A visit reads each file once through the #859 / #904 guarded path and every
model call, guardrail and judge gets the same bytes and
sha256; a file that changed is refused. -
The developer decides the rest. Answer files (
SeenInVisitby default,Anyexplicit), tool-result file guards, limits and media types are settings with the safe default.
-
CostReport.byCategoryhas afileskey; stored records written before it read it as 0. - The root import stays light: the redactor, the transcriber's work, the history reader, the guarded views and
the answer's guard load on first use;
sharpis an optional peer dependency. -
FileSource.Historyneeds a file store: a turn keeps a descriptor, not bytes, and a history file is copied under the execution that reads it. - A redacted view of a type no redactor takes is a start error, not a runtime surprise.
AGBoss
- Home
- Delivery Pipeline
- Architecture
- Configuration
- Environments
- Workflow — the paths
- Path scope
- Workflow as a step
- Parallel — quorums and arbiters
- Routing patterns
- Rollback — declared compensation
- Routers
- Guards
- CLI — agboss
- App — @Application and createApp
- Several instances
- Running on PostgreSQL
- Running on Redis
- Your own store
- Guarantees
- Guarantees across processes
- Payments
- Execution history
- Mesh Hub — agboss hub
- Health checks
- Metrics
- Autoscaling
- Deploying on Kubernetes
- Context and Authorization
- Testing
- The test split
- Suites and Comparisons
- Eval suites — @EvalSuite
- Components
- Naming
- Standard DTOs
- Examples: 01–08, flow-patterns
- Agents — the loop
- Model providers
- Tools
- Knowledge bases (RAG)
- A2A — agent to agent
- FinOps
- Tracing
- Observability
- Turns and evaluation
- Profiles and comparisons
- Pauses — pending, resume by id
- Pause seam
- Decisions (ADR)