Octopus as a Server Node — Workflow vs Server Nodes

The Concept

Deploying Octopus as a server node inverts the usual relationship. Normally, Octopus calls workflows via the ProcessPlugin's start_workflow tool. As a server node, workflows call Octopus — treating the agent runtime as a shared AI service.

┌─────────────────────────────────────────────────────────┐
│             Flow Studio Workflow                         │
│                                                          │
│  [Collect Data] → [Call AI Analysis Server]             │
│                       (server group: "ai-agents")        │
│                                ↓                         │
│                   ┌──────────────────────────┐           │
│                   │  Octopus Server Node      │           │
│                   │  Agent: "data-analyst"    │           │
│                   │  Tools: SQL, Charts, ML   │           │
│                   │                          │           │
│                   │  Receives the data, uses │           │
│                   │  tools, returns analysis │           │
│                   └──────────────────────────┘           │
│                                ↓                         │
│  [Send Report] ← [Generate PDF from Analysis]            │
└─────────────────────────────────────────────────────────┘

Registering Octopus in a Server Group

When the Octopus host registers itself as a server group member, it exposes its agent chat endpoint to the group controller.

{
  "OctopusConfig": {
    "ServerGroup": {
      "Enabled":    true,
      "GroupName":  "ai-agents",
      "NodeName":   "octopus-node-01",
      "PublicBaseUrl": "https://octopus-01.internal:5000",
      "Weight":     1,
      "Metadata": {
        "tier":    "primary",
        "region":  "eastus"
      }
    }
  }
}

// Octopus server group registration in Program.cs
if (octopusConfig.ServerGroup.Enabled)
{
    var registrar = app.Services.GetRequiredService<IServerGroupRegistrar>();
    app.Lifetime.ApplicationStarted.Register(async () =>
    {
        await registrar.RegisterAsync(new ServerNodeRegistration
        {
            GroupName = octopusConfig.ServerGroup.GroupName,
            Name      = octopusConfig.ServerGroup.NodeName,
            BaseUrl   = octopusConfig.ServerGroup.PublicBaseUrl,
            HealthUrl = $"{octopusConfig.ServerGroup.PublicBaseUrl}/health",
            Weight    = octopusConfig.ServerGroup.Weight,
            Metadata  = octopusConfig.ServerGroup.Metadata
        });
    });
}

Calling Octopus from a Workflow Node

// Workflow node that calls the Octopus AI agent server group
public class AiAnalysisWorkflowNodeExecutor : BaseNodeExecutor
{
    private readonly IServerGroupClient _serverGroup;

    public AiAnalysisWorkflowNodeExecutor(IServerGroupClient serverGroup)
        => _serverGroup = serverGroup;

    public override async Task ExecuteAsync(
        INodeExecutionContext context,
        CancellationToken ct)
    {
        var dataPayload = GetInput<string>(context, "DataJson");
        var agentId     = GetInput<string>(context, "AgentId");

        // Call the Octopus server group — routes to any healthy Octopus instance
        var response = await _serverGroup.PostAsync<AgentChatResponse>(
            groupName: "ai-agents",
            endpoint:  $"/api/agents/{agentId}/chat",
            body: new AgentChatRequest
            {
                SessionId = context.CorrelationId,
                Message   = $"Analyse the following data and provide a summary:\n\n{dataPayload}",
                TenantId  = context.TenantId
            },
            ct);

        SetOutput(context, "AnalysisSummary",     response.AssistantMessage);
        SetOutput(context, "ToolCallsPerformed",  response.ToolCallCount);
        SetOutput(context, "TokensConsumed",      response.TokensUsed);
    }
}

Multi-Instance Octopus Deployment

Registering multiple Octopus instances in the same server group provides horizontal scaling for agent workloads. Each instance has its own plugin set, episode store, and LLM connection — but they all serve the same agent definitions stored in the shared SQL database.

Aspect	Single Octopus Instance	Octopus Server Group
Throughput	Limited to single host capacity	Linear scaling — add nodes to group
Availability	Single point of failure	Automatic failover to healthy nodes
Agent definitions	In shared SQL (SqlServerPlugin)	Shared — all nodes read same database
Episode history	In shared SQL	Shared — sessions resume on any node
Plugin config	Per-node appsettings.json	Must be identical across all nodes in the group
LLM connections	Per-node	Per-node — each instance has its own connection pool

Session Affinity Considerations

If an agent conversation has multiple turns, all turns must reach the same Octopus node — or the node must be able to reconstruct the session from the shared SQL database. Configure the server group with sticky session routing keyed on the session/episode ID:

{
  "ServerGroup": {
    "GroupName":     "ai-agents",
    "LoadBalancing": "StickySession",
    "StickyKey":     "X-Octopus-Session-Id"
  }
}

Stateless agents. If the SqlServerPlugin is enabled and all Octopus nodes share the same SQL database, agents are effectively stateless at the node level — any node can continue any session. In this configuration, use round-robin load balancing for better throughput.

Complete Integration Pattern

Layer	Technology	Role
Business Process	Flow Studio Workflow	Orchestrates steps, manages state, handles branching
AI Reasoning	Octopus Server Group	Provides LLM reasoning and tool use as a service
Inference	Inference Server Group	Hosts the LLM model — called by Octopus nodes
Integration	MCP Tool Server Group	External system connectors — called by Octopus agents
Data	Shared SQL (SqlServerPlugin)	Agent definitions, episodes, procedures — shared state

← Satellite Nodes Back to Overview →