orchestrator

Purpose

This skill handles multi-instance delegation in distributed systems, routing tasks to instances A-H, managing fanout and aggregation of responses, spawning/sending sessions, and performing health checks. It's designed for coordinating complex workflows across distributed-comms clusters.

When to Use

Use this skill for scenarios involving multiple instances, such as load balancing requests across A-H, aggregating data from distributed nodes, managing long-running sessions, or ensuring instance health in fault-tolerant systems. Apply it when single-instance processing isn't sufficient, like in scalable web services or parallel computations.

Key Capabilities

• Routing: Direct tasks to specific instances (e.g., A-H) using targeted delegation.
• Fanout/Aggregation: Broadcast requests to multiple instances and collect/aggregate responses, supporting operations like parallel queries.
• Session Management: Spawn new sessions with sessions_spawn and send data via sessions_send, enabling stateful interactions.
• Health Checks: Periodically verify instance status with endpoints like /api/health/check, returning JSON with status codes (e.g., 200 for healthy).
• Error Resilience: Automatically retry failed delegations up to 3 times based on configurable thresholds.

Usage Patterns

• Simple Routing: Route a task to instance A by specifying the target; use for directed workflows.
• Fanout and Aggregate: Send a request to instances A-C, then aggregate results; ideal for distributed searches.
• Session-Based Workflows: Spawn a session, send data, and monitor health; use for multi-step processes.
• Health Monitoring Loop: Integrate into scripts to check instances every 60 seconds and reroute if needed. Always set the environment variable $ORCHESTRATOR_API_KEY for authenticated operations.

Common Commands/API

• CLI Commands:
  • Route to instances: openclaw orchestrator route --instances A B --payload '{"data": "task"}'
  • Fanout and aggregate: openclaw orchestrator fanout --targets A-H --aggregate true --timeout 10s
  • Spawn and send session: openclaw orchestrator sessions_spawn --id session1; openclaw orchestrator sessions_send --id session1 --data '{"key": "value"}'
  • Health check: openclaw orchestrator health --instances A-H --output json
• API Endpoints:
  • POST /api/orchestrator/route: Body: {"instances": ["A", "B"], "payload": {"data": "task"}}, Headers: Authorization: Bearer $ORCHESTRATOR_API_KEY
  • POST /api/orchestrator/fanout: Body: {"targets": ["A", "C"], "aggregate": true}, Returns aggregated JSON array.
  • POST /api/orchestrator/sessions/spawn: Body: {"sessionId": "session1"}, Response: session token.
  • GET /api/orchestrator/health: Query: ?instances=A-H, Returns: {"A": "healthy", "B": "down"}.
• Code Snippets:

  import requests
  headers = {'Authorization': f'Bearer {os.environ["ORCHESTRATOR_API_KEY"]}'}
  response = requests.post('http://api.openclaw/orchestrator/route', json={'instances': ['A'], 'payload': {'data': 'task'}}, headers=headers)
  

  export ORCHESTRATOR_API_KEY=your_key_here
  openclaw orchestrator fanout --targets A-H --aggregate true > output.json
  

• Config Formats: Use JSON for payloads, e.g., {"instances": ["A"], "timeout": 5}; store in files like config.json and pass via --config config.json.

Integration Notes

Integrate by setting $ORCHESTRATOR_API_KEY in your environment before running commands. For distributed-comms clusters, ensure the skill is registered via the cluster's API (e.g., POST /api/cluster/register with body {"skillId": "orchestrator"}). Use SDK wrappers for languages like Python; install via pip install openclaw-sdk. When embedding, include the hint string in metadata: orchestrate delegate multi-instance session spawn send fanout aggregate instances. Test integrations in a sandbox environment to verify routing and session persistence.

Error Handling

• Common Errors:
  • Authentication failures (e.g., 401 Unauthorized): Check if $ORCHESTRATOR_API_KEY is set and valid; retry once after verifying.
  • Instance unreachable (e.g., 503 Service Unavailable): Use --retry 3 in CLI or handle in code with exponential backoff.
  • Aggregation timeouts: Set --timeout 10s and catch errors with try/except in scripts.
• Prescriptive Steps:
  • For routing errors: Parse response JSON for error codes (e.g., "instance_down") and fallback to healthy instances.
  • In code:

    try:
        response = requests.post(url, headers=headers)
        response.raise_for_status()
    except requests.exceptions.HTTPError as e:
        print(f"Error: {e} - Retrying...")
        # Implement retry logic here
    

  • Always log errors with timestamps and instance details for debugging.

Graph Relationships

• Related to: distributed-comms cluster (parent), sessions skill (dependency for session management), multi-instance skills (peers for delegation).
• Dependencies: Requires health-checks module for instance monitoring.
• Connections: Integrates with delegation tags for routing; aggregates with fanout operations in distributed-comms.