How to build an agent with speech-to-text input and text-only output

You can configure a LiveKit Agent to accept audio input (speech-to-text) while responding only with text—no TTS audio output. This is useful for chat-style interfaces where you want voice input but text-based responses.

Configuration

To set this up, disable audio output when starting your agent session while keeping audio input enabled:

Python

1
from livekit.agents.voice import room_io
2

3
await session.start(
4
    agent=MyAgent(),
5
    room=ctx.room,
6
    room_options=room_io.RoomOptions(
7
        audio_output=False,  # Disable TTS audio output
8
        # audio_input remains True by default
9
    ),
10
)

Node.js

1
await session.start({
2
  agent: new MyAgent(),
3
  room: ctx.room,
4
  outputOptions: {
5
    audioEnabled: false,  // Disable TTS audio output
6
  },
7
  // inputOptions.audioEnabled remains true by default
8
});

When audio output is disabled:

• The agent will not publish an audio track to the room
• Text responses are published to the lk.transcription text stream topic
• Responses are sent without the lk.transcribed_track_id attribute (since there's no audio track to associate with)
• Text is sent without speech synchronization

Receiving Agent Responses

To receive the agent's text responses, you need to listen to the lk.transcription text stream topic on your frontend client. The built-in playground UI uses legacy transcription events and won't display responses when audio track publishing is disabled.

JavaScript

1
room.registerTextStreamHandler('lk.transcription', async (reader, participantInfo) => {
2
  const message = await reader.readAll();
3
  
4
  // Check if this is a transcription (has track ID) or a text-only response
5
  const isTranscription = reader.info.attributes['lk.transcribed_track_id'] != null;
6
  
7
  if (isTranscription) {
8
    console.log(`Transcription from ${participantInfo.identity}: ${message}`);
9
  } else {
10
    // This is a text-only agent response (no audio)
11
    console.log(`Agent response from ${participantInfo.identity}: ${message}`);
12
  }
13
});

Swift

1
try await room.registerTextStreamHandler(for: "lk.transcription") { reader, participantIdentity in
2
    let message = try await reader.readAll()
3
    
4
    if let _ = reader.info.attributes["lk.transcribed_track_id"] {
5
        print("Transcription from \(participantIdentity): \(message)")
6
    } else {
7
        // Text-only agent response
8
        print("Agent response from \(participantIdentity): \(message)")
9
    }
10
}

React

For React applications, use the useTranscriptions hook from @livekit/components-react:

1
import { useTranscriptions } from '@livekit/components-react';
2

3
function ChatDisplay() {
4
  const transcriptions = useTranscriptions();
5
  
6
  return (
7
    <div>
8
      {transcriptions.map((segment) => (
9
        <div key={segment.id}>
10
          <strong>{segment.participant?.identity}:</strong> {segment.text}
11
        </div>
12
      ))}
13
    </div>
14
  );
15
}

Important Notes

• Console playground limitation: If you're using the console playground and don't see agent responses to audio input, this is expected behavior. You must implement a custom receiver to listen to the lk.transcription text stream topic.

• Distinguishing response types: When audio output is disabled, agent responses won't have a lk.transcribed_track_id attribute. You can use this to differentiate between transcriptions of audio tracks and text-only responses.

• Hybrid mode: If you need to dynamically toggle audio on and off, use session.output.set_audio_enabled() instead of disabling it in RoomOptions. See the text and transcriptions guide for more details.

Example Implementations

For complete working examples, check out:

• Transcriber agent: An agent that performs STT without TTS or LLM
• Text streams documentation: Full guide on receiving and sending text streams

Additional Resources

• Text and transcriptions guide - Complete documentation on text input/output in agents
• Voice agents examples repository - More agent examples

Read related documentation

• LiveKit Agents overview - Get started with voice AI agents
• Speech-to-text plugins - Configure STT providers
• Text streams - Send and receive text data

Find more Agents guides

• Troubleshooting STT not picking up utterances - Diagnose speech detection issues
• How to detect when an agent has finished speaking - Track playback completion events