Open URL Tool

Open a fixed URL in the user’s default browser.

Overview

The open_url toolset exposes a single, argument-less tool that opens a URL baked into the toolset definition in the user’s default browser. The model never supplies the URL — it just calls the tool by name. Launching the browser is cross-platform: docker-agent uses open on macOS, xdg-open on Linux, and rundll32 on Windows.

[!NOTE] When to Use

• Letting an agent open a dashboard, documentation page, or deep link on demand
• Deep-linking into a desktop app via a custom URI scheme (e.g. docker-desktop://)
• Any “take me there” action where the destination is fixed and known up front

Configuration

agents:
  assistant:
    model: openai/gpt-4o
    description: Assistant that can open the dashboard
    instruction: When the user asks to see the dashboard, call open_dashboard.
    toolsets:
      - type: open_url
        name: open_dashboard
        url: https://example.com/dashboard

Properties

Multiple URLs

Add one toolset entry per destination, each with its own name:

toolsets:
  - type: open_url
    name: open_dashboard
    url: https://example.com/dashboard
  - type: open_url
    name: open_docs
    url: https://docs.example.com/${env.DOCS_VERSION}

URL Interpolation

The url field supports ${env.VAR} placeholders, expanded at call time against the runtime environment:

toolsets:
  - type: open_url
    name: open_docs
    url: https://docs.example.com/${env.DOCS_VERSION}

Custom URI Schemes

Any scheme the operating system knows how to dispatch works, including deep links into desktop applications:

toolsets:
  - type: open_url
    name: open_in_docker_desktop
    url: docker-desktop://dashboard/apps

Limitations

• The URL must include a scheme (e.g. https://); bare paths are rejected.
• URLs that look like a command-line flag (starting with -) are refused to prevent argument injection into the platform open helper.
• The tool opens the URL on the host running docker-agent; in headless or remote environments where no browser/launcher is available, the call fails gracefully and reports the error to the agent.

See examples/open_url.yaml for a complete configuration.