Skip to content

Commit 8fc16f2

Browse files
fern-api[bot]fern-api[bot]
authored
SDK regeneration
Unable to analyze changes with AI, incrementing PATCH version.
1 parent 6544a3a commit 8fc16f2

5 files changed

Lines changed: 372 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 360 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,360 @@
1+
# Agoraio Python Library
2+
3+
[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Ffern-demo%2Fagoraio-python-sdk)
4+
[![pypi](https://img.shields.io/pypi/v/agoraio-sdk)](https://pypi.python.org/pypi/agoraio-sdk)
5+
6+
The Agora Conversational AI SDK provides convenient access to the Agora Conversational AI APIs,
7+
enabling you to build voice-powered AI agents with support for both cascading flows (ASR -> LLM -> TTS)
8+
and multimodal flows (MLLM) for real-time audio processing.
9+
10+
11+
## Table of Contents
12+
13+
- [Documentation](#documentation)
14+
- [Installation](#installation)
15+
- [Reference](#reference)
16+
- [Mllm Flow Multimodal](#mllm-flow-multimodal)
17+
- [Usage](#usage)
18+
- [Async Client](#async-client)
19+
- [Exception Handling](#exception-handling)
20+
- [Pagination](#pagination)
21+
- [Advanced](#advanced)
22+
- [Access Raw Response Data](#access-raw-response-data)
23+
- [Retries](#retries)
24+
- [Timeouts](#timeouts)
25+
- [Custom Client](#custom-client)
26+
- [Contributing](#contributing)
27+
28+
## Documentation
29+
30+
API reference documentation is available [here](https://docs.agora.io/en/conversational-ai/overview).
31+
32+
## Installation
33+
34+
```sh
35+
pip install agoraio-sdk
36+
```
37+
38+
## Reference
39+
40+
A full reference for this library is available [here](https://github.com/fern-demo/agoraio-python-sdk/blob/HEAD/./reference.md).
41+
42+
## MLLM Flow (Multimodal)
43+
44+
For real-time audio processing using OpenAI's Realtime API or Google Gemini Live, use the MLLM (Multimodal Large Language Model) flow instead of the cascading ASR -> LLM -> TTS flow. See the [MLLM Overview](https://docs.agora.io/en/conversational-ai/models/mllm/overview) for more details.
45+
46+
```python
47+
from agoraio-sdk import Agora
48+
from agoraio-sdk.agents import (
49+
StartAgentsRequestProperties,
50+
StartAgentsRequestPropertiesAdvancedFeatures,
51+
StartAgentsRequestPropertiesMllm,
52+
StartAgentsRequestPropertiesMllmVendor,
53+
StartAgentsRequestPropertiesTts,
54+
StartAgentsRequestPropertiesTtsVendor,
55+
StartAgentsRequestPropertiesLlm,
56+
StartAgentsRequestPropertiesTurnDetection,
57+
StartAgentsRequestPropertiesTurnDetectionType,
58+
)
59+
60+
client = Agora(
61+
username="YOUR_APP_ID",
62+
password="YOUR_APP_CERTIFICATE",
63+
)
64+
65+
client.agents.start(
66+
appid="your_app_id",
67+
name="mllm_agent",
68+
properties=StartAgentsRequestProperties(
69+
channel="channel_name",
70+
token="your_token",
71+
agent_rtc_uid="1001",
72+
remote_rtc_uids=["1002"],
73+
idle_timeout=120,
74+
advanced_features=StartAgentsRequestPropertiesAdvancedFeatures(
75+
enable_mllm=True,
76+
),
77+
mllm=StartAgentsRequestPropertiesMllm(
78+
url="wss://api.openai.com/v1/realtime",
79+
api_key="<your_openai_api_key>",
80+
vendor=StartAgentsRequestPropertiesMllmVendor.OPENAI,
81+
params={
82+
"model": "gpt-4o-realtime-preview",
83+
"voice": "alloy",
84+
},
85+
input_modalities=["audio"],
86+
output_modalities=["text", "audio"],
87+
greeting_message="Hello! I'm ready to chat in real-time.",
88+
),
89+
turn_detection=StartAgentsRequestPropertiesTurnDetection(
90+
type=StartAgentsRequestPropertiesTurnDetectionType.SERVER_VAD,
91+
threshold=0.5,
92+
silence_duration_ms=500,
93+
),
94+
# TTS and LLM are still required but not used when MLLM is enabled
95+
tts=StartAgentsRequestPropertiesTts(
96+
vendor=StartAgentsRequestPropertiesTtsVendor.MICROSOFT,
97+
params={},
98+
),
99+
llm=StartAgentsRequestPropertiesLlm(
100+
url="https://api.openai.com/v1/chat/completions",
101+
),
102+
),
103+
)
104+
```
105+
106+
107+
## Usage
108+
109+
Instantiate and use the client with the following:
110+
111+
```python
112+
from agoraio import Agora, MicrosoftTtsParams, Tts_Microsoft
113+
from agoraio.agents import (
114+
StartAgentsRequestProperties,
115+
StartAgentsRequestPropertiesAdvancedFeatures,
116+
StartAgentsRequestPropertiesAsr,
117+
StartAgentsRequestPropertiesLlm,
118+
)
119+
120+
client = Agora(
121+
username="YOUR_USERNAME",
122+
password="YOUR_PASSWORD",
123+
)
124+
client.agents.start(
125+
appid="appid",
126+
name="unique_name",
127+
properties=StartAgentsRequestProperties(
128+
channel="channel_name",
129+
token="token",
130+
agent_rtc_uid="1001",
131+
remote_rtc_uids=["1002"],
132+
idle_timeout=120,
133+
advanced_features=StartAgentsRequestPropertiesAdvancedFeatures(
134+
enable_aivad=True,
135+
),
136+
asr=StartAgentsRequestPropertiesAsr(
137+
language="en-US",
138+
),
139+
tts=Tts_Microsoft(
140+
params=MicrosoftTtsParams(
141+
key="key",
142+
region="region",
143+
voice_name="voice_name",
144+
),
145+
),
146+
llm=StartAgentsRequestPropertiesLlm(
147+
url="https://api.openai.com/v1/chat/completions",
148+
api_key="<your_llm_key>",
149+
system_messages=[
150+
{"role": "system", "content": "You are a helpful chatbot."}
151+
],
152+
params={"model": "gpt-4o-mini"},
153+
max_history=32,
154+
greeting_message="Hello, how can I assist you today?",
155+
failure_message="Please hold on a second.",
156+
),
157+
),
158+
)
159+
```
160+
161+
## Async Client
162+
163+
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).
164+
165+
```python
166+
import asyncio
167+
168+
from agoraio import AsyncAgora, MicrosoftTtsParams, Tts_Microsoft
169+
from agoraio.agents import (
170+
StartAgentsRequestProperties,
171+
StartAgentsRequestPropertiesAdvancedFeatures,
172+
StartAgentsRequestPropertiesAsr,
173+
StartAgentsRequestPropertiesLlm,
174+
)
175+
176+
client = AsyncAgora(
177+
username="YOUR_USERNAME",
178+
password="YOUR_PASSWORD",
179+
)
180+
181+
182+
async def main() -> None:
183+
await client.agents.start(
184+
appid="appid",
185+
name="unique_name",
186+
properties=StartAgentsRequestProperties(
187+
channel="channel_name",
188+
token="token",
189+
agent_rtc_uid="1001",
190+
remote_rtc_uids=["1002"],
191+
idle_timeout=120,
192+
advanced_features=StartAgentsRequestPropertiesAdvancedFeatures(
193+
enable_aivad=True,
194+
),
195+
asr=StartAgentsRequestPropertiesAsr(
196+
language="en-US",
197+
),
198+
tts=Tts_Microsoft(
199+
params=MicrosoftTtsParams(
200+
key="key",
201+
region="region",
202+
voice_name="voice_name",
203+
),
204+
),
205+
llm=StartAgentsRequestPropertiesLlm(
206+
url="https://api.openai.com/v1/chat/completions",
207+
api_key="<your_llm_key>",
208+
system_messages=[
209+
{"role": "system", "content": "You are a helpful chatbot."}
210+
],
211+
params={"model": "gpt-4o-mini"},
212+
max_history=32,
213+
greeting_message="Hello, how can I assist you today?",
214+
failure_message="Please hold on a second.",
215+
),
216+
),
217+
)
218+
219+
220+
asyncio.run(main())
221+
```
222+
223+
## Exception Handling
224+
225+
When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
226+
will be thrown.
227+
228+
```python
229+
from agoraio.core.api_error import ApiError
230+
231+
try:
232+
client.agents.start(...)
233+
except ApiError as e:
234+
print(e.status_code)
235+
print(e.body)
236+
```
237+
238+
## Pagination
239+
240+
Paginated requests will return a `SyncPager` or `AsyncPager`, which can be used as generators for the underlying object.
241+
242+
```python
243+
from agoraio import Agora
244+
245+
client = Agora(
246+
username="YOUR_USERNAME",
247+
password="YOUR_PASSWORD",
248+
)
249+
response = client.agents.list(
250+
appid="appid",
251+
)
252+
for item in response:
253+
yield item
254+
# alternatively, you can paginate page-by-page
255+
for page in response.iter_pages():
256+
yield page
257+
```
258+
259+
```python
260+
# You can also iterate through pages and access the typed response per page
261+
pager = client.agents.list(...)
262+
for page in pager.iter_pages():
263+
print(page.response) # access the typed response for each page
264+
for item in page:
265+
print(item)
266+
```
267+
268+
## Advanced
269+
270+
### Access Raw Response Data
271+
272+
The SDK provides access to raw response data, including headers, through the `.with_raw_response` property.
273+
The `.with_raw_response` property returns a "raw" client that can be used to access the `.headers` and `.data` attributes.
274+
275+
```python
276+
from agoraio import Agora
277+
278+
client = Agora(
279+
...,
280+
)
281+
response = client.agents.with_raw_response.start(...)
282+
print(response.headers) # access the response headers
283+
print(response.data) # access the underlying object
284+
pager = client.agents.list(...)
285+
print(pager.response) # access the typed response for the first page
286+
for item in pager:
287+
print(item) # access the underlying object(s)
288+
for page in pager.iter_pages():
289+
print(page.response) # access the typed response for each page
290+
for item in page:
291+
print(item) # access the underlying object(s)
292+
```
293+
294+
### Retries
295+
296+
The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
297+
as the request is deemed retryable and the number of retry attempts has not grown larger than the configured
298+
retry limit (default: 2).
299+
300+
A request is deemed retryable when any of the following HTTP status codes is returned:
301+
302+
- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
303+
- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
304+
- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)
305+
306+
Use the `max_retries` request option to configure this behavior.
307+
308+
```python
309+
client.agents.start(..., request_options={
310+
"max_retries": 1
311+
})
312+
```
313+
314+
### Timeouts
315+
316+
The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level.
317+
318+
```python
319+
320+
from agoraio import Agora
321+
322+
client = Agora(
323+
...,
324+
timeout=20.0,
325+
)
326+
327+
328+
# Override timeout for a specific method
329+
client.agents.start(..., request_options={
330+
"timeout_in_seconds": 1
331+
})
332+
```
333+
334+
### Custom Client
335+
336+
You can override the `httpx` client to customize it for your use-case. Some common use-cases include support for proxies
337+
and transports.
338+
339+
```python
340+
import httpx
341+
from agoraio import Agora
342+
343+
client = Agora(
344+
...,
345+
httpx_client=httpx.Client(
346+
proxy="http://my.test.proxy.example.com",
347+
transport=httpx.HTTPTransport(local_address="0.0.0.0"),
348+
),
349+
)
350+
```
351+
352+
## Contributing
353+
354+
While we value open-source contributions to this SDK, this library is generated programmatically.
355+
Additions made directly to this library would have to be moved over to our generation code,
356+
otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
357+
a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
358+
an issue first to discuss with us!
359+
360+
On the other hand, contributions to the README are always very welcome!

‎changelog.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
## 0.1.1 - 2026-01-13
2+
* SDK regeneration
3+
* Unable to analyze changes with AI, incrementing PATCH version.
4+
15
## 0.0.10 - 2026-01-13
26
* SDK regeneration
37
* Unable to analyze changes with AI, incrementing PATCH version.

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name = "agoraio-sdk"
33

44
[tool.poetry]
55
name = "agoraio-sdk"
6-
version = "0.1.0"
6+
version = "0.1.1"
77
description = ""
88
readme = "README.md"
99
authors = []

‎src/agoraio/agents/types/start_agents_request_properties.py‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,11 @@ class StartAgentsRequestProperties(UncheckedBaseModel):
6363
Automatic Speech Recognition (ASR) configuration.
6464
"""
6565

66-
tts: Tts
66+
tts: Tts = pydantic.Field()
67+
"""
68+
Text-to-speech (TTS) module configuration.
69+
"""
70+
6771
llm: StartAgentsRequestPropertiesLlm = pydantic.Field()
6872
"""
6973
Large language model (LLM) configuration.

0 commit comments

Comments
 (0)