Voice Agent

Voice Agent quickstart

Start a Voice Agent session from your backend and talk to the agent from a web page in about five minutes.

You add one route to your backend that starts a session, and one web page that joins it.

Before you start

  • An API key from the HUMAIN Voice console (Authentication) with the agent scope: open the key under API keys and enable it. New keys don't have it, and without it the session request returns 403 AUTH_SCOPE_MISSING.
  • Node.js 24 or newer, or Python 3.10 or newer, for the backend. Node.js is also used to bundle the page.

1. Install

npm install @humain-voice/[email protected] @humain-voice/[email protected] livekit-client express
npm install --save-dev esbuild @types/express

2. Set your environment

export API_URL="https://api.voice.humain.com"
export API_KEY="YOUR_API_KEY"

3. Add a session route to your backend

server.ts or server.py. Replace user-123 with your own ID for the signed-in user.

import express from 'express';
import { AgentClient } from '@humain-voice/sdk/agent';

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

const agent = new AgentClient({ api_url: requiredEnv('API_URL'), api_key: requiredEnv('API_KEY') });
const app = express();
app.use(express.static('public'));

app.post('/agent-session', async (_req, res) => {
  try {
    const session = await agent.createSession({
      participant: { identity: 'user-123' },
      agent: {
        prompt: 'You are the assistant of a bakery in Riyadh. Keep answers short.',
        intro: 'Hello! How can I help you today?',
      },
    });
    res.json(session.tokenResponse());
  } catch (err) {
    console.error('error:', err);
    res.status(502).json({ error: 'could not start a session' });
  }
});

app.listen(3000, () => console.log('open http://localhost:3000'));

4. Add the web page

public/index.html. Serve it from localhost or over HTTPS, or the browser blocks the microphone:

<!doctype html>
<html lang="en">
  <body>
    <button id="talk">Talk to the agent</button>
    <p id="status">idle</p>
    <script type="module" src="./agent.js"></script>
  </body>
</html>

agent.ts:

import { AgentSession } from '@humain-voice/agent';

const button = document.querySelector<HTMLButtonElement>('#talk')!;
const status = document.querySelector<HTMLParagraphElement>('#status')!;
let call: AgentSession | undefined;

button.addEventListener('click', async () => {
  if (call) {
    await call.end();
    return;
  }
  call = await AgentSession.start({
    token: () => fetch('/agent-session', { method: 'POST' }).then((res) => res.json()),
    onStatusChange: (value) => (status.textContent = value),
    onModeChange: (mode) => (status.textContent = mode),
    onMessage: (message) => {
      if (message.final) console.log(`${message.role}: ${message.text}`);
    },
    onEnd: ({ reason }) => {
      status.textContent = `ended: ${reason}`;
      button.textContent = 'Talk to the agent';
      call = undefined;
    },
  });
  button.textContent = 'Hang up';
});

Bundle it into the page:

npx esbuild agent.ts --bundle --format=esm --outfile=public/agent.js

5. Talk to the agent

node server.ts

Open http://localhost:3000 and select Talk to the agent.

On this page