Skip to main content
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
​
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

  • Basic Web Automation
  • Structured Data Extraction
  • Conversational Agent
  • Error Handling & Timeouts
  • Advanced Configuration
  • Secure Variables
  • File Attachments
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())

​
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']
The agent method automatically handles agent prefixes, provides better error handling, and returns a cleaner response object with proper typing support.
⌘I