Declare Task Failed - Cyberdesk Docs

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).

Why This Tool Exists

Not all workflow failures are the same. Some errors are recoverable, while others indicate fundamental issues that make task completion impossible:

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.

Think of task_failed as a terminal run outcome, not an infrastructure crash. Cyberdesk still keeps the run’s message history and failure reason, and you can retry that run later from the Runs UI or API. The part that is discarded is the pending trajectory cache for that failed path.

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."

Integration with Other Tools

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'"

​What is Declare Task Failed?

​Why This Tool Exists

​How It Works

​When to Use Declare Task Failed

​1. Authentication Errors

​2. Missing Critical Data

​3. System Unavailability

​4. Business Rule Violations

​How to Prompt for Task Failure

​Best Practices

​Prompt Template

​Real-World Examples

​Healthcare: Patient Safety

​Finance: Compliance Checks

​E-commerce: Inventory Management

​IT Operations: Deployment Safety

​Common Failure Patterns

​Multiple Attempt Failures

​Timeout Conditions

​Validation Failures

​Permission Denials

​Failure vs. Recovery Strategies

​When to Fail vs. Retry

​Cascading Failures

​Integration with Other Tools

​With Focused Action

​With Terminal Commands

​Conditional Workflow Paths

​Advanced Usage

​Complex Failure Conditions

​Partial Success Handling

​Pre-flight Checks

​Best Practices Summary

​Common Mistakes to Avoid

​❌ Incorrect Usage

​✅ Correct Usage

What is Declare Task Failed?

Why This Tool Exists

How It Works

When to Use Declare Task Failed

1. Authentication Errors

2. Missing Critical Data

3. System Unavailability

4. Business Rule Violations

How to Prompt for Task Failure

Best Practices

Prompt Template

Real-World Examples

Healthcare: Patient Safety

Finance: Compliance Checks

E-commerce: Inventory Management

IT Operations: Deployment Safety

Common Failure Patterns

Multiple Attempt Failures

Timeout Conditions

Validation Failures

Permission Denials

Failure vs. Recovery Strategies

When to Fail vs. Retry

Cascading Failures

Integration with Other Tools

With Focused Action

With Terminal Commands

Conditional Workflow Paths

Advanced Usage

Complex Failure Conditions

Partial Success Handling

Pre-flight Checks

Best Practices Summary

Common Mistakes to Avoid

❌ Incorrect Usage

✅ Correct Usage