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:

import { actor } from "rivetkit";

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 };
    }
  }
});

TypeScript

Use Cases and Patterns

Actor Orchestration

Use a coordinator actor to manage complex workflows:

import { actor } from "rivetkit";

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;
    }
  }
});

TypeScript

Data Aggregation

Collect data from multiple actors:

import { actor } from "rivetkit";

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;
    }
  }
});

TypeScript

Event-Driven Architecture

Use connections to listen for events from other actors:

import { actor } from "rivetkit";

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" };
    }
  }
});

TypeScript

Batch Operations

Process multiple items in parallel:

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

TypeScript

API Reference

ActorHandle - Handle for calling other actors
Client - Client type for actor communication
ActorAccessor - Accessor for getting actor handles