> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberdesk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Declare Task Succeeded
> Allow focused actions to signal workflow completion when success conditions are met
## 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
1. A focused action evaluates the current screen state
2. Your prompt tells that focused action exactly when it should call `declare_task_succeeded`
3. If that success condition is met, it calls `declare_task_succeeded` (optionally with a description of why)
4. Workflow execution immediately terminates with success status
5. Trajectories are committed (the successful path is saved)
6. Post-run Checks run normally, unless the focused action called `declare_task_succeeded` with `skip_post_run_checks=True`
7. 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:
```text theme={null}
"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:
```text theme={null}
"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:
```text theme={null}
"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
1. **Be Specific**: Clearly define what constitutes success
2. **Explain the Condition**: Describe what the focused action should look for
3. **Write the Exact Tool Name**: Include the literal phrase `declare_task_succeeded` in the prompt when you want to enable this behavior
4. **Include Context**: Specify what message to include when succeeding
5. **Use in Focused Actions**: Remember this is only for dynamic success detection
### Prompt Template
```text theme={null}
"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:
```text theme={null}
"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
```text theme={null}
"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
```text theme={null}
"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
```text theme={null}
"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
```text theme={null}
"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:
```text theme={null}
"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
```text theme={null}
"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
```text theme={null}
"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
```text theme={null}
"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
```text theme={null}
// 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
```text theme={null}
// 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
1. **Use only within focused\_action** - This is the key constraint
2. **Explicitly include `declare_task_succeeded` in the instructions** - The focused action should not infer this behavior on its own
3. **Define clear success conditions** - Be specific about what "success" means
4. **Consider adding descriptive messages** - Optionally explain why the workflow succeeded (helps debugging)
5. **Consider idempotency** - Great for workflows that should be safe to re-run
6. **Pair with declare\_task\_failed** - Handle both success and failure conditions
7. **Think about cached replay** - Most valuable when focused actions run during trajectory replay