> ## 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.
# Getting Started with the SDK
> Step-by-step guide to using the Narada Python SDK with practical examples
You should have completed the [Installation](/documentation/installation) and
[Authentication](/documentation/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:
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.
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:
```python theme={null}
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:
```python theme={null}
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](/documentation/action-trace).
## Structured Output
Use a Pydantic model when you need typed data instead of free-form text:
```python theme={null}
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.
```python theme={null}
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:
```python theme={null}
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?
Run multiple browser environments simultaneously
Handle timeouts, retries, and initialization errors
Extract typed data using Pydantic models
Capture and analyze automation workflows
## Need Help?
Explore complete SDK examples
Contact support for assistance