> ## 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.

# Workflow Trace

> Inspect custom agent workflow execution

## Workflow Trace Response

Custom GUI and Python agent runs can return a workflow trace. In raw API responses this is
`workflowTrace`; in the Python SDK it is `response.workflow_trace`.

## Choosing A Trace

Use `response.action_trace` to inspect individual `/Operator` browser actions, such as navigation,
typing, clicks, and element selection. Use `response.workflow_trace` to inspect the execution of an
Agent Studio custom workflow: its workflow-level status, GUI steps, and nested workflows. A workflow
step that invokes Operator can include its own nested action trace.

The workflow envelope and timed GUI step timestamps use `startTs` and `endTs`.

```json theme={null}
{
  "workflowTrace": {
    "workflowId": "workflow_123",
    "workflowName": "Example workflow",
    "runtime": "gui",
    "status": "success",
    "startTs": 1720000000000,
    "endTs": 1720000001200,
    "children": [
      {
        "kind": "gui_step",
        "stepId": "step_navigate",
        "stepType": "goToUrl",
        "label": "Navigate",
        "status": "success",
        "startTs": 1720000000000,
        "endTs": 1720000000500,
        "children": []
      }
    ]
  }
}
```

`endTs` is omitted while a workflow or step is still running. It is also absent when no end time
was recorded.

## Workflow Envelope

| Field          | Description                                          |
| -------------- | ---------------------------------------------------- |
| `workflowId`   | Identifier of the custom agent workflow.             |
| `workflowName` | Name of the workflow.                                |
| `runtime`      | Workflow runtime: `gui` or `python`.                 |
| `status`       | Final workflow status.                               |
| `startTs`      | Timestamp when the workflow started.                 |
| `endTs`        | Timestamp when the workflow ended, when recorded.    |
| `children`     | Trace nodes for workflow steps and nested workflows. |

## Trace Nodes

### GUI Nodes

GUI workflow step nodes have `kind: "gui_step"` and include `stepId`, `stepType`, `status`, and
`children`. They include `startTs` and, once complete, `endTs`. Nested workflow nodes have
`kind: "sub_workflow"`, carry their own workflow trace, and follow the same timestamp fields.

### Python Nodes

Python workflow traces can include the following child nodes:

| Node kind      | Description                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `output`       | A stdout or stderr entry with `channel`, `text`, `ts`, and `seq`.                                                        |
| `sdk_event`    | An SDK call event with `event`, `ts`, and `seq`. The event describes a sub-agent call, extension action, or side effect. |
| `sub_workflow` | A nested workflow with its own workflow trace.                                                                           |