Agent Quickstart
Agents in Dataworkz act as orchestrators of data and AI—allowing you to connect and retrieve insights from a wide variety of sources such as RAG applications, SQL databases, JDBC, MongoDB, GraphQL, and REST APIs. Each data source or interaction is enabled via "tools" the agent uses, powered by LLMs.
This quickstart sample demonstrates power of Dataworkz Agents
1. Overview
This document walks through a concrete implementation of Business Insight Analyzer agent that uses Data Insight Summarizer tool for Sales, Marketing, and Customer Support scenarios.
It uses LLM Tool that integrates Large Language Models (LLMs) into Dataworkz Agents, enabling them to analyze business data and automatically generates human‑readable insights and recommendations. By defining a System Prompt (tool persona and rules) and a User Prompt (task template), the tool can be reused across multiple agent scenarios.
2. What we built (summary)
LLM Tool: Data_Insight_Summarizer — generic summarizer for structured / semi‑structured business metrics (sales, marketing, support, operations).
Agent: Business Insight Analyzer — Agent that exposes multiple scenarios that call the LLM tool (Sales Performance Analysis, Marketing Campaign Insights, Customer Service KPI Analysis).
Goal: Demonstrate how a single LLM Tool can be reused across different intents by wiring it into scenario workflows in the Agent UI.
3. Prerequisites
An LLM configured in Dataworkz LLM Configurator (e.g., gpt_4o or equivalent model in the platform).
4. LLM Tool Configuration
4.1 Create tool (UI flow)
From the Dataworkz dashboard, open Agents -> Create Tool and choose the LLM tool type.
Enter Tool name: Data_Insight_Summarizer.
Enter Description:
Analyzes structured or semi-structured business data (sales, marketing, support, operations) and generates human-readable insights with actionable recommendations.
Select an LLM from the LLM selection dropdown (e.g., gpt_4o).
4.2 Configuration — Prompts
System prompt (tool persona/rules)
You are a professional business data analyst.
Your role is to carefully read dataset summaries (including KPIs, metrics, and performance indicators) and generate clear, concise, and actionable business insights.
Always provide:
Three key insights highlighting trends, patterns, or anomalies.
One practical business recommendation based on the insights.
Write in simple business language that non-technical users can understand.
User prompt (task template, with parameter)
Based on the following dataset summary, provide three key insights and one recommendation:
${data_summary}
Json_format_output:
{
"insights": [
"Insight 1",
"Insight 2",
"Insight 3"
],
"recommendation": "Actionable recommendation"
}
4.3 Input parameters and Output
Input parameter: data_summary (type = String) — contains a short structured summary such as: Q3 2025 Sales Metrics: Total Revenue = $1.2M (-15% QoQ), Repeat Customers = 43% (+8%), Average Order Value = $62 (+2%), Website Traffic = 210K (-10%).
Output format: The tool is configured to return a JSON object like:
{
"insights": ["...", "...", "..."],
"recommendation": "..."
}
This output makes downstream scenario handling and UI rendering deterministic.
4.4 Test/validate tool
Use the Test tool panel (right side of the Create Tool UI) to paste sample data_summary inputs and validate if the tool returns the expected JSON structure.
If outputs are inconsistent, refine the system prompt to be more prescriptive (e.g., require numbered insights and JSON structures).
5. Agent
5.1 Create agent (UI flow)
From Agents -> Create Agent.
Describe "What would you like the agent to do" :
Analyzes structured or semi-structured business data including sales, marketing, support, and operations to generate insights and recommendations.
Click "Create"
You can optionally change the default agent name.
Edit the short description of agent if needed.
5.2 Define Persona
In the Agent persona set the voice and scope. Example persona used:
You are a specialized AI assistant focused on providing business insights and actionable recommendations.
Keep answers concise and structured: provide headings (Insights, Analysis, Recommendations) and present 3 insights + 1 recommendation.
5.3 Add Scenarios and map to the LLM Tool
We created 3 primary scenarios, each wired to the same Data_Insight_Summarizer tool:
Scenario A: BusinessDataAnalysis (Sales Performance Analysis)
Description: Sales Performance Analysis.
Planning instructions: When user provides a quarterly/monthly sales summary (revenue, traffic, AOV, repeat customers), call the Data_Insight_Summarizer tool with this data. Present results as insights + recommendation.
Output format: Add a relevant heading to the response (Insights / Analysis / Recommendations) for readability in the agent chat.
Tool reference: Data_Insight_Summarizer (pass data_summary param)
Scenario B: Marketing Campaign Insights
Description: Interprets campaign metrics (CTR, CPC, conversions, spend) into ROI-driven insights.
Instruction: Route campaign metric inputs to Data_Insight_Summarizer; display insights and allocate a short suggestion for next steps.
Scenario C: Customer Service KPI Analysis
Description: Analyze support KPIs (tickets, response time, CSAT, escalations) and provide operational recommendations.
Instructions: Use the tool and present the results using headings and short bullet points.
5.4 Variables & Failure Messages
Define agent-level variables if needed (e.g., defaultCurrency = USD). In this demo, all inputs are passed directly via scenario text.
Set failure messages for no scenario match or missing inputs. Example:
No scenario match: "I’m not sure I can help with that — try providing a sales, campaign, or support summary."
Missing input: "Please paste the summary (KPIs) so I can analyze it."
5.5 Run Mode and Example Outputs
Test the agent by opening Run and entering one of the sample inputs (see Section 6).
The agent will select a scenario, call the Data_Insight_Summarizer tool, and render the returned insights and recommendation.
The Agent can now be published to complete the creation of the same.
6. Best practices & tuning
Be explicit in the System Prompt: force a specific output format (JSON) to ensure stability.
Keep User Prompt concise: include the parameter name and the expected JSON schema so the model returns a consistent structure.
Test with edge cases: missing deltas, single metric inputs, and contradictory metrics (e.g., traffic up but revenue down).
Show friendly headings in the Agent: add small post‑processing on the agent response to render headings (Insights / Recommendations) for readability.
Limit prompt length: if you are feeding long datasets, consider summarizing numerics before sending to the LLM.
7. Common Pitfalls to Avoid
Overly broad scenarios → split into smaller, focused ones.
Vague persona instructions → keep concise and specific.
Missing input validation → enforce correct data types.
Hardcoded secrets → always use secure storage.
Last updated