> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Collections with Agents

> Give your AI agents read and write access to structured data

Collections is built for agents. Once a collection is linked to an agent, the agent can query it, compute exact aggregations, and write records back — all during a normal conversation. This page explains what agents can do, how access works, and how to keep control.

## What an Agent Can Do with a Collection

When an agent has access to a collection, it gains a set of data tools:

| Capability               | What the agent does with it                                                |
| ------------------------ | -------------------------------------------------------------------------- |
| **Query**                | Find records matching a filter — "show me the open deals over €50k"        |
| **Count**                | Answer "how many" questions exactly                                        |
| **Aggregate**            | Sum, average, and group — "total pipeline value by owner"                  |
| **List distinct values** | Discover the categories present in a column                                |
| **Insert**               | Record new data captured in conversation — a lead, a task, a survey answer |
| **Update**               | Modify existing records — "mark this ticket as resolved"                   |
| **Upsert**               | Insert-or-update in one step, using a matching field like an email address |
| **Delete**               | Remove records, with safeguards (see below)                                |

Because these are structured operations on real data, answers are **exact** — a count is a count, not an estimate from retrieved text.

## Linking a Collection to an Agent

<Steps>
  <Step title="Open your agent in Agent Creator">
    Edit the agent that should use the data.
  </Step>

  <Step title="Add the data analysis capability">
    Add the collection/data tool to the agent's capabilities.
  </Step>

  <Step title="Select the collection">
    Search and select the collection to link. The linked collection appears as a card showing its rows, columns, and linked agents.
  </Step>

  <Step title="Test in the Playground">
    Ask a question the data can answer ("How many active customers do we have?") and check the agent uses the collection tools.
  </Step>
</Steps>

Back in Collections, the collection card shows which agents are linked to it.

## Access and Isolation

* **Private by default.** A collection is visible only to its owner and the agents explicitly granted access. Different agents' working data is isolated — one agent never sees another agent's records unless you share the collection.
* **Shared when you decide.** A collection can be linked to several agents when they collaborate on the same dataset — for example, a capture agent that inserts leads and an analysis agent that reports on them.
* **System fields are protected.** Agents cannot alter record identifiers, timestamps, or ownership metadata.
* **Deletes are guarded.** Bulk deletion by agents is disabled unless explicitly allowed by your platform configuration — an agent cannot wipe a collection by accident.

## Auditability

Every write an agent performs is recorded as an audit event — insertions, updates, upserts, and deletions, with the actor and the affected collection. Denied access attempts are logged too. Your platform administrators can monitor these events from the governance tools.

## Example: A Lead-Capture Agent

<Steps>
  <Step title="Create the collection">
    Create a `leads` collection — either empty, or from a CSV of existing leads with columns like `name`, `email`, `company`, `status`.
  </Step>

  <Step title="Link it to your agent">
    Give your sales assistant agent access to the collection, with instructions such as: "When a visitor shares contact details, upsert them into the leads collection using the email as the key."
  </Step>

  <Step title="Let it run">
    During conversations, the agent records each lead. Upserting by email means a returning visitor updates their existing record instead of creating a duplicate.
  </Step>

  <Step title="Analyze">
    Ask the same agent — or another one linked to the collection — "How many new leads this week, by company?" and get exact numbers. Track the trend with a chart in the Visualize tab.
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Tell the agent what the data means">
    Column names alone are ambiguous. In the agent's instructions, describe the collection: what one row represents, what units amounts are in, what the status values mean.
  </Accordion>

  <Accordion title="Use upsert for anything with a natural key">
    Contacts have emails, products have SKUs, tickets have references. Instructing the agent to upsert on that key prevents duplicate records over time.
  </Accordion>

  <Accordion title="Separate reading agents from writing agents">
    If only one agent writes and others read, data quality issues have a single source — much easier to debug than five agents all inserting into the same collection.
  </Accordion>

  <Accordion title="Review agent-written data regularly">
    Open the Data tab and sort by newest records to spot formatting drift early (wrong date formats, inconsistent categories), then tighten the agent's instructions.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols="2">
  <Card title="API Reference" icon="code" href="/products/ai-collection/api">
    The underlying REST and MCP interfaces
  </Card>

  <Card title="Agent Creator" icon="robot" href="/products/agent-factory/overview">
    Build and configure your agents
  </Card>
</CardGroup>