Go SDK

The github.com/AgoraIO/agora-agents-go/v2 Go SDK supports the Conversational AI Platform (Preview) alongside the Voice Agent API. This page covers the Platform features: saved agents, Platform sessions, secret sets, phone numbers, campaigns, and the low-level client.V3 client.

The vendor constructors, such as vendors.NewOpenAI() and vendors.NewDeepgramSTT(), and the builder methods, such as WithLlm(), are shared with the Voice Agent API. For those, see the Go SDK reference for Voice Agents.

InstallCopy Anchor Link

Platform support is in the SDK preview, version v2.14.0-alpha.3. You need Go 1.21 or later. Add the SDK to your Go module:

go get github.com/AgoraIO/agora-agents-go/v2@v2.14.0-alpha.3
go mod tidy

Import the packages you use:

import (
	"github.com/AgoraIO/agora-agents-go/v2/agentkit"
	"github.com/AgoraIO/agora-agents-go/v2/agentkit/vendors"
	"github.com/AgoraIO/agora-agents-go/v2/option"
	"github.com/AgoraIO/agora-agents-go/v2/v3"
)

The v3 package holds the low-level Platform types, such as v3.ListOptions. Import it when you use them.

AgoraClientCopy Anchor Link

Create a client with one of the following authentication methods. To choose one, see Choose an authentication method.

• Token authentication: Pass your App ID and App Certificate. The SDK generates a ConvoAI token for each Platform request.

  Copy Text

  client := agentkit.NewAgoraClient(agentkit.AgoraClientOptions{
  	Area:           option.AreaUS,
  	AppID:          os.Getenv("AGORA_APP_ID"),
  	AppCertificate: os.Getenv("AGORA_APP_CERTIFICATE"),
  })

• Basic HTTP authentication: Pass your App ID, customer ID, and customer secret. The SDK sends Authorization: Basic <base64_credentials> with each request.

  Copy Text

  client := agentkit.NewAgoraClient(agentkit.AgoraClientOptions{
  	Area:           option.AreaUS,
  	AppID:          os.Getenv("AGORA_APP_ID"),
  	CustomerID:     os.Getenv("AGORA_CUSTOMER_ID"),
  	CustomerSecret: os.Getenv("AGORA_CUSTOMER_SECRET"),
  })

Without an App Certificate, the SDK can't generate the agent's RTC token. To start an RTC session with a Basic client and no App Certificate, pass the RTC token when you create the session.

The client exposes the following Platform resources:

AgentCopy Anchor Link

*agentkit.Agent is an immutable builder. Each builder method returns a new *Agent. To save a configuration on the Platform, build it with the vendor constructors and call Save().

agent := agentkit.NewAgent(client).
	WithStt(vendors.NewDeepgramSTT(vendors.DeepgramSTTOptions{Model: "nova-3", Language: "en-US"})).
	WithLlm(vendors.NewOpenAI(vendors.OpenAIOptions{Model: "gpt-4.1-mini"})).
	WithTts(vendors.NewOpenAITTS(vendors.OpenAITTSOptions{Model: "tts-1", Voice: "alloy"})).
	WithVariable("customer_name", agentkit.VariableDefinition{Type: "str", Required: true})

savedAgent, err := agent.Save(ctx, agentkit.SaveOptions{Name: "Support agent"})

The vendor constructors and WithVariable() panic on invalid input, because they don't return an error.

VariablesCopy Anchor Link

func (a *Agent) WithVariable(name string, def VariableDefinition) *Agent

Declares a variable and returns a new *Agent. def is an agentkit.VariableDefinition:

A variable name starts with a lowercase letter and contains up to 64 lowercase letters, digits, and underscores.

Save an agentCopy Anchor Link

func (a *Agent) Save(ctx context.Context, opts SaveOptions) (*SavedAgent, error)

Saves the configuration and returns a *SavedAgent. opts is an agentkit.SaveOptions with Name and AgentID. Without AgentID, it creates a new agent. Names aren't unique, so saving twice creates two agents. To update a saved agent, prefer savedAgent.Update().

Start a session without savingCopy Anchor Link

func (a *Agent) CreateSession(opts CreateSessionOptions) *AgentSession

Creates a session from the builder without saving it. The SDK starts an ephemeral session on the Platform when the configuration has a secret reference or a variable, or when you set a Platform session option such as MaxDuration, Values, Labels, or DataPolicy. Otherwise, it uses the Voice Agent API. For the options, see Session options.

How the builder maps to the PlatformCopy Anchor Link

• Credentials: A model without an API key uses managed mode. A model with an API key uses BYOK. A saved agent must use an agentkit.SecretRef() as the key. An ephemeral session also accepts a key value.
• Instructions and messages: The LLM's system messages become the agent's instructions. Its other messages become messages. GreetingMessage and GreetingConfigs become the agent's greeting.
• Pipeline: Only cascaded ASR, LLM, and TTS pipelines are supported. An MLLM configuration can't be saved or used in a Platform session.
• Unsupported fields: Builder settings without a Platform equivalent, such as SAL, advanced features, labels, RTC settings, and pipeline IDs, make Save() return an error that wraps agentkit.ErrUnsupportedField and lists them.
• Generated types: Interruption, turn detection, and filler word settings use generated types from the root package. Where agentkit has a shorter alias, such as agentkit.FillerWordsContent or agentkit.InterruptionModeKeywords, use it.

Secret referencesCopy Anchor Link

func SecretRef(set, key string) string

Returns the reference $secrets.<set>.<key> for a key in a secret set. It validates both names locally, makes no request, and panics on an invalid name. Each name contains 1 to 64 letters, digits, and underscores.

SavedAgentCopy Anchor Link

A handle to an agent saved on the Platform.

A handle is a snapshot. If another process changes the agent, load it again with agentkit.GetSavedAgent().

Session optionsCopy Anchor Link

savedAgent.CreateSession() and agent.CreateSession() take an agentkit.CreateSessionOptions. The following fields apply to Platform sessions:

AgentSessionCopy Anchor Link

A session handle. On the Platform, the following methods are available:

Say(), Interrupt(), and the history and turns methods return agentkit.ErrUnsupportedSessionOperation on Platform sessions.

To read or stop a session by ID without a handle, use client.V3.Sessions.Get(ctx, id) and client.V3.Sessions.Stop(ctx, id).

Low-level APICopy Anchor Link

client.V3 has one client for each part of the Platform REST API. Every method takes ctx first and returns (*v3.Response[T], error). A v3.Response has Body (the parsed response), Header, ETag, RequestID, and StatusCode.

Pass "" for an optional string argument, such as an ifMatch or an idempotency key, to leave it out.

current, err := client.V3.Agents.Get(ctx, agentID)
if err != nil {
	log.Fatal(err)
}
etag := current.ETag

AgentsCopy Anchor Link

SessionsCopy Anchor Link

SecretsCopy Anchor Link

Secrets.Create and Numbers.Create take an idempotency-key argument for compatibility. Pass "". A non-empty key returns an error.

Phone numbersCopy Anchor Link

CampaignsCopy Anchor Link

PaginationCopy Anchor Link

Each List method returns one page. The page body has Data.Count, Data.List, HasMore, and NextCursor. To read every page, pass NextCursor as Cursor until HasMore is false:

cursor := ""
for {
	page, err := client.V3.Agents.List(ctx, v3.ListOptions{Limit: 100, Cursor: cursor})
	if err != nil {
		log.Fatal(err)
	}
	for _, item := range page.Body.Data.List {
		fmt.Println(item.AgentID, item.AgentName)
	}
	if !page.Body.HasMore || page.Body.NextCursor == nil || *page.Body.NextCursor == "" {
		break
	}
	cursor = *page.Body.NextCursor
}

v3.SessionListOptions adds Channel, Status, StartedAfter, and StartedBefore. Without Status, Sessions.List returns running sessions. To list others, pass a comma-separated list, for example "STOPPED,FAILED".

Conditional writes and retriesCopy Anchor Link

Updates to agents, numbers, and campaigns, and deletes and replacements of secret sets, require the resource's current ETag in ifMatch. Get it from Response.ETag. If the resource changed since you read it, the method returns a *v3.PreconditionFailedError. Call its Latest(ctx) method to reload the resource and its new ETag. It doesn't retry the write.

The SDK makes one attempt for every write. To retry a session start safely, pass the same idempotency key. Other operations don't support idempotency keys.

ErrorsCopy Anchor Link