Session recording options

Overview

The record parameter on AgentSession.start() controls which observability data is collected and uploaded for that session: audio, transcripts, traces, and logs. You can follow the project setting, turn everything off, turn everything on, or opt out of specific categories.

The data this parameter governs is what you see in Agent insights.

Recording modes

The value you pass to record sets one of four recording modes:

• Follow the project setting (default): omit record. The session collects everything when Agent observability is on for the project, and nothing when it's off.
• Record nothing: pass record=False. No audio, transcripts, traces, or logs are uploaded.
• Record everything: pass record=True, subject to the project setting.
• Granular control: pass an options object. Omitted audio, transcript, traces, and logs keys default to True, so specify only what you turn off.

Granular options

Pass an options object to set each category independently. Each option takes a boolean value:

The following examples show each recording mode:

# Follow the project setting (default)
await session.start(agent)

# Record everything the project setting allows
await session.start(agent, record=True)

# Record nothing
await session.start(agent, record=False)

# Record audio only
await session.start(
    agent,
    record={"audio": True, "traces": False, "logs": False, "transcript": False},
)

# Redact this session even if the project setting is off
await session.start(agent, record={"redaction": True})

// Follow the project setting (default)
await session.start({ agent });

// Record everything the project setting allows
await session.start({ agent, record: true });

// Record nothing
await session.start({ agent, record: false });

// Record audio only
await session.start({
  agent,
  record: { audio: true, traces: false, logs: false, transcript: false },
});

// Redact this session even if the project setting is off
await session.start({ agent, record: { redaction: true } });

Rules and limits

The following rules apply to every recording mode:

• The project setting comes first. When Agent observability is off, a session uploads nothing, whatever you pass to record. For the warning the agent logs, see Recording was off.
• Text-only sessions never record audio.
• Only the first session in a job is recorded. A later AgentSession that asks to record raises an error. Omit record to turn recording off for it automatically, or pass record=False.
• A session can turn on redaction, but not turn it off. record={"redaction": True} redacts the session even when the project setting is off. When the project setting is on, "redaction": False has no effect.

Additional resources