Action Trace

Action tracing provides comprehensive visibility into your automation workflows through two complementary features: detailed step logging and visual GIF recording.

Action Trace Response

An action trace records the individual browser actions performed by /Operator, such as navigating, typing, clicking, and selecting elements. In the Python SDK, access it through response.action_trace. For Agent Studio custom-agent workflow steps and nested workflows, use Workflow Trace instead.

Operator Traces

Simple action logs for /Operator commands:

{
  "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"
    }
  ]
}

Operator Action Timing

Timed Operator browser actions include optional startTs, endTs, and durationMs fields. The first two are Unix epoch milliseconds measured in the browser, and durationMs is the elapsed milliseconds between them. Composite actions can include nested children; timing currently describes the parent action rather than each child. The synthetic Done item has no timing fields.

{
  "url": "https://example.com",
  "action": "Clicked More information",
  "startTs": 1720000000000,
  "endTs": 1720000000350,
  "durationMs": 350
}

In the Python SDK, the same fields are available on response.action_trace items as start_ts, end_ts, and duration_ms.

Nested Operator Traces

When a custom workflow invokes Operator, that workflow step can include its Operator action trace:

{
  "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": [...]
    }
  ]
}

Legacy Custom Agent Step Types

Legacy custom-agent action 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):

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):
        # SDK response items are Pydantic models; normalize them for dictionary access.
        if hasattr(step, "model_dump"):
            step = step.model_dump()

        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

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.

Automatic Directory Creation

Narada automatically creates a directory structure for your GIFs:

Main Directory: Narada Downloads in your machine’s Downloads folder
Request Directory: Directory named after your request_id from the SDK response
File: Automation saved as an animated .gif file

If the Narada Downloads directory doesn’t exist, it will be created automatically.

Find Your GIF File

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

Debugging

Use action traces for programmatic debugging and GIFs for visual verification

Auditing

Action traces provide detailed audit logs for compliance and monitoring

Documentation

GIFs document visual workflows while action traces capture step-by-step logic

Analysis

Parse action traces to analyze automation patterns and optimize workflows

Getting Started

Development

Web Agent Guides

Narada Assistant

Action Trace Response

Operator Traces

Operator Action Timing

Nested Operator Traces

Legacy Custom Agent Step Types

Formatting Example

GIF Recording

Best Practices

Debugging

Auditing

Documentation

Analysis

​Action Trace Response

​Operator Traces

​Operator Action Timing

​Nested Operator Traces

​Legacy Custom Agent Step Types

​Formatting Example

​GIF Recording

​Best Practices

Debugging

Auditing

Documentation

Analysis

Action Trace Response

Operator Traces

Operator Action Timing

Nested Operator Traces

Legacy Custom Agent Step Types

Formatting Example

GIF Recording

Best Practices