Declare Task Succeeded

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.

Why This Tool Exists

During cached workflow replay, the main agent is not invoked—actions are replayed deterministically from the trajectory. However, 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)
Post-run Checks run normally, unless the focused action called declare_task_succeeded with skip_post_run_checks=True
Normal success cleanup occurs (status update, webhooks, etc.)

The text parameter is optional. If omitted, a default “Task completed successfully” message is used.

declare_task_succeeded also accepts skip_post_run_checks=True. Use this only when the prompt explicitly says the early-success path should skip Post-run Checks, such as when the task was already complete before the workflow produced the attachments or output data that those checks normally verify.

Unlike declare_task_failed which clears pending trajectories, declare_task_succeeded commits them because the workflow reached a valid success state.

Explicit success still goes through the normal terminal output-processing path. If a workflow promises structured output_data and that final transformation fails, Cyberdesk preserves the pending trajectories but surfaces the run as error instead of silently returning success with missing output.

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

Skipping Post-run Checks

If your workflow has Post-run Checks that only make sense after the normal path creates files, screenshots, or structured output, tell the focused action to use skip_post_run_checks=True only for the early-success case:

"Use focused_action to check if {invoice_id} is already marked Paid.
If it is already Paid, call declare_task_succeeded with
skip_post_run_checks=True and message 'Invoice {invoice_id} was already paid'.
Otherwise, continue normally so the workflow can produce the usual attachments
and output data for Post-run Checks."

When this parameter is set, Cyberdesk marks each configured Post-run Check as success and records a message explaining that it was skipped because declare_task_succeeded was called with skip_post_run_checks=True. Cyberdesk also does not generate a reusable trajectory for that early-success path, since it represents an idempotent shortcut rather than the workflow’s normal repeatable path.

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

IT Operations: System Already Configured

"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	Usually `success`	Usually `task_failed` for explicit agent-declared failure
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...]"

During cached replay, the focused action will dynamically evaluate step 2 and can terminate the workflow early if the order is already complete, preventing unnecessary cached actions from executing.

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

Getting started

SDK Guides

Cyberdriver

Workflow Prompting

Webhooks

Concepts

Additional Details

What is Declare Task Succeeded?

Why This Tool Exists

How It Works

When to Use Declare Task Succeeded

1. Early Success Detection

2. Conditional Workflow Completion

3. Goal-Based Termination

How to Prompt for Task Success

Best Practices

Prompt Template

Skipping Post-run Checks

Real-World Examples

Healthcare: Record Already Updated

Finance: Transaction Already Processed

E-commerce: Order Already Fulfilled

IT Operations: System Already Configured

Comparison: declare_task_succeeded vs declare_task_failed

Integration with Cached Workflows

Common Patterns

Pre-flight Success Check

Polling with Success Detection

Idempotent Operations

Common Mistakes to Avoid

Incorrect Usage

Correct Usage

Best Practices Summary

​What is Declare Task Succeeded?

​Why This Tool Exists

​How It Works

​When to Use Declare Task Succeeded

​1. Early Success Detection

​2. Conditional Workflow Completion

​3. Goal-Based Termination

​How to Prompt for Task Success

​Best Practices

​Prompt Template

​Skipping Post-run Checks

​Real-World Examples

​Healthcare: Record Already Updated

​Finance: Transaction Already Processed

​E-commerce: Order Already Fulfilled

​IT Operations: System Already Configured

​Comparison: declare_task_succeeded vs declare_task_failed

​Integration with Cached Workflows

​Common Patterns

​Pre-flight Success Check

​Polling with Success Detection

​Idempotent Operations

​Common Mistakes to Avoid

​Incorrect Usage

​Correct Usage

​Best Practices Summary

What is Declare Task Succeeded?

Why This Tool Exists

How It Works

When to Use Declare Task Succeeded

1. Early Success Detection

2. Conditional Workflow Completion

3. Goal-Based Termination

How to Prompt for Task Success

Best Practices

Prompt Template

Skipping Post-run Checks

Real-World Examples

Healthcare: Record Already Updated

Finance: Transaction Already Processed

E-commerce: Order Already Fulfilled

IT Operations: System Already Configured

Comparison: declare_task_succeeded vs declare_task_failed

Integration with Cached Workflows

Common Patterns

Pre-flight Success Check

Polling with Success Detection

Idempotent Operations

Common Mistakes to Avoid

Incorrect Usage

Correct Usage

Best Practices Summary