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:

## 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

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:

- [ ] 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:

## 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:

#!/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

# [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

# [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:

## 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

# 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:

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

## 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

## 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