Custom workflow nodes

A custom node implements workflow.Node: Type, Validate, and Execute. Embed workflow.BaseNode to supply Type.

Implement a node

This complete package defines a node that reads a name and returns a greeting:

package nodes

import (
    "context"
    "fmt"
    "github.com/hastekit/agent-sdk-go/pkg/workflow"
)

type Greeting struct { workflow.BaseNode }

func NewGreeting() *Greeting {
    return &Greeting{BaseNode: workflow.BaseNode{NodeType: "greeting"}}
}
func (*Greeting) Validate() error { return nil }
func (*Greeting) Execute(ctx context.Context, in *workflow.Input) (map[string]any, string, error) {
    if err := ctx.Err(); err != nil { return nil, "", err }
    name, ok := in.RunContext["name"].(string)
    if !ok || name == "" { return nil, "", fmt.Errorf("name is required") }
    return map[string]any{"greeting": "Hello, " + name}, workflow.DefaultPort, nil
}

Register it with graph.AddNode("greet", nodes.NewGreeting()). Validate runs during compilation and should check static configuration. Check input-dependent constraints in Execute.

Read shared state, return updates

Do not mutate Input, its maps, or nested values. Parallel nodes share that input during a wave. Return only the partial RunContext update that the walker should merge. Map values merge recursively; non-map values replace previous values. Prefer distinct output keys for independent nodes. Built-in nodes place output at RunContext["nodes"][nodeID]; custom nodes can follow that convention but are not automatically wrapped into it. Outputs, metadata, and continuation state must be serializable when you persist a checkpoint or use Temporal. Do not store database clients, function closures, or Go channels in run state.

Cancellation and errors

Pass ctx to blocking work and return promptly when it is cancelled. The local executor waits for running nodes to unwind before returning the shared state. A node that ignores cancellation can hold the run open. Return a non-nil error for failure. Return workflow.Pause(payload) for suspension. A pause is handled separately from failure and does not cancel sibling nodes in the current wave. Node implementations may run again after a failed attempt or durable retry. Make writes idempotent where required; a completed checkpoint only protects work already recorded as completed.

Getting started

Core concepts

Models and providers

Tools and capabilities

Multi-agent patterns

Interfaces

Durable execution

Scheduled work

Workflows

Testing and operations

Custom workflow nodes

Implement a node

Read shared state, return updates

Cancellation and errors

​Implement a node

​Read shared state, return updates

​Cancellation and errors

Implement a node

Read shared state, return updates

Cancellation and errors