agent

The agent method provides a modern, streamlined interface for executing automation tasks in the Narada Python SDK. It returns a simplified AgentResponse object with cleaner error handling and better type safety compared to the legacy dispatch_request method.

The agent method is the recommended approach for new integrations. It provides a cleaner API surface and better developer experience than the legacy dispatch_request method.

Method Signature

async def agent(
    self,
    *,
    prompt: str,
    agent: Agent | str = Agent.OPERATOR,
    clear_chat: bool | None = None,
    generate_gif: bool | None = None,
    output_schema: type[BaseModel] | None = None,
    attachment: File | None = None,
    time_zone: str = "America/Los_Angeles",
    variables: dict[str, str] | None = None,
    timeout: int = 120,
) -> AgentResponse

Parameters

prompt

str

required

The natural language instruction for the automation task. When using the OPERATOR agent, commands are automatically prefixed with /Operator.

prompt="Search for 'machine learning jobs' and extract the first 5 results"

agent

Agent | str

default:"Agent.OPERATOR"

The agent to use for task execution. Choose from predefined agents or provide a custom agent name.

OPERATOR Agent
GENERALIST Agent
Custom Agent

Best for web automation tasks like clicking, navigating, and data extraction.

agent=Agent.OPERATOR  # Default

Best for general conversations and non-web-specific tasks.

agent=Agent.GENERALIST

Use a custom agent by providing a string name.

agent="CustomDataAnalyst"

clear_chat

bool | None

default:"None"

Whether to clear the chat history before executing the command. Useful for isolated tasks or continuing conversations.

clear_chat=True   # Start fresh (default behavior)
clear_chat=False  # Continue previous conversation

generate_gif

bool | None

default:"None"

Whether to capture an animated GIF of the automation process. GIFs are saved to your local Narada Downloads directory.

generate_gif=True  # Record automation workflow

output_schema

type[BaseModel] | None

default:"None"

A Pydantic model class defining the expected structure of the response. When provided, the agent will return structured data matching this schema.

from pydantic import BaseModel, Field

class JobListing(BaseModel):
    title: str = Field(description="Job title")
    company: str = Field(description="Company name")
    location: str = Field(description="Job location")

output_schema=JobListing

attachment

File | None

default:"None"

A file attachment to provide to the agent. Files must be uploaded first using the upload_file() method, which returns a File object that can be passed here.

# Upload a file first
with open("document.pdf", "rb") as f:
    file = await window.upload_file(file=f)

# Pass it to the agent
attachment=file

Attachments are particularly useful with the GENERALIST agent for document analysis, summarization, and question answering tasks.

time_zone

str

default:"America/Los_Angeles"

The time zone for any time-related operations in the automation task.

time_zone="America/New_York"

variables

dict[str, str] | None

default:"None"

A dictionary of variables for secure substitution in prompts. Variables protect sensitive data by performing substitution after the LLM generates its action plan, ensuring the LLM never sees the actual values.Use ${variable_name} syntax in your prompt, and provide the actual values in this dictionary. This is ideal for API keys, passwords, personal information, or any data you want to keep private from the LLM.

response = await window.agent(
    prompt="Search for ${search_term} and download the first PDF result",
    variables={"search_term": "confidential research topic"}
)

Variables are substituted at action time, after the LLM has planned its actions. The LLM will see the placeholder ${variable_name} but never the actual value.

timeout

int

default:"120"

Maximum time in seconds to wait for task completion before timing out.

timeout=180  # 3 minutes for complex tasks

Response

The method returns an AgentResponse object with the following structure:

status

str

The execution status: "success", "error", or "input-required"

text

str

The text response from the agent containing the results of the automation task

structured_output

BaseModel | None

When output_schema is provided, contains the parsed structured data matching your schema. None otherwise.

usage

AgentUsage

Contains usage metrics:

actions: Number of actions performed
credits: Credits consumed for the task

Examples

import asyncio
from narada import Narada

async def main():
    async with Narada() as narada:
        window = await narada.open_and_initialize_browser_window()

        # Simple web automation task
        response = await window.agent(
            prompt="Search for 'Python tutorials' on Google and get the title of the first result"
        )

        print(f"Status: {response.status}")
        print(f"Result: {response.text}")
        print(f"Actions used: {response.usage.actions}")

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

import asyncio
from narada import Narada
from pydantic import BaseModel, Field

class SearchResult(BaseModel):
    query: str = Field(description="The search query used")
    result_count: str = Field(description="Number of results found")
    top_result_title: str = Field(description="Title of the first result")
    top_result_url: str = Field(description="URL of the first result")

async def main():
    async with Narada() as narada:
        window = await narada.open_and_initialize_browser_window()

        # Extract structured data from web automation
        response = await window.agent(
            prompt="Search for 'AI research papers' and extract search details",
            output_schema=SearchResult
        )

        if response.status == "success" and response.structured_output:
            data = response.structured_output
            print(f"Query: {data.query}")
            print(f"Results: {data.result_count}")
            print(f"Top result: {data.top_result_title}")
            print(f"URL: {data.top_result_url}")

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

import asyncio
from narada import Agent, Narada

async def main():
    async with Narada() as narada:
        window = await narada.open_and_initialize_browser_window()

        # Start a conversation with the Generalist agent
        response = await window.agent(
            prompt="Pick a lucky number between 1 and 100 for me",
            agent=Agent.GENERALIST,
            clear_chat=True
        )
        print(f"Agent: {response.text}")

        # Continue the conversation
        response = await window.agent(
            prompt="What did you pick again?",
            agent=Agent.GENERALIST,
            clear_chat=False  # Maintain conversation context
        )
        print(f"Agent: {response.text}")

        # Ask a follow-up question
        response = await window.agent(
            prompt="What's double that number?",
            agent=Agent.GENERALIST,
            clear_chat=False
        )
        print(f"Agent: {response.text}")

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

import asyncio
from narada import Narada, NaradaTimeoutError

async def main():
    async with Narada() as narada:
        window = await narada.open_and_initialize_browser_window()

        max_attempts = 3
        for attempt in range(max_attempts):
            try:
                response = await window.agent(
                    prompt="Search for 'complex data analysis tutorial' and summarize the top 3 results",
                    timeout=60,  # 1 minute timeout
                    generate_gif=True  # Record for debugging
                )

                if response.status == "success":
                    print("Task completed successfully!")
                    print(f"Result: {response.text}")
                    break
                else:
                    print(f"Task failed with status: {response.status}")
                    break

            except NaradaTimeoutError:
                if attempt == max_attempts - 1:
                    print("Task failed after maximum attempts")
                    raise

                print(f"Attempt {attempt + 1} timed out, retrying...")
                # Reinitialize to cancel any inflight requests
                await window.reinitialize()

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

import asyncio
from narada import Narada
from pydantic import BaseModel, Field

class CompanyInfo(BaseModel):
    name: str = Field(description="Company name")
    industry: str = Field(description="Primary industry")
    employee_count: str = Field(description="Number of employees")
    headquarters: str = Field(description="Headquarters location")

async def main():
    async with Narada() as narada:
        window = await narada.open_and_initialize_browser_window()

        # Complex automation with structured output and recording
        response = await window.agent(
            prompt="Navigate to TechCorp's about page and extract company information",
            output_schema=CompanyInfo,
            generate_gif=True,
            timeout=180,  # 3 minutes for complex navigation
            time_zone="America/New_York"
        )

        print(f"Execution time: {response.usage.actions} actions")
        print(f"Credits used: {response.usage.credits}")

        if response.structured_output:
            company = response.structured_output
            print(f"Company: {company.name}")
            print(f"Industry: {company.industry}")
            print(f"Size: {company.employee_count}")
            print(f"Location: {company.headquarters}")

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

import asyncio
from narada import Narada

async def main():
    async with Narada() as narada:
        window = await narada.open_and_initialize_browser_window()

        # Use variables to protect sensitive credentials from the LLM
        # The LLM will see ${username} and ${password} but not the actual values
        response = await window.agent(
            prompt="Navigate to https://example-app.com/login and log in with username ${username} and password ${password}",
            variables={
                "username": "[email protected]",
                "password": "super_secret_password_123"
            }
        )

        print(f"Status: {response.status}")
        print(f"Result: {response.text}")

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

import asyncio
from narada import Agent, Narada
from pydantic import BaseModel, Field

class InvoiceData(BaseModel):
    invoice_number: str = Field(description="Invoice number")
    date: str = Field(description="Invoice date")
    vendor_name: str = Field(description="Vendor or supplier name")
    total_amount: str = Field(description="Total amount with currency")
    line_items: list[str] = Field(description="List of items or services")

async def main():
    async with Narada() as narada:
        window = await narada.open_and_initialize_browser_window()

        # Upload a file to extract structured data from it
        with open("/path/to/invoice.pdf", "rb") as f:
            file = await window.upload_file(file=f)

        # Extract structured information from the attached file
        response = await window.agent(
            prompt="Extract the invoice details from the attached document",
            agent=Agent.GENERALIST,
            attachment=file,
            output_schema=InvoiceData
        )

        invoice = response.structured_output
        print(f"Invoice: {invoice.invoice_number}")
        print(f"Date: {invoice.date}")
        print(f"Vendor: {invoice.vendor_name}")
        print(f"Total: {invoice.total_amount}")
        print(f"Items: {', '.join(invoice.line_items)}")

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

Agent Types

OPERATOR Agent

Best for web automation tasks

Clicking buttons and links
Filling forms
Navigating websites
Extracting data from pages
Downloading files

GENERALIST Agent

Best for conversational tasks

Answering questions
General conversation
Text analysis
Mathematical calculations
Creative writing

Best Practices

Choose the Right Agent

Use OPERATOR for web tasks and GENERALIST for conversation or analysis tasks

Structure Your Data

Define Pydantic schemas for consistent, typed responses from complex extractions

Protect Sensitive Data

Use variables for API keys, passwords, or personal info to prevent the LLM from seeing actual values

Analyze Documents

Upload files with upload_file() and pass as attachment for document analysis with the GENERALIST agent

Handle Timeouts Gracefully

Set appropriate timeouts and implement retry logic for complex or unreliable tasks

Record Complex Flows

Use generate_gif=True for debugging and documenting complex automation workflows

Migration from dispatch_request

If you’re migrating from the legacy dispatch_request method, here are the key differences:

Old dispatch_request
New agent method

# Legacy approach
response = await window.dispatch_request(
    prompt='/Operator search for "jobs" on Google'
)

# Manual response parsing
if response['status'] == 'success':
    text = response['response']['text']
    structured_data = response['response']['structuredOutput']

# Modern approach - no manual /Operator prefix needed
response = await window.agent(
    prompt='search for "jobs" on Google'
)

# Clean, typed response
if response.status == "success":
    text = response.text
    structured_data = response.structured_output

The agent method automatically handles agent prefixes, provides better error handling, and returns a cleaner response object with proper typing support.

Quickstart

API Endpoints

Python SDK

Method Signature

Parameters

Response

Examples

Agent Types

OPERATOR Agent

GENERALIST Agent

Best Practices

Choose the Right Agent

Structure Your Data

Protect Sensitive Data

Analyze Documents

Handle Timeouts Gracefully

Record Complex Flows

Migration from dispatch_request

Quickstart

API Endpoints

Python SDK

​Method Signature

​Parameters

​Response

​Examples

​Agent Types

OPERATOR Agent

GENERALIST Agent

​Best Practices

Choose the Right Agent

Structure Your Data

Protect Sensitive Data

Analyze Documents

Handle Timeouts Gracefully

Record Complex Flows

​Migration from dispatch_request

Method Signature

Parameters

Response

Examples

Agent Types

Best Practices

Migration from dispatch_request