TypeScript SDK

The agora-agents TypeScript 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 namespace.

The vendor classes, such as OpenAI and DeepgramSTT, and the builder methods, such as withLlm(), are shared with the Voice Agent API. For those, see the TypeScript SDK reference for Voice Agents.

InstallCopy Anchor Link

Platform support is in the SDK preview, version 3.0.0-alpha.3. You need Node.js 18 or later. Install the SDK in your project, and specify the version, because the default agora-agents release doesn't support the Platform API:

npm install agora-agents@3.0.0-alpha.3

Import the classes you use, for example:

import { Agent, AgoraClient, Area, SavedAgent, secretRef } from 'agora-agents';

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

  const client = new AgoraClient({
    area: Area.US,
    appId: process.env.AGORA_APP_ID!,
    appCertificate: process.env.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

  const client = new AgoraClient({
    area: Area.US,
    appId: process.env.AGORA_APP_ID!,
    customerId: process.env.AGORA_CUSTOMER_ID!,
    customerSecret: process.env.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

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

const agent = new Agent({ client })
  .withStt(new DeepgramSTT({ model: 'nova-3', language: 'en-US' }))
  .withLlm(new OpenAI({ model: 'gpt-4.1-mini' }))
  .withTts(new OpenAITTS({ model: 'tts-1', voice: 'alloy' }))
  .withVariable('customer_name', { type: 'str', required: true });

const savedAgent = await agent.save({ name: 'Support agent' });

VariablesCopy Anchor Link

withVariable(name: string, definition: VariableDefinition): Agent

Declares a variable and returns a new Agent. The definition is validated locally.

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

Save an agentCopy Anchor Link

save(options?: SaveOptions): Promise<SavedAgent>

Saves the configuration and returns a SavedAgent. Without agentId, it creates a new agent. Names aren't unique, so saving twice creates two agents.

Start a session without savingCopy Anchor Link

createSession(options: SessionOptions): 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 a 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() throw an UnsupportedFieldError that lists them.

Secret referencesCopy Anchor Link

secretRef(set: string, key: string): SecretRef

Returns the reference $secrets.<set>.<key> for a key in a secret set. It validates both names locally and makes no request. 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 SavedAgent.get().

Session optionsCopy Anchor Link

savedAgent.createSession() and agent.createSession() accept the following options for Platform sessions:

AgentSessionCopy Anchor Link

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

say(), interrupt(), think(), and the history and turns methods throw on Platform sessions.

To read or stop a session by ID without a handle, use client.v3.sessions.get({ agentSessionId }) and client.v3.sessions.stop({ agentSessionId }).

Low-level APICopy Anchor Link

client.v3 has one resource for each part of the Platform REST API. Each method takes a request object and returns a promise of the parsed response. Request body fields use the REST API names, such as agent_name. Path and header fields use camelCase, such as agentSessionId and ifMatch.

To read response headers, such as ETag, call .withRawResponse() on the returned promise. It resolves to { data, rawResponse }.

const { data, rawResponse } = await client.v3.agents.get({ id: agentId }).withRawResponse();
const etag = rawResponse.headers.get('etag');

AgentsCopy Anchor Link

SessionsCopy Anchor Link

SecretsCopy Anchor Link

Phone numbersCopy Anchor Link

CampaignsCopy Anchor Link

PaginationCopy Anchor Link

Each list() method returns one page: { data: { count, list }, has_more, next_cursor }. To continue, pass next_cursor as cursor. Each resource also has listAll(request?), an async generator that follows the cursors for you.

for await (const session of client.v3.sessions.listAll({ status: 'STOPPED', limit: 100 })) {
  console.log(session.agent_session_id);
}

sessions.list() returns running sessions by default. To list others, pass status, 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 a raw response. If the resource changed since you read it, the request throws a PreconditionFailedError. Call await error.latest() to reload the resource. It doesn't retry the write.

The SDK retries GET requests up to maxRetries times. It never retries writes. To retry a session start safely, pass the same idempotencyKey. Other operations don't support idempotency keys.

ErrorsCopy Anchor Link