Skip to main content

​
Overview

When working with custom agents in Narada, you can provide input variables beyond the simple prompt string. This allows for more sophisticated data passing and enables your custom agents to access structured information during execution.

​
Video Walkthrough

Watch this demonstration of input variables in action:

​
Two Types of Variables

Narada supports two distinct variable mechanisms:

Secret Variables

For sensitive data (passwords, API keys). The LLM never sees the actual values. Substitution happens after the action plan is generated. Use ${variable_name} syntax in your prompt.

Input Variables

For custom agent parameters. These are visible to the agent and accessible in your custom agent workflow via the variables dictionary.

​
Secret Variables (Python SDK)

Use the variables parameter on the agent() method to pass sensitive values that should not be seen by the LLM: 
response = await window.agent(
    prompt="Log in with username ${user} and password ${pass}",
    variables={"user": "john@company.com", "pass": "s3cret_passw0rd"}
)
The LLM will see the placeholders ${user} and ${pass} but never the actual values. Substitution happens at action time.

​
Input Variables (Custom Agents)

When calling a custom agent with a simple prompt, the string becomes the $input_as_text variable: 
# Simple prompt - becomes $input_as_text variable
await window.agent(
    prompt="Search for the latest AI research papers",
    agent="/$USER/my-custom-agent"
)
In your custom agent workflow, this would be accessible as:
  • $input_as_text = “Search for the latest AI research papers”

​
Providing Multiple Input Variables

To provide more than just the $input_as_text value, use the inputVariables= format with a JSON object in the prompt: 
await window.agent(
    prompt="""
    inputVariables={
        "searchTerm": "artificial intelligence",
        "maxResults": 5,
        "includeAbstracts": true,
        "keywords": ["deep learning", "neural networks", "transformers"],
        "input_as_text": "Find recent AI papers"
    }
    """,
    agent="/$USER/research-assistant"
)

​
REST API

When calling the REST API directly, use the inputVariables and secretVariables body fields: 
{
  "prompt": "Log in and search for ${searchTerm}",
  "browserWindowId": "your-browser-window-id",
  "secretVariables": {"searchTerm": "confidential topic"},
  "inputVariables": {"maxResults": 5, "format": "csv"}
}

​
Variable Types

Input variables support basic JSON data types:

Strings

"searchTerm": "machine learning"
Text values for search terms, descriptions, etc.

Numbers

"maxResults": 10,
"threshold": 0.85
Integer and floating-point values for limits and scores.

Booleans

"includeImages": true,
"strictMode": false
True/false values for feature flags and options.

Arrays

"tags": ["ai", "ml", "research"],
"websites": ["site1.com", "site2.com"]
Lists of basic values like strings, numbers, or booleans.
Complex nested objects are not supported yet. Use only basic data types (strings, numbers, booleans) and arrays of basic types.

​
Best Practices

1

Use Descriptive Variable Names

Choose clear, descriptive names for your input variables:
# Good
"searchQuery": "AI research",
"maxResults": 10,
"includeMetadata": true

# Avoid
"q": "AI research",
"max": 10,
"meta": true
2

Include input_as_text When Needed

If your custom agent expects a main user query, include it explicitly:
inputVariables={
    "specificData": "some value",
    "input_as_text": "The main user instruction"
}
3

Validate JSON Format

Ensure your JSON is properly formatted. Use tools or linters to validate syntax:
# Properly escaped quotes and valid JSON structure
inputVariables={
    "message": "This is a \"quoted\" string",
    "data": {"nested": "value"}
}
4

Use Basic Data Types Only

Stick to basic data types - complex nested objects are not supported:
# Supported
inputVariables={
    "count": 5,                    # Number
    "enabled": true,               # Boolean
    "searchTerm": "AI research",   # String
    "tags": ["ai", "ml", "nlp"],   # Array of strings
    "scores": [0.8, 0.9, 0.7]      # Array of numbers
}

# Not supported
inputVariables={
    "config": {                    # Nested objects not supported
        "timeout": 30,
        "retries": 3
    }
}

​
Consuming Variables in Code

When writing workflow code (e.g., in Agent Studio), input variables are available via the variables dictionary, which is automatically injected at runtime. 
# Access a variable with a default fallback
search_term = variables.get("searchTerm", "default value")

# Access a variable (raises KeyError if missing)
search_term = variables["searchTerm"]
Always prefer variables.get("key", default) over variables["key"] so your workflow can run standalone without input variables.
from narada import Agent, LocalBrowserWindow
from pydantic import BaseModel

window = LocalBrowserWindow()

# Use variables.get() with sensible defaults from the recording context
target_url = variables.get("targetUrl", "https://example.com/search")
search_term = variables.get("searchTerm", "machine learning")
max_results = variables.get("maxResults", 10)

await window.go_to_url(url=target_url, new_tab=True)

class SearchResults(BaseModel):
    results: list[str]

resp = await window.agent(
    prompt=f"Search for '{search_term}' and extract the top {max_results} result titles",
    agent=Agent.OPERATOR,
    output_schema=SearchResults,
)

​
Next Steps

Parallel Execution

Learn how to run multiple custom agents with different input variables simultaneously

Error Handling

Implement robust error handling for custom agent workflows

Structured Output

Structure your output data with JSON schemas

API Reference

Explore the complete Window.agent() API documentation
Start with simple input variables and gradually add complexity as your custom agents become more sophisticated. This approach makes debugging easier and helps you understand which variables provide the most value.