Skip to main content
Minitap provides powerful observability features to help you debug and understand your task executions. Whether running locally or on the platform, you can capture detailed traces of agent behavior.

Overview

Local Traces

Screenshots and action logs saved to your local filesystem

Platform GIF Upload

Animated GIF automatically uploaded to platform for easy viewing

How It Works

How it works:
  • When record_trace=True (default), a GIF is created locally from screenshots
    • For platform tasks, the GIF is automatically uploaded to cloud storage
    • Local GIF is always saved, even if upload fails
    • Access control via API key - only you can view your traces

Local Trace Recording

Enable trace recording to save screenshots and action logs locally.

Basic Usage

Custom Path

What Gets Saved

Local traces include:
  • trace.gif: An animated GIF showing the entire execution. It’s a compilation of screenshots taken after each agent step.
  • steps.json: A compilation of the agent’s thoughts and reasoning during the run, along with timestamps.

Platform GIF Upload

When running platform tasks, traces are automatically uploaded to Minitap cloud storage for easy viewing in the web UI.

Automatic Upload (Default)

Platform tasks upload GIF traces by default. You don’t need to specify record_trace=True:

Disable Upload (Optional)

To disable cloud upload while keeping local GIF creation, set record_trace=False:

Manual Tasks

Manual tasks (using ManualTaskConfig) also support GIF upload:

Viewing Platform Traces

SDK Runs List

Navigate to SDK Runs to see all your task executions with GIF previews:
SDK Runs list with GIF thumbnails
Each run card shows:
  • Task status
  • Execution duration
  • LLM profile used
  • GIF thumbnail preview

Task Run Details

Click “View details” to see the full execution trace:
Task run details with playable GIF
The details page includes:
  • Input prompt and output
  • Playable GIF of the execution
  • Start time and duration
  • LLM profile configuration
  • Agent thoughts and reasoning
Use the GIF player to step through the execution and identify where issues occurred.

Configuration Reference

PlatformTaskRequest Parameters

bool
default:true
Controls GIF creation and upload. When True (default), a GIF is created locally and uploaded to the platform. Set to False to disable cloud upload (local GIF still created).
Path
Local directory to save trace files. Defaults to system temporary directory.

Example

Console Output


Troubleshooting

Upload Failed

If the GIF upload fails, check:
Maximum GIF size is 300MB. Very long-running tasks (+1h) may exceed this limit. Reduce max_steps in your task configuration or split into multiple shorter tasks.

Verify Upload Success

Check the console output for the platform URL:
If you see this message, the upload succeeded. Click the link to view your trace.

Missing GIF on Platform

If the GIF doesn’t appear on the platform:
  1. Check task status - GIF upload happens after task completes
  2. Verify record_trace=True - Default is true, but confirm it wasn’t disabled
  3. Check console for errors - Look for upload failure messages
  4. Refresh the page - Browser cache may show old data

Best Practices

Tracing is enabled by default for easy debugging. Disable it when processing sensitive data or running many tasks in production:

Next Steps

Platform Quickstart

Learn more about platform task execution

Task Request Builder

Explore all task configuration options

Troubleshooting

Common issues and solutions

Examples

See complete working examples