Live sessions with an agent

A live session is the same session the Test button on an agent runs in the portal. You start it with the API, join it from your own app, talk or type to the agent, and end it. The key needs the Talk to agents access.

What you need

• An API key with Talk to agents (agents:talk). See Give a key talk access.
• The agent id, as GET /v1/agents returns it.
• The livekit-client package in the app that joins the session.

Give a key talk access

Under Agent and tool access on the key form, tick Talk to agents. A key with only this access can start, read and end sessions. It cannot change agents. Without it the API answers 403 with This API key cannot talk to agents..

The key acts for the member who created it. That member must keep the permission to view agents and the permission to manage the developer API.

Start, join, end

1. Start the session with your key. The answer carries a room token and a wsUrl.
2. Join the room from the client with the token.
3. End the session when the user is done.

Start a voice session. Leave channel out for voice, or send "chat" for a text session.

curl -X POST "https://api.echonova.ai/v1/agents/{agentId}/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"voice"}'

The answer holds id, agentId, channel, status, startedAt, endedAt, token, wsUrl and greeting. greeting is the agent's first message for a chat session and null for voice. See Start a live session.

Join a voice session

Open the microphone, connect with wsUrl and token, publish the microphone and play the agent's audio track.

import { Room, RoomEvent, createLocalAudioTrack } from 'livekit-client';

const mic = await createLocalAudioTrack();
const room = new Room({ adaptiveStream: true, dynacast: true });
const audio = new Audio();
audio.autoplay = true;

room.on(RoomEvent.TrackSubscribed, (track) => {
  if (track.kind === 'audio') {
    track.attach(audio);
    audio.play().catch(() => undefined);
  }
});

await room.connect(session.wsUrl, session.token);
await room.localParticipant.publishTrack(mic);

An agent track that is already in the room when you join is not announced again. After you connect, attach the audio tracks that are already there:

room.remoteParticipants.forEach((participant) =>
  participant.audioTrackPublications.forEach((publication) => {
    if (publication.track) publication.track.attach(audio);
  }),
);

Join a chat session

A chat session is text only. Send the user's message on the topic lk.chat. The agent answers on the topic lk.transcription, one text stream for each turn. echonova.status carries short progress notes as JSON { "kind", "text" }. It is optional: a client can ignore it.

import { Room } from 'livekit-client';

const room = new Room();

room.registerTextStreamHandler('lk.transcription', async (reader) => {
  let text = '';
  for await (const chunk of reader) {
    text += chunk;
    // Show `text` as it grows.
  }
});

await room.connect(session.wsUrl, session.token);
await room.localParticipant.sendText('What are your opening hours?', {
  topic: 'lk.chat',
});

Show greeting from the start answer before the user types. The agent may also send the same greeting as its first stream; skip that stream so it shows once.

End the session

Leave the room, then end the session so the room closes and the conversation is saved.

await room.disconnect();

curl -X POST "https://api.echonova.ai/v1/agents/{agentId}/sessions/{sessionId}/end" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ending a session that already ended answers 200 with its final status. GET /v1/agents/{agentId}/sessions/{sessionId} returns the status at any time. See Get a live session and End a live session.

Keep the token on your side

• The token is sent once, in the start answer. The read and end calls never return it.
• Hand it only to the client that joins. Do not log it or store it.
• A token opens one session. To talk again, start a new session.
• Start sessions from your server, so the API key never reaches the browser.

A retried start opens a second session, so do not retry a start blindly.

Limits and credits

• Starts: 10 a minute for each key. Past that the API answers 429; wait Retry-After seconds.
• The agent's own limits: the agent's chat limits and call limits apply to sessions started here. A full agent answers 409 with This agent has reached its call limit. Try again later. for a voice start, or This agent has reached its chat limit. Try again later. for a chat start.
• Credits: a session uses workspace credits, as a test in the portal does. They do not count against the key's Credit Limit. A workspace with no credits answers 402 before the session starts, and nothing is charged.
• Archived agents: an archived agent answers 409. Restore it first.

Every error text is on Errors.

Use your own avatar

If your app already has an avatar, it can speak for the agent. Join the voice session with the token, take the agent's audio track and play it through your avatar. That is all. EchoNova sends no extra events for an avatar and does not render the face. Your app draws it.

Related

• Errors
• Rate limits
• Changelog