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.artaios.ai/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.artaios.ai/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.artaios.ai/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.artaios.ai/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.artaios.ai/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.artaios.ai/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.artaios.ai/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.artaios.ai/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.artaios.ai/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

Artaios 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

​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