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
|
||||
Reference in New Issue
Block a user