Skip to main content
Resources give your agent access to your organization’s data — CRM records, knowledge bases, product databases, and more. This is called RAG (Retrieval-Augmented Generation): the agent retrieves relevant information before generating responses. In code, structured data is wired through the models array on defineAgent; unstructured content comes from files attached to the workspace:
agents/support.ts
export const support = defineAgent("support", {
  connector: openai,
  languageModel: "gpt-4o",
  systemPrompt: "Answer using our CRM data and playbooks; never invent facts.",
  models: [
    {
      ref: deals,
      readOnly: true,                       // don't let it write back
      columns: ["name", "stage", "amount"], // narrow the surface
      prompt: "Query open deals to check account status.",
    },
  ],
});
Each models entry is a model handle (or modelRef(uuid)), bare or wrapped as { ref, readOnly, columns, prompt }. Without resources, an agent only knows its instructions and what web search returns.

​
Types of resources

There are two types of resources you can connect to your agent:
TypeData formatExamples
ModelsStructured dataCRM objects, product databases, SQL tables
FilesUnstructured dataPDFs, documents, transcripts, knowledge articles

​
Models

Models connect your agent to structured data — tables with rows and columns. The agent queries this data using SQL, making it ideal for filtering, sorting, and aggregating records. Best for:
  • CRM Objects (HubSpot Deals, Salesforce Accounts, Attio Records)
  • Product Data (usage databases, analytics platforms)
  • Custom Databases (BigQuery, Snowflake)

​
Files

Files connect your agent to unstructured data — documents, PDFs, and text content. You select which files or folders to include, and the agent searches this content using vector similarity to find relevant information. Best for:
  • Knowledge Bases (Notion, Google Docs, uploaded files)
  • Playbooks, FAQs, and process documentation
  • Meeting transcripts and call notes
When a workspace has a context repository configured, non-temporary files from the workspace Files library are also mirrored under .files/ in that repo (preserving folder structure). That tree is read-only in the context runtime — agents can read mirrored files but cannot write, edit, or auto-commit changes under .files/. Update files in the Files library; Cargo syncs them into context.

​
Configuring a model resource

​
In code

The { ref, …options } wrapper covers the settings that matter most:
OptionEffect
readOnlyBlock writes back to the model (defaults to true on agents)
columnsOnly expose these column slugs — less noise, better reasoning
promptCustom instructions for how the agent should query this resource

​
In the UI

The agent’s Resources tab adds settings that don’t have a code equivalent yet — configure these in the UI after deploying:
SettingDescription
Query modeSQL (filter, sort, aggregate) or Vector (semantic similarity over text fields)
FiltersRestrict which records the agent can access
LimitMaximum number of records returned per query
SQL example:
“Find all deals in the Discovery stage with value over $50k”
Vector example:
“Find companies with product descriptions similar to AI automation”
UI-configured settings on a code-managed agent are overwritten if you later change that agent in code and re-deploy — see Code and UI round-trips.

​
Configuring files

File resources are selected in the UI today (the agent’s Resources tab): choose the files or folders to include, and the agent searches all selected content by vector similarity. A per-resource prompt guides how the agent interprets or prioritizes the content: 
This folder contains our sales playbooks. Prioritize the
objection handling guide when the user asks about pricing concerns.
Upload and organize the underlying files from code and the CLI — see Files.

​
Best practices

Start with filters

Narrow down data access to what the agent actually needs. Less noise = better reasoning.

Write clear prompts

Help the agent understand how to query your data and what matters most.

Choose the right query mode

For models, use SQL for filtering and aggregating, Vector for semantic search.

Test before deploying

Run test prompts to verify the agent retrieves the right data.

​
Learn more

Models

Learn how to build and manage structured data models.

Files

Work with documents, PDFs, and unstructured content.