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
agentscope: open the key under API keys and enable it. New keys don't have it, and without it the session request returns403 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/express2. 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.js5. Talk to the agent
node server.tsOpen http://localhost:3000 and select Talk to the agent.
Voice Agent
Add a hosted HUMAIN voice agent to your web or mobile app; your backend starts each call with its API key and your user talks to the agent over WebRTC.
Session options
Set the prompt, intro, voice, variables, and client tools of a Voice Agent session, read back its settings and limits, and look up past sessions.