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,
    time_zone: str = "America/Los_Angeles",
    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.
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
time_zone
str
default:"America/Los_Angeles"
The time zone for any time-related operations in the automation task.
time_zone="America/New_York"
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())

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

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