Add optional execution trace export for debugging agent runs

[petiole-planks]

Language Implementation

• Python
• TypeScript

Feature Type

• Action Provider Template
• Wallet Provider Template
• Framework Extension
• Core Requirements
• Other

🚀 The feature, motivation and pitch

Overview

When agents perform multi-step reasoning or tool execution, it can be difficult to understand why a specific decision or action was taken. Today, developers often rely on logs or manual instrumentation to reconstruct an agent’s execution path.

Problem Description

Without a structured execution trace:

• Debugging complex agent behavior is time-consuming.
• Comparing expected vs actual agent behavior is difficult.
• Observability tools cannot easily consume agent execution details.

This limits confidence when agents behave unexpectedly in production.

Proposed Solution

Introduce an optional execution trace feature that records structured steps of an agent run, including decisions, tool invocations, inputs, outputs, and timing. The trace should be exportable (e.g., JSON) and disabled by default to avoid performance impact.

Acceptance Criteria

Developers can enable execution tracing on demand and receive a structured trace of agent execution. Traces are safe to log or store and do not include secrets by default. Existing agent behavior remains unchanged when tracing is disabled.

Alternatives

No response

Additional context

No response