Execute Code Fallback

Execute Code Fallback Pattern

When execute_code_sandbox fails due to e2b unavailability, immediately fall back to run_shell with embedded Python code. This ensures task continuity when the sandbox service is down.

When to Apply

Use this pattern when you observe:

• execute_code_sandbox returns errors mentioning "e2b", "sandbox unavailable", or connection timeouts
• Repeated sandbox execution failures (2+ attempts)
• Error messages indicating the code execution environment is unreachable

Fallback Procedure

Step 1: Detect the Failure

Identify that execute_code_sandbox has failed. Common error indicators:

• "e2b service unavailable"
• "Sandbox connection failed"
• "Execution environment not reachable"
• Timeout errors during code execution

Step 2: Switch to run_shell with Embedded Python

Instead of:

execute_code_sandbox(code="...")

Use:

run_shell(command="python3 -c '...your Python code...'")

Step 3: Install Dependencies First (If Needed)

If your Python code requires external packages, install them first:

run_shell(command="pip install pandas requests matplotlib")

Then execute your main code:

run_shell(command="python3 << 'EOF'
import pandas as pd
import requests

# Your code here
print("Success")
EOF
")

Step 4: Use Heredoc for Multi-line Code

For complex Python scripts, use heredoc syntax for cleaner code:

run_shell(command="python3 << 'PYTHON_SCRIPT'
import json
import os

# Complex logic here
data = {'key': 'value'}
with open('output.json', 'w') as f:
    json.dump(data, f)

print('File created successfully')
PYTHON_SCRIPT
")

Complete Example

Scenario: You need to process a CSV file and generate a report.

Original approach (sandbox):

execute_code_sandbox(code="""
import pandas as pd
df = pd.read_csv('data.csv')
summary = df.describe()
print(summary)
""")

Fallback approach (run_shell):

# First install dependencies if needed
run_shell(command="pip install pandas --quiet")

# Then execute the code
run_shell(command="python3 << 'EOF'
import pandas as pd
df = pd.read_csv('data.csv')
summary = df.describe()
print(summary)
EOF
")

Important Considerations

1. State Persistence: Unlike execute_code_sandbox, run_shell executions may not share state between calls. Save intermediate results to files if needed.

1. Working Directory: Ensure you're operating in the correct directory. Use pwd to verify or include cd /path/to/workdir in your commands.

1. Python Version: Use python3 explicitly to avoid ambiguity. Verify with python3 --version if needed.

1. Error Handling: Check the stdout/stderr from run_shell to confirm success. Failed Python scripts will return non-zero exit codes.

1. Security: Be cautious when embedding user-provided data into shell commands. Escape appropriately or use file-based input.

1. Performance: For large computations, run_shell may be slower than sandbox. Consider breaking into smaller steps if timeouts occur.

Quick Reference

| Task | Sandbox Approach | Fallback Approach | |------|-----------------|-------------------| | Simple calculation | execute_code_sandbox(code="print(2+2)") | run_shell(command="python3 -c 'print(2+2)'") | | Install + run | execute_code_sandbox(code="import pkg; ...") | run_shell(command="pip install pkg && python3 -c '...'") | | Multi-line script | execute_code_sandbox(code="...") | run_shell(command="python3 << 'EOF'...EOF") | | File I/O | execute_code_sandbox(code="...") | run_shell(command="python3 << 'EOF'...EOF") |

Recovery Checklist

• [ ] Confirm execute_code_sandbox failure (not a code bug)
• [ ] Switch to run_shell immediately
• [ ] Install required packages with pip install
• [ ] Use heredoc for multi-line Python
• [ ] Verify output and handle errors
• [ ] Save intermediate results to files if multi-step

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HKUDS
• Source: HKUDS/OpenSpace
• License: MIT

Install and usage instructions live in the source repository linked above.