Knowledge files

How it works

Each agent has a Knowledge tab. Upload PDF, plain text, Markdown, CSV or Excel files there (up to 10 MB each) and they are split into passages and indexed in the background - a small file is ready in under a minute. From then on the agent has a search_knowledge tool: when a run needs a fact that might be in those files, it searches them and reads the best-matching passages.

The agent retrieves passages, not whole documents. A question about refunds pulls the refund section of your policy, not all forty pages - which keeps runs cheap and answers focused.

What it needs

• An OpenAI connector. Indexing and searching use OpenAI’s embedding model on your key. The amounts are tiny - indexing a large document costs a fraction of a cent - but without the connector, uploads are refused. This applies even if the agent itself thinks with Claude.
• Text the file actually contains. Scanned PDFs are photographs of pages; there is no text to extract, and the upload is rejected with a message saying so.

Tables you can query

A CSV or Excel file is also turned into a table the agent can query with SQL, through a query_data tool. This is the right shape for anything with rows: a list of tenders, a product catalogue, last month’s orders. Instead of reading five thousand rows and trying to filter them in its head, the agent asks for “rows where the deadline is in the next two weeks and the category is IT” and gets exactly those back. Counting, sorting, joining two files and totals all work the same way.

The agent already knows each table’s columns and types - they are shown to it on every run, along with a sample row - so you never write SQL yourself. Tell it what to find in plain language. The Knowledge tab shows each file’s table name and how many rows and columns it has.

• Excel: every sheet becomes its own table. A title row or blank lines above the real header are skipped automatically.
• Column names are tidied to snake_case (“Ref No” becomes ref_no); the agent is told the original name too.
• Mixed formats in a column (two different date styles, say) make that column plain text rather than failing the upload; the agent can still convert it when it queries.
• Limits: a query runs for at most 20 seconds and returns at most 200 rows - the agent is told to aggregate or narrow the query when it hits either. Queries can only read the tables; nothing on the server is reachable from them.

What to put in - and what not to

Knowledge suits reference material: things the agent should look up when relevant. Rules of behaviour belong in the instructions, which the agent reads on every run without fail. A passage in a knowledge file is only seen when the agent decides to search for it - so “never promise a delivery date” goes in the instructions, and the shipping rate table goes in Knowledge.

Keeping it current

There is no re-sync: a knowledge file is a snapshot from the moment you uploaded it. When the price list changes, delete the old file and upload the new one - the old passages disappear immediately, and the new ones are searchable as soon as the file shows Ready.