Skip to content

quick-start.md

Latest commit

 

History

History
92 lines (68 loc) · 3.18 KB

quick-start.md

File metadata and controls

92 lines (68 loc) · 3.18 KB
sidebar_position 3
title Quick Start
description Build and run your first Agora Conversational AI agent in Python with app credentials and the builder API.

Quick Start

This guide starts with the standard AgentKit path:

  • app_id, app_certificate, and area on Agora or AsyncAgora
  • Agent(client=client, ...) — client is required on every agent builder
  • the Agent builder with .with_stt(), .with_llm(), and .with_tts()
  • automatic ConvoAI REST auth and RTC join token generation
  • no vendor API keys when using supported Agora-managed global models

Sync example

from agora_agent import Agent, Agora, Area, DeepgramSTT, MiniMaxTTS, OpenAI
import time


def main() -> None:
    client = Agora(
        area=Area.US,
        app_id="your-app-id",
        app_certificate="your-app-certificate",
    )

    agent = (
        Agent(client=client)
        .with_stt(DeepgramSTT(model="nova-3", language="en"))
        .with_llm(OpenAI(
            model="gpt-4o-mini",
            system_messages=[{"role": "system", "content": "You are a concise support voice assistant."}],
            greeting_message="Hello! How can I help you today?",
            max_history=10,
        ))
        .with_tts(MiniMaxTTS(model="speech_2_6_turbo", voice_id="English_captivating_female1"))
    )

    session = agent.create_session(
        channel=f"demo-channel-{int(time.time())}",
        agent_uid="1",
        remote_uids=["100"],
        name=f"conversation-{int(time.time())}",
        idle_timeout=120,
    )

    agent_session_id = session.start()
    print(f"Agent started: {agent_session_id}")

    session.say("Thanks for calling Agora support.")
    session.stop()


if __name__ == "__main__":
    main()

What this does

  1. Agora runs in app-credentials mode when you pass app_id and app_certificate only.
  2. Agent(client=client, ...) requires a bound client. create_session() raises ValueError without it.
  3. Agent(client=client, ...) binds the area-aware client once. Pass vendor classes such as DeepgramSTT(...), OpenAI(...), and MiniMaxTTS(...) directly; the SDK does not enforce area and vendor matching. Leave vendor credentials unset for supported Agora-managed global models, or provide keys when you want BYOK. CN MiniMax TTS typically includes key.
  4. create_session(name=...) sets the agent instance name for the Start Agent API. If omitted, the SDK generates agent-{timestamp}.
  5. session.start() generates the required auth tokens and returns the unique agent session ID.

Async applications

For asyncio services, switch to AsyncAgora and await the session methods. The builder and app-credentials flow stay the same.

When to use BYOK instead

Use the builder without vendor API keys when you are using supported Agora-managed global models.

Use BYOK when you need to:

  • supply your own vendor API keys
  • use models outside the Agora-managed catalog
  • point at custom vendor endpoints
  • manage vendor-specific parameters directly

See BYOK Guide.

Next steps