Initial commit
This commit is contained in:
Zhongwei Li
422
skills/deployment/SKILL.md
Normal file
422
skills/deployment/SKILL.md
Normal file
@@ -0,0 +1,422 @@
|
||||
---
|
||||
name: field-agent-deployment
|
||||
description: Best practices for developing, testing, and deploying production-ready Field Agents including R&D workflows, version control, testing strategies, and release management
|
||||
---
|
||||
|
||||
# Field Agent Deployment Best Practices
|
||||
|
||||
This skill provides comprehensive guidelines for the complete lifecycle of Field Agent development and deployment, from initial R&D through production release.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when you need help with:
|
||||
- Setting up a Field Agent development workflow
|
||||
- Structuring a Field Agent project for production
|
||||
- Creating deployment pipelines for Field Agents
|
||||
- Implementing testing strategies for Field Agents
|
||||
- Publishing and releasing Field Agent updates
|
||||
- Managing Field Agent environments (dev, staging, prod)
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### R&D Phase Best Practices
|
||||
|
||||
#### 1. Project Initiation
|
||||
Before starting new agent development:
|
||||
|
||||
```markdown
|
||||
## Pre-Development Checklist
|
||||
- [ ] Validate use case and business requirements
|
||||
- [ ] Review existing agent catalog to avoid duplication
|
||||
- [ ] Get stakeholder approval for new agent development
|
||||
- [ ] Document initial requirements and expected outcomes
|
||||
- [ ] Set up team communication channel
|
||||
- [ ] Publish initial draft documentation to alert team
|
||||
```
|
||||
|
||||
#### 2. Environment Strategy
|
||||
|
||||
**Development Environments:**
|
||||
- R&D can occur in any development environment
|
||||
- Production deployment requires dedicated production instance
|
||||
- Use environment variables for instance-specific configurations
|
||||
|
||||
## Production Publishing Workflow
|
||||
|
||||
### Step-by-Step Publishing Process
|
||||
|
||||
#### Phase 1: Preparation
|
||||
```markdown
|
||||
1. Code Freeze
|
||||
- Ensure all features are complete and tested
|
||||
- No new features during release cycle
|
||||
- Bug fixes only with approval
|
||||
|
||||
2. Quality Gates
|
||||
- All unit tests passing
|
||||
- Integration tests successful
|
||||
- Performance benchmarks met
|
||||
- Security scan completed
|
||||
- Documentation updated
|
||||
```
|
||||
|
||||
#### Phase 2: Pre-Release Testing
|
||||
|
||||
**End-to-End Testing Checklist:**
|
||||
```markdown
|
||||
- [ ] Test all primary use cases in staging environment
|
||||
- [ ] Verify tool integrations and data access
|
||||
- [ ] Validate error handling and edge cases
|
||||
- [ ] Test with various input formats and user prompts
|
||||
- [ ] Verify output format consistency
|
||||
- [ ] Check resource usage (iterations, tokens, runtime)
|
||||
- [ ] Test timeout and failure scenarios
|
||||
- [ ] Validate permissions and access control
|
||||
```
|
||||
|
||||
#### Phase 3: Production Deployment
|
||||
|
||||
**Deployment Checklist:**
|
||||
```markdown
|
||||
## Pre-Deployment
|
||||
- [ ] Clone/update production repository
|
||||
- [ ] Export agent configuration from staging
|
||||
- [ ] Review and validate all configuration files
|
||||
- [ ] Verify README.md is complete and accurate
|
||||
- [ ] Check environment-specific variables
|
||||
|
||||
## Database & Dependencies
|
||||
- [ ] Migrate required databases to production instance
|
||||
- [ ] Verify table schemas match expectations
|
||||
- [ ] Validate data access permissions
|
||||
- [ ] Test external API connections
|
||||
- [ ] Confirm tool dependencies are available
|
||||
|
||||
## Deployment
|
||||
- [ ] Push agent to production instance
|
||||
- [ ] Verify agent appears in production catalog
|
||||
- [ ] Test agent activation and loading
|
||||
- [ ] Run smoke tests in production
|
||||
- [ ] Monitor initial executions for errors
|
||||
|
||||
## Post-Deployment
|
||||
- [ ] Record demo video of production usage
|
||||
- [ ] Update documentation with production links
|
||||
- [ ] Announce release to stakeholders
|
||||
- [ ] Set up monitoring and alerting
|
||||
- [ ] Schedule post-deployment review
|
||||
```
|
||||
|
||||
**Deployment Script Template:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# deploy-agent.sh
|
||||
|
||||
set -e # Exit on error
|
||||
|
||||
AGENT_NAME="customer-segmentation-agent"
|
||||
PROD_INSTANCE="prod-instance-id"
|
||||
GITHUB_REPO="https://github.com/your-org/field-agents"
|
||||
|
||||
echo "Starting deployment for ${AGENT_NAME}..."
|
||||
|
||||
# Step 1: Clone/update repository
|
||||
if [ -d "field-agents" ]; then
|
||||
cd field-agents && git pull origin main && cd ..
|
||||
else
|
||||
git clone ${GITHUB_REPO}
|
||||
fi
|
||||
|
||||
# Step 2: Push to production (use your deployment tool)
|
||||
echo "Deploying to production instance ${PROD_INSTANCE}..."
|
||||
# TODO: Replace with your actual deployment command
|
||||
# Example placeholder: td-agent-cli push --instance ${PROD_INSTANCE} --agent ${AGENT_NAME}
|
||||
# For TD deployments, consult your infrastructure team for the correct deployment tool
|
||||
|
||||
echo "Deployment completed successfully!"
|
||||
```
|
||||
|
||||
## Documentation Standards
|
||||
|
||||
### Required Documentation Components
|
||||
|
||||
#### 1. README.md Template
|
||||
```markdown
|
||||
# [Agent Name]
|
||||
|
||||
Brief one-line description of what this agent does.
|
||||
|
||||
## Overview
|
||||
Detailed description of agent purpose, capabilities, and business value.
|
||||
|
||||
## Quick Start
|
||||
\```
|
||||
# Example usage
|
||||
[Show simplest possible usage example]
|
||||
\```
|
||||
|
||||
## Features
|
||||
- Feature 1: Description
|
||||
- Feature 2: Description
|
||||
- Feature 3: Description
|
||||
|
||||
## Prerequisites
|
||||
- Treasure Data instance access
|
||||
- Required databases: [list databases]
|
||||
- Required tools/integrations: [list tools]
|
||||
|
||||
## Installation
|
||||
Step-by-step installation instructions
|
||||
|
||||
## Usage
|
||||
Common usage patterns and examples
|
||||
|
||||
## Configuration
|
||||
Configuration options and parameters
|
||||
|
||||
## Troubleshooting
|
||||
Common issues and solutions
|
||||
|
||||
## Contributing
|
||||
Guidelines for contributions (if applicable)
|
||||
|
||||
## License & Support
|
||||
License information and support contacts
|
||||
```
|
||||
|
||||
#### 2. Technical Documentation
|
||||
```markdown
|
||||
# [Agent Name] - Technical Documentation
|
||||
|
||||
## Architecture Overview
|
||||
High-level architecture diagram and component description
|
||||
|
||||
## System Prompt
|
||||
Link to or excerpt of system prompt
|
||||
|
||||
## Tools & Functions
|
||||
Detailed description of each tool:
|
||||
- Function name
|
||||
- Purpose
|
||||
- Input parameters
|
||||
- Output format
|
||||
- Example usage
|
||||
|
||||
## Data Flow
|
||||
Describe how data flows through the agent
|
||||
|
||||
## Performance Characteristics
|
||||
- Average execution time
|
||||
- Token usage patterns
|
||||
- Resource requirements
|
||||
|
||||
## Security & Permissions
|
||||
Required permissions and security considerations
|
||||
|
||||
## Version History
|
||||
Major versions and changes
|
||||
```
|
||||
|
||||
#### 3. Demo & Examples
|
||||
|
||||
**Create Demo Content:**
|
||||
```markdown
|
||||
## Demo Video Requirements
|
||||
- Length: 2-5 minutes
|
||||
- Show: Primary use case walkthrough
|
||||
- Include: Input prompt, execution, output
|
||||
- Highlight: Key features and benefits
|
||||
- Format: Screen recording with audio narration
|
||||
|
||||
## Sample Conversations
|
||||
Provide 3-5 example conversations:
|
||||
1. Basic/common use case
|
||||
2. Advanced use case with options
|
||||
3. Error handling example
|
||||
4. Edge case handling
|
||||
5. Integration with other tools
|
||||
```
|
||||
|
||||
## Release Management
|
||||
|
||||
### Version Numbering
|
||||
|
||||
Use semantic versioning (MAJOR.MINOR.PATCH):
|
||||
```
|
||||
1.0.0 - Initial production release
|
||||
1.1.0 - New feature added
|
||||
1.1.1 - Bug fix
|
||||
2.0.0 - Breaking change
|
||||
```
|
||||
|
||||
### Release Notes Template
|
||||
|
||||
```markdown
|
||||
# Release Notes - v1.2.0
|
||||
|
||||
## Release Date
|
||||
2024-11-15
|
||||
|
||||
## Summary
|
||||
Brief overview of this release
|
||||
|
||||
## New Features
|
||||
- Feature 1: Description and benefit
|
||||
- Feature 2: Description and benefit
|
||||
|
||||
## Improvements
|
||||
- Improvement 1: What was enhanced
|
||||
- Improvement 2: Performance optimization details
|
||||
|
||||
## Bug Fixes
|
||||
- Fix 1: Issue resolved
|
||||
- Fix 2: Error corrected
|
||||
|
||||
## Breaking Changes
|
||||
- Change 1: What changed and migration path
|
||||
- Change 2: Required updates
|
||||
|
||||
## Migration Guide
|
||||
Step-by-step instructions for upgrading from previous version
|
||||
|
||||
## Known Issues
|
||||
- Issue 1: Workaround if available
|
||||
- Issue 2: Expected fix timeline
|
||||
```
|
||||
|
||||
### Communication Protocol
|
||||
|
||||
**Release Announcement Template:**
|
||||
```markdown
|
||||
Subject: [RELEASED] [Agent Name] v1.2.0 - [Key Feature]
|
||||
|
||||
Team,
|
||||
|
||||
We've released version 1.2.0 of [Agent Name] to production.
|
||||
|
||||
**Key Updates:**
|
||||
• New feature: [Feature name and benefit]
|
||||
• Improvement: [Performance/usability improvement]
|
||||
• Bug fix: [Critical fix]
|
||||
|
||||
**Links:**
|
||||
• Production Agent: [link]
|
||||
• Documentation: [link]
|
||||
• Demo Video: [link]
|
||||
• Release Notes: [link]
|
||||
|
||||
**Action Required:**
|
||||
[Any required actions for users/teams]
|
||||
|
||||
**Support:**
|
||||
For questions or issues, contact [support channel/person]
|
||||
|
||||
Thanks,
|
||||
[Your Name]
|
||||
```
|
||||
|
||||
## Monitoring & Maintenance
|
||||
|
||||
### Maintenance Schedule
|
||||
|
||||
```markdown
|
||||
## Regular Maintenance Tasks
|
||||
|
||||
### Daily
|
||||
- Review error logs
|
||||
- Monitor execution metrics
|
||||
- Check system health
|
||||
|
||||
### Weekly
|
||||
- Review performance trends
|
||||
- Update documentation if needed
|
||||
- Check for dependency updates
|
||||
|
||||
### Monthly
|
||||
- Security audit
|
||||
- Performance optimization review
|
||||
- User feedback collection and analysis
|
||||
- Roadmap planning
|
||||
|
||||
### Quarterly
|
||||
- Major version planning
|
||||
- Architecture review
|
||||
- Disaster recovery testing
|
||||
```
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### Common Deployment Issues
|
||||
|
||||
```markdown
|
||||
## Issue: Agent Not Appearing in Production
|
||||
|
||||
**Symptoms:** Agent deployed but not visible in catalog
|
||||
|
||||
**Possible Causes:**
|
||||
1. Configuration file not properly formatted
|
||||
2. Agent ID conflict with existing agent
|
||||
3. Permissions not set correctly
|
||||
|
||||
**Solutions:**
|
||||
1. Validate JSON configuration files
|
||||
2. Check for ID conflicts in production catalog
|
||||
3. Verify production instance permissions
|
||||
|
||||
## Issue: Tools Failing in Production
|
||||
|
||||
**Symptoms:** Tools work in dev but fail in production
|
||||
|
||||
**Possible Causes:**
|
||||
1. Database not migrated to production
|
||||
2. API credentials not configured
|
||||
3. Network/firewall restrictions
|
||||
|
||||
**Solutions:**
|
||||
1. Verify database exists: `td db:list | grep [db_name]`
|
||||
2. Check environment variables and secrets
|
||||
3. Test network connectivity to external services
|
||||
|
||||
## Issue: Poor Performance in Production
|
||||
|
||||
**Symptoms:** Agent slower than expected
|
||||
|
||||
**Possible Causes:**
|
||||
1. Large dataset queries without optimization
|
||||
2. Too many tool iterations
|
||||
3. Inefficient system prompt
|
||||
|
||||
**Solutions:**
|
||||
1. Add query filters and limits
|
||||
2. Reduce max_tool_iterations setting
|
||||
3. Optimize system prompt for efficiency
|
||||
```
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
### Do's ✅
|
||||
- Always test thoroughly before production deployment
|
||||
- Use version control for all agent components
|
||||
- Document every configuration change
|
||||
- Create comprehensive test suites
|
||||
- Monitor production usage and errors
|
||||
- Keep dependencies updated
|
||||
- Follow semantic versioning
|
||||
- Communicate releases to stakeholders
|
||||
|
||||
### Don'ts ❌
|
||||
- Don't deploy untested changes to production
|
||||
- Don't skip documentation updates
|
||||
- Don't hardcode environment-specific values
|
||||
- Don't deploy without backup/rollback plan
|
||||
- Don't ignore error logs and metrics
|
||||
- Don't make breaking changes without migration guide
|
||||
- Don't deploy during peak usage hours without notice
|
||||
|
||||
## Resources & Tools
|
||||
|
||||
### Recommended Development Tools
|
||||
- **Version Control:** Git with GitHub/GitLab
|
||||
- **CI/CD:** GitHub Actions, GitLab CI, or Jenkins
|
||||
- **Monitoring:** Application logging and metrics collection
|
||||
- **Documentation:** Markdown with auto-generated API docs
|
||||
941
skills/documentation/SKILL.md
Normal file
941
skills/documentation/SKILL.md
Normal file
@@ -0,0 +1,941 @@
|
||||
---
|
||||
name: field-agent-documentation
|
||||
description: Comprehensive template and guidelines for documenting Field Agents including technical specifications, system prompts, tool specifications, user interactions, and standardized documentation structure
|
||||
---
|
||||
|
||||
# Field Agent Documentation Standards
|
||||
|
||||
This skill provides a complete template and best practices for creating professional, comprehensive documentation for Field Agents. Following these standards ensures consistency, clarity, and ease of use across all agent documentation.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when you need to:
|
||||
- Create documentation for a new Field Agent
|
||||
- Standardize existing Field Agent documentation
|
||||
- Write system prompts with best practices
|
||||
- Define tool specifications and naming conventions
|
||||
- Structure user prompts and interaction patterns
|
||||
- Document agent architecture and technical details
|
||||
|
||||
## Documentation Structure Overview
|
||||
|
||||
Complete Field Agent documentation should include these sections in order:
|
||||
|
||||
```markdown
|
||||
1. Basic Information (metadata, links, status)
|
||||
2. Team Structure (owners, contributors)
|
||||
3. Purpose & Functionality (description, value, users)
|
||||
4. Usage Scenarios (use cases, examples)
|
||||
5. Technical Specifications (model, settings, parameters)
|
||||
6. Dependencies & Integration (requirements, data sources)
|
||||
7. Agent/Sub-Agent Details (per-agent specifications)
|
||||
8. System Prompt (detailed agent instructions)
|
||||
9. Tools (function specifications and schemas)
|
||||
10. Input/Output Format (data structures, formats)
|
||||
11. User Prompts (interaction patterns, guided flows)
|
||||
12. Development Roadmap (milestones, phases)
|
||||
13. Demo (examples, videos, recordings)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 1: Basic Information
|
||||
|
||||
This section provides essential metadata about the agent.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
# [Agent Name]
|
||||
|
||||
## Basic Information
|
||||
|
||||
| Item | Details |
|
||||
|------|---------|
|
||||
| **Project Name** | [Clean, self-explanatory, immutable name] |
|
||||
| **Type** | Field Agent |
|
||||
| **Interface Type** | TD Workflow / Chat / Slack / API |
|
||||
| **GitHub Repo Link** | [Repository URL] |
|
||||
| **Status** | Development / Staging / Production |
|
||||
| **Version** | [Semantic version: MAJOR.MINOR.PATCH] |
|
||||
| **Last Updated** | [YYYY-MM-DD] |
|
||||
| **Agent Instance** | [Cloud provider: instance ID] |
|
||||
| **Agent Link** | [Direct link to agent] |
|
||||
| **One-Pager Slide** | [Link to overview presentation] |
|
||||
| **Demo Video** | [Link to demonstration recording] |
|
||||
| **Demo Talk-Track** | [Link to demo script] |
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
- **Project Name**: Choose a clear, descriptive name that won't change
|
||||
- **Status**: Keep status current (Development → Staging → Production)
|
||||
- **Version**: Use semantic versioning (1.0.0, 1.1.0, 2.0.0)
|
||||
- **Links**: Ensure all links are accessible to target audience
|
||||
|
||||
---
|
||||
|
||||
## Section 2: Team Structure
|
||||
|
||||
Document who is responsible for the agent.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Team Structure
|
||||
|
||||
| Role | Assignee |
|
||||
|------|----------|
|
||||
| **Product Owner / Main Architect** | [Name, Email] |
|
||||
| **Additional Contributors** | [Names, Roles] |
|
||||
| **Support Contact** | [Team/Channel] |
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
- Include contact information for support
|
||||
- List all contributors for accountability
|
||||
- Update when team changes occur
|
||||
|
||||
---
|
||||
|
||||
## Section 3: Purpose & Functionality
|
||||
|
||||
Explain what the agent does and why it matters.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Purpose & Functionality
|
||||
|
||||
### Description
|
||||
[Brief 2-3 sentence description of what the agent performs and its core functionality]
|
||||
|
||||
### Key Capabilities
|
||||
- **Integration 1**: [What it integrates with and how]
|
||||
- **Integration 2**: [What it integrates with and how]
|
||||
- **Core Feature**: [Primary capability description]
|
||||
|
||||
### Business Value
|
||||
[Explain the business value this agent delivers. What problems does it solve? What ROI does it provide?]
|
||||
|
||||
### Target Users
|
||||
- **Primary**: [Job roles/personas who will use this most]
|
||||
- **Secondary**: [Additional users who may benefit]
|
||||
|
||||
### Potential Applications
|
||||
[Detailed description of who will use this agent and in what contexts]
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```markdown
|
||||
## Purpose & Functionality
|
||||
|
||||
### Description
|
||||
Customer Segmentation Agent analyzes customer data to automatically identify behavioral segments using RFM (Recency, Frequency, Monetary) analysis and predictive modeling.
|
||||
|
||||
### Key Capabilities
|
||||
- **Database Integration**: Connects to Treasure Data customer databases
|
||||
- **Segmentation Algorithms**: RFM, K-means clustering, behavioral scoring
|
||||
- **Visualization**: Generates interactive Plotly charts and segment distributions
|
||||
|
||||
### Business Value
|
||||
Enables marketing teams to identify high-value customer segments 10x faster than manual analysis, improving campaign targeting accuracy by 35% and increasing ROI on marketing spend.
|
||||
|
||||
### Target Users
|
||||
- **Primary**: Marketing Managers, CRM Analysts, Customer Success Teams
|
||||
- **Secondary**: Data Analysts, Business Intelligence Teams
|
||||
|
||||
### Potential Applications
|
||||
Marketing teams use this agent to create targeted campaigns, CRM teams identify at-risk customers for retention programs, and analysts explore customer lifetime value patterns.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 4: Usage Scenarios
|
||||
|
||||
Provide concrete examples of how the agent is used.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Usage Scenarios
|
||||
|
||||
### Primary Use Case
|
||||
[Describe the most common use case with a step-by-step example]
|
||||
|
||||
**Example:**
|
||||
1. User asks: "[Sample user query]"
|
||||
2. Agent performs: "[What the agent does]"
|
||||
3. Agent returns: "[What the user receives]"
|
||||
|
||||
### Additional Use Cases
|
||||
1. **Use Case Name**: [Description and benefit]
|
||||
2. **Use Case Name**: [Description and benefit]
|
||||
3. **Use Case Name**: [Description and benefit]
|
||||
|
||||
### Example Scenarios
|
||||
|
||||
#### Scenario 1: [Name]
|
||||
**Context**: [When this scenario applies]
|
||||
**User Input**: "[Example user query]"
|
||||
**Agent Output**: [What the agent provides]
|
||||
**Outcome**: [Business result]
|
||||
|
||||
#### Scenario 2: [Name]
|
||||
[Follow same structure]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 5: Technical Specifications
|
||||
|
||||
Define the technical configuration of the agent.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Technical Specifications
|
||||
|
||||
| Item | Details |
|
||||
|------|---------|
|
||||
| **Agent Name** | [Name - use `[Sub]` prefix for sub-agents] |
|
||||
| **Model Name** | Claude 4 Sonnet ⭐ (Recommended) / Claude 3.5 Sonnet / Claude 3 Haiku |
|
||||
| **Max Tool Iterations** | [Number - controls resource consumption] |
|
||||
| **Temperature** | [0-1, where 0 = deterministic, 1 = creative] ⭐ Recommended: 0 |
|
||||
| **Max Tokens** | [Output token limit] |
|
||||
| **Timeout** | [Execution timeout in seconds] |
|
||||
```
|
||||
|
||||
### Model Selection Guide
|
||||
|
||||
**Claude 4 Sonnet (Recommended)** ⭐
|
||||
- Best for: Most production Field Agents
|
||||
- Benefits: Highest performance, more output tokens, better reasoning
|
||||
- Use when: You need reliability and comprehensive outputs
|
||||
|
||||
**Claude 3.5 Sonnet**
|
||||
- Best for: Alternative to Claude 4, similar capabilities
|
||||
- Benefits: Strong performance, widely tested
|
||||
- Use when: Claude 4 not available or testing compatibility
|
||||
|
||||
**Claude 3 Haiku**
|
||||
- Best for: Lightweight, fast-response tasks
|
||||
- Benefits: Lower cost, faster execution
|
||||
- Use when: Simple queries, real-time requirements, budget constraints
|
||||
|
||||
### Temperature Guide
|
||||
|
||||
| Temperature | Behavior | Best For |
|
||||
|-------------|----------|----------|
|
||||
| **0** ⭐ | Deterministic, consistent answers | Most Field Agents, production use |
|
||||
| **0.3** | Slight variation, mostly consistent | Agents needing minor creative variation |
|
||||
| **0.7** | Balanced creativity and consistency | Content generation with some flexibility |
|
||||
| **1.0** | Maximum creativity, varied outputs | Creative writing, brainstorming agents |
|
||||
|
||||
**Recommended**: Use temperature **0** for Field Agents to ensure consistent, reliable outputs.
|
||||
|
||||
### Max Tool Iterations
|
||||
|
||||
Controls how many times the agent can execute tools before stopping.
|
||||
|
||||
```markdown
|
||||
- **Low (5-10)**: Simple agents with few tool calls
|
||||
- **Medium (15-20)**: Most Field Agents with moderate complexity
|
||||
- **High (25-30)**: Complex agents requiring multiple data sources and iterations
|
||||
```
|
||||
|
||||
**Best Practice**: Start with 15-20, increase only if agent needs more steps.
|
||||
|
||||
---
|
||||
|
||||
## Section 6: Dependencies & Integration
|
||||
|
||||
Document all external requirements and integrations.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Dependencies & Integration
|
||||
|
||||
### Required Data Sources
|
||||
| Data Source | Purpose | Access Requirements |
|
||||
|-------------|---------|---------------------|
|
||||
| [Database/Table] | [What data is used] | [Permissions needed] |
|
||||
|
||||
### Integration Points
|
||||
| Integration | Type | Purpose |
|
||||
|-------------|------|---------|
|
||||
| [System/API] | [REST/GraphQL/SDK] | [What it's used for] |
|
||||
|
||||
### Prerequisites
|
||||
- [ ] Access to [database/system]
|
||||
- [ ] Permissions: [specific permissions]
|
||||
- [ ] API keys configured: [which APIs]
|
||||
- [ ] Dependencies installed: [libraries/tools]
|
||||
|
||||
### Dependencies on Other Systems
|
||||
- [None] OR [List dependent workflows, features, product permissions]
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```markdown
|
||||
## Dependencies & Integration
|
||||
|
||||
### Required Data Sources
|
||||
| Data Source | Purpose | Access Requirements |
|
||||
|-------------|---------|---------------------|
|
||||
| `customer_db.transactions` | Transaction history for RFM analysis | Read access to customer_db |
|
||||
| `customer_db.profiles` | Customer demographic data | Read access to customer_db |
|
||||
|
||||
### Integration Points
|
||||
| Integration | Type | Purpose |
|
||||
|-------------|------|---------|
|
||||
| Treasure Data Trino | SQL Query | Data extraction and analysis |
|
||||
| Plotly | Visualization Library | Chart generation |
|
||||
|
||||
### Prerequisites
|
||||
- [ ] Access to `customer_db` database
|
||||
- [ ] Permissions: Read access on customer tables
|
||||
- [ ] API keys configured: None required
|
||||
- [ ] Dependencies installed: Plotly for visualizations
|
||||
|
||||
### Dependencies on Other Systems
|
||||
- Requires Treasure Data instance with Trino query engine
|
||||
- No dependencies on external workflows
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 7: Agent/Sub-Agent Details
|
||||
|
||||
Provide detailed specifications for each agent and sub-agent.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Agent Details: [Agent Name]
|
||||
|
||||
| Item | Details |
|
||||
|------|---------|
|
||||
| **Agent Name** | [Name] or **[Sub] [Name]** for sub-agents |
|
||||
| **Model Name** | Claude 4 Sonnet ⭐ |
|
||||
| **Max Tool Iterations** | [Number] |
|
||||
| **Temperature** | 0 ⭐ |
|
||||
| **Purpose** | [What this specific agent does] |
|
||||
| **Invocation** | [How this agent is called] |
|
||||
|
||||
### Sub-Agents
|
||||
If this agent uses sub-agents, list them:
|
||||
|
||||
- **[Sub] Sub-Agent Name**: [Purpose and when it's invoked]
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
- Use `[Sub]` prefix for sub-agents to distinguish from main agents
|
||||
- Document invocation patterns (how/when sub-agents are called)
|
||||
- Specify different configurations if sub-agents use different models
|
||||
|
||||
---
|
||||
|
||||
## Section 8: System Prompt
|
||||
|
||||
The system prompt is the most critical element - it defines agent behavior.
|
||||
|
||||
### System Prompt Structure Template
|
||||
|
||||
```markdown
|
||||
## System Prompt: [Agent Name]
|
||||
|
||||
# [Agent Name]
|
||||
|
||||
[Brief one-line description of agent role and purpose]
|
||||
|
||||
# Role
|
||||
|
||||
The agent's role and responsibilities:
|
||||
- [Responsibility 1]
|
||||
- [Responsibility 2]
|
||||
- [Responsibility 3]
|
||||
|
||||
# Goal
|
||||
|
||||
[Detailed description of what the user receives when the agent is executed and what the agent aims to achieve]
|
||||
|
||||
## Basic Principles
|
||||
|
||||
High-level workflow:
|
||||
1. [Step 1: What happens first]
|
||||
2. [Step 2: What happens next]
|
||||
3. [Step 3: Final steps]
|
||||
4. [Step 4: Output delivery]
|
||||
|
||||
## Available Tools
|
||||
|
||||
### [Tool Category/Purpose]
|
||||
|
||||
**Tool**: `tool_name_in_snake_case`
|
||||
**Purpose**: [Brief purpose of this tool]
|
||||
**Input**: [What inputs the tool consumes]
|
||||
**Output**: [What outputs the tool returns]
|
||||
|
||||
### [Next Tool Category]
|
||||
|
||||
**Tool**: `another_tool_name`
|
||||
**Purpose**: [Brief purpose]
|
||||
**Input**: [Input parameters]
|
||||
**Output**: [Return values]
|
||||
|
||||
## Task Flow
|
||||
|
||||
### Task 1: [Tool Name] [required = true, mandatory_start = true]
|
||||
|
||||
**Execution**:
|
||||
call_<tool_name>[required = true, mandatory_start = true]
|
||||
|
||||
**Steps** [sequential=true]:
|
||||
1. [Detailed step-by-step pseudo-logic]
|
||||
2. [What the tool should do]
|
||||
3. [How to handle results]
|
||||
4. [Error handling]
|
||||
|
||||
**Output Format**:
|
||||
[Describe or show sample output format]
|
||||
|
||||
### Task 2: [Next Tool] [required = false]
|
||||
|
||||
[Follow same structure]
|
||||
|
||||
## Checklist (Optional)
|
||||
|
||||
If applicable, provide a validation checklist:
|
||||
- [ ] [Validation item 1]
|
||||
- [ ] [Validation item 2]
|
||||
- [ ] [Validation item 3]
|
||||
```
|
||||
|
||||
### System Prompt Best Practices
|
||||
|
||||
#### 1. Tool Naming Conventions ⭐
|
||||
|
||||
**Use snake_case with descriptive names:**
|
||||
|
||||
✅ **Good Examples:**
|
||||
```
|
||||
verify_database_access
|
||||
list_columns_customer_db
|
||||
query_sales_data
|
||||
calculate_rfm_scores
|
||||
generate_segment_visualization
|
||||
fetch_customer_transactions
|
||||
```
|
||||
|
||||
❌ **Bad Examples:**
|
||||
```
|
||||
verify # Too vague
|
||||
list # What are we listing?
|
||||
query # Query what?
|
||||
verifydbaccess # Hard to read, no separators
|
||||
listColumns # Should be snake_case
|
||||
```
|
||||
|
||||
**Naming Pattern**: `[action]_[object]_[context]`
|
||||
- **Action**: verify, list, query, calculate, generate, fetch, create, update
|
||||
- **Object**: database, columns, data, scores, visualization
|
||||
- **Context**: customer_db, sales, rfm, etc.
|
||||
|
||||
#### 2. Reduce Hallucination with Detailed Logic
|
||||
|
||||
Provide explicit pseudo-logic instead of general instructions:
|
||||
|
||||
✅ **Good - Explicit Logic:**
|
||||
```markdown
|
||||
### Task 1: Query Customer Data
|
||||
|
||||
**Steps** [sequential=true]:
|
||||
1. Call `verify_database_access` with database name
|
||||
2. If access is denied, return error message: "Database access denied. Please check permissions."
|
||||
3. If access is granted, call `list_columns_customer_db` to retrieve schema
|
||||
4. Validate that required columns exist: ['customer_id', 'revenue', 'last_purchase_date']
|
||||
5. If columns missing, return error: "Required columns not found: [list missing columns]"
|
||||
6. If columns exist, call `query_sales_data` with filters:
|
||||
- WHERE last_purchase_date >= DATE_SUB(CURRENT_DATE, INTERVAL 365 DAY)
|
||||
- AND revenue > 0
|
||||
7. Return result set in JSON format
|
||||
```
|
||||
|
||||
❌ **Bad - Vague Instructions:**
|
||||
```markdown
|
||||
### Task 1: Query Customer Data
|
||||
|
||||
Query the customer database and get the data we need.
|
||||
```
|
||||
|
||||
#### 3. Specify Sequential vs. Parallel Execution
|
||||
|
||||
```markdown
|
||||
**Steps** [sequential=true]:
|
||||
# Tasks must execute in order - each depends on previous
|
||||
|
||||
**Steps** [parallel=true]:
|
||||
# Tasks can execute simultaneously - no dependencies
|
||||
```
|
||||
|
||||
#### 4. Include Sample Output Formats
|
||||
|
||||
```markdown
|
||||
**Output Format**:
|
||||
\```json
|
||||
{
|
||||
"status": "success",
|
||||
"segments": [
|
||||
{
|
||||
"segment_name": "Champions",
|
||||
"customer_count": 1250,
|
||||
"avg_revenue": 5200.00,
|
||||
"characteristics": {
|
||||
"recency_score": 5,
|
||||
"frequency_score": 5,
|
||||
"monetary_score": 5
|
||||
}
|
||||
}
|
||||
],
|
||||
"total_customers_analyzed": 5000,
|
||||
"execution_time_ms": 2341
|
||||
}
|
||||
\```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 9: Tools
|
||||
|
||||
Document each tool/function specification.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Tools
|
||||
|
||||
### Tool: `tool_name_in_snake_case`
|
||||
|
||||
| Item | Details |
|
||||
|------|---------|
|
||||
| **Function Name** | `tool_name_in_snake_case` |
|
||||
| **Function Description** | [Brief description of what this function does] |
|
||||
| **Target** | Knowledge Base / Agent / External API |
|
||||
| **Target Function** | List Columns / Query Data / Search Schema / Custom |
|
||||
|
||||
#### Input Format
|
||||
\```json
|
||||
{
|
||||
"parameter1": "value1",
|
||||
"parameter2": "value2"
|
||||
}
|
||||
\```
|
||||
|
||||
#### Output Format
|
||||
\```json
|
||||
{
|
||||
"result": "data",
|
||||
"status": "success"
|
||||
}
|
||||
\```
|
||||
|
||||
#### Example Usage
|
||||
\```
|
||||
User: "Get customer segments"
|
||||
Tool Call: query_customer_segments({"min_revenue": 1000})
|
||||
Tool Response: {"segments": [...], "total": 5}
|
||||
\```
|
||||
|
||||
### Tool: `next_tool_name`
|
||||
|
||||
[Follow same structure for each tool]
|
||||
```
|
||||
|
||||
### Tool Target Types
|
||||
|
||||
**Knowledge Base Tools:**
|
||||
- **List Columns**: Retrieve schema information
|
||||
- **Query Data (Trino SQL)**: Execute SQL queries
|
||||
- **Search Schema**: Find tables/columns (avoid if possible - can be slow)
|
||||
|
||||
**Agent Tools:**
|
||||
- **Sub-Agent Call**: Invoke another agent and return results
|
||||
- **Custom Function**: Execute custom Python/JavaScript code
|
||||
|
||||
### Best Practices for Tool Documentation
|
||||
1. **Match names** between system prompt and tool specification exactly
|
||||
2. **Use snake_case** consistently
|
||||
3. **Provide examples** of inputs and outputs
|
||||
4. **Document errors** and how the tool handles them
|
||||
5. **Specify data types** for all parameters
|
||||
|
||||
---
|
||||
|
||||
## Section 10: Input/Output Format
|
||||
|
||||
Define how users interact with the agent and what they receive.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Input/Output Format
|
||||
|
||||
### Input Format
|
||||
|
||||
**Language Request**: [Natural language or structured format]
|
||||
|
||||
**Sample Dialogue**:
|
||||
\```
|
||||
User: "[Example user query]"
|
||||
Agent: "[Agent's clarifying question if needed]"
|
||||
User: "[User's response]"
|
||||
\```
|
||||
|
||||
**Optional Parameters**:
|
||||
- `parameter_name`: [Description, constraints, default value]
|
||||
- `another_parameter`: [Description, constraints, default value]
|
||||
|
||||
### Output Format
|
||||
|
||||
**Output Type**: HTML / Plotly Graph / Markdown / JSON / Summarized Text
|
||||
|
||||
**Sample Output**:
|
||||
[Show representative example of what the user receives]
|
||||
|
||||
### Sample Conversation Flow
|
||||
|
||||
\```
|
||||
User: "Analyze my customer segments for Q4 2024"
|
||||
|
||||
Agent: "I'll analyze your customer segments. I can use RFM analysis, behavioral clustering, or both. Which would you prefer?"
|
||||
|
||||
User: "Both"
|
||||
|
||||
Agent: [Executes analysis]
|
||||
|
||||
Agent Output:
|
||||
# Customer Segmentation Analysis - Q4 2024
|
||||
|
||||
## RFM Segments
|
||||
[Table showing segments]
|
||||
|
||||
## Behavioral Clusters
|
||||
[Visualization showing clusters]
|
||||
|
||||
## Key Insights
|
||||
- [Insight 1]
|
||||
- [Insight 2]
|
||||
\```
|
||||
```
|
||||
|
||||
### Output Format Options
|
||||
|
||||
| Format | Best For | Example |
|
||||
|--------|----------|---------|
|
||||
| **HTML** | Structured presentation with formatting | Reports, dashboards, formatted tables |
|
||||
| **Plotly Graph** | Data visualizations | Charts, graphs, interactive visualizations |
|
||||
| **Markdown** | Text-heavy content with structure | Analysis summaries, documentation |
|
||||
| **JSON** | Programmatic consumption | API responses, data pipelines |
|
||||
| **Summarized Text** | Quick insights | Executive summaries, key findings |
|
||||
|
||||
---
|
||||
|
||||
## Section 11: User Prompts
|
||||
|
||||
User prompts guide the conversation and capture necessary information.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## User Prompt: [Prompt Name]
|
||||
|
||||
| Item | Details |
|
||||
|------|---------|
|
||||
| **User Prompt Name** | [Descriptive name indicating purpose] |
|
||||
| **Purpose** | [What this prompt accomplishes] |
|
||||
|
||||
### User Prompt Text
|
||||
|
||||
\```
|
||||
Step 1: [First question or instruction]
|
||||
- Option A: [Description]
|
||||
- Option B: [Description]
|
||||
- Option C: [Description]
|
||||
|
||||
Step 2: [Next question based on previous answer]
|
||||
[Continue step-by-step flow]
|
||||
|
||||
Step 3: [Final configuration]
|
||||
[Gather remaining details]
|
||||
\```
|
||||
|
||||
### Advanced Settings
|
||||
|
||||
**Pre-Configuration Checklist**:
|
||||
- [ ] [Configuration item 1]
|
||||
- [ ] [Configuration item 2]
|
||||
- [ ] [Configuration item 3]
|
||||
|
||||
**System Prompt Override** (if applicable):
|
||||
[Explain if/when system prompt can be customized by users]
|
||||
|
||||
### Sample Conversation
|
||||
|
||||
\```
|
||||
Agent: "Welcome! I can help you with customer segmentation. What would you like to do?
|
||||
1. Analyze existing segments
|
||||
2. Create new segments
|
||||
3. Compare segment performance"
|
||||
|
||||
User: "Analyze existing segments"
|
||||
|
||||
Agent: "Great! Which time period should I analyze?
|
||||
- Last 30 days
|
||||
- Last quarter
|
||||
- Last year
|
||||
- Custom date range"
|
||||
|
||||
User: "Last quarter"
|
||||
|
||||
Agent: "Analyzing your customer segments for Q3 2024..."
|
||||
[Proceeds with analysis]
|
||||
\```
|
||||
```
|
||||
|
||||
### User Prompt Best Practices
|
||||
|
||||
1. **Step-by-step flow**: Guide users through complex tasks incrementally
|
||||
2. **Clear options**: Provide specific choices rather than open-ended questions
|
||||
3. **Context**: Explain what each option does and why they'd choose it
|
||||
4. **Validation**: Include checks to ensure user input is valid
|
||||
5. **Defaults**: Suggest sensible defaults for common use cases
|
||||
|
||||
---
|
||||
|
||||
## Section 12: Development Roadmap
|
||||
|
||||
Track the agent's development milestones and future plans.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Development Roadmap
|
||||
|
||||
### Milestones
|
||||
|
||||
| Phase | Date | Deliverables | Status |
|
||||
|-------|------|--------------|--------|
|
||||
| **Planning** | [Date] | Requirements, architecture design, team formation | ✅ Complete |
|
||||
| **Development** | [Date] | Core functionality, tools, system prompt | ✅ Complete |
|
||||
| **Testing** | [Date] | Unit tests, integration tests, user testing | ✅ Complete |
|
||||
| **Deployment** | [Date] | Production deployment, documentation, training | 🔄 In Progress |
|
||||
| **Enhancement** | [Date] | Feature additions, optimizations, feedback integration | 📅 Planned |
|
||||
|
||||
### Future Enhancements
|
||||
- [ ] [Planned feature 1]
|
||||
- [ ] [Planned feature 2]
|
||||
- [ ] [Planned feature 3]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 13: Demo
|
||||
|
||||
Provide examples and demonstrations of the agent in action.
|
||||
|
||||
### Template
|
||||
|
||||
```markdown
|
||||
## Demo
|
||||
|
||||
### Input Example
|
||||
|
||||
\```
|
||||
User Query: "[Realistic example user input]"
|
||||
|
||||
Context:
|
||||
- [Relevant context or prerequisites]
|
||||
\```
|
||||
|
||||
### Output Example
|
||||
|
||||
\```
|
||||
[Show exactly what the agent returns]
|
||||
|
||||
[Include visualizations, formatted output, or screenshots]
|
||||
\```
|
||||
|
||||
### Video Recording
|
||||
|
||||
**Demo Video**: [Link to recording]
|
||||
**Duration**: [Length]
|
||||
**Covers**: [What the demo shows]
|
||||
|
||||
### Live Demo Access
|
||||
|
||||
**Demo Environment**: [Link if available]
|
||||
**Test Credentials**: [If applicable]
|
||||
**Sample Data**: [Link to sample data for testing]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Documentation Example
|
||||
|
||||
Here's a concise example applying all the templates:
|
||||
|
||||
```markdown
|
||||
# Customer RFM Segmentation Agent
|
||||
|
||||
## Basic Information
|
||||
|
||||
| Item | Details |
|
||||
|------|---------|
|
||||
| **Project Name** | Customer RFM Segmentation Agent |
|
||||
| **Type** | Field Agent |
|
||||
| **Interface Type** | Chat |
|
||||
| **Status** | Production |
|
||||
| **Version** | 1.2.0 |
|
||||
| **Model** | Claude 4 Sonnet |
|
||||
| **Temperature** | 0 |
|
||||
|
||||
## Purpose & Functionality
|
||||
|
||||
### Description
|
||||
Automatically segments customers using RFM (Recency, Frequency, Monetary) analysis to identify high-value segments and at-risk customers.
|
||||
|
||||
### Business Value
|
||||
Enables 10x faster customer segmentation, improving campaign targeting by 35% and increasing marketing ROI.
|
||||
|
||||
## System Prompt: RFM Agent
|
||||
|
||||
# Customer RFM Segmentation Agent
|
||||
|
||||
Analyzes customer transaction data to create actionable segments.
|
||||
|
||||
# Role
|
||||
- Query customer transaction databases
|
||||
- Calculate RFM scores for each customer
|
||||
- Assign customers to segments based on scores
|
||||
- Generate visualizations and insights
|
||||
|
||||
# Goal
|
||||
Provide marketers with clear customer segments and actionable insights for targeted campaigns.
|
||||
|
||||
## Available Tools
|
||||
|
||||
### Database Access
|
||||
**Tool**: `verify_database_access`
|
||||
**Purpose**: Verify user has access to customer database
|
||||
**Input**: Database name
|
||||
**Output**: Access status (granted/denied)
|
||||
|
||||
### Data Retrieval
|
||||
**Tool**: `query_customer_transactions`
|
||||
**Purpose**: Retrieve customer transaction history
|
||||
**Input**: Database, table, date range
|
||||
**Output**: Transaction records with customer_id, date, amount
|
||||
|
||||
### RFM Calculation
|
||||
**Tool**: `calculate_rfm_scores`
|
||||
**Purpose**: Calculate Recency, Frequency, Monetary scores
|
||||
**Input**: Transaction data
|
||||
**Output**: RFM scores per customer
|
||||
|
||||
### Visualization
|
||||
**Tool**: `generate_segment_chart`
|
||||
**Purpose**: Create Plotly visualization of segments
|
||||
**Input**: Segment data
|
||||
**Output**: Plotly JSON chart specification
|
||||
|
||||
## Task Flow
|
||||
|
||||
### Task 1: Verify Access [required = true, mandatory_start = true]
|
||||
|
||||
**Steps** [sequential=true]:
|
||||
1. Call `verify_database_access` with customer database name
|
||||
2. If access denied, return error and stop
|
||||
3. If access granted, proceed to Task 2
|
||||
|
||||
### Task 2: Retrieve Transaction Data [required = true]
|
||||
|
||||
**Steps** [sequential=true]:
|
||||
1. Call `query_customer_transactions` with date range (default: last 365 days)
|
||||
2. Validate minimum 100 records returned
|
||||
3. If insufficient data, warn user and ask to expand date range
|
||||
4. Proceed to Task 3
|
||||
|
||||
### Task 3: Calculate RFM [required = true]
|
||||
|
||||
**Steps** [sequential=true]:
|
||||
1. Call `calculate_rfm_scores` with transaction data
|
||||
2. Assign scores 1-5 for Recency (days since last purchase)
|
||||
3. Assign scores 1-5 for Frequency (number of purchases)
|
||||
4. Assign scores 1-5 for Monetary (total revenue)
|
||||
5. Create segments based on score combinations:
|
||||
- Champions: RFM 5-5-5
|
||||
- Loyal: RFM 4-5-4 or 5-4-5
|
||||
- At Risk: RFM 2-3-3 or 3-2-3
|
||||
- Lost: RFM 1-1-1
|
||||
6. Proceed to Task 4
|
||||
|
||||
### Task 4: Generate Output [required = true]
|
||||
|
||||
**Steps** [parallel=true]:
|
||||
1. Call `generate_segment_chart` to create visualization
|
||||
2. Format summary statistics
|
||||
3. Compile key insights
|
||||
|
||||
**Output Format**:
|
||||
\```json
|
||||
{
|
||||
"segments": [
|
||||
{"name": "Champions", "count": 1250, "avg_revenue": 5200},
|
||||
{"name": "Loyal", "count": 2100, "avg_revenue": 3100}
|
||||
],
|
||||
"chart": { "plotly_json": "..." },
|
||||
"insights": ["45% of revenue from Champions (25% of customers)"]
|
||||
}
|
||||
\```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
### Documentation Do's ✅
|
||||
- Use clear, descriptive tool names in snake_case
|
||||
- Provide detailed pseudo-logic in system prompts
|
||||
- Include sample inputs and outputs for every tool
|
||||
- Keep documentation updated with code changes
|
||||
- Use semantic versioning
|
||||
- Include visual examples and demos
|
||||
- Document error handling explicitly
|
||||
|
||||
### Documentation Don'ts ❌
|
||||
- Don't use vague tool names (verify, list, query)
|
||||
- Don't write generic system prompts without details
|
||||
- Don't skip example conversations
|
||||
- Don't forget to update version numbers
|
||||
- Don't leave links broken or outdated
|
||||
- Don't omit dependencies or prerequisites
|
||||
- Don't publish without demo/video
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Tool Naming
|
||||
|
||||
| Purpose | Good Name | Bad Name |
|
||||
|---------|-----------|----------|
|
||||
| Verify database access | `verify_database_access` | `verify` |
|
||||
| List columns from customer DB | `list_columns_customer_db` | `listColumns` |
|
||||
| Query sales data | `query_sales_data` | `query` |
|
||||
| Calculate RFM scores | `calculate_rfm_scores` | `calcRFM` |
|
||||
| Generate visualization | `generate_segment_chart` | `makeChart` |
|
||||
|
||||
---
|
||||
|
||||
By following this comprehensive documentation template, your Field Agent documentation will be clear, consistent, and professional, making it easy for users to understand, deploy, and use your agents effectively.
|
||||
975
skills/visualization/SKILL.md
Normal file
975
skills/visualization/SKILL.md
Normal file
@@ -0,0 +1,975 @@
|
||||
---
|
||||
name: field-agent-visualization
|
||||
description: Professional Plotly visualization best practices for Field Agents including chart specifications, color palettes, formatting standards, and JSON structure requirements for executive-ready data visualizations
|
||||
---
|
||||
|
||||
# Field Agent Visualization Best Practices
|
||||
|
||||
This skill provides comprehensive guidelines for creating professional, executive-ready visualizations for Field Agents using Plotly. Follow these standards to ensure clean, readable, and impactful data visualizations.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when you need to:
|
||||
- Create Plotly visualizations for Field Agent outputs
|
||||
- Generate charts for data analysis and reporting
|
||||
- Build dashboards with KPI indicators
|
||||
- Design executive-ready visual presentations
|
||||
- Ensure consistent visualization standards across agents
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Golden Rules
|
||||
1. **Create SINGLE CHARTS ONLY** - NO SUBPLOTS for analysis charts
|
||||
2. **Always use descriptive titles, axis labels, and legends**
|
||||
3. **Ensure proper formatting and readability**
|
||||
4. **Use the specified color palette consistently**
|
||||
5. **Always show numbers/percentages in bar charts and heatmaps**
|
||||
6. **LEGENDS MUST BE VISIBLE** for pie charts and comparison charts
|
||||
7. **NEVER CREATE SUBPLOTS** for analysis - Always create separate individual charts
|
||||
|
||||
## MANDATORY Color Palette
|
||||
|
||||
Always use this Treasure Data color palette for consistency:
|
||||
|
||||
```python
|
||||
TD_COLORS = [
|
||||
'#44BAB8', # Teal (Primary)
|
||||
'#8FD6D4', # Light Teal
|
||||
'#DAF1F1', # Pale Teal
|
||||
'#2E41A6', # Navy Blue
|
||||
'#828DCA', # Purple
|
||||
'#D5D9ED', # Light Purple
|
||||
'#8CC97E', # Green
|
||||
'#BADFB2', # Light Green
|
||||
'#E8F4E5', # Pale Green
|
||||
'#EEB53A', # Accent Yellow
|
||||
'#F5D389', # Light Yellow
|
||||
'#5FCFD8', # Cyan
|
||||
'#A05EB0', # Magenta
|
||||
'#C69ED0' # Light Magenta
|
||||
]
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
- Use `#44BAB8` (Teal) as primary color for single-series charts
|
||||
- Use `#2E41A6` (Navy) for text and titles
|
||||
- Cycle through colors for multi-series charts
|
||||
- Use color scales for heatmaps (DAF1F1 → 8FD6D4 → 44BAB8)
|
||||
|
||||
### Color Conversion Helper Function
|
||||
|
||||
For charts requiring RGB/RGBA format (e.g., transparency effects):
|
||||
|
||||
```python
|
||||
def hex_to_rgb(hex_color):
|
||||
"""Convert hex color to RGB tuple
|
||||
|
||||
Args:
|
||||
hex_color (str): Hex color code (e.g., '#44BAB8' or '44BAB8')
|
||||
|
||||
Returns:
|
||||
tuple: RGB values as (R, G, B) where each value is 0-255
|
||||
|
||||
Example:
|
||||
>>> hex_to_rgb('#44BAB8')
|
||||
(68, 186, 184)
|
||||
"""
|
||||
hex_color = hex_color.lstrip('#')
|
||||
return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4))
|
||||
|
||||
def hex_to_rgba(hex_color, alpha=1.0):
|
||||
"""Convert hex color to RGBA string for Plotly
|
||||
|
||||
Args:
|
||||
hex_color (str): Hex color code (e.g., '#44BAB8')
|
||||
alpha (float): Opacity value 0.0-1.0
|
||||
|
||||
Returns:
|
||||
str: RGBA color string (e.g., 'rgba(68, 186, 184, 0.5)')
|
||||
|
||||
Example:
|
||||
>>> hex_to_rgba('#44BAB8', 0.5)
|
||||
'rgba(68, 186, 184, 0.5)'
|
||||
"""
|
||||
r, g, b = hex_to_rgb(hex_color)
|
||||
return f'rgba({r}, {g}, {b}, {alpha})'
|
||||
|
||||
# Usage examples:
|
||||
td_primary_rgb = hex_to_rgb('#44BAB8') # (68, 186, 184)
|
||||
td_primary_transparent = hex_to_rgba('#44BAB8', 0.3) # 'rgba(68, 186, 184, 0.3)'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CRITICAL: JSON Structure Requirements
|
||||
|
||||
### ✅ CORRECT JSON Format
|
||||
|
||||
Always use proper JSON objects with native arrays and objects:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"type": "bar",
|
||||
"x": ["A", "B", "C"],
|
||||
"y": [10, 20, 30],
|
||||
"marker": {"color": "#44BAB8"},
|
||||
"text": ["10", "20", "30"],
|
||||
"textposition": "outside",
|
||||
"textfont": {"size": 11, "color": "black"}
|
||||
}
|
||||
],
|
||||
"layout": {
|
||||
"title": {
|
||||
"text": "Chart Title",
|
||||
"x": 0.5,
|
||||
"font": {"size": 18, "color": "#2E41A6"}
|
||||
},
|
||||
"height": 500,
|
||||
"showlegend": true,
|
||||
"margin": {"t": 120, "b": 80, "l": 80, "r": 80},
|
||||
"font": {"family": "Arial", "size": 12},
|
||||
"plot_bgcolor": "white",
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ❌ NEVER DO: String Data (Causes Errors)
|
||||
|
||||
```json
|
||||
{
|
||||
"data": "[{\"type\": \"bar\", \"x\": [\"A\", \"B\"], \"y\": [10, 20]}]"
|
||||
}
|
||||
```
|
||||
|
||||
**Critical**: Data must be JSON objects and arrays, NOT stringified JSON.
|
||||
|
||||
---
|
||||
|
||||
## CRITICAL: Missing Elements Fixes
|
||||
|
||||
### For Bar Charts - MANDATORY Properties
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [{
|
||||
"type": "bar",
|
||||
"x": ["Category A", "Category B", "Category C"],
|
||||
"y": [45, 30, 25],
|
||||
"name": "Series Name",
|
||||
"marker": {"color": "#44BAB8"},
|
||||
"text": [45, 30, 25], // ⚠️ CRITICAL: Must include for numbers on bars
|
||||
"textposition": "outside", // ⚠️ CRITICAL: Shows numbers above bars
|
||||
"textfont": {"size": 11, "color": "black"}
|
||||
}],
|
||||
"layout": {
|
||||
"title": {"text": "Bar Chart Title", "x": 0.5, "font": {"size": 18}},
|
||||
"height": 500,
|
||||
"showlegend": true, // ⚠️ CRITICAL: Must be true for multi-series
|
||||
"legend": {
|
||||
"orientation": "h",
|
||||
"yanchor": "bottom",
|
||||
"y": 1.05, // ⚠️ CRITICAL: Must be above 1.0 to be visible
|
||||
"xanchor": "center",
|
||||
"x": 0.5
|
||||
},
|
||||
"margin": {"t": 120, "b": 80, "l": 80, "r": 80}, // ⚠️ CRITICAL: Extra top margin for legend
|
||||
"xaxis": {"title": {"text": "Categories", "font": {"size": 14}}},
|
||||
"yaxis": {"title": {"text": "Values", "font": {"size": 14}}},
|
||||
"font": {"family": "Arial", "size": 12},
|
||||
"plot_bgcolor": "white",
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### For Heatmaps - MANDATORY Properties
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [{
|
||||
"type": "heatmap",
|
||||
"x": ["Col A", "Col B", "Col C"],
|
||||
"y": ["Row 1", "Row 2", "Row 3"],
|
||||
"z": [[23.4, 45.6, 12.3], [34.5, 56.7, 23.1], [45.2, 67.8, 34.5]],
|
||||
"text": [[23.4, 45.6, 12.3], [34.5, 56.7, 23.1], [45.2, 67.8, 34.5]], // ⚠️ CRITICAL: Numbers to display
|
||||
"texttemplate": "%{text:.1f}", // ⚠️ CRITICAL: Format to 1 decimal
|
||||
"textfont": {"size": 12, "color": "black"}, // ⚠️ CRITICAL: Visible text
|
||||
"showscale": true, // ⚠️ CRITICAL: Show color scale
|
||||
"colorscale": [
|
||||
[0, "#DAF1F1"],
|
||||
[0.5, "#8FD6D4"],
|
||||
[1, "#44BAB8"]
|
||||
],
|
||||
"colorbar": {
|
||||
"title": {"text": "Value", "font": {"size": 12}},
|
||||
"titleside": "right"
|
||||
},
|
||||
"hovertemplate": "<b>%{y}</b> - <b>%{x}</b><br>Value: %{z:.1f}<extra></extra>"
|
||||
}],
|
||||
"layout": {
|
||||
"title": {"text": "Heatmap Title", "x": 0.5, "font": {"size": 18}},
|
||||
"height": 500,
|
||||
"xaxis": {"title": {"text": "X Axis", "font": {"size": 14}}},
|
||||
"yaxis": {"title": {"text": "Y Axis", "font": {"size": 14}}},
|
||||
"margin": {"t": 80, "b": 80, "l": 80, "r": 100},
|
||||
"font": {"family": "Arial", "size": 12},
|
||||
"plot_bgcolor": "white",
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Issues Fix Checklist
|
||||
|
||||
Before generating any chart, verify:
|
||||
|
||||
- [ ] **Bar charts**: Include `"text"`, `"textposition": "outside"`, `"textfont"`
|
||||
- [ ] **Multi-series**: Include `"showlegend": true`, legend `"y": 1.05` or higher
|
||||
- [ ] **Legend spacing**: Top margin `"t": 120` minimum for horizontal legends
|
||||
- [ ] **Heatmaps**: Include `"text"`, `"texttemplate": "%{text:.1f}"`, `"showscale": true`
|
||||
- [ ] **Text visibility**: Use `"textfont": {"color": "black"}` for contrast
|
||||
- [ ] **JSON format**: Use proper objects/arrays, NOT stringified JSON
|
||||
- [ ] **Color palette**: Use TD colors exclusively
|
||||
- [ ] **No subplots**: Create individual charts for analysis
|
||||
|
||||
---
|
||||
|
||||
## Chart-Specific Guidelines
|
||||
|
||||
### 1. Pie Charts - LEGEND MANDATORY
|
||||
|
||||
Pie charts **ALWAYS** require visible legends.
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [{
|
||||
"type": "pie",
|
||||
"values": [45, 30, 25],
|
||||
"labels": ["Channel A", "Channel B", "Channel C"],
|
||||
"marker": {
|
||||
"colors": ["#44BAB8", "#8FD6D4", "#DAF1F1"]
|
||||
},
|
||||
"textinfo": "label+percent",
|
||||
"textposition": "auto",
|
||||
"textfont": {"size": 14, "color": "black"},
|
||||
"hovertemplate": "<b>%{label}</b><br>Value: %{value}<br>Percentage: %{percent}<extra></extra>"
|
||||
}],
|
||||
"layout": {
|
||||
"title": {
|
||||
"text": "Attribution Distribution",
|
||||
"x": 0.5,
|
||||
"font": {"size": 18, "color": "#2E41A6"}
|
||||
},
|
||||
"height": 500,
|
||||
"showlegend": true,
|
||||
"legend": {
|
||||
"orientation": "v",
|
||||
"yanchor": "middle",
|
||||
"y": 0.5,
|
||||
"xanchor": "left",
|
||||
"x": 1.02,
|
||||
"font": {"size": 12}
|
||||
},
|
||||
"margin": {"t": 80, "b": 80, "l": 80, "r": 150},
|
||||
"font": {"family": "Arial", "size": 12},
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
- Use vertical legend positioned to the right (`x: 1.02`)
|
||||
- Include extra right margin (`r: 150`) for legend space
|
||||
- Show both label and percent in slices
|
||||
- Use TD color palette for consistent branding
|
||||
|
||||
---
|
||||
|
||||
### 2. Bar Charts with Comparison - LEGEND VISIBLE
|
||||
|
||||
Multi-series bar charts require horizontal legends positioned above the chart.
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"type": "bar",
|
||||
"x": ["Channel A", "Channel B", "Channel C"],
|
||||
"y": [45, 30, 25],
|
||||
"name": "Metric 1",
|
||||
"marker": {"color": "#44BAB8"},
|
||||
"text": [45, 30, 25],
|
||||
"textposition": "outside",
|
||||
"textfont": {"size": 11, "color": "black"}
|
||||
},
|
||||
{
|
||||
"type": "bar",
|
||||
"x": ["Channel A", "Channel B", "Channel C"],
|
||||
"y": [35, 40, 30],
|
||||
"name": "Metric 2",
|
||||
"marker": {"color": "#8FD6D4"},
|
||||
"text": [35, 40, 30],
|
||||
"textposition": "outside",
|
||||
"textfont": {"size": 11, "color": "black"}
|
||||
}
|
||||
],
|
||||
"layout": {
|
||||
"title": {
|
||||
"text": "Channel Comparison",
|
||||
"x": 0.5,
|
||||
"font": {"size": 18, "color": "#2E41A6"}
|
||||
},
|
||||
"height": 500,
|
||||
"barmode": "group",
|
||||
"showlegend": true,
|
||||
"legend": {
|
||||
"orientation": "h",
|
||||
"yanchor": "bottom",
|
||||
"y": 1.05,
|
||||
"xanchor": "center",
|
||||
"x": 0.5,
|
||||
"font": {"size": 12}
|
||||
},
|
||||
"xaxis": {
|
||||
"title": {"text": "Channels", "font": {"size": 14, "color": "#2E41A6"}}
|
||||
},
|
||||
"yaxis": {
|
||||
"title": {"text": "Performance %", "font": {"size": 14, "color": "#2E41A6"}}
|
||||
},
|
||||
"margin": {"t": 120, "b": 80, "l": 80, "r": 80},
|
||||
"font": {"family": "Arial", "size": 12},
|
||||
"plot_bgcolor": "white",
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
- Set `barmode` to `"group"` for side-by-side or `"stack"` for stacked
|
||||
- Horizontal legend above chart (`y: 1.05`)
|
||||
- Adequate top margin (`t: 120`)
|
||||
- Numbers displayed on all bars
|
||||
|
||||
---
|
||||
|
||||
### 3. Single Bar Chart - NO Legend Needed
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [{
|
||||
"type": "bar",
|
||||
"x": ["Product A", "Product B", "Product C", "Product D"],
|
||||
"y": [1200, 950, 800, 650],
|
||||
"marker": {"color": "#44BAB8"},
|
||||
"text": ["$1,200", "$950", "$800", "$650"],
|
||||
"textposition": "outside",
|
||||
"textfont": {"size": 11, "color": "black"}
|
||||
}],
|
||||
"layout": {
|
||||
"title": {
|
||||
"text": "Revenue by Product",
|
||||
"x": 0.5,
|
||||
"font": {"size": 18, "color": "#2E41A6"}
|
||||
},
|
||||
"height": 500,
|
||||
"showlegend": false,
|
||||
"xaxis": {
|
||||
"title": {"text": "Products", "font": {"size": 14, "color": "#2E41A6"}}
|
||||
},
|
||||
"yaxis": {
|
||||
"title": {"text": "Revenue ($)", "font": {"size": 14, "color": "#2E41A6"}}
|
||||
},
|
||||
"margin": {"t": 80, "b": 80, "l": 80, "r": 80},
|
||||
"font": {"family": "Arial", "size": 12},
|
||||
"plot_bgcolor": "white",
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
- Single series = no legend needed (`showlegend: false`)
|
||||
- Use primary TD color (#44BAB8)
|
||||
- Show formatted values on bars
|
||||
|
||||
---
|
||||
|
||||
### 4. Heatmaps - Numbers with 1 Decimal
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [{
|
||||
"type": "heatmap",
|
||||
"x": ["Channel A", "Channel B", "Channel C"],
|
||||
"y": ["Week 1", "Week 2", "Week 3"],
|
||||
"z": [
|
||||
[23.4, 45.6, 12.3],
|
||||
[34.5, 56.7, 23.1],
|
||||
[45.2, 67.8, 34.5]
|
||||
],
|
||||
"colorscale": [
|
||||
[0, "#DAF1F1"],
|
||||
[0.5, "#8FD6D4"],
|
||||
[1, "#44BAB8"]
|
||||
],
|
||||
"showscale": true,
|
||||
"colorbar": {
|
||||
"title": {"text": "Performance", "font": {"size": 12}},
|
||||
"titleside": "right"
|
||||
},
|
||||
"text": [
|
||||
[23.4, 45.6, 12.3],
|
||||
[34.5, 56.7, 23.1],
|
||||
[45.2, 67.8, 34.5]
|
||||
],
|
||||
"texttemplate": "%{text:.1f}",
|
||||
"textfont": {"size": 12, "color": "black"},
|
||||
"hovertemplate": "<b>%{y}</b> - <b>%{x}</b><br>Value: %{z:.1f}<extra></extra>"
|
||||
}],
|
||||
"layout": {
|
||||
"title": {
|
||||
"text": "Performance Heatmap",
|
||||
"x": 0.5,
|
||||
"font": {"size": 18, "color": "#2E41A6"}
|
||||
},
|
||||
"height": 500,
|
||||
"xaxis": {
|
||||
"title": {"text": "Channels", "font": {"size": 14, "color": "#2E41A6"}}
|
||||
},
|
||||
"yaxis": {
|
||||
"title": {"text": "Time Periods", "font": {"size": 14, "color": "#2E41A6"}}
|
||||
},
|
||||
"margin": {"t": 80, "b": 80, "l": 80, "r": 100},
|
||||
"font": {"family": "Arial", "size": 12},
|
||||
"plot_bgcolor": "white",
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
- Include `text` array matching `z` values
|
||||
- Use `texttemplate: "%{text:.1f}"` for 1 decimal formatting
|
||||
- Use TD color scale (light to dark)
|
||||
- Show color scale bar
|
||||
|
||||
---
|
||||
|
||||
### 5. Line Charts with Multiple Series
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"type": "scatter",
|
||||
"mode": "lines+markers",
|
||||
"x": ["Jan", "Feb", "Mar", "Apr"],
|
||||
"y": [10, 15, 20, 25],
|
||||
"name": "Channel A",
|
||||
"line": {"color": "#44BAB8", "width": 3},
|
||||
"marker": {"color": "#44BAB8", "size": 8}
|
||||
},
|
||||
{
|
||||
"type": "scatter",
|
||||
"mode": "lines+markers",
|
||||
"x": ["Jan", "Feb", "Mar", "Apr"],
|
||||
"y": [8, 12, 18, 22],
|
||||
"name": "Channel B",
|
||||
"line": {"color": "#8FD6D4", "width": 3},
|
||||
"marker": {"color": "#8FD6D4", "size": 8}
|
||||
}
|
||||
],
|
||||
"layout": {
|
||||
"title": {
|
||||
"text": "Performance Trends",
|
||||
"x": 0.5,
|
||||
"font": {"size": 18, "color": "#2E41A6"}
|
||||
},
|
||||
"height": 500,
|
||||
"showlegend": true,
|
||||
"legend": {
|
||||
"orientation": "h",
|
||||
"yanchor": "bottom",
|
||||
"y": 1.02,
|
||||
"xanchor": "center",
|
||||
"x": 0.5,
|
||||
"font": {"size": 12}
|
||||
},
|
||||
"xaxis": {
|
||||
"title": {"text": "Time Period", "font": {"size": 14, "color": "#2E41A6"}}
|
||||
},
|
||||
"yaxis": {
|
||||
"title": {"text": "Performance", "font": {"size": 14, "color": "#2E41A6"}}
|
||||
},
|
||||
"margin": {"t": 100, "b": 80, "l": 80, "r": 80},
|
||||
"font": {"family": "Arial", "size": 12},
|
||||
"plot_bgcolor": "white",
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
- Use `scatter` type with `mode: "lines+markers"`
|
||||
- Different colors for each series from TD palette
|
||||
- Horizontal legend above chart
|
||||
- Visible markers on data points
|
||||
|
||||
---
|
||||
|
||||
### 6. Sankey Diagrams
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [{
|
||||
"type": "sankey",
|
||||
"orientation": "h",
|
||||
"node": {
|
||||
"pad": 15,
|
||||
"thickness": 30,
|
||||
"line": {"color": "black", "width": 0.5},
|
||||
"label": ["Source A", "Source B", "Destination X", "Destination Y"],
|
||||
"color": ["#44BAB8", "#8FD6D4", "#2E41A6", "#828DCA"]
|
||||
},
|
||||
"link": {
|
||||
"source": [0, 1, 0, 1],
|
||||
"target": [2, 2, 3, 3],
|
||||
"value": [10, 20, 15, 25],
|
||||
"color": [
|
||||
"rgba(68, 186, 184, 0.4)",
|
||||
"rgba(143, 214, 212, 0.4)",
|
||||
"rgba(68, 186, 184, 0.4)",
|
||||
"rgba(143, 214, 212, 0.4)"
|
||||
]
|
||||
}
|
||||
}],
|
||||
"layout": {
|
||||
"title": {
|
||||
"text": "Customer Journey Flow",
|
||||
"x": 0.5,
|
||||
"font": {"size": 18, "color": "#2E41A6"}
|
||||
},
|
||||
"height": 600,
|
||||
"margin": {"t": 80, "b": 50, "l": 50, "r": 50},
|
||||
"font": {"family": "Arial", "size": 12},
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
- Node colors from TD palette
|
||||
- Semi-transparent link colors (0.4 opacity)
|
||||
- Clear node labels
|
||||
- Adequate height (600px) for visibility
|
||||
|
||||
---
|
||||
|
||||
## Legend Configuration Standards
|
||||
|
||||
### When to Show Legends
|
||||
|
||||
| Chart Type | Show Legend? | Position |
|
||||
|------------|--------------|----------|
|
||||
| **Pie Chart** | ✅ ALWAYS | Vertical, right side |
|
||||
| **Multi-Series Bar** | ✅ ALWAYS | Horizontal, top |
|
||||
| **Single Bar** | ❌ NEVER | N/A |
|
||||
| **Multi-Series Line** | ✅ ALWAYS | Horizontal, top |
|
||||
| **Single Line** | ❌ NEVER | N/A |
|
||||
| **Heatmap** | ❌ (Use colorbar) | N/A |
|
||||
| **Sankey** | ❌ (Labels in nodes) | N/A |
|
||||
|
||||
### Pie Charts - Vertical Legend (Right Side)
|
||||
|
||||
```json
|
||||
{
|
||||
"showlegend": true,
|
||||
"legend": {
|
||||
"orientation": "v",
|
||||
"yanchor": "middle",
|
||||
"y": 0.5,
|
||||
"xanchor": "left",
|
||||
"x": 1.02,
|
||||
"font": {"size": 12}
|
||||
},
|
||||
"margin": {"t": 80, "b": 80, "l": 80, "r": 150}
|
||||
}
|
||||
```
|
||||
|
||||
### Bar/Line Charts - Horizontal Legend (Top)
|
||||
|
||||
```json
|
||||
{
|
||||
"showlegend": true,
|
||||
"legend": {
|
||||
"orientation": "h",
|
||||
"yanchor": "bottom",
|
||||
"y": 1.05,
|
||||
"xanchor": "center",
|
||||
"x": 0.5,
|
||||
"font": {"size": 12}
|
||||
},
|
||||
"margin": {"t": 120, "b": 80, "l": 80, "r": 80}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Text and Number Formatting
|
||||
|
||||
### Percentage Display
|
||||
|
||||
```json
|
||||
// Option 1: Add % in template
|
||||
{
|
||||
"text": [45.2, 30.1, 24.7],
|
||||
"texttemplate": "%{text}%",
|
||||
"textposition": "outside",
|
||||
"textfont": {"size": 11, "color": "black"}
|
||||
}
|
||||
|
||||
// Option 2: Pre-formatted strings
|
||||
{
|
||||
"text": ["45.2%", "30.1%", "24.7%"],
|
||||
"textposition": "outside",
|
||||
"textfont": {"size": 11, "color": "black"}
|
||||
}
|
||||
```
|
||||
|
||||
### Currency Display
|
||||
|
||||
```json
|
||||
// Option 1: Format with template
|
||||
{
|
||||
"text": [1200000, 850000, 650000],
|
||||
"texttemplate": "$%{text:,.0f}",
|
||||
"textposition": "outside",
|
||||
"textfont": {"size": 11, "color": "black"}
|
||||
}
|
||||
|
||||
// Option 2: Pre-formatted strings
|
||||
{
|
||||
"text": ["$1.2M", "$850K", "$650K"],
|
||||
"textposition": "outside",
|
||||
"textfont": {"size": 11, "color": "black"}
|
||||
}
|
||||
```
|
||||
|
||||
### Heatmap Numbers (1 Decimal)
|
||||
|
||||
```json
|
||||
{
|
||||
"text": [[23.4, 45.6], [34.5, 56.7]],
|
||||
"texttemplate": "%{text:.1f}",
|
||||
"textfont": {"size": 12, "color": "black"},
|
||||
"hovertemplate": "Value: %{z:.1f}<extra></extra>"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## KPI Indicators (ONLY Use Case for Subplots)
|
||||
|
||||
KPI indicators are the **ONLY** exception where subplots are allowed. Use simple number indicators only.
|
||||
|
||||
### Simple Number Indicators (NO GAUGES)
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"type": "indicator",
|
||||
"mode": "number+delta",
|
||||
"value": 5240,
|
||||
"delta": {"reference": 4800, "suffix": " customers"},
|
||||
"title": {"text": "Total Customers", "font": {"size": 12, "color": "#2E41A6"}},
|
||||
"number": {"font": {"size": 32, "color": "#44BAB8"}},
|
||||
"domain": {"x": [0, 0.25], "y": [0, 1]}
|
||||
},
|
||||
{
|
||||
"type": "indicator",
|
||||
"mode": "number+delta",
|
||||
"value": 42.5,
|
||||
"delta": {"reference": 38.2, "suffix": "%"},
|
||||
"title": {"text": "Conversion Rate", "font": {"size": 12, "color": "#2E41A6"}},
|
||||
"number": {"prefix": "", "suffix": "%", "font": {"size": 32, "color": "#44BAB8"}},
|
||||
"domain": {"x": [0.25, 0.5], "y": [0, 1]}
|
||||
},
|
||||
{
|
||||
"type": "indicator",
|
||||
"mode": "number+delta",
|
||||
"value": 1250000,
|
||||
"delta": {"reference": 1100000, "valueformat": "$,.0f"},
|
||||
"title": {"text": "Total Revenue", "font": {"size": 12, "color": "#2E41A6"}},
|
||||
"number": {"prefix": "$", "valueformat": ",.0f", "font": {"size": 32, "color": "#44BAB8"}},
|
||||
"domain": {"x": [0.5, 0.75], "y": [0, 1]}
|
||||
},
|
||||
{
|
||||
"type": "indicator",
|
||||
"mode": "number+delta",
|
||||
"value": 25.3,
|
||||
"delta": {"reference": 22.1, "suffix": "%"},
|
||||
"title": {"text": "Champions %", "font": {"size": 12, "color": "#2E41A6"}},
|
||||
"number": {"suffix": "%", "font": {"size": 32, "color": "#44BAB8"}},
|
||||
"domain": {"x": [0.75, 1], "y": [0, 1]}
|
||||
}
|
||||
],
|
||||
"layout": {
|
||||
"height": 150,
|
||||
"margin": {"t": 20, "b": 20, "l": 20, "r": 20},
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Points for KPI Indicators:**
|
||||
- Maximum 4 indicators per row
|
||||
- **Number + Delta ONLY** - no gauges, no fancy visuals
|
||||
- Large number (32pt), clear title (12pt)
|
||||
- Show change vs. previous period
|
||||
- Clean, minimal design
|
||||
- Use domains to position: `[0, 0.25]`, `[0.25, 0.5]`, `[0.5, 0.75]`, `[0.75, 1]`
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before generating any visualization, verify:
|
||||
|
||||
### Required for Every Chart
|
||||
- [ ] Descriptive title with proper positioning (`"x": 0.5`)
|
||||
- [ ] Clear axis labels with appropriate font size (`"font": {"size": 14}`)
|
||||
- [ ] TD color palette used consistently
|
||||
- [ ] Proper height (500-600px based on chart type)
|
||||
- [ ] Adequate margins (minimum 80px, more for legends)
|
||||
- [ ] White background (`"plot_bgcolor": "white", "paper_bgcolor": "white"`)
|
||||
- [ ] Readable font size (12px minimum)
|
||||
- [ ] Legends visible for multi-category/multi-series charts
|
||||
- [ ] Numbers displayed on bars/heatmaps with proper formatting
|
||||
|
||||
### Legend Requirements
|
||||
- [ ] `"showlegend": true` for pie charts and comparisons
|
||||
- [ ] Proper orientation (vertical for pie, horizontal for others)
|
||||
- [ ] Adequate margin space for legend display
|
||||
- [ ] Readable font size for legend items
|
||||
- [ ] Legend positioned visibly (y > 1.0 for horizontal)
|
||||
|
||||
### Text Display Requirements
|
||||
- [ ] Values shown on bars with `"text"` and `"textposition"`
|
||||
- [ ] Heatmap values formatted to 1 decimal place
|
||||
- [ ] Hover templates with meaningful information
|
||||
- [ ] Consistent text formatting across similar chart types
|
||||
- [ ] Black text for visibility (`"textfont": {"color": "black"}`)
|
||||
|
||||
---
|
||||
|
||||
## Forbidden Patterns
|
||||
|
||||
### ❌ NEVER DO
|
||||
|
||||
1. **Subplots for analysis** (`yaxis2`, `xaxis2`, domain specifications)
|
||||
- Exception: KPI indicators only
|
||||
2. **String data format** (`"data": "[...]"`)
|
||||
3. **Missing legends** on pie charts or comparisons
|
||||
4. **Legend positioned below visible area** (e.g., `"y": -0.3`)
|
||||
5. **Missing `"text"` property on bar charts** - numbers won't show
|
||||
6. **Missing `"textposition"` on bar charts** - numbers won't be positioned
|
||||
7. **Missing `"texttemplate"` on heatmaps** - numbers won't be formatted
|
||||
8. **Missing `"showscale"` on heatmaps** - color scale won't appear
|
||||
9. **Insufficient top margin** for legends (`"t": 80` insufficient, use `"t": 120`)
|
||||
10. **Unformatted numbers** in heatmaps
|
||||
11. **Empty or generic titles**
|
||||
12. **Non-TD colors**
|
||||
13. **Gauges in KPI indicators** - use number+delta only
|
||||
|
||||
### ✅ ALWAYS DO
|
||||
|
||||
1. **Individual separate charts** for analysis
|
||||
2. **JSON array data format** (proper objects, not strings)
|
||||
3. **Visible legends**: `"y": 1.05` for horizontal, adequate margins
|
||||
4. **Numbers on bars**: `"text": [...]`, `"textposition": "outside"`
|
||||
5. **Numbers on heatmaps**: `"text": [...]`, `"texttemplate": "%{text:.1f}"`
|
||||
6. **Adequate margins**: `"t": 120` minimum for legends
|
||||
7. **Formatted numbers** with appropriate decimals
|
||||
8. **Descriptive titles** and axis labels
|
||||
9. **TD color palette** consistently
|
||||
10. **Black text color** for visibility: `"textfont": {"color": "black"}`
|
||||
11. **Simple KPI indicators** - number + delta only
|
||||
|
||||
---
|
||||
|
||||
## Complete Examples
|
||||
|
||||
### Example 1: Customer Segment Distribution (Pie Chart)
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [{
|
||||
"type": "pie",
|
||||
"values": [1250, 2100, 1500, 390],
|
||||
"labels": ["Champions", "Loyal Customers", "At Risk", "Lost"],
|
||||
"marker": {
|
||||
"colors": ["#44BAB8", "#8FD6D4", "#EEB53A", "#828DCA"]
|
||||
},
|
||||
"textinfo": "label+percent",
|
||||
"textposition": "auto",
|
||||
"textfont": {"size": 14, "color": "black"},
|
||||
"hovertemplate": "<b>%{label}</b><br>Customers: %{value}<br>Percentage: %{percent}<extra></extra>"
|
||||
}],
|
||||
"layout": {
|
||||
"title": {
|
||||
"text": "Customer Segment Distribution",
|
||||
"x": 0.5,
|
||||
"font": {"size": 18, "color": "#2E41A6"}
|
||||
},
|
||||
"height": 500,
|
||||
"showlegend": true,
|
||||
"legend": {
|
||||
"orientation": "v",
|
||||
"yanchor": "middle",
|
||||
"y": 0.5,
|
||||
"xanchor": "left",
|
||||
"x": 1.02,
|
||||
"font": {"size": 12}
|
||||
},
|
||||
"margin": {"t": 80, "b": 80, "l": 80, "r": 150},
|
||||
"font": {"family": "Arial", "size": 12},
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 2: Revenue by Channel (Multi-Series Bar)
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"type": "bar",
|
||||
"x": ["Email", "Social", "Search", "Display"],
|
||||
"y": [125000, 98000, 156000, 67000],
|
||||
"name": "Q3 2024",
|
||||
"marker": {"color": "#44BAB8"},
|
||||
"text": ["$125K", "$98K", "$156K", "$67K"],
|
||||
"textposition": "outside",
|
||||
"textfont": {"size": 11, "color": "black"}
|
||||
},
|
||||
{
|
||||
"type": "bar",
|
||||
"x": ["Email", "Social", "Search", "Display"],
|
||||
"y": [142000, 115000, 178000, 73000],
|
||||
"name": "Q4 2024",
|
||||
"marker": {"color": "#8FD6D4"},
|
||||
"text": ["$142K", "$115K", "$178K", "$73K"],
|
||||
"textposition": "outside",
|
||||
"textfont": {"size": 11, "color": "black"}
|
||||
}
|
||||
],
|
||||
"layout": {
|
||||
"title": {
|
||||
"text": "Revenue by Marketing Channel",
|
||||
"x": 0.5,
|
||||
"font": {"size": 18, "color": "#2E41A6"}
|
||||
},
|
||||
"height": 500,
|
||||
"barmode": "group",
|
||||
"showlegend": true,
|
||||
"legend": {
|
||||
"orientation": "h",
|
||||
"yanchor": "bottom",
|
||||
"y": 1.05,
|
||||
"xanchor": "center",
|
||||
"x": 0.5,
|
||||
"font": {"size": 12}
|
||||
},
|
||||
"xaxis": {
|
||||
"title": {"text": "Marketing Channels", "font": {"size": 14, "color": "#2E41A6"}}
|
||||
},
|
||||
"yaxis": {
|
||||
"title": {"text": "Revenue ($)", "font": {"size": 14, "color": "#2E41A6"}}
|
||||
},
|
||||
"margin": {"t": 120, "b": 80, "l": 80, "r": 80},
|
||||
"font": {"family": "Arial", "size": 12},
|
||||
"plot_bgcolor": "white",
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 3: Performance Heatmap
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [{
|
||||
"type": "heatmap",
|
||||
"x": ["Week 1", "Week 2", "Week 3", "Week 4"],
|
||||
"y": ["Email", "Social", "Search", "Display"],
|
||||
"z": [
|
||||
[85.3, 92.1, 88.7, 94.2],
|
||||
[72.5, 78.3, 81.2, 76.8],
|
||||
[91.4, 89.6, 93.8, 95.1],
|
||||
[68.2, 71.5, 69.9, 73.4]
|
||||
],
|
||||
"colorscale": [
|
||||
[0, "#DAF1F1"],
|
||||
[0.5, "#8FD6D4"],
|
||||
[1, "#44BAB8"]
|
||||
],
|
||||
"showscale": true,
|
||||
"colorbar": {
|
||||
"title": {"text": "Performance %", "font": {"size": 12}},
|
||||
"titleside": "right"
|
||||
},
|
||||
"text": [
|
||||
[85.3, 92.1, 88.7, 94.2],
|
||||
[72.5, 78.3, 81.2, 76.8],
|
||||
[91.4, 89.6, 93.8, 95.1],
|
||||
[68.2, 71.5, 69.9, 73.4]
|
||||
],
|
||||
"texttemplate": "%{text:.1f}",
|
||||
"textfont": {"size": 12, "color": "black"},
|
||||
"hovertemplate": "<b>%{y}</b> - <b>%{x}</b><br>Performance: %{z:.1f}%<extra></extra>"
|
||||
}],
|
||||
"layout": {
|
||||
"title": {
|
||||
"text": "Weekly Channel Performance",
|
||||
"x": 0.5,
|
||||
"font": {"size": 18, "color": "#2E41A6"}
|
||||
},
|
||||
"height": 500,
|
||||
"xaxis": {
|
||||
"title": {"text": "Week", "font": {"size": 14, "color": "#2E41A6"}}
|
||||
},
|
||||
"yaxis": {
|
||||
"title": {"text": "Channel", "font": {"size": 14, "color": "#2E41A6"}}
|
||||
},
|
||||
"margin": {"t": 80, "b": 80, "l": 100, "r": 100},
|
||||
"font": {"family": "Arial", "size": 12},
|
||||
"plot_bgcolor": "white",
|
||||
"paper_bgcolor": "white"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Your visualization is ready when:
|
||||
|
||||
✅ Executives can instantly understand the key message
|
||||
✅ All text is readable at standard screen sizes
|
||||
✅ Colors are consistent with TD branding
|
||||
✅ Legends are visible and descriptive (where needed)
|
||||
✅ Numbers are formatted appropriately
|
||||
✅ Chart tells a clear story
|
||||
✅ JSON structure is valid (not stringified)
|
||||
✅ No subplots for analysis charts
|
||||
✅ Clean, professional, executive-ready appearance
|
||||
|
||||
---
|
||||
|
||||
By following these guidelines, your Field Agent visualizations will be professional, consistent, and immediately actionable for decision-makers.
|
||||
Reference in New Issue
Block a user