An intelligent command-line agent powered by the Gemini API that analyzes marketing campaign performance, runs analytics calculations, and answers complex follow-up questions dynamically.
Marketers deal with massive amounts of raw campaign metrics scattered across multiple platforms. Translating columns of raw numbers—spend, impressions, clicks, conversions, and revenue—into meaningful and actionable insights is time-consuming. Traditional analysis often requires static dashboards or rigid scripts that cannot adapt to custom inquiries or provide instant recommendations.
This agent ingest campaign data from a CSV file and automates the analytical heavy lifting:
- Calculates core business performance metrics like Click-Through Rate (CTR), Conversion Rate, Customer Acquisition Cost (CAC), and Return on Ad Spend (ROAS).
- Automatically flags underperforming marketing channels based on customizable ROAS thresholds.
- Generates a natural, plain-English summary report summarizing the best and worst performing channels with actionable recommendations.
- Engages in an interactive CLI session where users can ask arbitrary follow-up questions (e.g., "Which channel had the highest number of conversions?" or "What would happen if we cut the TikTok budget by half?").
A static dashboard displays charts but cannot answer novel, unstructured follow-up questions. A simple script can calculate fixed ratios but requires code changes if the user wants to filter by a different criteria or ask for business advice.
By contrast, this application runs a Gemini function calling loop. The Gemini model acts as the brain: it reads the user's natural language question, reasons about what information is required to answer it, selects the appropriate tool to call (and parameterizes it), receives the raw metrics response from the local environment, and synthesizes a final natural language answer.
┌──────────────────┐
│ data/ │
│ campaigns.csv │
└────────┬─────────┘
│ (raw csv read)
▼
┌──────────────────┐
│ src/ │
│ analytics.js │ (calculates CTR, ROAS, CAC, etc. using pure functions)
└────────┬─────────┘
│ (aggregates data)
▼
┌──────────────────┐
│ src/ │
│ tools.js │ (bridges analytics functions with Gemini schemas)
└────────┬─────────┘
│ (declares tool metadata and executes requests)
▼
┌──────────────────┐
│ src/ │
│ agent.js │ (initializes Gemini Client & drives the loop)
└────────┬─────────┘
│ (requests tool execution / returns natural text responses)
▼
┌──────────────────┐
│ CLI Interface │
│ (Interactive) │ (displays initial report and prompts user query)
└──────────────────┘
- Agent/ADK (Gemini Function Calling): Implements native tool declarations and executes the request -> tool call -> tool result -> final answer loop to resolve queries dynamically.
- Agent Skills: Modularity via pure analytical capabilities mapped directly to tool interfaces, allowing the model to choose between summarizing overview data or isolating underperforming segments.
- Security:
- Prevents API key exposure using
.envenvironment variables and a robust.gitignorefile. - Ensures robust input validation (e.g., type coercion for thresholds) to prevent crashes on malformed inputs from the model.
- Prevents API key exposure using
- Clone the repository to your local machine.
- Navigate to the project root and run package installation:
npm install
- Get an API Key from Google AI Studio.
- Create a
.envfile in the project root containing your key:GEMINI_API_KEY=your_key_here
- Run the agent:
npm start
├── data/
│ └── campaigns.csv # 30 days of realistic marketing campaign mock data
├── src/
│ ├── agent.js # Main entry point (Gemini client & interactive CLI loop)
│ ├── analytics.js # Campaign metric calculations & CSV parser
│ └── tools.js # Gemini function declarations & tool executor
├── .env # Local environment variables (ignored by Git)
├── .env.example # Placeholder environment template for reference
├── .gitignore # Excludes sensitive environment configurations & node modules
├── package.json # Node project configuration and script commands
└── README.md # Project documentation
====================================================
Starting Marketing Analytics Agent...
====================================================
[Agent] Generating startup marketing performance report...
[Agent] Tool call requested: get_campaign_metrics with args: {}
[Agent] Tool execution successful.
[Agent] Tool call requested: find_underperforming_channels with args: {}
[Agent] Tool execution successful.
--- STARTUP MARKETING PERFORMANCE REPORT ---
Our recent campaign analysis reveals Email as the top-performing channel with an impressive ROAS of 2.82, while TikTok significantly underperforms with a ROAS of 0.51. For TikTok, both its Click-Through Rate (1%) and Conversion Rate (0%) are extremely low, indicating a fundamental issue. This suggests that the problem lies with either weak ad appeal failing to capture user interest or poor targeting reaching an irrelevant audience. To address this, we recommend a comprehensive review and overhaul of TikTok's ad creatives and audience targeting to ensure they resonate with potential customers and drive engagement.
--------------------------------------------
Ask a question (or type 'exit'): Which channel had the highest number of conversions?
[Agent] Sending query to Gemini...
[Agent] Tool call requested: get_campaign_metrics with args: {}
[Agent] Tool execution successful.
[Gemini]: Email had the highest number of conversions with 266.
Ask a question (or type 'exit'): exit
Goodbye!