> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narada.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Action Trace
> Detailed logging and visual recording of automation workflows
Action tracing provides comprehensive visibility into your automation workflows through two complementary features: detailed step logging and visual GIF recording.
## Action Trace Response
Action traces provide detailed step-by-step logs of automation execution, returned in API responses for both custom agent shortcuts and `/Operator` commands.
### Operator Traces
Simple action logs for `/Operator` commands:
```json theme={null}
{
"actionTrace": [
{
"url": "https://arxiv.org/",
"action": "Typed 'artificial intelligence' and pressed Enter into search input"
},
{
"url": "https://arxiv.org/search/",
"action": "Clicked on search button"
}
]
}
```
### Custom Agent Traces
Detailed step logs for custom agent workflows with multiple action types:
```json theme={null}
{
"actionTrace": [
{
"url": "https://example.com",
"step_type": "goToUrl",
"description": "Navigated to https://example.com"
},
{
"url": "https://example.com",
"step_type": "agent",
"agent_type": "operator",
"action_trace": [...]
}
]
}
```
#### Supported Step Types
Custom agent traces use a `step_type` field to identify the action. The full list of supported step types:
| Step Type | Description |
| ------------------------------------------------- | ----------------------------------------------------- |
| `start` / `end` | Workflow boundaries |
| `goToUrl` | Navigate to a URL |
| `getUrl` | Get the current page URL |
| `agent` | Sub-agent invocation (contains nested `action_trace`) |
| `agenticSelector` | Element selection via CSS selectors with fallback |
| `agenticMouseAction` | Mouse action at recorded coordinates |
| `getFullHtml` / `getSimplifiedHtml` | HTML content capture |
| `getScreenshot` | Screenshot capture |
| `print` | Print a message to the chat |
| `python` | Inline Python code execution |
| `for` / `while` | Loop constructs |
| `if` | Conditional branching |
| `setVariable` | Variable assignment |
| `wait` | Delay step |
| `waitForElement` | Wait for an element to appear |
| `pressKeys` | Keyboard input |
| `readGoogleSheet` / `writeGoogleSheet` | Google Sheets operations |
| `dataTableExportAsCsv` | Export data as CSV |
| `objectExportAsJson` | Export data as JSON |
| `dataTableInsertRow` / `dataTableUpdateCellValue` | Data table operations |
| `objectSetProperties` | Object property updates |
| `runCustomAgent` | Invoke another custom agent workflow |
### Formatting Example
Convert action traces to readable markdown (handles multiple custom agent step types):
```python theme={null}
def format_action_trace(trace_data):
if not trace_data:
return "No action trace available"
markdown = "# Action Trace\n\n"
for i, step in enumerate(trace_data, 1):
if 'action' in step:
# Operator trace
markdown += f"{i}. **{step['url']}**\n - {step['action']}\n\n"
else:
# Custom agent trace - handle different step types
step_type = step['step_type']
description = step.get('description', step_type)
if step_type == 'goToUrl':
markdown += f"{i}. 🌐 **Navigate** to {step.get('url', 'URL')}\n"
elif step_type == 'agent':
agent_type = step.get('agent_type', 'unknown')
markdown += f"{i}. 🤖 **Agent** ({agent_type}) - {description}\n"
if step.get('action_trace'):
markdown += f" - Contains {len(step['action_trace'])} sub-actions\n"
elif step_type in ['for', 'while']:
markdown += f"{i}. 🔄 **Loop** ({step_type}) - {description}\n"
elif step_type == 'python':
markdown += f"{i}. 🐍 **Code Execution** - {description}\n"
elif step_type == 'print':
markdown += f"{i}. 📝 **Message** - {description}\n"
elif step_type == 'agenticSelector':
markdown += f"{i}. 🎯 **Element Selection** - {description}\n"
elif step_type == 'agenticMouseAction':
markdown += f"{i}. 🖱️ **Mouse Action** - {description}\n"
else:
markdown += f"{i}. ⚡ **{step_type.title()}** - {description}\n"
markdown += "\n"
return markdown
```
## GIF Recording
```python highlight={11} theme={null}
import asyncio
from narada import Agent, BrowserEnvironment
async def main() -> None:
env = BrowserEnvironment()
agent = Agent(environment=env)
try:
# Run automation with GIF recording enabled
response = await agent.run(
prompt='search for "machine learning" on Google and extract the number of results',
generate_gif=True # Enable GIF recording
)
print("Response:", response.text)
print("GIF saved to your Downloads/Narada Downloads folder!")
finally:
await env.close()
if __name__ == "__main__":
asyncio.run(main())
```
The SDK automatically compiles frames into an animated GIF showing the complete
automation trajectory.
Narada automatically creates a directory structure for your GIFs:
1. **Main Directory**: `Narada Downloads` in your machine's Downloads folder
2. **Request Directory**: Directory named after your `request_id` from the [SDK response](/documentation/getting-started-with-sdk)
3. **File**: Automation saved as an animated `.gif` file
If the `Narada Downloads` directory doesn't exist, it will be created automatically.
Navigate to your Downloads folder and look for:
```
Downloads/
└── Narada Downloads/
└── req_abc123def456/
└── automation_recording.gif
```
Each GIF request gets its own directory named after the `request_id` for easy correlation with your SDK calls.
## Best Practices
Use action traces for programmatic debugging and GIFs for visual verification
Action traces provide detailed audit logs for compliance and monitoring
GIFs document visual workflows while action traces capture step-by-step logic
Parse action traces to analyze automation patterns and optimize workflows