Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.autosana.ai/llms.txt

Use this file to discover all available pages before exploring further.

Autosana has two types of variables that work together to make your flows flexible and data-driven:
  1. Environment Variables — Static configuration (credentials, URLs, feature flags) set before runs
  2. Runtime Variables — Dynamic values that accumulate during execution from hooks, flow/suite overrides, and the agent itself

​
Environment Variables

Environment variables are key-value pairs managed in Settings > Environments. They store static configuration like API keys, test credentials, and URLs.
  • Reference them in flow instructions and cURL hooks using ${env:VARIABLE_NAME}
  • Scripts access them via standard language methods (os.environ.get(), process.env, $VAR)
  • Can be stored as secrets (encrypted, never displayed in plain text)
  • The agent never sees the raw variable — only the resolved value substituted into instructions
See Environments for full details on creating and managing environment variables.

​
Runtime Variables

Runtime variables are dynamic values that build up during a run. They come from five sources, and all feed into the same pool:

​
Build Variables

Attached to a specific app build, either from your CI pipeline or the dashboard. These override environment variables for all flows that run against that build. When to use: You need to pass context from your CI pipeline into flow instructions — PR numbers, branch names, feature flags, deployment URLs, or any other build-specific data. How to set them from CI (GitHub Action): 
- uses: autosana/autosana-ci@main
  with:
    api-key: ${{ secrets.AUTOSANA_KEY }}
    platform: ios
    build-path: app.zip
    suite-ids: "uuid-here"
    variables: 'PR_NUMBER=${{ github.event.pull_request.number }},BRANCH=${{ github.head_ref }}'
How to set them from the API: Include a variables field in the request body of /api/ci/confirm-upload, /api/ci/upload-web-build, or /api/v1/flows/run. The value can be a string ("KEY1=VALUE1,KEY2=VALUE2") or a JSON object ({"KEY1": "VALUE1"}). How to set them from the dashboard:
  1. Go to Apps
  2. Expand the build history for an app
  3. Click the variables icon on any build
  4. Add key-value pairs and click Save Variables
You can also set variables when uploading a new build via the Advanced section in the upload dialog. How to use them in instructions: 
Navigate to the channel switcher. Enter pr-${env:PR_NUMBER} and apply.
The agent sees the resolved value (e.g., pr-42) and types it into the UI.

​
Suite Variables

Set in the suite editor before a run. These override environment variables for all flows in the suite. When to use: You want a different TEST_EMAIL or API_URL for a specific suite without changing the environment. How to set them:
  1. Edit your suite
  2. Expand the Advanced dropdown
  3. Add key-value pairs

​
Flow Variables

Set in the flow editor before a run. These override both suite variables and environment variables for that specific flow. When to use: One flow in a suite needs a different value than the rest — for example, a flow that tests a different API endpoint. How to set them:
  1. Edit your flow
  2. Expand the Advanced dropdown
  3. Add key-value pairs

​
Hook Exports

Hooks can export values by writing KEY=VALUE pairs to /tmp/autosana.env. These values become available to all subsequent hooks and flows in the suite. 
# In a setup hook (Python)
with open('/tmp/autosana.env', 'w') as f:
    f.write(f"AUTH_TOKEN={token}\n")
    f.write(f"USER_ID={user_id}\n")
See Sharing Data Between Hooks for full details and examples in all supported languages.

​
Agent Variables

The agent can dynamically save and retrieve values during flow execution. This is useful when the data you need doesn’t exist until the agent interacts with the app. Set Variable — Tell the agent to save a value it sees on screen: 
1. Navigate to the order confirmation page
2. Save the displayed order number as a variable called order_id
3. Navigate to the orders list
4. Verify that order_id appears in the list
Get Variable — Tell the agent to retrieve a previously saved value: 
1. Get the variable auth_token
2. Verify the token is displayed in the debug panel
The agent automatically knows which variables are currently set, so you can reference them by name in your instructions without having to list what exists. Use cases:
  • Saving a generated order ID, username, or confirmation number from the screen
  • Capturing dynamic data in one step and verifying it in a later step
  • Storing values that subsequent hooks or flows need
Very large values are stored and available to hooks and subsequent flows (via ${env:KEY}), but are not displayed to the agent when using Get Variable. Keep stored values concise — save specific data points (IDs, names, tokens) rather than large payloads.

​
Using Variables in Instructions

Use the ${env:VARIABLE_NAME} syntax to reference variables in flow instructions: 
Log in with ${env:TEST_EMAIL} and ${env:TEST_PASSWORD}
Navigate to ${env:API_URL}/settings
This syntax resolves all variable types — environment variables, suite variables, flow variables, and any runtime values (hook exports, agent-set values) that were set before the current flow started.
${env:KEY} is resolved once, before the agent starts running. This means it cannot reference values that the agent sets or that hooks export during the current flow. For those, use Get Variable in your instructions instead.For subsequent flows in a suite, ${env:KEY} works — runtime variables from earlier flows are available to later flows.

​
Variable Precedence

When multiple sources define the same variable name, later sources override earlier ones:
PrioritySourceSet by
HighestHook exports and agent-set variablesHook scripts, agent using Set Variable
HighFlow variablesFlow editor, before the run
MediumSuite variablesSuite editor, before the run
LowBuild variablesCI pipeline or dashboard, attached to the build
LowestEnvironment variablesSettings > Environments
For example, if your environment defines TEST_EMAIL=default@example.com and your suite defines TEST_EMAIL=suite@example.com, the suite value wins for all flows in that suite.
If both a hook and the agent set the same variable name, whichever runs last wins — there’s no fixed priority between them.

​
Cross-Flow Propagation in Suites

When flows run together in a suite, runtime variables from one flow automatically carry forward to the next. This lets you chain data across flows: Flow 1 — Agent captures data: 
1. Navigate to the product catalog
2. Save the name of the first product as a variable called product_name
3. Add it to the cart
Flow 2 — Uses the data from Flow 1 (via ${env:KEY}): 
1. Navigate to the search page
2. Search for ${env:product_name}
3. Verify search results show ${env:product_name}
Hook on Flow 2 — Also has access: 
import os

product_name = os.environ.get("product_name")
print(f"Verifying product: {product_name}")
All runtime variable types carry forward — suite variables, flow variables, hook exports, and values set by the agent.

​
Examples

​
Example 1: Dynamic Data Capture Within a Single Flow

Capture a value from the app and verify it later in the same flow: 
1. Navigate to the registration page
2. Fill in the form with a random email and submit
3. Save the displayed confirmation code as a variable called confirmation_code
4. Navigate to the verification page
5. Get the variable confirmation_code and enter it in the verification field
6. Verify the account is successfully verified

​
Example 2: Passing Data Between Flows in a Suite

Flow 1 — Create an order: 
1. Add "Wireless Mouse" to the cart
2. Complete checkout
3. Save the order number as a variable called order_number
Flow 2 — Verify the order (uses ${env:KEY}): 
1. Navigate to the order history page
2. Search for ${env:order_number}
3. Verify the order status shows "Processing"

​
Example 3: Agent Sets a Variable, Hook Uses It

Flow instructions: 
1. Log in and navigate to the profile page
2. Save the displayed username as a variable called current_username
Teardown hook (Python) — reads the saved variable: 
import os
import urllib.request

username = os.environ.get("current_username")
# Clean up test data for this user
req = urllib.request.Request(
    f"{os.environ.get('API_URL')}/users/{username}",
    method='DELETE',
    headers={'Authorization': f"Bearer {os.environ.get('ADMIN_TOKEN')}"}
)
urllib.request.urlopen(req)
print(f"Cleaned up user: {username}")

​
Next Steps