> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Recording

> Record an agent session automatically by enabling recording on serve or invoke.

Recording captures session activity for analysis, compliance, and quality assurance. Zero Runtime Agents support automatic recording with a single configuration flag. Recordings can be accessed in the Zero Runtime Dashboard with transcripts and timestamps, or downloaded for offline review.

## How It Works

Enable recording when you serve or invoke the agent, and the framework automatically:

* Starts recording when the agent joins the session.
* Starts recording for each participant as they join.
* Stops and merges the recordings when the session ends.

Audio is always recorded when recording is on. Recording defaults to off, and no pipeline changes are needed once you enable it.

## What You Can Record

By default, only audio is captured. Pass a `RecordingConfig` to opt in to additional streams:

| Option                | Type | Default | Records                                                        |
| --------------------- | ---- | ------- | -------------------------------------------------------------- |
| `record_video`        | bool | `False` | The agent's camera video track.                                |
| `record_screen_share` | bool | `False` | The screen-share track. Requires `vision=True` on the session. |

## Configure Recording

The quickest way to record every session a process serves is `recording=True` on `zrt.serve()`:

<CodeGroup>
  ```python title="main.py" Python theme={null}
  import zrt

  # Record every session this process serves.
  zrt.serve(Assistant, recording=True, on_ready=lambda: zrt.invoke(AGENT_ID))
  ```
</CodeGroup>

You can also turn recording on for a single session by setting `recording=True` on the `Room` you pass to `zrt.invoke()`:

<CodeGroup>
  ```python title="main.py" Python theme={null}
  import zrt

  zrt.invoke(AGENT_ID, room=zrt.Room(recording=True))
  ```
</CodeGroup>

To also record camera video, pass a `RecordingConfig` with `record_video=True` instead of a plain `True`:

<CodeGroup>
  ```python title="main.py" Python theme={null}
  import zrt
  from zrt import RecordingConfig

  zrt.serve(
      Assistant,
      recording=RecordingConfig(enabled=True, record_video=True),
      on_ready=lambda: zrt.invoke(AGENT_ID),
  )
  ```
</CodeGroup>

To record the screen-share track, set `record_screen_share=True` along with `vision=True` on the session:

<CodeGroup>
  ```python title="main.py" Python theme={null}
  import zrt
  from zrt import RecordingConfig

  zrt.serve(
      Assistant,
      vision=True,  # required for screen-share recording
      recording=RecordingConfig(enabled=True, record_screen_share=True),
      on_ready=lambda: zrt.invoke(AGENT_ID, room=zrt.Room(vision=True)),
  )
  ```
</CodeGroup>

<Warning>
  `record_screen_share=True` requires `vision=True` because vision is what subscribes to the video and share streams. Without `vision=True`, there is no screen-share track to capture, so the screen-share recording has no effect.
</Warning>

## Recording Lifecycle Events

Recording lifecycle hooks let you observe when recording starts, stops, or fails without polling any API. They are side-effect-only: they react to events without changing the data flow.

<Note>
  Hooks fire only when recording is enabled. Turn recording on with `recording=True` on `zrt.serve()`, or by setting `recording=True` on the `Room` you pass to `zrt.invoke()`.
</Note>

| Hook                | Fires when                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| `recording_started` | Recording starts successfully.                                                                                |
| `recording_stopped` | Recording stops successfully, typically at session end.                                                       |
| `recording_failed`  | Recording fails to start or stop. Use it to surface issues to your monitoring system before the session ends. |

Register the hooks on your pipeline to react to each event:

<CodeGroup>
  ```python title="main.py" Python theme={null}
  @pipeline.on("recording_started")
  def on_recording_started(data):
      """Fired when recording starts successfully."""
      print(f"[RECORDING HOOK] Started: {data}")

  @pipeline.on("recording_stopped")
  def on_recording_stopped(data):
      """Fired when recording stops successfully."""
      print(f"[RECORDING HOOK] Stopped: {data}")

  @pipeline.on("recording_failed")
  def on_recording_failed(data):
      """Fired when recording fails to start or stop."""
      print(f"[RECORDING HOOK] Failed: {data}")
  ```
</CodeGroup>

## Best Practices

* Inform participants that the session is being recorded.
* Ensure requests are properly authenticated with a valid token.
* Monitor recording status and errors using the recording lifecycle hooks.
* Implement a data retention policy and meet the regulations that apply to your users.

## What's Next

<CardGroup cols={2}>
  <Card title="Analytics" icon="chart-line" href="/build/observability-and-monitoring/analytics/overview">
    Pair recordings with traces, metrics, and logs for each session.
  </Card>

  <Card title="Run Your Agent" icon="play" href="/build/run-the-runtime">
    Run an agent session and capture it with recording.
  </Card>
</CardGroup>

## References

<Tabs>
  <Tab title="Python">
    #### SDK Reference

    <CardGroup cols={2}>
      <Card title="Recording" icon="book" href="/api-reference/python/core/recording-and-audio">
        Recording in the Python API reference.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>