Agent portability lets you export any agent, along with its skills, tools, and prompts, as a portable “package”, and then import it into another tenant or environment. Whether you’re promoting a configuration from staging to production or replicating a working agent across business units, the agent and its building blocks move together in a few clicks.
With agent portability, you can:
- Clone an agent, skill, tool, or prompt from one tenant to another within the same environment
- Download and upload an agent, skill, tool, or prompt to migrate it between environments
- Replicate proven agents across business units or teams
In the steps below, you will learn how to use both the Clone option and the Download + Upload option to move agents (together with their associated skills, tools, and prompts) between tenants and environments.
Before you begin, make sure you are logged in and that your account has the necessary permissions to access the Agent builder and to perform export/import actions.
When to use Clone vs. Download + Upload
Both options move an agent together with its skills, models, and tools, but they target different scenarios:
- Use Clone when copying an agent, skill, or tool from one tenant to another within the same environment (for example, between two tenants on the same instance).
- Use Download + Upload when migrating an agent, skill, or tool between different environments (for example, from a staging environment to a production environment).
What is included in the package
Both Clone and Download + Upload move the agent together with its internal building blocks. The same rules apply to both options.
Included in the package:
- The agent itself
- All skills that belong to the agent
- All tools used by those skills
- All prompts used by the agent and its skills
When you clone or upload a skill on its own, all tools that belong to that skill are moved together with it.
Not included in the package:
- Credentials (for example, API keys, tokens, or any secrets configured on the source tenant or environment)
- Knowledge base documents associated with the agent
After the resource is created in the target tenant or environment, credentials and knowledge base documents must be (re)configured there. For the knowledge base, this means uploading the required documents in the target tenant and refreshing the knowledge so that the agent can use them.
How name conflicts are handled
Both Clone and Download + Upload check whether the resources being moved (agents, skills, tools, prompts) already exist on the target tenant. The behavior depends on whether the content behind each matching name is identical or different.
Case 1: A resource with the same name already exists and its content is identical
The operation is completed end to end. Resources that already exist on the target tenant in exactly the same form are reported as skipped, while the missing ones are created. The end result is that the target tenant contains the agent (and all its building blocks) in the desired form.
Success is defined by the final state of the target tenant: if the target contains the agent, skills, tools, and prompts you wanted, the operation is considered successful, regardless of whether each individual resource was newly created or already existed.
Case 2: A resource with the same name already exists but its content differs
The operation is rejected with a 409 Conflict response and nothing is cloned or uploaded. The platform does not overwrite an existing resource on the target tenant, because that resource may be intentionally kept in its current form by another team or workflow.
To proceed in this case, either rename the conflicting resource on the source or on the target tenant, or align the content so that the two versions match before retrying the operation.
Option 1: Clone an agent, skill, tool, or prompt between tenants
Use the Clone option to copy an agent, skill, tool, or prompt from one tenant to another within the same environment. When you clone an agent, all of its skills, tools, and prompts are cloned together with it. When you clone a skill, all of its tools are cloned together with it.
Step 1: Open the resource you want to clone
Navigate to the Agents section (or to the Skills, Tools, or Prompts section, depending on the resource you want to copy) and locate the resource in the list.
Step 2: Trigger the Clone action
Open the Actions menu next to the resource and select Clone. A dialog will appear, asking you to choose the destination tenant.
Step 3: Select the target tenant
Choose the tenant to which the resource should be cloned and confirm the action. The agent (or skill, tool, or prompt) and all of its internal dependencies will be created in the target tenant. Any matching resources that already exist on the target tenant in identical form will be reported as skipped rather than created.
Step 4: Validate the clone
Open the resource in the target tenant and verify that all expected skills, tools, and prompts are present. Because credentials and knowledge base documents are not part of the package, configure these separately on the target tenant – for example, set up credentials for any external systems the tools rely on, and upload the required documents to the knowledge base (and refresh the knowledge) so that the agent has the context it needs.
Important notes
- The Clone option works only within the same environment. To copy resources between different environments, use the Download + Upload option described below.
- Only agents, skills, tools, and prompts are part of the cloned package. Credentials and knowledge base documents are not copied and must be configured on the target tenant after cloning.
- Cloning an agent automatically includes all of its skills, tools, and prompts. Cloning a skill automatically includes all of its tools.
- If resources with the same name already exist on the target tenant and their content is identical, the operation completes successfully and those resources are marked as skipped. If a resource with the same name exists but its content differs, the operation fails with a 409 Conflict and nothing is cloned.
- Cloning creates a copy of the resource as it currently exists. Later changes made to the source are not automatically propagated to the cloned resource.
Option 2: Download and upload an agent, skill, tool, or prompt between environments
Use the Download + Upload option to migrate an agent, skill, tool, or prompt from one environment to another. This option exports the resource as a portable package file (containing the agent together with its skills, tools, and prompts) that can be uploaded into any compatible environment.
Step 1: Download the resource from the source environment
In the source environment, navigate to the Agents section (or to the Skills, Tools, or Prompts section, depending on the resource type) and locate the resource. Open the Actions menu and select Download. A portable package file containing the resource together with all of its internal dependencies (skills, tools, and prompts) will be generated and saved to your computer.
Step 2: Switch to the target environment
Log in to the target environment (for example, the production workspace if you are promoting from staging). Make sure your account in the target environment has permissions to upload agents, skills, tools, and prompts.
Step 3: Upload the package
Navigate to the Agents section (or to the Skills, Tools, or Prompts section, depending on the resource type) and click Upload. Select the package file you downloaded in Step 1 and confirm the action. As with cloning, any matching resources that already exist in identical form on the target are reported as skipped, while everything else is created.
Step 4: Review and validate in the target environment
After the upload completes, open the imported resource and verify that all expected skills, tools, and prompts are present. Configure credentials for any external systems the tools rely on, and upload the relevant documents to the knowledge base (then refresh the knowledge) – credentials and knowledge base documents are not part of the package and must be set up separately in the target environment.
Important notes
- Use Download + Upload when moving resources between different environments – for example, from staging to production, or between independent deployments.
- Only agents, skills, tools, and prompts are part of the package. Credentials and knowledge base documents are not migrated and must be configured in the target environment after upload.
- Downloading an agent automatically includes all of its skills, tools, and prompts. Downloading a skill automatically includes all of its tools.
- Name conflicts are handled the same way as with Clone: if a resource with the same name already exists and its content is identical, the upload completes and that resource is reported as skipped; if a resource with the same name exists but its content differs, the upload fails with a 409 Conflict and nothing is created.
- If the source and target environments use different versions of the platform, ensure that the target environment supports all features used by the imported resource.
Common use cases
- Promote a tested agent configuration from a staging environment to production.
- Replicate a working agent across multiple business units or tenants.
- Create a backup of an agent and its dependencies before making significant changes.
- Share reusable agent templates between teams or projects.
Comments
0 comments
Please sign in to leave a comment.