Build Intelligent AI Agent Workflows with Go
Quick Start • Features • Examples • Documentation • Contributing
GoLangGraph is a Go framework for building AI agent workflows using graph-based execution. Create intelligent agents that can reason, use tools, and execute complex workflows with the performance and reliability of Go.
💡 Perfect for: Building AI applications, RAG systems, multi-agent workflows, and intelligent automation tools using local LLMs like Ollama.
GoLangGraphStudio -> we are working on a GUI based Studio component for this library GoLangGraphStudio
don't hesitate to contribute !
- 🔄 Graph-Based Execution - Build workflows as directed graphs with nodes and edges
- 🧠 AI Agent Framework - Chat, ReAct, and Tool agents with different capabilities
- 🌐 Multi-LLM Support - OpenAI, Ollama, and Gemini provider integrations
- 🔧 Built-in Tools - Calculator, web search, file operations, and more
- 💾 State Management - Thread-safe state containers with persistence options
- 🚀 Auto Server - Automatically generate REST APIs for your agents
- 📊 Monitoring & Observability - Grafana dashboards, Prometheus metrics, and comprehensive monitoring
- 🐳 Production Ready - Docker support, comprehensive testing, and error handling
go get github.com/UnicoLab/GoLangGraphBuild reusable agents as ordinary Go modules containing typed contracts, embedded prompts, tools, Go handlers and declared child agents. The GoLangGraph adapter supplies persistent isolated threads, dependency validation, request deduplication and execution traces. A CLI scaffolds modules and inspects their manifests.
make demo-agent-packages # Reusable habitat → designer + storyteller composition
make test-agent-packages # Contract, runtime and all independent modulesSee the agent package guide and consumer example for authoring, distribution, live-model use and current limits. The packages are a local experimental implementation; module releases have not been published.
- Go 1.21+
- Ollama (optional, for local LLM testing)
package main
import (
"context"
"fmt"
"log"
"github.com/UnicoLab/GoLangGraph/pkg/agent"
"github.com/UnicoLab/GoLangGraph/pkg/llm"
"github.com/UnicoLab/GoLangGraph/pkg/tools"
)
func main() {
// Create LLM provider manager
llmManager := llm.NewProviderManager()
// Add Ollama provider (requires Ollama running locally)
provider, err := llm.NewOllamaProvider(&llm.ProviderConfig{
Endpoint: "http://localhost:11434",
Model: "gemma3:1b",
})
if err != nil {
log.Fatal(err)
}
llmManager.RegisterProvider("ollama", provider)
// Create tool registry
toolRegistry := tools.NewToolRegistry()
// Create chat agent
config := &agent.AgentConfig{
Name: "chat-agent",
Type: agent.AgentTypeChat,
Model: "gemma3:1b",
Provider: "ollama",
SystemPrompt: "You are a helpful AI assistant.",
Temperature: 0.7,
MaxTokens: 500,
}
chatAgent := agent.NewAgent(config, llmManager, toolRegistry)
// Execute
ctx := context.Background()
execution, err := chatAgent.Execute(ctx, "Hello! Tell me about Go programming.")
if err != nil {
log.Fatal(err)
}
fmt.Printf("🤖 Agent: %s\n", execution.Output)
}// Create ReAct agent with tools
config := &agent.AgentConfig{
Name: "react-agent",
Type: agent.AgentTypeReAct,
Model: "gemma3:1b",
Provider: "ollama",
Tools: []string{"calculator", "web_search"},
MaxIterations: 5,
SystemPrompt: "You are a helpful assistant that can use tools to solve problems.",
}
reactAgent := agent.NewAgent(config, llmManager, toolRegistry)
// Execute complex task
execution, err := reactAgent.Execute(ctx, "What is 25 * 34?")
if err != nil {
log.Fatal(err)
}
fmt.Printf("🧠 ReAct Agent: %s\n", execution.Output)// Create custom graph workflow
graph := core.NewGraph("my-workflow")
// Add processing node
graph.AddNode("process", "Process Input", func(ctx context.Context, state *core.BaseState) (*core.BaseState, error) {
input, _ := state.Get("user_input")
state.Set("processed_input", fmt.Sprintf("Processing: %s", input))
return state, nil
})
// Add response node
graph.AddNode("respond", "Generate Response", func(ctx context.Context, state *core.BaseState) (*core.BaseState, error) {
processed, _ := state.Get("processed_input")
state.Set("response", fmt.Sprintf("Response: %s", processed))
return state, nil
})
// Connect nodes
graph.AddEdge("process", "respond", nil)
graph.SetStartNode("process")
graph.AddEndNode("respond")
// Execute graph
initialState := core.NewBaseState()
initialState.Set("user_input", "Hello, world!")
result, err := graph.Execute(context.Background(), initialState)
if err != nil {
log.Fatal(err)
}
fmt.Printf("🔄 Graph Result: %v\n", result.Get("response"))Defaults favour local development. Before exposing GoLangGraph to real traffic, read docs/PRODUCTION.md, which covers:
- Authentication and CORS —
RequireAuthis off by default, and the allowed-origin list also governs WebSocket upgrades. - Tool sandboxing — filesystem confinement, the shell allowlist, and SSRF protection for the HTTP tool.
- Durable execution — checkpointing, resume after a crash, and human-in-the-loop interrupts.
- Health checking — which probe belongs in a container, and which does not.
- Typed errors, retries, concurrency and observability.
LangGraph compatibility, including the places GoLangGraph intentionally differs, is documented in test/conformance/DEVIATIONS.md and enforced by the conformance suite:
go test -race ./test/conformance/...GoLangGraph follows a modular architecture:
📁 pkg/
├── 🧠 core/ # Graph execution engine and state management
├── 🤖 agent/ # AI agent implementations (Chat, ReAct, Tool)
├── 🌐 llm/ # LLM provider integrations (OpenAI, Ollama, Gemini)
├── 🔧 tools/ # Built-in tools and tool registry
├── 💾 persistence/ # Database integration and checkpointing
├── 🌐 server/ # HTTP server and WebSocket support
├── 🏗️ builder/ # Quick builder patterns for rapid development
└── 🐛 debug/ # Debugging and visualization tools
Simple conversational agent for basic interactions:
config := &agent.AgentConfig{
Type: agent.AgentTypeChat,
// ... other config
}Reasoning and Acting agent that can use tools:
config := &agent.AgentConfig{
Type: agent.AgentTypeReAct,
Tools: []string{"calculator", "web_search"},
MaxIterations: 5,
// ... other config
}Specialized agent focused on tool usage:
config := &agent.AgentConfig{
Type: agent.AgentTypeTool,
Tools: []string{"file_read", "file_write", "shell"},
// ... other config
}- 🧮 Calculator - Mathematical operations
- 🔍 Web Search - Information retrieval
- 📁 File Operations - Read/write files
- 🌐 HTTP Client - Web requests
- ⏰ Time - Date and time operations
- 🖥️ Shell - Command execution
provider, err := llm.NewOpenAIProvider(&llm.ProviderConfig{
APIKey: "your-api-key",
Model: "gpt-4",
})provider, err := llm.NewOllamaProvider(&llm.ProviderConfig{
Endpoint: "http://localhost:11434",
Model: "gemma3:1b",
})provider, err := llm.NewGeminiProvider(&llm.ProviderConfig{
APIKey: "your-gemini-api-key",
Model: "gemini-pro",
})GoLangGraph can automatically generate REST APIs for your agents:
import "github.com/UnicoLab/GoLangGraph/pkg/server"
// Create auto server
config := server.DefaultAutoServerConfig()
config.Port = 8080
config.EnableWebUI = true
config.EnablePlayground = true
autoServer := server.NewAutoServer(config)
// Register your agents
autoServer.RegisterAgent("chat-agent", chatAgentDefinition)
autoServer.RegisterAgent("react-agent", reactAgentDefinition)
// Generate endpoints automatically
autoServer.GenerateEndpoints()
// Start server
ctx := context.Background()
autoServer.Start(ctx)This automatically creates:
- 🌐 REST Endpoints:
/api/{agent-id}for each agent - 🎮 Web UI: Interactive chat interface at
/ - 🔧 API Playground: Test endpoints at
/playground - 📊 Metrics: System metrics at
/metrics - 📋 Health Checks: Status monitoring at
/health
Explore comprehensive examples in the /examples directory:
- 01-basic-chat - Simple chat agent
- 02-react-agent - ReAct agent with tools
- 03-multi-agent - Multi-agent coordination
- 04-rag-system - RAG implementation
- 05-streaming - Real-time streaming
- 06-persistence - Data persistence
- 07-tools-integration - Advanced tools
- 08-production-ready - Production deployment
- 09-workflow-graph - Complex workflows
- 10-ideation-agents - Creative agent collaboration with monitoring
# Prerequisites: Install Ollama and pull models
ollama serve
ollama pull gemma3:1b
# Run any example
cd examples/01-basic-chat
go run main.go- 🐹 Go 1.21+ - Latest Go version
- 🦙 Ollama (optional) - For local LLM testing
- 🐳 Docker (optional) - For containerized development
# Clone repository
git clone https://github.com/UnicoLab/GoLangGraph.git
cd GoLangGraph
# Install dependencies
make install
# Build the project
make build
# Run tests
make test
# Run examples
cd examples/01-basic-chat
go run main.go# Run all tests
make test
# Run tests with coverage
make test-coverage
# Run integration tests
make test-integration
# Code quality checks
make lint # Run linter
make fmt # Format code
make vet # Run go vet
make security # Security scan
# Complete quality check
make check # Run all checks# Build Docker images
make docker-build-agent
# Production deployment
make build-release
# Local development with Ollama
make ollama-setup
make test-local- ✅ Input Validation - All inputs are validated and sanitized
- 🛡️ SQL Injection Prevention - Parameterized queries throughout
- 🔑 Secure Credential Handling - Environment variable management
- 📝 Audit Logging - Comprehensive execution logging
We welcome contributions! Please see our Contributing Guide for details.
- 🍴 Fork the repository
- 🌿 Create a feature branch
- ✨ Make your changes and add tests
- 🧪 Run tests:
go test ./... - 💾 Commit your changes
- 🚀 Push and open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
| Resource | Link |
|---|---|
| 📚 Documentation | GoDoc |
| 🐛 Issues | GitHub Issues |
| 💬 Discussions | GitHub Discussions |
| 🎮 Discord | Join our Discord |
- 🌟 Inspired by LangGraph and similar workflow engines
- 🐹 Built with the excellent Go ecosystem
- 👥 Special thanks to all contributors