Files

Upload unstructured content — documents, PDFs, playbooks — as searchable resources with defineFile.

Files are unstructured resources — documents, PDFs, transcripts, playbooks. When attached to an agent or tool, their content is chunked and embedded so it can be retrieved by meaning (semantic search), not just keywords. You upload one from a local path with defineFile.

Define a file

files/playbook.ts

import { defineFile } from "@cargo-ai/cdk";

export const playbook = defineFile("playbook", {
  path: new URL("./playbook.md", import.meta.url).pathname,
});

The content is uploaded on deploy; the file handle can then be referenced as an agent resource.

Supported types

Type	Extensions
Documents	.pdf, .docx, .doc
Text	.txt, .md, .markdown
Presentations	.pptx, .ppt
Spreadsheets	.xlsx, .xls, .csv

Using files in agents

Attach files (or folders of files) as agent resources. The agent searches them with vector similarity — a query for “pricing concerns” surfaces content about “cost objections” even without the exact words. Add a prompt to steer how the agent prioritizes the content.

From the CLI

cargo-ai content file upload --file ./playbook.pdf
cargo-ai content file list
cargo-ai content library list      # group files into retrieval libraries

For structured, queryable data (CRM objects, tables) use models instead — files are for unstructured knowledge.