Resources & context

Ground an agent in your data — models wired through defineAgent, files searched by vector similarity, and the context repository.

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 agent’s uses array (alongside its tools and actions); 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.",
  uses: [
    {
      ref: deals, //                          a defineModel handle
      readOnly: true, //                      don't let it write back
      columns: ["name", "stage", "amount"], // narrow the surface
      prompt: "Query open deals to check account status.",
    },
  ],
});

A data model in uses is a model handle (or modelRef(uuid)), bare or wrapped as { ref, readOnly, columns, prompt } — its kind is read from the handle, so it sits in the same array as the agent’s tools and actions. 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:

Type	Data format	Examples
Models	Structured data	CRM objects, product databases, SQL tables
Files	Unstructured data	PDFs, 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:

Option	Effect
readOnly	Block writes back to the model (defaults to true on agents)
columns	Only expose these column slugs — less noise, better reasoning
prompt	Custom 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:

Setting	Description
Query mode	SQL (filter, sort, aggregate) or Vector (semantic similarity over text fields)
Filters	Restrict which records the agent can access
Limit	Maximum 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.