Workflow Variable Processing Documentation¶
WARNING: Never use
{{ ... }}
(Go template) or${...}
syntax for dynamic values in YAML workflow/config files. Only use dot notation (e.g.,task_id.output_key
,INPUT.var
,TASKFLOW.process_id
). The{{ ... }}
syntax is only allowed inside prompt templates, not in YAML config.
1. Variable Sources and Syntax Rules¶
1.1 Core Variable Syntax Rules¶
-
Never use
${}
or{{}}
syntax in YAML -
Use proper template syntax only in prompts
1.2 Trigger Input Variables¶
- Variables from webhook triggers are mapped using
input_mapping
in the workflow YAML - Accessed via
INPUT.
prefix in task configurations - Example from workflow_email_processing.yml:
1.3 Task Output Variables¶
- Each task can produce output that becomes available to subsequent tasks
- Task outputs are stored in the execution context
- Access patterns:
- Direct task output:
task_id.output_key
- Extraction tool output:
task_id.tool_call_results.tool_name.field_name
- Nested fields:
task_id.output_key.nested_field
Example from workflow_email_processing.yml:
# Accessing extraction tool output
prompt_context:
email_analysis_structured: "analyze_email.tool_call_results.extract_email_analysis_data"
suggested_actions: "analyze_email.tool_call_results.extract_email_analysis_data.suggested_actions"
# Accessing nested fields
config:
sender_email: "fetch_resource_content.resource.Content.sender.email"
1.4 Prompt Template Variables¶
- Prompts define required variables in their templates
- Variables must be provided in:
prompt_context
in task configurationdefault_variables
in prompt template definition
Example from workflow_email_processing.yml:
# In prompts.yml
templates:
mail_analysis:
system_prompt: |
Email Content: {{ .email_content }}
default_variables:
email_content: "<Contenu de l'e-mail XML ici>"
# In workflow.yml
tasks:
- id: "analyze_email"
config:
prompt_context:
email_content: "fetch_resource_content.resource.Content"
2. Variable Context Management¶
2.1 Execution Context¶
- Implemented in
internal/taskflow/context.go
- Thread-safe map for variable storage
- Key methods:
2.2 Flow Context¶
- Maintains state during workflow execution
- Tracks current task ID
- Handles variable scoping and lifecycle
3. Variable Resolution Process¶
3.1 Task Configuration Resolution¶
- Resolution Order:
- Task output variables (e.g.,
task_id.output_key
) - Input variables (e.g.,
INPUT.variable_name
) -
Default values from prompt templates
-
Path Resolution:
3.2 Prompt Variable Resolution¶
- System checks required variables in prompt template
- Looks for variables in:
- Task's
prompt_context
- Prompt's
default_variables
- Validates all required variables are present
4. Extraction Tool Output Mapping¶
4.1 Tool Output Structure¶
When an extraction tool is used in a prompt, its output is stored with this structure:
4.2 Common Patterns¶
-
Basic Tool Output Access
-
Nested Object Access
-
Array Access
4.3 Common Issues and Solutions¶
-
Missing Tool Results Path
-
Incorrect Field Path
-
Missing Required Fields
5. Best Practices¶
5.1 Variable Naming¶
- Use consistent naming conventions
- Prefix trigger inputs with
INPUT.
- Use dot notation for task outputs
- Document variable paths in comments
5.2 Prompt Templates¶
- Define all required variables
- Provide default values when possible
- Document variable requirements
- Include error handling templates
5.3 Task Configuration¶
- Validate variable references
- Handle missing variables gracefully
- Use proper error handling templates
- Document variable dependencies
5.4 Error Handling¶
error_handling:
on_error:
- type: "retry_with_prompt"
append_to_system_prompt: "retry_with_prompt"
max_retries: 2
6. Common Validation Errors¶
- Missing Required Variables
- Error:
prompt template requires variable '{{ .summary }}'
-
Fix: Add missing variable to
prompt_context
-
Invalid Task Output References
- Error:
references non-existent output 'resource.Content'
-
Fix: Check task output structure and path
-
Invalid Input References
- Error:
references non-existent task 'INPUT'
-
Fix: Verify input mapping in workflow definition
-
Incorrect Template Syntax
- Error:
invalid template syntax: ${variable}
-
Fix: Use
{{ .variable }}
syntax -
Missing Error Handling
- Error:
missing error handling template
- Fix: Add error handling configuration