Chains API

Create and manage Agent Chains — unified swarms that pool computing power from up to 100 Clouds with AI agents.

What are Agent Chains? Agent Chains combine multiple Clouds with agents into one unified swarm. Instead of running agents separately, you pool their computing power and capabilities into a single, more powerful system. One agent = one brain. Agent Chain = 100 brains working together.

// Endpoints Overview

Method	Endpoint	Description
`GET`	`/v1/chains`	List all chains
`POST`	`/v1/chains`	Create a new chain
`GET`	`/v1/chains/:id`	Get chain details
`PATCH`	`/v1/chains/:id`	Update chain configuration
`DELETE`	`/v1/chains/:id`	Delete a chain
`POST`	`/v1/chains/:id/invoke`	Execute the chain
`GET`	`/v1/chains/:id/executions`	List chain executions
`GET`	`/v1/chains/:id/executions/:exec_id`	Get execution details

// The Chain Object

{
  "id": "chain_abc123xyz",
  "name": "production-swarm",
  "display_name": "Production Swarm",
  "description": "Unified swarm of 20 agents for high-performance processing",
  "status": "active",
  "created_at": "2024-01-10T08:00:00Z",
  "updated_at": "2024-01-15T14:30:00Z",

  "clouds": [
    {
      "cloud_id": "cloud_001",
      "name": "us-east-node-1",
      "agents_count": 5,
      "status": "connected"
    },
    {
      "cloud_id": "cloud_002",
      "name": "us-east-node-2",
      "agents_count": 5,
      "status": "connected"
    },
    {
      "cloud_id": "cloud_003",
      "name": "eu-west-node-1",
      "agents_count": 10,
      "status": "connected"
    }
  ],

  "total_agents": 20,

  "resources": {
    "total_cpu": 80,
    "total_memory_gb": 160,
    "available_cpu": 45,
    "available_memory_gb": 92
  },

  "load_balancing": {
    "strategy": "round_robin",
    "health_check_interval": 30
  },

  "metrics": {
    "requests_24h": 125847,
    "success_rate": 99.8,
    "avg_latency_ms": 45
  }
}

// Create Chain

POST/v1/chains

Create a new chain by specifying which Clouds to combine into a unified swarm.

curl -X POST https://api.shellhub.app/v1/chains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-swarm",
    "display_name": "Production Swarm",
    "cloud_ids": [
      "cloud_001",
      "cloud_002",
      "cloud_003"
    ],
    "load_balancing": {
      "strategy": "round_robin"
    },
    "settings": {
      "auto_failover": true,
      "health_check_interval": 30
    }
  }'

Response

{
  "success": true,
  "data": {
    "id": "chain_new123",
    "name": "production-swarm",
    "status": "activating",
    "total_agents": 20,
    "clouds_count": 3,
    "created_at": "2024-01-15T15:00:00Z"
  }
}

// Add Cloud to Chain

POST/v1/chains/:id/clouds

Dynamically add more Clouds to increase your swarm's computing power.

curl -X POST https://api.shellhub.app/v1/chains/chain_abc123/clouds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cloud_id": "cloud_004"
  }'

Remove Cloud

DELETE/v1/chains/:id/clouds/:cloud_id

curl -X DELETE https://api.shellhub.app/v1/chains/chain_abc123/clouds/cloud_004 \
  -H "Authorization: Bearer YOUR_API_KEY"

// Get Chain Metrics

GET/v1/chains/:id/metrics

Get real-time metrics for your swarm's combined computing power.

{
  "success": true,
  "data": {
    "chain_id": "chain_abc123",
    "period": "24h",

    "resources": {
      "total_cpu": 80,
      "total_memory_gb": 160,
      "cpu_utilization": 45.2,
      "memory_utilization": 62.5
    },

    "performance": {
      "requests_total": 125847,
      "requests_per_second": 1.45,
      "success_rate": 99.8,
      "avg_latency_ms": 45
    },

    "clouds": [
      {"cloud_id": "cloud_001", "status": "healthy", "load": 42.1},
      {"cloud_id": "cloud_002", "status": "healthy", "load": 48.3},
      {"cloud_id": "cloud_003", "status": "healthy", "load": 45.0}
    ],

    "agents": {
      "total": 20,
      "running": 20,
      "failed": 0
    }
  }
}

// Load Balancing Strategies

Configure how requests are distributed across your swarm.

Round Robin

Distribute requests evenly across all agents in rotation.

"strategy": "round_robin"

Least Connections

Route to the agent with the fewest active connections.

"strategy": "least_connections"

Weighted

Distribute based on Cloud capacity. Higher-tier Clouds receive more requests.

"strategy": "weighted"

Geo-Proximity

Route to the nearest Cloud based on request origin for lowest latency.

"strategy": "geo_proximity"

// SDK Examples

Python

from shellhub import ShellHub

client = ShellHub(api_key="...")

# Invoke chain
result = client.chains.invoke(
    chain_id="chain_abc123",
    input={"document_url": "https://..."}
)

print(result.output)

Node.js

import { ShellHub } from '@shellhub/sdk';

const client = new ShellHub({ apiKey: '...' });

const result = await client.chains.invoke('chain_abc123', {
  input: { document_url: 'https://...' }
});

console.log(result.output);