Skip to content

reference.md

Latest commit

 

History

History
1682 lines (1202 loc) · 24.7 KB

reference.md

File metadata and controls

1682 lines (1202 loc) · 24.7 KB

Reference

Agents

client.agents.start(...)

📝 Description

Create and start a Conversational AI agent instance.

🔌 Usage

from shengwang_agent import AgentClient, MicrosoftTtsParams, Tts_Microsoft
from shengwang_agent.agents import (
    StartAgentsRequestProperties,
    StartAgentsRequestPropertiesAsr,
    StartAgentsRequestPropertiesLlm,
)

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.agents.start(
    appid="appid",
    name="unique_name",
    properties=StartAgentsRequestProperties(
        channel="channel_name",
        token="token",
        agent_rtc_uid="1001",
        remote_rtc_uids=["1002"],
        idle_timeout=120,
        asr=StartAgentsRequestPropertiesAsr(
            language="en-US",
        ),
        tts=Tts_Microsoft(
            params=MicrosoftTtsParams(
                key="key",
                region="region",
                voice_name="voice_name",
            ),
        ),
        llm=StartAgentsRequestPropertiesLlm(
            url="https://api.minimax.chat/v1/text/chatcompletion_v2",
            api_key="<your_llm_key>",
            system_messages=[
                {"role": "system", "content": "You are a helpful chatbot."}
            ],
            params={"model": "abab6.5s-chat"},
            max_history=32,
            greeting_message="你好，有什么可以帮您？",
            failure_message="请稍等。",
        ),
    ),
)

⚙️ Parameters

appid: str — The App ID of the project.

name: str — The unique identifier of the agent. The same identifier cannot be used repeatedly.

properties: StartAgentsRequestProperties — Configuration details of the agent.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.list(...)

📝 Description

Retrieve a list of agents that meet the specified conditions.

🔌 Usage

from shengwang_agent import AgentClient

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
response = client.agents.list(
    appid="appid",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

appid: str — The App ID of the project.

channel: typing.Optional[str] — The channel to query for a list of agents.

from_time: typing.Optional[float] — The start timestamp (in seconds) for the query. Default is 2 hours ago.

to_time: typing.Optional[float] — The end timestamp (in seconds) for the query. Default is current time.

state: typing.Optional[ListAgentsRequestState]

The agent state to filter by. Only one state can be specified per query:

  • IDLE (0): Agent is idle.
  • STARTING (1): The agent is being started.
  • RUNNING (2): The agent is running.
  • STOPPING (3): The agent is stopping.
  • STOPPED (4): The agent has exited.
  • RECOVERING (5): The agent is recovering.
  • FAILED (6): The agent failed to execute.

limit: typing.Optional[int] — The maximum number of entries returned per page.

cursor: typing.Optional[str] — The paging cursor, indicating the starting position (agent_id) of the next page of results.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.get(...)

📝 Description

Get the current state information of the specified agent instance.

🔌 Usage

from shengwang_agent import AgentClient

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.agents.get(
    appid="appid",
    agent_id="agentId",
)

⚙️ Parameters

appid: str — The App ID of the project.

agent_id: str — The agent instance ID you obtained after successfully calling join to start a conversational AI agent.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.get_history(...)

📝 Description

Get the history of the conversation between the user and the agent.

Call this endpoint while the agent is running to retrieve the conversation history. You can set the maximum number of cached entries using the llm.max_history parameter when calling the start agent endpoint. The default value is 32.

🔌 Usage

from shengwang_agent import AgentClient

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.agents.get_history(
    appid="appid",
    agent_id="agentId",
)

⚙️ Parameters

appid: str — The App ID of the project.

agent_id: str — The agent instance ID you obtained after successfully calling join to start a conversational AI agent.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.stop(...)

📝 Description

Stop the specified conversational agent instance.

🔌 Usage

from shengwang_agent import AgentClient

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.agents.stop(
    appid="appid",
    agent_id="agentId",
)

⚙️ Parameters

appid: str — The App ID of the project.

agent_id: str — The agent instance ID you obtained after successfully calling join to start a conversational AI agent.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.update(...)

📝 Description

Adjust Conversation AI Engine parameters at runtime.

🔌 Usage

from shengwang_agent import AgentClient
from shengwang_agent.agents import (
    UpdateAgentsRequestProperties,
    UpdateAgentsRequestPropertiesLlm,
)

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.agents.update(
    appid="appid",
    agent_id="agentId",
    properties=UpdateAgentsRequestProperties(
        token="007eJxTYxxxxxxxxxxIaHMLAAAA0ex66",
        llm=UpdateAgentsRequestPropertiesLlm(
            system_messages=[
                {
                    "role": "system",
                    "content": "You are a helpful assistant. xxx",
                },
                {
                    "role": "system",
                    "content": "Previously, user has talked about their favorite hobbies with some key topics: xxx",
                },
            ],
            params={"model": "abab6.5s-chat", "max_token": 1024},
        ),
    ),
)

⚙️ Parameters

appid: str — The App ID of the project.

agent_id: str — The agent instance ID you obtained after successfully calling join to start a conversational AI agent.

properties: typing.Optional[UpdateAgentsRequestProperties] — Configuration properties to update.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.speak(...)

📝 Description

Broadcast a custom message using the TTS module.

During a conversation with an agent, call this endpoint to immediately broadcast a custom message using the TTS module. Upon receiving the request, the system interrupts the agent's speech and thought process to deliver the message. This broadcast can be interrupted by human voice.

Note: The speak API is not supported when using mllm configuration.

🔌 Usage

from shengwang_agent import AgentClient

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.agents.speak(
    appid="appid",
    agent_id="agentId",
    text="Sorry, the conversation content is not compliant.",
    priority="INTERRUPT",
    interruptable=False,
)

⚙️ Parameters

appid: str — The App ID of the project.

agent_id: str — The agent instance ID you obtained after successfully calling join to start a conversational AI agent.

text: str — The broadcast message text. The maximum length of the text content is 512 bytes.

priority: typing.Optional[SpeakAgentsRequestPriority]

Sets the priority of the message broadcast:

  • INTERRUPT: High priority. The agent immediately interrupts the current interaction to announce the message.
  • APPEND: Medium priority. The agent announces the message after the current interaction ends.
  • IGNORE: Low priority. If the agent is busy interacting, it ignores and discards the broadcast; the message is only announced if the agent is not interacting.

interruptable: typing.Optional[bool]

Whether to allow users to interrupt the agent's broadcast by speaking:

  • true: Allow
  • false: Don't allow

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.interrupt(...)

📝 Description

Interrupt the specified agent while speaking or thinking.

🔌 Usage

from shengwang_agent import AgentClient

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.agents.interrupt(
    appid="appid",
    agent_id="agentId",
)

⚙️ Parameters

appid: str — The App ID of the project.

agent_id: str — The agent instance ID you obtained after successfully calling join to start a conversational AI agent.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Telephony

client.telephony.list(...)

📝 Description

Query historical call records for a specified appid based on the filter criteria.

🔌 Usage

from shengwang_agent import AgentClient

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
response = client.telephony.list(
    appid="appid",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

appid: str — The App ID of the project.

number: typing.Optional[str] — Filter by phone number. Can be either the calling number or the called number.

from_time: typing.Optional[int] — Query list start timestamp (in seconds). Default is 60 days ago.

to_time: typing.Optional[int] — Query list end timestamp (in seconds). Default is current time.

type: typing.Optional[ListTelephonyRequestType]

Call type filter:

  • inbound: Inbound call.
  • outbound: Outbound call.

If not specified, all call types are returned.

limit: typing.Optional[int] — Maximum number of items returned in a single page.

cursor: typing.Optional[str] — Pagination cursor. Use the agent_id from the previous page as the cursor for the next page.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.telephony.call(...)

📝 Description

Initiate an outbound call to a specified number and create an agent to join the specified RTC channel.

Use this endpoint to initiate an outbound call to the specified number and create an agent that joins the target RTC channel. The agent waits for the callee to answer.

🔌 Usage

from shengwang_agent import AgentClient
from shengwang_agent.telephony import (
    CallTelephonyRequestProperties,
    CallTelephonyRequestSip,
)

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.telephony.call(
    appid="appid",
    name="customer_service",
    sip=CallTelephonyRequestSip(
        to_number="+19876543210",
        from_number="+11234567890",
        rtc_uid="100",
        rtc_token="<agora_sip_rtc_token>",
    ),
    properties=CallTelephonyRequestProperties(
        channel="<agora_channel>",
        token="<agora_channel_token>",
        agent_rtc_uid="111",
        remote_rtc_uids=["100"],
    ),
)

⚙️ Parameters

appid: str — The App ID of the project.

name: str — The name identifier of the call session.

sip: CallTelephonyRequestSip — SIP (Session Initiation Protocol) call configuration object.

properties: CallTelephonyRequestProperties

Call attribute configuration. The content of this field varies depending on the invocation method:

  • Using pipeline ID: Simply pass in channel, token, agent_rtc_uid, and remote_rtc_uids.
  • Using complete configuration: Pass in the complete parameters of the Start a conversational AI agent properties, including all required fields such as channel, token, agent_rtc_uid, remote_rtc_uids, tts, and llm.

pipeline_id: typing.Optional[str] — The unique ID of a published project in AI Studio.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.telephony.get(...)

📝 Description

Retrieve the call status and related information of a specified agent.

🔌 Usage

from shengwang_agent import AgentClient

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.telephony.get(
    appid="appid",
    agent_id="agent_id",
)

⚙️ Parameters

appid: str — The App ID of the project.

agent_id: str — The agent ID you obtained after successfully calling the API to initiate an outbound call.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.telephony.hangup(...)

📝 Description

Instruct the agent to proactively hang up the ongoing call and leave the RTC channel.

🔌 Usage

from shengwang_agent import AgentClient

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.telephony.hangup(
    appid="appid",
    agent_id="agent_id",
)

⚙️ Parameters

appid: str — The App ID of the project.

agent_id: str — The agent ID you obtained after successfully calling the API to initiate an outbound call.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

PhoneNumbers

client.phone_numbers.list()

📝 Description

Retrieve a list of all imported phone numbers under the current account.

🔌 Usage

from shengwang_agent import AgentClient

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.phone_numbers.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.phone_numbers.add(...)

📝 Description

Import a pre-configured phone number that can be used for inbound or outbound calls.

🔌 Usage

from shengwang_agent import AgentClient
from shengwang_agent.phone_numbers import (
    AddPhoneNumbersRequestInboundConfig,
    AddPhoneNumbersRequestOutboundConfig,
)

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.phone_numbers.add(
    provider="byo",
    phone_number="+19876543210",
    label="Sales Hotline",
    inbound=True,
    outbound=True,
    inbound_config=AddPhoneNumbersRequestInboundConfig(
        allowed_addresses=["112.126.15.64/27"],
    ),
    outbound_config=AddPhoneNumbersRequestOutboundConfig(
        address="xxx:xxx@sip.example.com",
        transport="tls",
    ),
)

⚙️ Parameters

provider: AddPhoneNumbersRequestProvider

Number provider:

  • byo: BYO (Bring Your Own)
  • twilio: Twilio

phone_number: str — Telephone number in E.164 format.

label: str — A label used to identify the number.

inbound_config: AddPhoneNumbersRequestInboundConfig — SIP inbound call configuration.

outbound_config: AddPhoneNumbersRequestOutboundConfig — SIP outbound call configuration.

inbound: typing.Optional[bool] — Whether the number supports inbound calls.

outbound: typing.Optional[bool] — Whether the number supports outbound calls.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.phone_numbers.get(...)

📝 Description

Retrieve detailed information for a specific phone number.

🔌 Usage

from shengwang_agent import AgentClient

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.phone_numbers.get(
    phone_number="phone_number",
)

⚙️ Parameters

phone_number: str — Telephone number in E.164 format. For example, +11234567890.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.phone_numbers.delete(...)

📝 Description

Remove an imported phone number from the system.

After calling this endpoint, the number stops receiving calls routed through this system. To delete the number from the service provider, remove it in the service provider's console.

This operation only removes the number configuration from the system; the number stored with the phone service provider is not deleted.

🔌 Usage

from shengwang_agent import AgentClient

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.phone_numbers.delete(
    phone_number="phone_number",
)

⚙️ Parameters

phone_number: str — Telephone number in E.164 format. For example, +11234567890.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.phone_numbers.update(...)

📝 Description

Update the configuration for a phone number.

🔌 Usage

from shengwang_agent import AgentClient
from shengwang_agent.phone_numbers import (
    UpdatePhoneNumbersRequestInboundConfig,
    UpdatePhoneNumbersRequestOutboundConfig,
)

client = AgentClient(
    authorization="YOUR_AUTHORIZATION",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.phone_numbers.update(
    phone_number="phone_number",
    inbound_config=UpdatePhoneNumbersRequestInboundConfig(
        pipeline_id="xxxxx",
    ),
    outbound_config=UpdatePhoneNumbersRequestOutboundConfig(
        pipeline_id="xxxxx",
    ),
)

⚙️ Parameters

phone_number: str — Telephone number in E.164 format. For example, +11234567890.

inbound_config: typing.Optional[UpdatePhoneNumbersRequestInboundConfig] — Update inbound call configuration. Passing null will clear the configuration.

outbound_config: typing.Optional[UpdatePhoneNumbersRequestOutboundConfig] — Update outbound call configuration. Passing null will clear the configuration.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.