What is Declare Task Succeeded?
Declare Task Succeeded is a specialized tool that allows a focused action agent to immediately terminate workflow execution with a success status when specific success conditions are met. This enables dynamic success detection during cached workflow replay.
In your prompts, always refer to this tool as declare_task_succeeded (lowercase, with underscores).
Focused Action Only: This tool is only available within focused_action. The main agent and recovery agent can already signal success by completing their task normally (sending a final message without a tool call). Use declare_task_succeeded when you need a focused action to determine that the entire workflow is complete.
focused_action always runs dynamically, even during cached runs. This creates situations where:
- A focused action discovers the task is already complete (e.g., data was already processed)
- A user-defined success condition is met earlier than expected
- The focused action determines no further steps are needed
Without declare_task_succeeded, the focused action would return to the trajectory replay, which would continue executing remaining steps unnecessarily.
How It Works
- A focused action evaluates the current screen state
- It determines that a user-specified success condition has been met
- It calls
declare_task_succeeded (optionally with a description of why)
- Workflow execution immediately terminates with success status
- Trajectories are committed (the successful path is saved)
- Normal success cleanup occurs (status update, webhooks, etc.)
The text parameter is optional. If omitted, a default “Task completed successfully” message is used.
Unlike declare_task_failed which clears pending trajectories, declare_task_succeeded commits them because the workflow reached a valid success state.
When to Use Declare Task Succeeded
1. Early Success Detection
When a focused action discovers the goal is already achieved:
"Use focused_action to check if the invoice has already been processed.
If you see 'Status: Paid' or 'Status: Complete', use declare_task_succeeded
with message 'Invoice already processed - no action needed'."
2. Conditional Workflow Completion
When success depends on dynamic content evaluation:
"Use focused_action to verify the data migration status. If the progress
shows '100% Complete' and no errors are listed, use declare_task_succeeded
with 'Migration completed successfully'."
3. Goal-Based Termination
When the focused action can determine the workflow’s goal is met:
"Use focused_action to check if the patient's appointment has been confirmed.
If you see the confirmation number and 'Appointment Scheduled' message,
use declare_task_succeeded with the confirmation details."
How to Prompt for Task Success
Best Practices
- Be Specific: Clearly define what constitutes success
- Explain the Condition: Describe what the focused action should look for
- Include Context: Specify what message to include when succeeding
- Use in Focused Actions: Remember this is only for dynamic success detection
Prompt Template
"Use focused_action to [check specific condition]. If [success condition is met],
use declare_task_succeeded with message '[descriptive success reason]'."
Real-World Examples
Healthcare: Record Already Updated
"Use focused_action to navigate to the patient's medication list and check
if {medication_name} with dosage {dosage} is already present. If the medication
is already listed with the correct dosage, use declare_task_succeeded with
'Medication {medication_name} already exists in patient record'."
Finance: Transaction Already Processed
"Use focused_action to search for transaction ID {transaction_id}. If the
transaction shows 'Status: Completed' with the correct amount {amount},
use declare_task_succeeded with 'Transaction {transaction_id} already processed'."
E-commerce: Order Already Fulfilled
"Use focused_action to check the order status for {order_id}. If the order
shows 'Shipped' or 'Delivered' with a tracking number, use declare_task_succeeded
with 'Order {order_id} already fulfilled - tracking: [tracking number]'."
"Use focused_action to verify the server configuration. If all required
settings match the expected values and the health check shows 'Healthy',
use declare_task_succeeded with 'Server configuration verified - all checks passed'."
Comparison: declare_task_succeeded vs declare_task_failed
| Aspect | declare_task_succeeded | declare_task_failed |
|---|
| Purpose | Signal successful completion | Signal unrecoverable failure |
| Trajectory | Committed (saved) | Cleared (not saved) |
| Run Status | SUCCESS | ERROR |
| Use Case | Goal achieved early | Insurmountable obstacle |
| Availability | Focused action only | All agents |
Integration with Cached Workflows
This tool is particularly valuable in cached workflows where:
"The workflow normally processes an order through multiple steps. However,
if the order was already processed in a previous run or by another system:
1. Navigate to order {order_id}
2. Use focused_action to check the current status
- If 'Pending': Continue with normal processing
- If 'Complete': Use declare_task_succeeded with 'Order already complete'
- If 'Cancelled': Use declare_task_failed with 'Order was cancelled'
3. [Remaining processing steps...]"
Common Patterns
Pre-flight Success Check
"Before starting the main workflow, use focused_action to check if the
target state already exists. If the report for {report_date} already
exists in the Reports folder, use declare_task_succeeded with
'Report already generated for {report_date}'."
Polling with Success Detection
"Use focused_action to check the job status.
- If 'Running' or 'Pending': Wait 10 seconds and check again
- If 'Completed': Use declare_task_succeeded with the job results
- If 'Failed': Use declare_task_failed with the error message"
Idempotent Operations
"Use focused_action to verify the user account status:
- If account already exists with correct permissions: Use declare_task_succeeded
- If account doesn't exist: Proceed to create account
- If account exists with wrong permissions: Update permissions"
Common Mistakes to Avoid
Don’t use declare_task_succeeded for:
- Normal workflow completion (just let the workflow end naturally)
- Main agent success detection (the main agent completes by sending a final message)
- Partial success (if more steps are needed, don’t terminate early)
Incorrect Usage
// Wrong: Using in main agent context (main agent doesn't need this)
"After completing all steps, use declare_task_succeeded"
// Wrong: Using outside focused_action
"Click submit, then use declare_task_succeeded if it works"
// Wrong: Terminating when more work remains
"Use focused_action to check the first item. If it's correct, use declare_task_succeeded"
Correct Usage
// Correct: Dynamic success detection in focused_action
"Use focused_action to verify all items have been processed. If the
status shows 'All items complete', use declare_task_succeeded"
// Correct: Early termination when goal is already met
"Use focused_action to check if the file already exists at the destination.
If it exists with matching checksum, use declare_task_succeeded with
'File already present at destination'"
Best Practices Summary
- Use only within focused_action - This is the key constraint
- Define clear success conditions - Be specific about what “success” means
- Consider adding descriptive messages - Optionally explain why the workflow succeeded (helps debugging)
- Consider idempotency - Great for workflows that should be safe to re-run
- Pair with declare_task_failed - Handle both success and failure conditions
- Think about cached replay - Most valuable when focused actions run during trajectory replay
