Skip to main content
Deepgram's Docs

Search documentation

Type to search this documentation.

On this pageOverview

Build a Voice Agent with Go

This tutorial walks you through building a basic voice agent using Go 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.
  • Go 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 a Go module.

Shell
mkdir deepgram-agent-demo
cd deepgram-agent-demo
go mod init deepgram-agent-demo
touch main.go

Export your Deepgram API key as an environment variable.

Shell
export DEEPGRAM_API_KEY="your_api_key"

2. Install the Deepgram SDK

Section titled “2. Install the Deepgram SDK”

Install the Deepgram Go SDK. The /v3 suffix is required because Go uses major-version module paths.

Shell
go get github.com/deepgram/deepgram-go-sdk/v3

3. Create the Voice Agent

Section titled “3. Create the Voice Agent”

Open main.go and add the following code. This script connects to Deepgram, configures the agent, and streams a sample audio file.

Go
package main

import (
	"bufio"
	"context"
	"fmt"
	"net/http"
	"os"

	msginterfaces "github.com/deepgram/deepgram-go-sdk/v3/pkg/api/agent/v1/websocket/interfaces"
	client "github.com/deepgram/deepgram-go-sdk/v3/pkg/client/agent"
	"github.com/deepgram/deepgram-go-sdk/v3/pkg/client/interfaces"
)

type MyHandler struct {
	binaryChan chan *[]byte
}

func (dch MyHandler) GetBinary() []*chan *[]byte                                                   { return []*chan *[]byte{&dch.binaryChan} }
func (dch MyHandler) GetOpen() []*chan *msginterfaces.OpenResponse                                 { return nil }
func (dch MyHandler) GetWelcome() []*chan *msginterfaces.WelcomeResponse                           { return nil }
func (dch MyHandler) GetConversationText() []*chan *msginterfaces.ConversationTextResponse         { return nil }
func (dch MyHandler) GetUserStartedSpeaking() []*chan *msginterfaces.UserStartedSpeakingResponse   { return nil }
func (dch MyHandler) GetAgentThinking() []*chan *msginterfaces.AgentThinkingResponse               { return nil }
func (dch MyHandler) GetAgentStartedSpeaking() []*chan *msginterfaces.AgentStartedSpeakingResponse { return nil }
func (dch MyHandler) GetAgentAudioDone() []*chan *msginterfaces.AgentAudioDoneResponse             { return nil }
func (dch MyHandler) GetClose() []*chan *msginterfaces.CloseResponse                               { return nil }
func (dch MyHandler) GetError() []*chan *msginterfaces.ErrorResponse                               { return nil }
func (dch MyHandler) GetUnhandled() []*chan *[]byte                                                { return nil }
func (dch MyHandler) GetInjectionRefused() []*chan *msginterfaces.InjectionRefusedResponse         { return nil }
func (dch MyHandler) GetKeepAlive() []*chan *msginterfaces.KeepAlive                               { return nil }
func (dch MyHandler) GetFunctionCallRequest() []*chan *msginterfaces.FunctionCallRequestResponse   { return nil }
func (dch MyHandler) GetSettingsApplied() []*chan *msginterfaces.SettingsAppliedResponse           { return nil }

func main() {
	ctx := context.Background()

	client.Init(client.InitLib{LogLevel: client.LogLevelDefault})

	cOptions := &interfaces.ClientOptions{EnableKeepAlive: true}
	tOptions := client.NewSettingsConfigurationOptions()
	tOptions.Audio.Output.Encoding = "linear16"
	tOptions.Audio.Output.SampleRate = 24000
	tOptions.Audio.Output.Container = "wav"
	tOptions.Agent.Language = "en"
	tOptions.Agent.Greeting = "Hello! How can I help you today?"
	tOptions.Agent.Listen.Provider = map[string]interface{}{
		"type":  "deepgram",
		"model": "nova-3",
	}
	tOptions.Agent.Think.Provider = map[string]interface{}{
		"type":  "open_ai",
		"model": "gpt-4o-mini",
	}
	tOptions.Agent.Think.Prompt = "You are a friendly AI assistant."
	tOptions.Agent.Speak.Provider = map[string]interface{}{
		"type":  "deepgram",
		"model": "aura-2-thalia-en",
	}

	handler := &MyHandler{binaryChan: make(chan *[]byte)}

	go func() {
		counter := 0
		for br := range handler.binaryChan {
			counter++
			file, _ := os.Create(fmt.Sprintf("output_%d.wav", counter))
			file.Write(*br)
			file.Close()
		}
	}()

	dgClient, _ := client.NewWSUsingChan(ctx, "", cOptions, tOptions, msginterfaces.AgentMessageChan(*handler))
	dgClient.Connect()

	resp, _ := http.Get("https://dpgr.am/spacewalk.wav")
	defer resp.Body.Close()

	dgClient.Stream(bufio.NewReader(resp.Body))

	fmt.Println("Press ENTER to exit")
	bufio.NewScanner(os.Stdin).Scan()
	dgClient.Stop()
}

4. Run the Voice Agent

Section titled “4. Run the Voice Agent”

Run your script using the Go CLI.

Shell
go run main.go

The agent will process the audio and generate responses. You can find the agent's audio responses in output_*.wav files in your project directory.

Next steps

Section titled “Next steps”

Now that you have built a basic agent, you can customize its behavior:

Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu