Add ROI Reporting Agent in tdx CLI format by ko47kmr · Pull Request #433 · treasure-data/treasure-boxes

ko47kmr · 2026-04-13T00:00:18Z

Summary

Add ROI Reporting Agent that works directly with tdx agent push, eliminating the need for LLM API and Python scripts.

Changes

New Files (tdx CLI format)

Dashboard Viz/agent.yml - Agent configuration with embedded tools/outputs
Dashboard Viz/prompt.md - System prompt (English)
Dashboard Viz/prompt_ja.md - System prompt (Japanese, reference)
knowledge_bases/OverallSummary_Spec.md - Overall Summary KB (English)
knowledge_bases/OverallSummary_Spec_ja.md - Overall Summary KB (Japanese, reference)
knowledge_bases/CampaignDetails_Spec.md - Campaign Details KB (English)
knowledge_bases/CampaignDetails_Spec_ja.md - Campaign Details KB (Japanese, reference)
knowledge_bases/engage_roi_reporting.yml - Database KB definition
form_interfaces/Overall Summary.yml - Form interface (YAML object format)
form_interfaces/Campaign Details.yml - Form interface (YAML object format)
tdx.json - Project reference
README.md - Simplified setup documentation (English)
README_JA.md - Simplified setup documentation (Japanese)

Removed Files (old treasure-boxes format)

agent.yml (replaced by Dashboard Viz/agent.yml)
system_prompt.md (replaced by Dashboard Viz/prompt.md)
system_prompt_JA.md (replaced by Dashboard Viz/prompt_ja.md)
tools.yml (merged into Dashboard Viz/agent.yml)
knowledge_base_overall_summary.md (replaced by knowledge_bases/OverallSummary_Spec.md)
knowledge_base_overall_summary_JA.md (replaced by knowledge_bases/OverallSummary_Spec_ja.md)
knowledge_base_campaign_details.md (replaced by knowledge_bases/CampaignDetails_Spec.md)
knowledge_base_campaign_details_JA.md (replaced by knowledge_bases/CampaignDetails_Spec_ja.md)
form_interfaces/td_managed_overall_summary.yml (replaced by form_interfaces/Overall Summary.yml)
form_interfaces/td_managed_campaign_details.yml (replaced by form_interfaces/Campaign Details.yml)

Benefits

✅ 2-command setup (vs 10+ steps before):

tdx llm project create "ROI Reporting Agent"
tdx agent push . -y

✅ No Python/PyYAML dependencies
✅ No LLM API knowledge required
✅ Compatible with tdx CLI 2026.4.55+ (PR treasure-data/tdx#2139)
✅ Creates all components: Agent, Knowledge Bases, Tools, Outputs, Form Interfaces
✅ Japanese files included for reference

Verification

Tested on ko47kmr/treasure-boxes:

✅ All components created successfully via tdx agent push
✅ Agent: 1 created
✅ Knowledge Bases: 3 created (1 Database KB + 2 Text KBs)
✅ Tools: 4 configured
✅ Outputs: 3 configured
✅ Form Interfaces: 2 created

Verification details:

Branch: ko47kmr:update-roi-agent-to-tdx-format
Tested with tdx CLI 2026.4.55
Confirmed all components work correctly

Breaking Changes

Yes - This is a format change from treasure-boxes format to tdx CLI format.

Migration Path

Users with existing setups:

Continue using existing agents (no impact)
New agents: Use the simplified 2-command setup

Users wanting to update:

Clone repository
Run tdx agent push to create new agent
Delete old agent if desired

Note on Japanese Files

Japanese files (*_ja.md) are included for reference. The tdx agent push command uses English files by default. To use Japanese versions:

Manually replace English files with Japanese versions before pushing, or
Use files as reference for creating Japanese variants

- Enables direct setup with 'tdx agent push' (no LLM API needed) - Includes all components: Agent, Knowledge Bases, Tools, Outputs, Forms - Simplified README with 2-command setup - Compatible with tdx CLI 2026.4.55+ (PR treasure-data/tdx#2139) File structure: - Dashboard Viz/agent.yml: Agent config with embedded tools/outputs - Dashboard Viz/prompt.md: System prompt - knowledge_bases/: 2 Text KBs + 1 Database KB - form_interfaces/: 2 forms (YAML object format) - tdx.json: Project reference Setup: tdx llm project create "ROI Reporting Agent" tdx agent push . -y

- Add prompt_ja.md (Japanese system prompt) - Add README_JA.md (Japanese README with tdx CLI setup instructions) - Add OverallSummary_Spec_ja.md (Japanese knowledge base) - Add CampaignDetails_Spec_ja.md (Japanese knowledge base) - Update README.md to reference Japanese files - Note: Japanese files included for reference; tdx agent push uses English files

Copilot

Pull request overview

This PR migrates the ROI Reporting Agent to the tdx agent push (tdx CLI) project format, adding agent configuration, knowledge bases, and form interfaces so the agent can be deployed without external Python/LLM API setup.

Changes:

Adds a new Dashboard Viz agent definition with embedded tools/outputs and bilingual prompts.
Adds report specification knowledge bases (Overall Summary + Campaign Details) and a database KB definition.
Adds YAML object-format form interfaces plus simplified English/Japanese READMEs and tdx.json project reference.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
engage-box/roi_reporting/agent/tdx.json	tdx CLI project reference for `tdx agent push`
engage-box/roi_reporting/agent/README.md	English setup/usage docs for the new tdx CLI format
engage-box/roi_reporting/agent/README_JA.md	Japanese setup/usage docs for the new tdx CLI format
engage-box/roi_reporting/agent/knowledge_bases/OverallSummary_Spec.md	Overall Summary report spec KB (English)
engage-box/roi_reporting/agent/knowledge_bases/OverallSummary_Spec_ja.md	Overall Summary report spec KB (Japanese reference)
engage-box/roi_reporting/agent/knowledge_bases/CampaignDetails_Spec.md	Campaign Details report spec KB (English)
engage-box/roi_reporting/agent/knowledge_bases/CampaignDetails_Spec_ja.md	Campaign Details report spec KB (Japanese reference)
engage-box/roi_reporting/agent/knowledge_bases/engage_roi_reporting.yml	Database knowledge base definition
engage-box/roi_reporting/agent/form_interfaces/Overall Summary.yml	Form interface for Overall Summary report
engage-box/roi_reporting/agent/form_interfaces/Campaign Details.yml	Form interface for Campaign Details report
engage-box/roi_reporting/agent/Dashboard Viz/prompt.md	System prompt guiding SQL + dashboard generation (English)
engage-box/roi_reporting/agent/Dashboard Viz/prompt_ja.md	System prompt guiding SQL + dashboard generation (Japanese reference)
engage-box/roi_reporting/agent/Dashboard Viz/agent.yml	Agent config: model, outputs, and KB-backed tools

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-13T00:05:28Z

+- notes: "Timestamp columns (event_timestamp, conversion_timestamp) are varchar strings. They MUST be parsed using date_parse(column, '%Y-%m-%d %H:%i:%s.%f')."
+
+## 3. Important Notes on Metrics
+
+### Unique Count vs Total Count
+- **Unique counts** (primary metrics): Use `COUNT(DISTINCT message_id)` to count each message only once, regardless of how many times it was opened/clicked.
+- **Total counts** (supplementary information): Use `COUNT(*)` to count all events, including multiple opens/clicks of the same message.
+- **Rate calculations**: All rates MUST use unique counts to avoid inflated metrics (industry standard).
+
+### Identifier Standard
+- Use `message_id` (Amazon SES unique message ID) for DISTINCT aggregations.
+- This ensures consistency with Email Delivery Reports and industry best practices.
+
+### Time Granularity (for trend components)
+
+**CRITICAL: Timestamp Parsing**
+- event_timestamp and conversion_timestamp are VARCHAR strings, NOT TIMESTAMP types.
+- You MUST use `date_parse(column, '%Y-%m-%d %H:%i:%s.%f')` to parse these columns.
+- DO NOT use `CAST(column AS DATE)` or `CAST(column AS TIMESTAMP)` - these will fail.


The timestamp parsing guidance appears incorrect for the existing ROI workflow tables: event_timestamp is ISO8601 (the workflow uses from_iso8601_timestamp(event_timestamp)), while conversion_timestamp is stored as YYYY-MM-DD HH:MM:SS and can be CAST(... AS TIMESTAMP). The current date_parse(..., '%Y-%m-%d %H:%i:%s.%f') instruction will fail for both formats. Update the parsing rules to match the actual table formats.

@copilot apply changes based on https://github.com/treasure-data/treasure-boxes/tree/master/engage-box/roi_reporting/workflows/reporting_agent にあるワークフローを「正」としてこのワークフローによって作成されるテーブルのみを使ってエージェントが挙動するように修正してください。このドキュメントのこの箇所以外でもそれに即していないところがあったらコメントください。

Copilot · 2026-04-13T00:05:30Z

+エージェントは`engage_roi_reporting`データベースに以下のテーブルを必要とします:
+
+| テーブル | 説明 | 主要カラム |
+|---|---|---|
+| `daily_summary` | 日次集計パフォーマンスメトリクス | `summary_date`, `campaign_id`, `journey_id`, `total_sends`, `total_deliveries`, `total_opens`, `total_clicks`, `total_conversions`, `total_revenue_direct`, `total_revenue_contributed` |
+| `events_master` | キャンペーン/ジャーニーメタデータ | `campaign_id`, `journey_id`, `campaign_name`, `journey_name` |
+| `email_events` | メールイベントログ | `event_timestamp`, `event_type`, `message_id`, `campaign_id`, `journey_id`, `email_title` |
+| `revenue_table` | 収益アトリビューションデータ | `conversion_timestamp`, `conversion_id`, `campaign_id`, `total_revenue`, `attribution_type` |
+


daily_summary key columns listed here omit columns that the agent specs rely on (e.g., total_hard_bounces, total_soft_bounces, total_unsubscribes, and also campaign_name/journey_name if present). Update the documented schema so Japanese readers don’t create an incompatible table definition.

@copilot apply changes based on this feedbackPlease apply changes based on this workflow:
https://github.com/treasure-data/treasure-boxes/tree/master/engage-box/roi_reporting/workflows/reporting_agent

Update the documentation to match only the tables created by this workflow.

…_Spec_ja.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…_Spec.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…Spec.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…Spec_ja.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

- Update table names to match workflow: - revenue → revenue_table - event_master → events_master - Update daily_summary columns to include: - campaign_name, journey_name - total_hard_bounces, total_soft_bounces, total_unsubscribes - Fix timestamp parsing instructions: - event_timestamp: Use from_iso8601_timestamp() (ISO8601 format) - conversion_timestamp: Use CAST AS TIMESTAMP - Fix tool name in prompts: - render_plotly_chart → new_plot - Fix documentation links: - Remove reference to non-existent LEGACY_SETUP.md - Update Japanese KB links to new filenames - Update both English and Japanese versions All changes aligned with workflow: https://github.com/treasure-data/treasure-boxes/tree/master/engage-box/roi_reporting/workflows/reporting_agent

Kona (Koshi Nakamura) added 2 commits April 10, 2026 16:14

ko47kmr requested a review from a team as a code owner April 13, 2026 00:00

Copilot AI review requested due to automatic review settings April 13, 2026 00:00

Copilot AI reviewed Apr 13, 2026

View reviewed changes

toru-takahashi approved these changes Apr 13, 2026

View reviewed changes

ko47kmr and others added 10 commits April 13, 2026 09:54

Merge branch 'master' into update-roi-agent-to-tdx-format

fdb833f

Update engage-box/roi_reporting/agent/knowledge_bases/CampaignDetails…

078b9d9

…_Spec_ja.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update engage-box/roi_reporting/agent/knowledge_bases/CampaignDetails…

074ecd4

…_Spec.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update engage-box/roi_reporting/agent/knowledge_bases/CampaignDetails…

3715165

…_Spec.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update engage-box/roi_reporting/agent/Dashboard Viz/prompt_ja.md

a5541b3

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update engage-box/roi_reporting/agent/knowledge_bases/OverallSummary_…

4085512

…Spec.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update engage-box/roi_reporting/agent/Dashboard Viz/prompt.md

9f7b662

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update engage-box/roi_reporting/agent/Dashboard Viz/agent.yml

6c2ee1c

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update engage-box/roi_reporting/agent/knowledge_bases/OverallSummary_…

b323b13

…Spec_ja.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

toru-takahashi merged commit 2dce6c4 into treasure-data:master Apr 13, 2026
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add ROI Reporting Agent in tdx CLI format#433

Add ROI Reporting Agent in tdx CLI format#433
toru-takahashi merged 12 commits into
treasure-data:masterfrom
ko47kmr:update-roi-agent-to-tdx-format

ko47kmr commented Apr 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

ko47kmr Apr 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

ko47kmr Apr 13, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

ko47kmr commented Apr 13, 2026

Summary

Changes

New Files (tdx CLI format)

Removed Files (old treasure-boxes format)

Benefits

Verification

Breaking Changes

Migration Path

Note on Japanese Files

Related

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

ko47kmr Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

ko47kmr Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants