Agent Tools

When Agent Mode is enabled on a widget, the AI can use tools to take actions beyond just generating text. The AI decides when to use a tool based on the conversation context.

Enabling Agent Mode

1. Open your widget settings
2. Toggle Agent Enabled
3. Select which tools to enable
4. Set the Max Tool Calls limit (default: 5 per message)

Available Tools

Image Generation

Tool name: image_gen

Generates images from text descriptions using AI. The AI can specify:

• Prompt: Description of the image to generate
• Style: photographic, illustration, abstract, or minimalist
• Aspect ratio: 1:1, 16:9, 9:16, or 4:3

Generated images are uploaded to cloud storage and returned as URLs.

Example conversation:

User: Can you create a minimalist logo for a coffee shop?

AI: [Uses image_gen tool] Here's a minimalist coffee shop logo I generated for you:

Web Search

Tool name: web_search

Searches the web and returns results with titles, URLs, and snippets. The AI can use this to find current information, verify facts, or provide references.

• Query: Search terms (max 500 characters)
• Max results: Number of results to return (1-10, default 5)

Example conversation:

User: What are the latest trends in sustainable packaging?

AI: [Uses web_search tool] Based on recent search results, here are the top trends...

Playbook Trigger

Tool name: playbook_trigger

Triggers pre-configured playbook workflows. Only playbooks that are explicitly allowed for the widget can be triggered.

• Playbook ID: Which playbook to run (must be in the allowed list)
• Inputs: Key-value pairs passed to the playbook

See Playbooks for how to create and configure playbooks.

Example conversation:

User: Please send a follow-up email to the client.

AI: [Uses playbook_trigger tool] I've triggered the follow-up email playbook. The email has been sent successfully.

Data agents

Capability: Data agents (read-only)

One switch that lets the AI answer from your own BigQuery reports. It brings every way the AI can read your data:

• Ask your data (ask_data, query_insights): plain-language questions, turned into SQL for you
• Write SQL (query_data): a SELECT query you or the AI write directly
• Dashboards (query_dashboard): the figures behind your Studio dashboards
• Table descriptions (list_data_sources, describe_table): which reports exist, what one row means and what each column contains, so the AI picks the right report before it queries

Data agents only read. They never change your data, and they only see the reports your organization has made available.

Example:

User: Which page brought in the most revenue last week?

AI: [Reads the table description of the platform report, then queries it] The homepage brought in the most revenue last week...

If your organization limits which tools agents may use, an administrator turns on Data agents there as well. That setting also lets your organization's scheduled agents read your reports (still read-only). If the widget already lists specific Studio tools, the switch only adds the ones on that list.

Knowledge agents

Capability: Knowledge agents (read-only)

Lets the AI search your organization's knowledge base (uploaded documents, notes and other knowledge files) to ground its answers in your own material.

Example:

User: What is our tone of voice for social posts?

AI: [Searches the knowledge base] According to your brand guide, social posts are warm, short and optimistic...

Knowledge agents only read. Signed-in users may be asked once for permission before the AI uses Studio tools in a conversation; without it the AI answers without them. Anonymous visitors never get these tools.

The two sections below describe the individual data tools in more detail.

Query Data

Tool name: query_data

Executes a SQL SELECT query you write directly against a connected BigQuery data provider. Useful when you need precise control over the data query.

• Provider ID: Which BigQuery provider to query
• Query: SQL SELECT statement (DDL/DML blocked, table allowlist enforced)
• Params: Named query parameters as key-value pairs
• Limit: Max rows to return (default 100, max 1000)

Example conversation:

User: Show me all active campaigns from last month.

AI: [Uses query_data tool] Here are the active campaigns from February 2026...

Ask Data

Tool name: ask_data

Ask questions about your data in plain English. The AI translates your question into SQL using the Vanna AI model, then executes it against your BigQuery data provider. Use this when you're not sure how to write the SQL yourself.

• Question: Natural language question about your data (e.g. "What was the fill rate last month?")
• Provider ID: Which BigQuery provider to query
• Limit: Max rows to return (default 100, max 1000)

Security: The generated SQL is automatically filtered to your organization's data. You can only see your own data regardless of how the question is phrased.

Cost: Each question runs a BigQuery query. Query costs are tracked and attributed to your organization.

Example conversation:

User: Which agencies had the highest fill rate last quarter?

AI: [Uses ask_data tool] Based on your data, here are the top agencies by fill rate in Q4 2025...

Limitations:

• Works best with questions about data that matches your training examples. Add training data via the /train API endpoint to improve accuracy.
• Complex multi-step analysis may require query_data with explicit SQL instead.
• Only SELECT queries are executed, the AI cannot modify your data.

Limits

Agent tools have built-in limits to control costs and prevent abuse:

Limit	Default	Description
Max tool calls per message	3 (widget) / 5 (organization)	Maximum number of tool calls in a single response

These limits can be configured at the widget level and overridden at the organization level.

How the Agent Decides

When a user sends a message, the AI evaluates whether any tools would help answer the question:

1. If Agent Mode is off or no tools are configured, the widget uses plain chat
2. If Agent Mode is on, the AI receives tool descriptions and decides autonomously
3. The AI can call multiple tools in sequence (up to the limit)
4. After all tool calls complete, the AI synthesizes the results into a final response

The system prompt influences which tools the AI prefers. For example, if your prompt says "Always search for current data before answering," the AI will use web search more frequently.