Skip to content

Commit c935557

Browse files
digitallysavvydigitallysavvy
committed
Streamline Python docs and README for app-credentials-first onboarding.
Remove duplicated low-level client examples from the README, de-emphasize legacy auth modes, refocus the low-level API guide on AgentKit with telephony escape hatches, and update Agora-managed model terminology.
1 parent d475306 commit c935557

3 files changed

Lines changed: 34 additions & 384 deletions

File tree

‎README.md‎

Lines changed: 7 additions & 190 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,6 @@ and multimodal flows (MLLM) for real-time audio processing.
1717
- [MLLM (Realtime / Multimodal)](#mllm-realtime--multimodal)
1818
- [Documentation](#documentation)
1919
- [Reference](#reference)
20-
- [Usage](#usage)
21-
- [Async Client](#async-client)
2220
- [Exception Handling](#exception-handling)
2321
- [Pagination](#pagination)
2422
- [Advanced](#advanced)
@@ -148,7 +146,7 @@ def start_conversation() -> str:
148146

149147
### Why no token or vendor key in the example?
150148

151-
`Agora` generates the required ConvoAI REST auth and RTC join tokens automatically when you provide `app_id` and `app_certificate`. AgentKit then inspects the builder-provided vendor configs and infers the matching supported `preset` values for reseller-backed models, so you do not pass vendor API keys in this flow.
149+
`Agora` generates the required ConvoAI REST auth and RTC join tokens automatically when you provide `app_id` and `app_certificate`. AgentKit inspects the builder-provided vendor configs and infers Agora-managed configuration for supported models, so you do not pass vendor API keys in this flow.
152150

153151
### BYOK version of the same builder flow
154152

@@ -187,7 +185,7 @@ Migrating from `agora-agent-server-sdk` on PyPI? Use `pip install agora-agents`;
187185

188186
## BYOK
189187

190-
If you want to bring your own vendor credentials instead of using Agora-managed presets, use the BYOK guide:
188+
If you want to bring your own vendor credentials instead of using Agora-managed models, use the BYOK guide:
191189

192190
- [BYOK Guide](./docs/guides/byok.md)
193191

@@ -217,187 +215,6 @@ API reference documentation is available [here](https://docs.agora.io/en/convers
217215

218216
A full reference for this library is available [here](https://github.com/AgoraIO-Conversational-AI/agent-server-sdk-python/blob/HEAD/./reference.md).
219217

220-
## MLLM Flow (Multimodal)
221-
222-
For real-time audio processing using OpenAI Realtime, Gemini Live, Vertex AI, or xAI Grok, use the MLLM (Multimodal Large Language Model) flow instead of the cascading ASR -> LLM -> TTS flow. MLLM mode does not require separate TTS, STT, or LLM vendors. See the [MLLM Overview](https://docs.agora.io/en/conversational-ai/models/mllm/overview) for more details.
223-
224-
```python
225-
from agora_agent import Agora
226-
from agora_agent.agents import (
227-
StartAgentsRequestProperties,
228-
StartAgentsRequestPropertiesMllm,
229-
StartAgentsRequestPropertiesMllmVendor,
230-
StartAgentsRequestPropertiesTurnDetection,
231-
StartAgentsRequestPropertiesTurnDetectionType,
232-
)
233-
234-
client = Agora(
235-
customer_id="YOUR_CUSTOMER_ID",
236-
customer_secret="YOUR_CUSTOMER_SECRET",
237-
)
238-
239-
client.agents.start(
240-
appid="your_app_id",
241-
name="mllm_agent",
242-
properties=StartAgentsRequestProperties(
243-
channel="channel_name",
244-
token="your_token",
245-
agent_rtc_uid="1001",
246-
remote_rtc_uids=["1002"],
247-
idle_timeout=120,
248-
mllm=StartAgentsRequestPropertiesMllm(
249-
enable=True,
250-
url="wss://api.openai.com/v1/realtime",
251-
api_key="<your_openai_api_key>",
252-
vendor=StartAgentsRequestPropertiesMllmVendor.OPENAI,
253-
params={
254-
"model": "gpt-4o-realtime-preview",
255-
"voice": "alloy",
256-
},
257-
input_modalities=["audio"],
258-
output_modalities=["text", "audio"],
259-
greeting_message="Hello! I'm ready to chat in real-time.",
260-
),
261-
turn_detection=StartAgentsRequestPropertiesTurnDetection(
262-
type=StartAgentsRequestPropertiesTurnDetectionType.SERVER_VAD,
263-
threshold=0.5,
264-
silence_duration_ms=500,
265-
),
266-
),
267-
)
268-
```
269-
270-
271-
## Usage
272-
273-
Instantiate and use the client with the following:
274-
275-
```python
276-
from agora_agent import Agora, MicrosoftTtsParams, Tts_Microsoft
277-
from agora_agent.agents import (
278-
StartAgentsRequestProperties,
279-
StartAgentsRequestPropertiesAsr,
280-
StartAgentsRequestPropertiesLlm,
281-
StartAgentsRequestPropertiesTurnDetection,
282-
StartAgentsRequestPropertiesTurnDetectionConfig,
283-
StartAgentsRequestPropertiesTurnDetectionConfigEndOfSpeech,
284-
)
285-
286-
client = Agora(
287-
authorization="YOUR_AUTHORIZATION",
288-
username="YOUR_USERNAME",
289-
password="YOUR_PASSWORD",
290-
)
291-
client.agents.start(
292-
appid="appid",
293-
name="unique_name",
294-
properties=StartAgentsRequestProperties(
295-
channel="channel_name",
296-
token="token",
297-
agent_rtc_uid="1001",
298-
remote_rtc_uids=["1002"],
299-
idle_timeout=120,
300-
asr=StartAgentsRequestPropertiesAsr(
301-
language="en-US",
302-
),
303-
tts=Tts_Microsoft(
304-
params=MicrosoftTtsParams(
305-
key="key",
306-
region="region",
307-
voice_name="voice_name",
308-
),
309-
),
310-
llm=StartAgentsRequestPropertiesLlm(
311-
url="https://api.openai.com/v1/chat/completions",
312-
api_key="<your_llm_key>",
313-
system_messages=[
314-
{"role": "system", "content": "You are a helpful chatbot."}
315-
],
316-
params={"model": "gpt-4o-mini"},
317-
max_history=32,
318-
greeting_message="Hello, how can I assist you today?",
319-
failure_message="Please hold on a second.",
320-
),
321-
turn_detection=StartAgentsRequestPropertiesTurnDetection(
322-
config=StartAgentsRequestPropertiesTurnDetectionConfig(
323-
end_of_speech=StartAgentsRequestPropertiesTurnDetectionConfigEndOfSpeech(
324-
mode="semantic",
325-
),
326-
),
327-
),
328-
),
329-
)
330-
```
331-
332-
## Async Client
333-
334-
The SDK also exports an `async` client so that you can make non-blocking calls to our API. Note that if you are constructing an Async httpx client class to pass into this client, use `httpx.AsyncClient()` instead of `httpx.Client()` (e.g. for the `httpx_client` parameter of this client).
335-
336-
```python
337-
import asyncio
338-
339-
from agora_agent import AsyncAgora, MicrosoftTtsParams, Tts_Microsoft
340-
from agora_agent.agents import (
341-
StartAgentsRequestProperties,
342-
StartAgentsRequestPropertiesAsr,
343-
StartAgentsRequestPropertiesLlm,
344-
StartAgentsRequestPropertiesTurnDetection,
345-
StartAgentsRequestPropertiesTurnDetectionConfig,
346-
StartAgentsRequestPropertiesTurnDetectionConfigEndOfSpeech,
347-
)
348-
349-
client = AsyncAgora(
350-
authorization="YOUR_AUTHORIZATION",
351-
username="YOUR_USERNAME",
352-
password="YOUR_PASSWORD",
353-
)
354-
355-
356-
async def main() -> None:
357-
await client.agents.start(
358-
appid="appid",
359-
name="unique_name",
360-
properties=StartAgentsRequestProperties(
361-
channel="channel_name",
362-
token="token",
363-
agent_rtc_uid="1001",
364-
remote_rtc_uids=["1002"],
365-
idle_timeout=120,
366-
asr=StartAgentsRequestPropertiesAsr(
367-
language="en-US",
368-
),
369-
tts=Tts_Microsoft(
370-
params=MicrosoftTtsParams(
371-
key="key",
372-
region="region",
373-
voice_name="voice_name",
374-
),
375-
),
376-
llm=StartAgentsRequestPropertiesLlm(
377-
url="https://api.openai.com/v1/chat/completions",
378-
api_key="<your_llm_key>",
379-
system_messages=[
380-
{"role": "system", "content": "You are a helpful chatbot."}
381-
],
382-
params={"model": "gpt-4o-mini"},
383-
max_history=32,
384-
greeting_message="Hello, how can I assist you today?",
385-
failure_message="Please hold on a second.",
386-
),
387-
turn_detection=StartAgentsRequestPropertiesTurnDetection(
388-
config=StartAgentsRequestPropertiesTurnDetectionConfig(
389-
end_of_speech=StartAgentsRequestPropertiesTurnDetectionConfigEndOfSpeech(
390-
mode="semantic",
391-
),
392-
),
393-
),
394-
),
395-
)
396-
397-
398-
asyncio.run(main())
399-
```
400-
401218
## Exception Handling
402219

403220
When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
@@ -418,15 +235,15 @@ except ApiError as e:
418235
Paginated requests will return a `SyncPager` or `AsyncPager`, which can be used as generators for the underlying object.
419236

420237
```python
421-
from agora_agent import Agora
238+
from agora_agent import Agora, Area
422239

423240
client = Agora(
424-
authorization="YOUR_AUTHORIZATION",
425-
username="YOUR_USERNAME",
426-
password="YOUR_PASSWORD",
241+
area=Area.US,
242+
app_id="your-app-id",
243+
app_certificate="your-app-certificate",
427244
)
428245
response = client.agents.list(
429-
appid="appid",
246+
appid=client.app_id,
430247
)
431248
for item in response:
432249
yield item

‎docs/getting-started/authentication.md‎

Lines changed: 2 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -46,41 +46,6 @@ session = agent.create_session(
4646
print(client.auth_mode) # "app-credentials"
4747
```
4848

49-
## Other auth modes
49+
## Legacy auth modes
5050

51-
The SDK also supports pre-minted REST tokens and HTTP Basic Auth for legacy integrations. These are not recommended for new applications.
52-
53-
### Token auth (`auth_token`)
54-
55-
Pass a pre-minted Agora REST token on the client. You must also supply the RTC join token on `create_session(..., token=...)`.
56-
57-
```python
58-
client = Agora(
59-
area=Area.US,
60-
app_id="your-app-id",
61-
app_certificate="your-app-certificate",
62-
auth_token="your-rest-auth-token",
63-
)
64-
65-
session = agent.create_session(
66-
client,
67-
channel="room-123",
68-
agent_uid="1",
69-
remote_uids=["100"],
70-
token="your-rtc-join-token",
71-
)
72-
```
73-
74-
### Basic Auth (`customer_id` + `customer_secret`)
75-
76-
Uses HTTP Basic Auth with Customer ID and Secret from Agora Console. Avoid for new integrations — the same credentials are sent on every request instead of minting fresh tokens.
77-
78-
```python
79-
client = Agora(
80-
area=Area.US,
81-
app_id="your-app-id",
82-
app_certificate="your-app-certificate",
83-
customer_id="your-customer-id",
84-
customer_secret="your-customer-secret",
85-
)
86-
```
51+
The generated client still supports pre-minted REST tokens and HTTP Basic Auth for legacy integrations. Do not use those modes for new session integrations. Use app credentials so AgentKit can mint short-lived ConvoAI REST auth and RTC join tokens for each session.

0 commit comments

Comments
 (0)