Agents

An agent is the runnable unit you talk to. It bundles a persona with everything the runtime needs to actually carry a conversation: a voice stack, an attached tool set, knowledge sources, dynamic variables, listening behavior, post-session work, and limits.

A persona on its own defines how the AI should behave. An agent decides what providers, tools, voices, and rules that behavior runs against in production.

What an agent is composed of

Piece	What it controls
Persona	System prompt, first message, no-go zones, sleep windows, escalation rules, greeting mode.
Voice stack	STT + LLM + TTS providers, cascading fallbacks, soft-timeout filler, custom-LLM endpoints. Used for voice modalities; the LLM choice also drives text turns.
Tools	Built-in, system, and custom HTTP / MCP tools the agent may call.
Knowledge base	Documents and inline notes attached for retrieval-augmented answers.
Dynamic variables	Per-session values substituted into prompts and (optionally) tool calls.
Listening profile	Voice tuning: VAD sensitivity, interruption policy, first-message protection.
Post-session runners	LLM-driven extraction jobs that run after each conversation ends.
Phone numbers	Inbound numbers attached to the agent.
Modality	voice, voice+text, or text. Drives which transports are accepted.
Security and limits	Origin allowlist, signed-URL requirement, max call duration, audio recording flag.
Widget config	Visual defaults if you embed the agent through the web widget.

Create an agent

In the dashboard, Agents → New lets you select a persona, a voice profile, and a modality, then configure each tab:

• Voice — pick STT, LLM, TTS providers, voices, and fallback chains.
• Models — choose the model used for text turns and post-session work.
• Tools — attach catalog tools (built-ins, system, and custom workspace tools).
• Knowledge — attach knowledge base sources.
• Variables — declare dynamic variables and how they are sourced.
• Listening — pick a listening profile or create a new one.
• Post-session — add runners to extract structured data after each call.
• Tests — wire datasets and scorers for repeatable evaluation runs.
• Publish — promote the current draft to the next version.
• Advanced — origin allowlist, recording, call duration, widget defaults.

You can also create an agent through the API:

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/agents" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reception agent",
    "persona_id": "persona_...",
    "voice_profile_id": "voice_profile_...",
    "modality": "voice+text"
  }'

PATCH the same path to update fields. POST .../duplicate clones an agent. Use the dashboard whenever you can — most settings are easier to edit visually and the API surface is curated for v1.

Drafts, versions, and publish

Edits to an agent or its persona are saved as draft state. They take effect immediately for dashboard test sessions and for live sessions that point at the latest configuration, but they do not roll forward to a published version until you publish.

POST /workspaces/{ws}/agents/{agent_id}/publish snapshots the current persona, voice stack, tools, KB attachments, dynamic variables, and policies into a new AgentVersion. The version snapshot is what live conversations are anchored to, so post-publish edits do not retroactively change historical sessions.

POST /workspaces/{ws}/agents/{agent_id}/rollback re-points the agent at a prior version when a publish underperforms.

GET /workspaces/{ws}/agents/{agent_id}/versions lists the version history.

Agent vs. persona — when to edit which

• Edit the persona when you want to change what the AI says, its tone, its no-go zones, escalation rules, or its greeting behavior.
• Edit the agent when you want to change the providers it runs through, the tools it can call, the knowledge it can read, or per-session limits.
• A persona can be reused across agents (e.g. one persona, two agents with different voices).

Modalities and entry points

Modality	Entry points
voice	Voice WebSocket, telephony, web widget (voice-only).
voice+text	Voice WebSocket plus inline text events, web widget (voice+text).
text	Text chat SSE, web widget (text-only).

The modality you set on the agent is the union of what the agent will accept. A text-only agent rejects voice WebSocket connections; a voice agent rejects text-only sessions.

What’s next

• Walk through Operator setup for a checklist before launching.
• Attach actions through Tools (HTTP and MCP).
• Give the agent reference material through the Knowledge base.
• Personalize per session with Dynamic variables.
• Extract structured data after each conversation with Evaluations and testing.