Python SDK

The agora-agents Python 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 with_llm(), are shared with the Voice Agent API. For those, see the Python SDK reference for Voice Agents.

InstallCopy Anchor Link

Platform support is in the SDK preview, version 3.0.0a3. You need Python 3.8 or later. Install the SDK in your project's virtual environment, and specify the version, because the default agora-agents release doesn't support the Platform API:

pip install agora-agents==3.0.0a3

The package imports as agora_agent. Import the classes you use, for example:

from agora_agent import Agent, Agora, Area, SavedAgent, secret_ref

AgoraCopy 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

  import os
  from agora_agent import Agora, Area
  
  client = Agora(
      area=Area.US,
      app_id=os.environ["AGORA_APP_ID"],
      app_certificate=os.environ["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

  import os
  from agora_agent import Agora, Area
  
  client = Agora(
      area=Area.US,
      app_id=os.environ["AGORA_APP_ID"],
      customer_id=os.environ["AGORA_CUSTOMER_ID"],
      customer_secret=os.environ["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.

For asyncio applications, use AsyncAgora. It takes the same parameters, and its methods are awaitable.

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().

from agora_agent import Agent, DeepgramSTT, OpenAI, OpenAITTS

agent = (
    Agent(client=client)
    .with_stt(DeepgramSTT(model="nova-3", language="en-US"))
    .with_llm(OpenAI(model="gpt-4.1-mini"))
    .with_tts(OpenAITTS(model="tts-1", voice="alloy"))
    .with_variable("customer_name", type="str", required=True)
)

saved_agent = agent.save(name="Support agent")

VariablesCopy Anchor Link

with_variable(name, definition=None, **fields) -> Agent

Declares a variable and returns a new Agent. Pass the fields as keyword arguments, or as a dictionary in definition. 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(*, name=None, agent_id=None) -> SavedAgent

Saves the configuration and returns a SavedAgent. Without agent_id, it creates a new agent. Names aren't unique, so saving twice creates two agents. To update a saved agent, prefer saved_agent.update(). With AsyncAgora, use await agent.save_async(...).

Start a session without savingCopy Anchor Link

create_session(*, channel, agent_uid=None, remote_uids=None, ...) -> 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 max_duration, values, labels, or data_policy. Otherwise, it uses the Voice Agent API. For the parameters, see Session parameters.

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 secret_ref() 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. greeting_message and greeting_configs 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() raise an UnsupportedFieldError that lists them.

Secret referencesCopy Anchor Link

secret_ref(secret_set: str, key: str) -> 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. With AsyncAgora, the handle is AsyncSavedAgent, and its methods are awaitable.

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

Session parametersCopy Anchor Link

saved_agent.create_session() and agent.create_session() take keyword arguments. The following apply to 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 raise on Platform sessions.

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

Low-level APICopy Anchor Link

client.v3 has one resource for each part of the Platform REST API. All arguments are keyword-only, and body fields use the REST API names, such as agent_name. Each method returns the parsed response as a dictionary.

To read response headers, such as ETag, call the method through with_raw_response. The result has .data, .headers, .etag, and .status_code.

raw = client.v3.agents.with_raw_response.get(agent_id=agent_id)
etag = raw.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 iter_pages(...) and iter_all(...), which follow the cursors for you.

for session in client.v3.sessions.iter_all(status="STOPPED", limit=100):
    print(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 if_match. Get it from a raw response. If the resource changed since you read it, the request raises a PreconditionFailedError. Call error.latest() to reload the resource. It doesn't retry the write.

The SDK can retry GET requests. It never retries writes. To retry a session start safely, pass the same idempotency_key. Other operations don't support idempotency keys.

ErrorsCopy Anchor Link

Import the following errors from agora_agent, except ApiError.