From 83d0f615a6d3998a11c09b60fc98352599e8dde4 Mon Sep 17 00:00:00 2001 From: "Kona (Koshi Nakamura)" Date: Fri, 10 Apr 2026 11:29:02 +0900 Subject: [PATCH] Improve ROI Reporting Agent setup documentation and naming MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- engage-box/roi_reporting/agent/README.md | 52 ++++++++++++++++--- engage-box/roi_reporting/agent/agent.yml | 2 +- .../td_managed_campaign_details.yml | 4 +- .../td_managed_overall_summary.yml | 4 +- 4 files changed, 51 insertions(+), 11 deletions(-) diff --git a/engage-box/roi_reporting/agent/README.md b/engage-box/roi_reporting/agent/README.md index b3673c5d..22a47fbc 100644 --- a/engage-box/roi_reporting/agent/README.md +++ b/engage-box/roi_reporting/agent/README.md @@ -32,14 +32,20 @@ Two report types are supported: ## Prerequisites +### Data Preparation + +Before using this agent, you need to prepare the required database tables. The `roi_reporting` workflow in the treasure-boxes repository provides a reference implementation for creating these tables. + ### Required Database Tables +The agent requires the following tables in the `engage_roi_reporting` database: + | Table | Description | Key Columns | |---|---|---| | `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` | ### Data Schema Requirements @@ -63,17 +69,51 @@ Two report types are supported: ## Setup Instructions -### Option A: CLI (Recommended) +**IMPORTANT**: The `tdx agent push` command currently creates ONLY the agent resource itself. Knowledge Bases, Tools, Outputs, and Form Interfaces must be configured separately via LLM API or the AI Agent Foundry UI. + +### Option A: LLM API Setup (Recommended for Complete Setup) + +For a fully automated setup including all components, use the LLM API approach: + +**Step 1: Create Project** +```bash +tdx llm project create "ROI Reporting Agent" +``` + +**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) +- ✅ Knowledge Bases (Text KBs and Database KB) +- ✅ Tools and Outputs configuration +- ✅ Form Interfaces + +Reference implementation: See the `/llm-api-setup` skill documentation for complete workflow and Python script templates. + +**Key points:** +- Use `POST /api/agents` to create the agent with core attributes +- Use `POST /api/text_knowledge_bases` for Text KBs +- Use `POST /api/knowledge_bases` for Database KB +- Use `PATCH /api/agents/{id}` to configure tools and outputs +- Use `POST /api/form_interfaces` for form interfaces +- Verify all components after setup + +### Option B: CLI + Manual Configuration (Partial Automation) ```bash # 1. Clone or download this directory # 2. Edit tools.yml and replace with your actual database name -# 3. Run: +# 3. Create project and agent: tdx llm project create "ROI Reporting Agent" tdx agent push . -f ``` -### Option B: Manual (AI Agent Foundry UI) +**Note**: `tdx agent push` creates only the agent itself. You must manually configure: +- Knowledge Bases (via UI or LLM API) +- Tools and Outputs (via LLM API) +- Form Interfaces (via LLM API) + +### Option C: Manual (AI Agent Foundry UI) #### 1. Create Project Create a new project named **`ROI Reporting Agent`** in AI Agent Foundry. @@ -93,7 +133,7 @@ Create a new project named **`ROI Reporting Agent`** in AI Agent Foundry. - Content: paste from `knowledge_base_campaign_details.md` #### 4. Create Agent -- Name: **`TD-Managed: Dashboard Viz`** +- Name: **`Dashboard Viz`** - System Prompt: paste from `system_prompt.md` - Model: Claude 4.5 Sonnet - Max tool iterations: 4 diff --git a/engage-box/roi_reporting/agent/agent.yml b/engage-box/roi_reporting/agent/agent.yml index 1a4fe6ac..af571c32 100644 --- a/engage-box/roi_reporting/agent/agent.yml +++ b/engage-box/roi_reporting/agent/agent.yml @@ -1,5 +1,5 @@ llm_project: "ROI Reporting Agent" -name: "TD-Managed: Dashboard Viz" +name: "Dashboard Viz" model: claude-4.5-sonnet max_tool_iterations: 4 temperature: 0 diff --git a/engage-box/roi_reporting/agent/form_interfaces/td_managed_campaign_details.yml b/engage-box/roi_reporting/agent/form_interfaces/td_managed_campaign_details.yml index 71348f24..ba1a98ec 100644 --- a/engage-box/roi_reporting/agent/form_interfaces/td_managed_campaign_details.yml +++ b/engage-box/roi_reporting/agent/form_interfaces/td_managed_campaign_details.yml @@ -1,5 +1,5 @@ -name: "TD-Managed: Campaign Details" -agent: "@ref(type: \"agent\", name: \"TD-Managed: Dashboard Viz\")" +name: "Campaign Details" +agent: "@ref(type: \"agent\", name: \"Dashboard Viz\")" prompt_template: | Create dashboard with following conditions: - Report_id: 2. Campaign Summary diff --git a/engage-box/roi_reporting/agent/form_interfaces/td_managed_overall_summary.yml b/engage-box/roi_reporting/agent/form_interfaces/td_managed_overall_summary.yml index 8da06d12..3fb0ab44 100644 --- a/engage-box/roi_reporting/agent/form_interfaces/td_managed_overall_summary.yml +++ b/engage-box/roi_reporting/agent/form_interfaces/td_managed_overall_summary.yml @@ -1,5 +1,5 @@ -name: "TD-Managed: Overall Summary" -agent: "@ref(type: \"agent\", name: \"TD-Managed: Dashboard Viz\")" +name: "Overall Summary" +agent: "@ref(type: \"agent\", name: \"Dashboard Viz\")" prompt_template: | Create dashboard with following conditions: - Report_id: 1.Overall Summary