Skip to content

Latest commit

 

History

History
476 lines (363 loc) · 14 KB

README.md

File metadata and controls

476 lines (363 loc) · 14 KB
GoLangGraph Logo

🚀 GoLangGraph

Build Intelligent AI Agent Workflows with Go

CI codecov Go Report Card GoDoc License: MIT

Quick Start • Features • Examples • Documentation • Contributing


🎯 Overview

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.

🚀 Graphical Interface Studio

GoLangGraphStudio -> we are working on a GUI based Studio component for this library GoLangGraphStudio don't hesitate to contribute !

✨ Key Features

  • 🔄 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

📦 Installation

go get github.com/UnicoLab/GoLangGraph

Experimental Go-native agent packages

Build 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 modules

See 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.

🏃 Quick Start

Prerequisites

  • Go 1.21+
  • Ollama (optional, for local LLM testing)

Simple Chat Agent

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)
}

ReAct Agent with Tools

// 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)

Graph Workflow

// 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"))

🔒 Production Deployment

Defaults favour local development. Before exposing GoLangGraph to real traffic, read docs/PRODUCTION.md, which covers:

  • Authentication and CORS — RequireAuth is 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/...

🏗️ Architecture

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

🎯 Agent Types

💬 Chat Agent

Simple conversational agent for basic interactions:

config := &agent.AgentConfig{
    Type: agent.AgentTypeChat,
    // ... other config
}

🧠 ReAct Agent

Reasoning and Acting agent that can use tools:

config := &agent.AgentConfig{
    Type:          agent.AgentTypeReAct,
    Tools:         []string{"calculator", "web_search"},
    MaxIterations: 5,
    // ... other config
}

🔧 Tool Agent

Specialized agent focused on tool usage:

config := &agent.AgentConfig{
    Type:  agent.AgentTypeTool,
    Tools: []string{"file_read", "file_write", "shell"},
    // ... other config
}

🔧 Built-in Tools

  • 🧮 Calculator - Mathematical operations
  • 🔍 Web Search - Information retrieval
  • 📁 File Operations - Read/write files
  • 🌐 HTTP Client - Web requests
  • ⏰ Time - Date and time operations
  • 🖥️ Shell - Command execution

🌐 LLM Providers

OpenAI

provider, err := llm.NewOpenAIProvider(&llm.ProviderConfig{
    APIKey: "your-api-key",
    Model:  "gpt-4",
})

Ollama (Local)

provider, err := llm.NewOllamaProvider(&llm.ProviderConfig{
    Endpoint: "http://localhost:11434",
    Model:    "gemma3:1b",
})

Gemini

provider, err := llm.NewGeminiProvider(&llm.ProviderConfig{
    APIKey: "your-gemini-api-key",
    Model:  "gemini-pro",
})

🚀 Auto Server & API Generation

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

📊 Examples

Explore comprehensive examples in the /examples directory:

Running Examples

# Prerequisites: Install Ollama and pull models
ollama serve
ollama pull gemma3:1b

# Run any example
cd examples/01-basic-chat
go run main.go

🛠️ Development

📋 Prerequisites

  • 🐹 Go 1.21+ - Latest Go version
  • 🦙 Ollama (optional) - For local LLM testing
  • 🐳 Docker (optional) - For containerized development

🚀 Setup

# 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

🧪 Testing & Quality

# 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

🐳 Docker & Production

# Build Docker images
make docker-build-agent

# Production deployment
make build-release

# Local development with Ollama
make ollama-setup
make test-local

🔒 Security

  • ✅ 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

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

🔄 Development Workflow

  1. 🍴 Fork the repository
  2. 🌿 Create a feature branch
  3. ✨ Make your changes and add tests
  4. 🧪 Run tests: go test ./...
  5. 💾 Commit your changes
  6. 🚀 Push and open a Pull Request

📄 License

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

🆘 Support & Community

Resource Link
📚 Documentation GoDoc
🐛 Issues GitHub Issues
💬 Discussions GitHub Discussions
🎮 Discord Join our Discord

🙏 Acknowledgments

  • 🌟 Inspired by LangGraph and similar workflow engines
  • 🐹 Built with the excellent Go ecosystem
  • 👥 Special thanks to all contributors

🚀 GoLangGraph - Building intelligent AI workflows with Go! 🚀

⭐ Star us on GitHub • 🐛 Report Bug • 💬 Request Feature