This guide shows you how to synchronize your agents between local development and Writer Cloud environments. This allows local development offline and cloud development and deployment when you wish to share your agent with your team.
To avoid conflicts, work in one environment at a time, then explicitly sync your changes to the other environment when ready. This ensures your changes are properly tracked and preserved across environments.

​
Overview

There are two main synchronization workflows:
  1. Cloud to local: Start with a cloud agent and bring it to local development
  2. Local to cloud: Start locally and push to the cloud
Both workflows involve downloading an agent’s configuration from one environment and importing it into another. Before starting, ensure you have:

​
Cloud to local workflow

If you’ve already created an agent in the AI Studio Agent Builder web editor and want to continue development locally:

​
Step 1: Export from cloud

From your cloud agent in Agent Builder, click the three dots in the top right corner of your agent and select Download agent .zip file to download a .zip file containing your agent’s configuration.

​
Step 2: Create local project

Create a new local project with Writer Framework and import the cloud agent by unzipping the export file you downloaded: 
# Create a new local project
writer create my-cloud-agent
cd my-cloud-agent

​
Step 3: Import the cloud agent into your local project

Import the cloud agent by unzipping the export file you downloaded into your local project: 
# The export file contains all your agent's configuration from the web editor
unzip your-agent-export.zip
Because the export file contains all your agent’s configuration, the terminal asks you to confirm file-by-file whether you’d like to overwrite your local project’s files. Type A to replace all files in your local project with the exported agent. You can also choose the following options:
  • y to replace an individual file
  • r to rename an individual file
  • N to cancel the import and not replace any files
my-agent unzip ~/Downloads/export.zip
Archive:  /Users/Downloads/export.zip
  inflating: README.md
replace main.py? [y]es, [n]o, [A]ll, [N]one, [r]ename: A

​
Step 4: Set up environment variables

Set up a .env file in your local project directory and add your Writer API key: 
# .env
export WRITER_API_KEY="[your_api_key]"
Run the following command to activate the environment variables: 
source .env

​
Step 5: Start local development

Start the local development server: 
writer edit .
Your local environment now contains an exact copy of your cloud agent, and you can continue development locally.

​
Local to cloud workflow

To start development locally and then push to the cloud development environment, follow these steps:

​
Step 1: Create local project

Start with a local project: 
writer create my-local-agent
cd my-local-agent
writer edit .

​
Step 2: Develop locally

Build your agent locally using the Writer Framework development environment. You have full access to:
  • Python code editing
  • UI component configuration
  • Blueprint design
  • Local testing and debugging

​
Step 3: Prepare for cloud sync

Before syncing to the cloud, ensure your code handles both Vault and environment variables as described in the handle environment variables and secrets section.
Remove or move your .env file before syncing to prevent it from showing in the cloud editor.

​
Step 4: Download the local agent’s export file

When you’re ready to sync your local agent to the cloud, download the local agent’s export file from the web editor. In the visual editor interface, click the three dots in the top right corner of your agent and select Download agent .zip file to download a .zip file containing your agent’s configuration.
All files in your local project are included in the export file. Do not include sensitive information in the exported file as it will be visible in the cloud editor.

​
Step 5: Import the local agent into your cloud project

Open the Agent Builder web editor in AI Studio and click the three dots in the top right corner of your agent. Then select Import agent .zip file to upload the local agent’s export file. A modal appears and asks you to confirm that you are overwriting your existing agent. Check the box to acknowledge that you’re replacing your existing agent and click Import to continue.

​
Deploy your agent

After syncing your agent to the cloud, deploy it following the standard cloud workflow. From the agent editor interface in Agent Builder, click Configure deployment in the top right corner of the Agent Builder interface. You can also access the deployment configuration by going to the AI Studio homepage and selecting the agent you created. If the agent isn’t deployed, you see a toggle bar that says Draft. To deploy the agent, toggle the bar. Writer deploys the agent to the Writer cloud, which takes a moment to complete. When you deploy the agent, the toggle bar shows Deployed. It also shows a list of the teams in your organization, which you can use to grant access to the agent. You must select at least one team before you can view the URL for the deployed agent.

​
Considerations for dual-environment development

  • Local-only libraries: If you install Python packages locally that aren’t listed in Python libraries installed in Agent Builder, your agent won’t run in the cloud version of Agent Builder because those packages aren’t available there.
  • Environment file visibility: Your .env file is visible in plain text in the cloud editor when you sync your local project. Any file you add to your local project is included in the export file to the cloud. Before syncing, move your .env file to a different location or delete it to prevent it from showing in the cloud editor, and add your secrets to Vault.
  • Vault availability: Vault is only available in the cloud version of Agent Builder. For local development, you must use environment variables. Structure your code to handle both scenarios gracefully.
  • Keep your local Writer Framework package up to date: When you sync your agent to the cloud, the cloud version of Agent Builder uses the latest version of the Writer Framework package. If you’re using a different version of the Writer Framework package in your local project, you might encounter errors when you sync to the cloud. To avoid this, keep your local Writer Framework package up to date by running the following command: 
pip install --upgrade writer

​
Handle environment variables and secrets

The following code shows an example of how to look for secrets in Vault first, then fall back to environment variables: 
import os

def get_secret(key, default=None):
    """Get a secret from Vault if available, otherwise from environment variables"""
    try:
        # Try to get from Vault first (cloud environment). The `vault` object is available in Python code blocks and in event handlers.
        return vault[key]
    except KeyError:
        # Fall back to environment variables (local development)
        return os.getenv(key, default)

# Usage example
api_key = get_secret("WRITER_API_KEY", "default_key")
database_url = get_secret("DATABASE_URL")

​
Next steps