Skip to main content
You should have completed the Installation and Authentication sections before proceeding. If you haven’t, please complete them first.

​
How the Narada SDK Works

The Narada Python SDK uses two core objects:

Environment

An environment is the execution target. Use BrowserEnvironment for a local browser, CloudBrowserEnvironment for a hosted browser, RemoteBrowserEnvironment for an existing browser window, or LambdaEnvironment for cloud execution without browser actions.

Agent

An agent runs tasks inside an environment. Create Agent(environment=env) and call await agent.run(...) for natural-language automation.
Browser actions such as go_to_url(), agentic_selector(), and Google Sheets helpers are methods on Agent. Lifecycle details such as close(), browser_window_id, and cloud_browser_session_id are methods or properties on the environment.
You do not need to prefix prompts with /Operator when using Agent.run(). The default agent kind is AgentKind.OPERATOR, which adds the correct command prefix for browser automation.

​
Demo: Narada SDK in Action

Watch this demonstration of the complete SDK workflow:
This video demonstrates the complete workflow from initializing the SDK, through browser execution, to receiving results in Python.

​
Your First SDK Automation

Start with a simple local browser automation: 
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 "software engineering jobs" on Google and tell me how many results you find',
        )

        print("Automation completed!")
        print("Response:", response.text)
    finally:
        await env.close()


if __name__ == "__main__":
    asyncio.run(main())
The first time you run a local browser environment, the SDK opens Chrome and guides you through any missing extension or login setup. The environment initializes lazily on the first Agent.run() call or browser action.

​
Eagerly Initialize the Browser

You can call await env.start() when you need the browser window ID before running a task: 
import asyncio

from narada import Agent, BrowserEnvironment


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

    try:
        await env.start()
        print(f"Browser window ID: {env.browser_window_id}")

        response = await agent.run(
            prompt='Search for "Narada AI" and summarize the first result',
            generate_gif=True,
            clear_chat=True,
        )

        print("Response:", response.text)
    finally:
        await env.close()


if __name__ == "__main__":
    asyncio.run(main())
When generate_gif=True, Narada records the automation trajectory. Read more in Action Trace.

​
Structured Output

Use a Pydantic model when you need typed data instead of free-form text: 
import asyncio

from narada import Agent, BrowserEnvironment
from pydantic import BaseModel, Field


class JobSearchResult(BaseModel):
    total_jobs: int = Field(description="Total number of job listings found")
    location: str = Field(description="The location searched")
    top_company: str = Field(description="Name of the first company in results")


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

    try:
        response = await agent.run(
            prompt=(
                'Search for "software engineering jobs in Berkeley" and extract '
                "the job count, location, and first company name."
            ),
            output_schema=JobSearchResult,
            generate_gif=True,
        )

        job_data = response.structured_output
        assert job_data is not None

        print(f"Found {job_data.total_jobs} jobs in {job_data.location}")
        print(f"Top company: {job_data.top_company}")
    finally:
        await env.close()


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

​
Choose an Agent Kind

The default Agent uses AgentKind.OPERATOR, which is best for browser automation. Use AgentKind.CORE_AGENT for read-only reasoning and conversation-style tasks. 
import asyncio

from narada import Agent, AgentKind, BrowserEnvironment


async def main() -> None:
    env = BrowserEnvironment()
    operator = Agent(environment=env)
    core_agent = Agent(environment=env, kind=AgentKind.CORE_AGENT)

    try:
        await operator.go_to_url(url="https://example.com")

        page_summary = await core_agent.run(
            prompt="Summarize the visible content on this page.",
        )

        print(page_summary.text)
    finally:
        await env.close()


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

​
Error Handling

The SDK raises typed exceptions for common failures: 
import asyncio

from narada import (
    Agent,
    BrowserEnvironment,
    NaradaInitializationError,
    NaradaTimeoutError,
)


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

    try:
        response = await agent.run(
            prompt='Search for "AI research papers" and summarize the first result',
            timeout=60,
        )

        print("Response:", response.text)
    except NaradaTimeoutError:
        print("Task timed out. Try a simpler prompt or a longer timeout.")
        await agent.reset_agent_state()
    except NaradaInitializationError:
        print("Browser initialization failed. Check your extension setup.")
    finally:
        await env.close()


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

​
Troubleshooting

  1. Verify NARADA_API_KEY is set.
  2. Make sure Chrome is installed and up to date.
  3. Install and sign in to the Narada Chrome extension.
  4. Check your internet connection and firewall settings.
  1. Make prompts clear and specific.
  2. Increase timeout for complex tasks.
  3. Wait for slow pages to load before asking the agent to inspect them.
  4. Call await agent.reset_agent_state() after a timeout to cancel inflight work while preserving browser pages.

​
What’s Next?

Parallel Execution

Run multiple browser environments simultaneously

Error Handling

Handle timeouts, retries, and initialization errors

Structured Output

Extract typed data using Pydantic models

Action Trace

Capture and analyze automation workflows

​
Need Help?

GitHub Examples

Explore complete SDK examples

Support

Contact support for assistance