216 lines
7.3 KiB
Markdown
216 lines
7.3 KiB
Markdown
# GopherGraph
|
||
|
||
A lightweight, high-performance, and type-safe Multi-Agent workflow orchestration engine written in Go.
|
||
基于 Go 语言（泛型）实现的轻量级、高性能、类型安全的多智能体（Multi-Agent）协同与任务编排引擎。
|
||
Go 言語（ジェネリクス）で書かれた、軽量・高性能・型安全なマルチエージェント・ワークフロー協調エンジン。
|
||
|
||
---
|
||
|
||
* [简体中文](#-简体中文)
|
||
* [English](#-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)
|
||
```go
|
||
type MyState struct {
|
||
Query string
|
||
Response string
|
||
}
|
||
```
|
||
|
||
#### 2. 构建工作流图
|
||
```go
|
||
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：
|
||
```bash
|
||
go run examples/translation/main.go
|
||
```
|
||
|
||
#### 运行单元测试
|
||
```bash
|
||
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
|
||
```go
|
||
type MyState struct {
|
||
Query string
|
||
Response string
|
||
}
|
||
```
|
||
|
||
#### 2. Define and Run the Graph
|
||
```go
|
||
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:
|
||
```bash
|
||
go run examples/translation/main.go
|
||
```
|
||
|
||
#### Run Unit Tests
|
||
```bash
|
||
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）の定義
|
||
```go
|
||
type MyState struct {
|
||
Query string
|
||
Response string
|
||
}
|
||
```
|
||
|
||
#### 2. ワークフロー図の構築と実行
|
||
```go
|
||
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翻訳 -> 監査 -> 人間による確認 -> 公開」の一連のループを体験できるデモを用意しています：
|
||
```bash
|
||
go run examples/translation/main.go
|
||
```
|
||
|
||
#### ユニットテストの実行
|
||
```bash
|
||
go test -v ./...
|
||
```
|