Knowledge and files

Where files live

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

Nothing is loaded into the prompt. The agent opens, searches and reads these folders 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.

Everything a person authored sits under /knowledge, so one search covers all of it at once:

grep -ril "refund" /knowledge

Knowledge bases

A named folder of documents that belongs to the workspace. Attach it to as many agents as you like; correct a file once and every one of them sees the correction.

const kb = await ws.knowledgeBases.create({
  key: 'product-docs',
  name: 'Product docs',
});

await kb.files.putDirectory('./docs', { include: ['**/*.md'] });
await kb.files.put('/pricing.md', bytes);

await agent.knowledgeBases.attach('product-docs');

The agent now has /knowledge/product-docs/ and finds things in it the way you would:

grep -ril "refund window" /knowledge/product-docs

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.

Attaching and detaching

await agent.knowledgeBases.attach('product-docs');
await agent.knowledgeBases.list();      // ['product-docs']
await agent.knowledgeBases.detach('product-docs');

await kb.attachments();                 // which agents read this base

Attaching publishes a version of the agent, so the change is something you can diff and roll back. A key that names no base is refused when you save, and a base cannot be deleted while an agent still attaches it, so an attachment that was valid stays valid.

Limits

The file listing reports usage, so you can check before sending something that would be refused.

Files for one agent

Documents that belong to a single agent rather than the workspace. They appear at /knowledge/_agent, alongside any bases it attaches, so one search covers both.

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

Use a knowledge base when several agents need the same documents. Use these when the documents belong to one agent and nothing else.

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

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.