feat(examples): add tool usage examples for bash, edit, ckg and json …

examples/tools/bash_example.py

@@ -0,0 +1,59 @@
+import asyncio
+from pathlib import Path
+import sys
+
+# Add project root to Python path to import trae_agent module
+project_root = Path(__file__).resolve().parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+from trae_agent.tools.bash_tool import BashTool
+from trae_agent.tools.base import ToolCallArguments
+
+
+async def main():
+    """
+    An example of how to use the BashTool to execute shell commands.
+    """
+    tool = BashTool()
+
+    # 1. Execute a simple echo command
+    echo_command = 'echo "Hello from BashTool!"'
+    print(f"--- 1. Executing command: '{echo_command}' ---")
+    echo_args = ToolCallArguments(command=echo_command)
+    echo_result = await tool.execute(echo_args)
+
+    if echo_result.error:
+        print(f"Error: {echo_result.error}")
+    else:
+        print("--- Output ---")
+        print(echo_result.output)
+    print("-" * 20)
+
+    # 2. Execute a command to list files
+    ls_command = "ls -la"
+    print(f"--- 2. Executing command: '{ls_command}' ---")
+    ls_args = ToolCallArguments(command=ls_command)
+    ls_result = await tool.execute(ls_args)
+
+    if ls_result.error:
+        print(f"Error: {ls_result.error}")
+    else:
+        print("--- Output ---")
+        print(ls_result.output)
+    print("-" * 20)
+
+    # 3. Execute a command that fails
+    error_command = "cat non_existent_file.txt"
+    print(f"--- 3. Executing a failing command: '{error_command}' ---")
+    error_args = ToolCallArguments(command=error_command)
+    error_result = await tool.execute(error_args)
+
+    # The BashTool is designed to pipe stderr to stdout, so errors appear in the output
+    if error_result.output:
+        print("--- Output (contains error) ---")
+        print(error_result.output)
+    print("-" * 20)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/tools/ckg_tool_example.py

@@ -0,0 +1,86 @@
+import asyncio
+from pathlib import Path
+import sys
+
+# Add project root to Python path to import trae_agent module
+project_root = Path(__file__).resolve().parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+from trae_agent.tools.ckg_tool import CKGTool
+from trae_agent.tools.base import ToolCallArguments
+
+
+async def main():
+    """
+    An example of how to use the CKGTool to query the codebase.
+    """
+    tool = CKGTool()
+    codebase_path = str(project_root)
+
+    print(
+        f"--- CKG Tool Example ---"
+        f"\nThis script will query the codebase at '{codebase_path}'."
+        f"\nNote: The first run might be slow as it needs to build the code knowledge graph."
+    )
+    print("-" * 20)
+
+    # 1. Search for a function
+    print("--- 1. Searching for function: 'run' ---")
+    search_func_args = ToolCallArguments(
+        command="search_function",
+        path=codebase_path,
+        identifier="run",
+    )
+    search_func_result = await tool.execute(search_func_args)
+    if search_func_result.error:
+        print(f"Error: {search_func_result.error}")
+    else:
+        print(search_func_result.output)
+    print("-" * 20)
+
+    # 2. Search for a class
+    print("--- 2. Searching for class: 'BashTool' ---")
+    search_class_args = ToolCallArguments(
+        command="search_class",
+        path=codebase_path,
+        identifier="BashTool",
+    )
+    search_class_result = await tool.execute(search_class_args)
+    if search_class_result.error:
+        print(f"Error: {search_class_result.error}")
+    else:
+        print(search_class_result.output)
+    print("-" * 20)
+
+    # 3. Search for a class method
+    print("--- 3. Searching for class method: 'execute' ---")
+    search_method_args = ToolCallArguments(
+        command="search_class_method",
+        path=codebase_path,
+        identifier="execute",
+        print_body=False,  # Disable printing body to keep output clean
+    )
+    search_method_result = await tool.execute(search_method_args)
+    if search_method_result.error:
+        print(f"Error: {search_method_result.error}")
+    else:
+        print(search_method_result.output)
+    print("-" * 20)
+
+    # 4. Search for an identifier that does not exist
+    print("--- 4. Searching for non-existent function: 'non_existent_function' ---")
+    search_non_existent_args = ToolCallArguments(
+        command="search_function",
+        path=codebase_path,
+        identifier="non_existent_function",
+    )
+    search_non_existent_result = await tool.execute(search_non_existent_args)
+    if search_non_existent_result.error:
+        print(f"Error: {search_non_existent_result.error}")
+    else:
+        print(search_non_existent_result.output)
+    print("-" * 20)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/tools/edit_tool_example.py

@@ -0,0 +1,85 @@
+import asyncio
+import os
+from pathlib import Path
+
+# Since the script is in examples, we need to add the project root to the python path
+# to import the trae_agent module.
+import sys
+
+# Add the project root to the Python path
+project_root = Path(__file__).parent.parent
+sys.path.insert(0, str(project_root))
+
+from trae_agent.tools.edit_tool import TextEditorTool
+from trae_agent.tools.base import ToolCallArguments
+
+
+async def main():
+    """
+    An example of how to use the TextEditorTool to perform file operations.
+    """
+    tool = TextEditorTool()
+    test_file_path = Path(__file__).parent / "test_file.txt"
+    test_file_path_str = str(test_file_path.absolute())
+
+    # 1. Create a file
+    print("--- 1. Testing 'create' command ---")
+    create_args = ToolCallArguments(
+        command="create",
+        path=test_file_path_str,
+        file_text="Hello, world!\nThis is a test file.\n",
+    )
+    create_result = await tool.execute(create_args)
+    print(create_result.output)
+    print("-" * 20)
+
+    # 2. View the file
+    print("--- 2. Testing 'view' command ---")
+    view_args = ToolCallArguments(command="view", path=test_file_path_str)
+    view_result = await tool.execute(view_args)
+    print(view_result.output)
+    print("-" * 20)
+
+    # 3. Replace a string in the file
+    print("--- 3. Testing 'str_replace' command ---")
+    replace_args = ToolCallArguments(
+        command="str_replace",
+        path=test_file_path_str,
+        old_str="world",
+        new_str="Python",
+    )
+    replace_result = await tool.execute(replace_args)
+    print(replace_result.output)
+    print("-" * 20)
+
+    # 4. View the file again to see the replacement
+    print("--- 4. Viewing file after replacement ---")
+    view_result_after_replace = await tool.execute(view_args)
+    print(view_result_after_replace.output)
+    print("-" * 20)
+
+    # 5. Insert a string into the file
+    print("--- 5. Testing 'insert' command ---")
+    insert_args = ToolCallArguments(
+        command="insert",
+        path=test_file_path_str,
+        insert_line=1,
+        new_str="This is a new line.",
+    )
+    insert_result = await tool.execute(insert_args)
+    print(insert_result.output)
+    print("-" * 20)
+
+    # 6. View the file again to see the insertion
+    print("--- 6. Viewing file after insertion ---")
+    view_result_after_insert = await tool.execute(view_args)
+    print(view_result_after_insert.output)
+    print("-" * 20)
+
+    # Clean up the test file
+    os.remove(test_file_path)
+    print(f"Cleaned up test file: {test_file_path_str}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/tools/json_edit_tool_example.py

@@ -0,0 +1,112 @@
+import asyncio
+import json
+import os
+from pathlib import Path
+import sys
+
+# Add project root to Python path to import trae_agent module
+project_root = Path(__file__).resolve().parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+from trae_agent.tools.json_edit_tool import JSONEditTool
+from trae_agent.tools.base import ToolCallArguments
+
+
+async def main():
+    """
+    An example of how to use the JSONEditTool to perform JSON file operations.
+    """
+    tool = JSONEditTool()
+    test_file_path = Path(__file__).parent / "test_data.json"
+    test_file_path_str = str(test_file_path.absolute())
+
+    # Initial JSON data
+    initial_data = {
+        "name": "test-project",
+        "version": "1.0.0",
+        "dependencies": {"libA": "1.0", "libB": "2.0"},
+    }
+
+    # 1. Create a JSON file for testing
+    print("--- 1. Creating test JSON file ---")
+    with open(test_file_path, "w") as f:
+        json.dump(initial_data, f, indent=2)
+    print(f"File created at: {test_file_path_str}")
+    print("Initial content:")
+    print(test_file_path.read_text())
+    print("-" * 20)
+
+    # 2. Add a new key-value pair at the root
+    print("--- 2. Testing 'add' operation (root level) ---")
+    add_args = ToolCallArguments(
+        operation="add",
+        file_path=test_file_path_str,
+        json_path="$.author",
+        value="Gemini",
+    )
+    add_result = await tool.execute(add_args)
+    if add_result.error:
+        print(f"Error: {add_result.error}")
+    else:
+        print(add_result.output)
+    print("Current content:")
+    print(test_file_path.read_text())
+    print("-" * 20)
+
+    # 3. Replace an existing value
+    print("--- 3. Testing 'set' operation ---")
+    replace_args = ToolCallArguments(
+        operation="set",
+        file_path=test_file_path_str,
+        json_path="$.version",
+        value="1.1.0",
+    )
+    replace_result = await tool.execute(replace_args)
+    if replace_result.error:
+        print(f"Error: {replace_result.error}")
+    else:
+        print(replace_result.output)
+    print("Current content:")
+    print(test_file_path.read_text())
+    print("-" * 20)
+
+    # 4. Add a new dependency (nested add)
+    print("--- 4. Testing 'add' operation (nested) ---")
+    add_nested_args = ToolCallArguments(
+        operation="add",
+        file_path=test_file_path_str,
+        json_path="$.dependencies.libC",
+        value="3.0",
+    )
+    add_nested_result = await tool.execute(add_nested_args)
+    if add_nested_result.error:
+        print(f"Error: {add_nested_result.error}")
+    else:
+        print(add_nested_result.output)
+    print("Current content:")
+    print(test_file_path.read_text())
+    print("-" * 20)
+
+    # 5. Delete a dependency
+    print("--- 5. Testing 'remove' operation ---")
+    delete_args = ToolCallArguments(
+        operation="remove",
+        file_path=test_file_path_str,
+        json_path="$.dependencies.libA",
+    )
+    delete_result = await tool.execute(delete_args)
+    if delete_result.error:
+        print(f"Error: {delete_result.error}")
+    else:
+        print(delete_result.output)
+    print("Current content:")
+    print(test_file_path.read_text())
+    print("-" * 20)
+
+    # Clean up the test file
+    os.remove(test_file_path)
+    print(f"Cleaned up test file: {test_file_path_str}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())