Improve ROI Reporting Agent setup documentation and naming by ko47kmr · Pull Request #432 · treasure-data/treasure-boxes

ko47kmr · 2026-04-10T02:30:32Z

Summary

This PR improves the ROI Reporting Agent setup experience by addressing several documentation and naming issues discovered during actual setup testing.

Changes

1. Remove "TD-Managed: " prefix from agent and form interface names

agent.yml: "Dashboard Viz" (was "TD-Managed: Dashboard Viz")
Form interfaces: "Overall Summary" and "Campaign Details" (removed prefix)
Reason: "TD-Managed" is an internal prefix not needed for user-facing agents

2. Fix table names to match actual workflow output

event_master → events_master (plural)
revenue → revenue_table (with suffix)
Verification: Confirmed against workflow config.yaml

3. Add comprehensive LLM API setup instructions

Document that tdx agent push creates ONLY the agent resource itself
Provide Option A: LLM API Setup for complete automated setup including:
- ✅ Agent core attributes (name, model, system prompt)
- ✅ Knowledge Bases (Text KBs and Database KB)
- ✅ Tools and Outputs configuration
- ✅ Form Interfaces
Keep existing CLI and Manual UI options as alternatives
Reference /llm-api-setup skill for detailed implementation

4. Add data preparation prerequisite

Document that required workflow execution is needed before using agent
Reference treasure-boxes roi_reporting workflow
List all 4 required tables with correct names

Testing

These changes were validated through actual agent setup:

Created project: ROI_Agent_test_20260410
Successfully configured all components via LLM API
Verified agent functionality with correct table names
Confirmed all form interfaces working

Impact

These changes make the ROI Reporting Agent:

✅ Easier to set up (clear LLM API workflow)
✅ More accurate (correct table names)
✅ Better documented (prerequisites and limitations)
✅ Cleaner naming (no internal prefixes)

Files Changed

engage-box/roi_reporting/agent/agent.yml
engage-box/roi_reporting/agent/form_interfaces/td_managed_overall_summary.yml
engage-box/roi_reporting/agent/form_interfaces/td_managed_campaign_details.yml
engage-box/roi_reporting/agent/README.md

This commit addresses several issues in the ROI Reporting Agent setup: 1. Remove "TD-Managed: " prefix from agent and form interface names - agent.yml: "Dashboard Viz" (was "TD-Managed: Dashboard Viz") - Form interfaces: "Overall Summary" and "Campaign Details" - Reason: "TD-Managed" is an internal prefix not needed for user-facing agents 2. Fix table names to match actual workflow output - event_master → events_master (plural) - revenue → revenue_table (with suffix) - Verified against workflow config.yaml 3. Add comprehensive LLM API setup instructions - Document that tdx agent push creates ONLY the agent resource - Provide LLM API workflow (Option A) for complete setup - Include all required components: Agent, KBs, Tools, Outputs, Forms - Reference /llm-api-setup skill for detailed implementation 4. Add data preparation prerequisite - Document required workflow execution before using agent - Reference treasure-boxes roi_reporting workflow These changes make the agent easier to set up and align documentation with actual implementation requirements. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Copilot

Pull request overview

Updates the ROI Reporting Agent configuration/docs to improve setup clarity and to standardize user-facing naming.

Changes:

Renames the agent and form interfaces to remove the “TD-Managed:” prefix.
Updates documented required table names (event_master→events_master, revenue→revenue_table).
Expands setup documentation to describe LLM API-based provisioning and clarifies tdx agent push limitations.

Reviewed changes

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

File	Description
engage-box/roi_reporting/agent/README.md	Adds data prep prerequisite, updates required table names, and documents LLM API setup flow.
engage-box/roi_reporting/agent/form_interfaces/td_managed_overall_summary.yml	Renames the Overall Summary form and updates agent reference to the new agent name.
engage-box/roi_reporting/agent/form_interfaces/td_managed_campaign_details.yml	Renames the Campaign Details form and updates agent reference to the new agent name.
engage-box/roi_reporting/agent/agent.yml	Renames the agent resource to remove the “TD-Managed:” prefix.

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

Copilot · 2026-04-10T02:33:45Z

 | `daily_summary` | Daily aggregated performance metrics | `summary_date`, `campaign_id`, `journey_id`, `total_sends`, `total_deliveries`, `total_opens`, `total_clicks`, `total_conversions`, `total_revenue_direct`, `total_revenue_contributed` |
-| `event_master` | Campaign/journey metadata | `campaign_id`, `journey_id`, `campaign_name`, `journey_name` |
+| `events_master` | Campaign/journey metadata | `campaign_id`, `journey_id`, `campaign_name`, `journey_name` |
 | `email_events` | Email event logs | `event_timestamp`, `event_type`, `message_id`, `campaign_id`, `journey_id`, `email_title` |
-| `revenue` | Revenue attribution data | `conversion_timestamp`, `conversion_id`, `campaign_id`, `total_revenue`, `attribution_type` |
+| `revenue_table` | Revenue attribution data | `conversion_timestamp`, `conversion_id`, `campaign_id`, `total_revenue`, `attribution_type` |


The Required Database Tables section was updated to events_master / revenue_table, but this README still references the old revenue naming elsewhere (e.g., the later schema subsection title 'revenue table:' and the manual setup note about databases containing “revenue tables”). Please update the remaining references in this README to consistently use revenue_table (and, if applicable, events_master) so users don’t set up the wrong schema.

Copilot · 2026-04-10T02:33:45Z

+- ✅ Form Interfaces
+
+Reference implementation: See the `/llm-api-setup` skill documentation for complete workflow and Python script templates.
+


The reference to “/llm-api-setup skill documentation” isn’t resolvable within this repository (no matching docs found), so readers won’t know where to go next. Please replace this with a concrete link/path that exists in-repo (or an explicit external URL), or add the referenced documentation to the repo.

Copilot · 2026-04-10T02:33:46Z

+**Step 2-6: Use LLM API**
+
+Use Python scripts to create the agent and all resources via LLM API. This ensures:
+- ✅ Agent core attributes (name, model, system prompt)


The “Step 2-6: Use LLM API” section doesn’t actually enumerate steps 2–6 or point to specific script filenames/commands to run, which makes the setup flow hard to follow. Please either list the concrete steps (with inputs/outputs to expect) or link to the exact scripts in this repo that implement each step.

Copilot · 2026-04-10T02:33:46Z

+name: "Campaign Details"
+agent: "@ref(type: \"agent\", name: \"Dashboard Viz\")"
 prompt_template: |
  Create dashboard with following conditions:
  - Report_id: 2. Campaign Summary


The form is named “Campaign Details”, but the prompt template uses Report_id: 2. Campaign Summary. If Report_id is user-facing or used to route logic, this mismatch is confusing and can lead to selecting the wrong report type. Please align the Report_id label/value with the report’s name (or document why “Campaign Summary” is the correct identifier).

ko47kmr requested a review from a team as a code owner April 10, 2026 02:30

Copilot AI review requested due to automatic review settings April 10, 2026 02:30

Copilot started reviewing on behalf of ko47kmr April 10, 2026 02:31 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

toru-takahashi approved these changes Apr 10, 2026

View reviewed changes

toru-takahashi merged commit 976a7cb into treasure-data:master Apr 10, 2026
6 of 7 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve ROI Reporting Agent setup documentation and naming#432

Improve ROI Reporting Agent setup documentation and naming#432
toru-takahashi merged 1 commit into
treasure-data:masterfrom
ko47kmr:fix/roi-agent-setup-improvements

ko47kmr commented Apr 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		- ✅ Form Interfaces

		Reference implementation: See the `/llm-api-setup` skill documentation for complete workflow and Python script templates.

Conversation

ko47kmr commented Apr 10, 2026

Summary

Changes

1. Remove "TD-Managed: " prefix from agent and form interface names

2. Fix table names to match actual workflow output

3. Add comprehensive LLM API setup instructions

4. Add data preparation prerequisite

Testing

Impact

Files Changed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants