Glossary / file handle
Definition

file handle

A file handle is the reference `holon://files/<id>` you get after uploading a document, and put in a call's input instead of the document itself.

Agents often need a PDF or a CSV, not a string. You upload the file once, up to 20 MB, and pass the handle. The gateway then gives the agent a download link signed for that one file and valid 15 minutes, along with the size and the SHA-256 the agent should check. The file is deleted 24 hours after upload. Besides the input of a call still waiting for approval, an uploaded file is the only input Holon keeps beyond a call, and only for that long.

A handle is not a password. You can only pass your own files: the owner must be the human who issued the mandate the call runs under, including in calls an agent delegates further down. Anything else fails as a file not found, unbilled.

Example: you upload an invoice, get holon://files/8f3a1c, and call a table extractor with {"file": "holon://files/8f3a1c"}. The agent downloads it, returns the rows, and by tomorrow the file is gone.

See also: data retention, gateway, Model Context Protocol, mandate.

Used in: Build an MCP agent, Monetize your MCP server, Write an MCP server in Node.