run

Agent.run() executes a natural-language task in a Narada environment and returns an AgentResponse. Create an environment first, then bind an agent to it:

from narada import Agent, BrowserEnvironment

env = BrowserEnvironment()
agent = Agent(environment=env)

response = await agent.run(prompt="Search for Narada AI and summarize the first result.")
print(response.text)

Agent.run() is the current SDK interface. The older Narada().open_and_initialize_browser_window() and window.agent(...) pattern is no longer the recommended API.

Constructor

class Agent:
    def __init__(
        self,
        *,
        environment: Environment,
        kind: AgentKind | str = AgentKind.OPERATOR,
    ) -> None: ...

Run Signature

async def run(
    self,
    prompt: str,
    *,
    reasoning: ReasoningEffort | None = None,
    clear_chat: bool | None = None,
    generate_gif: bool | None = None,
    output_schema: type[BaseModel] | None = None,
    previous_request_id: str | None = None,
    chat_history: list[RemoteDispatchChatHistoryItem] | None = None,
    additional_context: dict[str, str] | None = None,
    attachment: File | IO[Any] | None = None,
    time_zone: str = "America/Los_Angeles",
    user_resource_credentials: UserResourceCredentials | None = None,
    mcp_servers: list[McpServer] | None = None,
    secret_variables: dict[str, str] | None = None,
    input_variables: Mapping[str, Any] | None = None,
    callback_url: str | None = None,
    callback_secret: str | None = None,
    callback_headers: Mapping[str, Any] | None = None,
    on_input_required: InputRequiredCallback | None = None,
    critic: CriticConfig | None = None,
    timeout: int = 1000,
) -> AgentResponse

Agent Kinds

Choose the agent kind when constructing Agent.

AgentKind | str

default:"AgentKind.OPERATOR"

The agent to use for task execution.

OPERATOR
CORE_AGENT
PRODUCTIVITY
Custom Agent

Best for browser automation tasks like clicking, navigating, filling forms, and extracting data from pages.

from narada import Agent, AgentKind

agent = Agent(environment=env, kind=AgentKind.OPERATOR)

Best for read-only reasoning, answering questions about page content, and conversation-style tasks.

from narada import Agent, AgentKind

agent = Agent(environment=env, kind=AgentKind.CORE_AGENT)

Best for general productivity and non-browser-specific tasks.

from narada import Agent, AgentKind

agent = Agent(environment=env, kind=AgentKind.PRODUCTIVITY)

Invoke custom agents created in Agent Studio using the namespaced format.

# Use $USER shorthand for your own account.
agent = Agent(environment=env, kind="/$USER/my-data-analyst")

# Or reference a shared agent explicitly.
agent = Agent(environment=env, kind="/jane@company.com/sales-report-generator")

The same syntax works in the Narada chat side panel:

/$USER/my-agent Search for recent tech news
/jane@company.com/research-bot Find papers on transformers

Agents must be shared or published in Agent Studio before other users can invoke them.

Parameters

str

required

The natural-language instruction for the task. When using AgentKind.OPERATOR, Narada applies the correct Operator prefix automatically.

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

ReasoningEffort | None

default:"None"

Controls how much reasoning the Core Agent uses before responding. This option is only valid with AgentKind.CORE_AGENT.

from narada import AgentKind, ReasoningEffort

agent = Agent(environment=env, kind=AgentKind.CORE_AGENT)
response = await agent.run(
    prompt="Analyze the page and explain the pricing model.",
    reasoning=ReasoningEffort.MEDIUM,
)

bool | None

default:"None"

Whether to clear chat context before executing the command.

clear_chat=True

bool | None

default:"None"

Whether to capture an animated GIF of the automation trajectory.

generate_gif=True

type[BaseModel] | None

default:"None"

A Pydantic model class defining the expected structured response.

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")

response = await agent.run(
    prompt="Extract the first job listing.",
    output_schema=JobListing,
)

str | None

default:"None"

The prior request ID to continue a conversation.

first = await agent.run(prompt="Pick a lucky number.")
second = await agent.run(
    prompt="What number did you pick?",
    previous_request_id=first.request_id,
)

File | IO[Any] | None

default:"None"

A file-like object to attach to the request. The SDK uploads the file automatically before dispatching the task.

with open("document.pdf", "rb") as f:
    response = await agent.run(
        prompt="Summarize the attached document.",
        attachment=f,
    )

str

default:"America/Los_Angeles"

The time zone for time-related operations.

time_zone="America/New_York"

list[McpServer] | None

default:"None"

MCP servers to connect during task execution.

from narada_core.models import AuthenticationNone, McpServer

mcp_server = McpServer(
    url="https://your-mcp-server.example.com",
    label="My MCP Server",
    description="Custom tools",
    authentication=AuthenticationNone(),
)

response = await agent.run(
    prompt="Use the MCP tools to process this data.",
    mcp_servers=[mcp_server],
)

dict[str, str] | None

default:"None"

Sensitive values substituted at action time. The LLM sees placeholders such as ${password}, not the actual values.

response = await agent.run(
    prompt="Log in with username ${username} and password ${password}.",
    secret_variables={
        "username": "john.doe@company.com",
        "password": "super_secret_password_123",
    },
)

Mapping[str, Any] | None

default:"None"

Values passed into prompts using {{$variable_name}} syntax. File-like values are uploaded automatically.

response = await agent.run(
    prompt="Summarize {{$doc}}.",
    input_variables={"doc": file_obj},
)

str | None

default:"None"

URL to call when the task status changes or completes. Use this with callback_secret or callback_headers to authenticate callbacks.

InputRequiredCallback | None

default:"None"

Callback invoked when a task enters an input-required state.

CriticConfig | None

default:"None"

Optional critic configuration that validates the run after the main agent finishes.

int

default:"1000"

Maximum time in seconds to wait for task completion.

timeout=180

Response

Agent.run() returns an AgentResponse object:

str

Unique identifier for this request. Use it for debugging, callbacks, or conversation continuation.

str

Execution status: "success", "error", or "input-required".

str

The text response from the agent.

BaseModel | None

Parsed structured data when output_schema is provided. Otherwise None.

TextOutput | StructuredOutput

Discriminated union containing either text or structured data:

{ type: "text", content: string }
| { type: "structured", content: object }

AgentUsage

Usage metrics:

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

ActionTrace | None

Detailed log of agent actions. Top-level action trace entries include start_ts, end_ts, and duration_ms fields. See Action Trace for the trace format and timing semantics.

dict | None

Workflow-level trace data when available.

CriticResult | None

Result from the optional critic step.

Examples

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 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}")
    finally:
        await env.close()


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

import asyncio

from narada import Agent, BrowserEnvironment
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() -> None:
    env = BrowserEnvironment()
    agent = Agent(environment=env)

    try:
        response = await agent.run(
            prompt="Search for AI research papers and extract search details",
            output_schema=SearchResult,
        )

        data = response.structured_output
        assert data is not None

        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}")
    finally:
        await env.close()


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

import asyncio

from narada import Agent, AgentKind, BrowserEnvironment


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

    try:
        response = await agent.run(
            prompt="Pick a lucky number between 1 and 100 for me.",
        )
        print("Agent:", response.text)

        response = await agent.run(
            prompt="What did you pick again?",
            previous_request_id=response.request_id,
        )
        print("Agent:", response.text)

        response = await agent.run(
            prompt="What's double that number?",
            previous_request_id=response.request_id,
        )
        print("Agent:", response.text)
    finally:
        await env.close()


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

import asyncio

from narada import Agent, BrowserEnvironment, NaradaTimeoutError


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

    try:
        max_attempts = 3
        for attempt in range(max_attempts):
            try:
                response = await agent.run(
                    prompt="Search for complex data analysis tutorials and summarize the top 3 results",
                    timeout=60,
                    generate_gif=True,
                )

                print("Task completed successfully!")
                print(response.text)
                break
            except NaradaTimeoutError:
                if attempt == max_attempts - 1:
                    raise

                print(f"Attempt {attempt + 1} timed out, retrying...")
                await agent.reset_agent_state()
    finally:
        await env.close()


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

import asyncio

from narada import Agent, AgentKind, BrowserEnvironment
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() -> None:
    env = BrowserEnvironment()
    agent = Agent(environment=env, kind=AgentKind.CORE_AGENT)

    try:
        with open("/path/to/invoice.pdf", "rb") as f:
            response = await agent.run(
                prompt="Extract the invoice details from the attached document.",
                attachment=f,
                output_schema=InvoiceData,
            )

        invoice = response.structured_output
        assert invoice is not None

        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)}")
    finally:
        await env.close()


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

import asyncio

from narada import Agent, BrowserEnvironment


async def main() -> None:
    env = BrowserEnvironment()
    agent = Agent(environment=env, kind="/$USER/my-research-agent")

    try:
        response = await agent.run(
            prompt="Search for recent machine learning papers.",
        )
        print(response.text)
    finally:
        await env.close()


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

Best Practices

Reuse Environments

Create one environment and reuse it across multiple Agent instances when tasks should share a browser session.

Choose the Agent Kind

Use AgentKind.OPERATOR for browser automation and AgentKind.CORE_AGENT for read-only reasoning or conversation.

Use Structured Output

Define Pydantic schemas for consistent, typed responses from data extraction tasks.

Protect Sensitive Data

Use secret_variables for passwords, API keys, or personal information that should not be exposed to the LLM.

Pass Files Directly

Pass file-like objects with attachment= instead of calling a separate upload method.

Handle Timeouts

Set appropriate timeouts and call agent.reset_agent_state() before retrying after a timeout.

Migration from Older SDKs

Older SDK examples used a Narada client and window object:

async with Narada() as narada:
    window = await narada.open_and_initialize_browser_window()
    response = await window.agent(prompt='search for "jobs" on Google')

Use an environment and agent instead:

env = BrowserEnvironment()
agent = Agent(environment=env)

try:
    response = await agent.run(prompt='search for "jobs" on Google')
    print(response.text)
finally:
    await env.close()

For browser actions, call methods on agent:

await agent.go_to_url(url="https://example.com")
await agent.agentic_selector(
    action={"type": "click"},
    selectors={"aria_label": "Submit"},
    fallback_operator_query="click the Submit button",
)

For lifecycle and IDs, use the environment:

await env.start()
print(env.browser_window_id)
await env.close()

Quickstart

API Endpoints

Python SDK

Constructor

Run Signature

Agent Kinds

Parameters

Response

Examples

Best Practices

Reuse Environments

Choose the Agent Kind

Use Structured Output

Protect Sensitive Data

Pass Files Directly

Handle Timeouts

Migration from Older SDKs

​Constructor

​Run Signature

​Agent Kinds

​Parameters

​Response

​Examples

​Best Practices

Reuse Environments

Choose the Agent Kind

Use Structured Output

Protect Sensitive Data

Pass Files Directly

Handle Timeouts

​Migration from Older SDKs

Constructor

Run Signature

Agent Kinds

Parameters

Response

Examples

Best Practices

Migration from Older SDKs