langgraphgo

Overview ¶

LangGraph Go - Building Stateful, Multi-Agent Applications in Go

LangGraph Go is a Go implementation of LangChain's LangGraph framework for building stateful, multi-agent applications with LLMs. It provides a powerful graph-based approach to constructing complex AI workflows with support for cycles, checkpoints, and human-in-the-loop interactions.

Quick Start ¶

Install the package:

go get github.com/smallnest/langgraphgo

Basic example:

package main

import (
	"context"
	"fmt"

	"github.com/smallnest/langgraphgo/graph"
	"github.com/smallnest/langgraphgo/prebuilt"
	"github.com/tmc/langchaingo/llms/openai"
	"github.com/tmc/langchaingo/tools"
)

func main() {
	// Initialize LLM
	llm, _ := openai.New()

	// Create a simple ReAct agent
	agent, _ := prebuilt.CreateReactAgent(
		llm,
		[]tools.Tool{&tools.CalculatorTool{}},
		10, // max iterations
	)

	// Execute the agent
	ctx := context.Background()
	result, _ := agent.Invoke(ctx, map[string]any{
		"messages": []llms.MessageContent{
			{
				Role: llms.ChatMessageTypeHuman,
				Parts: []llms.ContentPart{
					llms.TextPart("What is 123 * 456?"),
				},
			},
		},
	})

	fmt.Println(result)
}

Key Features ¶

• **Stateful Graphs**: Define complex workflows with state persistence
• **Agent Orchestration**: Build multi-agent systems with specialized roles
• **Checkpointing**: Save and resume execution state
• **Streaming**: Real-time event streaming during execution
• **Memory Management**: Various strategies for conversation memory
• **Tool Integration**: Extensive ecosystem of built-in tools
• **Type Safety**: Generic-based typed graphs for compile-time safety
• **Visualization**: Graph visualization and debugging tools

Core Concepts ¶

## Graph Structure

LangGraph Go uses a directed graph structure where:

• Nodes represent processing units (agents, tools, functions)
• Edges define the flow of execution
• State flows through the graph and evolves at each node

## State Management

State can be managed in different ways:

• **Untyped**: Using map[string]any for flexibility
• **Typed**: Using Go generics for type safety
• **Structured**: Using predefined schemas

Package Structure ¶

## Core Packages

### graph/ The core graph construction and execution engine

// Create a state graph
g := graph.NewStateGraph()

// Add nodes
g.AddNode("process", func(ctx context.Context, state map[string]any) (map[string]any, error) {
	state["processed"] = true
	return state, nil
})

// Define execution flow
g.SetEntry("process")
g.AddEdge("process", graph.END)

// Compile and run
runnable, _ := g.Compile()
result, _ := runnable.Invoke(ctx, initialState)

### prebuilt/ Ready-to-use agent implementations

Types of agents:

• **ReAct Agent**: Reason and act pattern
• **Supervisor Agent**: Orchestrates multiple agents
• **Planning Agent**: Creates and executes plans
• **Reflection Agent**: Self-correcting agent
• **Tree of Thoughts**: Multi-path reasoning

Example:

// Create a supervisor with multiple agents
members := map[string]*graph.StateRunnable{
	"analyst":   analystAgent,
	"coder":     coderAgent,
	"reviewer":  reviewerAgent,
}

supervisor, _ := prebuilt.CreateSupervisor(llm, members, "router")

### memory/ Various memory management strategies

Types:

• Buffer: Simple FIFO buffer
• Sliding Window: Maintains recent context with overlap
• Summarization: Compresses older conversations
• Hierarchical: Multi-level memory with importance scoring
• OS-like: Sophisticated paging and eviction

Example:

// Use summarization memory
memory := memory.NewSummarizationMemory(llm, 2000)
agent, _ := prebuilt.CreateChatAgent(llm, "", memory)

### tool/ Collection of useful tools

Categories:

• Web Search: Tavily, Brave, EXA, Bocha
• File Operations: Read, write, list files
• Code Execution: Shell, Python
• Web APIs: HTTP requests

Example:

// Use web search tool
searchTool, _ := tool.NewTavilySearchTool(apiKey)
agent, _ := prebuilt.CreateReactAgent(llm, []tools.Tool{searchTool}, 10)

## Storage Packages

### store/ Checkpoint persistence implementations

Options:

• SQLite: Lightweight, file-based storage
• PostgreSQL: Scalable relational database
• Redis: High-performance in-memory storage

Example:

// PostgreSQL checkpoint store
store, _ := postgres.NewPostgresCheckpointStore(ctx, postgres.PostgresOptions{
	ConnString: "postgres://user:pass@localhost/langgraph",
})

g.WithCheckpointing(graph.CheckpointConfig{Store: store})

## Adapter Packages

### adapter/ Integration adapters for external systems

Adapters:

• GoSkills: Custom Go-based skills
• MCP: Model Context Protocol tools

Example:

// Load GoSkills
skills, _ := goskills.LoadSkillsFromDir("./skills")
tools, _ := goskills.ConvertToLangChainTools(skills)

## Specialized Packages

### ptc/ Programmatic Tool Calling - agents generate code to use tools

agent, _ := ptc.CreatePTCAgent(ptc.PTCAgentConfig{
	Model:    llm,
	Tools:    tools,
	Language: ptc.LanguagePython,
})

### log/ Simple logging utilities

logger := log.NewDefaultLogger(log.LogLevelInfo)
listener := graph.NewLoggingListener(logger, log.LogLevelInfo, false)

Advanced Examples ¶

## 1. Multi-Agent System with Supervisor

package main

import (
	"context"
	"fmt"

	"github.com/smallnest/langgraphgo/prebuilt"
	"github.com/tmc/langchaingo/llms/openai"
	"github.com/tmc/langchaingo/tools"
)

func main() {
	llm, _ := openai.New()

	// Create specialized agents
	researcher, _ := prebuilt.CreateReactAgent(llm, researchTools, 10)
	writer, _ := prebuilt.CreateReactAgent(llm, writingTools, 10)
	critic, _ := prebuilt.CreateReactAgent(llm, criticTools, 5)

	// Create supervisor
	members := map[string]*graph.StateRunnable{
		"researcher": researcher,
		"writer":    writer,
		"critic":    critic,
	}

	supervisor, _ := prebuilt.CreateSupervisor(llm, members, "router")

	// Execute workflow
	result, _ := supervisor.Invoke(ctx, map[string]any{
		"messages": []llms.MessageContent{
			{
				Role: llms.ChatMessageTypeHuman,
				Parts: []llms.ContentPart{
					llms.TextPart("Write a research paper on quantum computing"),
				},
			},
		},
	})

	fmt.Println(result)
}

## 2. RAG (Retrieval-Augmented Generation) System

package main

import (
	"context"

	"github.com/smallnest/langgraphgo/prebuilt"
	"github.com/smallnest/langgraphgo/memory"
	"github.com/smallnest/langgraphgo/store/postgres"
	"github.com/tmc/langchaingo/embeddings/openai"
	"github.com/tmc/langchaingo/llms"
	"github.com/tmc/langchaingo/vectorstores/pgvector"
)

func main() {
	// Initialize components
	llm, _ := openai.NewChat(openai.GPT4)
	embedder, _ := openai.NewEmbedder()

	// Setup vector store
	store, _ := pgvector.New(
		ctx,
		pgvector.WithConnString("postgres://localhost/postgres"),
		pgvector.WithEmbedder(embedder),
	)

	// Create RAG agent
	rag, _ := prebuilt.CreateRAGAgent(
		llm,
		documentLoader,
		textSplitter,
		embedder,
		store,
		5, // retrieve 5 documents
	)

	// Add memory for conversation
	mem := memory.NewBufferMemory(100)
	rag.WithMemory(mem)

	// Enable checkpointing
	checkpointStore, _ := postgres.NewPostgresCheckpointStore(ctx, postgres.PostgresOptions{
		ConnString: "postgres://localhost/langgraph",
	})
	rag.WithCheckpointing(graph.CheckpointConfig{
		Store: checkpointStore,
	})

	// Query the system
	result, _ := rag.Invoke(ctx, map[string]any{
		"messages": []llms.MessageContent{
			{
				Role: llms.ChatMessageTypeHuman,
				Parts: []llms.ContentPart{
					llms.TextPart("What are the latest developments in AI?"),
				},
			},
		},
	})
}

## 3. Typed Graph with Custom State

package main

import (
	"context"
	"fmt"

	"github.com/smallnest/langgraphgo/graph"
	"github.com/smallnest/langgraphgo/prebuilt"
)

type WorkflowState struct {
	Input     string `json:"input"`
Processed  string `json:"processed"`
Validated  bool   `json:"validated"`
Output     string `json:"output"`
StepCount  int    `json:"step_count"`
}

func main() {
	// Create typed graph
	g := graph.NewStateGraphTyped(func() WorkflowState {
		return WorkflowState{}
	})

	// Add typed nodes
	g.AddNodeTyped("process", func(ctx context.Context, state WorkflowState) (WorkflowState, error) {
		state.Processed = strings.ToUpper(state.Input)
		state.StepCount++
		return state, nil
	})

	g.AddNodeTyped("validate", func(ctx context.Context, state WorkflowState) (WorkflowState, error) {
		state.Validated = len(state.Processed) > 0
		state.StepCount++
		return state, nil
	})

	g.AddNodeTyped("output", func(ctx context.Context, state WorkflowState) (WorkflowState, error) {
		state.Output = fmt.Sprintf("Processed: %s, Validated: %v", state.Processed, state.Validated)
		state.StepCount++
		return state, nil
	})

	// Define flow
	g.SetEntryTyped("process")
	g.AddEdgeTyped("process", "validate")
	g.AddConditionalEdgeTyped("validate", func(ctx context.Context, state WorkflowState) string {
		if state.Validated {
			return "output"
		}
		return "process" // Retry
	}, "output", "process")
	g.AddEdgeTyped("output", graph.END)

	// Compile and run
	runnable, _ := g.CompileTyped()

	result, _ := runnable.InvokeTyped(ctx, WorkflowState{
		Input: "hello world",
	})

	fmt.Printf("Result: %+v\n", result)
	fmt.Printf("Steps: %d\n", result.StepCount)
}

Best Practices ¶

1. **Choose the right agent type** for your use case - ReAct for general tasks - Supervisor for multi-agent workflows - PTC for complex tool interactions

2. **Use typed graphs** when possible for better type safety

3. **Implement proper error handling** in all node functions

4. **Add checkpoints** for long-running or critical workflows

5. **Use appropriate memory** strategy for conversations

6. **Monitor execution** with listeners and logging

7. **Test thoroughly** with various input scenarios

Configuration ¶

The library supports configuration through environment variables:

• OPENAI_API_KEY: OpenAI API key for LLM access
• LANGGRAPH_LOG_LEVEL: Logging level (debug, info, warn, error)
• LANGGRAPH_CHECKPOINT_DIR: Default directory for checkpoints
• LANGGRAPH_MAX_ITERATIONS: Default max iterations for agents

Community and Support ¶

• GitHub: https://github.com/smallnest/langgraphgo
• Documentation: https://pkg.go.dev/github.com/smallnest/langgraphgo
• Examples: ./examples directory
• Issues: Report bugs and request features on GitHub

Contributing ¶

We welcome contributions! Please see:

• CONTRIBUTING.md for guidelines
• CODE_OF_CONDUCT.md for community standards
• Examples in ./examples for reference implementations

License ¶

This project is licensed under the MIT License - see the LICENSE file for details.