Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

docs: update terminal and browser tookit (#3762)

Tao Sun60a871c6f715
diff --git a/docs/mintlify/key_modules/browsertoolkit.mdx b/docs/mintlify/key_modules/browsertoolkit.mdx
index fdd8876fb..bc91e83ca 100644
--- a/docs/mintlify/key_modules/browsertoolkit.mdx
+++ b/docs/mintlify/key_modules/browsertoolkit.mdx
@@ -3,137 +3,569 @@ title: "Browser Toolkit"
icon: "globe"
---
-<Note type="info" title="What is the Browser Toolkit?">
- The <b>Browser Toolkit</b> provides a powerful set of tools to automate and interact with web browsers. It allows CAMEL agents to perform complex web-based tasks, from simple page navigation to intricate form submissions and data extraction.
+<Note type="info" title="What is the HybridBrowserToolkit?">
+ The <b>HybridBrowserToolkit</b> provides a powerful set of browser automation tools for CAMEL agents. It enables web navigation, form interaction, screenshot capture, and data extraction through a unified interface with TypeScript (WebSocket-based) and Python implementations.
</Note>
<CardGroup cols={2}>
- <Card title="Two-Agent System" icon="users">
- Uses a sophisticated two-agent system: a `planning_agent` to create and refine high-level plans, and a `web_agent` to observe the screen and execute low-level actions.
+ <Card title="Dual Implementation" icon="code-branch">
+ Choose between TypeScript (WebSocket-based, recommended) or pure Python (Playwright) implementations based on your needs.
</Card>
- <Card title="Visual Reasoning" icon="image">
- The `web_agent` can analyze "Set-of-Marks" (SoM) screenshots, which are visual representations of the page with interactive elements highlighted, enabling it to perform complex visual reasoning.
+
+ <Card title="Set-of-Marks (SoM)" icon="image">
+ Capture annotated screenshots with interactive elements highlighted and numbered, enabling visual reasoning for AI agents.
</Card>
+
<Card title="Persistent Sessions" icon="cookie">
- Supports persistent browser sessions by saving and loading cookies and user data, allowing the agent to stay logged into websites across multiple sessions.
+ Maintain browser sessions with `user_data_dir`, keeping login states and cookies across multiple runs.
</Card>
- <Card title="Video Analysis" icon="video">
- Can analyze videos on the current page (e.g., YouTube) to answer questions about their content, leveraging the `VideoAnalysisToolkit`.
+
+ <Card title="CDP Connection" icon="link">
+ Connect to existing Chrome instances via Chrome DevTools Protocol (CDP) for debugging or reusing browser sessions.
</Card>
</CardGroup>
-## Initialization
+**Source Code**
+- Toolkit: `camel/toolkits/hybrid_browser_toolkit/`
+- Example: `examples/toolkits/hybrid_browser_toolkit_example.py`
+
+## Installation
-To get started, initialize the `BrowserToolkit`. You can configure the underlying models for the planning and web agents.
+The HybridBrowserToolkit requires Node.js for the TypeScript implementation (recommended) or Playwright for Python mode.
<Tabs>
-<Tab title="Default">
-```python
-from camel.toolkits import BrowserToolkit
+<Tab title="TypeScript Mode (Recommended)">
+```bash
+# Install CAMEL with browser support
+pip install "camel-ai[browser]"
-# Initialize with default models
-browser_toolkit = BrowserToolkit()
+# The toolkit will automatically install Node.js dependencies on first use
```
</Tab>
-<Tab title="Custom Models">
+<Tab title="Python Mode">
+```bash
+# Install CAMEL with browser support
+pip install "camel-ai[browser]"
+
+# Install Playwright browsers
+playwright install chromium
+```
+</Tab>
+</Tabs>
+
+## Quick Start
+
+<Card title="Basic Usage" icon="rocket">
```python
-from camel.toolkits import BrowserToolkit
+import asyncio
+from camel.agents import ChatAgent
from camel.models import ModelFactory
+from camel.toolkits import HybridBrowserToolkit
from camel.types import ModelPlatformType, ModelType
-# Define custom models for the agents (use latest OpenAI models)
-web_agent_model = ModelFactory.create(
- model_platform=ModelPlatformType.OPENAI,
- model_type=ModelType.GPT_5_MINI,
+async def main():
+ # Initialize the toolkit
+ toolkit = HybridBrowserToolkit(
+ headless=False, # Set True for headless mode
+ )
+
+ # Create a model and agent with browser tools
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.OPENAI,
+ model_type=ModelType.GPT_4O,
+ )
+
+ agent = ChatAgent(
+ model=model,
+ tools=toolkit.get_tools(),
+ )
+
+ # Run a browser task
+ response = await agent.astep(
+ "Go to google.com and search for 'CAMEL AI framework'"
+ )
+ print(response.msgs[0].content)
+
+ # Clean up
+ await toolkit.browser_close()
+
+asyncio.run(main())
+```
+</Card>
+
+## Initialization
+
+The `HybridBrowserToolkit` supports extensive configuration options.
+
+<Tabs>
+<Tab title="Basic">
+```python
+from camel.toolkits import HybridBrowserToolkit
+
+# Default TypeScript mode with basic settings
+toolkit = HybridBrowserToolkit(
+ headless=True, # Run in headless mode
+ stealth=True, # Enable stealth mode to avoid detection
+)
+```
+</Tab>
+<Tab title="With Persistence">
+```python
+from camel.toolkits import HybridBrowserToolkit
+
+# Persistent session with user data directory
+toolkit = HybridBrowserToolkit(
+ headless=False,
+ user_data_dir="./browser_data", # Saves cookies, localStorage, etc.
+ stealth=True,
)
-planning_agent_model = ModelFactory.create(
- model_platform=ModelPlatformType.OPENAI,
- model_type=ModelType.O4_MINI,
+```
+</Tab>
+<Tab title="Python Mode">
+```python
+from camel.toolkits import HybridBrowserToolkit
+
+# Use pure Python Playwright implementation
+toolkit = HybridBrowserToolkit(
+ mode="python", # Switch to Python mode
+ headless=True,
+ user_data_dir="./browser_data",
)
+```
+</Tab>
+<Tab title="CDP Connection">
+```python
+from camel.toolkits import HybridBrowserToolkit
-browser_toolkit = BrowserToolkit(
- web_agent_model=web_agent_model,
- planning_agent_model=planning_agent_model,
+# Connect to an existing Chrome instance (TypeScript mode only)
+toolkit = HybridBrowserToolkit(
+ connect_over_cdp=True,
+ cdp_url="ws://localhost:9222/devtools/browser/...",
+ cdp_keep_current_page=True, # Use existing page instead of creating new
)
```
</Tab>
</Tabs>
-## Core Functionality: `browse_url`
+### Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `mode` | `"typescript"` \| `"python"` | `"typescript"` | Implementation mode |
+| `headless` | `bool` | `True` | Run browser without visible window |
+| `user_data_dir` | `str` | `None` | Directory for persistent browser data |
+| `stealth` | `bool` | `False` | Enable stealth mode to avoid bot detection |
+| `cache_dir` | `str` | `None` | Directory for caching |
+| `enabled_tools` | `List[str]` | `DEFAULT_TOOLS` | List of enabled tool methods |
+| `browser_log_to_file` | `bool` | `False` | Log browser actions to file |
+| `log_dir` | `str` | `"browser_log"` | Directory for log files |
+| `session_id` | `str` | `None` | Session identifier for logging |
+| `viewport_limit` | `bool` | `False` | Filter snapshot to visible viewport only |
+| `full_visual_mode` | `bool` | `False` | Return minimal snapshots, rely on screenshots |
+
+### Timeout Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `default_timeout` | `int` | `None` | Default timeout in milliseconds |
+| `navigation_timeout` | `int` | `None` | Page navigation timeout |
+| `network_idle_timeout` | `int` | `None` | Wait for network idle |
+| `screenshot_timeout` | `int` | `None` | Screenshot capture timeout |
+| `page_stability_timeout` | `int` | `None` | Wait for page stability |
-The main entry point for the toolkit is the `browse_url` function. It takes a high-level task and a starting URL, and then autonomously navigates the web to complete the task.
+## Available Tools
+
+### Default Tools
+
+The default tool set provides essential browser functionality:
+
+```python
+DEFAULT_TOOLS = [
+ "browser_open",
+ "browser_close",
+ "browser_visit_page",
+ "browser_back",
+ "browser_forward",
+ "browser_click",
+ "browser_type",
+ "browser_switch_tab",
+]
+```
+
+### All Available Tools
+
+Use `enabled_tools=HybridBrowserToolkit.ALL_TOOLS` for full functionality:
+
+```python
+ALL_TOOLS = [
+ # Navigation
+ "browser_open", # Start browser session
+ "browser_close", # Close browser
+ "browser_visit_page", # Navigate to URL
+ "browser_back", # Go back in history
+ "browser_forward", # Go forward in history
+
+ # Page Observation
+ "browser_get_page_snapshot", # Get page structure as text
+ "browser_get_som_screenshot", # Screenshot with element annotations
+ "browser_get_screenshot", # Plain screenshot
+
+ # Interaction
+ "browser_click", # Click on element (by ref or coordinates)
+ "browser_type", # Type text into element
+ "browser_select", # Select dropdown option
+ "browser_scroll", # Scroll the page
+ "browser_enter", # Press Enter key
+ "browser_press_key", # Press any key combination
+ "browser_mouse_control", # Move mouse to position
+ "browser_mouse_drag", # Drag from one point to another
+
+ # Tab Management
+ "browser_switch_tab", # Switch to different tab
+ "browser_close_tab", # Close a tab
+ "browser_get_tab_info", # Get info about all tabs
+
+ # Developer Tools
+ "browser_console_view", # View console logs
+ "browser_console_exec", # Execute JavaScript
+
+ # Special
+ "browser_wait_user", # Wait for user intervention
+ "browser_sheet_input", # Input data into spreadsheets
+ "browser_sheet_read", # Read spreadsheet data
+]
+```
+
+### Custom Tool Selection
-<Card title="Example: Researching a Topic" icon="magnifying-glass">
```python
-task_prompt = "Find the main contributions of the paper 'Sparks of AGI' by Microsoft Research."
-start_url = "https://www.google.com"
+from camel.toolkits import HybridBrowserToolkit
-# The agent will navigate from Google, find the paper, and extract the information.
-result = browser_toolkit.browse_url(
- task_prompt=task_prompt,
- start_url=start_url,
+# Select only the tools you need
+toolkit = HybridBrowserToolkit(
+ enabled_tools=[
+ "browser_open",
+ "browser_visit_page",
+ "browser_click",
+ "browser_type",
+ "browser_get_som_screenshot",
+ "browser_close",
+ ]
)
+```
+
+## Core Tool Methods
+
+### Navigation
+
+<Card title="browser_visit_page" icon="compass">
+Navigate to a URL and get the page snapshot.
+
+```python
+result = await toolkit.browser_visit_page("https://example.com")
+# Returns: {"snapshot": "...", "url": "...", "title": "..."}
+```
+</Card>
+
+<Card title="browser_back / browser_forward" icon="arrows-left-right">
+Navigate through browser history.
+
+```python
+await toolkit.browser_back()
+await toolkit.browser_forward()
+```
+</Card>
+
+### Interaction
+
+<Card title="browser_click" icon="mouse-pointer">
+Click on an element by ref ID (from SoM screenshot) or pixel coordinates.
+
+```python
+# Click by ref (from Set-of-Marks screenshot)
+await toolkit.browser_click(ref="e15")
+
+# Click by pixel coordinates (in full_visual_mode)
+await toolkit.browser_click(x=350, y=200)
+```
+</Card>
+
+<Card title="browser_type" icon="keyboard">
+Type text into an input field.
+
+```python
+# Type into element by ref
+await toolkit.browser_type(ref="e8", text="Hello World")
+
+# Type by coordinates (in full_visual_mode)
+await toolkit.browser_type(x=350, y=200, text="Hello World")
+```
+</Card>
+
+<Card title="browser_scroll" icon="arrows-up-down">
+Scroll the page in any direction.
-print(result)
+```python
+await toolkit.browser_scroll(direction="down", amount=500)
+# direction: "up", "down", "left", "right"
```
</Card>
-## How It Works: The Two-Agent System
-
-The `browse_url` function orchestrates a loop between the `planning_agent` and the `web_agent`.
-
-<Steps>
-<Step title="Planning">
-The `planning_agent` creates a high-level plan to accomplish the task.
-</Step>
-<Step title="Observation">
-The `web_agent` observes the current page by taking a "Set-of-Marks" (SoM) screenshot.
-</Step>
-<Step title="Action">
-Based on the observation and the plan, the `web_agent` decides on the next action to take (e.g., click, type, scroll).
-</Step>
-<Step title="Execution">
-The toolkit executes the action and the loop repeats.
-</Step>
-<Step title="Replanning">
-If the `web_agent` gets stuck, the `planning_agent` can re-evaluate the situation and create a new plan.
-</Step>
-</Steps>
+### Page Observation
+
+<Card title="browser_get_som_screenshot" icon="camera">
+Capture a screenshot with Set-of-Marks annotations. Each interactive element is labeled with a ref ID (e.g., `e1`, `e2`).
+
+```python
+result = await toolkit.browser_get_som_screenshot()
+# Returns screenshot image with numbered element overlays
+```
+</Card>
+
+<Card title="browser_get_page_snapshot" icon="code">
+Get the page structure as text, showing all interactive elements with their ref IDs.
+
+```python
+snapshot = await toolkit.browser_get_page_snapshot()
+# Returns text representation of page elements
+```
+</Card>
+
+### Tab Management
+
+<Card title="Tab Operations" icon="window-restore">
+```python
+# Get info about all tabs
+tabs = await toolkit.browser_get_tab_info()
+
+# Switch to a specific tab
+await toolkit.browser_switch_tab(tab_id="tab_123")
+
+# Close a tab
+await toolkit.browser_close_tab(tab_id="tab_123")
+```
+</Card>
+
+### Console Operations
+
+<Card title="JavaScript Execution" icon="terminal">
+```python
+# View console logs
+logs = await toolkit.browser_console_view()
+
+# Execute JavaScript
+result = await toolkit.browser_console_exec("document.title")
+```
+</Card>
## Advanced Usage
-### Persistent Sessions
-You can maintain login sessions across runs by providing a path to a `cookies.json` file or a `user_data_dir`.
+### Full Visual Mode
+
+Full Visual Mode is designed for vision-capable models that can reason directly from screenshots using pixel coordinates. When enabled, several key behaviors change:
+
+<AccordionGroup>
+<Accordion title="Automatic Tool Signature Switching">
+Tools that normally use `ref` IDs automatically switch to pixel-based parameters. The docstrings are also updated accordingly - **you will only see the pixel-based signatures**, not both versions simultaneously.
+
+| Tool | Standard Mode | Full Visual Mode |
+|------|--------------|------------------|
+| `browser_click` | `click(ref="e15")` | `click(x=350, y=200)` |
+| `browser_type` | `type(ref="e8", text="...")` | `type(x=350, y=200, text="...")` |
+| `browser_mouse_drag` | `drag(from_ref="e1", to_ref="e2")` | `drag(from_x=100, from_y=100, to_x=300, to_y=200)` |
+
+Tools that require `ref` with no pixel alternative (`browser_select`, `browser_get_page_snapshot`, `browser_get_som_screenshot`) are automatically excluded from the tool list.
+</Accordion>
+
+<Accordion title="Screenshot with Pixel Rulers">
+`browser_get_screenshot` returns screenshots with pixel rulers added to the top and left edges. This helps vision models accurately identify pixel coordinates for click and type operations.
+
+The rulers show:
+- Major tick marks every 100 pixels with numeric labels
+- Medium tick marks every 50 and 10 pixels
+- Minor tick marks every 5 pixels
+</Accordion>
+
+<Accordion title="Ineffective Click Detection">
+When a click does not change the page content (snapshot remains the same), the toolkit detects this as a potentially ineffective click and returns helpful feedback including the **5 nearest interactive elements** with their clickable coordinates.
+
+Example response:
+```
+Click at (350, 200) may be ineffective - page content unchanged.
+Nearest interactive elements:
+ 1. [button] "Submit" - click at (380, 195), area: (340, 180) to (420, 210)
+ 2. [link] "Learn more" - click at (290, 240), area: (250, 230) to (330, 250)
+ 3. [textbox] "Email" - click at (400, 150), area: (300, 140) to (500, 160)
+ ...
+```
+
+This helps the model correct its click position without needing another screenshot.
+</Accordion>
+</AccordionGroup>
-<Card title="Using a Persistent Session" icon="cookie">
```python
-# The toolkit will save cookies and local storage to this file
-cookie_path = "./my_browser_session.json"
+toolkit = HybridBrowserToolkit(
+ full_visual_mode=True,
+ headless=False,
+)
-# First run: Log in to a website
-# browser_toolkit = BrowserToolkit(cookie_json_path=cookie_path)
-# browser_toolkit.browse_url(task_prompt="Log in to my account...", start_url="...")
+# Get screenshot with pixel rulers for coordinate identification
+screenshot = await toolkit.browser_get_screenshot()
-# Subsequent runs: The agent will be logged in automatically
-browser_toolkit_loggedin = BrowserToolkit(cookie_json_path=cookie_path)
+# Click using pixel coordinates (ref parameter not available in this mode)
+await toolkit.browser_click(x=350, y=200)
+
+# Type at specific coordinates
+await toolkit.browser_type(x=400, y=150, text="[email protected]")
```
+
+### Diff Snapshot for Dropdowns and Autocomplete
+
+When interacting with **combobox** (dropdown) or **textbox** (input/textarea) elements, the toolkit intelligently returns a **diff snapshot** instead of the full page snapshot. This optimization is particularly useful for:
+
+- Dropdown menus that expand with options
+- Autocomplete/typeahead suggestions
+- Search result suggestions
+
+<Card title="How Diff Snapshot Works" icon="code-compare">
+**Trigger elements:**
+- `combobox` - dropdown select elements
+- `textbox`, `input`, `textarea` - text input fields
+
+**What's returned:**
+- Only **new** `option` and `menuitem` elements that appeared after the interaction
+- For combobox: includes the combobox's updated state (since its ref may change after expansion)
+
+**Example diff snapshot after clicking a dropdown:**
+```
+- combobox "Country" [ref=e12] [expanded]
+- option "United States" [ref=e45]
+- option "Canada" [ref=e46]
+- option "United Kingdom" [ref=e47]
+- option "Germany" [ref=e48]
+```
+
+This significantly reduces context size compared to returning the entire page snapshot, helping the model focus on the relevant options.
</Card>
-### Video Analysis
+### Viewport Limiting
+
+Reduce context size by only including elements visible in the current viewport:
+
+```python
+toolkit = HybridBrowserToolkit(
+ viewport_limit=True, # Only show visible elements in snapshots
+)
+```
+
+### Action Logging
+
+Enable detailed logging for debugging or replay:
+
+```python
+toolkit = HybridBrowserToolkit(
+ browser_log_to_file=True,
+ log_dir="./my_browser_logs",
+ session_id="task_001",
+)
+```
+
+### Spreadsheet Operations
-The toolkit can answer questions about videos on a webpage.
+The toolkit includes specialized tools for interacting with web-based spreadsheets (Google Sheets, Excel Online):
-<Card title="Asking a Question About a YouTube Video" icon="video">
```python
-# First, navigate to the video
-browser_toolkit.browse_url(task_prompt="Navigate to a specific YouTube video", start_url="...")
+# Input data into cells
+await toolkit.browser_sheet_input(
+ data=[["A1", "Hello"], ["B1", "World"]],
+ start_cell="A1",
+)
+
+# Read spreadsheet data
+data = await toolkit.browser_sheet_read()
+```
+
+## Integration with ChatAgent
+
+<Card title="Complete Example" icon="robot">
+```python
+import asyncio
+from camel.agents import ChatAgent
+from camel.models import ModelFactory
+from camel.toolkits import HybridBrowserToolkit
+from camel.types import ModelPlatformType, ModelType
+
+async def search_and_extract():
+ # Initialize toolkit with logging
+ toolkit = HybridBrowserToolkit(
+ headless=False,
+ user_data_dir="./browser_data",
+ stealth=True,
+ viewport_limit=True,
+ browser_log_to_file=True,
+ )
+
+ # Create model
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.OPENAI,
+ model_type=ModelType.GPT_4O,
+ model_config_dict={"temperature": 0.0},
+ )
-# Then, ask a question about it
-# Note: This is an example of how you might use the underlying BaseBrowser.
-# The browse_url function would orchestrate this automatically.
-question = "What is the main topic of this video?"
-answer = browser_toolkit.browser.ask_question_about_video(question=question)
+ # Create agent with browser tools
+ agent = ChatAgent(
+ model=model,
+ tools=toolkit.get_tools(),
+ max_iteration=15,
+ )
-print(answer)
+ task = """
+ 1. Go to google.com
+ 2. Search for "CAMEL AI multi-agent framework"
+ 3. Click on the official GitHub repository
+ 4. Find and report the number of stars
+ """
+
+ try:
+ response = await agent.astep(task)
+ print(response.msgs[0].content)
+ finally:
+ await toolkit.browser_close()
+
+asyncio.run(search_and_extract())
```
</Card>
+
+## Mode Comparison
+
+| Feature | TypeScript Mode | Python Mode |
+|---------|-----------------|-------------|
+| **Performance** | Faster (WebSocket) | Standard |
+| **CDP Connection** | Supported | Not supported |
+| **Viewport Limit** | Supported | Not supported |
+| **Full Visual Mode** | Supported | Supported |
+| **Dependencies** | Node.js (auto-installed) | Playwright |
+| **Recommended For** | Production use | Simple tasks |
+
+## Troubleshooting
+
+<AccordionGroup>
+<Accordion title="Browser fails to start">
+Ensure Node.js is installed for TypeScript mode, or run `playwright install chromium` for Python mode.
+</Accordion>
+
+<Accordion title="Elements not found">
+Use `browser_get_page_snapshot` to see the current page snapshot. Elements may change refs after actions.
+</Accordion>
+
+<Accordion title="CDP connection fails">
+Ensure Chrome is started with remote debugging enabled:
+```bash
+google-chrome --remote-debugging-port=9222
+```
+</Accordion>
+
+<Accordion title="Stealth mode not working">
+Some websites have advanced bot detection. Try using a persistent `user_data_dir` with realistic browsing history.
+</Accordion>
+</AccordionGroup>
diff --git a/docs/mintlify/key_modules/terminaltoolkit.mdx b/docs/mintlify/key_modules/terminaltoolkit.mdx
index b0b52c94a..51f1d63f0 100644
--- a/docs/mintlify/key_modules/terminaltoolkit.mdx
+++ b/docs/mintlify/key_modules/terminaltoolkit.mdx
@@ -62,6 +62,11 @@ terminal_toolkit = TerminalToolkit(clone_current_env=True)
### Executing Commands
The `shell_exec` function is the primary way to execute commands. Each command is run within a session, identified by a unique `id`.
+**How it works**
+- `block=True` (default): waits for completion and returns combined stdout/stderr.
+- `block=False`: starts a background session for interactive/long-running tasks.
+- The `id` is how you later view output or terminate the session.
+
<Tabs>
<Tab title="Listing Files">
```python
@@ -88,18 +93,20 @@ print(output)
### Interacting with Processes
You can manage long-running or interactive processes.
+**Tip**: `shell_view` returns only *new* output since the last call. Call it
+periodically to stream logs.
+
<Tabs>
<Tab title="Writing to a Process">
-You can write to a process's standard input using `shell_write_to_process`. This is useful for interactive command-line tools.
+You can write to a process's standard input using `shell_write_to_process`. Start the process in non-blocking mode, then send input and read output.
```python
# Start a python REPL in a new session
-terminal_toolkit.shell_exec(id='interactive_session', command='python')
+terminal_toolkit.shell_exec(id='interactive_session', command='python', block=False)
# Write code to the python process
terminal_toolkit.shell_write_to_process(
id='interactive_session',
- input='print("Hello, interactive world!")',
- press_enter=True
+ command='print("Hello, interactive world!")'
)
# View the output
@@ -111,7 +118,7 @@ print(output)
Forcibly terminate a running process using `shell_kill_process`.
```python
# Start a long-running process
-terminal_toolkit.shell_exec(id='long_process', command='sleep 100')
+terminal_toolkit.shell_exec(id='long_process', command='sleep 100', block=False)
# Kill the process before it finishes
result = terminal_toolkit.shell_kill_process(id='long_process')
@@ -120,6 +127,83 @@ print(result)
</Tab>
</Tabs>
+### Advanced Usage
+
+#### Non-blocking Sessions and Timeouts
+Blocking commands that exceed `timeout` are converted into background sessions. You can then view output or terminate them.
+
+This is useful for long tasks where you still want a quick response, but
+need to keep the process alive in the background.
+
+```python
+# If this exceeds timeout, it becomes a background session automatically
+output = terminal_toolkit.shell_exec(
+ id='long_task',
+ command='python long_running_job.py',
+ block=True,
+ timeout=5,
+)
+print(output)
+
+# Later, check output or terminate
+print(terminal_toolkit.shell_view(id='long_task'))
+print(terminal_toolkit.shell_kill_process(id='long_task'))
+```
+
+#### Safe Mode Allowlist
+When `safe_mode=True`, you can restrict execution to an explicit allowlist.
+
+This is helpful for production deployments where only specific commands
+should be allowed.
+
+```python
+terminal_toolkit = TerminalToolkit(
+ safe_mode=True,
+ allowed_commands=["ls", "cat", "python", "pip", "uv"]
+)
+```
+
+#### Docker Backend
+Run commands inside a pre-existing Docker container for stronger isolation.
+
+The container must already exist and be running.
+
+```python
+terminal_toolkit = TerminalToolkit(
+ use_docker_backend=True,
+ docker_container_name="camel-runtime",
+ working_directory="/workspace",
+)
+```
+
+#### Environment and Dependencies
+Clone the current environment or preinstall dependencies into the sandboxed workspace.
+
+Use this to ensure tools like `python`, `pip`, or `uv` are available
+inside the sandboxed workspace.
+
+```python
+terminal_toolkit = TerminalToolkit(
+ working_directory="./workspace",
+ clone_current_env=True,
+ install_dependencies=["python-pptx", "pandas"],
+)
+```
+
+#### Write Files Directly
+Use `shell_write_content_to_file` to write large files without shell escaping issues.
+
+Relative paths are resolved under `working_directory`. In safe mode, the
+path must stay inside that directory.
+
+```python
+content = "line1\nline2\nline3\n"
+result = terminal_toolkit.shell_write_content_to_file(
+ content=content,
+ file_path="notes/demo.txt",
+)
+print(result)
+```
### Safe Mode
When `safe_mode` is enabled (default), the toolkit blocks commands that could be harmful to your system.
@@ -138,15 +222,26 @@ print(output)
### Human-in-the-Loop
-When an agent gets stuck, it can use `ask_user_for_help` to request human intervention.
+When an agent gets stuck, it can use `shell_ask_user_for_help` to request human intervention.
+
+This call blocks and waits for a human response in the console, then returns
+the user's input or the resulting command output.
<Card title="Asking for Human Help" icon="hand">
```python
# The agent is stuck, so it asks for help in 'session_1'
-help_result = terminal_toolkit.ask_user_for_help(id='session_1')
+help_result = terminal_toolkit.shell_ask_user_for_help(
+ id='session_1',
+ prompt="The tool is asking for a filename. Please type 'config.json'.",
+)
-# The script will now pause and wait for the user to type commands
-# in the console. After the user types '/exit', the script will resume.
+# The script will now pause and wait for the user to type a response
+# in the console. It will then resume with the user's input.
print(help_result)
```
</Card>
+
+## References
+- `camel/toolkits/terminal_toolkit/terminal_toolkit.py`
+- `examples/toolkits/terminal_toolkit.py`
+- `examples/runtimes/shared_runtime_multi_toolkit.py`