---
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.
