---
title: Getting Started with AI Agents
description: Step-by-step guide to building your first multi-agent workflow with @nolag/agents.
---

# Getting Started with AI Agents

Build your first multi-agent workflow in minutes.

## Prerequisites

- A NoLag account ([free tier available](/pricing))
- A project with an agents app created in the [portal](/docs/agents/getting-started)
- Node.js 18+ (JavaScript) or Python 3.10+ (Python)

## Step 1: Install

```bash [npm]
npm install @nolag/agents @nolag/js-sdk
```
```bash [pip]
pip install nolag-agents
```

The agents SDK is available for **JavaScript/TypeScript** (`@nolag/agents`) and **Python** (`nolag-agents`). Both provide the same six coordination patterns.

## 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:

```typescript [TypeScript]
import { NoLagAgents, Handoff } from "@nolag/agents";

const agents = new NoLagAgents(ORCHESTRATOR_TOKEN, {
  appName: "my-agents",
  presence: { name: "orchestrator", role: "orchestrator", capabilities: ["dispatch"] },
});
await agents.connect();

const room = agents.room("default-workflow");
const handoff = new Handoff(room);

// Dispatch a task to any worker with the "summarize" capability
const result = await handoff.dispatch("summarize",
  { url: "https://example.com/article" },
  { waitForResult: true, timeout: 30000 }
);

console.log("Result:", result.payload);
```
```python [Python]
from nolag_agents import NoLagAgents, NoLagAgentsOptions, AgentPresenceData
from nolag_agents.patterns import Handoff

agents = NoLagAgents(ORCHESTRATOR_TOKEN, NoLagAgentsOptions(
    app_name="my-agents",
    presence=AgentPresenceData(name="orchestrator", role="orchestrator", capabilities=["dispatch"]),
))
await agents.connect()

room = await agents.room("default-workflow")
handoff = Handoff(room)

# Dispatch a task to any worker with the "summarize" capability
result = await handoff.dispatch("summarize",
    {"url": "https://example.com/article"},
    wait_for_result=True, timeout=30000,
)

print("Result:", result.payload)
```

## Step 5: Connect a Worker

Workers register their capabilities and handle incoming tasks:

```typescript [TypeScript]
import { NoLagAgents, Handoff } from "@nolag/agents";

const agents = new NoLagAgents(WORKER_TOKEN, {
  appName: "my-agents",
  presence: { name: "worker-1", role: "agent", capabilities: ["summarize"] },
});
await agents.connect();

const room = agents.room("default-workflow");
const handoff = new Handoff(room);

// Handle incoming tasks filtered by capability
handoff.onTask(["summarize"], async (task, respond) => {
  console.log("Received task:", task.capability);

  const summary = await summarizeUrl(task.payload.url);
  respond("success", { summary });
});
```
```python [Python]
from nolag_agents import NoLagAgents, NoLagAgentsOptions, AgentPresenceData
from nolag_agents.patterns import Handoff

agents = NoLagAgents(WORKER_TOKEN, NoLagAgentsOptions(
    app_name="my-agents",
    load_balance=True,  # Share tasks with other workers
    presence=AgentPresenceData(name="worker-1", role="agent", capabilities=["summarize"]),
))
await agents.connect()

room = await agents.room("default-workflow")
handoff = Handoff(room)

# Handle incoming tasks filtered by capability
def handle_task(task, respond):
    print("Received task:", task.capability)
    summary = summarize_url(task.payload["url"])
    asyncio.ensure_future(respond("success", {"summary": summary}))

handoff.on_task(["summarize"], handle_task)
```

## Step 6: Monitor with Observe

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

```typescript [TypeScript]
import { NoLagAgents, Observe } from "@nolag/agents";

const agents = new NoLagAgents(MONITOR_TOKEN, { appName: "my-agents" });
await agents.connect();

const room = agents.room("default-workflow");
const observe = new Observe(room, "monitor");

// Watch all events in the workflow
observe.on((event) => {
  console.log(`[${event.category}] ${event.severity}: ${JSON.stringify(event.payload)}`);
});
```
```python [Python]
from nolag_agents import NoLagAgents, NoLagAgentsOptions
from nolag_agents.patterns import Observe

agents = NoLagAgents(MONITOR_TOKEN, NoLagAgentsOptions(app_name="my-agents"))
await agents.connect()

room = await agents.room("default-workflow")
observe = Observe(room, "monitor")

# Watch all events in the workflow
observe.on(lambda event: print(f"[{event.category}] {event.severity}: {event.payload}"))
```

## 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](/docs/scopes/getting-started). 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](/docs/scopes/multi-tenancy) guide for detailed implementation examples, including per-tenant agent deployments.

## Next Steps

- [Patterns](/docs/agents/patterns) - deep dive on all six coordination patterns
- [Composition](/docs/agents/composition) - combine agents with chat, notifications, and more
- [Tag Vocabulary](/docs/agents/tags) - learn how capability and priority tags work
- [Examples](/docs/agents/examples) - canonical recipes for common agent workflows