Query and Run Analysis

The analytical workflow in the Build an Agent tutorial has two connected stages: first the agent learns to ask data questions through SQL, then it learns to compute and render analysis artifacts in a sandbox. SQL is the agent's data access layer; the sandbox is the agent's computation layer. Keeping those concerns separate is important because the model should use typed tools to fetch structured data, but it should use an isolated workspace when it needs files, scripts, charts, or multi-step computation beyond a single query.

Sources: docs/tutorial/run-analysis.mdx

In the tutorial, Step 3 gives the analytics assistant a run_sql tool over a small bundled dataset, while Step 5 teaches it to seed schema context and produce a chart in /workspace. The repository source for this requested page is the Run Analysis tutorial, which explicitly says that if the real warehouse step is skipped, the analysis step still works against the Step 3 sample dataset. That makes the combined workflow useful for both paths: a no-setup local tutorial path and a production-shaped path that can later swap the sample dataset for a real warehouse connection.

Sources: docs/tutorial/run-analysis.mdx

Purpose and Scope

Use this page when you want the tutorial's data loop to feel like a real analyst workflow instead of a chatbot demo. A conversational agent can discuss metrics from general knowledge, but it cannot inspect rows until you expose a tool. Once it can query rows, it still needs a safe place to perform computations such as cohort curves, forecasts, file-based transformations, and chart rendering. Eve's tutorial models that progression by pairing a SQL tool with the sandbox filesystem and shell tools.

The term tool means an action primitive exposed to the model with typed input and structured output. In the sample-data step, agent/tools/run_sql.ts becomes the model-visible run_sql tool by filename convention, and the tool accepts a read-only SQL string. The term sandbox means eve's isolated bash environment with a /workspace filesystem. The Run Analysis page states that every agent gets exactly one sandbox and that built-in bash, read_file, and write_file tools target it.

Sources: docs/tutorial/run-analysis.mdx

The workflow is intentionally staged. The SQL tool should stay close to the app runtime because it owns database access and, in later steps, credentials or connection brokering. The sandbox should receive reference files and non-secret inputs, then produce derived artifacts such as JSON files, scripts, and PNG charts. This boundary lets the model compute without receiving warehouse tokens or process environment secrets, which the tutorial calls out directly: secrets stay out of the sandbox, and the warehouse token remains in the app runtime.

Sources: docs/tutorial/run-analysis.mdx

Relevant Source Files

• docs/tutorial/run-analysis.mdx - Defines the Run Analysis tutorial step, including sandbox workspace seeding, schema file placement, custom analysis tool code, sandbox secret boundaries, local and Vercel sandbox behavior, and the prompt that drives a charting analysis.

Core Primitives

The first primitive is the query tool. In the official tutorial flow, a tiny in-memory SQL dataset is placed under agent/lib/, and agent/tools/run_sql.ts wraps it with defineTool from eve/tools plus a Zod input schema. The model sees the tool name from the filename, not from an arbitrary runtime registry name, so a file named run_sql.ts gives the agent a run_sql action. The tool returns columns and rows, which gives the model exact values instead of forcing it to infer from prose.

The second primitive is the seeded workspace. The Run Analysis source describes a folder sandbox layout where anything under agent/sandbox/workspace/ lands in the live /workspace current working directory at session bootstrap. The example mounts schema.sql and notes/grain.md, and top-level workspace entries are advertised to the model automatically. That means the model can discover that schema.sql exists and read it before writing queries or interpreting output grain.

Sources: docs/tutorial/run-analysis.mdx

The third primitive is a custom analysis tool that uses ctx.getSandbox(). The tutorial's chart_series example writes analysis/series.json, writes a Python plotting script, resolves the sandbox path for analysis, and runs python plot.py inside that directory. This tool is different from run_sql: it does not fetch data from the warehouse. Instead, it consumes already-computed points and materializes a chart file in the sandbox workspace.

Sources: docs/tutorial/run-analysis.mdx

Execution Flow

A practical local run begins with the sample SQL dataset when no warehouse is configured. The agent receives a question such as Plot total order revenue per customer. It should use the SQL tool to compute the numeric series from orders and customers, inspect the seeded schema to confirm table shapes and grain, then call the charting tool with typed {date, value} or similarly shaped points. The expected output is not just a text answer; it can include the location of a generated PNG under /workspace.

The sandbox setup happens before the analysis turn needs it. Create the workspace seed files under agent/sandbox/workspace/, and keep them as reference material rather than secret configuration. The Run Analysis page shows schema.sql as a reference-only file with orders and customers table definitions. This is enough context for the model to avoid guessing column names, date fields, or customer-plan fields while it composes SQL or explains assumptions.

Sources: docs/tutorial/run-analysis.mdx

agent/sandbox/
  workspace/
    schema.sql        ← lands at /workspace/schema.sql
    notes/grain.md    ← lands at /workspace/notes/grain.md

-- agent/sandbox/workspace/schema.sql
-- Reference only: table shapes the analyst can read before writing queries.
CREATE TABLE orders     (id INT, customer_id INT, amount_cents INT, created_at DATE);
CREATE TABLE customers  (id INT, name TEXT, plan TEXT, signed_up_at DATE);

After seeding, the model can combine data access and computation in one run. First it calls run_sql or a warehouse connection tool to get numbers. Next it calls chart_series, which writes a JSON payload and plotting script into analysis/. The tool resolves the real sandbox path and shells out from there. The source notes an important operational constraint: the sandbox base image does not preinstall Python with matplotlib, so you must install that runtime in sandbox bootstrap or bake it into a custom image.

Sources: docs/tutorial/run-analysis.mdx

Implementation Details

The chart_series tool illustrates the shape of a sandbox-aware custom tool. It uses defineTool, validates inputs with Zod, accepts a title and an array of points, and receives the execution context as the second argument to execute. Calling ctx.getSandbox() gives the tool a live sandbox handle. The handle exposes file-writing, path-resolution, and command-running capabilities, which keeps the filesystem and shell operations scoped to the agent's isolated workspace rather than the application process.

Sources: docs/tutorial/run-analysis.mdx

import { defineTool } from "eve/tools";
import { z } from "zod";
 
export default defineTool({
  description:
    "Plot a time series to a PNG in the workspace. Pass {date, value} points; " +
    "returns the chart path.",
  inputSchema: z.object({
    title: z.string(),
    points: z.array(z.object({ date: z.string(), value: z.number() })),
  }),
  async execute({ title, points }, ctx) {
    const sandbox = await ctx.getSandbox();
    await sandbox.writeTextFile({
      path: "analysis/series.json",
      content: JSON.stringify({ title, points }),
    });
    const root = sandbox.resolvePath("analysis");
    await sandbox.run({ command: `cd ${JSON.stringify(root)} && python plot.py` });
    return { chart: `${root}/chart.png` };
  },
});

The secret boundary is part of the implementation model, not an optional deployment hardening step. The tutorial says the sandbox has no process.env and no access to app secrets. Warehouse credentials stay in the app runtime, and firewall brokering is the only path the token takes to the warehouse host. This means analysis tools should pass ordinary data or file references into the sandbox, not credentials. If the analysis needs fresh warehouse data, fetch it through the app-side tool or connection first.

Sources: docs/tutorial/run-analysis.mdx

System-to-Code Mapping

Testing Signals

The fastest manual test is to ask for an output that requires both a query and a chart, not just a textual answer. Plot total order revenue per customer. is the tutorial prompt for this stage. A successful run should show the model retrieving numbers from the warehouse or sample dataset, checking schema.sql so it uses the right columns and grain, then invoking the charting tool to render a PNG. If Python or matplotlib is missing, the failure points to sandbox bootstrap rather than SQL or agent instructions.

Sources: docs/tutorial/run-analysis.mdx

For automated confidence, the broader eve repository includes eval support in the official documentation, and the relevant pattern is to encode the analysis prompt as an eval that targets either local eve dev or a deployed app. The assertion should not only check for a final sentence; it should check that the run used the intended data path and produced an artifact reference. That keeps the tutorial workflow honest as tools, schemas, or sandbox bootstrap steps change.

Next Steps

Once this combined query-and-analysis path works, replace the toy data source with the warehouse connection from the previous tutorial step, then move on to the safety step that gates expensive scans. Keep the schema and grain notes in the sandbox workspace, but keep credentials and authorization in the app runtime or connection layer. Read the Sandbox page next if you need custom images, bootstrap installation, or network policy details before producing richer analysis artifacts.