Quickstart

This quickstart walks through the smallest useful Hyponema setup: create or open a workspace, configure an agent, start a session, and send one text message.

Prerequisites

You need:

• A Hyponema workspace with private-beta access.
• An API key for that workspace.
• At least one configured model provider.
• A user identifier from your application, such as a user ID or account ID.

1. Configure an agent

In the dashboard, create an agent and attach a persona. The persona contains the system prompt, first message, boundaries, sleep windows, and greeting behavior.

Keep the first version simple. Add tools, telephony, and custom greeting behavior after the basic session works.

2. Start a session

Create a session for the user and agent. The session represents one live conversation across text, voice, widget, or telephony.

curl -X POST "https://api.hyponema.ai/sessions" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_...",
    "user_id": "user_123",
    "modality": "text"
  }'

Save the returned session ID. You will use it to send messages or connect a client.

3. Send a text message

curl -N -X POST "https://api.hyponema.ai/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hi, can you help me continue where we left off?"
  }'

The response streams assistant output over Server-Sent Events.

4. Inspect the trace

Open the session in the dashboard to review the transcript, tool calls, memory retrieval, guardrails, latency, and errors.

Next steps

• Add the web widget for browser sessions.
• Connect a voice WebSocket for real-time audio.
• Attach tools so the agent can act inside your product.
• Review observability before moving to production.