> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narada.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Input Variables
> Pass reusable data into custom Narada agents
## 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.
Runtime values for custom agents. The agent can read them, reason about them, and use them in workflow steps.
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](/documentation/getting-started-with-sdk) for setup.
```python theme={null}
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:
```json theme={null}
{
"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`.
```python theme={null}
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:
```json theme={null}
{
"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.
```python theme={null}
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.
```json theme={null}
{
"searchTerm": "machine learning"
}
```
Use strings for search terms, labels, URLs, email addresses, and other text.
```json theme={null}
{
"maxResults": 10,
"threshold": 0.85
}
```
Use numbers for limits, scores, counters, and numeric settings.
```json theme={null}
{
"includeInactive": false,
"strictMode": true
}
```
Use booleans for on/off options.
```json theme={null}
{
"priority": "high"
}
```
If the workflow variable is declared as an enum, pass one of the allowed string values.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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": }`. 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:
```json theme={null}
{
"columnNames": ["Name", "Category", "Spend"],
"rows": [
["Northwind", "Logistics", "12000"],
["Contoso", "Software", "8500"]
]
}
```
or an array of objects with the same columns in every row:
```json theme={null}
[
{"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:
```text theme={null}
Search for {{$searchTerm}}.
Return at most {{$maxResults}} results.
```
For objects and arrays, use bracket access:
```text theme={null}
Customer: {{$customer["name"]}}
Renewal date: {{$customer["renewalDate"]}}
First keyword: {{$keywords[0]}}
```
For data tables, use a row index and column name:
```text theme={null}
First vendor: {{$vendors[0]["Name"]}}
First vendor spend: {{$vendors[0]["Spend"]}}
```
For Python agent code, see [Python Agents](/documentation/python-agents#using-input-variables). For Python Code steps inside GUI workflows, see [Agent Studio](/documentation/agent-studio#passing-variables-in-and-out).
## Best Practices
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.
Prefer descriptive names like `searchTerm`, `maxResults`, `customer`, and `vendors` over short names like `q`, `max`, or `data`.
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.
When using `inputVariables={...}` in the prompt text, keep the JSON valid and do not add extra text after the closing `}`.
Use a data table for spreadsheet-like rows. Use an object when you need nested configuration, grouped fields, or a single structured record.