Deep Search

May 6, 2026 · View on GitHub

A comprehensive guide to setting up and using the Deep Search capability with AWorld CLI and agent-browser integration.

Table of Contents

  1. Prerequisites
  2. Step 1: Enable Chrome DevTools Protocol (CDP)
  3. Step 2: Install agent-browser
  4. Step 3: Install the agent-browser Skill
  5. Step 4: Create Workspace and Launch AWorld CLI
  6. Step 5: Configure Memory Settings
  7. Getting Started
  8. Troubleshooting

Prerequisites

Before you begin, ensure you have:

  • Google Chrome installed on your system
  • Node.js and npm installed (for agent-browser)
  • AWorld CLI installed and configured
  • Terminal access with appropriate permissions

Step 1: Enable Chrome DevTools Protocol (CDP)

The Chrome DevTools Protocol allows external tools to interact with Chrome programmatically. You need to launch Chrome with remote debugging enabled.

Command

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-work

What This Does

  • --remote-debugging-port=9222: Opens Chrome with CDP enabled on port 9222
  • --user-data-dir=/tmp/chrome-work: Uses a temporary profile directory to avoid conflicts with your regular Chrome session

Important Notes

  • Keep this Chrome instance running throughout your Deep Search session
  • This creates a separate Chrome profile, so you won't see your regular bookmarks or extensions
  • The port 9222 is the default; ensure no other application is using this port

Step 2: Install agent-browser

agent-browser is a powerful tool that enables automated browser interactions for AI agents.

Installation Steps

  1. Install the agent-browser package globally:
npm install -g agent-browser
  1. Download the required Chromium binary:
agent-browser install

Reference

Verification

After installation, verify that agent-browser is correctly installed:

agent-browser --version

Step 3: Install the agent-browser Skill

Skills extend AWorld's capabilities. The agent-browser skill enables browser automation within your AWorld agents.

Installation Command

cp -r ./aworld-skills/agent-browser/ ~/.aworld/skills/

What This Does

  • Copies the agent-browser skill directory to your AWorld skills folder
  • Makes the skill available to all AWorld agents on your system

Directory Structure

After installation, you should have:

~/.aworld/skills/
└── agent-browser/
    ├── SKILL.md
    └── [other skill files]

Verification

Ensure the skill directory exists:

ls -la ~/.aworld/skills/agent-browser/

Step 4: Create Workspace and Launch AWorld CLI

Set up a dedicated workspace for your Deep Search projects to keep your work organized.

Commands

  1. Create and navigate to your workspace:
mkdir -p ~/deep_search_workspace
cd ~/deep_search_workspace
  1. Launch AWorld CLI:
aworld-cli

What This Does

  • Creates a new directory for Deep Search projects (if it doesn't exist)
  • Changes to that directory
  • Starts the AWorld CLI interface in your workspace

Workspace Benefits

  • Keeps all Deep Search-related files organized
  • Provides a clean environment for each session
  • Makes it easier to manage project artifacts

Step 5: Configure Memory Settings

Configure AWorld to use the CDP-enabled Chrome instance for browser automation.

Configuration Steps

  1. Save the workspace preference explicitly:

    Run the following command in the AWorld CLI:

/remember --type workspace When using agent-browser, always include --cdp 9222.

  1. Optional: inspect or edit the workspace instruction file:

    You can review the current workspace memory with:

/memory view

Or open the editor with:

/memory

What This Does

  • Instructs AWorld agents to connect to your CDP-enabled Chrome instance (port 9222)
  • Ensures browser automation commands use the correct Chrome session
  • Persists this configuration in the current workspace memory
  • Makes the preference available in future AWorld CLI sessions started from the same workspace

Why This Matters

Without this configuration, agent-browser would try to launch its own browser instance instead of using your CDP-enabled Chrome, which could lead to connection issues.

For more details about memory commands, storage files, and auto-promotion behavior, see Memory.

Getting Started

Once you've completed all the setup steps, you're ready to use Deep Search!

Quick Start Checklist

  • Chrome is running with CDP enabled (port 9222)
  • agent-browser is installed and verified
  • agent-browser skill is copied to ~/.aworld/skills/
  • You're in your workspace directory
  • AWorld CLI is running
  • Memory is configured with CDP settings

Example Usage

Try asking your AWorld agent to:

  • "Search for the latest AI research papers"
  • "Browse to example.com and extract the main heading"
  • "Find information about [topic] and summarize it"

Troubleshooting

Common Issues and Solutions

Chrome CDP Connection Failed

Problem: Agent cannot connect to Chrome on port 9222

Solutions:

  • Verify Chrome is running with the CDP command
  • Check that port 9222 is not blocked by a firewall
  • Ensure no other application is using port 9222
  • Try restarting Chrome with the CDP command

agent-browser Command Not Found

Problem: Terminal doesn't recognize the agent-browser command

Solutions:

  • Verify npm global installation: npm list -g agent-browser
  • Check your PATH includes npm global binaries
  • Try reinstalling: npm install -g agent-browser

Skill Not Loading

Problem: AWorld doesn't recognize the agent-browser skill

Solutions:

  • Verify the skill directory exists: ls ~/.aworld/skills/agent-browser/
  • Check file permissions: chmod -R 755 ~/.aworld/skills/agent-browser/
  • Restart AWorld CLI to reload skills

Browser Automation Not Working

Problem: Commands execute but browser doesn't respond

Solutions:

  • Confirm memory configuration includes --cdp 9222
  • Check Chrome DevTools at http://localhost:9222 to verify CDP is active
  • Restart both Chrome (with CDP) and AWorld CLI

Additional Resources

Enjoy Your Deep Search Experience! 🚀

You're now ready to leverage the full power of automated web browsing and deep search capabilities with AWorld. Happy exploring!