Skip to main content

Talking to the Agent

Learn how to get the most out of the AI agent — how it thinks, what it can do, and how to prompt it effectively.

How the Agent Works​

When you send a message, the agent goes through a tool loop:

  1. Thinks — Analyzes your request using extended thinking (up to 8,000 tokens of reasoning)
  2. Plans — Decides which tools to call to answer your question
  3. Executes — Calls tools and waits for results
  4. Iterates — Repeats until the answer is complete (max 10 steps)

Responses stream in real-time, so you see progress as it happens.

What the Agent Can Do​

Data Exploration​

  • List connections — See all available databases
  • Browse schemas — Explore tables and columns
  • Preview data — Sample rows from any table

Cell Operations​

  • Create cells — Add SQL, Markdown, or Chart cells
  • Edit cells — Modify content, rename, reposition
  • Execute cells — Run queries and wait for results
  • Delete cells — Remove cells (requires your approval)

Building Pipelines​

  • Create edges — Connect cells to form data dependencies
  • Run downstream — Execute a cell and everything that depends on it

Semantic Layers​

  • Search definitions — Find relevant metrics and dimensions
  • Pin versions — Lock a semantic layer version to the notebook

Tool Approvals​

Some operations require your explicit approval before executing:

OperationWhy Approval?
Delete cellDestructive — can't be undone
Pin semantic layerChanges notebook behavior

When approval is needed, you'll see a card showing exactly what the agent wants to do. Click Approve to proceed or Reject to decline.

Token Usage & Costs​

The agent uses Claude Opus 4.5. Costs are visible in the chat footer:

  • Input tokens — Your messages + context
  • Output tokens — Agent's responses + reasoning
  • Cache savings — Repeated context is cached (90% cheaper)

Typical costs per conversation are a few cents. Heavy analysis sessions might cost $0.10-0.50.

Prompting Tips​

Be Specific​

❌ "Show me sales"
✅ "Show monthly sales revenue for 2024, grouped by product category"

Reference Your Schema​

✅ "Join the users table with orders on user_id"

Iterate​

Start simple, then drill down:

  1. "Show me the orders table"
  2. "Now group by customer and sum the total"
  3. "Add a chart showing the top 10"

Use Semantic Layers​

If you have defined metrics, reference them:

✅ "Show me monthly_recurring_revenue by region"

Troubleshooting​

Agent doesn't know my schema​

Make sure you've connected your database and it's visible in the Connection Explorer.

Queries are slow​

The agent has a 30-second timeout per query. For complex queries, break them into smaller steps.

Agent hallucinates table names​

Define a semantic layer to ground the agent in your actual schema.

Tool keeps failing​

Check the error message — usually it's a SQL syntax issue or missing permissions. You can manually edit the cell and re-run.