Variables System

The AMAS Variables System provides a powerful way to define, populate, and use dynamic values throughout your agent configurations. Variables can be populated from user inputs, agent structured outputs, or defined with static defaults.

Overview

Variables enable:

Dynamic prompts - Inject context into agent system prompts using {{ variables.name }}
Input overrides - User-provided inputs override variable defaults at runtime
Automatic population - Extract data from agent structured outputs via variable_assignments
Persistence - Variables persist across executions when using checkpoints

Defining Variables

Variables are defined in the variables section of your configuration:

variables:
  customer_name:
    type: "str"
    description: "Customer name extracted from conversation"
  
  priority:
    type: "str"
    default: "medium"
  
  max_retries:
    type: "int"
    default: 3

Variable Properties

Property	Type	Default	Required	Description
`type`	string	—	Yes	Data type using BAML type notation: `str`, `int`, `float`, `bool`, `list[str]`, `list[int]`, `dict[str, int]`, `str \| None`, etc.
`default`	any	`null`	No	Default value if not provided. Supports template syntax like `{{ variables.key }}`.
`description`	string	`null`	No	Human-readable description (shown in UI and playground).
`required`	boolean	`true`	No	If `true`, variable must be provided or have a default value. If `false`, a `default` must be set — omitting both causes a validation error.
`require_every_execution`	boolean	`false`	No	If `true`, variable must be provided on every execution request. Checkpoint values are ignored.
`mode`	string	`"replace"`	No	Assignment mode: `"replace"` (overwrite previous value) or `"concat"` (append to existing value).
`separator`	string	`" "`	No	Separator string used when `mode="concat"` to join existing and new values.

If required is false and no default is set, validation will fail with: “Variable must either be required=True or have a default value set”.

Variable Lifecycle

Understanding when variables are required is crucial for proper configuration:

Session-Level Variables

These are required on the first execution only and persist via checkpoints:

variables:
  current_user_id:
    type: "str"
    required: true
    description: "User ID (persists after first execution)"

When the user provides inputs: {"current_user_id": "user_123"}, this value is stored in the variable and persists across subsequent executions.

Set once at session start
Persist across all subsequent executions in the session
Ideal for: user identity, session context, preferences

Request-Level Variables

These must be provided on every execution:

variables:
  current_query:
    type: "str"
    require_every_execution: true
    description: "User's query (must be provided every time)"

Fresh value required for each request
Checkpoint values are ignored for these variables
Ideal for: user messages, request-specific data

Providing Inputs

Inputs are values provided at runtime that override variable defaults. The input key must match the variable name.

Via REST API

Send inputs in the request body:

curl -X POST /api/v1/sessions/{session_id}/execute \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Help me with my order",
    "inputs": {
      "current_user_id": "user_123",
      "current_department": "support",
      "current_query": "Help me with my order"
    }
  }'

The inputs object keys correspond directly to variable names defined in your configuration.

Via Playground UI

Use the Variable Inputs panel to provide values:

Click the input field next to each variable
Enter the value
Variables with required: true must be filled before execution
Variables with defaults show the default value as placeholder

The Variable Inputs panel shows all defined variables with their descriptions and current values.

Using Variables in Prompts

Reference variables in agent prompts using Jinja2 syntax:

agents:
  - name: support_agent
    prompt_config:
      system_prompt: |
        You are a support agent for {{ variables.company_name }}.
        
        Current User: {{ variables.current_user_id }}
        Department: {{ variables.current_department }}
        
        Customer Query: "{{ variables.current_query }}"
        Customer Name: {{ variables.customer_name }}
        Priority Level: {{ variables.priority }}

Template Syntax

Variables are accessed in system_prompt using {{ variables.name }} syntax. The substitution engine also supports other template variables — see Prompt Configuration for the full list.

Syntax	Description	Example
`{{ variables.name }}`	Access a variable value	`{{ variables.customer_name }}`
`{{ user_input }}`	Current user message text	`{{ user_input }}`
`{{ agent_name.output.field }}`	Structured output field from another agent	`{{ analyzer.output.priority }}`
`{{ agent_name.output }}`	Last text output from another agent	`{{ researcher.output }}`

The substitution engine uses regex-based {{ ... }} matching, not Jinja2 filters. Expressions like {{ variables.name | default('x') }} are not supported. Unknown variables resolve to an empty string.

Reserved Variable Names

The following names cannot be used for custom variables: user_input, history, full_history, prompts, variables. Using a reserved name causes a validation error.

Variable Assignments

The most powerful feature: automatically populate variables from agent structured outputs.

How It Works

Agent generates structured output using structured_output configuration
Variable assignments map output fields to variables
Downstream agents receive populated variables in their prompts

Configuration

agents:
  - name: analyzer
    structured_output:
      enabled: true
      schema:
        customer:
          type: "str"
          description: "Customer name mentioned"
        priority_level:
          type: "str"
          description: "Urgency level (low, medium, high, urgent)"
        order_number:
          type: "str"
          description: "Order ID if mentioned"
    
    # Map structured output fields to variables
    variable_assignments:
      customer_name: "analyzer.output.customer"
      priority: "analyzer.output.priority_level"
      order_id: "analyzer.output.order_number"

Assignment Patterns

Variable assignments support three patterns:

1. Structured output field (most common)

variable_assignments:
  customer_name: "analyzer.output.customer"
  priority: "analyzer.output.priority_level"

variable_name — The variable to populate (must be defined in variables)
agent_name — The agent that produces the output
output — Fixed keyword
field_name — The field from the structured output schema

2. Non-structured agent output

variable_assignments:
  agent_summary: "summarizer.output"

Assigns the text content of the agent’s last message. Useful for agents without structured output.

3. Static value assignment

variable_assignments:
  threshold: 0.85
  max_retries: 10
  greeting: "Hello"
  is_active: true

Assigns a constant value directly. Type is validated against the variable’s declared type.

Nested Fields

For nested structured output data, use dot-separated paths:

variable_assignments:
  customer_name: "analyzer.output.customer.name"
  customer_email: "analyzer.output.customer.email"

Type Coercion

During variable assignment, values are automatically coerced to match the type specified in your variable definition. This means you can assign strings from user input or non-structured agent output, and the system will intelligently convert them:

Numbers: Strings like "42" become 42 (int), "3.14" becomes 3.14 (float)
Booleans: Strings like "true" or "1" become true; "false" or "0" become false
Collections: Valid JSON strings are parsed into dict or list types (e.g., list[str])

If type coercion fails, the system safely falls back to the original raw value. This coercion applies seamlessly to dynamic outputs, static values, and the final combined string when using concat mode.

Concat Mode Example

Build a progressive story where each agent adds a sentence:

variables:
  story:
    type: "str"
    default: "Once upon a time"
    mode: "concat"
    separator: " "
    description: "Story built progressively"

agents:
  - name: storyteller
    structured_output:
      enabled: true
      schema:
        sentence:
          type: "str"
          description: "Next sentence in the story"
    
    variable_assignments:
      story: "storyteller.output.sentence"
    
    prompt_config:
      system_prompt: |
        Continue this story with ONE sentence:
        {{ variables.story }}

Execution flow:

Initial: "Once upon a time"
After run 1: "Once upon a time there was a brave knight."
After run 2: "Once upon a time there was a brave knight. He embarked on a quest."
After run 3: "Once upon a time there was a brave knight. He embarked on a quest. The journey was perilous."

Best Practices

1. Use Descriptive Names

# ✅ Good
variables:
  customer_email:
    type: "str"
    description: "Customer's email address for follow-up"

# ❌ Avoid
variables:
  ce:
    type: "str"

2. Provide Helpful Descriptions

Descriptions appear in the UI and help users understand what to provide:

variables:
  current_query:
    type: "str"
    require_every_execution: true
    description: "The user's question or request for this interaction"

3. Set Sensible Defaults

variables:
  priority:
    type: "str"
    default: "medium"  # Reasonable fallback
  
  max_retries:
    type: "int"
    default: 3

4. Separate Session vs Request Variables

Clearly distinguish between persistent and per-request variables:

variables:
  # SESSION-LEVEL (comment for clarity)
  # Provided once on first execution, then persists
  user_id:
    type: "str"
    required: true
  
  # REQUEST-LEVEL (comment for clarity)
  # Must be provided on every execution
  current_message:
    type: "str"
    require_every_execution: true

5. Validate Required Variables

Use required: true for critical session variables:

variables:
  api_key:
    type: "str"
    required: true
    description: "API key for external service (required)"

Troubleshooting

Variable Not Populated

Symptom: Variable shows empty or default value in prompt Causes:

Agent didn’t produce structured output
Assignment path is incorrect
Field name doesn’t match schema

Solution: Check the agent’s structured output schema matches the assignment path:

# Schema defines "customer_name"
structured_output:
  schema:
    customer_name:  # ← Field name
      type: "str"

# Assignment must match
variable_assignments:
  customer: "agent.output.customer_name"  # ← Must match schema field

Required Variable Error

Symptom: “Required variable ‘X’ not provided” Cause: Variable with required: true wasn’t provided in inputs Solution: Provide the variable in your API request or UI:

{
  "inputs": {
    "user_id": "your_value_here"
  }
}

Variables Not Persisting

Symptom: Variables reset between executions Cause: persistent_state not enabled or using new session Solution: Enable checkpoints in configuration:

persistent_state: true

API Reference

Variable Definition Schema

variable_name:
  type: "str"                      # Required. BAML type notation.
  default: "value"                 # Optional. Default value.
  description: "Human-readable"    # Optional. Shown in UI.
  required: true                   # Optional. Default: true.
  require_every_execution: false   # Optional. Default: false.
  mode: "replace"                  # Optional. "replace" or "concat". Default: "replace".
  separator: " "                   # Optional. Used with mode="concat". Default: " ".

Variable Assignment Schema

variable_assignments:
  var_name: "agent.output.field"   # Dynamic: structured output field
  var_name: "agent.output"         # Dynamic: non-structured output (text)
  var_name: 42                     # Static: constant value

Execution Request

{
  "message": "User's question",
  "inputs": {
    "variable_name": "value"
  }
}

Supported Types

All types supported by the BAML type parser:

Type	Description	Example
`str`	Text string	`"hello"`
`int`	Integer	`42`
`float`	Decimal number	`3.14`
`bool`	Boolean	`true`
`list[str]`	List of strings	`["a", "b"]`
`list[int]`	List of integers	`[1, 2, 3]`
`dict[str, int]`	Dictionary	`{"a": 1}`
`str \| None`	Nullable string	`"hello"` or `null`
`Optional[str]`	Nullable string (alternate syntax)	`"hello"` or `null`
`Any`	Any type	—

​Variables System

​Overview

​Defining Variables

​Variable Properties

​Variable Lifecycle

​Session-Level Variables

​Request-Level Variables

​Providing Inputs

​Via REST API

​Via Playground UI

​Using Variables in Prompts

​Template Syntax

​Reserved Variable Names

​Variable Assignments

​How It Works

​Configuration

​Assignment Patterns

​1. Structured output field (most common)

​2. Non-structured agent output

​3. Static value assignment

​Nested Fields

​Type Coercion

​Concat Mode Example

​Best Practices

​1. Use Descriptive Names

​2. Provide Helpful Descriptions

​3. Set Sensible Defaults

​4. Separate Session vs Request Variables

​5. Validate Required Variables

​Troubleshooting

​Variable Not Populated

​Required Variable Error

​Variables Not Persisting

​API Reference

​Variable Definition Schema

​Variable Assignment Schema

​Execution Request

​Supported Types

Variables System

Overview

Defining Variables

Variable Properties

Variable Lifecycle

Session-Level Variables

Request-Level Variables

Providing Inputs

Via REST API

Via Playground UI

Using Variables in Prompts

Template Syntax

Reserved Variable Names

Variable Assignments

How It Works

Configuration

Assignment Patterns

1. Structured output field (most common)

2. Non-structured agent output

3. Static value assignment

Nested Fields

Type Coercion

Concat Mode Example

Best Practices

1. Use Descriptive Names

2. Provide Helpful Descriptions

3. Set Sensible Defaults

4. Separate Session vs Request Variables

5. Validate Required Variables

Troubleshooting

Variable Not Populated

Required Variable Error

Variables Not Persisting

API Reference

Variable Definition Schema

Variable Assignment Schema

Execution Request

Supported Types