Skip to content

Playwright MCP と Koog でブラウザを操作する

GitHub で開く .ipynb をダウンロード

このノートブックでは、Koog エージェントを Playwright の Model Context Protocol (MCP) サーバーに接続し、実際のブラウザを操作してタスクを完了させます。具体的には、jetbrains.com を開き、Cookie を承認し、ツールバーの AI セクションをクリックします。

物事をシンプルかつ再現性のあるものにし、公開して再利用できる、最小限ながらも現実的なエージェントとツールのセットアップに焦点を当てます。

kotlin
%useLatestDescriptors
%use koog

前提条件

  • 環境変数としてエクスポートされた OpenAI API キー: OPENAI_API_KEY
  • PATH に Node.js および npx が利用可能であること
  • %use koog 経由で Koog が利用可能な Kotlin Jupyter ノートブック環境

ヒント: Playwright MCP サーバーをヘッドフルモードで実行すると、ブラウザがステップを自動化する様子を確認できます。

1) OpenAI API キーを提供する

OPENAI_API_KEY 環境変数から API キーを読み取ります。これにより、機密情報がノートブックから除外されます。

kotlin
// 環境変数からAPIキーを取得
val openAIApiToken = System.getenv("OPENAI_API_KEY") ?: error("OPENAI_API_KEY environment variable not set")

2) Playwright MCP サーバーを起動する

npx を使用して、Playwright の MCP サーバーをローカルで起動します。デフォルトでは、Koog から接続できる SSE エンドポイントが公開されます。

kotlin
// npx 経由で Playwright MCP サーバーを起動
val process = ProcessBuilder(
    "npx",
    "@playwright/mcp@latest",
    "--port",
    "8931"
).start()

3) Koog から接続し、エージェントを実行する

OpenAI エグゼキュータを備えた最小限の Koog AIAgent を構築し、そのツールレジストリを SSE 経由で MCP サーバーに向けます。次に、ツールのみを使用してブラウザタスクを完了するよう要求します。

kotlin
import kotlinx.coroutines.runBlocking

runBlocking {
    println("Playwright MCP サーバーに接続中...")
    val toolRegistry = McpToolRegistryProvider.fromTransport(
        transport = McpToolRegistryProvider.defaultSseTransport("http://localhost:8931")
    )
    println("Playwright MCP サーバーに正常に接続しました")

    // エージェントを作成
    val agent = AIAgent(
        executor = simpleOpenAIExecutor(openAIApiToken),
        llmModel = OpenAIModels.Chat.GPT4o,
        toolRegistry = toolRegistry,
    )

    val request = "Open a browser, navigate to jetbrains.com, accept all cookies, click AI in toolbar"
    println("リクエストを送信中: $request")

    agent.run(
        request + ". " +
            "You can only call tools. Use the Playwright tools to complete this task."
    )
}

4) MCP プロセスをシャットダウンする

実行の最後には必ず外部プロセスをクリーンアップしてください。

kotlin
// Playwright MCP プロセスをシャットダウン
println("Playwright MCP サーバーへの接続を閉じています")
process.destroy()

トラブルシューティング

  • エージェントが接続できない場合は、MCP サーバーが http://localhost:8931 で実行されていることを確認してください。
  • ブラウザが表示されない場合は、Playwright がインストールされており、システム上でブラウザを起動できることを確認してください。
  • OpenAI から認証エラーが発生する場合は、OPENAI_API_KEY 環境変数を再確認してください。

次のステップ

  • さまざまなウェブサイトやフローを試してみてください。MCP サーバーは、豊富な Playwright ツールセットを公開しています。
  • LLM モデルを入れ替えるか、Koog エージェントにツールを追加してください。
  • このフローをアプリに統合するか、ノートブックをドキュメントとして公開してください。