Input Variables

Overview

Input variables let you run the same custom agent with different data each time. Instead of hardcoding a customer name, date range, table of rows, or configuration object into the agent, pass that value at run time and let the workflow read it as a variable. Use input variables for data the agent is allowed to see. Use secret variables for credentials or other sensitive values that should be substituted later without exposing the value to the model.

Input Variables

Runtime values for custom agents. The agent can read them, reason about them, and use them in workflow steps.

Secret Variables

Sensitive values for prompt substitution. Use ${variable_name} syntax when the model should only see the placeholder.

The Default `chat_input` Variable

When you call a custom agent with a plain prompt, Narada stores that prompt in the chat_input input variable. The SDK examples on this page use a BrowserEnvironment; see Getting Started with the SDK for setup.

from narada import Agent, BrowserEnvironment

env = BrowserEnvironment()
agent = Agent(environment=env, kind="/$USER/research-assistant")

response = await agent.run(
    prompt="Search for the latest AI research papers",
)

Inside the custom agent, the run includes:

{
  "chat_input": "Search for the latest AI research papers"
}

Use chat_input for the main user instruction in new custom agents.

Before You Pass Variables

Declare the non-chat_input variables that the custom agent expects before you pass them at run time. In Agent Studio, add the variable to the custom agent and choose its type so Narada can validate incoming values and show the variable in the builder. Python custom agents should declare every non-chat_input value they read, because the agent’s variables dictionary is built from declared workflow variables. The declared type also tells Narada how to validate and coerce incoming values. For example, a declared number must receive a number, a declared enum must receive one of its allowed values, and a declared dataTable can receive one of the supported table shapes below.

Passing Multiple Variables

For direct SDK, REST API, and prompt-text custom-agent runs, there are two supported formats for passing more than chat_input. Use structured input variables for new SDK and REST API calls. Narada also supports the prompt text inputVariables={...} format for prompt-based runs.

SDK and REST API

When calling a custom agent from the SDK or REST API, pass an object whose keys match the variable names in the custom agent. In the Python SDK, use input_variables. In the REST API body, use inputVariables.

from narada import Agent, BrowserEnvironment

env = BrowserEnvironment()
agent = Agent(environment=env, kind="/$USER/vendor-reviewer")

response = await agent.run(
    prompt="Find vendors for the Q3 renewal cycle",
    input_variables={
        "region": "west",
        "maxResults": 10,
        "includeInactive": False,
    },
)

If you include chat_input in input_variables, Narada uses that value as the main instruction. If you omit it, the prompt text becomes chat_input. When calling the REST API directly, use the inputVariables body field:

{
  "prompt": "/$USER/vendor-reviewer Find vendors for the Q3 renewal cycle",
  "browserWindowId": "your-browser-window-id",
  "inputVariables": {
    "region": "west",
    "maxResults": 10,
    "includeInactive": false
  }
}

Prompt Text Format

Narada also supports putting variables directly in the prompt by appending inputVariables={...} with valid JSON. Prefer the structured input_variables argument or inputVariables REST body field when you can control the caller.

from narada import Agent, BrowserEnvironment

env = BrowserEnvironment()
agent = Agent(environment=env, kind="/$USER/vendor-reviewer")

response = await agent.run(
    prompt="""
Find vendors for the Q3 renewal cycle
inputVariables={
  "region": "west",
  "maxResults": 10,
  "includeInactive": false,
  "tags": ["renewal", "priority"]
}
""",
)

The text before inputVariables={...} becomes chat_input unless the JSON object already includes chat_input. If the JSON object includes chat_input, put inputVariables={...} at the start of the prompt with no leading instruction text.

The prompt text format must be valid JSON from the opening { through the end of the prompt. Do not add comments, trailing commas, or extra text after the closing }.

Supported Types

These are the common JSON-shaped input types for custom agents, including object and data table inputs. Agent Studio also has specialized variable types such as file, image, and cssSelectors for attachment and selector workflows; this page focuses on values you pass as JSON or Python data structures.

String

{
  "searchTerm": "machine learning"
}

Use strings for search terms, labels, URLs, email addresses, and other text.

Number

{
  "maxResults": 10,
  "threshold": 0.85
}

Use numbers for limits, scores, counters, and numeric settings.

Boolean

{
  "includeInactive": false,
  "strictMode": true
}

Use booleans for on/off options.

Enum

{
  "priority": "high"
}

If the workflow variable is declared as an enum, pass one of the allowed string values.

Array

{
  "keywords": ["ai", "ml", "research"],
  "scores": [0.8, 0.9, 0.7]
}

Use arrays for lists of values. Arrays can contain JSON values, including objects, when the workflow expects that shape.

Object

{
  "customer": {
    "name": "Acme Corp",
    "renewalDate": "2026-09-30",
    "contacts": [
      {"name": "Ari", "role": "Legal"},
      {"name": "Mina", "role": "Finance"}
    ]
  }
}

Use objects for grouped configuration or structured records. Nested objects and arrays are valid JSON input.

Data Table

{
  "vendors": {
    "columnNames": ["Name", "Category", "Spend"],
    "rows": [
      ["Northwind", "Logistics", "12000"],
      ["Contoso", "Software", "8500"]
    ]
  }
}

Use a data table variable when the workflow needs rows and columns for spreadsheet-like steps.

Data Table Shapes

A data table input is passed under the variable name, such as input_variables={"vendors": <table value>}. The table value itself can use either shape below. A declared dataTable variable accepts either the canonical table shape. In this shape, columnNames and every cell in rows must be strings:

{
  "columnNames": ["Name", "Category", "Spend"],
  "rows": [
    ["Northwind", "Logistics", "12000"],
    ["Contoso", "Software", "8500"]
  ]
}

or an array of objects with the same columns in every row:

[
  {"Name": "Northwind", "Category": "Logistics", "Spend": 12000},
  {"Name": "Contoso", "Category": "Software", "Spend": 8500}
]

For the array-of-objects shape, every row must have the same keys. Cell values may be strings, numbers, booleans, or null; Narada converts accepted cells to strings in the table, and null becomes an empty cell. Missing keys, extra keys, nested objects, and nested arrays are rejected. An empty array ([]) is also accepted and creates an empty table.

Referencing Variables in Agent Studio

In GUI workflow steps, reference input variables with the same variable syntax used for other workflow variables:

Search for {{$searchTerm}}.
Return at most {{$maxResults}} results.

For objects and arrays, use bracket access:

Customer: {{$customer["name"]}}
Renewal date: {{$customer["renewalDate"]}}
First keyword: {{$keywords[0]}}

For data tables, use a row index and column name:

First vendor: {{$vendors[0]["Name"]}}
First vendor spend: {{$vendors[0]["Spend"]}}

For Python agent code, see Python Agents. For Python Code steps inside GUI workflows, see Agent Studio.

Best Practices

Declare variables in the custom agent

Define each expected non-chat_input input variable on the custom agent so Narada can validate its type before the run starts and make it available in Studio and Python agent code.

Use clear variable names

Prefer descriptive names like searchTerm, maxResults, customer, and vendors over short names like q, max, or data.

Use `chat_input` for the main instruction

If the agent has one primary user instruction plus supporting data, put the instruction in chat_input and keep the other keys focused on structured inputs.

Keep prompt-embedded JSON strict

When using inputVariables={...} in the prompt text, keep the JSON valid and do not add extra text after the closing }.

Use data tables for rows, not nested objects

Use a data table for spreadsheet-like rows. Use an object when you need nested configuration, grouped fields, or a single structured record.

Next Steps

Python Agents

Read input variables from Python agent code

Python Code Steps

Use workflow variables inside Python Code steps

Agent Studio Variables

Reference variables in GUI workflow steps

Remote Dispatch

Pass input variables through the REST API

​Overview

Input Variables

Secret Variables

​The Default chat_input Variable

​Before You Pass Variables

​Passing Multiple Variables

​SDK and REST API

​Prompt Text Format

​Supported Types

String

Number

Boolean

Enum

Array

Object

Data Table

​Data Table Shapes

​Referencing Variables in Agent Studio

​Best Practices

​Next Steps

Python Agents

Python Code Steps

Agent Studio Variables

Remote Dispatch

Overview

The Default `chat_input` Variable

Before You Pass Variables

Passing Multiple Variables

SDK and REST API

Prompt Text Format

Supported Types

Data Table Shapes

Referencing Variables in Agent Studio

Best Practices

Next Steps