Agents allow you to create, manage, and interact with intelligent AI assistants. Follow the example below to create a simple agent and start speaking with it.

import os
import asyncio

# See AgentConfig model for full list of parameters to configure the agent
from pyneuphonic import Neuphonic, Agent, AgentConfig

async def main():
    client = Neuphonic(api_key=os.environ.get('NEUPHONIC_API_KEY'))

    agent_id = client.agents.create(
        name='Agent 1',
        prompt='You are a helpful agent. Answer in 10 words or less.',
        greeting='Hi, how can I help you today?'
    ).data['agent_id']

    # All additional keyword arguments (such as `agent_id` and `tts_model`) are passed as
    # parameters to the model. See AgentConfig model for full list of parameters.
    agent = Agent(client, agent_id=agent_id, tts_model='neu_hq')

    try:
        await agent.start()

        while True:
            await asyncio.sleep(1)
    except KeyboardInterrupt:
        await agent.stop()

asyncio.run(main())

When you run the example, the agent will greet you with “Hi, how can I help you today?”. Your spoken input is then converted into text by a speech recognition system. The prompt you set above is used as the system prompt for a GPT-4o model, which generates the responses. These responses are then converted to audio using Neuphonic’s TTS and played back to you. You can keep the conversation going for as long as you want!

​
Editing the Callback

The Agent interface described above utilizes a WebSocket connection to facilitate real-time audio streaming between your microphone and the server. The server processes this audio and sends back responses, which can be categorized into the following types:

This message contains the text transcription of your spoken input. It is sent by the server once the speech recognition system detects a pause long enough to consider your turn complete. You will receive one of these messages for each turn in the conversation.

{
    "type": "user_transcript",
    "text": "<TRANSCRIPTION>"
}

The Agent class, by default, plays audio_response messages and prints llm_response and user_transcript messages to the console. To customize this behavior, you can attach a custom event handler as shown below:

import os
import asyncio

from pyneuphonic import Neuphonic, Agent, AgentConfig
from pyneuphonic.models import APIResponse, AgentResponse

def on_message(message: APIResponse[AgentResponse]):
    if message.data.type == 'user_transcript':
        print(f'Received user_transcript')
    elif message.data.type == 'llm_response':
        print(f'Received llm_response')
    elif message.data.type == 'audio_response':
        print(f'Received audio_response')

async def main():
    client = Neuphonic(api_key=os.environ.get('NEUPHONIC_API_KEY'))

    agent_id = client.agents.create(
        name='Agent 1',
        prompt='You are a helpful agent. Answer in 10 words or less.',
        greeting='Hi, how can I help you today?'
    ).data['agent_id']

    agent = Agent(
        client,
        agent_id=agent_id,
        tts_model='neu_hq',
        on_message=on_message,  # attach the custom callback
    )

    try:
        await agent.start()

        while True:
            await asyncio.sleep(1)
    except KeyboardInterrupt:
        await agent.stop()

asyncio.run(main())

​
View Agents

To retrieve a list of all your existing agents

curl -X GET "https://eu-west-1.api.neuphonic.com/agents" \
     -H "X-API-KEY: <API_KEY>"

The previous response does not include prompt and greeting because they can be quite lengthy, especially for complex agents with extensive system prompts. The following request will return all details for the specified agent_id.

curl -X GET "http://eu-west-1.api.neuphonic.com/agents/<AGENT_ID>" \
     -H "X-API-KEY: <API_KEY>"

​
More Examples

To see more examples with our Python SDK, head over to the GitHub repo agents examples section.

How to Clone a VoiceHow to Restore Speech