Novium Creation Guide

Build and Run Your First AI Agent

Novium Cloud is an Agent Control Plane. It helps developers deploy, manage, monitor, and scale AI agents using a unified platform.

1. Prerequisites

Node.js >= 20
pnpm >= 9
A Novium account (sign up at novium.cloud)
An API key (generate in Dashboard → Settings → API Keys)

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

2. Install the CLI

pnpm add -g @novium/cli

Verify:

novium --version

3. Create Your Workspace

novium login

Follow the browser prompt to authenticate. Then:

novium org create my-org
novium workspace create my-workspace

Expected output:

Workspace "my-workspace" created successfully.

Set your API key as an environment variable:

export NOVIUM_API_KEY=nv_live_xxxxxxxxxxxxxxxxxxxx

4. Create Your First Agent

novium agent create hello-agent

Generated structure:

agents/
  hello-agent/
    agent.ts
    package.json

5. Write Agent Logic

Open agents/hello-agent/agent.ts:

export default async function agent(input: { name: string }) {
  return {
    message: `Hello, ${input.name}!`
  };
}

How it works:

input — data sent to the agent when invoked
return — the agent's response (any JSON-serializable value)

That's it. No framework. No boilerplate.

6. Run Locally

novium agent dev

Agent "hello-agent" running at http://localhost:3000

Test with curl:

curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{"name": "Novium"}'

Response:

{
  "message": "Hello, Novium!"
}

7. Deploy

novium deploy

Deploying "hello-agent"...
✓ Built (1.2s)
✓ Deployed to production
  Version:   v1
  Endpoint:  https://my-workspace.novium.cloud/hello-agent

Your agent is live. Call the production endpoint the same way you called localhost.

8. Add Memory

Give your agent persistent state.

Update agents/hello-agent/agent.ts:

export default async function agent(input: { name: string }) {
  const visits = await memory.get("visits") ?? 0;
  await memory.save({ key: "visits", value: visits + 1 });

  return {
    message: `Hello, ${input.name}!`,
    visitCount: visits + 1,
  };
}

How it works:

memory.get(key) — retrieve a stored value
memory.save({ key, value }) — persist a value

Memory survives agent restarts and deployments.

9. Create a Workflow

Chain your agent with memory and logging.

novium workflow create hello-workflow

Open workflows/hello-workflow/workflow.ts:

export default {
  trigger: { type: "http", method: "POST", path: "/hello-workflow" },
  steps: [
    { id: "greet", agent: "hello-agent", input: { name: "$input.name" } },
    { id: "remember", agent: "hello-agent", input: { name: "$input.name" } },
    { id: "log", action: "log", message: "Workflow complete" },
  ],
};

Run the workflow:

novium workflow run hello-workflow --input '{"name": "Novium"}'

Output:

Workflow "hello-workflow" started.
  ✓ greet     — 0.3s
  ✓ remember  — 0.2s
  ✓ log       — 0.0s
Completed in 0.5s

10. View Logs

novium logs

TIMESTAMP            REQUEST ID          AGENT            DURATION   STATUS
2025-01-15 10:23:01  req_abc123          hello-agent      312ms      success
2025-01-15 10:24:12  req_def456          hello-agent      287ms      success
2025-01-15 10:25:44  req_ghi789          hello-agent      401ms      success

Filter by agent or status:

novium logs --agent hello-agent --status error

11. Use the SDK

For applications that need to call agents programmatically:

pnpm add @novium/sdk

import { Novium } from "@novium/sdk";

const client = new Novium({
  apiKey: process.env.NOVIUM_API_KEY,
});

const result = await client.agent.run("hello-agent", {
  input: { name: "Novium" },
});

console.log(result); // { message: "Hello, Novium!", visitCount: 1 }

12. Troubleshooting

Authentication Failed

Cause: Invalid or missing API key.

Solution: Check NOVIUM_API_KEY is set and matches the key in Dashboard → Settings → API Keys.

echo $NOVIUM_API_KEY

Agent Deployment Failed

Cause: Build error in agent code.

Solution: Run locally first to catch errors:

novium agent dev

Check the console for stack traces.

Workflow Not Triggering

Cause: Trigger configuration mismatch.

Solution: Verify the trigger path and method match your request. Check workflow logs:

novium logs --workflow hello-workflow

Memory Not Found

Cause: Key was never saved, or was saved in a different agent context.

Solution: Memory is scoped per agent. Make sure you're reading from the same agent that wrote the value.

13. Next Steps

You've built and deployed an AI agent with memory and workflows.

What you can do next:

Create multiple agents that call each other
Build complex workflows with conditional steps and approval gates
Add observability alerts for error thresholds
Use the Developer Cloud SDK to embed agents in your own applications

Resources: