From 8d297670905a0d52ef75859fc1d25eb537fdab5c Mon Sep 17 00:00:00 2001 From: "Kona (Koshi Nakamura)" Date: Mon, 13 Apr 2026 19:00:16 +0900 Subject: [PATCH 1/3] Fix ROI reporting docs: correct table names, file structure, and commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix table name inconsistencies: revenue → revenue_table, event_master → events_master - Update project structure in top-level README to match actual file layout - Replace obsolete file references (system_prompt.md, tools.yml, forms/) with current structure (Dashboard Viz/, knowledge_bases/, form_interfaces/) - Fix tdx agent push flag: -y → -f (correct flag) - Update workflow README: td workflow push → tdx wf push, add tdx.json step - Clarify revenue_table setup: sample data is for testing only, production requires user-provided actual conversion/revenue data - Allow independent setup of agent and workflow components - Remove internal references (PS team, development status) - Fix event_master → events_master in Japanese KB specs (OverallSummary, CampaignDetails) Co-Authored-By: Claude Opus 4.6 (1M context) --- engage-box/roi_reporting/README.md | 70 +++++++++++-------- engage-box/roi_reporting/agent/README.md | 4 +- engage-box/roi_reporting/agent/README_JA.md | 4 +- .../CampaignDetails_Spec_ja.md | 2 +- .../knowledge_bases/OverallSummary_Spec_ja.md | 6 +- .../workflows/reporting_agent/README.md | 17 +++-- 6 files changed, 62 insertions(+), 41 deletions(-) diff --git a/engage-box/roi_reporting/README.md b/engage-box/roi_reporting/README.md index a779213d..07316338 100644 --- a/engage-box/roi_reporting/README.md +++ b/engage-box/roi_reporting/README.md @@ -75,8 +75,8 @@ cd workflows/reporting_agent/ │ Treasure Data Tables │ │ ├─ daily_summary │ │ ├─ email_events │ - │ ├─ revenue │ - │ └─ event_master │ + │ ├─ revenue_table │ + │ └─ events_master │ └─────────────────────────────────────────┘ ``` @@ -91,23 +91,21 @@ cd workflows/reporting_agent/ ### Setup Steps -1. **Set up Data Preparation Workflows** - ```bash - cd workflows/reporting_agent/ - # Follow instructions in workflows/reporting_agent/README.md - # This creates the required tables (daily_summary, email_events, revenue, event_master) - ``` +The two components can be set up independently. You can start with either one: -2. **Deploy AI Reporting Agent** - ```bash - cd agent/ - # Follow instructions in agent/README.md - # This sets up the agent in AI Agent Foundry - ``` +**Option A: Set up the Agent first** (if the database and tables already exist) +```bash +cd agent/ +# Follow instructions in agent/README.md +``` + +**Option B: Set up the Workflow first** (to create tables from scratch) +```bash +cd workflows/reporting_agent/ +# Follow instructions in workflows/reporting_agent/README.md +``` -3. **Generate Reports** - - Use the agent via AI Agent Foundry UI - - Or integrate via Form Interfaces (when API available) +> **Note**: The agent requires the `engage_roi_reporting` database with populated tables to function. If the tables already exist (e.g., created by another team), you can deploy the agent without running the workflow. ## Required Tables @@ -117,8 +115,8 @@ The solution requires the following tables to be created by the workflow: |---|---|---| | `daily_summary` | Daily aggregated performance metrics | Workflow | | `email_events` | Email event logs (deduplicated) | Workflow | -| `revenue` | Revenue attribution data | Workflow | -| `event_master` | Campaign/journey metadata | Workflow | +| `revenue_table` | Revenue attribution data | Workflow (sample) or user-provided | +| `events_master` | Campaign/journey metadata | Workflow | ## Use Cases @@ -144,7 +142,6 @@ Deep-dive into specific campaign or journey performance: |---|---| | Agent reports "schema mismatch" | Verify workflow has run successfully and all required tables exist | | No data in reports | Check workflow execution logs, verify date ranges | -| Form Interfaces not available | API support for Form Interfaces is in development | ### Support Resources @@ -160,23 +157,40 @@ Deep-dive into specific campaign or journey performance: roi_reporting/ ├── README.md # This file ├── agent/ # AI Reporting Agent +│ ├── tdx.json # Project reference │ ├── README.md │ ├── README_JA.md -│ ├── system_prompt.md -│ ├── system_prompt_JA.md -│ ├── knowledge_base_overall_summary.md -│ ├── knowledge_base_campaign_details.md -│ ├── tools.yml -│ └── forms/ -│ ├── td_managed_overall_summary.yml -│ └── td_managed_campaign_details.yml +│ ├── Dashboard Viz/ +│ │ ├── agent.yml # Agent config (tools/outputs) +│ │ ├── prompt.md # System prompt (English) +│ │ └── prompt_ja.md # System prompt (Japanese, reference) +│ ├── knowledge_bases/ +│ │ ├── engage_roi_reporting.yml +│ │ ├── OverallSummary_Spec.md +│ │ ├── OverallSummary_Spec_ja.md +│ │ ├── CampaignDetails_Spec.md +│ │ └── CampaignDetails_Spec_ja.md +│ └── form_interfaces/ +│ ├── Overall Summary.yml +│ └── Campaign Details.yml └── workflows/ # Data Preparation Workflows └── reporting_agent/ + ├── tdx.json # Workflow project reference ├── README.md ├── config.yaml ├── report_preparation.dig + ├── revenue_generation.dig ├── queries/ + │ ├── daily_summary.sql + │ ├── deduplicate_email_events.sql + │ ├── email_events.sql + │ └── merge_summary_data.sql └── scripts/ + └── reporting_agent/ + ├── __init__.py + ├── events_master.py + ├── generate_revenue_data.py + └── setup_test_tables.py ``` ## License diff --git a/engage-box/roi_reporting/agent/README.md b/engage-box/roi_reporting/agent/README.md index ce3c31ae..bf13b973 100644 --- a/engage-box/roi_reporting/agent/README.md +++ b/engage-box/roi_reporting/agent/README.md @@ -52,7 +52,7 @@ cd treasure-boxes/engage-box/roi_reporting/agent # 2. Create project and push agent tdx llm project create "ROI Reporting Agent" -tdx agent push . -y +tdx agent push . -f ``` **That's it!** All components are created: @@ -78,7 +78,7 @@ cd agents/ROI\ Reporting\ Agent echo '{"llm_project": "My New Project"}' > tdx.json # 4. Push to new project -tdx agent push . -y +tdx agent push . -f ``` ### Verify Setup diff --git a/engage-box/roi_reporting/agent/README_JA.md b/engage-box/roi_reporting/agent/README_JA.md index 33e189d5..cdde0aa0 100644 --- a/engage-box/roi_reporting/agent/README_JA.md +++ b/engage-box/roi_reporting/agent/README_JA.md @@ -52,7 +52,7 @@ cd treasure-boxes/engage-box/roi_reporting/agent # 2. プロジェクトを作成してエージェントをプッシュ tdx llm project create "ROI Reporting Agent" -tdx agent push . -y +tdx agent push . -f ``` **これだけです！** すべてのコンポーネントが作成されます: @@ -78,7 +78,7 @@ cd agents/ROI\ Reporting\ Agent echo '{"llm_project": "My New Project"}' > tdx.json # 4. 新しいプロジェクトにプッシュ -tdx agent push . -y +tdx agent push . -f ``` ### セットアップの確認 diff --git a/engage-box/roi_reporting/agent/knowledge_bases/CampaignDetails_Spec_ja.md b/engage-box/roi_reporting/agent/knowledge_bases/CampaignDetails_Spec_ja.md index 3eef44b2..18526b5c 100644 --- a/engage-box/roi_reporting/agent/knowledge_bases/CampaignDetails_Spec_ja.md +++ b/engage-box/roi_reporting/agent/knowledge_bases/CampaignDetails_Spec_ja.md @@ -108,7 +108,7 @@ SQLエージェントは、指定されたcampaign_idまたはjourney_idの利 - クエリ構築: 1. email_eventsテーブルから直接email_titleでGROUP BY 2. campaign_idまたはjourney_idでフィルタ - 3. event_masterテーブルとのJOINは不要 + 3. events_masterテーブルとのJOINは不要 - SQLエージェントはLIMIT 51でクエリする必要があります。 - 51行が返された場合、VIZエージェントは注記を表示する必要があります: '上位50件のみ表示しています。追加の件名が表示されていない可能性があります。' - 最初の50行のみを表示します。 diff --git a/engage-box/roi_reporting/agent/knowledge_bases/OverallSummary_Spec_ja.md b/engage-box/roi_reporting/agent/knowledge_bases/OverallSummary_Spec_ja.md index 4ba39717..e6872a56 100644 --- a/engage-box/roi_reporting/agent/knowledge_bases/OverallSummary_Spec_ja.md +++ b/engage-box/roi_reporting/agent/knowledge_bases/OverallSummary_Spec_ja.md @@ -6,7 +6,7 @@ - purpose: "指定された期間における主要パフォーマンス指標（KPI）、トレンド、上位キャンペーン/ジャーニーを可視化する。" - source_tables: - "daily_summary" - - "event_master" # ランキングでの名前検索に使用 + - "events_master" # ランキングでの名前検索に使用 ## 2. フィルタ - filter: @@ -46,7 +46,7 @@ - component_id: "campaign_performance_ranking" - component_type: "table" - title: "Top 5 Campaigns" - - source_tables: ["daily_summary", "event_master"] + - source_tables: ["daily_summary", "events_master"] - dimensions: - { id: "campaign_name", display_name: "Campaign Name" } - { id: "campaign_id", display_name: "Campaign ID" } @@ -68,7 +68,7 @@ - component_id: "journey_performance_ranking" - component_type: "table" - title: "Top 5 Journeys" - - source_tables: ["daily_summary", "event_master"] + - source_tables: ["daily_summary", "events_master"] - dimensions: - { id: "journey_name", display_name: "Journey Name" } - { id: "journey_id", display_name: "Journey ID" } diff --git a/engage-box/roi_reporting/workflows/reporting_agent/README.md b/engage-box/roi_reporting/workflows/reporting_agent/README.md index 750a0ee0..6c83a87b 100644 --- a/engage-box/roi_reporting/workflows/reporting_agent/README.md +++ b/engage-box/roi_reporting/workflows/reporting_agent/README.md @@ -54,8 +54,6 @@ The `config.yaml` file allows you to configure: 1. Create Database named `engage_roi_reporting` -1. Prepare Revenue data table named `revenue_table` under `engage_roi_reporting` database - 1. Edit the `config.yaml` file to match your environment after you download this example 1. Set email_domains When you send emails using Engage Studio, a database with a name beginning with "delivery_email_" is generated. Please list that database name under `email_domains` instead of the existing database name, `delivery_email_example_com`. @@ -63,11 +61,21 @@ The `config.yaml` file allows you to configure: 1. Set endpoint Please set the endpoints that matches the Treasure Data region you are using. In this example, the US region endpoints are set. If you are using the Tokyo region, please comment out the US region endpoints and use the commented out endpoints. + 1. Set revenue generation settings + The workflow can generate sample revenue data for testing by setting `revenue_generation.generate_sample: true` in config.yaml. This creates realistic dummy data for verifying report output. **Note**: Sample data is for testing only. For production use, you must prepare your own `revenue_table` with actual conversion and revenue data from your systems, and set `generate_sample: false`. + + 1. Create `tdx.json` in the workflow directory (if it doesn't exist): + ```json + { + "workflow_project": "reporting_agent" + } + ``` + 1. Upload your project - Upload the project using `td workflow push` command in the same directory as `report_preparation.dig`. + Upload the project using `tdx wf push` command in the same directory as `report_preparation.dig`. 1. Register Master Key(API Key) to Secret - Please register Master Key to the secret of uploaded project. The name of the Secret is `td.apikey`. + Register Master Key to the secret of the uploaded project using `tdx wf secrets set reporting_agent "td.apikey=ACCOUNT_ID/YOUR_MASTER_API_KEY"`. The name of the Secret is `td.apikey`. ### Scheduled Execution @@ -236,7 +244,6 @@ scripts/reporting_agent/generate_revenue_data.py ## Important Notes -- This workflow is designed to be run by the PS team - The workflow should be implemented as a user-defined workflow - Handle API keys with appropriate security measures From be6f3bfda156cb987c5c0d8d7ca17903a9fe0f5c Mon Sep 17 00:00:00 2001 From: "Kona (Koshi Nakamura)" Date: Mon, 13 Apr 2026 20:59:31 +0900 Subject: [PATCH 2/3] Fix Copilot review comments on README.md - Clarify tdx.json is user-created and not committed to repo - Fix contradictory table section heading to not imply all tables are workflow-created Co-Authored-By: Claude Opus 4.6 (1M context) --- engage-box/roi_reporting/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/engage-box/roi_reporting/README.md b/engage-box/roi_reporting/README.md index 07316338..1a4d9cd9 100644 --- a/engage-box/roi_reporting/README.md +++ b/engage-box/roi_reporting/README.md @@ -109,7 +109,7 @@ cd workflows/reporting_agent/ ## Required Tables -The solution requires the following tables to be created by the workflow: +The solution requires the following tables in the `engage_roi_reporting` database: | Table | Description | Created By | |---|---|---| @@ -157,7 +157,7 @@ Deep-dive into specific campaign or journey performance: roi_reporting/ ├── README.md # This file ├── agent/ # AI Reporting Agent -│ ├── tdx.json # Project reference +│ ├── tdx.json # User-created local project file (not committed) │ ├── README.md │ ├── README_JA.md │ ├── Dashboard Viz/ @@ -175,7 +175,7 @@ roi_reporting/ │ └── Campaign Details.yml └── workflows/ # Data Preparation Workflows └── reporting_agent/ - ├── tdx.json # Workflow project reference + ├── tdx.json # User-created local project file (not committed) ├── README.md ├── config.yaml ├── report_preparation.dig From 8c04eeafdcb8b92711649d1aac58e5300f6d93c8 Mon Sep 17 00:00:00 2001 From: "Kona (Koshi Nakamura)" Date: Mon, 13 Apr 2026 21:01:59 +0900 Subject: [PATCH 3/3] Clarify tdx.json is auto-generated by CLI, not manually created Co-Authored-By: Claude Opus 4.6 (1M context) --- engage-box/roi_reporting/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/engage-box/roi_reporting/README.md b/engage-box/roi_reporting/README.md index 1a4d9cd9..e0341572 100644 --- a/engage-box/roi_reporting/README.md +++ b/engage-box/roi_reporting/README.md @@ -157,7 +157,7 @@ Deep-dive into specific campaign or journey performance: roi_reporting/ ├── README.md # This file ├── agent/ # AI Reporting Agent -│ ├── tdx.json # User-created local project file (not committed) +│ ├── tdx.json # Auto-generated by tdx CLI (not committed) │ ├── README.md │ ├── README_JA.md │ ├── Dashboard Viz/ @@ -175,7 +175,7 @@ roi_reporting/ │ └── Campaign Details.yml └── workflows/ # Data Preparation Workflows └── reporting_agent/ - ├── tdx.json # User-created local project file (not committed) + ├── tdx.json # Auto-generated by tdx CLI (not committed) ├── README.md ├── config.yaml ├── report_preparation.dig