Go SDK

The Go SDK provides native Go support for building AI workflow agents with full type safety and high performance.

Installation

go get github.com/duragraph/duragraph-go

Quick Start

1. Define Your State

State flows through the graph as nodes process it. Define your state as a Go struct:

type ChatState struct {
    Messages []string `json:"messages"`
    Result   string   `json:"result,omitempty"`
}

2. Create Nodes

Nodes implement the graph.Node interface:

import (
    "context"
    "github.com/duragraph/duragraph-go/graph"
    "github.com/duragraph/duragraph-go/llm"
    "github.com/duragraph/duragraph-go/llm/openai"
)

type ThinkNode struct {
    llm llm.Provider
}

func (n *ThinkNode) Execute(ctx context.Context, state *ChatState) (*ChatState, error) {
    messages := make([]llm.Message, len(state.Messages))
    for i, m := range state.Messages {
        messages[i] = llm.Message{Role: "user", Content: m}
    }

    resp, err := n.llm.Complete(ctx, messages)
    if err != nil {
        return nil, err
    }

    state.Result = resp.Content
    return state, nil
}

3. Build the Graph

Connect nodes with edges:

func NewChatAgent() *graph.Graph[*ChatState] {
    g := graph.New[*ChatState]("chat_agent")

    // Add nodes
    g.AddNode("think", &ThinkNode{llm: openai.New()})
    g.AddNode("respond", &RespondNode{})

    // Connect with edges
    g.AddEdge("think", "respond")

    // Set entry point
    g.SetEntrypoint("think")

    return g
}

func main() {
    g := NewChatAgent()

    result, err := g.Run(context.Background(), &ChatState{
        Messages: []string{"Hello, how can I help you today?"},
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.Result)

}

import "github.com/duragraph/duragraph-go/worker"

func main() {
    g := NewChatAgent()

    w := worker.New(g,
        worker.WithControlPlane("http://localhost:8081"),
        worker.WithConcurrency(10),
    )

    ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
    defer cancel()

    if err := w.Start(ctx); err != nil {
        log.Fatal(err)
    }
}

Conditional Routing

For dynamic branching, implement the Router interface:

type DecisionNode struct{}

func (n *DecisionNode) Execute(ctx context.Context, state *ChatState) (*ChatState, error) {
    // Analyze state and prepare for routing decision
    return state, nil
}

func (n *DecisionNode) Route(ctx context.Context, state *ChatState) (string, error) {
    if needsSearch(state) {
        return "search", nil
    }
    return "respond", nil
}

LLM Providers

The SDK supports multiple LLM providers:

import "github.com/duragraph/duragraph-go/llm/openai"

client := openai.New() // Uses OPENAI_API_KEY env var

resp, err := client.Complete(ctx, messages,
llm.WithModel("gpt-4o-mini"),
llm.WithTemperature(0.7),
)

import "github.com/duragraph/duragraph-go/llm/anthropic"

client := anthropic.New() // Uses ANTHROPIC_API_KEY env var

resp, err := client.Complete(ctx, messages,
    llm.WithModel("claude-3-sonnet-20240229"),
)

import "github.com/duragraph/duragraph-go/llm/ollama"

client := ollama.New(ollama.WithHost("http://localhost:11434"))

resp, err := client.Complete(ctx, messages,
llm.WithModel("llama3"),
)

Tool Calling

Define tools for the LLM to call:

tools := []llm.Tool{
    {
        Name:        "search",
        Description: "Search the web for information",
        Parameters: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "query": map[string]any{
                    "type":        "string",
                    "description": "The search query",
                },
            },
            "required": []string{"query"},
        },
    },
}

resp, err := client.Complete(ctx, messages, llm.WithTools(tools))

// Handle tool calls
for _, call := range resp.ToolCalls {
    switch call.Name {
    case "search":
        query := call.Arguments["query"].(string)
        result := performSearch(query)
        // Add tool result to messages and continue
    }
}

Worker Configuration

Configure workers for production deployment:

w := worker.New(g,
    worker.WithControlPlane("http://localhost:8081"),
    worker.WithConcurrency(10),              // Process 10 runs concurrently
    worker.WithPollInterval(time.Second),    // Poll every second
    worker.WithAPIKey(os.Getenv("API_KEY")), // Authenticate with control plane
)

Error Handling

Errors in nodes stop graph execution:

func (n *MyNode) Execute(ctx context.Context, state *State) (*State, error) {
    result, err := doSomething()
    if err != nil {
        // Wrap with context for debugging
        return nil, fmt.Errorf("MyNode failed: %w", err)
    }
    return state, nil
}

API Reference

Full API documentation is available at pkg.go.dev/github.com/duragraph/duragraph-go.

Examples

See the examples directory for complete working examples:

Chat Agent - Simple conversational agent
RAG Agent - Retrieval-augmented generation
Multi-Agent - Coordinating multiple agents