Hyperfold AI
Back

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:

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// 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:

bash
1
2
3
4
5
6
7
8
9
10
11
12
# 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:

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// 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:

yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
# 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 }}"
Workflows automatically retry failed steps with exponential backoff. Configure max retries and dead-letter handling in your workflow definition.