Skip to main content

​
Overview

Stops a workflow that is currently running or paused. Use when you want to abort a build/deployment that is no longer needed or is taking too long.
Canceling a workflow cannot be undone. The workflow will stop immediately and its progress will be lost.

​
Parameters

​
session_id
string
required
Session ID of the workflow to cancel
  • Format: UUID
  • Get it from: bilt_get_session
  • Example: "550e8400-e29b-41d4-a716-446655440000"
​
reason
string
Optional reason for cancellation
  • Max length: 500 characters
  • Example: "User requested cancellation"
  • Usage: Helpful for logs and debugging

​
Response

​
session_id
string
required
Session ID (same as input)
​
status
string
required
New status after cancellation ("cancelled")
​
cancelled_at
string
required
ISO 8601 timestamp when workflow was cancelled
​
message
string
Confirmation message

​
Example Usage

​
Basic Cancellation

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
With Reason

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "reason": "User changed requirements"
}

​
When to Use

​
User Requests Stop

User: "Stop the build"

Agent workflow:
1. Call bilt_get_session()
2. If status === "running" or "paused":
3.   Call bilt_cancel_workflow(session_id)
4.   Confirm: "Build cancelled"

​
Build Taking Too Long

User: "This is taking forever, cancel it"

Agent: "Cancelling the build..."
Agent calls bilt_cancel_workflow()
Agent: "Build cancelled. Would you like to try a simpler approach?"

​
User Changed Mind

User: "Actually, nevermind, I don't want that feature"

Agent: "No problem. Cancelling the current build..."
Agent calls bilt_cancel_workflow()

​
Detected Error During Build

If agent detects an issue:

Agent: "I noticed an error in the build configuration. 
       Cancelling this workflow..."
Agent calls bilt_cancel_workflow(reason: "Configuration error detected")

​
Common Patterns

​
Cancel with Confirmation

async function cancelWithConfirmation(sessionId) {
  // Check if there's something to cancel
  const session = await bilt_get_session({ session_id: sessionId });
  
  if (session.status !== 'running' && session.status !== 'paused') {
    return `Nothing to cancel. Workflow is ${session.status}`;
  }
  
  // Cancel
  await bilt_cancel_workflow({ 
    session_id: sessionId,
    reason: 'User requested cancellation'
  });
  
  return 'Workflow cancelled successfully';
}

​
Cancel and Start Fresh

// Cancel current workflow and start a new one
await bilt_cancel_workflow({ session_id: oldSessionId });

// Wait a moment for cancellation to process
await sleep(1000);

// Start new workflow
await bilt_send_message({
  session_id: newSessionId,
  message: "Start over with corrected instructions"
});

​
Cancellation States

Can Cancel
  • running
  • paused
  • pending

Cannot Cancel
  • completed
  • failed
  • cancelled (already cancelled)

​
Best Practices

For important workflows, ask the user first:
Agent: "Are you sure you want to cancel? 
       The build is 80% complete."

User: "Yes"

Agent: *calls bilt_cancel_workflow()*
Include a reason for better logging:
await bilt_cancel_workflow({
  session_id,
  reason: 'Build exceeded 5 minute timeout'
});
Don’t attempt to cancel completed workflows:
const session = await bilt_get_session({ session_id });

if (['completed', 'failed', 'cancelled'].includes(session.status)) {
  return 'Workflow already finished';
}

await bilt_cancel_workflow({ session_id });
After cancelling, help the user move forward:
Agent: "Build cancelled. Would you like to:
       1. Start over with different instructions
       2. Resume from where we stopped
       3. Check the build logs"

​
Error Handling

{
  "error": "Cannot cancel workflow",
  "details": {
    "current_status": "completed",
    "message": "Workflow has already completed"
  }
}

​
Workflow State After Cancellation

Once cancelled, a workflow cannot be resumed. You’ll need to start a new workflow.

​
What Happens to Resources?

When you cancel a workflow:
  1. Build stops immediately - No further processing
  2. Partial changes may exist - Code may be partially generated
  3. No deployment - App won’t be deployed
  4. Logs preserved - You can still view what was done
  5. Session remains - Session history is kept for debugging

bilt_get_session

Check workflow status

bilt_resume_workflow

Resume instead of cancel

bilt_send_message

Start new workflow

​
Next Steps

After cancelling workflow:
  1. Start fresh - Use bilt_send_message
  2. Check logs - Use bilt_get_messages
  3. Verify status - Use bilt_get_session