Skip to main content

Debugging Guide

SmythOS offers a complete set of debugging tools to help you test workflows, inspect component behavior, and catch issues before deployment. This guide walks through each tool and shows how to use them effectively.

Debug Toolbar​

The debug toolbar allows you to activate component-level debugging during development. Once enabled, you can step through components, inspect their state, and monitor execution in real time.

Controls​

  • Debug Mode: Enables inspection for all components.
  • Step: Executes the selected component once.
  • Run/Pause: Starts or pauses the workflow.
  • Stop: Terminates the session.
  • Attach: Links to an external debug request sent into the system.

If a session becomes unresponsive, refresh the page to reset the environment.

Inspecting a Component​

Once debugging is active:

  1. Select a component
  2. Hover to see input/output values, current state, and execution status
  3. Review detailed logs in the component panel

Attach to Running Processes​

The Attach button allows you to connect the debugger to a process that is already running. This includes agents triggered from the Chat interface, API calls, schedules, or external systems.

You do not need to restart or retrigger the agent. Simply enable Debug Mode and click Attach. SmythOS will begin listening for any live executions. As soon as one is detected, the debugger connects automatically and begins displaying the internal state, logs, and data flow in real time.

This is helpful when:

  • You have already sent a message through the Test with Chat interface
  • A function or agent was triggered externally, such as through an API call
  • You are working with agents that were not started from the builder
  • You need to inspect a workflow already in progress without rerunning it

Once attached, you can view inputs, outputs, errors, and execution steps in the visual builder as if the process had started in debug mode.

How to use Attach after a process starts

Use Attach after you've triggered an agent via chat or API.
It listens for live calls and connects as soon as something runs.

Testing with Form Preview​

Use Form Preview to run full workflows from a UI-based form, directly inside the builder.

How It Works​

  • Every agent skill is exposed as an API endpoint through the Agent Skill component.
  • Clicking the Form Preview button auto-generates a form with required input fields.
  • Default values are pre-filled, which you can modify.
  • Clicking "Run" executes the entire workflow.

This lets you validate inputs, debug logic, and verify outputs before deployment.

Tip

Use Form Preview to test workflows without writing any API calls.

Inspect Panel​

The Inspect panel offers structured visibility into agent execution. Access it from the Inspect button at the bottom of the builder interface.

Tabs​

Logs​

  • View a detailed log stream for each component
  • Track inputs, outputs, errors, and timestamps
  • Understand the full execution path

Network​

  • Timeline view of each component’s runtime
  • Identify performance bottlenecks and slow steps
  • View credits consumed by cost-based components like WebSearch or NodeJS
  • Click to highlight that component in the canvas

Source​

  • See the full JSON representation of the current agent
  • Includes component configs, inputs, outputs, globals, and metadata
Tip

Use the Network tab to visually trace workflow execution and locate performance issues.

Error Handling​

Use the reserved _error output to capture execution failures from any component.

{
  "message": "Error description",
  "code": "ERROR_CODE",
  "details": {
    "component": "ComponentName",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Configuration​

  • Must be manually added to components
  • Captures failure metadata
  • Works system-wide or per component

Workflow Optimization​

  • Use the Network tab to analyze execution duration for each component
  • Identify and fix slow or high-cost operations
  • Use cache layers for repeated computations or data access
  • Track credit usage for LLM and API components during testing

What's Next?​

Need Help?

If you encounter persistent debugging issues, review logs, inspect input/output mismatches, and reach out via Support Chat for direct assistance.