Cursor Rules

1
You are working with Scrapybara, a Python SDK for deploying and managing remote desktop instances for AI agents. Use this guide to properly interact with the SDK.
2
3
**CORE SDK USAGE:**
4
- Initialize client: from scrapybara import Scrapybara; client = Scrapybara(api_key="KEY")
5
- Instance lifecycle:
6
    instance = client.start_ubuntu(timeout_hours=1)
7
    instance.pause() # Pause to save resources
8
    instance.resume(timeout_hours=1) # Resume work
9
    instance.stop() # Terminate and clean up
10
- Instance types:
11
    ubuntu_instance = client.start_ubuntu(): supports bash, computer, edit, browser
12
    browser_instance = client.start_browser(): supports computer, browser
13
    windows_instance = client.start_windows(): supports computer
14
15
**TYPE IMPORTS:**
16
- Core types:
17
    from scrapybara import Scrapybara
18
- Instance types:
19
    from scrapybara.client import UbuntuInstance, BrowserInstance, WindowsInstance
20
- Tool types:
21
    from scrapybara.tools import Tool, BashTool, ComputerTool, EditTool
22
- Model types:
23
    from scrapybara.anthropic import Anthropic
24
- Message types:
25
    from pydantic import BaseModel
26
    from typing import List, Union, Optional, Any
27
- Error types:
28
    from scrapybara.core.api_error import ApiError
29
30
**CORE INSTANCE OPERATIONS:**
31
- Screenshots: instance.screenshot().base_64_image
32
- Bash commands: instance.bash(command="ls -la")
33
- Mouse control: instance.computer(action="move_mouse", coordinates=[x, y])
34
- Click actions: instance.computer(action="click_mouse", button="right", coordinates=[x, y])
35
- Drag actions: instance.computer(action="drag_mouse", path=[[x1, y1], [x2, y2]])
36
- Scroll actions: instance.computer(action="scroll", coordinates=[x, y], delta_x=0, delta_y=0)
37
- Key actions: instance.computer(action="press_key", keys=[keys])
38
- Type actions: instance.computer(action="type_text", text="Hello world")
39
- Wait actions: instance.computer(action="wait", duration=3)
40
- Get cursor position: instance.computer(action="get_cursor_position").output
41
- File operations: instance.file.read(path="/path/file"), instance.file.write(path="/path/file", content="data")
42
43
**ACT SDK (Primary Focus):**
44
- Purpose: Enables building computer use agents with unified tools and model interfaces
45
- Core components:
46
1. Model: Handles LLM integration (currently Anthropic)
47
    from scrapybara.anthropic import Anthropic
48
    model = Anthropic() # Or model = Anthropic(api_key="KEY") for own key
49
2. Tools: Interface for computer interactions
50
    - BashTool: Run shell commands
51
    - ComputerTool: Mouse/keyboard control
52
    - EditTool: File operations
53
    tools = [
54
        BashTool(instance),
55
        ComputerTool(instance),
56
        EditTool(instance),
57
    ]
58
3. Prompt:
59
    - system: system prompt, recommend to use UBUNTU_SYSTEM_PROMPT, BROWSER_SYSTEM_PROMPT, WINDOWS_SYSTEM_PROMPT
60
    - prompt: simple user prompt
61
    - messages: list of messages
62
    - Only include either prompt or messages, not both
63
response = client.act(
64
    model=Anthropic(),
65
    tools=tools,
66
    system=UBUNTU_SYSTEM_PROMPT,
67
    prompt="Task",
68
    on_step=handle_step
69
)
70
messages = response.messages
71
steps = response.steps
72
text = response.text
73
output = response.output
74
usage = response.usage
75
76
**MESSAGE HANDLING:**
77
- Response Structure: Messages are structured with roles (user/assistant/tool) and typed content
78
- Content Types:
79
- TextPart: Simple text content
80
    TextPart(type="text", text="content")
81
- ImagePart: Base64 or URL images
82
    ImagePart(type="image", image="base64...", mime_type="image/png")
83
- ReasoningPart: Model reasoning content
84
    ReasoningPart(
85
        type="reasoning",
86
        id="id",
87
        reasoning="reasoning",
88
        signature="signature",
89
        instructions="instructions"
90
    )
91
- ToolCallPart: Tool invocations
92
    ToolCallPart(
93
        type="tool-call",
94
        tool_call_id="id",
95
        tool_name="bash",
96
        args={"command": "ls"}
97
    )
98
- ToolResultPart: Tool execution results
99
    ToolResultPart(
100
        type="tool-result",
101
        tool_call_id="id",
102
        tool_name="bash",
103
        result="output",
104
        is_error=False
105
    )
106
107
**STEP HANDLING:**
108
def handle_step(step: Step):
109
    if step.reasoning_parts:
110
        print(f"Reasoning: {step.reasoning_parts}")
111
    if step.text:
112
        print(f"Text: {step.text}")
113
    if step.tool_calls:
114
        for call in step.tool_calls:
115
            print(f"Tool: {call.tool_name}")
116
    if step.tool_results:
117
        for result in step.tool_results:
118
            print(f"Result: {result.result}")
119
    print(f"Tokens: {step.usage.total_tokens if step.usage else 'N/A'}")
120
121
**STRUCTURED OUTPUT:**
122
Use the schema parameter to define a desired structured output. The response's output field will contain the validated typed data returned by the model.
123
class HNSchema(BaseModel):
124
    class Post(BaseModel):
125
        title: str
126
        url: str 
127
        points: int
128
    posts: List[Post]
129
response = client.act(
130
    model=Anthropic(),
131
    tools=tools,
132
    schema=HNSchema,
133
    system=SYSTEM_PROMPT,
134
    prompt="Get the top 10 posts on Hacker News",
135
)
136
posts = response.output.posts
137
138
**TOKEN USAGE:**
139
- Track token usage through TokenUsage objects
140
- Fields: prompt_tokens, completion_tokens, total_tokens
141
- Available in both Step and ActResponse objects
142
143
**EXAMPLE:**
144
from scrapybara import Scrapybara
145
from scrapybara.anthropic import Anthropic
146
from scrapybara.prompts import UBUNTU_SYSTEM_PROMPT
147
from scrapybara.tools import BashTool, ComputerTool, EditTool
148
149
client = Scrapybara()
150
instance = client.start_ubuntu()
151
instance.browser.start()
152
153
response = client.act(
154
    model=Anthropic(),
155
    tools=[
156
        BashTool(instance),
157
        ComputerTool(instance),
158
        EditTool(instance),
159
    ],
160
    system=UBUNTU_SYSTEM_PROMPT,
161
    prompt="Go to the YC website and fetch the HTML",
162
    on_step=lambda step: print(f"{step}\n"),
163
)
164
messages = response.messages
165
steps = response.steps
166
text = response.text
167
output = response.output
168
usage = response.usage
169
170
instance.browser.stop()
171
instance.stop()
172
173
**EXECUTION PATTERNS:**
174
1. Basic agent execution:
175
response = client.act(
176
    model=Anthropic(),
177
    tools=tools,
178
    system="System context here",
179
    prompt="Task description"
180
)
181
2. Browser automation:
182
cdp_url = instance.browser.start().cdp_url
183
auth_state_id = instance.browser.save_auth(name="default").auth_state_id  # Save auth
184
instance.browser.authenticate(auth_state_id=auth_state_id)  # Reuse auth
185
3. File management:
186
instance.file.write("/tmp/data.txt", "content")
187
content = instance.file.read("/tmp/data.txt").content
188
4. Environment variables:
189
instance.env.set({"API_KEY": "value"})
190
instance.env.get().variables
191
instance.env.delete(["VAR_NAME"])
192
193
**ERROR HANDLING:**
194
from scrapybara.core.api_error import ApiError
195
try:
196
    client.start_ubuntu()
197
except ApiError as e:
198
    print(f"Error {e.status_code}: {e.body}")
199
200
**IMPORTANT GUIDELINES:**
201
- Always stop instances after use to prevent unnecessary billing
202
- Use async client (AsyncScrapybara) for non-blocking operations
203
- Handle API errors with try/except ApiError blocks
204
- Default timeout is 60s; customize with timeout parameter or request_options
205
- Instance auto-terminates after 1 hour by default
206
- For browser operations, always start browser before BrowserTool usage
207
- Prefer bash commands over GUI interactions for launching applications