Instructions

Enhance your AI agent's capabilities by adding dynamic, interactive responses with callbacks and delays during tool execution. This feature allows you to create more engaging user experiences with real-time feedback and controlled execution flow.

Overview

Instructions enable you to:

• Execute custom JavaScript functions during tool execution
• Add controlled delays for better user experience
• Provide real-time progress updates
• Create multi-step interactive workflows

Implementation

Define your tool with instructions

copilot.tools.add([
  {
    name: "data_processor",
    description: "Process data with real-time progress updates",
    timeout: 15000,

    handler: () => {
      return {
        success: true,
        message: "Data processing initiated",

        _agent_instructions: [
          {
            type: "callback",
            options: {
              name: "show_processing_start",
              args: ["Starting data analysis..."]
            }
          },
          {
            type: "delay",
            options: {
              duration: 1000
            }
          },
          {
            type: "callback",
            options: {
              name: "update_progress",
              args: ["Processing step 1 of 3..."]
            }
          },
          {
            type: "delay",
            options: {
              duration: 2000
            }
          },
          {
            type: "callback",
            options: {
              name: "show_completion",
              args: ["Data processing completed successfully!"]
            }
          }
        ]
      };
    }
  }
]);

Register callback handlers

// Progress indicator callback
copilot.callbacks.add({
  name: "show_processing_start",
  handler: (message) => {
    console.log("Processing started:", message);
    // Update UI to show loading state
    updateProgressUI("start", message);
  }
});

// Progress update callback
copilot.callbacks.add({
  name: "update_progress",
  handler: (message) => {
    console.log("Progress update:", message);
    // Update progress bar or status
    updateProgressUI("update", message);
  }
});

// Completion callback
copilot.callbacks.add({
  name: "show_completion",
  handler: (message) => {
    console.log("Processing completed:", message);
    // Show success state
    updateProgressUI("complete", message);
  }
});

Instruction Types

Callback Instructions

Execute custom JavaScript functions during tool execution to update UI, show progress, or perform side effects.

{
  type: "callback",
  options: {
    name: "your_callback_function",
    args: ["parameter1", "parameter2"]
  }
}

Parameters:

• name: The callback function name (must match registered handler)
• args: Array of arguments passed to the callback function

Delay Instructions

Pause execution for a specified duration to create natural conversation flow or simulate processing time.

Parameters:

• duration: Time to wait in milliseconds

{
  type: "delay",
  options: {
    duration: 2000 // milliseconds
  }
}

Quick Reply Instructions

Automatically send a predefined message as a quick reply option during tool execution.

{
  type: "quick_reply",
  options: {
    value: "Show Details of move-on-restart-oversize-men-s-tshirt-7868711"
  }
}

Navigate Instructions

Redirect users to a specific URL during tool execution.

{
  type: "navigate",
  options: {
    value: "https://fynd.hostx5.de/product/move-on-restart-oversize-men-s-tshirt-7868711"
  }
}

Parameters:

• value: The URL to navigate to

Best Practices

User Experience

• Use delays sparingly to avoid frustrating users
• Provide meaningful progress updates
• Keep callback execution time minimal

Error Handling

copilot.callbacks.add({
  name: "handle_error",
  handler: (errorMessage) => {
    console.error("Tool execution error:", errorMessage);
    showErrorMessage(errorMessage);
  }
});

Performance

• Limit the number of instructions per tool
• Use appropriate timeout values
• Clean up resources in callback handlers

Common Use Cases

Progress Indicators

// Show step-by-step progress
{
  type: "callback",
  options: {
    name: "update_progress_bar",
    args: ["Step 1/5: Initializing..."]
  }
}

User Feedback

// Provide real-time status updates
{
  type: "callback",
  options: {
    name: "show_notification",
    args: ["Data validation completed"]
  }
}

Sequential Operations

// Chain multiple operations with delays
[
  { type: "callback", options: { name: "start_operation", args: [] } },
  { type: "delay", options: { duration: 1000 } },
  { type: "callback", options: { name: "complete_operation", args: [] } }
]

Interactive Workflows

// Create multi-step processes
[
  { type: "callback", options: { name: "show_step_1", args: [] } },
  { type: "delay", options: { duration: 500 } },
  { type: "callback", options: { name: "show_step_2", args: [] } },
  { type: "delay", options: { duration: 500 } },
  { type: "callback", options: { name: "show_final_result", args: [] } }
]

Troubleshooting

Common Issues and Solutions

Callbacks not executing:

• Verify callback names match exactly between tool definition and registration
• Check browser console for JavaScript errors
• Ensure callback handlers are registered before tool execution

Timeout errors:

• Increase the tool's timeout value
• Reduce the number of instructions or delay durations
• Optimize callback handler performance

UI not updating:

• Ensure callback handlers properly update DOM elements
• Check for CSS conflicts or z-index issues
• Verify event listeners are properly attached

Memory leaks:

• Clean up event listeners in callback handlers
• Avoid creating circular references
• Use proper cleanup functions for long-running operations

Debug Mode

Enable debug logging to troubleshoot instruction execution:

// Enable debug mode
copilot.debug = true;

// Check instruction execution in console
copilot.callbacks.add({
  name: "debug_callback",
  handler: (message) => {
    console.log("Debug callback executed:", message);
  }
});