Blueprint Composition

Combine the agents Blueprint with other Blueprints to build powerful real-time applications.

How Composition Works

NoLag Blueprints are independent apps within the same project. Each Blueprint manages its own topics, rooms, and QoS settings. Composition happens through cross-app actor access: a single actor can connect to multiple apps simultaneously.

For example, an actor representing a chatbot can connect to both a @nolag/chat app (for user-facing messaging) and a @nolag/agents app (for AI coordination). The actor bridges the two apps, forwarding user messages to the agent workflow and sending agent responses back to the chat.

Key concepts

• Actors are created at the project level and granted access to specific apps
• A single actor can have tokens for multiple apps
• Each app connection is independent - different rooms, topics, and QoS
• The actor code bridges the apps by listening on one and publishing on the other

Example: Agentic Chatbot

A customer support chatbot that uses @nolag/chat for the user-facing interface and @nolag/agents for the AI backend. When a user sends a message, the bot dispatches it as a task to a customer-support agent, then sends the response back to the chat room.

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

// Same actor connects to both apps
const chat = new NoLagChat(ACTOR_TOKEN_CHAT);
const agents = new NoLagAgents(ACTOR_TOKEN_AGENTS);

await Promise.all([chat.connect(), agents.connect()]);

// User-facing chat room
const chatRoom = chat.joinRoom("support");

// Agent coordination room
const agentRoom = agents.joinRoom("support-agents");

// When user sends a message, dispatch to agent workflow
chatRoom.on("message", async (msg) => {
  if (msg.sender.id !== "bot") {
    await agentRoom.handoff.dispatch({
      type: "respond",
      payload: { userMessage: msg.text, context: chatRoom.getMessages() },
      capabilities: ["customer-support"],
    });
  }
});

// When agent completes, send response back to chat
agentRoom.handoff.onResult(async (result) => {
  await chatRoom.sendMessage(result.data.response);
});

Architecture

Example: Monitored IoT Fleet

A delivery fleet that uses @nolag/track for real-time GPS tracking and @nolag/agents for intelligent monitoring. When a vehicle enters a geofence, an agent analyzes the delivery and updates shared fleet status.

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

const track = new NoLagTrack(ACTOR_TOKEN_TRACK);
const agents = new NoLagAgents(ACTOR_TOKEN_AGENTS);

await Promise.all([track.connect(), agents.connect()]);

const fleet = track.joinRoom("delivery-fleet");
const agentRoom = agents.joinRoom("fleet-monitor");

// When a vehicle enters a geofence, trigger agent analysis
fleet.on("geofence:enter", async (event) => {
  await agentRoom.handoff.dispatch({
    type: "analyze-delivery",
    payload: { vehicleId: event.vehicleId, zone: event.zone },
    capabilities: ["logistics"],
  });
});

// Agent updates shared state with fleet overview
agentRoom.handoff.onResult(async (result) => {
  await agentRoom.blackboard.update("fleet-status", (prev) => ({
    ...prev,
    [result.data.vehicleId]: result.data.status,
  }));
});

Composition Patterns

Event bridge

The simplest pattern: listen for events on one Blueprint and trigger actions on another. The chatbot example above uses this - chat messages trigger agent tasks.

Shared state sync

Use the Blackboard pattern to maintain state that's derived from events in other Blueprints. The IoT example updates fleet status based on tracking events.

Approval pipeline

Combine @nolag/agents (Approve pattern) with @nolag/notify to send approval requests as notifications. When a human approves via the notification, the agent workflow continues.

Which Blueprints compose well?