Reactive derived state across agents and a shared scratchpad for coordination.

Cross-agent state lets you compute values from the combined state of all agents and share mutable state through a scratchpad – both integrated with the debug timeline.

Cross-Agent Derivations

Define derived values that react to changes across any registered agent's state:

import { createMultiAgentOrchestrator } from '@directive-run/ai';

const orchestrator = createMultiAgentOrchestrator({
  runner,
  agents: {
    researcher: { agent: researcher },
    writer: { agent: writer },
    reviewer: { agent: reviewer },
  },

  derive: {
    totalTokens: (snapshot) => {
      let sum = 0;
      for (const [, agentState] of Object.entries(snapshot.agents)) {
        sum += agentState.totalTokens ?? 0;
      }

      return sum;
    },

    allIdle: (snapshot) =>
      Object.values(snapshot.agents).every(
        (s) => s.status === 'idle' || s.status === 'completed'
      ),

    progress: (snapshot) => {
      const agents = Object.values(snapshot.agents);
      const completed = agents.filter((s) => s.status === 'completed').length;

      return `${completed}/${agents.length} agents done`;
    },
  },
});

Reading Derived Values

// Read all derived values (frozen record)
const derived = orchestrator.derived;
console.log(derived.totalTokens);
console.log(derived.allIdle);
console.log(derived.progress);

Subscribing to Changes

const unsubscribe = orchestrator.onDerivedChange((id, value) => {
  console.log(`Derivation ${id} changed to:`, value);
});

// Later
unsubscribe();

CrossAgentSnapshot

The snapshot passed to derivation functions contains:

interface CrossAgentSnapshot {
  agents: Record<string, AgentState>;            // All agent states
  coordinator: { globalTokens: number; status: string };  // Coordinator facts
  scratchpad?: Record<string, unknown>;          // Current scratchpad state
}

Timeline Integration

Derivation changes emit derivation_update events on the debug timeline, recording which derivation changed and its new value.

Shared Scratchpad

A key-value store shared across all agents for mutable coordination state:

const orchestrator = createMultiAgentOrchestrator({
  runner,
  agents: { /* ... */ },

  scratchpad: {
    init: {
      taskList: [],
      completedCount: 0,
      lastUpdate: null,
    },
  },
});

Reading and Writing

const pad = orchestrator.scratchpad!;

// Basic operations
pad.set('taskList', ['research', 'write', 'review']);
pad.get('taskList');      // ['research', 'write', 'review']
pad.has('taskList');       // true
pad.delete('lastUpdate');

// Batch update (merges into scratchpad)
pad.update({ completedCount: 1 });

// Read all values
const all = pad.getAll();
// { taskList: [...], completedCount: 1 }

// Reset to initial values
pad.reset();

Subscribing to Changes

// Subscribe to specific keys
const unsub = pad.subscribe(['completedCount', 'taskList'], (key, value) => {
  console.log(`Scratchpad: ${String(key)} =`, value);
});

// Subscribe to all changes
const unsub2 = pad.onChange((key, value) => {
  console.log(`Changed: ${key} =`, value);
});

Scratchpad API

Method	Returns	Description
`get(key)`	`T`	Read a value
`set(key, value)`	`void`	Write a value
`has(key)`	`boolean`	Check if key exists
`delete(key)`	`void`	Remove a key
`update(values)`	`void`	Merge partial values into scratchpad
`getAll()`	`T`	Read all values
`subscribe(keys, cb)`	`() => void`	Subscribe to specific key changes
`onChange(cb)`	`() => void`	Subscribe to all changes
`reset()`	`void`	Reset to initial values

Timeline Integration

Scratchpad mutations emit scratchpad_update events on the debug timeline with the key and new value.

Reactive Agent Triggering

Combine derivations with derivedConstraint to trigger agent runs when derived state changes:

import { derivedConstraint } from '@directive-run/ai';

const orchestrator = createMultiAgentOrchestrator({
  runner,
  agents: {
    researcher: { agent: researcher },
    writer: { agent: writer },
    optimizer: { agent: optimizer },
  },

  derive: {
    totalCost: (snapshot) => {
      let sum = 0;
      for (const [, s] of Object.entries(snapshot.agents)) {
        sum += s.totalTokens ?? 0;
      }

      return sum * 0.00001;  // Estimated cost
    },
  },

  constraints: {
    costAlert: derivedConstraint(
      'totalCost',
      (value) => (value as number) > 0.50,
      {
        agent: 'optimizer',
        input: (value) => `Reduce token usage – current cost: $${value}`,
        priority: 100,
      }
    ),
  },
});

When totalCost crosses $0.50, the optimizer agent is automatically triggered.

Next Steps

Multi-Agent Orchestrator – Setup and configuration
Execution Patterns – Coordinating agent execution
Communication – Agent-to-agent messaging
DevTools – Visualize state in the DevTools UI

Cross-Agent State

Cross-Agent Derivations

Reading Derived Values

Subscribing to Changes

CrossAgentSnapshot

Timeline Integration

Shared Scratchpad

Reading and Writing

Subscribing to Changes

Scratchpad API

Timeline Integration

Reactive Agent Triggering

Next Steps

Stay in the loop. Sign up for our newsletter.