Skip to content

Commit e6618b3

Browse files
digitallysavvydigitallysavvy
committed
udpated example snippets
1 parent 434c4b1 commit e6618b3

1 file changed

Lines changed: 98 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 98 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,11 @@ pip install agora-agent-sdk
1313

1414
## Quick Start
1515

16-
Use the **builder pattern** with `Agent` and `AgentSession`:
16+
Use the **builder pattern** with `Agent` and `AgentSession`. The SDK auto-generates all required tokens:
1717

1818
```python
1919
from agora_agent import Agora, Area
20-
from agora_agent.agentkit import Agent
20+
from agora_agent.agentkit import Agent, expires_in_hours
2121
from agora_agent.agentkit.vendors import OpenAI, ElevenLabsTTS, DeepgramSTT
2222

2323
client = Agora(
@@ -28,34 +28,113 @@ client = Agora(
2828

2929
agent = (
3030
Agent(name="support-assistant", instructions="You are a helpful voice assistant.")
31+
# Create Agent: STT → LLM → TTS → (optional) Avatar
32+
.with_stt(DeepgramSTT(api_key="your-deepgram-key", language="en-US"))
3133
.with_llm(OpenAI(api_key="your-openai-key", model="gpt-4o-mini"))
3234
.with_tts(ElevenLabsTTS(key="your-elevenlabs-key", model_id="eleven_flash_v2_5", voice_id="your-voice-id", sample_rate=24000))
33-
.with_stt(DeepgramSTT(api_key="your-deepgram-key", language="en-US"))
35+
# .with_avatar(HeyGenAvatar(...)) # optional
3436
)
3537

36-
session = agent.create_session(client, channel="support-room-123", agent_uid="1", remote_uids=["100"])
37-
agent_id = session.start()
38-
session.say("Hello! How can I help you today?")
38+
session = agent.create_session(
39+
client,
40+
channel="support-room-123",
41+
agent_uid="1",
42+
remote_uids=["100"],
43+
expires_in=expires_in_hours(12), # optional — default is 24 h (Agora max)
44+
)
45+
46+
# start() returns a session ID unique to this agent session
47+
agent_session_id = session.start()
48+
49+
# In production, stop is typically called when your client signals the session has ended.
50+
# Your server receives that request and calls session.stop().
51+
session.stop()
52+
```
53+
54+
For async usage, use `AsyncAgora` and `await session.start()`, etc. See [Quick Start](docs/getting-started/quick-start.md).
55+
56+
### Session lifecycle
57+
58+
`start()` joins the agent to the channel and returns a **session ID** — a unique identifier for this agent session. The session stays active until `stop()` is called.
59+
60+
There are two ways to stop a session depending on how your server is structured:
61+
62+
**Option 1 — Hold the session in memory:**
63+
64+
```python
65+
# start-session handler
66+
agent_session_id = session.start() # unique ID for this session
67+
# stop-session handler (same process, session still in scope)
3968
session.stop()
4069
```
4170

42-
For async usage, use `AsyncAgora` and `await session.start()`, `await session.say()`, etc. See [Quick Start](docs/getting-started/quick-start.md).
71+
**Option 2 — Store the session ID and stop by ID (stateless servers):**
72+
73+
```python
74+
# start-session handler: return session ID to your client app
75+
agent_session_id = session.start()
76+
# ... return agent_session_id to client ...
77+
78+
# stop-session handler: client sends back agent_session_id
79+
client = Agora(area=Area.US, app_id="...", app_certificate="...")
80+
client.stop_agent(agent_session_id)
81+
```
82+
83+
### Manual tokens (for debugging)
84+
85+
Generate tokens yourself and pass them in — useful when inspecting or reusing tokens:
86+
87+
```python
88+
from agora_agent import Agora, Area
89+
from agora_agent.agentkit.token import generate_convo_ai_token, expires_in_hours
90+
91+
APP_ID = "your-app-id"
92+
APP_CERT = "your-app-certificate"
93+
CHANNEL = "support-room-123"
94+
AGENT_UID = "1"
95+
96+
# Auth header token — used by the SDK to authenticate REST API calls
97+
auth_token = generate_convo_ai_token(
98+
app_id=APP_ID, app_certificate=APP_CERT,
99+
channel_name=CHANNEL, account=AGENT_UID,
100+
token_expire=expires_in_hours(12),
101+
)
102+
103+
# Channel join token — embedded in the start request so the agent can join the channel
104+
join_token = generate_convo_ai_token(
105+
app_id=APP_ID, app_certificate=APP_CERT,
106+
channel_name=CHANNEL, account=AGENT_UID,
107+
token_expire=expires_in_hours(12),
108+
)
109+
110+
client = Agora(
111+
area=Area.US,
112+
app_id=APP_ID,
113+
app_certificate=APP_CERT,
114+
auth_token=auth_token, # SDK sets Authorization: agora token=<auth_token>
115+
)
116+
117+
session = agent.create_session(
118+
client, channel=CHANNEL, agent_uid=AGENT_UID, remote_uids=["100"],
119+
token=join_token, # channel join token
120+
)
121+
```
43122

44123
## Documentation
45124

46-
| Topic | Link |
47-
|-------|------|
48-
| **API docs** | [docs.agora.io](https://docs.agora.io/en/conversational-ai/overview) |
49-
| **Installation** | [docs/getting-started/installation.md](docs/getting-started/installation.md) |
125+
| Topic | Link |
126+
| ------------------ | -------------------------------------------------------------------------------- |
127+
| **API docs** | [docs.agora.io](https://docs.agora.io/en/conversational-ai/overview) |
128+
| **Installation** | [docs/getting-started/installation.md](docs/getting-started/installation.md) |
50129
| **Authentication** | [docs/getting-started/authentication.md](docs/getting-started/authentication.md) |
51-
| **Quick Start** | [docs/getting-started/quick-start.md](docs/getting-started/quick-start.md) |
52-
| **Cascading flow** | [docs/guides/cascading-flow.md](docs/guides/cascading-flow.md) |
53-
| **MLLM flow** | [docs/guides/mllm-flow.md](docs/guides/mllm-flow.md) |
54-
| **Low-level API** | [docs/guides/low-level-api.md](docs/guides/low-level-api.md) |
55-
| **Error handling** | [docs/guides/error-handling.md](docs/guides/error-handling.md) |
56-
| **Pagination** | [docs/guides/pagination.md](docs/guides/pagination.md) |
57-
| **Advanced** | [docs/guides/advanced.md](docs/guides/advanced.md) |
58-
| **API reference** | [reference.md](reference.md) |
130+
| **Quick Start** | [docs/getting-started/quick-start.md](docs/getting-started/quick-start.md) |
131+
| **Cascading flow** | [docs/guides/cascading-flow.md](docs/guides/cascading-flow.md) |
132+
| **MLLM flow** | [docs/guides/mllm-flow.md](docs/guides/mllm-flow.md) |
133+
| **Low-level API** | [docs/guides/low-level-api.md](docs/guides/low-level-api.md) |
134+
| **Error handling** | [docs/guides/error-handling.md](docs/guides/error-handling.md) |
135+
| **Pagination** | [docs/guides/pagination.md](docs/guides/pagination.md) |
136+
| **Advanced** | [docs/guides/advanced.md](docs/guides/advanced.md) |
137+
| **API reference** | [reference.md](reference.md) |
59138

60139
## Contributing
61140

0 commit comments

Comments
 (0)