Herald

Files agents download

Spreadsheets, CSVs and slide decks kept as the original file, for agents that need the real thing rather than a description of it.

Updated

Some context only works as the file itself. An agent building a quote needs the actual price list. An agent drafting a deck should start from your template, not a summary of it. For these, a workspace can hold the original file and hand it to agents on request.

What can be attached

Excel (.xlsx), PowerPoint (.pptx) and CSV files, up to 50 MB each.

A CSV usually works better as a table, where each row is searchable and agents can filter and sort. Keep it as a file when agents should process it as a file rather than read it. A table page also gives agents a CSV through get_file, generated from its rows when you publish.

How it works

A file always lives on a page. The page holds the file, and its body holds your description of it.

That description is what makes the file findable. Herald doesn't read inside the file: search matches the page's title, its description and the file's name. So a page called "Q3 price list" with a body that says what's in it and when to use it will be found for pricing tasks. A page called "export_final_v2" with no description mostly won't.

When a page with a file comes back from get_context, search or read_page, the agent sees a note telling it there's a file and how to get it. It then calls get_file with the page's id or title and gets:

  • the file's name, type and size,
  • a download link that works for two minutes,
  • the page's usage note and description.

The link is short-lived on purpose. Agents are told to fetch it straight away (for example with curl) and to call get_file again if it expires. Over the REST API, reading a page with a file returns the same link in page.file.download_url.

Adding a file

From Import, choose the .xlsx or .pptx files, or CSVs with Keep the file for agents to download selected. Each file becomes a new page at the top level, titled after the file name. Then:

  1. Rename the page to something a person would search for.
  2. Write a few lines in the body: what's in the file, what it's for, anything an agent should know before using it. ("One row per plan. Prices in USD, excluding tax. The Enterprise row is a starting price; real quotes come from sales.")
  3. Add a usage note if there's a rule about using it.
  4. Move it into the right folder and publish.

Replacing a file

Open the page and press Replace on the file card. The new file becomes part of the draft. Agents keep getting the previous file until you publish, just like the page text. Download gets you the current draft's file.

Who sees it

A file follows its page. If an agent can read the page, it can download the file; if it can't, it can't.