What is Declare Task Failed?
Declare Task Failed is a specialized tool that allows your agent to immediately terminate workflow execution when specific failure conditions are met. This prevents the agent from continuing to attempt a task that cannot be completed, saving time and resources.
In your prompts, always refer to this tool as declare_task_failed (lowercase, with underscores).
- Authentication Failures: Locked accounts or invalid credentials
- Missing Prerequisites: Required data or systems unavailable
- Business Rule Violations: Conditions that invalidate the entire process
- Technical Limitations: System errors that cannot be resolved
- User-Defined Conditions: Specific scenarios you define as failures
Without declare_task_failed, the agent might spend excessive time trying to work around insurmountable obstacles.
How It Works
- The agent encounters a condition you’ve defined as a failure
- It calls
declare_task_failed with a description of the failure
- Workflow execution immediately terminates
- The run is marked with status
task_failed (shown in the dashboard as Task Failed)
- No trajectory is saved (the run is not cached)
- The failure reason is recorded for debugging
Important: Once declare_task_failed is called, the workflow stops immediately. This tool is never cached because failed runs don’t create trajectories.
task_failed is reserved for explicit declare_task_failed calls. Other failure paths (for example infrastructure or unexpected execution errors) continue using status error.
You can filter runs by this status using the Runs list status=task_failed filter.
When to Use Declare Task Failed
1. Authentication Errors
"If you see 'Account Locked' or 'Invalid Credentials' after attempting login,
use declare_task_failed to terminate the workflow. Do not attempt
password recovery or multiple login attempts."
2. Missing Critical Data
"Search for patient ID {patient_id}. If no results are found after searching,
use declare_task_failed indicating 'Patient ID {patient_id} not found in system'.
Do not proceed with empty data."
3. System Unavailability
"If the application shows 'System Maintenance in Progress' or fails to load
after 30 seconds, use declare_task_failed stating 'Target system unavailable'."
4. Business Rule Violations
"Check the account balance before processing. If balance is less than {required_amount},
use declare_task_failed with message 'Insufficient funds: balance below required amount'."
How to Prompt for Task Failure
Best Practices
- Be Specific: Clearly define what constitutes a failure
- Provide Context: Explain why this is a failure condition
- Include Messages: Specify what message to include when failing
- Set Boundaries: Define how many attempts before failing
- Consider Timing: Specify timeouts for time-sensitive operations
Prompt Template
"If [specific condition occurs], use declare_task_failed with message
'[descriptive failure reason]'. Do not [what not to do]."
Real-World Examples
Healthcare: Patient Safety
"When searching for the patient's medication list, if you see any alert about
'Drug Interaction Warning - Contraindicated', immediately use declare_task_failed
with message 'Critical drug interaction detected - manual review required'.
Do not proceed with the prescription."
Finance: Compliance Checks
"Before initiating the transfer, verify the recipient is not on the sanctions list.
If the screen shows 'Compliance Alert - Restricted Entity', use declare_task_failed
stating 'Transfer blocked - recipient on sanctions list'. Do not attempt workarounds."
E-commerce: Inventory Management
"Check inventory for all items in order {order_id}. If any item shows
'Out of Stock' or 'Discontinued', use declare_task_failed with message
'Order cannot be fulfilled - {item_name} unavailable'. Do not process partial orders."
IT Operations: Deployment Safety
"Before deploying, check the pre-deployment tests. If status shows 'FAILED'
for any critical test, use declare_task_failed with 'Deployment aborted -
critical test failures detected'. Do not override or skip failed tests."
Common Failure Patterns
Multiple Attempt Failures
"Attempt to connect to the database. If connection fails, retry up to 3 times
with 10-second intervals. If still failing after 3 attempts, use declare_task_failed
with 'Database connection failed after 3 attempts'."
Timeout Conditions
"Click 'Generate Report' and wait for completion. If the progress bar doesn't
finish within 5 minutes, use declare_task_failed stating 'Report generation
timeout - exceeded 5 minute limit'."
Validation Failures
"After filling the form, click Submit. If validation errors appear for required
fields that cannot be populated from the provided data {input_data},
use declare_task_failed listing the missing required fields."
Permission Denials
"Navigate to the admin panel. If you see 'Access Denied' or 'Insufficient Privileges',
use declare_task_failed with 'User lacks required admin permissions'.
Do not attempt to access via other routes."
Failure vs. Recovery Strategies
When to Fail vs. Retry
Use declare_task_failed
Retry/Recover
"If login fails with 'Account Locked', use declare_task_failed"
"If the file is corrupted (shows 'Cannot read file'), use declare_task_failed"
"If payment is declined with 'Card Reported Stolen', use declare_task_failed"
"If page doesn't load, refresh and try again"
"If button click doesn't respond, wait 2 seconds and retry"
"If search returns no results, try alternative search terms"
Cascading Failures
"The workflow requires sequential approvals from 3 departments. If any department
shows 'Request Denied' or 'Not Authorized', use declare_task_failed immediately
with 'Approval chain broken at {department_name}'. Don't continue to other departments."
With Focused Action
"Use focused_action to check if an error message appears after submission.
If the error contains 'Fatal', 'Critical', or 'Unrecoverable',
use declare_task_failed with the full error message."
With Terminal Commands
"Use execute_terminal_command to run 'Test-Path C:\RequiredFiles\config.xml'.
If it returns False, use declare_task_failed with 'Required configuration file missing'."
Conditional Workflow Paths
"Check the order status. If status is 'Cancelled' or 'Refunded',
use declare_task_failed with 'Order {order_id} already {status} - no action needed'.
Only proceed if status is 'Pending' or 'Processing'."
Advanced Usage
Complex Failure Conditions
"Monitor the batch processing progress. Use declare_task_failed if:
1. More than 10% of items fail processing
2. Any critical error (severity = 'CRITICAL') appears in logs
3. Processing time exceeds 30 minutes
4. System memory usage exceeds 90%
Include specific failure reason in the message."
Partial Success Handling
"Process all invoices in the list. Keep track of successes and failures.
If more than 50% fail, use declare_task_failed with
'Batch processing failed - {failed_count} of {total_count} invoices failed'.
Otherwise, complete successfully even with some failures."
Pre-flight Checks
"Before starting the main workflow:
1. Verify all required applications are running
2. Check available disk space > 10GB
3. Confirm network connectivity to required services
If any check fails, use declare_task_failed with specific check that failed.
This prevents wasting time on doomed workflows."
Best Practices Summary
- Define clear, specific failure conditions
- Fail fast when recovery is impossible
- Include descriptive failure messages
- Don’t use for recoverable errors
- Consider the business impact of failing vs. continuing
- Set reasonable retry limits before failing
- Document why each failure condition exists
- Test failure scenarios to ensure proper handling
Common Mistakes to Avoid
Don’t use declare_task_failed for:
- Temporary UI delays (use wait/retry instead)
- Minor data variations (use focused_action to adapt)
- Recoverable errors (implement retry logic)
- Success scenarios (even if no action needed)
❌ Incorrect Usage
"If the page takes more than 2 seconds to load, use declare_task_failed" // Too aggressive
"If anything goes wrong, use declare_task_failed" // Too vague
"After completing successfully, use declare_task_failed" // Wrong tool
✅ Correct Usage
"If login fails with 'Account Suspended', use declare_task_failed"
"If required file is missing after checking 3 locations, use declare_task_failed"
"If the API returns 403 Forbidden, use declare_task_failed with 'API access denied'"
