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

# Integrating Tables with Agents

Timely.ai allows Agents to interact with **Tables** (also known internally as *Datagrids*) through specialized **Tools** that provide permission-based access to perform specific operations — such as inserting, updating, or retrieving data.

These Tools act as **capability enablers**: each one grants a distinct level of interaction between the Agent and the Table.\
Without an appropriate Datagrid Tool assigned, an Agent cannot read or write data to that Table.

***

## 🧠 How Integration Works

Each Table can be linked to one or multiple Agents.\
However, instead of a direct connection, integration is managed through **Datagrid Tools** — each representing a precise permission scope.

When a Datagrid Tool is attached to an Agent, it defines *what kind of actions that Agent can perform* on the target Table.

> ⚙️ **Note:**\
> Workflows currently **cannot** interact directly with Tables.\
> Only Agents can perform these operations, and if needed, they can **pass the retrieved data to a Workflow** through a Request Node.

***

## 🧩 Available Datagrid Tools

Below is a list of the available **Datagrid interaction Tools** and their purposes:

### 1. 🔵 Datagrid Row Insertion

**Function:**\
Allows the Agent to insert a new row into a specific Table based on structured or contextual information gathered during a conversation.

**Typical use cases:**

* Logging user inquiries or form submissions.
* Saving contact data, tickets, or feedback.

**Example:**

> “Store this user’s question in the *Unanswered Questions* table.”

***

### 2. 🔵 Datagrid Row Update

**Function:**\
Allows the Agent to modify existing rows in a Table by matching a unique identifier or condition.

**Typical use cases:**

* Updating the status of a contact or request.
* Changing the sentiment field in a feedback record.

**Example:**

> “Update the *status* field of chat `5edca67d-dd2d...` to `resolved`.”

***

### 3. 🔵 Datagrid Row Semantic Search

**Function:**\
Grants the Agent permission to **search Table rows using semantic understanding** — meaning queries are based on contextual similarity, not only keywords.

**Typical use cases:**

* Retrieving questions similar to a current user inquiry.
* Searching for feedback containing specific intent or emotion.

**Example:**

> “Find all feedbacks that mention onboarding issues.”

***

### 4. 🔵 Datagrid Row Similarity Search

**Function:**\
Allows the Agent to perform **similarity-based vector searches** among Table rows, often used for advanced matching or clustering operations.

**Typical use cases:**

* Identifying duplicate records or repeated questions.
* Finding content with semantic similarity to a new input.

**Example:**

> “Search for entries similar to this user’s message.”

***

## 🔐 Permission-Based Architecture

Each Datagrid Tool represents a **permission level** within the Agent’s operational scope:

| Tool                               | Permission Level     | Read / Write | Semantic Access |
| ---------------------------------- | -------------------- | ------------ | --------------- |
| **Datagrid Row Insertion**         | Create               | ✅ Write      | ❌               |
| **Datagrid Row Update**            | Modify               | ✅ Write      | ❌               |
| **Datagrid Row Semantic Search**   | Query (contextual)   | ✅ Read       | ✅               |
| **Datagrid Row Similarity Search** | Query (vector-based) | ✅ Read       | ✅               |

> ⚙️ Assigning a tool effectively grants that Agent the associated Table capability.\
> Without it, the Agent cannot perform those actions, even if it references the Table in conversation.

***

## 🔗 Connecting a Table to an Agent

To link a Table to an Agent, follow these steps:

1. Open the **Agent Builder**.
2. Go to the **Tools** tab.
3. Click **Add Tool +** and select one of the **Datagrid Row Tools**.
4. Configure:
   * The **target Table** you want the Agent to access.
   * Any specific parameters or permissions.

Once added, the Agent can interact with the Table within the defined tool boundaries.

***

## 🔁 Example — Using Multiple Tools

An Agent may require more than one Datagrid Tool to fully manage a Table.\
For example, a *Support Agent* may need:

* **Datagrid Row Insertion** → to record new issues.
* **Datagrid Row Update** → to mark them as resolved.
* **Datagrid Row Semantic Search** → to check if a similar issue already exists.

Each of these tools would be individually added to the Agent to grant the corresponding capabilities.

***

## 🧩 Data Flow Example (Agent + Workflow)

While Workflows cannot access Tables directly, Agents can serve as **data intermediaries**:

1. The Agent performs a **Semantic Search** in a Table.
2. It retrieves the result in context.
3. The Agent then sends this structured data forward through a **Request Node** (e.g., HTTP or Workflow call).
4. The Workflow processes the received data for automation or analytics purposes.

This architecture maintains **data integrity**, ensures **AI-controlled access**, and prevents unauthorized manipulation of Table data.

***

## ⚙️ Best Practices

| Recommendation                      | Description                                                                             |
| ----------------------------------- | --------------------------------------------------------------------------------------- |
| **Use precise column descriptions** | Helps the Agent understand each field’s purpose when inserting or updating data.        |
| **Assign only necessary Tools**     | Avoid giving Agents permissions they don’t need (e.g., write access when only reading). |
| **Combine Tools logically**         | Agents can use multiple Datagrid Tools for full CRUD-like control when needed.          |
| **Monitor output via logs**         | Review Agent logs to confirm correct table operations and semantic matches.             |
| **Avoid redundancy**                | Use Similarity Search only when precise vector comparison is required.                  |

### Final Note

In Timely.ai, Tables are not just passive data containers — they’re part of the **Agent’s extended cognitive framework**.\
By combining Tables with the right Datagrid Tools, your Agents gain the ability to **reason contextually, act autonomously, and persist knowledge** — safely, intelligently, and under precise permission control.