Pular para o conteúdo principal
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:
ToolPermission LevelRead / WriteSemantic Access
Datagrid Row InsertionCreate✅ Write❌
Datagrid Row UpdateModify✅ Write❌
Datagrid Row Semantic SearchQuery (contextual)✅ Read✅
Datagrid Row Similarity SearchQuery (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

RecommendationDescription
Use precise column descriptionsHelps the Agent understand each field’s purpose when inserting or updating data.
Assign only necessary ToolsAvoid giving Agents permissions they don’t need (e.g., write access when only reading).
Combine Tools logicallyAgents can use multiple Datagrid Tools for full CRUD-like control when needed.
Monitor output via logsReview Agent logs to confirm correct table operations and semantic matches.
Avoid redundancyUse 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.