Hyperfold AI

Dec 15, 2025

Multi-Agent Workflows

H
Hyperfold Team
AgentsWorkflows

Workflow Design

Multi-agent workflows orchestrate complex commerce operations across specialized agents. Each agent handles its domain while communicating via events.

A typical order flow involves:

  • Negotiator: Handles discovery, negotiation, checkout
  • Order Agent: Validates orders, processes payments
  • Fulfillment Agent: Creates shipments, generates labels
  • Recommender: Suggests products during negotiation

Agent Communication

Agents communicate asynchronously through Cloud Pub/Sub:

// Agent-to-agent communication via Pub/Sub
import { PubSub } from '@google-cloud/pubsub';

const pubsub = new PubSub();

// Negotiator publishes order created event
async function publishOrderCreated(order: Order) {
const topic = pubsub.topic('order-events');

await topic.publishMessage({
  data: Buffer.from(JSON.stringify({
    type: 'order.created',
    order_id: order.id,
    items: order.items,
    customer_id: order.customer_id,
    timestamp: new Date().toISOString(),
  })),
  attributes: {
    source: 'negotiator-agent',
    priority: 'high',
  },
});
}

// Fulfillment agent subscribes to orders
@OnEvent('order.created')
async handleNewOrder(event: OrderCreatedEvent) {
const { order_id, items } = event;

// Process the order
const shipment = await this.createShipment(order_id, items);

// Publish fulfillment created
await this.publish('fulfillment.created', {
  order_id,
  tracking_number: shipment.tracking,
});
}

Pub/Sub Integration

Configure event topics for your workflow:

# Create event topics
$ hyperfold workflows topics create

Creating topics:
✓ order-events
✓ fulfillment-events
✓ inventory-events
✓ notification-events

# Subscribe agents to topics
$ hyperfold agents subscribe fulfillment-agent order-events
$ hyperfold agents subscribe order-agent fulfillment-events

State Management

Workflow state is persisted in Firestore, enabling recovery from failures:

// Workflow state structure
interface WorkflowState {
workflow_id: string;
name: string;
status: 'running' | 'completed' | 'failed';
current_step: string;
steps: {
  [stepName: string]: {
    status: 'pending' | 'running' | 'completed' | 'failed';
    input: any;
    output?: any;
    error?: string;
    started_at?: string;
    completed_at?: string;
  };
};
context: Record<string, any>;
}

Error Handling

Define error handling and retry policies:

# workflow-order-to-delivery.yaml
name: order-to-delivery
version: "1.0"
description: Complete order processing workflow

triggers:
- event: order.created
  source: negotiator-agent

steps:
- name: validate-order
  agent: order-agent
  action: validate
  input:
    order_id: "{{ trigger.order_id }}"
  on_success: process-payment
  on_failure: notify-error

- name: process-payment
  agent: order-agent
  action: capturePayment
  input:
    order_id: "{{ trigger.order_id }}"
  on_success: create-fulfillment
  on_failure: notify-payment-failed

- name: create-fulfillment
  agent: fulfillment-agent
  action: createShipment
  input:
    order_id: "{{ trigger.order_id }}"
    items: "{{ steps.validate-order.output.items }}"
  on_success: send-confirmation

- name: send-confirmation
  agent: order-agent
  action: sendConfirmation
  input:
    order_id: "{{ trigger.order_id }}"
    tracking: "{{ steps.create-fulfillment.output.tracking_number }}"