Data Agents
The Data Agents component manages AI-powered agents that operate on top of Timbr’s ontology-based semantic layer.
Agents use the virtual knowledge graph to translate natural language requests into SQL, enabling use cases such as NL2SQL, GraphRAG, and agent-based workflows. Each agent connects one or more knowledge graphs to an LLM, allowing queries to be executed against the underlying data while preserving business meaning and relationships.
Agents are scoped to specific ontologies and can be refined by selecting which concepts, views, properties, and tags are accessible. Execution options control SQL validation, retry behaviour, and result limits, while advanced options enable multi-step reasoning and custom context to guide query generation.
Manage Data Agents
All available agent configurations can be found in Manage Agents, which can be accessed through the Manage tab by clicking on Agents.
On the right of the screen are the search filters enabling you to search through the agents by connected knowledge graphs as well as free text search.
Adding a new Agent
On the top right is Add New Agent that when clicked on will open a pop-up in order to begin adding a new agent to the environment.
When Add New Agent is clicked, a pop-up window will appear where all the relevant configuration details must be provided. The form is organised into collapsible panels.
Panel 1: Agent Information
| Field | Required | Description |
|---|---|---|
| Agent Name | ✓ | A unique identifier for the agent. Converted to Timbr name format automatically. Cannot be changed after creation. |
| Description | - | An optional description explaining what the agent is used for. |
Panel 2: Ontology & Scope
Defines which knowledge graphs and data the agent has access to.
| Field | Required | Description |
|---|---|---|
| Ontology | ✓ | One or more knowledge graphs the agent is scoped to. When an ontology is added, its concepts, views, properties, and tags are fetched automatically. |
| Concepts List | - | Specific concepts the agent is allowed to query. Supports multi-select with ontology grouping. Use Exclude All Concepts to prevent access to all concepts. |
| Views / Cubes List | - | Specific views or cubes the agent is allowed to use. Supports multi-select with ontology grouping. Use Exclude All Views to prevent access to all views. |
| Include Logic Concepts | - | When enabled, the agent's scope includes logical/calculated concepts. |
| Include Tags | - | Restricts the agent's scope to concepts, properties, and relationships marked with the selected tags. |
| Exclude Properties | - | Specific properties to exclude from the agent's scope. |
| Graph Depth | - | Controls how deep the ontology graph is traversed when building context for the agent (default: 1). |
When multiple ontologies are selected, concepts and views are displayed with their ontology prefix (e.g., ontology1.PersonConcept) to avoid ambiguity. Removing an ontology from the selection automatically clears any concepts, views, or properties that belonged to it.
Panel 3: Execution Options
Controls how the agent validates and retries SQL queries.
| Field | Required | Description |
|---|---|---|
| Validate SQL | - | When enabled, the agent validates the generated SQL before execution. Enables the Retries field. |
| Retries | - | Number of retry attempts if SQL validation fails (default: 3). Visible only when Validate SQL is enabled. |
| Retry If No Results | - | When enabled, the agent retries the query if it returns an empty result set. Enables the No Results Max Retries field. |
| No Results Max Retries | - | Maximum number of retry attempts for empty result scenarios (default: 2). Visible only when Retry If No Results is enabled. |
| Results Max Limit | - | The maximum number of rows the agent is allowed to return. Prevents large dataset queries from overloading the system. |
Panel 4: Advanced Options
| Field | Required | Description |
|---|---|---|
| Enable Reasoning | - | Enables multi-step chain-of-thought reasoning. When enabled, the Reasoning Steps field becomes available. |
| Reasoning Steps | - | The number of reasoning steps the agent will perform before generating SQL (default: 2). Visible only when Enable Reasoning is enabled. |
| Database Is Case Sensitive | - | Indicates whether the connected back-end database treats identifiers as case-sensitive. |
| Note (Additional Context) | - | Custom instructions or extra context provided to the agent. Use this to guide the agent's query generation behaviour. |
When all details are entered, Create Agent must be clicked in order to save the configuration and register the agent with the environment.
Editing an existing Agent
Each agent row contains 3 horizontal dots on the right that when clicked on offer the following additional options on the selected agent:
Edit - Opens a window to edit the selected agent and its configuration. The agent name is read-only and cannot be changed after creation.
Test Agent - Executes a test query to verify the agent is correctly configured and responsive.
Delete - Permanently removes the selected agent configuration.