Build a Voice Agent with JavaScript
This tutorial walks you through building a basic voice agent using JavaScript and the Deepgram SDK. You will learn how to connect to the Agent API, configure its behavior, and stream audio for processing.
Prerequisites
Section titled “Prerequisites”Before you begin, ensure you have the following:
- A Deepgram API key. You can get one in the Deepgram Console.
- Node.js installed on your machine.
1. Set up your environment
Section titled “1. Set up your environment”Create a new directory for your project and initialize it.
mkdir deepgram-agent-demo
cd deepgram-agent-demo
npm init -y
touch index.jsExport your Deepgram API key as an environment variable.
export DEEPGRAM_API_KEY="your_api_key"2. Install the Deepgram SDK
Section titled “2. Install the Deepgram SDK”Install the Deepgram JavaScript SDK and cross-fetch for audio streaming.
npm install @deepgram/sdk cross-fetch3. Create the Voice Agent
Section titled “3. Create the Voice Agent”Open index.js and add the following code. This script connects to Deepgram, configures the agent, and streams a sample audio file.
const { writeFile, appendFile } = require("fs/promises");
const { DeepgramClient } = require("@deepgram/sdk");
const fetch = require("cross-fetch");
const { join } = require("path");
const deepgram = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });
const agent = async () => {
let audioBuffer = Buffer.alloc(0);
let i = 0;
const url = "https://dpgr.am/spacewalk.wav";
const connection = await deepgram.agent.v1.connect();
connection.on("message", async (data) => {
if (data.type === "Welcome") {
console.log("Welcome to the Deepgram Voice Agent!");
connection.sendSettings({
type: "Settings",
audio: {
input: {
encoding: "linear16",
sample_rate: 24000,
},
output: {
encoding: "linear16",
sample_rate: 16000,
container: "wav",
},
},
agent: {
language: "en",
listen: {
provider: {
type: "deepgram",
model: "nova-3",
},
},
think: {
provider: {
type: "open_ai",
model: "gpt-4o-mini",
},
prompt: "You are a friendly AI assistant.",
},
speak: {
provider: {
type: "deepgram",
model: "aura-2-thalia-en",
},
},
greeting: "Hello! How can I help you today?",
},
});
console.log("Deepgram agent configured!");
setInterval(() => {
console.log("Keep alive!");
connection.sendKeepAlive({ type: "KeepAlive" });
}, 5000);
fetch(url)
.then((r) => r.body)
.then((res) => {
res.on("readable", () => {
const chunk = res.read();
if (chunk) {
console.log("Sending audio chunk");
connection.sendMedia(chunk);
}
});
});
} else if (data.type === "ConversationText") {
await appendFile(join(__dirname, `chatlog.txt`), JSON.stringify(data) + "\n");
} else if (data.type === "UserStartedSpeaking") {
if (audioBuffer.length) {
console.log("Interrupting agent.");
audioBuffer = Buffer.alloc(0);
}
} else if (typeof Blob !== "undefined" && data instanceof Blob) {
console.log("Audio chunk received");
const chunk = Buffer.from(await data.arrayBuffer());
audioBuffer = Buffer.concat([audioBuffer, chunk]);
} else if (data.type === "AgentAudioDone") {
console.log("Agent audio done");
await writeFile(join(__dirname, `output-${i}.wav`), audioBuffer);
audioBuffer = Buffer.alloc(0);
i++;
}
});
connection.on("open", () => {
console.log("Connection opened");
});
connection.on("close", () => {
console.log("Connection closed");
process.exit(0);
});
connection.on("error", (err) => {
console.error("Error:", err.message);
});
connection.connect();
await connection.waitForOpen();
};
void agent();4. Run the Voice Agent
Section titled “4. Run the Voice Agent”Run your script using Node.js.
node index.jsThe agent will process the audio and generate responses. You can find the conversation transcript in chatlog.txt and the agent's audio responses in output-*.wav files.
Next steps
Section titled “Next steps”Now that you have built a basic agent, you can customize its behavior:
- Configure the Voice Agent: Explore all available settings for models and voices.
- Build a Voice Agent: Return to the overview to see other language options.