---
title: Blueprint Composition for Agents
description: How to compose the agents Blueprint with chat, notify, track, and other Blueprints via cross-app actor access.
---

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

```typescript [TypeScript]
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

| Component | Blueprint | Role |
| --- | --- | --- |
| Chat UI | `@nolag/chat` | User-facing chat rooms with presence and typing |
| Bot bridge | Both | Listens to chat, dispatches to agents, sends responses |
| AI workers | `@nolag/agents` | Process user queries with LLM, return responses |

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

```typescript [TypeScript]
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?

| Combination | Use case |
| --- | --- |
| Agents + Chat | Agentic chatbots, AI-assisted customer support |
| Agents + Notify | Agent-triggered notifications, approval requests |
| Agents + Track | Intelligent fleet monitoring, autonomous logistics |
| Agents + Dash | AI-powered dashboards, automated reporting |
| Agents + IoT | Autonomous device management, predictive maintenance |