Debug Agents with Weaver

Weaver gives you built-in tools to find, fix, and prevent errors without leaving chat or the Canvas. This guide walks you from quick fixes to deeper diagnosis, then prevention.

Quick Fix Flow

Click the red component, review its input and output snapshot, press Fix with AI, then rerun. Most problems resolve in under a minute.

Spot Problems Quickly

Component border colors show status during a run:

Border Colour	Meaning	What To Do
🟢 Green	Success	No action needed
🟡 Yellow	Waiting for upstream	Inspect earlier components
🟠 Orange	Missing required input	Connect the correct input or fill a field
⚪ Grey	Still running	Let it complete
🔴 Red	Failed	Start diagnosis

Why This Works

Weaver’s visual debugger and Canvas updates make it easy to “see where it broke” before you dive into details.

Diagnose with Inputs and Outputs

Click any red component to open its inspector. You will see the inputs the block received and the output or error it produced. Look for:

• Empty or malformed inputs
• 500-level API responses
• Quota or rate-limit errors
• JSON parsing failures

Example diagnosis:

Input: { 'article': '' } Output: Error: Empty string cannot be processed

Upstream vs Local Errors

If inputs are wrong or empty, fix the upstream step or wiring. If inputs look fine, adjust this component’s configuration or prompt.

Fix with AI

When the issue is prompt or parameter related, use Fix with AI on the failing block. Provide a short, direct instruction:

Article text exceeded 5000 characters. Trim to 800 characters and retry.

Weaver updates the component’s prompt or parameters, reruns the block, and shows you what changed. If it stays red, refine your instruction and try again.

Handle Cascading Failures

Select multiple components with Cmd/Ctrl + click, then rerun them in sequence. This helps when a bad output flows downstream and several blocks need to be re-executed together.

Rollback

If a series of changes made things worse, use the Revert and Reapply to revert to a clean state and try again.

Common Error Recipes

Symptom	Likely Fix
JSON parse error	In the upstream LLM or transformer, constrain output to strict JSON and validate before passing forward.
Quota or rate limit	Insert a Sleep component between retries. You can pass a variable like Retry-After to wait exactly as required.
Empty input	Check Canvas wiring and ensure the expected upstream output is connected.
Unexpected API format	Normalize with a JSON Filter or transformer before the next step.

Reference Components

You will find Sleep for timed pauses, JSON Filter for shaping payloads, and other helpers in the Component Library.

Prevent Tomorrow’s Bugs

• Keep workflows modular so each step is easy to test in isolation.
• Save real test inputs and reuse them while iterating.
• Lean on linting to catch prompt ambiguities, weak types, or missing auth early.
• Throttle retries with Sleep to respect API limits and backoff policies.

Sleep Component Tip

Sleep can take a fixed duration or a variable such as an API’s Retry-After value, which makes rate-limit handling reliable.

Use Debug Mode and Logs

Turn on Debug Mode from the toolbar when you need deeper inspection. You will see:

• Execution timeline per component
• Request and response payloads
• Headers and runtime metadata
• Parsed inputs and structured outputs
• Model prompts and replies
• Click-through trace from a log entry to the block on Canvas

Use the Agent Activity Logs to compare expected versus actual results across runs and to spot slow or flaky steps.

Reading Logs Effectively

Filter by run, jump to the failing block, and compare payloads before and after your fix to confirm the change worked.

When You Need Extra Help

• Export your agent and test it locally with the SmythOS runtime.
• Share minimal repro steps and payloads in the Discord debugging channel.
• Keep logs handy so others can help you pinpoint the failure quickly.

Start Small

Inspect the failing block first. Large, sweeping changes often mask the real issue and slow you down.

Next Steps

• See real prompts that trigger these patterns in the Prompt Library.
• If you are new to Weaver, try the Weaver Quickstart.
• Browse the Component Library for Sleep, JSON tools, and other helpers.
• Review your run history in Agent Logs whenever something feels off.