Skip to content

Commit 36fbb38

Browse files
fern-api[bot]fern-api[bot]
authored
SDK regeneration
1 parent 858a78e commit 36fbb38

61 files changed

Lines changed: 1493 additions & 99 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.fern/metadata.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"cliVersion": "3.76.0",
2+
"cliVersion": "4.4.4",
33
"generatorName": "fernapi/fern-python-sdk",
44
"generatorVersion": "4.37.0",
55
"generatorConfig": {

‎README.md‎

Lines changed: 355 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,355 @@
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%2FAgoraIO-Conversational-AI%2Fagora-agent-python-sdk)
4+
[![pypi](https://img.shields.io/pypi/v/agora-agent-sdk)](https://pypi.python.org/pypi/agora-agent-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 agora-agent-sdk
36+
```
37+
38+
## Reference
39+
40+
A full reference for this library is available [here](https://github.com/AgoraIO-Conversational-AI/agora-agent-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 agora-agent-sdk import Agora
48+
from agora-agent-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+
customer_id="YOUR_CUSTOMER_ID",
62+
customer_secret="YOUR_CUSTOMER_SECRET",
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+
StartAgentsRequestPropertiesAsr,
116+
StartAgentsRequestPropertiesLlm,
117+
)
118+
119+
client = Agora(
120+
authorization="YOUR_AUTHORIZATION",
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+
asr=StartAgentsRequestPropertiesAsr(
134+
language="en-US",
135+
),
136+
tts=Tts_Microsoft(
137+
params=MicrosoftTtsParams(
138+
key="key",
139+
region="region",
140+
voice_name="voice_name",
141+
),
142+
),
143+
llm=StartAgentsRequestPropertiesLlm(
144+
url="https://api.openai.com/v1/chat/completions",
145+
api_key="<your_llm_key>",
146+
system_messages=[
147+
{"role": "system", "content": "You are a helpful chatbot."}
148+
],
149+
params={"model": "gpt-4o-mini"},
150+
max_history=32,
151+
greeting_message="Hello, how can I assist you today?",
152+
failure_message="Please hold on a second.",
153+
),
154+
),
155+
)
156+
```
157+
158+
## Async Client
159+
160+
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).
161+
162+
```python
163+
import asyncio
164+
165+
from agoraio import AsyncAgora, MicrosoftTtsParams, Tts_Microsoft
166+
from agoraio.agents import (
167+
StartAgentsRequestProperties,
168+
StartAgentsRequestPropertiesAsr,
169+
StartAgentsRequestPropertiesLlm,
170+
)
171+
172+
client = AsyncAgora(
173+
authorization="YOUR_AUTHORIZATION",
174+
username="YOUR_USERNAME",
175+
password="YOUR_PASSWORD",
176+
)
177+
178+
179+
async def main() -> None:
180+
await client.agents.start(
181+
appid="appid",
182+
name="unique_name",
183+
properties=StartAgentsRequestProperties(
184+
channel="channel_name",
185+
token="token",
186+
agent_rtc_uid="1001",
187+
remote_rtc_uids=["1002"],
188+
idle_timeout=120,
189+
asr=StartAgentsRequestPropertiesAsr(
190+
language="en-US",
191+
),
192+
tts=Tts_Microsoft(
193+
params=MicrosoftTtsParams(
194+
key="key",
195+
region="region",
196+
voice_name="voice_name",
197+
),
198+
),
199+
llm=StartAgentsRequestPropertiesLlm(
200+
url="https://api.openai.com/v1/chat/completions",
201+
api_key="<your_llm_key>",
202+
system_messages=[
203+
{"role": "system", "content": "You are a helpful chatbot."}
204+
],
205+
params={"model": "gpt-4o-mini"},
206+
max_history=32,
207+
greeting_message="Hello, how can I assist you today?",
208+
failure_message="Please hold on a second.",
209+
),
210+
),
211+
)
212+
213+
214+
asyncio.run(main())
215+
```
216+
217+
## Exception Handling
218+
219+
When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
220+
will be thrown.
221+
222+
```python
223+
from agoraio.core.api_error import ApiError
224+
225+
try:
226+
client.agents.start(...)
227+
except ApiError as e:
228+
print(e.status_code)
229+
print(e.body)
230+
```
231+
232+
## Pagination
233+
234+
Paginated requests will return a `SyncPager` or `AsyncPager`, which can be used as generators for the underlying object.
235+
236+
```python
237+
from agoraio import Agora
238+
239+
client = Agora(
240+
authorization="YOUR_AUTHORIZATION",
241+
username="YOUR_USERNAME",
242+
password="YOUR_PASSWORD",
243+
)
244+
response = client.agents.list(
245+
appid="appid",
246+
)
247+
for item in response:
248+
yield item
249+
# alternatively, you can paginate page-by-page
250+
for page in response.iter_pages():
251+
yield page
252+
```
253+
254+
```python
255+
# You can also iterate through pages and access the typed response per page
256+
pager = client.agents.list(...)
257+
for page in pager.iter_pages():
258+
print(page.response) # access the typed response for each page
259+
for item in page:
260+
print(item)
261+
```
262+
263+
## Advanced
264+
265+
### Access Raw Response Data
266+
267+
The SDK provides access to raw response data, including headers, through the `.with_raw_response` property.
268+
The `.with_raw_response` property returns a "raw" client that can be used to access the `.headers` and `.data` attributes.
269+
270+
```python
271+
from agoraio import Agora
272+
273+
client = Agora(
274+
...,
275+
)
276+
response = client.agents.with_raw_response.start(...)
277+
print(response.headers) # access the response headers
278+
print(response.data) # access the underlying object
279+
pager = client.agents.list(...)
280+
print(pager.response) # access the typed response for the first page
281+
for item in pager:
282+
print(item) # access the underlying object(s)
283+
for page in pager.iter_pages():
284+
print(page.response) # access the typed response for each page
285+
for item in page:
286+
print(item) # access the underlying object(s)
287+
```
288+
289+
### Retries
290+
291+
The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
292+
as the request is deemed retryable and the number of retry attempts has not grown larger than the configured
293+
retry limit (default: 2).
294+
295+
A request is deemed retryable when any of the following HTTP status codes is returned:
296+
297+
- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
298+
- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
299+
- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)
300+
301+
Use the `max_retries` request option to configure this behavior.
302+
303+
```python
304+
client.agents.start(..., request_options={
305+
"max_retries": 1
306+
})
307+
```
308+
309+
### Timeouts
310+
311+
The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level.
312+
313+
```python
314+
315+
from agoraio import Agora
316+
317+
client = Agora(
318+
...,
319+
timeout=20.0,
320+
)
321+
322+
323+
# Override timeout for a specific method
324+
client.agents.start(..., request_options={
325+
"timeout_in_seconds": 1
326+
})
327+
```
328+
329+
### Custom Client
330+
331+
You can override the `httpx` client to customize it for your use-case. Some common use-cases include support for proxies
332+
and transports.
333+
334+
```python
335+
import httpx
336+
from agoraio import Agora
337+
338+
client = Agora(
339+
...,
340+
httpx_client=httpx.Client(
341+
proxy="http://my.test.proxy.example.com",
342+
transport=httpx.HTTPTransport(local_address="0.0.0.0"),
343+
),
344+
)
345+
```
346+
347+
## Contributing
348+
349+
While we value open-source contributions to this SDK, this library is generated programmatically.
350+
Additions made directly to this library would have to be moved over to our generation code,
351+
otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
352+
a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
353+
an issue first to discuss with us!
354+
355+
On the other hand, contributions to the README are always very welcome!

‎poetry.lock‎

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pyproject.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name = "agora-agent-sdk"
33

44
[tool.poetry]
55
name = "agora-agent-sdk"
6-
version = "1.0.0"
6+
version = "0.1.0"
77
description = ""
88
readme = "README.md"
99
authors = []
@@ -31,7 +31,7 @@ packages = [
3131
]
3232

3333
[tool.poetry.urls]
34-
Repository = 'https://github.com/fern-demo/agoraio-python-sdk'
34+
Repository = 'https://github.com/AgoraIO-Conversational-AI/agora-agent-python-sdk'
3535

3636
[tool.poetry.dependencies]
3737
python = "^3.8"

0 commit comments

Comments
 (0)