> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narada.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor Integration

> Use Cursor IDE to write Narada Python SDK code and build custom agents with AI-powered assistance

# Cursor Integration

Cursor is an AI-powered code editor that can reference external documentation to provide context-aware assistance. By integrating Narada's documentation with Cursor, you can efficiently write Python code using the Narada SDK to build custom agents and web automation workflows.

## Adding Narada Documentation to Cursor

<Steps>
  <Step title="Open Cursor Settings">
    Navigate to **Cursor Settings** -> **Docs** in Cursor IDE.
  </Step>

  <Step title="Add New Documentation">
    Click **Add Doc** to add a new documentation source.
  </Step>

  <Step title="Configure Documentation">
    Enter the following details:

    * **Name**: `Narada`
    * **Prefix**: `https://docs.narada.ai`
    * **Entrypoint**: `https://docs.narada.ai`
  </Step>

  <Step title="Index Documentation">
    Cursor crawls and indexes the Narada documentation site.
  </Step>
</Steps>

<Check>
  Once indexed, reference Narada documentation with the `@` command, such as `@Narada`, in Cursor chat or inline edits.
</Check>

## Adding Cursor Rules for Better Development

Cursor rules provide persistent project context so generated SDK code follows your team's current Narada patterns.

### Set Up Project Rules

1. Create a `.cursor/rules/` directory in your project.
2. Add a `.mdc` file, such as `narada-cursor-rules.mdc`.
3. Copy the rules from the next section.
4. Set `alwaysApply: true` so Cursor applies the rules automatically.

## Cursor Rules for Narada Development

Use this as a starting point for a project rule:

````mdx wrap expandable theme={null}
---
alwaysApply: true
---

# Rules for Narada Development

You are an AI coding assistant helping developers build web automation workflows and custom agents with the Narada Python SDK.

## Current SDK Model

Narada uses an environment + agent design:

- Create an execution target with an environment, such as `BrowserEnvironment`, `CloudBrowserEnvironment`, `RemoteBrowserEnvironment`, or `LambdaEnvironment`.
- Create an `Agent(environment=env, kind=...)`.
- Call `await agent.run(prompt=...)` for natural-language tasks.
- Call browser action helpers on `agent`, such as `go_to_url()`, `agentic_selector()`, `read_google_sheet()`, and `print_message()`.
- Use the environment for lifecycle and IDs, such as `await env.start()`, `env.browser_window_id`, `env.cloud_browser_session_id`, and `await env.close()`.

Do not use older APIs such as `Narada()`, `open_and_initialize_browser_window()`, `LocalBrowserWindow`, `RemoteBrowserWindow`, or `window.agent()`.

## Standalone SDK Script Pattern

```python
import asyncio

from narada import Agent, BrowserEnvironment


async def main() -> None:
    env = BrowserEnvironment()
    agent = Agent(environment=env)

    try:
        response = await agent.run(
            prompt="Search for Narada AI and summarize the first result.",
        )
        print(response.text)
    finally:
        await env.close()


if __name__ == "__main__":
    asyncio.run(main())
```

## Agent Studio Python Agent Pattern

In Agent Studio, `BrowserEnvironment()` targets the current browser window through the runtime environment.

```python
from narada import Agent, BrowserEnvironment

env = BrowserEnvironment()
agent = Agent(environment=env)

await agent.go_to_url(url="https://example.com", new_tab=True)

response = await agent.run(
    prompt="Extract the main heading from this page.",
)

print(response.text)
```

Use `new_tab=True` for the first navigation in Agent Studio so the workflow runtime tab stays separate from the page being automated.

## Agent Kinds

Choose the agent kind when constructing the agent:

```python
from narada import Agent, AgentKind, BrowserEnvironment

env = BrowserEnvironment()

operator = Agent(environment=env)  # Defaults to AgentKind.OPERATOR
core_agent = Agent(environment=env, kind=AgentKind.CORE_AGENT)
custom_agent = Agent(environment=env, kind="/$USER/my-custom-agent")
```

Use `AgentKind.OPERATOR` for browser automation. Use `AgentKind.CORE_AGENT` for read-only reasoning, page summaries, and conversation-style tasks. Use a namespaced string for custom agents from Agent Studio.

## Structured Output

Use Pydantic models with `output_schema` for reliable extraction:

```python
from pydantic import BaseModel, Field


class CompanyInfo(BaseModel):
    name: str = Field(description="Company name")
    valuation: str = Field(description="Latest known valuation")
    source_url: str = Field(description="URL where the valuation was found")


response = await agent.run(
    prompt="Extract company valuation data from this page.",
    output_schema=CompanyInfo,
)

company = response.structured_output
assert company is not None
```

Prefer `response.text` for text responses and `response.structured_output` for typed responses.

## Navigation and Browser Actions

Use agent methods for browser actions:

```python
await agent.go_to_url(url="https://example.com/products", new_tab=True)

await agent.agentic_selector(
    action={"type": "click"},
    selectors={"aria_label": "Search"},
    fallback_operator_query="click the search button",
)

current_url = await agent.get_url()
print(current_url.url)
```

Prefer resilient selectors such as ARIA labels, `data_testid`, roles, names, and stable text. Always include a clear fallback query.

## Attachments

Pass file-like objects directly to `Agent.run()`. The SDK uploads them automatically.

```python
from narada import AgentKind

document_agent = Agent(environment=env, kind=AgentKind.CORE_AGENT)

with open("financial_report.pdf", "rb") as f:
    response = await document_agent.run(
        prompt="Summarize the key financial metrics from this report.",
        attachment=f,
    )
```

Do not call a separate public `upload_file()` method.

## Google Sheets

Read from and write to Google Sheets with agent methods:

```python
sheet_data = await agent.read_google_sheet(
    spreadsheet_id="your_sheet_id",
    range="Companies!A1:C10",
)

results = []
for row in sheet_data.values:
    company_name = row[0]
    response = await agent.run(
        prompt=f"Find the latest valuation for {company_name}.",
    )
    results.append([company_name, response.text])

await agent.write_google_sheet(
    spreadsheet_id="your_sheet_id",
    range="Results!A1:B5",
    values=results,
)
```

## Progress Updates

Use `print_message()` for user-visible progress in the Narada side panel:

```python
await agent.print_message(message="Starting data extraction...")
await agent.print_message(message=f"Processed {len(results)} companies")
```

## Error Handling

Handle timeouts and reset agent state before retrying:

```python
from narada import NaradaError, NaradaTimeoutError

try:
    response = await agent.run(
        prompt="Complete a complex task on this slow page.",
        timeout=60,
    )
except NaradaTimeoutError:
    await agent.reset_agent_state()
    response = await agent.run(prompt="Try a simpler version of the task.")
except NaradaError as exc:
    print(f"Narada failed: {exc}")
```

## Parallel Execution

Create one environment per independent browser task:

```python
import asyncio

from narada import Agent, BrowserEnvironment


async def analyze_company(company_url: str):
    env = BrowserEnvironment()
    agent = Agent(environment=env)

    try:
        await agent.go_to_url(url=company_url, new_tab=True)
        return await agent.run(prompt="Extract company valuation data.")
    finally:
        await env.close()


results = await asyncio.gather(*[
    analyze_company(url) for url in company_urls
])
```

## Documentation Workflow

Before writing Narada code:

1. Read the relevant `@Narada` documentation page.
2. Check the current method signature and examples.
3. Plan the environment, agent kind, browser actions, response shape, and cleanup.
4. Implement with `try` / `finally` so environments close cleanly.
````

## Building Custom Agents with Cursor

Once integrated, Cursor can help you build Narada agents with the current SDK patterns:

* **Smart code completion**: Get suggestions for Narada SDK methods and parameters.
* **Context-aware assistance**: Ask questions about Narada APIs and get documentation-backed answers.
* **Code generation**: Generate boilerplate for common environment, agent, selector, sheet, and structured-output workflows.
* **Error prevention**: Avoid stale window-based SDK patterns and missing cleanup.

### Example Development Workflow

When building custom agents with the Narada Python SDK, you can ask Cursor:

* "How do I create an agent that extracts data from a website and saves it to Google Sheets?"
* "Show me how to use `agentic_selector()` with fallback handling."
* "Why is my `go_to_url()` call timing out?"
* "How can I make this agent more reliable with retry logic?"

Cursor will reference the indexed Narada documentation to provide accurate, current answers and code suggestions.

<Warning>
  Add the Narada documentation to Cursor before relying on generated SDK code. Without indexed docs, Cursor may suggest outdated APIs.
</Warning>