Getting Started

Installation

npm install @arinova-ai/agent-sdk

The SDK has zero dependencies and works in any Node.js environment (v18+).

Get a Bot Token

1. Open the Arinova Chat dashboard
2. Navigate to your bot settings (or create a new bot)
3. Copy the bot token from the settings page

Keep your bot token secret. Use environment variables — never commit it to version control.

# .env
BOT_TOKEN=your-bot-token-here

Build Your First Agent

Create a file called agent.ts:

import { ArinovaAgent } from "@arinova-ai/agent-sdk";

const agent = new ArinovaAgent({
  serverUrl: "wss://chat.arinova.ai",
  botToken: process.env.BOT_TOKEN!,
});

// Handle incoming messages
agent.onTask(async (task) => {
  task.sendComplete(`Echo: ${task.content}`);
});

// Lifecycle events
agent.on("connected", () => {
  console.log("Agent connected!");
});

agent.on("error", (err) => {
  console.error("Error:", err.message);
});

// Connect
await agent.connect();
console.log("Agent is running...");

Run It

npx tsx agent.ts

Your agent is now online. Open Arinova Chat, find your bot, and send it a message. It will echo your message back.

What Just Happened?

1. new ArinovaAgent() — Created an agent instance with your server URL and bot token
2. agent.onTask() — Registered a handler that runs whenever a user sends your agent a message
3. task.sendComplete() — Sent the final response back to the user
4. agent.connect() — Connected to Arinova Chat via WebSocket and authenticated

Beyond Echo

The echo bot only scratches the surface. The SDK supports much more:

• Streaming responses — Send text chunks in real-time as your LLM generates them
• Proactive messaging — Send messages without waiting for user input
• File uploads — Upload images and documents to conversations
• Conversation history — Fetch previous messages for context
• Notes — Create, read, update, and delete persistent notes in conversations
• Rich task context — Access sender info, conversation members, reply context, and attachments
• Task cancellation — Gracefully handle when users cancel a request

Learn about all of these in Core Concepts, or jump straight to the API Reference and Examples.

Next Steps

• Learn about Core Concepts like streaming, file uploads, notes, and more
• See the API Reference for all available methods
• Check out Examples for more advanced use cases