AgentNava · Build

Knowledge and files

Agents work with files. There is no vector store to provision.

Two drives

An agent works with files, not with text pasted into a prompt. Which drive a file belongs on comes down to who owns it.

	Path the agent sees	Belongs to	You write	The agent writes
Knowledge	`/knowledge`	the agent	yes	no
Conversation	`/workspace`	one conversation	yes	yes

Neither is loaded into the prompt. The agent opens, searches and reads them with ordinary file tools, so a thousand-page corpus costs nothing until it looks something up. There is no vector store to provision, no chunking and no index to rebuild.

Knowledge

Documents that belong to the agent. Every conversation reads the same set, and it is read-only to the agent, so a turn cannot rewrite your source of truth.

await agent.knowledge.put('refunds/consumer.md', bytes);
await agent.knowledge.put('refunds/enterprise.md', bytes);

await agent.knowledge.list();
// [{ path: 'refunds/consumer.md', kind: 'file', size: 8120, ... }]

await agent.knowledge.remove('refunds/consumer.md');

Paths are yours and the agent sees them, so name them the way you would for a colleague. refunds/enterprise.md tells it something; doc_41.md does not.

One folder per agent

The folder hangs off the agent, not off a version of it. A file is readable on the next turn, including in conversations already open, and removing one removes it everywhere at once. If two bodies of work need different corpora, they need two agents.

The conversation's drive

The working directory for one conversation. The agent writes its output here, and you can put files here too: the contract this person just uploaded, the export their question is about. It goes when the conversation goes.

await conversation.writeFile('input/acme-msa.pdf', bytes);
await conversation.files();
await conversation.readFile('risk-summary.md');

Two writers share one namespace, so put what your application supplies under its own folder. Then the agent's output lives at the root and neither can stand on the other by accident.

Getting an artifact out

Call	Use it for
`readFile`	Text. Markdown, CSV, JSON, source
`readFileBytes`	Anything. The file passes through your server
`fileUrl`	A short-lived URL you hand straight to a browser

const href = await conversation.fileUrl('report.xlsx', {
  download: true,   // omit it and the browser displays the file instead
  ttl: 300,
});

fileUrl is what you want when a person clicks something. Your API key must never reach a browser, so the URL carries its own short-lived grant instead.