Build an AI Assistant with Novium Cloud

Create, deploy, and run a memory-enabled AI assistant in under 30 minutes.

Overview

You'll build a conversational AI assistant that:

Receives and responds to user messages
Remembers users across sessions
Stores conversation history
Runs as a durable workflow
Deploys to production with observability

Expected outcome: A working assistant you can call via HTTP, with persistent memory and logging.

Architecture

User
  ↓
Assistant Agent
  ↓
Memory (user identity + conversation history)
  ↓
Workflow (trigger → agent → memory → log)
  ↓
Observability (logs, traces, execution time)

Prerequisites

Node.js >= 20
pnpm >= 9
Novium account (sign up)
API key (Dashboard → Settings → API Keys)

node --version   # >= 20
pnpm --version   # >= 9

Step 1: Create Workspace

novium login

Follow the browser prompt, then:

novium org create demo-org
novium workspace create ai-assistant

Workspace "ai-assistant" created successfully.

Set your API key:

export NOVIUM_API_KEY=nv_live_xxxxxxxxxxxxxxxxxxxx

Concepts:

| Term | Definition | | ---- | ---------- | | Organization | Top-level account that owns workspaces, agents, and resources | | Workspace | An isolated environment within an organization for a project | | API Key | Secret token used to authenticate API and CLI requests |

Step 2: Create Assistant Agent

novium agent create assistant

Created agent "assistant" at ./agents/assistant/

Generated structure:

agents/
  assistant/
    agent.ts          ← your agent logic
    package.json       ← dependencies
    novium.config.ts   ← agent configuration

Step 3: Implement Logic

Open agents/assistant/agent.ts:

export default async function agent(input: {
  userId: string;
  message: string;
}) {
  return {
    reply: `Hello! You said: "${input.message}"`,
    timestamp: new Date().toISOString(),
  };
}

| Concept | Description | | ------- | ----------- | | input | JSON payload sent when the agent is invoked | | return | The agent's response — any JSON-serializable value |

Step 4: Add Memory

Remember who is talking, and store conversation history.

export default async function agent(input: {
  userId: string;
  message: string;
  name?: string;
}) {
  // Store user identity
  if (input.name) {
    await memory.save({
      key: `user:${input.userId}:name`,
      value: input.name,
    });
  }

  // Retrieve conversation history
  const history =
    (await memory.get(`conversation:${input.userId}`)) ?? [];

  history.push({
    role: "user" as const,
    content: input.message,
    timestamp: new Date().toISOString(),
  });

  await memory.save({
    key: `conversation:${input.userId}`,
    value: history,
  });

  const userName = await memory.get(`user:${input.userId}:name`);

  return {
    reply: userName
      ? `Welcome back, ${userName}! (Message #${history.length})`
      : `Hello! (Message #${history.length})`,
    rememberedName: userName ?? null,
    messageCount: history.length,
    timestamp: new Date().toISOString(),
  };
}

Memory API:

| Method | Description | | ------ | ----------- | | memory.save({ key, value }) | Persist a value | | memory.get(key) | Retrieve a value. Returns null if not found. |

Memory is scoped per agent and persists across deploys.

Step 5: Add Workflow

Wrap the assistant in a durable workflow.

novium workflow create assistant-chat

Open workflows/assistant-chat/workflow.ts:

export default {
  trigger: { type: "http", method: "POST", path: "/chat" },
  steps: [
    {
      id: "greet-user",
      agent: "assistant",
      input: {
        userId: "$input.userId",
        message: "$input.message",
        name: "$input.name",
      },
    },
    {
      id: "store-conversation",
      agent: "assistant",
      input: {
        userId: "$input.userId",
        message: "$input.message",
      },
    },
    { id: "finalize", action: "log", message: "Chat completed for user $input.userId" },
  ],
};

Trigger (HTTP POST /chat)
  ↓
greet-user          ← agent with name + message
  ↓
store-conversation  ← agent with message only
  ↓
finalize            ← log completion

Step 6: Run Locally

novium agent dev

Agent "assistant" running at http://localhost:3000

Test first visit:

curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-1", "message": "Hi!", "name": "Alice"}'

{
  "reply": "Welcome back, Alice! (Message #1)",
  "rememberedName": "Alice",
  "messageCount": 1
}

Test return visit (no name sent):

curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-1", "message": "How are you?"}'

{
  "reply": "Welcome back, Alice! (Message #2)",
  "rememberedName": "Alice",
  "messageCount": 2
}

The assistant remembered Alice.

Step 7: Observe Logs

novium logs

TIMESTAMP            REQUEST ID     AGENT       DURATION   STATUS
2025-01-15 10:30:01  req_a1b2c3     assistant   312ms      success
2025-01-15 10:31:05  req_d4e5f6     assistant   287ms      success

Filter by error:

novium logs --status error

Step 8: Deploy

novium deploy

✓ Deployed to production

  Agent "assistant":
    Endpoint: https://ai-assistant.novium.cloud/assistant
    Version:  v1

  Workflow "assistant-chat":
    Endpoint: https://ai-assistant.novium.cloud/chat
    Version:  v1

Call production:

curl -X POST https://ai-assistant.novium.cloud/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NOVIUM_API_KEY" \
  -d '{"userId": "user-1", "message": "Hello from production!"}'

{
  "workflowId": "wf_xyz789",
  "status": "completed",
  "result": {
    "reply": "Welcome back, Alice! (Message #3)",
    "rememberedName": "Alice",
    "messageCount": 3
  },
  "duration": "412ms"
}

Final Result

A conversational AI assistant deployed to production, with user memory, conversation history, workflow orchestration, and observability.

User
  ↓
Novium Endpoint (https://ai-assistant.novium.cloud/chat)
  ↓
Workflow (greet → store → log)
  ↓
Memory Cloud (user identity + history)
  ↓
Observability Cloud (logs, traces)

What You Learned

✅ Created a workspace
✅ Created an AI assistant agent
✅ Added user identity memory
✅ Stored and retrieved conversation history
✅ Created a multi-step workflow
✅ Viewed execution logs
✅ Deployed to production
✅ Called the deployed endpoint

Next Tutorial

Build a Customer Support Agent →