How to Build an Agent with Multiple Shell Environments

In this tutorial you will build an AI agent that has access to multiple isolated shell environments. Instead of giving the agent a single bash ability, you will create separate skillsets, each with their own shell abilities bound to a dedicated space. The agent dynamically loads whichever skillset it needs using the Install Skillset ability, giving it access to completely independent sandboxes.

This pattern is useful whenever the agent needs to keep work separated across contexts, for example when working across development and staging environments, managing multiple projects, or running comparative tests in isolated sandboxes.

Prerequisites

• A ChatBotKit account
• Basic familiarity with the Blueprint Designer (see Creating an AI Agent That Can Interact with Shells and Construct Its Own Tools for an introduction)

Why Multiple Environments?

When an agent uses a single shell/exec ability, all commands run in the same sandbox. Environment variables, installed packages, files, and running processes are all shared. This is fine for simple tasks, but it becomes a problem when you need isolation:

• Commands in one environment can accidentally affect another
• There is no way to tell which environment produced which output
• State leaks between contexts make debugging difficult

The solution is to give each environment its own skillset with its own space. Because the shell session is tied to the skillset's space, each environment gets a completely independent sandbox.

How It Works

The architecture uses three types of resources:

1. A Core Skillset attached to the bot. It contains two meta-abilities:

   • List Environments - discovers all available environment skillsets in the blueprint
   • Install Environment - dynamically loads a skillset into the current conversation

2. Environment Skillsets (one per environment). Each contains:

   • A shell/exec ability bound to a dedicated space
   • A shell/rw ability bound to the same space

3. Spaces (one per environment). Each space provides an isolated sandbox with its own file system.

The agent starts with only the Core Skillset. It lists available environments, installs the one it needs, and gains access to that environment's shell. It can install multiple environments in the same conversation and switch between them freely.

Here is the complete blueprint that you will build in this tutorial:

Step 1: Create a Blueprint

1. In ChatBotKit, create a new blueprint.
2. Click Design to open the Blueprint Designer.
3. Choose the Blank option to start with a bot and an empty skillset.

This empty skillset becomes your Core Skillset.

Step 2: Add the Core Meta-Abilities

The Core Skillset needs two abilities that let the agent discover and load environments.

1. Open the Core Skillset in the Blueprint Designer.
2. Add the List Blueprint Resources ability (blueprint/resource/list). Set the type parameter to skillset. Name it "List Environments" and give it a description such as "Discovers all available environment skillsets. Returns the id, name, and description of each environment."
3. Add the Install Skillset ability (conversation/skillset/install[by-id]). Name it "Install Environment" and give it a description such as "Dynamically installs an environment skillset by id, giving access to that environment's shell and file abilities."

These two abilities are all the bot needs to start with. Everything else is loaded dynamically.

Step 3: Create the First Environment Skillset

1. In the Blueprint Designer, add a new Skillset resource. Name it "Development" and set its description to "Shell execution and file access in the isolated Development environment".
2. Add a new Space resource. Name it "Development Workspace" and set its description to "Isolated sandbox for the Development environment".
3. Inside the Development skillset, add two abilities:
   • bash - use the shell/exec template with no additional parameters. Link it to the Development Workspace space.
   • rw - use the shell/rw template with no additional parameters. Link it to the same Development Workspace space.

The Development skillset is not connected to the bot directly. The agent will load it dynamically using the Install Environment ability from the Core Skillset.

Step 4: Create the Second Environment Skillset

Repeat the same steps to create a second environment:

1. Add another Skillset resource. Name it "Staging" with description "Shell execution and file access in the isolated Staging environment".
2. Add another Space resource. Name it "Staging Workspace" with description "Isolated sandbox for the Staging environment".
3. Inside the Staging skillset, add the same two abilities:
   • bash - shell/exec template, linked to the Staging Workspace space.
   • rw - shell/rw template, linked to the Staging Workspace space.

You now have two independent environments. Each has its own skillset and its own space, so commands in one environment cannot affect the other.

Tip: You can add as many environments as you need. The pattern scales to any number of isolated sandboxes, for example Development, Staging, and Production.

Step 5: Write the Bot Backstory

Give the bot a backstory that explains how to work with multiple environments. Here is an example:

Step 6: Test the Solution

1. Open the Chat interface from your blueprint to start a conversation.
2. Ask the agent to list available environments. It should call "List Environments" and return the Development and Staging skillsets.
3. Ask the agent to install the Development environment. It should call "Install Environment" with the Development skillset id.
4. Run a command in Development, for example echo "hello from dev" > /tmp/test.txt && cat /tmp/test.txt.
5. Ask the agent to install the Staging environment.
6. Run the same command in Staging: cat /tmp/test.txt. The file should not exist because Staging has a completely separate sandbox.

Example conversation:

• You: "List the available environments."
• Agent: "I found two environments: Development and Staging."
• You: "Install the Development environment."
• Agent: "Done. I now have access to the Development shell."
• You: "Write 'hello from dev' to /tmp/test.txt, then read it back."
• Agent: Executes the command in the Development sandbox and returns the content.
• You: "Now install Staging and try to read /tmp/test.txt there."
• Agent: Installs Staging and reports that the file does not exist, confirming isolation.

Use Cases

• Dev/staging/production workflows - test a script in development, verify in staging, and execute in production, all in the same conversation.
• Multi-project workspaces - give each project its own isolated environment with separate dependencies and configuration.
• Comparative testing - run the same script in two environments and compare outputs to detect environment-specific issues.
• Isolated experimentation - try something risky in one sandbox without affecting others.
• CI/CD simulation - model a build pipeline where the agent runs tests in one environment, then deploys artifacts to another.

Troubleshooting

The agent only sees the Core Skillset abilities

• Make sure the environment skillsets are added to the blueprint but are not connected directly to the bot. They should be standalone skillsets discovered through the "List Environments" ability.

"Install Environment" does not add new abilities

• Verify that the environment skillsets contain shell/exec and shell/rw abilities. Without abilities, installing the skillset has no visible effect.

Files persist across environments

• Confirm that each environment skillset's abilities are linked to a different space. If two skillsets share the same space, their sandboxes are not isolated.

Commands run in the wrong environment

• After installing multiple environments, the agent may have access to multiple "bash" abilities. Write the backstory to instruct the agent to always confirm the target environment before executing commands.

Conclusion

By creating separate skillsets with dedicated spaces and using the Install Skillset ability for dynamic loading, you can give a single agent access to multiple fully isolated shell environments. The agent discovers environments at runtime, loads only what it needs, and switches between sandboxes freely, all within the same conversation. This pattern works for any number of environments and is a building block for more advanced multi-environment workflows.

You can also get started quickly by deploying the Multi-environment Agent example blueprint, which includes a pre-configured setup with Development, Staging, and Production environments.