Table Knowledge Sources

A Database Table Knowledge Source lets an AI Agent use a selected Project Database table. The Agent can read permitted records and, when explicitly enabled, request record creation, updates, or deletion.

Table access should be configured around a specific Agent responsibility. Start with read-only behavior, then enable modification operations only when the workflow requires them and the Project's authorization rules can enforce them safely.

How Table Access Is Controlled

Several controls work together:

Control	Purpose
Agent Access (Security)	Controls which Project groups may access the Agent from the client through an AI Agent Widget. It does not restrict trusted Cloud Flow invocation.
Table access rules	Control which table operations the current user may perform.
Knowledge Source settings	Determine which modification tools are exposed to this Agent.
Agent instructions and source description	Guide when the model should use the table.
Database callbacks	Allow the Agent's Cloud Flow to reject or modify specific table operations.

No single layer replaces the others. For example, enabling Allow Record Update exposes the update capability to the Agent, but it does not grant a user permission to update every record.

The table access checks in this guide apply to operations performed through the built-in Table Knowledge Source. They do not automatically protect arbitrary Database operations implemented inside a Custom Function. A Function that accesses the same table directly must authorize the Agent user before reading or changing data.

Making an Agent public does not make a table public. A public Widget invocation has public access for the built-in table tools, so a table restricted to signed-in users remains unavailable. A Function that accesses the table directly is different: without an equivalent authorization check in the Function, it can expose protected data or operations through the public Agent.

For the underlying table permissions, see Table Access.

Add a Table Knowledge Source

To add a table:

1. Open AI Agents in the Project Editor.
2. Open the Agent's actions and select Settings.
3. Expand Knowledge Sources (Files, Databases, Functions, etc).
4. Select Add → Database Table.
5. Select the Project Database table.
6. Enter a detailed Description.
7. Set Max Records per Read Query.
8. Enable only the required create, update, or delete options.
9. Select Continue.
10. Test the Agent with users from each relevant access group.

Use the refresh control beside the table selector when a recently created table does not appear.

Table Settings

Setting	Purpose
Database Table	Selects the Project table exposed to the Agent.
Description	Explains the table's data, relevant fields, and when the Agent should use it.
Max Records per Read Query	Limits the number of records returned by an Agent read operation. The initial value is 128.
Allow New Records	Allows the Agent to request creation of a record.
Allow Record Update	Allows an update intended for one record.
Allow Batch Update (Multiple Records)	Allows one operation to update multiple matching records.
Allow Record Delete	Allows deletion intended for one record.
Allow Batch Delete (Multiple Records)	Allows one operation to delete multiple matching records.

Reading is part of the Table Knowledge Source and does not have a separate enable switch. Restrict what can be read through the table's access rules and, where necessary, an Agent database callback that narrows or rejects the operation.

Write the Table Description

The description helps the model understand both the table's contents and its intended use. Include:

• What one record represents.
• The important fields and their meaning.
• Which fields identify ownership or status.
• When the Agent should read this table.
• Which modifications, if any, are appropriate.
• Relevant business terms or constraints.

Do not place secrets or hidden authorization logic in the description. It is guidance to the model, not an enforcement mechanism.

Limit Read Results

Max Records per Read Query limits the amount of table data returned through one Agent read operation.

Choose a value that supports the intended question without exposing or processing unnecessary records. A high limit can increase latency, model context usage, and the amount of data involved in a response.

The limit does not replace filtering or authorization. If a user should see only their own records, enforce that through table access and trusted callbacks rather than relying on the model to ask for a small number of records.

Enable Modifications Deliberately

Creation, updates, and deletion change persistent Project data. Enable only the operations required by the Agent.

New Records

Enable Allow New Records when the Agent should create records, such as support requests or approved workflow items.

Validate required fields, accepted values, ownership, duplicate conditions, and business limits before allowing creation.

Single-Record Updates and Deletes

Use the single-record options when the intended operation targets one specific record. The implementation still needs selection criteria precise enough to identify the permitted record.

Do not assume a natural-language reference such as “my latest order” is sufficiently precise for a consequential change. Ask for clarification or resolve the record through trusted application logic.

Batch Updates and Deletes

Batch operations can affect every record matching the selection criteria. Enable them only when the Agent has a genuine bulk-management responsibility.

Before allowing a batch operation:

• Verify that the current user is authorized for the entire matching set.
• Restrict the selection criteria to the intended scope.
• Reject empty or overly broad criteria.
• Consider requiring explicit confirmation.
• Record enough information to understand what changed.
• Test failure and partial-completion behavior.

For many applications, a purpose-built Function Knowledge Source is safer than exposing a general batch modification tool. The Function can encode the exact business operation and permitted scope, but its implementation must explicitly authorize the Agent user because it does not automatically receive the Table Knowledge Source access checks.

User Confirmation

Agent update and delete tools include confirmation behavior in their operation flow. Treat confirmation as an interaction safeguard, not authorization.

A user confirming a request does not prove that the user owns the record or is allowed to modify it. Table permissions and trusted Cloud Flow checks must still enforce the operation.

Database Operation Callbacks

The Agent's Cloud Flow can register callbacks that run before table operations initiated by the Agent.

Callback	Can Be Used To
$io.system.registerAgentDbCreateCallback	Reject creation or replace the proposed record object.
$io.system.registerAgentDbReadCallback	Reject a read or replace its match criteria.
$io.system.registerAgentDbQueryCallback	Reject an advanced query or replace its aggregation pipeline.
$io.system.registerAgentDbUpdateCallback	Reject an update or replace its match criteria and update object.
$io.system.registerAgentDbDeleteCallback	Reject a delete or replace its match criteria.

These callbacks are registered from Custom Code in the Agent's own Cloud Flow. Whenever the Agent initiates a database operation, the runtime supplies the authentication information for the user invoking the Agent, the operation details, and request context as separate callback arguments.

The callback can use the runtime-provided authentication information to decide whether the user may perform the operation. Depending on the callback, it can reject the operation or narrow or modify the proposed record, match criteria, aggregation pipeline, or update data.

A callback returns an ioLoop Result Object:

• status: true allows the operation to continue.
• status: false rejects it and returns the supplied error.
• data: null keeps the proposed operation unchanged.
• Supported replacement data modifies the record, criteria, pipeline, or update details before execution.

Use the exact callback contract from the Server $io.system API.

Authentication and Request Context

Database callbacks receive two conceptually different forms of caller information:

• Authentication information is supplied by the runtime and identifies the user invoking the Agent, including public/admin state and user identity.
• Request context contains application-defined values supplied by the Agent client or a Cloud Flow caller.

The two are supplied separately. Use authentication information and trusted Project records for access decisions. Request context can help identify a workflow, tenant selection already verified by trusted logic, or correlation identifier, but it is caller-supplied data and must not be treated as proof of identity.

For example, a callback may use the authenticated username to add an ownership condition to a read:

Requested match criteria
  AND
Trusted ownership condition for the authenticated Agent user

The callback should not accept reqContext.userIsManager = true as proof that the caller has manager permissions. It should use the separately supplied Agent authentication information and supported group-membership checks.

Table Access Examples

User-Owned Records

A customer-service Agent may read tickets belonging to the current authenticated user.

1. Grant the intended Project user groups access to the Agent.
2. Configure the table's access rules.
3. Add the Tickets table as a Knowledge Source.
4. Keep modification switches off unless required.
5. Register a read callback that constrains selection to the authenticated user's records where application rules require it.
6. Return only the fields needed for the conversation.

Controlled Status Change

If the Agent should allow a user to cancel an eligible request, a narrow Custom Function is often preferable to general table update access.

The Function can:

1. Accept a specific request identifier.
2. Verify ownership from authentication information.
3. Read the current status.
4. Enforce the cancellation window.
5. Apply one permitted status transition.
6. Return a controlled summary.

This gives the model a business action rather than a general-purpose record update tool.

Administrative Batch Workflow

An internal administrative Agent may require a batch operation. If users access it through a Widget, restrict Agent access to the appropriate group. If it is invoked from a Web Hook, protect the Web Hook with its own Access (Security) settings. In either case, enable only the required batch capability and use callbacks to validate the criteria and permitted update operators.

Development and Production Data

Test table behavior with the Project's development data before publishing. Confirm which data environment is being used by each invocation path and do not assume that every custom or external operation is isolated merely because the Project is in Preview.

Publishing does not copy development records into production. Test the Agent again with appropriate production conditions after publishing.

See Development and Production Data.

Testing Table Knowledge Sources

Test reads and every enabled modification separately.

Test	What to Verify
Permitted read	The user receives only authorized records and fields.
No matching records	The Agent reports the absence of data without inventing a result.
Unauthorized record	Access is rejected or filtered even if the prompt names the record directly.
Read limit	Large result sets remain bounded.
Create	Required fields, ownership, duplicates, and defaults are handled correctly.
Single update/delete	Criteria identify one permitted record.
Batch update/delete	Criteria cannot expand beyond the authorized scope.
Callback rejection	The Agent reports a safe, useful failure and makes no change.
Callback modification	Added criteria or changed data is applied as intended.
Repeated request	The workflow avoids unintended duplicate records or repeated changes.
Public execution	No protected data or action is available to an unauthenticated user.

Review both the Agent Run Logs and the resulting Database records. A natural-language success message is not proof that the intended data operation occurred.

Troubleshooting

Issue	What to Check
Table does not appear	Development table existence, refresh control, and Agent initialization.
Agent does not use the table	Description, System Instructions, table schema, and relevance of the prompt.
Expected records are missing	User identity, table access rules, callback criteria, and data environment.
Too many records are returned	Max Records setting, requested criteria, and callback restrictions.
Modification is unavailable	The applicable single or batch switch and the current user's table permissions.
Modification is rejected	Callback result, ownership/business rules, confirmation, and Run Logs.
Wrong records are affected	Match criteria, callback replacement data, and whether a general table tool should be replaced by a focused Function.
Works in development but not published	Production data, published configuration, Widget Agent access or Web Hook access as applicable, and runtime logs.

Good Practices

• Begin with read-only access.
• Keep record limits appropriate to the intended questions.
• Use descriptions to explain the table, not to enforce security.
• Apply table permissions and trusted callbacks to every protected operation.
• Prefer focused Functions for consequential business actions.
• Avoid batch modification unless it is an explicit Agent responsibility.
• Treat request context as data, not identity.
• Test with public, ordinary, elevated, and unauthorized users as applicable.
• Review actual records after testing changes.

For general source management, see Knowledge Sources. For callback registration and module behavior, see AI Agent Cloud Flow.