> ## 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 `models` array on `defineAgent`; 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.",
  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:

| 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"

<Warning>
  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).
</Warning>

***

## 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

<CardGroup cols={2}>
  <Card title="Start with filters">
    Narrow down data access to what the agent actually needs. Less noise =
    better reasoning.
  </Card>

  <Card title="Write clear prompts">
    Help the agent understand how to query your data and what matters most.
  </Card>

  <Card title="Choose the right query mode">
    For models, use SQL for filtering and aggregating, Vector for semantic
    search.
  </Card>

  <Card title="Test before deploying">
    Run test prompts to verify the agent retrieves the right data.
  </Card>
</CardGroup>

***

## Learn more

<CardGroup cols={2}>
  <Card title="Models" icon="table" href="/models/overview">
    Learn how to build and manage structured data models.
  </Card>

  <Card title="Files" icon="file" href="/files/overview">
    Work with documents, PDFs, and unstructured content.
  </Card>
</CardGroup>