autourgos-cua-scroll-tool

Scroll tool for Autourgos computer-use agents. Scrolls vertically (up/down) or horizontally (left/right), with a configurable sensitivity (how many scroll clicks/units per call).

There are two ways to use this package -- pick one:

Table of Contents

• Install
• Use Case 1: scroll() (library)
• Use Case 2: ScrollTool (agent tool)
• Sensitivity
• Error Handling
• API Reference
• License

Install

pip install autourgos-cua-scroll-tool

Uses pyautogui under the hood to perform the actual scroll -- installed automatically as a dependency.

Use Case 1: scroll() (library)

Call it directly from your own code.

from autourgos_cua_scroll_tool import scroll

scroll("down")               # vertical scroll down, default sensitivity
scroll("up")                 # vertical scroll up
scroll("right")              # horizontal scroll right
scroll("left")               # horizontal scroll left

scroll("down", amount=15)    # scroll further per call (higher sensitivity)
scroll("down", amount=1)     # scroll less per call (lower sensitivity)

Use Case 2: ScrollTool (agent tool)

For autourgos-agent. No constructor arguments needed -- hand it straight to agent.add_tools(...).

from autourgos_agent import Agent
from autourgos_cua_scroll_tool import ScrollTool

agent = Agent(llm=my_llm)
agent.add_tools(ScrollTool())

result = agent.invoke("Scroll down to see more of the page")

It returns a dict:

{"scrolled": True, "direction": "down", "amount": 3}
# or, on failure:
{"scrolled": False, "error": "..."}

Sensitivity

amount is the sensitivity knob -- the number of scroll clicks/units performed per call, in the given direction:

• Higher amount scrolls further per call (a bigger jump).
• Lower amount scrolls less per call (finer control).
• Defaults to DEFAULT_AMOUNT (3), a moderate step -- not a full-page jump.

from autourgos_cua_scroll_tool import scroll, DEFAULT_AMOUNT

scroll("down")                       # DEFAULT_AMOUNT (3) clicks
scroll("down", amount=DEFAULT_AMOUNT * 5)   # a much bigger scroll

Error Handling

scroll() raises ScrollError -- never silently does nothing -- when:

• direction isn't one of "up"/"down"/"left"/"right",
• amount isn't a positive integer,
• the pyautogui dependency is unavailable, or
• the underlying scroll call itself fails (e.g. no display/desktop session).

ScrollTool's wrapped call catches ScrollError and returns {"scrolled": False, "error": "..."} instead of raising, so a calling agent gets a structured result rather than a crash.

API Reference

scroll(direction, amount=DEFAULT_AMOUNT) -> None

• direction: "up", "down", "left", or "right".
• amount: positive integer sensitivity -- number of scroll clicks/units.

Raises ScrollError on failure.

ScrollTool() -> Tool

A scroll(direction, amount) tool with a fixed name (scroll) and description stating it supports both vertical and horizontal scrolling with a configurable sensitivity. Ready for agent.add_tools(...).

DEFAULT_AMOUNT

The default sensitivity (3) used when amount is omitted.

License

Apache License 2.0. See LICENSE.