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. In production, this is an explicit opt-in tool: wire it into a focused_action prompt only when you want that focused action to be allowed to end the entire workflow early.
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 only when your workflow instructions explicitly tell the focused action to call declare_task_succeeded if a named success condition is met.
Think of declare_task_succeeded as an early-exit switch that you intentionally wire into a focused action prompt, not as a general “the agent can decide to stop whenever it thinks the task is done” behavior.
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
- Your prompt tells that focused action exactly when it should call
declare_task_succeeded
- If that success condition is 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 and your prompt explicitly allows early success:
"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 and you want the focused action to end the run immediately:
"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 and you have explicitly granted it permission to stop the run:
"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
- Write the Exact Tool Name: Include the literal phrase
declare_task_succeeded in the prompt when you want to enable this behavior
- 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]'. Otherwise, continue normally."
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, and only when explicitly instructed in the prompt | All agents |
Integration with Cached Workflows
This tool is particularly valuable in cached workflows where you want a dynamically evaluated focused_action check to have permission to end the run:
"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)
- Cases where the prompt never explicitly asked for
declare_task_succeeded
- 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: Expecting the focused action to infer early-success behavior on its own
"Use focused_action to check if the invoice is already paid"
// 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 with explicit opt-in
"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
- Explicitly include
declare_task_succeeded in the instructions - The focused action should not infer this behavior on its own
- 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
