CrewAI: Multi-Agent Orchestration

Executive Summary

CrewAI brings information-theoretic security to multi-agent AI systems — crew orchestration, task handoffs, and agent-to-agent communication all secured with XorIDA threshold sharing.

This package provides CrewAI-like patterns (crews, agents, tasks) with a critical security upgrade: every inter-agent payload is XorIDA-split before transmission. An attacker who compromises a single communication channel learns nothing about the task data — not computationally hard to break, but mathematically impossible.

Three core primitives cover most orchestration workflows: createCrewAgent() generates a unique DID identity for each agent. createSecureTask() encodes task descriptions, splits them into shares, and generates HMAC signatures for integrity verification. executeHandoff() transfers work between agents with HMAC-chained audit trails — every handoff links to the previous one, forming a tamper-evident execution log.

Zero configuration out of the box. Zero npm runtime dependencies. Runs anywhere the Web Crypto API is available — Node.js, Deno, Bun, Cloudflare Workers. All functions return Result<T, E> — no thrown exceptions in library code.

Developer Experience

CrewAI provides structured error handling and a simple Result pattern to make multi-agent orchestration reliable and debuggable.

Result Pattern

All functions return Result<T, E> instead of throwing exceptions. This makes error handling explicit and composable.

const crew = await createCrew({
  name: 'Research Team',
  agents: [
    { name: 'Researcher', role: 'data gathering', goal: 'find papers' },
    { name: 'Analyst', role: 'analysis', goal: 'summarize findings' },
  ],
  tasks: [
    { description: 'Find top AI papers from 2025' },
    { description: 'Summarize key findings' },
  ],
});

if (!crew.ok) {
  console.error('Crew creation failed:', crew.error);
  return;
}

// Type-safe access to value
const { agents, taskIds } = crew.value;

Error Categories

CrewAI organizes error codes across 9 categories, making systematic error handling straightforward:

The Problem

Multi-agent AI systems today transmit task data in plaintext or rely on transport-layer encryption that exposes data to every hop in the communication path.

Plaintext task handoffs leak strategy. When agents coordinate via unencrypted APIs or message queues, any middleware component can observe the full execution plan — task descriptions, intermediate results, agent assignments.

Transport-layer encryption isn't end-to-end. TLS protects data in transit but decrypts at every load balancer, API gateway, and logging proxy. A single compromised component exposes the entire multi-agent conversation.

No tamper evidence. Traditional orchestrators have no cryptographic proof that tasks weren't modified mid-flight. An attacker who intercepts a handoff can alter the payload, change the task description, or redirect work to a different agent — silently.

No agent accountability. Without cryptographic identity, there's no way to prove which agent performed which task. Audit logs can be forged. DIDs provide non-repudiation — an Ed25519 signature proves the agent existed and participated.

The Old Way

The New Way

Real-World Use Cases

Six scenarios where CrewAI's information-theoretic security protects multi-agent AI systems.

Architecture

Four composable modules. Each can be used independently or combined through the high-level crew orchestration API.

Security Model

CrewAI provides information-theoretic security via XorIDA threshold sharing, tamper-evident HMAC-chained handoffs, and DID-based non-repudiation.

XorIDA Threshold Sharing

Every task payload is XOR-split into n shares using XorIDA (threshold sharing over GF(2)). An attacker who compromises fewer than all shares learns nothing about the plaintext — not computationally hard to break, but mathematically impossible. This is information-theoretic security, stronger than AES-256.

HMAC Before Reconstruction

HMAC-SHA256 verification completes before any plaintext is returned. If the HMAC check fails, the share data is rejected and no plaintext is exposed. This prevents timing attacks and ensures tampered data never reaches the application layer.

HMAC-Chained Handoffs

Each handoff entry includes an HMAC covering (fromDid, toDid, taskId, timestamp, previousHmac). The chain is tamper-evident — modifying any entry invalidates all subsequent entries. This creates a cryptographic audit trail that proves the execution sequence.

DID Identity

Every agent receives a unique did:key identifier derived from a 32-byte random public key with the Ed25519 multicodec prefix (0xed01) and base58btc encoding. This provides:

• Non-repudiation: An agent's participation is cryptographically provable
• Unique identity: Each agent is distinguishable, preventing impersonation
• Decentralized trust: No central authority required — DIDs are self-sovereign

No Math.random()

All random values generated via crypto.getRandomValues(). No use of Math.random() anywhere in the codebase — cryptographic operations require cryptographically secure randomness.

Integration

Five lines to create a secure crew. Ten lines to execute a complete handoff chain with tamper-evident audit.

Installation

pnpm add @privateme/crewai

Basic Example

import {
  createCrew,
  executeHandoff,
  reconstructTaskOutput,
  verifyHandoffChain,
} from '@privateme/crewai';

// 1. Create a crew
const crew = await createCrew({
  name: 'Research Team',
  agents: [
    { name: 'Researcher', role: 'data gathering', goal: 'find papers' },
    { name: 'Analyst', role: 'analysis', goal: 'summarize findings' },
  ],
  tasks: [
    { description: 'Find top AI papers from 2025' },
  ],
  n: 3,  // 3 shares
  k: 2,  // 2-of-3 threshold
});

if (!crew.ok) throw new Error(crew.error);
const [researcher, analyst] = crew.value.agents;
const taskId = crew.value.taskIds[0]!;

// 2. Execute handoff (Researcher → Analyst)
const handoff = await executeHandoff(
  researcher!, analyst!, taskId,
  'Found 3 papers on LLM safety...',
);

if (!handoff.ok) throw new Error(handoff.error);

// 3. Verify the handoff chain
const valid = await verifyHandoffChain([handoff.value.handoff]);
if (!valid.ok || !valid.value) {
  throw new Error('Handoff chain tampered!');
}

// 4. Reconstruct the payload
const { shares, hmacKey, hmacSignature } = handoff.value;
const result = await reconstructTaskOutput(
  shares, shares.map((_, i) => i), hmacKey, hmacSignature,
);

if (!result.ok) throw new Error(result.error);
console.log(result.value);  // 'Found 3 papers on LLM safety...'

Advanced: Multi-Step Handoff Chain

// Create 3-agent crew: Researcher → Analyst → Writer
const crew = await createCrew({
  name: 'Content Production',
  agents: [
    { name: 'Researcher', role: 'research', goal: 'gather data' },
    { name: 'Analyst', role: 'analysis', goal: 'synthesize' },
    { name: 'Writer', role: 'writing', goal: 'draft article' },
  ],
  tasks: [{ description: 'AI safety trends 2025' }],
});

if (!crew.ok) throw new Error(crew.error);
const [researcher, analyst, writer] = crew.value.agents;
const taskId = crew.value.taskIds[0]!;

// Handoff 1: Researcher → Analyst
const h1 = await executeHandoff(
  researcher!, analyst!, taskId, 'Data: 15 papers, 4 trends...',
);
if (!h1.ok) throw new Error(h1.error);

// Handoff 2: Analyst → Writer (HMAC chains to h1)
const h2 = await executeHandoff(
  analyst!, writer!, taskId,
  'Synthesis: Safety-capability tradeoff is key theme...',
  h1.value.handoff.hmac,  // ← Chains to previous HMAC
);
if (!h2.ok) throw new Error(h2.error);

// Verify the entire chain
const chainValid = await verifyHandoffChain([
  h1.value.handoff,
  h2.value.handoff,
]);

if (!chainValid.ok || !chainValid.value) {
  throw new Error('Chain broken — handoff tampered!');
}

console.log('✓ Handoff chain verified');

Benchmarks

Performance characteristics measured on Node.js 22, Apple M2.

Honest Limitations

CrewAI is designed for secure multi-agent orchestration, not as a drop-in replacement for traditional workflow engines.

1. No Built-In Execution Runtime

CrewAI provides orchestration primitives (agent identity, task splitting, handoff chains), not an execution runtime. You must implement agent logic, task execution, and transport yourself. This package handles the cryptographic security layer — your code handles the workflow logic.

2. HMAC Chain Requires Sequential Validation

Handoff chain verification is O(n) — each entry's HMAC must be computed in sequence. For very long chains (hundreds of handoffs), this can add milliseconds of latency. If you need constant-time verification, consider using Merkle trees instead of HMAC chains.

3. No Agent Revocation

Once an agent is created, there's no built-in mechanism to revoke its DID or prevent it from participating in future handoffs. If an agent is compromised, you must implement revocation logic at the application layer (e.g., deny-list in your orchestrator).

4. XorIDA Requires All Shares for Reconstruction

The current implementation uses XOR-based splitting, which requires all n shares for reconstruction (k=n). True k-of-n threshold schemes (where k < n) require Shamir's Secret Sharing, which is 500-2000x slower. We optimized for speed at the cost of fault tolerance. If you need k < n, use a different threshold scheme.

5. No Transport Layer

CrewAI does not include transport adapters — it's your responsibility to transmit shares between agents. For network-based multi-agent systems, combine this package with @private.me/agent-sdk (Xlink) for encrypted transport, or implement your own message-passing layer.

6. DID Derivation is Deterministic

Agent DIDs are derived from a random 32-byte public key. If you need deterministic identity (e.g., derive the same DID from a seed on multiple devices), you must implement Agent.fromSeed() separately — this package only provides random key generation.

vs. Traditional Multi-Agent Frameworks

How CrewAI compares to AutoGen, LangGraph, and traditional orchestrators.

Handoff Chain Mechanics

How HMAC-chained handoffs provide tamper-evident audit trails for multi-agent workflows.

Handoff Entry Structure

interface HandoffEntry {
  readonly fromDid: string;        // Sending agent DID
  readonly toDid: string;          // Receiving agent DID
  readonly taskId: string;         // Task identifier
  readonly timestamp: number;       // Unix timestamp (ms)
  readonly hmac: string;           // HMAC-SHA256 signature (hex)
  readonly previousHmac?: string;  // Optional chain link
}

HMAC Computation

Each handoff's HMAC covers the concatenation of:

input = fromDid + toDid + taskId + timestamp + (previousHmac || '')
hmac  = HMAC-SHA256(hmacKey, input)

Chain Verification

To verify a handoff chain:

1. For each entry i, recompute its HMAC from (fromDid, toDid, taskId, timestamp, previousHmac)
2. Compare the recomputed HMAC to the stored HMAC — if they don't match, the entry was tampered with
3. If i > 0, verify that entry[i].previousHmac === entry[i-1].hmac — if they don't match, the chain was broken

Full API Surface

Complete function signatures and return types.

Error Taxonomy

Complete list of error codes and when they occur.

Codebase Statistics

Package structure and test coverage.

Package Structure

packages/crewai/
  src/
    index.ts          # Public API barrel exports
    types.ts          # All type definitions
    crew.ts           # Core orchestration logic
    crypto.ts         # XorIDA, HMAC, DID, base58btc
    errors.ts         # Error codes and messages
    __tests__/
      crewai.test.ts  # Comprehensive test suite (35 tests)
  package.json
  tsconfig.json
  vitest.config.ts
  README.md

Related Packages