A lightweight, high-performance, and type-safe Multi-Agent workflow orchestration engine written in Go.
基于 Go 语言（泛型）实现的轻量级、高性能、类型安全的多智能体（Multi-Agent）协同与任务编排引擎。
Go 言語（ジェネリクス）で書かれた、軽量・高性能・型安全なマルチエージェント・ワークフロー協調エンジン。

简体中文
English
日本語

简体中文

简介

GopherGraph 是一个用 Go 语言编写的代码即图（Code-as-Graph）智能体编排引擎，设计灵感来源于 Python 生态的 LangGraph。它利用 Go 1.18+ 的泛型机制，让工作流的上下文状态在编译期就具备强类型约束，并依靠 Go 原生的 Goroutines 和 Channels 实现极高并发的本地数据流转。它特别适合构建包含复杂循环（Looping）和人机协同（Human-in-the-Loop）的智能体工作流。

核心特性

强类型状态管理： 利用 Go 泛型定义全局状态 Graph[S]，彻底告别松散的 map[string]any 和繁琐的类型断言。
支持循环结构： 突破了传统 DAG（有向无环图）工作流的限制，原生支持节点间的双向循环和条件路由。
人机协同中断 (HITL)： 支持在特定节点前自动挂起，返回执行线程快照，等待人工修改状态或审批通过后一键恢复 (Resume)。
纯粹的高性能： 基于内存流转，零外部依赖，极低的上下文切换开销。

快速开始

1. 定义您的状态 (State)

type MyState struct {
    Query    string
    Response string
}

2. 构建工作流图

package main

import (
    "context"
    "fmt"
    "GopherGraph"
)

func main() {
    // 初始化一个强类型的图构建器
    g := GopherGraph.NewGraph[MyState]()

    // 注册节点 (Node)
    g.AddNode("agentA", func(ctx context.Context, s MyState) (MyState, error) {
        s.Response = "Hello from Agent A"
        return s, nil
    })

    // 建立连线 (Edge)
    g.AddEdge("agentA", "anotherNode")
    
    // 设置中断拦截点 (Interrupt)
    g.AddInterrupt("anotherNode")

    // 编译图
    cg, _ := g.Compile()

    // 启动运行
    thread, _ := cg.Start(context.Background(), "agentA", MyState{Query: "Test"})
}

运行内置示例

项目包含了一个完整的“AI翻译 -> 质量检测 -> 人工审核 -> 发布”的交互式 Demo：

go run examples/translation/main.go

运行单元测试

go test -v ./...

English

Introduction

GopherGraph is a Code-as-Graph agent orchestration engine built in Go, inspired by Python's LangGraph. By leveraging Go 1.18+ Generics, GopherGraph ensures that workflow states are strictly typed at compile-time. Powered by native Goroutines and Channels, it executes agent communication with microsecond latency, making it the perfect engine for building complex looping agent workflows with Human-in-the-Loop (HITL) requirements.

Key Features

Strictly Typed State: Bind your custom struct to Graph[S] via Go generics. Say goodbye to unsafe map[string]any and runtime type assertions.
Support for Cycles/Loops: Unlike traditional DAG (Directed Acyclic Graph) engines, GopherGraph natively supports loops and dynamic routing based on agent evaluation.
Human-in-the-Loop (HITL): Pause workflow execution before a designated node, capture a snapshot (Thread), modify the state, and Resume seamlessly.
Zero-Dependency & High-Performance: Written in pure Go with zero external dependencies, leveraging in-memory queues for lightning-fast orchestration.

Quick Start

1. Define Your State

type MyState struct {
    Query    string
    Response string
}

2. Define and Run the Graph

package main

import (
    "context"
    "fmt"
    "GopherGraph"
)

func main() {
    // Initialize the strongly-typed graph builder
    g := GopherGraph.NewGraph[MyState]()

    // Add nodes (agents)
    g.AddNode("agentA", func(ctx context.Context, s MyState) (MyState, error) {
        s.Response = "Hello from Agent A"
        return s, nil
    })

    // Add edges
    g.AddEdge("agentA", "anotherNode")
    
    // Add interrupts
    g.AddInterrupt("anotherNode")

    // Compile
    cg, _ := g.Compile()

    // Start execution
    thread, _ := cg.Start(context.Background(), "agentA", MyState{Query: "Test"})
}

Run the Interactive Demo

An interactive "Translation -> Review -> Human Approval -> Publish" demo is included:

go run examples/translation/main.go

Run Unit Tests

go test -v ./...

日本語

概要

GopherGraph は、Python エコシステムの LangGraph に着想を得て開発された、Go 言語向けの Code-as-Graph 型エージェントオーケストレーションエンジンです。Go 1.18+ のジェネリクスを活用することで、ワークフローの状態（State）をコンパイル時に厳密に型定義できます。Go 純正の Goroutines と Channels を利用したメモリ内メッセージングにより、高い並行性と極めて低いレイテンシを実現しています。自律的なループ（Looping）や人間参加型（Human-in-the-Loop）の意思決定を伴うエージェントワークフローの開発に最適です。

主な特徴

型安全な状態管理: ジェネリクスを用いて Graph[S] に構造体をバインドします。冗長な map[string]any やランタイム時の型アサーションから解放されます。
ループと条件付き分岐のサポート: 従来の DAG（有向非巡回グラフ）の制限を超え、エージェントの判定に基づく条件付きルートや双方向のループをサポート。
Human-in-the-Loop (HITL) の一時停止と再開: 特定のノードの実行前に処理を自動停止し、スナップショット（Thread）を返します。承認や状態修正の後にシームレスに処理を再開（Resume）できます。
ピュア Go & 高性能: 外部依存関係ゼロ。メモリ内チャネルを用いた高速なコンテキスト切り替え。

クイックスタート

1. 状態（State）の定義

type MyState struct {
    Query    string
    Response string
}

2. ワークフロー図の構築と実行

package main

import (
    "context"
    "fmt"
    "GopherGraph"
)

func main() {
    // 型安全なグラフビルダーの初期化
    g := GopherGraph.NewGraph[MyState]()

    // ノード（エージェント）の追加
    g.AddNode("agentA", func(ctx context.Context, s MyState) (MyState, error) {
        s.Response = "Hello from Agent A"
        return s, nil
    })

    // エッジ（遷移線）の接続
    g.AddEdge("agentA", "anotherNode")
    
    // 割り込み（一時停止）ポイントの設定
    g.AddInterrupt("anotherNode")

    // コンパイル
    cg, _ := g.Compile()

    // 実行開始
    thread, _ := cg.Start(context.Background(), "agentA", MyState{Query: "Test"})
}

インタラクティブデモの実行

「AI翻訳 -> 監査 -> 人間による確認 -> 公開」の一連のループを体験できるデモを用意しています：

go run examples/translation/main.go

ユニットテストの実行

go test -v ./...

README.md Unescape Escape

GopherGraph