Investigation v26.5+ PREVIEW
investigation is the first supported native capability. It accepts a goal for
one VDB and lets a replaceable runtime request bounded read actions until it can
return a conclusion or explain why it stopped.
Use it for questions where the next query depends on previous evidence, such as:
- why a workload is unhealthy across cluster, delivery and configuration data
- which operational change is correlated with an incident
- whether the available evidence is sufficient to explain a state transition
- which records should be inspected next before a human takes action
What an investigation can do
The runtime receives only the caller-authorized catalog, functions and semantic surface for the selected VDB version. It can request read-only Logical Query actions. Kubling validates and compiles each request, executes it under the initiating caller, and returns a typed observation bounded by rows, columns, bytes and deadline.
The task can return artifacts such as a plain-text conclusion. Every terminal
snapshot also reports cumulative usage and a stop reason.
A semantic package improves domain-aware planning, but it is not mandatory.
An investigation can use catalog relations when a VDB is catalogOnly.
Bounded loop
Each task is constrained by Kubling-enforced limits for:
- runtime exchanges
- input and output tokens
- model calls
- Kubling query actions
- rows, columns and bytes returned as observations
- wall-clock duration
The runtime cannot raise those limits in a response. A requested action whose shape exceeds the remaining budget is rejected by Kubling.
Possible terminal outcomes are:
| State | Typical stop reasons |
|---|---|
completed | goal_satisfied |
budget_exceeded | budget_exhausted or deadline_exceeded |
cancelled | cancelled |
failed | insufficient_evidence, policy_blocked, no_progress or internal_error |
input_required is an intermediate runtime state used for a query action or a
clarification. It is resolved inside the Kubling-to-runtime exchange before the
public fire-and-resolve request completes.
Evidence, not hidden access
Kubling returns only observations produced by accepted actions. The runtime does not receive source credentials, an unrestricted engine session or access to relations hidden from the caller.
Logical Query fingerprints, catalog revisions and semantic revisions keep the exchange tied to the registered context. If the required context is unavailable or inconsistent, the task fails instead of executing against a guessed model.
Invoke it
Send a task to:
POST /api/v1/capabilities/investigation/vdbs/{vdb}/versions/{version}/tasksSee the Task API for request and response examples.
Studio status
Studio includes an Investigations workspace that renders goals, artifacts, usage and terminal task states. It remains disabled because Kubling does not expose a read-only runtime-readiness endpoint. Use the HTTP Task API for executable validation until that readiness contract ships.
Stopping or navigating away from a Studio request would only disconnect the browser. The public ingress does not expose task cancellation.