Autonomous Data Analysis Agent

A serverless LLM agent that receives data-analysis questions through Telegram, uses web grounding and code execution when needed, and returns structured JSON responses. The system runs on Cloudflare Workers and keeps lightweight conversational state and execution logs in Cloudflare KV.

Architecture

Telegram user
    |
    v
Cloudflare Worker webhook
    |
    +-- short per-chat history (Cloudflare KV)
    +-- Gemini model orchestration
    |     +-- Google Search grounding
    |     +-- URL context / retrieval
    |     +-- code execution
    |
    +-- structured response shaping
    +-- JSONL run logging (Cloudflare KV)
    |
    v
Telegram response

What this project demonstrates

• LLM-agent orchestration with tool use
• Search-grounded and URL-grounded analysis
• Programmatic calculation through code execution
• Multi-turn conversational state with TTL-based KV storage
• Structured JSON output contracts
• Serverless webhook deployment on Cloudflare Workers
• Secret management with Wrangler secrets
• Execution logging and reproducible run traces
• Fallback model/tool configurations for resilience

Response modes

The agent can adapt its response envelope through ANSWER_MODE:

Mode	Behaviour
auto	Match the response shape requested by the incoming message
wrap	Return { "answer": ..., "log_url": ... }
raw	Return the core JSON payload only

The model emits a core payload which the Worker validates and shapes before sending the Telegram response.

Project structure

src/                 Worker and agent runtime
scripts/             Local solving and webhook utilities
evals/               Example evaluation prompts
wrangler.toml         Cloudflare Worker configuration
package.json          Scripts and dependencies

Setup

npm install
npx wrangler login
npx wrangler kv namespace create KV

Add the returned KV namespace ID to wrangler.toml, then configure secrets:

npx wrangler secret put TELEGRAM_TOKEN
npx wrangler secret put GEMINI_API_KEY
npx wrangler secret put WEBHOOK_SECRET

Deploy:

npm run deploy

Then configure the Telegram webhook using the included setup script.

Testing and CI

The agent logic can be exercised without Telegram:

GEMINI_API_KEY=... node scripts/local-solve.mjs \
  'Analyze this question and return the requested JSON response.'

Run the pure-function test suite with:

npm test

GitHub Actions runs the test suite on pushes to main and on pull requests.

Security

Secrets are intentionally excluded from source control. Use Cloudflare Wrangler secrets for model keys, Telegram credentials, and webhook secrets. Local .env and .dev.vars files are ignored by Git.

Engineering notes

The design intentionally separates the model's core answer from transport-specific response formatting. This makes the agent reusable across structured-response tasks while preserving deterministic output handling at the Worker layer.