# Integrating Tables with Agents

Zaia Endless 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 Zaia Endless, 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zaia.app/tables/integrating-tables-with-agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.