Knowledge base — AgentNavaKit

Uploaded files

Per-agent file storage. Upload via the console's Knowledge tab, or programmatically through the SDK. The agent reads files at runtime via two always-on builtin tools — no spec wiring required.

Manage files (developer SDK)

The methods below live on an.agents. Use them from CI scripts, multi-tenant onboarding flows, or anywhere you need to populate the KB without going through the console.

uploadKnowledgeFile (agentId, file, opts?) → KnowledgeFile

Upload a Blob/File (or any Blob-shaped object). 25 MB cap per file. Accepts text/markdown/code/HTML, all images, PDF, JSON/XML/YAML. Rejects archives, executables, A/V media, and binary office formats.

const blob = new Blob([markdownText], { type: 'text/markdown' });
const file = await an.agents.uploadKnowledgeFile(agentId, blob, {
  name: 'milpitas-school-districts.md',
});
// → { fileId, agentId, name, mimeType, sizeBytes, createdAt }

listKnowledgeFiles (agentId) → KnowledgeFile[]

List all files for an agent, newest first.

const files = await an.agents.listKnowledgeFiles(agentId);

readKnowledgeFile (agentId, fileId) → Response

Returns the raw Response. Caller picks the consumer — .text() for markdown / source, .blob() for images, .arrayBuffer() for PDFs.

const res = await an.agents.readKnowledgeFile(agentId, fileId);
const markdown = await res.text();

renameKnowledgeFile (agentId, fileId, newName) → KnowledgeFile

Rename the display name. R2 key is untouched (name is metadata only).

deleteKnowledgeFile (agentId, fileId) → void

Remove a file from both the metadata index and object storage.

How the agent reads files (runtime builtins)

These two tools are advertised to every agent automatically. They are intentionally read-only — no kb_write_file or kb_delete_file exists; users own the file set, agents only consume it.

kb_list_files () → { files: [...] }

Returns metadata for every file in the agent's Knowledge tab. Agent calls this to discover what reference material is available before answering a grounded question.

kb_read_file { name } → { name, mimeType, sizeBytes, text }

Read a file's text content by display name. Returns the body for text/markdown/csv/html/code/JSON. PDF and image reads need multimodal message wiring landing in a later release — until then those types are visible in kb_list_files but error on read.

Limits & supported types

Per file: 25 MB
Accepted: text, markdown, code (.py / .js / .ts / .rs / .go / ...), HTML, images (PNG / JPG / WebP / SVG), PDF, JSON, XML, YAML
Rejected: archives (zip / tar / 7z), executables (exe / dll), binary office (docx / xlsx / pptx), audio/video, fonts
Per agent: no hard limit today; we'll add quotas once we see real usage shapes

Working memory (the `knowledge_*` tools)

A separate primitive from uploaded files. The agent writes to this from inside the loop and reads it back on later turns — durable, mutable, key-addressed.

Every agent gets these three tools without any declaration. They're how the agent reads and writes its own knowledge base from inside the loop.

knowledge_write { key, kind, body, metadata? }

Upsert a document. key is the document's stable identifier in the agent's namespace — re-writing the same key replaces the body, preserves createdAt, and bumps updatedAt. kind is a free-form classifier (e.g. 'research-note', 'customer-summary') used by knowledge_list.

knowledge_write({
  key:  'research-NVDA',
  kind: 'research-note',
  body: '## NVDA — research note\n\nEarnings on May 20…',
  metadata: '{ "symbol": "NVDA", "bullish": 3, "bearish": 5 }'
})

knowledge_get { key }

Fetch a single document by key. Returns null if absent.

knowledge_get({ key: 'research-NVDA' })
// → { id, key, kind, body, metadata, createdAt, updatedAt }

knowledge_list { kind?, since?, limit? }

List documents, newest first. Filter by kind, restrict to entries updated after an ISO timestamp, cap with limit.

knowledge_list({ kind: 'research-note', limit: 10 })
// → { docs: [...] }

When to use it

You need…	Use
Stable per-entity working notes the agent updates over time (one row per ticker, one row per customer, one row per repo)	Knowledge base. Use the entity as the `key`.
An append-only audit of decisions the agent made and why	Journal — `journal_write({ kind, summary, payload })`. Read in the workspace dashboard, not by the agent.
Conversation context across a few turns	Session history. The runtime carries this automatically.
Reference material humans curated before the agent existed (handbooks, PDFs, MLS listings, brand guides)	Uploaded files. Upload via the console Knowledge tab or `an.agents.uploadKnowledgeFile()`; the agent reads via `kb_list_files` / `kb_read_file`.

Scope

One namespace per agent. A trading agent's research-NVDA doesn't collide with a real-estate agent's same key.
All sessions of an agent share the namespace. A note the agent wrote during Monday's cron firing is readable on Friday — that's the whole point.
Subagents (the Task tool) inherit the parent's knowledge base. A research subagent can write back its findings so the parent (and future runs) can read them by key.
Cross-workspace isolation is enforced — different workspaces never see each other's documents.

Tell the agent how to use it

The three tools are advertised to the model automatically, but the agent only uses them if you tell it to in AGENT.md or a skill body. A typical pattern:

# AGENT.md (excerpt)

## Working memory

Before researching a ticker, pull existing notes:
  knowledge_get({ key: 'research-<SYMBOL>' })

After researching, persist the result:
  knowledge_write({
    key:  'research-<SYMBOL>',
    kind: 'research-note',
    body: '...your structured thesis...',
    metadata: '{"last_refreshed": "<ISO>", "symbol": "<SYMBOL>"}'
  })