Agent & Tools

The Alkera Agent works within your data code repository. A wrong change there is quiet and expensive, so the agent is built around one idea: reads are cheap, and anything that mutates state has to earn its way through.

​

Effects

Every action the agent takes is classified by its effect before it runs. SQL is parsed into a syntax tree, so the effect is taken from every statement in the tree. A DELETE hidden inside a CTE is still a delete. Shell commands are parsed the same way, including inside pipelines and subshells. An UPDATE or DELETE with no WHERE clause, or a trivially true one, escalates from write to destroy, because it touches every row and warrants human review.

​

Permission modes

The mode decides what happens when the agent reaches a non-read action. Reads never prompt in any mode. Destroy and egress sit on a floor: they prompt a human in every mode except bypass. Auto mode’s judge only decides the recoverable middle, and it fails closed. If it cannot reach a verdict, the turn stops.

​

Approving actions

When the agent is gated, you get four choices: allow once, allow always, reject once, reject always. “Allow always” records the rule for that exact operation so the same action passes next time. It is deliberately narrow. Destroy actions, egress actions, and every shell command are clamped to a single use and never remembered, so a destructive action always asks again.

​

Tools

The agent acts only through tools. Every tool call is classified by effect and passes the same permission gate, so the rules above hold whether the agent is running SQL, a shell command, or writing a note.

​

Data tools

The agent can run SQL against your connections, read table and column schemas, list the connections available to it, and run shell commands. A read is free; anything that mutates is gated by its effect. Running SQL is guarded twice. The statement is classified before it is sent, and the connection checks it again at execution. A read runs inside a read-only transaction, so a query approved as a read cannot turn into a write.

​

Lineage tools

The agent reads the lineage graph to understand how your data is produced before and after a change. These are all reads, so none of them prompt. It can locate an asset and walk its edges, trace a table or a column back to its origins, and find everything downstream of it. Before changing a schema, it classifies the change as breaking, potentially breaking, or non-breaking, which is how it answers what breaks if I touch this without running anything.

​

Knowledge tools

The agent searches and reads the knowledge base freely, since both are reads. Recording what it learns is a write. In a read-only session the agent can still search and read, but it cannot record.

​

Tools come from your connections

Which data tools the agent has depends on the connections you have enabled. A warehouse connection that can run SQL and read schema is what lets the agent query and inspect it. A read-only integration such as dbt contributes lineage and context, and never SQL execution. Disable a plugin and its tools leave the agent’s surface.

​

Background work

Rather than sit on tools that perform a long-running task such as a long build, a heavy query, or a long investigation, the agent can run it in the background. When the tool finishes, if the agent is not currently active, it will wake to respond to the tool’s result.

​

Blobs

A query that returns a thousand rows should not be pasted into a conversation. It would cost a fortune in tokens, bury the reasoning, and force the agent to transcribe numbers by hand. So Alkera does not inline large results. When a tool result is too big, it spills to a blob: a stored first-class result object the agent holds a handle to. The agent gets that handle and a small preview instead of the whole result all at once.

​

When a result becomes a blob

A result spills when its serialized size passes 64 KiB, which is roughly 16,000 tokens. Below that it comes back inline, whole. This is a size threshold, not a row count. A thousand narrow rows may stay inline while fifty wide ones spill. Running SQL is the usual producer, but any oversized result can spill, including one the agent builds itself. A blob holds either rows or text, and pages accordingly.

​

How the agent works with a blob

The agent over a blob can:

• Check the result’s shape, size, and columns.
• Profile every column for summary statistics including the most common values.
• Filter, sort, and slice it.
• Run read-only SQL over the result in place.

Because SQL over a blob returns a result, and a large result spills to a blob, the agent can chain: query a blob, get a smaller blob, query that. The agent can also build a new result and store it, write a result to a file such as Parquet or CSV, and delete one it no longer needs.

​

How you inspect a blob

In the IDE, a blob shows up as a reference in the agent’s tool card. Hover it for a preview. Click it to open the result in its own editor tab. The viewer pages through the result rather than loading it at once. Text blobs page by character. You can download the result as CSV, JSON, or plain text. The viewer does not sort or filter. To reshape a result, ask the agent to do so. Every result a chat produces is also listed on its Results page in the chat, so you can reopen one later.

​

Where blobs live

Blobs are stored on disk in your project’s .alkera directory, shared across that project’s chats and addressed by their content, so an identical result is stored once. They are scratch, not an archive. A background sweep removes blobs that no chat still refers to, after a grace period.

​

What the agent reads

Before it changes anything, the agent grounds itself in two things. Lineage tells it how your data is produced. It uses this to measure blast radius, propagating a proposed change through the column graph to find what breaks downstream. The knowledge base tells it what your data means and what your team already decided. The agent reads it before it plans, and records what it learns.

​

Sub-agents

The agent delegates work to sub-agents. Each one investigates on its own and hands back a single report.

​

Explore

Explore answers a focused question about your code or your data for the main agent. It is built for breadth, so it issues many tool calls at once. It uses the whole read-only toolbox rather than just reading files. It greps and reads code, runs read-only shell commands, and runs read-only SQL against your connections, inspecting schemas and running SELECT, SHOW, and DESCRIBE to check real data instead of guessing from DDL. It walks the lineage graph to answer what feeds an asset or what reads it and can read blobs.

​

Review

Review checks a change you have already made and reports findings to the main agent. It anchors itself in the real diff, then reasons about correctness the way a careful reviewer would: join grain and fan-out, nulls and duplicates, type and cast issues, incremental keys, whether tests were updated, whether a consumer broke. Where it can, it verifies against real data with read-only SQL rather than solely reasoning about DDL. For a data change it uses the lineage tools to judge blast radius, classifying the change and walking both upstream and downstream. It is required to report lineage as evidence rather than proof, surfacing how each edge was observed.

​

What sub-agents cannot do

• They are read-only. Writes are refused.
• They cannot spawn further sub-agents. No recursion.
• The main agent sees only the final report.

Several can run at once, so multiple agents can cover different areas or defect classes in parallel.

​

Related