Skip to content

Automation Configuration Reference

This page provides a comprehensive reference for the JSON configuration schema used in Automation Mode. Use this guide to build valid automation configurations for your agents.

Configuration Structure

The top-level structure of an automation configuration:

{
  "tasks": [...],
  "constraints": [...],
  "variables_required_to_final_answer": [...],
  "parallelism": false,
  "version": "1.0"
}

Root Fields

Field Type Required Description
tasks Array[Task] Yes List of tasks to execute
constraints Array[String] No Optional execution constraints
variables_required_to_final_answer Array[String] Yes Variable names containing context for the final response
parallelism Boolean No Enable parallel task execution (default: false)
version String No Configuration version (default: "1.0")

Task Configuration

Each task in the tasks array follows this structure:

{
  "task_id": "unique_task_id",
  "description": "What this task accomplishes",
  "candidate_tools": ["tool1", "tool2"],
  "dependencies": [...],
  "expected_output": "Description of expected result",
  "output_variable_name": "result_variable",
  "known_arguments": [...],
  "runs_react_loop": false,
  "output_template": "Optional output format template",
  "requires_analysis": false,
  "result_evaluation": "Optional evaluation criteria",
  "pause_and_replan": false,
  "status": "pending",
  "metadata": {}
}

Task Fields

Field Type Required Description
task_id String Yes Unique identifier for the task
description String Yes Clear description of what the task does
output_variable_name String Yes Variable name to store task output
candidate_tools Array[String] No* Tools available for this task
candidate_agents Array[String] No* Agents available for this task (Magent only)
dependencies Array[Dependency] No Tasks that must complete before this one
expected_output String No Description of expected result format
known_arguments Array[KnownArguments] No Pre-configured tool arguments
runs_react_loop Boolean No Execute multiple tool calls until completion
output_template String No Template for formatting output
requires_analysis Boolean No Whether result needs analysis
result_evaluation String No Criteria for evaluating results
pause_and_replan Boolean No Pause and replan after dependencies
status String No Initial status (default: "pending")
metadata Object No Additional task metadata

*At least one of candidate_tools or candidate_agents must be specified

Dependencies

Control task execution order using dependencies:

{
  "dependencies": [
    {
      "task_id": "previous_task",
      "required_status": "completed"
    }
  ]
}

Dependency Fields

Field Type Required Description
task_id String Yes ID of the dependent task
required_status String No Required status (default: "completed")

Valid Status Values

  • pending - Task not started
  • in_progress - Currently executing
  • completed - Successfully finished
  • failed - Execution failed
  • cancelled - Task cancelled
  • skipped - Task skipped

Known Arguments

Pre-configure tool arguments to ensure deterministic execution:

{
  "known_arguments": [
    {
      "tool_name": "search_database",
      "arguments": [
        {
          "name": "query",
          "value": "SELECT * FROM users WHERE active = true"
        },
        {
          "name": "limit",
          "value": 100
        }
      ]
    }
  ]
}

Known Arguments Structure

Field Type Required Description
tool_name String Yes Name of the tool these arguments apply to
arguments Array[Argument] Yes List of argument configurations

Argument Fields

Field Type Required Description
name String Yes Argument name (must match tool schema)
value Any Yes Argument value (string, number, boolean, array, object, or DynamicVariable)

Dynamic Variables

Pass data between tasks using dynamic variables:

{
  "known_arguments": [
    {
      "tool_name": "send_email",
      "arguments": [
        {
          "name": "recipient",
          "value": {
            "name": "$$user_email$$"
          }
        },
        {
          "name": "subject",
          "value": "Report Ready"
        }
      ]
    }
  ]
}

Dynamic Variable Structure

Field Type Required Description
name String Yes Variable reference using $$variable$$ syntax

Important Notes

Variable References

  • Always use double dollar signs: $$variable_name$$
  • Variables must be defined by a previous task's output_variable_name
  • Dynamic variables can only be used for string-type arguments

React Loop Tasks

  • Set runs_react_loop: true when using multiple tools
  • Required when specifying more than one candidate_tools
  • The task will iterate until completion or failure

Final Answer Variables

  • variables_required_to_final_answer must list all variables needed for the final response
  • Failure to specify required variables may result in incomplete answers
  • Order matters - list variables in the order they should be considered

Tool Filtering

  • Only tools listed in candidate_tools will be available during task execution
  • For react loops, ensure all necessary tools are included
  • Tool names must match exactly with configured tool names in your agent

Validation Tips

  1. Unique Task IDs: Ensure all task_id values are unique
  2. Valid Dependencies: Referenced task IDs in dependencies must exist
  3. Tool Names: Verify tool names match your agent's configured tools
  4. Variable Names: Check that dynamic variables reference existing output variables
  5. Required Fields: Include all required fields for each task
  6. Argument Types: Ensure argument values match expected tool parameter types

Next Steps