> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/files/overview) attached to the workspace:
```ts agents/support.ts theme={null}
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**](/models/overview) | Structured data | CRM objects, product databases, SQL tables |
| [**Files**](/files/overview) | 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](/deploy/state-and-drift#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](/files/overview).
***
## Best practices
Narrow down data access to what the agent actually needs. Less noise =
better reasoning.
Help the agent understand how to query your data and what matters most.
For models, use SQL for filtering and aggregating, Vector for semantic
search.
Run test prompts to verify the agent retrieves the right data.
***
## Learn more
Learn how to build and manage structured data models.
Work with documents, PDFs, and unstructured content.