Using Variables in REST API

Variables allow you to inject dynamic values into your agent prompts. You can provide session-level variables once and have them persist across multiple requests, or request-level variables that must be provided fresh on each execution.

Overview

When executing a message in a session, you can pass variable values using the inputs field in your request body. Variables are substituted into your agent’s system prompts and used throughout the execution.

Request Body Structure

{
  "content": "Your message here",
  "inputs": {
    "variable_name_1": "value1",
    "variable_name_2": 42,
    "variable_name_3": true
  }
}

The inputs object contains key-value pairs where:

Key: Variable name (must match a variable defined in your agent configuration)
Value: The value for that variable (string, number, boolean, array, or object)

Variable Types: Session vs Request Level

Session-Level Variables

Session-level variables are provided once on the first execution and automatically persist across subsequent requests using checkpoints. When to use: User ID, session context, configuration that doesn’t change.

Configuration
First Request
Second Request

variables:
  user_id:
    type: "str"
    required: true
    description: "The user's unique identifier"
  
  user_department:
    type: "str"
    required: true
    description: "User's department (billing, support, etc)"

curl -X POST https://api-be.atthene.com/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello, I need help",
    "inputs": {
      "user_id": "user_12345",
      "user_department": "billing"
    }
  }'

curl -X POST https://api-be.atthene.com/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I have another question",
    "inputs": {}
  }'

user_id and user_department are automatically loaded from the session checkpoint.

Request-Level Variables

Request-level variables must be provided on every execution. Checkpoint values are ignored. When to use: User messages, search queries, form submissions—anything that changes per request.

Configuration
Every Request

variables:
  current_query:
    type: "str"
    require_every_execution: true
    description: "The user's current search or question"

# First request
curl -X POST https://api-be.atthene.com/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "current_query": "What is your refund policy?"
    }
  }'

# Second request - must provide current_query again
curl -X POST https://api-be.atthene.com/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "current_query": "Do you have free shipping?"
    }
  }'

Complete Example: Conversational Support Agent

This example shows a support agent that uses both session-level and request-level variables.

Configuration

persistent_state: true

variables:
  # Session-level: provided once, persists
  user_id:
    type: "str"
    required: true
    description: "Customer ID"
  
  user_email:
    type: "str"
    required: true
    description: "Customer email address"
  
  # Request-level: provided every time
  current_message:
    type: "str"
    require_every_execution: true
    description: "The customer's current message"
  
  # Dynamic: auto-populated by agent
  extracted_issue_type:
    type: "str"
    description: "Issue type extracted by analyzer agent"

agents:
  - name: analyzer
    agent_type: llm_agent
    prompt_config:
      system_prompt: |
        You are a support agent analyzer.
        Customer ID: {{ variables.user_id }}
        Customer Email: {{ variables.user_email }}
        
        Analyze this message and extract the issue type:
        {{ variables.current_message }}
    
    structured_output:
      enabled: true
      schema:
        issue_type:
          type: "str"
          description: "Type of issue (billing, technical, shipping, other)"
    
    variable_assignments:
      extracted_issue_type: "analyzer.output.issue_type"
  
  - name: responder
    agent_type: llm_agent
    prompt_config:
      system_prompt: |
        You are a helpful support agent for our company.
        
        Customer Details:
        - ID: {{ variables.user_id }}
        - Email: {{ variables.user_email }}
        
        Their Issue: {{ extracted_issue_type }}
        Their Message: {{ variables.current_message }}
        
        Provide a helpful, personalized response.

edges:
  - from: "__start__"
    to: analyzer
  - from: analyzer
    to: responder
  - from: responder
    to: "__end__"

entry_point: "analyzer"

First Request: Initialize Session

curl -X POST https://api-be.atthene.com/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello",
    "inputs": {
      "user_id": "CUST_12345",
      "user_email": "john@example.com",
      "current_message": "I was charged twice for my last order"
    }
  }'

Response:

{
  "success": true,
  "message_id": "msg_789",
  "response": {
    "content": "I sincerely apologize for the duplicate charge. I've located your order and can see the billing error. Let me help you get this resolved immediately..."
  }
}

Second Request: Continue Conversation

curl -X POST https://api-be.atthene.com/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Thanks for your help",
    "inputs": {
      "current_message": "How long will the refund take?"
    }
  }'

What happens:

user_id and user_email load from checkpoint (not provided in request)
current_message is fresh: “How long will the refund take?”
Agent has full context from first message + new query
Response is personalized to this customer

Supported Data Types

Variables use BAML type notation. You can pass:

Type	Example	Use Case
`str`	`"hello"`	Text values
`int`	`42`	Numbers without decimals
`float`	`3.14`	Decimal values
`bool`	`true`	Yes/no flags
`list[str]`	`["item1", "item2"]`	Multiple tags or selections
`list[int]`	`[1, 2, 3]`	Multiple numeric values
`dict[str, int]`	`{"key": 1, "key2": 2}`	Key-value data
`str \| None`	`"value"` or `null`	Optional text

Automatic Type Coercion

String values in JSON are automatically converted to match your variable’s declared type:

{
  "inputs": {
    "max_retries": "5"           // String in JSON
  }
}

If max_retries is typed as int, it becomes the integer 5. Type conversions:

"42" → 42 (for int type)
"true" or "1" → True (for bool type)
"[1,2,3]" → [1, 2, 3] (for list[int] type)

Common Patterns

Pattern 1: Conversational Loop

Use request-level variables for user messages in a multi-turn conversation:

import requests

session_id = "abc-123"
api_key = "your_api_key"
base_url = "https://api-be.atthene.com/api/v1"

headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json"
}

# First: Initialize with session variables
response = requests.post(
    f"{base_url}/runtime/{session_id}/execute/",
    headers=headers,
    json={
        "inputs": {
            "user_id": "user_123",
            "user_name": "John Doe"
        }
    }
)

# Loop: Send user queries
user_messages = [
    "Hello, I need help",
    "Can you tell me more?",
    "What about pricing?"
]

for message in user_messages:
    response = requests.post(
        f"{base_url}/runtime/{session_id}/execute/",
        headers=headers,
        json={
            "content": message,
            "inputs": {
                "current_message": message  # Fresh each iteration
            }
        }
    )
    print(response.json()["response"]["content"])

Pattern 2: Configuration + Queries

Store configuration once, run many queries:

# Initialize with config (session-level)
curl -X POST https://api-be.atthene.com/api/v1/runtime/session_abc/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "company_name": "Acme Corp",
      "support_email": "support@acme.com",
      "api_key": "sk_live_12345"
    }
  }'

# Later: Just provide the query
curl -X POST https://api-be.atthene.com/api/v1/runtime/session_abc/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User question",
    "inputs": {
      "user_query": "What is your refund policy?"
    }
  }'

Configuration variables persist; you only provide fresh queries each time.

Error Handling

Required Variable Missing

{
  "success": false,
  "error": "Required variable 'user_id' not provided",
  "error_code": "MISSING_REQUIRED_VARIABLE"
}

Solution: Ensure all required: true variables are provided on first execution.

Variable Not Defined

If you provide a variable name that isn’t defined in your configuration:

{
  "inputs": {
    "undefined_var": "value"
  }
}

It’s silently ignored. Only variables defined in your agent configuration are used.

Type Mismatch

If type coercion fails:

{
  "success": false,
  "error": "Type coercion failed for variable 'max_retries'",
  "error_code": "TYPE_COERCION_FAILED"
}

Best Practices

Use Descriptive Names

# ✅ Good
current_user_id:
  description: "The ID of the current user"

# ❌ Avoid
uid:
  description: "ID"

Provide Descriptions

current_query:
  type: "str"
  require_every_execution: true
  description: "The user's current search or question"

Set Sensible Defaults

priority:
  type: "str"
  default: "medium"
  description: "Request priority level"

Enable Persistent State

persistent_state: true  # Required for session variables

Troubleshooting

Variables not persisting between requests

Solution: Ensure persistent_state: true is set in your configuration.

persistent_state: true
variables:
  user_id:
    type: "str"
    required: true

Getting stale variable values

Solution: If you want a fresh value on every request, use require_every_execution: true:

current_query:
  type: "str"
  require_every_execution: true

Variables not appearing in agent prompts

Solution: Check that:

Variable is defined in variables section
Variable name in prompt uses correct syntax: {{ variables.name }}
Variable is provided in inputs on first execution (for required variables)

Agent Configuration Guide - Define variables in your config
Execute Endpoint - API reference for execute
REST API Tutorial - Full integration guide

Getting started

Agent Configuration

Multi Agent Systems

Advanced Features

Atthene Agents Studio

Platform

Integration

Overview

Request Body Structure

Variable Types: Session vs Request Level

Session-Level Variables

Request-Level Variables

Complete Example: Conversational Support Agent

Configuration

First Request: Initialize Session

Second Request: Continue Conversation

Supported Data Types

Automatic Type Coercion

Common Patterns

Pattern 1: Conversational Loop

Pattern 2: Configuration + Queries

Error Handling

Required Variable Missing

Variable Not Defined

Type Mismatch

Best Practices

Use Descriptive Names

Provide Descriptions

Set Sensible Defaults

Enable Persistent State

Troubleshooting

Getting started

Agent Configuration

Multi Agent Systems

Advanced Features

Atthene Agents Studio

Platform

Integration

Documentation Index

​Overview

​Request Body Structure

​Variable Types: Session vs Request Level

​Session-Level Variables

​Request-Level Variables

​Complete Example: Conversational Support Agent

​Configuration

​First Request: Initialize Session

​Second Request: Continue Conversation

​Supported Data Types

​Automatic Type Coercion

​Common Patterns

​Pattern 1: Conversational Loop

​Pattern 2: Configuration + Queries

​Error Handling

​Required Variable Missing

​Variable Not Defined

​Type Mismatch

​Best Practices

Use Descriptive Names

Provide Descriptions

Set Sensible Defaults

Enable Persistent State

​Troubleshooting

​Related Documentation

Overview

Request Body Structure

Variable Types: Session vs Request Level

Session-Level Variables

Request-Level Variables

Complete Example: Conversational Support Agent

Configuration

First Request: Initialize Session

Second Request: Continue Conversation

Supported Data Types

Automatic Type Coercion

Common Patterns

Pattern 1: Conversational Loop

Pattern 2: Configuration + Queries

Error Handling

Required Variable Missing

Variable Not Defined

Type Mismatch

Best Practices

Troubleshooting

Related Documentation