Getting Started with AI Agents

Build your first multi-agent workflow in minutes.

Prerequisites

Step 1: Install

npm install @nolag/agents @nolag/js-sdk

@nolag/agents is a high-level SDK built on @nolag/js-sdk. Both are required.

Step 2: Create an Agents App

  1. Open the NoLag Portal and navigate to your project
  2. Click Create App and select the Agents blueprint
  3. Give your app a slug (e.g. my-agents)
  4. The app is pre-configured with the topics and QoS settings needed for agent coordination

Step 3: Create Actor Tokens

Each agent in your system connects as an actor. Create at least two actors in the portal:

  1. Orchestrator - the agent that dispatches tasks and coordinates the workflow
  2. Worker - the agent that receives and completes tasks

Copy the access token for each actor. You'll use these tokens to connect.

Step 4: Connect the Orchestrator

The orchestrator dispatches tasks and listens for results:

import { NoLagAgents } from "@nolag/agents";

// Use the orchestrator actor token
const agents = new NoLagAgents(ORCHESTRATOR_TOKEN);
await agents.connect();

const room = agents.joinRoom("my-workflow");

// Dispatch a task to any worker with the "research" capability
const task = await room.handoff.dispatch({
  type: "summarize",
  payload: { url: "https://example.com/article" },
  capabilities: ["research"],
});

console.log("Dispatched task:", task.id);

// Listen for results
room.handoff.onResult((result) => {
  console.log("Task completed:", result.taskId);
  console.log("Result:", result.data);
});

Step 5: Connect a Worker

Workers register their capabilities and handle incoming tasks:

import { NoLagAgents } from "@nolag/agents";

// Use the worker actor token
const agents = new NoLagAgents(WORKER_TOKEN);
await agents.connect();

const room = agents.joinRoom("my-workflow");

// Register as a worker with capabilities
room.handoff.register({
  capabilities: ["research"],
});

// Handle incoming tasks
room.handoff.onTask(async (task) => {
  console.log("Received task:", task.type);

  // Do the work
  const summary = await summarizeUrl(task.payload.url);

  // Return the result
  await task.complete({ summary });
});

Step 6: Monitor with Observe

Use the observe pattern to watch everything that happens in your workflow:

import { NoLagAgents } from "@nolag/agents";

const agents = new NoLagAgents(MONITOR_TOKEN);
await agents.connect();

const room = agents.joinRoom("my-workflow");

// Watch all events in the workflow
room.observe.on("*", (event) => {
  console.log(`[${event.timestamp}] ${event.agent}: ${event.type}`);
  console.log("  Data:", JSON.stringify(event.data));
});

// Check who's online
const present = room.getPresence();
console.log("Online agents:", present.map(a => a.id));

Step 7: View in the Agent Dashboard

Open the Agent Dashboard in the portal to see your agents in real time. The dashboard shows connected agents, active tasks, task history, and the event stream.

Multi-Tenant Setup

If you are building a multi-tenant application where each customer needs isolated agent workflows, use Access Scopes. Scopes automatically namespace all MQTT topics - including agent coordination topics like _handoff/dispatch and _blackboard/state - under a tenant-specific slug.

This means you deploy one agents app and create scoped actors for each tenant. An orchestrator in tenant A cannot dispatch tasks to workers in tenant B. The isolation is enforced at the protocol level with zero code changes to your agent logic.

See the Multi-Tenant Patterns guide for detailed implementation examples, including per-tenant agent deployments.

Next Steps

  • Patterns - deep dive on all six coordination patterns
  • Composition - combine agents with chat, notifications, and more
  • Tag Vocabulary - learn how capability and priority tags work
  • Examples - canonical recipes for common agent workflows