README

Browser automation toolkit for Coqui. Wraps playwright-cli to give agents full web browsing capabilities including navigation, page interaction, screenshots, cookie/storage management, and session control.

Requirements

• PHP 8.4+
• Node.js 18+ and npm (for playwright-cli installation)

Installation

composer require coquibot/coqui-toolkit-browser

When installed alongside Coqui, the toolkit is auto-discovered via Composer's extra.php-agents.toolkits -- no manual registration needed.

On first use, the agent will automatically install playwright-cli and Chromium into .workspace/browser/ via the browser_session setup action. No manual Node.js setup is needed.

Tools Provided

browser

Navigate web pages and interact with elements.

browser_capture

Capture page state as snapshots, screenshots, or PDFs.

browser_storage

Manage cookies, localStorage, sessionStorage, and persist browser state.

browser_session

Manage browser sessions and playwright-cli installation.

Session Management

Sessions are auto-scoped to the workspace using a deterministic hash (coqui-{md5_8chars}). All four tools share the same session by default, so cookies and state persist across tool calls.

Override the session name with the session parameter on any tool to manage multiple independent browser contexts.

Agent Workflow

1. browser_session action setup -- install playwright-cli (first time only)
2. browser action open -- navigate to a URL
3. browser_capture action snapshot -- get the accessibility tree with element refs
4. browser action click/fill/type -- interact using refs from the snapshot
5. browser_capture action screenshot -- capture visual output
6. browser_session action close -- clean up when done

Standalone Usage

<?php

declare(strict_types=1);

use CoquiBot\Toolkits\Browser\BrowserToolkit;

require __DIR__ . '/vendor/autoload.php';

$toolkit = BrowserToolkit::fromEnv();

foreach ($toolkit->tools() as $tool) {
    echo $tool->name() . ': ' . $tool->description() . PHP_EOL;
}

// Navigate to a page
$browser = $toolkit->tools()[0];
$result = $browser->execute([
    'action' => 'open',
    'url' => 'https://example.com',
]);
echo $result->content;

Development

git clone https://github.com/AgentCoqui/coqui-toolkit-browser.git
cd coqui-toolkit-browser
composer install

Run tests

./vendor/bin/pest

Static analysis

./vendor/bin/phpstan analyse

License

MIT