Novium Cloud
All guides

Your First Agent

Create, Run, and Deploy an AI Agent

1. Create

novium agent create hello-agent

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

2. Write

Open agents/hello-agent/agent.ts:

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

Concepts:

| Concept | Description | | ------- | ----------- | | input | JSON payload sent by the caller | | return | Response object returned to the caller | | agent | A serverless function that runs on Novium Cloud |

3. Run Locally

novium agent dev

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

Test:

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

{
  "message": "Hello, Alice!",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

4. Environment Variables

Set in agents/hello-agent/.env:

OPENAI_API_KEY=sk-xxxxxxxx

Access in code:

const apiKey = process.env.OPENAI_API_KEY;

5. Deploy

novium deploy

✓ Built
✓ Deployed
  Version:   v1
  Endpoint:  https://my-workspace.novium.cloud/hello-agent

Call production:

curl -X POST https://my-workspace.novium.cloud/hello-agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NOVIUM_API_KEY" \
  -d '{"name": "Alice"}'

6. Update and Redeploy

Edit your agent, then:

novium deploy

✓ Deployed
  Version: v2

Previous version v1 remains available at https://my-workspace.novium.cloud/hello-agent?v=1.

7. List Agents

novium agent list

NAME           VERSION   STATUS    ENDPOINT
hello-agent    v2        active    /hello-agent

Next Steps