Files, artifacts and knowledge

An attachment is input. An artifact is a retained result. A workspace file belongs to an environment. Knowledge is domain information exposed through an application-owned store or capability. Decide which role a document has before wiring it into a prompt.

Accept bounded input

Validate media type, byte count, total request size and attachment count. Install cayu[files] for file-related integrations that require its dependencies. Choose extraction behavior for each supported format; an uploaded filename does not prove its content is safe or correctly parsed.

Keep provenance with extracted content. A sentence inside a document can be evidence about the document, but it cannot grant permission to execute a tool or disclose another session’s files.

Retain output before reporting success

Use the artifact interface to give results a stable identity. Test that the reported file exists, that its bytes match the expected result, and that the caller can retrieve it under the intended access policy. A model saying it wrote a report is insufficient evidence.

For workspace changes, inspect the actual diff. For a domain record, verify the owning transaction or receipt. Keep temporary work separate from results that must survive the environment’s cleanup.

Expose knowledge with a clear scope

Use the generated knowledge/ seam. Define which facts may be read, when pending writes become visible, and how the application confirms a mutation. Test stale, missing and unauthorized records, not only successful search.

Read the artifacts API, knowledge and storage API and memory guide.