Migration Guide

Migrate to SystemPrompt from other platforms or upgrade between versions

On this page

This guide covers migrating to SystemPrompt from other platforms and upgrading between versions.

Upgrading SystemPrompt

Check Current Version

systemprompt --version

Update CLI

# From crates.io
cargo install systemprompt-cli --force

# From source
git pull
cargo build --release -p systemprompt-cli

Update Core (for projects using submodule)

cd core
git fetch origin
git checkout v0.0.14  # or desired version
cd ..
cargo build

Run Migrations

After upgrading, always run migrations:

systemprompt infra db migrate

Version Compatibility

Breaking Changes

Major version changes (0.x to 1.0, 1.x to 2.0) may include breaking changes:

Version Breaking Changes
0.0.14 Template variable naming
0.0.13 MCP transport updates
0.0.12 OAuth scope format

Database Migrations

Migrations are forward-only. To rollback:

  1. Restore from backup
  2. Downgrade crates
  3. Rebuild
# Backup before upgrade
systemprompt infra db backup --output backup.sql

# Restore if needed
systemprompt infra db restore --input backup.sql

Migrating from Other Platforms

From LangChain/LangGraph

SystemPrompt provides similar agent orchestration with production features:

LangChain SystemPrompt
Agent Agent (A2A protocol)
Tool MCP Tool
Chain Agent workflow
Memory Database state

Migration steps:

  1. Define agents in services/agents/
  2. Convert tools to MCP servers
  3. Implement prompts as system prompts
  4. Use database for state management

From AutoGen

AutoGen SystemPrompt
AssistantAgent Agent
UserProxyAgent CLI interface
GroupChat Multi-agent A2A

From Custom Implementations

If migrating from a custom agent implementation:

  1. Authentication - Map to OAuth2/WebAuthn
  2. Tools - Convert to MCP format
  3. State - Migrate to PostgreSQL
  4. Config - Convert to YAML in services/

Data Migration

Export Existing Data

# Export to JSON
systemprompt admin export --format json --output data.json

# Export specific tables
systemprompt infra db query "SELECT * FROM users" --format csv > users.csv

Import Data

# Import from JSON
systemprompt admin import --input data.json

# Import SQL
psql -h localhost -U systemprompt -d systemprompt < data.sql

Content Migration

For content migration from other CMS:

  1. Export to Markdown with frontmatter
  2. Place in services/content/
  3. Sync to database:
systemprompt cloud sync local content --direction to-db -y

Configuration Migration

Environment Variables to Profiles

Convert environment variables to profile configuration:

# Old: environment variables
export DATABASE_URL="postgres://..."
export API_KEY="sk-..."

# New: profile configuration
systemprompt cloud profile create production
systemprompt admin config set-secret database.password "..."
systemprompt admin config set-secret anthropic.api_key "sk-..."

Docker Compose Updates

Update Docker Compose for new versions:

# docker-compose.yml
services:
  systemprompt:
    image: systemprompt/systemprompt:0.0.14  # Update version
    environment:
      - SYSTEMPROMPT_PROFILE=production
    volumes:
      - ./services:/app/services

Testing Migration

Pre-Migration Checklist

  • Backup database
  • Document current configuration
  • Test in staging environment
  • Verify all agents function
  • Check MCP server connectivity

Post-Migration Verification

# Verify services
systemprompt infra services status

# Test agents
systemprompt admin agents list
systemprompt admin agents message <agent> "test"

# Verify MCP servers
curl http://localhost:3000/api/v1/mcp/registry

# Check content
systemprompt core content list

Rollback Procedure

If migration fails:

  1. Stop services: systemprompt infra services stop --all
  2. Restore database backup
  3. Revert code changes
  4. Restart with previous version

Getting Help