Agentic Integrations
Agentic Integrations
Trilogy can be the data access layer in your agentic loops - making your agents faster, smarter, and more reliable, especially on messy warehouse context.
Give your agent a shared semantic model, let it write and check Trilogy, and execute the resulting SQL against your database. The agent can use the results to answer a question, build an artifact, or decide what to investigate next. Bring the loop of your choice; Trilogy provides the data context and query engine.
Accurate zero-shot text to SQL comes from constraining the surface area of translation and injecting accurate context; reliable answers come from fast feedback loops so 0-1 doesn't need to succeed every time.
Trilogy provides all of those - a constrained syntax and set of fields that provides exactly the right amount of context without sacrificing the expressiveness of SQL; and fast feedback loops even before you hit the database for typing, syntax, etc.
Semantic layers that are decoupled from SQL have been a pain. But by marrying the engine and the layer, the semantic layer comes into its own. Rich typing and modeling actually makes you and agents more productive - a lesson we've learned from decades of experience in other programming languages. Correct SQL needs FK/PK constraints, nullability information, cardinality/grain info, details on what the values in a column mean, and more.
Tips
If you have a small, well-maintained local DB - you probably can just throw it at an agent. Do what works best for you. Semantic layers start to pay off when you have a large, messy DB where re-exploring burns lots of context OR when DB queries are expensive (MPP, cloud, etc).
And your semantic layer can't be YAML. It needs to be a first-class language, with functions, logic, and reuse. Forcing humans to context switch to do different parts of their core job to be done will inevitably fail; and since the semantic layer has never been the 'main thing', it's always the thing that is dropped.
Trilogy can unify all of these - interactive, curated, machine - giving a shared, flexible context layer.
Bring Your Own Loop
Use the CLI from a coding agent, embed the Python SDK in your application, or connect through the MCP server in trilogy-studio-core. The same model and query language work across all three.
A typical loop is straightforward:
- Read the model to discover fields, metrics, and their meaning.
- Write a Trilogy query and use compiler feedback to fix typing or syntax errors before querying the database.
- Execute through your configured database connection, inspect the results, and refine the analysis.
For a CLI-based agent, start with trilogy agent-info - a self-contained guide to the commands and language. See the agent info reference, or try the built-in CLI agent for a ready-made loop.
Looking for an interactive analytics experience instead? Trilogy Studio's built-in agent chat brings the conversation, queries, and artifacts together in the browser.
Why Now
Text to SQL has been a fairy tale for some time. But modern LLMs excel at transforming unstructured inputs - a business user saying 'give me this thing' - into structured outputs. It's actually feasible now to build a 'clarify, contextualize, and generate' loop similar to what an analyst would need to do.
And progress has been fast - two years ago, we needed to build a railroad for LLMs to walk them down a specific path to build syntactic Trilogy. This worked well, but had increasing costs as we aspired to have them answer more and more complex queries.
Today, we can fix up some compiler messages, give them a few examples, and let an agent go wild. They need no DB access to read the model and compile queries with Trilogy - just a semantic model that gives them the context they need, and an expressive language to run with. Execution still uses your database connection and its permissions. Modern LLMs bring an enormous amount of the 'context' that is required to disambiguate (synonyms, business jargon, etc), and agentic tool use loops let them refine and improve their results.
Info
As an aside from the team, we've spent collective years wrestling with chatbots, NLTK, tokenizing, and semantic parsing, to get middling results - the world we're in today is magic. Take a moment to appreciate it!
What You Get
We want Trilogy to be an LLM-native language - though AI is optional. As a data access layer for agents, it should deliver the following:
- High precision. Accuracy is non-negotiable.
- No special syntax - humans need to review logic and extend it. Use the same language for everything.
- Performant - magic is more magic when it's fast.
- One-shot when possible - iterative cycles shouldn't be a requirement to get a good answer
Installation
The core trilogy SDK comes with AI helpers. Install with the ai flag to get dependencies. (just httpx) You'll also need an API key to your favorite provider - OpenAI, Anthropic, or Google.
pip install pytrilogy[ai]
Tips
You can also just wrap normal Trilogy query generation in an AI loop of your choice! Trilogy Studio does this on the frontend, for example - the 'here's a model, write a query, syntax check it, and refine until errors are gone' is straightforward to implement.
Quickstart
For an application that just needs a query-generation step, the SDK helper handles the write, check, and retry loop. Your application decides when to execute the query and what to do with the results.
from trilogy import Environment, Dialects
from trilogy.ai import Provider, text_to_query
from pathlib import Path
import os
executor = Dialects.DUCK_DB.default_executor(
environment=Environment(working_path=Path(__file__).parent)
)
api_key = os.environ.get("OPENAI_API_KEY")
if not api_key:
raise ValueError("OPENAI_API_KEY required for gpt generation")
# load a model
executor.parse_file("flight.preql")
# create tables in the DB if needed
executor.execute_file("setup.sql")
# generate a query
query = text_to_query(
executor.environment,
"number of flights by month in 2005",
Provider.OPENAI,
"gpt-5-chat-latest",
api_key,
)
# print the generated trilogy query
print(query)
# run it
results = executor.execute_text(query)[-1].fetchall()
assert len(results) == 12
for row in results:
# all monthly flights are between 5000 and 7000
assert row[1] > 5000 and row[1] < 7000, row
Details
It's really basic - we give the AI the language syntax rules, some examples, and the concepts from the current model. Then we ask it to generate a query, check syntax, and repeat the loop until it gets a valid query or runs out of tries. No database required; no big exploratory loops.
Tips
AI messing up? Update your model! Pre-define helpful metrics; add comments; improve typing and naming. It'll help humans too!
Optimizing The Language for Agents
We've done measurement ourselves.
We benchmarked agents writing Trilogy against the full TPC-DS query suite and iterated on the language and model until they beat hand-written SQL. Read about what we changed and why in Optimizing Agents: TPC-DS, and the philosophy behind it in Optimizing Agents: The Pit of Success.
Examples
California Sales
Tips
This public instance might take a minute.