Communication

Communicating Between Actors

Learn how actors can call other actors and share data

Actors can communicate with each other using the server-side actor client, enabling complex workflows and data sharing between different actor instances.

We recommend reading the clients documentation first. This guide focuses specifically on communication between actors.

Using the Server-Side Actor Client

The server-side actor client allows actors to call other actors within the same registry. Access it via c.client() in your actor context:

TypeScript

import { actor } from "@rivetkit/actor";

const orderProcessor = actor({
  state: { orders: [] },
  
  actions: {
    processOrder: async (c, order) => {
      const client = c.client<typeof registry>();
      
      // Reserve the stock
      const inventory = client.inventory.getOrCreate(["main"]);
      await inventory.reserveStock(order.quantity);
      
      // Process payment through payment actor
      const payment = client.payment.getOrCreate([order.customerId]);
      const result = await payment.processPayment(order.amount);
      
      // Update order state
      c.state.orders.push({ ...order, status: "completed", paymentResult: result });
      
      return { success: true, orderId: order.id };
    }
  }
});

Use Cases and Patterns

Actor Orchestration

Use a coordinator actor to manage complex workflows:

TypeScript

import { actor } from "@rivetkit/actor";

const workflowActor = actor({
  state: { workflows: [] },
  
  actions: {
    executeWorkflow: async (c, workflowId) => {
      const client = c.client<typeof registry>();
      
      // Step 1: Initialize data
      const dataProcessor = client.dataProcessor.getOrCreate(["main"]);
      const data = await dataProcessor.initialize(workflowId);
      
      // Step 2: Process through multiple actors
      const validator = client.validator.getOrCreate(["main"]);
      const validationResult = await validator.validate(data);
      
      // Step 3: Finalize
      const finalizer = client.finalizer.getOrCreate(["main"]);
      const result = await finalizer.finalize(validationResult);
      
      c.state.workflows.push({ workflowId, result, completedAt: Date.now() });
      return result;
    }
  }
});

Data Aggregation

Collect data from multiple actors:

TypeScript

import { actor } from "@rivetkit/actor";

const analyticsActor = actor({
  state: { reports: [] },
  
  actions: {
    generateReport: async (c, reportType) => {
      const client = c.client<typeof registry>();
      
      // Collect data from multiple sources
      const userMetrics = client.userMetrics.getOrCreate(["main"]);
      const orderMetrics = client.orderMetrics.getOrCreate(["main"]);
      const systemMetrics = client.systemMetrics.getOrCreate(["main"]);
      
      const [users, orders, system] = await Promise.all([
        userMetrics.getStats(),
        orderMetrics.getStats(),
        systemMetrics.getStats()
      ]);
      
      const report = {
        id: crypto.randomUUID(),
        type: reportType,
        data: { users, orders, system },
        generatedAt: Date.now()
      };
      
      c.state.reports.push(report);
      return report;
    }
  }
});

Event-Driven Architecture

Use connections to listen for events from other actors:

TypeScript

import { actor } from "@rivetkit/actor";

const auditLogActor = actor({
  state: { logs: [] },
  
  actions: {
    startAuditing: async (c) => {
      const client = c.client<typeof registry>();
      
      // Connect to multiple actors to listen for events
      const userActor = client.userActor.getOrCreate(["main"]).connect();
      const orderActor = client.orderActor.getOrCreate(["main"]).connect();
      
      // Listen for user events
      userActor.on("userCreated", (user) => {
        c.state.logs.push({ 
          event: "userCreated", 
          data: user, 
          timestamp: Date.now() 
        });
      });
      
      // Listen for order events
      orderActor.on("orderCompleted", (order) => {
        c.state.logs.push({ 
          event: "orderCompleted", 
          data: order, 
          timestamp: Date.now() 
        });
      });
      
      return { status: "auditing started" };
    }
  }
});

Batch Operations

Process multiple items in parallel:

TypeScript

// Process items in parallel
const results = await Promise.all(
  items.map(item => client.processor.getOrCreate([item.type]).process(item))
);