diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 93e3eb9..cebbe8c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -11,7 +11,7 @@ concurrency: cancel-in-progress: true env: - GO_VERSION: '1.25' + GO_VERSION: '1.27.4' jobs: test: @@ -86,6 +86,10 @@ jobs: REDIS_HOST: localhost REDIS_PORT: 6379 + - name: Test independent Go agent modules + # Nested modules are excluded from the root go test ./... invocation. + run: make test-agent-packages + - name: Enforce source coverage floor run: | coverage=$(go tool cover -func=coverage.out | awk '/^total:/ {gsub(/%/, "", $3); print $3}') @@ -103,6 +107,7 @@ jobs: "./pkg/core FuzzDeepCopy" \ "./pkg/core FuzzGraphRouting" \ "./pkg/core FuzzGraphConstruction" \ + "./pkg/agentspec FuzzManifest" \ "./pkg/tools FuzzToolArguments" \ "./pkg/tools FuzzPathResolution" \ "./pkg/tools FuzzCommandPolicy" \ @@ -156,7 +161,7 @@ jobs: - name: Run golangci-lint uses: golangci/golangci-lint-action@v9 with: - version: v2.13.1 + version: v2.15.0 args: --timeout=10m security: @@ -179,8 +184,11 @@ jobs: cache: false - name: Run Gosec Security Scanner + # Permit pinned scanners to select their required build toolchain. + env: + GOTOOLCHAIN: auto run: | - go install github.com/securego/gosec/v2/cmd/gosec@latest + go install github.com/securego/gosec/v2/cmd/gosec@v2.30.0 # Gosec reports findings with exit 1, which is indistinguishable from # an analyzer-only error on some runner/toolchain combinations. Always # emit SARIF, then make the actual release decision from its findings. @@ -308,6 +316,9 @@ jobs: runs-on: ubuntu-latest needs: [test, lint, build] timeout-minutes: 15 + env: + # Bake requires Dockerfiles to remain inside the authorized build context. + DEPLOY_DIR: ${{ github.workspace }}/.ci-docker-deploy steps: - name: Checkout code @@ -379,8 +390,8 @@ jobs: run: | set -euo pipefail go run ./cmd/golanggraph multi-agent generate docker "$RUNNER_TEMP/multi-agent.yaml" \ - --output "$RUNNER_TEMP/deploy" - docker compose -f "$RUNNER_TEMP/deploy/docker-compose.yml" -p golanggraph-ci \ + --output "$DEPLOY_DIR" + docker compose -f "$DEPLOY_DIR/docker-compose.yml" -p golanggraph-ci \ up --detach --build - name: Verify live health and agent endpoints @@ -401,12 +412,12 @@ jobs: - name: Print container logs on failure if: failure() - run: docker compose -f "$RUNNER_TEMP/deploy/docker-compose.yml" -p golanggraph-ci logs + run: docker compose -f "$DEPLOY_DIR/docker-compose.yml" -p golanggraph-ci logs - name: Remove disposable Compose deployment and image if: always() run: | - docker compose -f "$RUNNER_TEMP/deploy/docker-compose.yml" -p golanggraph-ci down --volumes --rmi local || true + docker compose -f "$DEPLOY_DIR/docker-compose.yml" -p golanggraph-ci down --volumes --rmi local || true kubernetes-e2e: name: Kubernetes End-to-End diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3ea0307..bbfc8fe 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -24,7 +24,7 @@ concurrency: cancel-in-progress: true env: - GO_VERSION: '1.25' + GO_VERSION: '1.27.4' jobs: build: diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml index c477120..d75b13a 100644 --- a/.github/workflows/pre-commit.yml +++ b/.github/workflows/pre-commit.yml @@ -12,7 +12,7 @@ concurrency: cancel-in-progress: true env: - GO_VERSION: '1.25' + GO_VERSION: '1.27.4' jobs: pre-commit: @@ -113,8 +113,10 @@ jobs: go mod tidy - name: Run Gosec Security Scanner + env: + GOTOOLCHAIN: auto run: | - go install github.com/securego/gosec/v2/cmd/gosec@latest + go install github.com/securego/gosec/v2/cmd/gosec@v2.30.0 # Enforce the scanner's SARIF findings explicitly. This preserves a # strict gate even when GoSec exits non-zero after a successful scan. gosec -no-fail -concurrency=1 -exclude=G301,G306,G304,G204,G104,G302 -exclude-dir=examples -exclude-dir=cmd/examples -fmt sarif -out gosec-results.sarif ./... @@ -193,8 +195,10 @@ jobs: go mod tidy - name: Check for vulnerabilities + env: + GOTOOLCHAIN: auto run: | - go install golang.org/x/vuln/cmd/govulncheck@latest + go install golang.org/x/vuln/cmd/govulncheck@v1.9.0 govulncheck ./... - name: Check for outdated dependencies diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c5a24fc..d68ef35 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -23,7 +23,7 @@ concurrency: cancel-in-progress: true env: - GO_VERSION: '1.25' + GO_VERSION: '1.27.4' REGISTRY: ghcr.io IMAGE_NAME: ${{ github.repository }} @@ -68,12 +68,12 @@ jobs: - name: Run linting uses: golangci/golangci-lint-action@v9 with: - version: v2.13.1 + version: v2.15.0 args: --timeout=5m - name: Run security scan run: | - go install github.com/securego/gosec/v2/cmd/gosec@latest + go install github.com/securego/gosec/v2/cmd/gosec@v2.30.0 # Enforce the scanner's SARIF findings explicitly. This preserves a # strict gate even when GoSec exits non-zero after a successful scan. gosec -no-fail -concurrency=1 -exclude=G301,G306,G304,G204,G104,G302 -exclude-dir=examples -exclude-dir=cmd/examples -fmt sarif -out results.sarif ./... diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7bac3d2..262e03f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -154,15 +154,15 @@ repos: - id: gosec-check name: Gosec Security Check description: Run gosec security scanner - entry: bash -c 'export PATH=$PATH:$(go env GOPATH)/bin; which gosec > /dev/null || go install github.com/securego/gosec/v2/cmd/gosec@latest; gosec -concurrency=1 -exclude=G301,G306,G304,G204,G104,G302 -exclude-dir=examples -exclude-dir=cmd/examples ./...' + entry: go run github.com/securego/gosec/v2/cmd/gosec@v2.30.0 -concurrency=1 -exclude=G301,G306,G304,G204,G104,G302 -exclude-dir=examples -exclude-dir=cmd/examples ./... language: system files: \.go$ pass_filenames: false - id: golangci-lint-local name: golangci-lint (Local) - description: Run golangci-lint with proper PATH - entry: bash -c 'export PATH=$PATH:$(go env GOPATH)/bin; which golangci-lint > /dev/null || go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.1; golangci-lint run --timeout=5m ./pkg/...' + description: Run the pinned golangci-lint release + entry: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 run --timeout=5m ./pkg/... language: system files: \.go$ pass_filenames: false diff --git a/.secrets.baseline b/.secrets.baseline index bed3c67..9d378bc 100644 --- a/.secrets.baseline +++ b/.secrets.baseline @@ -142,14 +142,14 @@ "filename": "README.md", "hashed_secret": "11fa7c37d697f30e6aee828b4426a10f83ab2380", "is_verified": false, - "line_number": 258 + "line_number": 275 }, { "type": "Secret Keyword", "filename": "README.md", "hashed_secret": "c58840dc02f98c5be9f5dfd4dce726f0fbe410f2", "is_verified": false, - "line_number": 274 + "line_number": 291 } ], "docs/PERSISTENCE_GUIDE.md": [ @@ -264,5 +264,5 @@ } ] }, - "generated_at": "2026-08-27T08:44:11Z" + "generated_at": "2026-11-14T21:42:30Z" } diff --git a/Dockerfile b/Dockerfile index c508627..703d2ed 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ # Build stage -FROM golang:1.25.13-alpine AS builder +FROM golang:1.27.4-alpine AS builder # Set working directory WORKDIR /app diff --git a/Makefile b/Makefile index 953994d..1ecf162 100644 --- a/Makefile +++ b/Makefile @@ -101,6 +101,17 @@ test-examples: ## Test all examples @echo "$(BLUE)Testing examples...$(NC)" go test -v $(EXAMPLES_PATH) +.PHONY: test-agent-packages +test-agent-packages: ## Test the Go agent contract, runtime and independent modules + GOWORK=off go test -race -timeout $(TEST_TIMEOUT) ./pkg/agentspec/... ./pkg/agentruntime/... + @for module in agents/designer agents/storymaker agents/habitat examples/11-agent-packages; do \ + (cd "$$module" && GOWORK=off go test -race -timeout $(TEST_TIMEOUT) ./...) || exit $$?; \ + done + +.PHONY: demo-agent-packages +demo-agent-packages: ## Compose the packaged designer and storyteller without a model server + cd examples/11-agent-packages && GOWORK=off go run . + .PHONY: test-cli test-cli: ## Test CLI functionality @echo "$(BLUE)Testing CLI functionality...$(NC)" @@ -190,13 +201,7 @@ docker-logs: ## Show Docker container logs .PHONY: lint lint: ## Run linter @echo "$(BLUE)Running linter...$(NC)" - @if command -v golangci-lint &> /dev/null; then \ - golangci-lint run; \ - else \ - echo "$(YELLOW)golangci-lint not found. Installing...$(NC)"; \ - go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest; \ - golangci-lint run; \ - fi + go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 run .PHONY: fmt fmt: ## Format code @@ -217,13 +222,7 @@ mod-tidy: ## Tidy go modules .PHONY: security security: ## Run security scan @echo "$(BLUE)Running security scan...$(NC)" - @if command -v gosec &> /dev/null; then \ - gosec $(PKG_PATH); \ - else \ - echo "$(YELLOW)gosec not found. Installing...$(NC)"; \ - go install github.com/securego/gosec/v2/cmd/gosec@latest; \ - gosec $(PKG_PATH); \ - fi + go run github.com/securego/gosec/v2/cmd/gosec@v2.30.0 $(PKG_PATH) ##@ Pre-commit diff --git a/README.md b/README.md index 2527e4c..19dd111 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,23 @@ don't hesitate to contribute ! 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. + +```bash +make demo-agent-packages # Reusable habitat → designer + storyteller composition +make test-agent-packages # Contract, runtime and all independent modules +``` + +See the [agent package guide](docs/AGENT_PACKAGES.md) and +[consumer example](examples/11-agent-packages/README.md) 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 diff --git a/agents/designer/LICENSE b/agents/designer/LICENSE new file mode 100644 index 0000000..0727628 --- /dev/null +++ b/agents/designer/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 GoLangGraph Team + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/agents/designer/README.md b/agents/designer/README.md new file mode 100644 index 0000000..e4f86ba --- /dev/null +++ b/agents/designer/README.md @@ -0,0 +1,20 @@ +# Designer agent package + +A Go-native adaptation of the ideation example's habitat designer. Import this +module and register the result of `designer.Package()` with the host runtime. +Its entry point is `designer.AgentID`; the public types are `designer.Input` and +`designer.Output`. + +The package carries an embedded prompt, a default model profile, generated +schemas and the `material_palette` tool. The host supplies model connections and +thread storage. The package does not import the graph engine or the storyteller. + +```sh +go test -race ./... +``` + +The default model profile is configurable by the host. Live-model capabilities +are not certified by the offline tests. See the +[consumer example](../../examples/11-agent-packages/README.md) and +[distribution guide](../../docs/AGENT_PACKAGES.md). Local replaces must be replaced +with a released SDK dependency before this module is published. diff --git a/agents/designer/designer.go b/agents/designer/designer.go new file mode 100644 index 0000000..560f23f --- /dev/null +++ b/agents/designer/designer.go @@ -0,0 +1,115 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +// Package designer packages the habitat designer from the ideation examples as +// a reusable Go agent. Applications supply the model connection and thread store. +package designer + +import ( + "context" + _ "embed" + "encoding/json" + "fmt" + "strings" + + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" +) + +const ( + Module = "github.com/UnicoLab/GoLangGraph/agents/designer" + Version = "v0.1.0" + AgentID = Module + "#design" +) + +//go:embed prompt.txt +var systemPrompt string + +type Input struct { + Message string `json:"message" description:"A short sustainable habitat brief" minLength:"1" maxLength:"4000"` +} + +func (i Input) Validate() error { + if strings.TrimSpace(i.Message) == "" || len(i.Message) > 4000 { + return fmt.Errorf("message must contain 1 to 4000 bytes of text") + } + return nil +} + +type Output struct { + Description string `json:"description" minLength:"1"` + Materials []string `json:"materials"` + Style string `json:"style" enum:"modern,minimalist,futuristic,organic,industrial"` +} + +func (o Output) Validate() error { + if strings.TrimSpace(o.Description) == "" || len(o.Materials) == 0 { + return fmt.Errorf("a description and at least one material are required") + } + switch o.Style { + case "modern", "minimalist", "futuristic", "organic", "industrial": + return nil + default: + return fmt.Errorf("unsupported design style %q", o.Style) + } +} + +type PaletteInput struct { + Focus string `json:"focus" description:"The habitat's energy, water or nature focus" minLength:"1"` +} + +type Palette struct { + Materials []string `json:"materials"` + Style string `json:"style"` + Uses int `json:"uses"` +} + +// Package returns a fresh immutable definition, including its prompt, typed +// schemas, default model profile and implementation of the palette tool. +func Package() (agentspec.Package, error) { + tool, err := agentspec.NewTool("material_palette", "Choose materials for an energy, water or nature-focused habitat.", palette) + if err != nil { + return agentspec.Package{}, err + } + definition, err := agentspec.NewAgent[Input, Output](agentspec.AgentConfig{ + Name: "design", Description: "Design a sustainable habitat from a short brief.", + Prompt: agentspec.Prompt{System: systemPrompt, Model: agentspec.Model{ + Provider: "ollama", Name: "gemma3:1b", Temperature: 0.7, MaxTokens: 1500, + }}, + Tools: []agentspec.Tool{tool}, MaxModelCalls: 5, + }) + if err != nil { + return agentspec.Package{}, err + } + return agentspec.NewPackage(Module, Version, "Reusable sustainable habitat designer.", definition) +} + +func palette(_ context.Context, state agentspec.State, input PaletteInput) (Palette, error) { + uses := 0 + if raw, exists := state.GetValue("palette_uses"); exists { + if err := json.Unmarshal(raw, &uses); err != nil { + return Palette{}, fmt.Errorf("read palette usage: %w", err) + } + } + uses++ + raw, err := json.Marshal(uses) + if err != nil { + return Palette{}, err + } + if err := state.SetValue("palette_uses", raw); err != nil { + return Palette{}, err + } + result := Palette{Materials: []string{"reclaimed timber", "natural insulation", "living roof"}, Style: "organic", Uses: uses} + focus := strings.ToLower(input.Focus) + switch { + case strings.Contains(focus, "energy"), strings.Contains(focus, "solar"): + result.Materials = []string{"photovoltaic panels", "recycled steel", "high-performance insulation"} + result.Style = "futuristic" + case strings.Contains(focus, "water"), strings.Contains(focus, "rain"): + result.Materials = []string{"rainwater cistern", "permeable paving", "reclaimed timber"} + result.Style = "modern" + } + return result, nil +} diff --git a/agents/designer/designer_test.go b/agents/designer/designer_test.go new file mode 100644 index 0000000..300f3e5 --- /dev/null +++ b/agents/designer/designer_test.go @@ -0,0 +1,54 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package designer_test + +import ( + "context" + "encoding/json" + "strings" + "testing" + + "github.com/UnicoLab/GoLangGraph/agents/designer" +) + +type state map[string]json.RawMessage + +func (state) ThreadID() string { return "test" } +func (s state) GetValue(key string) (json.RawMessage, bool) { value, ok := s[key]; return value, ok } +func (s state) SetValue(key string, value json.RawMessage) error { s[key] = value; return nil } + +func TestPackageCarriesPromptTypesAndWorkingTool(t *testing.T) { + pkg, err := designer.Package() + if err != nil { + t.Fatal(err) + } + manifest := pkg.Manifest() + if pkg.AgentID("design") != designer.AgentID || manifest.Version != designer.Version || !strings.Contains(manifest.Agents[0].Prompt.System, "sustainable architecture") { + t.Fatalf("incomplete package: %+v", manifest) + } + definition := pkg.Definitions()[0] + if err := definition.ValidateInput(json.RawMessage(`{"message":" "}`)); err == nil { + t.Fatal("blank brief accepted") + } + if err := definition.ValidateOutput(json.RawMessage(`{"description":"A home","materials":["wood"],"style":"invalid"}`)); err == nil { + t.Fatal("invalid style accepted") + } + values := state{} + for i := 1; i <= 2; i++ { + raw, err := definition.Tools()[0].Execute(context.Background(), values, json.RawMessage(`{"focus":"solar energy"}`)) + if err != nil { + t.Fatal(err) + } + var palette designer.Palette + if err := json.Unmarshal(raw, &palette); err != nil { + t.Fatal(err) + } + if palette.Uses != i || palette.Style != "futuristic" || palette.Materials[0] != "photovoltaic panels" { + t.Fatalf("unexpected palette: %+v", palette) + } + } +} diff --git a/agents/designer/go.mod b/agents/designer/go.mod new file mode 100644 index 0000000..6cd9ec1 --- /dev/null +++ b/agents/designer/go.mod @@ -0,0 +1,8 @@ +module github.com/UnicoLab/GoLangGraph/agents/designer + +go 1.23.0 + +require github.com/UnicoLab/GoLangGraph v0.0.0 + +// Local development until the root SDK is released. See docs/AGENT_PACKAGES.md. +replace github.com/UnicoLab/GoLangGraph => ../.. diff --git a/agents/designer/prompt.txt b/agents/designer/prompt.txt new file mode 100644 index 0000000..a0e4697 --- /dev/null +++ b/agents/designer/prompt.txt @@ -0,0 +1,8 @@ +You are a creative designer specializing in sustainable architecture and future habitats. +Develop a practical concept from the user's message. Consider materials, energy, +water and integration with the natural environment. Use material_palette when +choosing materials; its usage counter is internal bookkeeping, not part of the design. + +Return description, materials and style. The style must be one of modern, +minimalist, futuristic, organic or industrial. Explain the concept in the +description. Do not claim measured performance or fabricate an image. diff --git a/agents/habitat/LICENSE b/agents/habitat/LICENSE new file mode 100644 index 0000000..0727628 --- /dev/null +++ b/agents/habitat/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 GoLangGraph Team + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/agents/habitat/README.md b/agents/habitat/README.md new file mode 100644 index 0000000..aede6ff --- /dev/null +++ b/agents/habitat/README.md @@ -0,0 +1,19 @@ +# Habitat agent package + +An independently versioned Go module that composes the designer and storymaker +agents. Its `#create` entry is a Go handler. Each parent thread owns a persistent, +isolated designer child and storymaker child; the host resolves both declared +dependencies before registration succeeds. + +Register `designer.Package()`, `storymaker.Package()` and `habitat.Package()` in +one batch, then call `agentruntime.RunTyped[habitat.Input, habitat.Output]` on a +habitat thread. The handler passes the completed design into the storymaker. +The runtime validates both boundaries and records child request IDs in its trace. + +This module imports the two agents and `pkg/agentspec`. It does not import +GoLangGraph's graph engine, provider clients or persistence adapters. It can be +reused by another host that implements the Go contract. + +Run the full consuming application with `make demo-agent-packages` from the +repository root. These are local development versions, not published releases; +see [the package guide](../../docs/AGENT_PACKAGES.md) for release steps. diff --git a/agents/habitat/go.mod b/agents/habitat/go.mod new file mode 100644 index 0000000..ff32bd6 --- /dev/null +++ b/agents/habitat/go.mod @@ -0,0 +1,15 @@ +module github.com/UnicoLab/GoLangGraph/agents/habitat + +go 1.23.0 + +require ( + github.com/UnicoLab/GoLangGraph v0.0.0 + github.com/UnicoLab/GoLangGraph/agents/designer v0.1.0 + github.com/UnicoLab/GoLangGraph/agents/storymaker v0.1.0 +) + +replace github.com/UnicoLab/GoLangGraph => ../.. + +replace github.com/UnicoLab/GoLangGraph/agents/designer => ../designer + +replace github.com/UnicoLab/GoLangGraph/agents/storymaker => ../storymaker diff --git a/agents/habitat/habitat.go b/agents/habitat/habitat.go new file mode 100644 index 0000000..47d2db7 --- /dev/null +++ b/agents/habitat/habitat.go @@ -0,0 +1,62 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +// Package habitat is a reusable composition of two independently versioned +// agents. It depends on their contracts and the SDK, not an execution engine. +package habitat + +import ( + "context" + + "github.com/UnicoLab/GoLangGraph/agents/designer" + "github.com/UnicoLab/GoLangGraph/agents/storymaker" + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" +) + +const ( + Module = "github.com/UnicoLab/GoLangGraph/agents/habitat" + Version = "v0.1.0" + AgentID = Module + "#create" +) + +type Input = designer.Input + +type Output struct { + Design designer.Output `json:"design"` + Story storymaker.Output `json:"story"` +} + +// Package declares dependencies, but never installs or creates them itself. +// The host registers all three modules; each habitat thread owns two children. +func Package() (agentspec.Package, error) { + design, err := agentspec.NewSubagent[designer.Input, designer.Output]("designer", "Design the habitat", designer.AgentID, designer.Version) + if err != nil { + return agentspec.Package{}, err + } + story, err := agentspec.NewSubagent[storymaker.Input, storymaker.Output]("storymaker", "Tell the habitat's story", storymaker.AgentID, storymaker.Version) + if err != nil { + return agentspec.Package{}, err + } + definition, err := agentspec.NewHandler[Input, Output](agentspec.HandlerConfig{ + Name: "create", Description: "Design a sustainable habitat and tell its story", Subagents: []agentspec.Subagent{design, story}, + }, func(ctx context.Context, execution agentspec.Execution, input Input) (Output, error) { + design, err := agentspec.CallAgent[designer.Input, designer.Output](ctx, execution, "designer", input) + if err != nil { + return Output{}, err + } + story, err := agentspec.CallAgent[storymaker.Input, storymaker.Output](ctx, execution, "storymaker", storymaker.Input{ + StoryPrompt: "A resident's first morning in the habitat", DesignDescription: design.Description, + }) + if err != nil { + return Output{}, err + } + return Output{Design: design, Story: story}, nil + }) + if err != nil { + return agentspec.Package{}, err + } + return agentspec.NewPackage(Module, Version, "A composable habitat design and storytelling workflow", definition) +} diff --git a/agents/habitat/habitat_test.go b/agents/habitat/habitat_test.go new file mode 100644 index 0000000..3d042b8 --- /dev/null +++ b/agents/habitat/habitat_test.go @@ -0,0 +1,41 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package habitat + +import ( + "encoding/json" + "testing" + + "github.com/UnicoLab/GoLangGraph/agents/designer" + "github.com/UnicoLab/GoLangGraph/agents/storymaker" + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" +) + +func TestCompositionDeclaresExactDependencyContracts(t *testing.T) { + pkg, err := Package() + if err != nil { + t.Fatal(err) + } + data, err := json.Marshal(pkg.Manifest()) + if err != nil { + t.Fatal(err) + } + manifest, err := agentspec.ParseManifest(data) + if err != nil { + t.Fatal(err) + } + agent := manifest.Agents[0] + if agent.Kind != "handler" || agent.Prompt != nil || len(agent.Subagents) != 2 { + t.Fatalf("incorrect composition: %+v", agent) + } + if agent.Subagents[0].AgentID != designer.AgentID || agent.Subagents[1].AgentID != storymaker.AgentID { + t.Fatal("dependency identity changed") + } + if err := pkg.Definitions()[0].ValidateInput(json.RawMessage(`{"message":""}`)); err == nil { + t.Fatal("designer input validation lost through alias") + } +} diff --git a/agents/storymaker/LICENSE b/agents/storymaker/LICENSE new file mode 100644 index 0000000..0727628 --- /dev/null +++ b/agents/storymaker/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 GoLangGraph Team + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/agents/storymaker/README.md b/agents/storymaker/README.md new file mode 100644 index 0000000..fe1364d --- /dev/null +++ b/agents/storymaker/README.md @@ -0,0 +1,18 @@ +# Storymaker agent package + +A Go-native adaptation of the ideation example's storyteller. Import this module +and register the result of `storymaker.Package()` with the host runtime. Its entry +point is `storymaker.AgentID`; public types are `storymaker.Input` and +`storymaker.Output`. + +The package carries an embedded prompt, a default model profile, generated +schemas and the `story_outline` tool. It accepts a design description as ordinary +input and does not depend on the designer module or graph engine. + +```sh +go test -race ./... +``` + +See the [consumer example](../../examples/11-agent-packages/README.md) and +[distribution guide](../../docs/AGENT_PACKAGES.md). Local replaces must be replaced +with a released SDK dependency before this module is published. diff --git a/agents/storymaker/go.mod b/agents/storymaker/go.mod new file mode 100644 index 0000000..b3766c4 --- /dev/null +++ b/agents/storymaker/go.mod @@ -0,0 +1,8 @@ +module github.com/UnicoLab/GoLangGraph/agents/storymaker + +go 1.23.0 + +require github.com/UnicoLab/GoLangGraph v0.0.0 + +// Local development until the root SDK is released. See docs/AGENT_PACKAGES.md. +replace github.com/UnicoLab/GoLangGraph => ../.. diff --git a/agents/storymaker/prompt.txt b/agents/storymaker/prompt.txt new file mode 100644 index 0000000..bfaf67f --- /dev/null +++ b/agents/storymaker/prompt.txt @@ -0,0 +1,7 @@ +You are a storyteller helping people imagine everyday life in sustainable habitats. +Use the supplied design_description as the setting and story_prompt as the theme. +Use story_outline to organize a narrative with a resident, a daily challenge and +a community connection. Treat stories as imagined scenarios, not factual predictions. + +Return title, story, themes and moral. Keep the story grounded in the supplied +design and explain the sustainability ideas through the characters' experiences. diff --git a/agents/storymaker/storymaker.go b/agents/storymaker/storymaker.go new file mode 100644 index 0000000..93159e1 --- /dev/null +++ b/agents/storymaker/storymaker.go @@ -0,0 +1,89 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +// Package storymaker packages the storyteller from the ideation examples as a +// reusable Go agent. It has no dependency on the designer module or graph engine. +package storymaker + +import ( + "context" + _ "embed" + "fmt" + "strings" + + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" +) + +const ( + Module = "github.com/UnicoLab/GoLangGraph/agents/storymaker" + Version = "v0.1.0" + AgentID = Module + "#story" +) + +//go:embed prompt.txt +var systemPrompt string + +type Input struct { + StoryPrompt string `json:"story_prompt"` + DesignDescription string `json:"design_description"` +} + +func (i Input) Validate() error { + if strings.TrimSpace(i.StoryPrompt) == "" || strings.TrimSpace(i.DesignDescription) == "" { + return fmt.Errorf("story_prompt and design_description must contain text") + } + return nil +} + +type Output struct { + Title string `json:"title"` + Story string `json:"story"` + Themes []string `json:"themes"` + Moral string `json:"moral"` +} + +func (o Output) Validate() error { + if strings.TrimSpace(o.Title) == "" || strings.TrimSpace(o.Story) == "" || strings.TrimSpace(o.Moral) == "" || len(o.Themes) == 0 { + return fmt.Errorf("title, story, themes and moral are required") + } + return nil +} + +type OutlineInput struct { + Topic string `json:"topic"` +} + +type Outline struct { + Beats []string `json:"beats"` +} + +func Package() (agentspec.Package, error) { + tool, err := agentspec.NewTool("story_outline", "Build a three-part narrative outline from a theme.", + func(_ context.Context, _ agentspec.State, input OutlineInput) (Outline, error) { + if strings.TrimSpace(input.Topic) == "" { + return Outline{}, fmt.Errorf("topic must contain text") + } + return Outline{Beats: []string{ + "Introduce a resident discovering " + input.Topic, + "Show a daily challenge resolved through thoughtful habitat design", + "Connect the resident's experience to the wider community", + }}, nil + }) + if err != nil { + return agentspec.Package{}, err + } + definition, err := agentspec.NewAgent[Input, Output](agentspec.AgentConfig{ + Name: "story", Description: "Turn a habitat concept into a human-centered narrative.", + Prompt: agentspec.Prompt{System: systemPrompt, Model: agentspec.Model{ + Provider: "ollama", Name: "gemma3:1b", Temperature: 0.7, MaxTokens: 1800, + }}, + Tools: []agentspec.Tool{tool}, MaxModelCalls: 5, + }) + if err != nil { + return agentspec.Package{}, err + } + return agentspec.NewPackage(Module, Version, "Reusable storyteller for sustainable habitat concepts.", definition) +} diff --git a/agents/storymaker/storymaker_test.go b/agents/storymaker/storymaker_test.go new file mode 100644 index 0000000..5c9329c --- /dev/null +++ b/agents/storymaker/storymaker_test.go @@ -0,0 +1,51 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package storymaker_test + +import ( + "context" + "encoding/json" + "strings" + "testing" + + "github.com/UnicoLab/GoLangGraph/agents/storymaker" +) + +type state struct{} + +func (state) ThreadID() string { return "test" } +func (state) GetValue(string) (json.RawMessage, bool) { return nil, false } +func (state) SetValue(string, json.RawMessage) error { return nil } + +func TestPackageCarriesPromptTypesAndWorkingTool(t *testing.T) { + pkg, err := storymaker.Package() + if err != nil { + t.Fatal(err) + } + if pkg.AgentID("story") != storymaker.AgentID || !strings.Contains(pkg.Manifest().Agents[0].Prompt.System, "sustainable habitats") { + t.Fatal("missing package assets") + } + definition := pkg.Definitions()[0] + if err := definition.ValidateInput(json.RawMessage(`{"story_prompt":"hello"}`)); err == nil { + t.Fatal("missing design accepted") + } + tool := definition.Tools()[0] + if _, err := tool.Execute(context.Background(), state{}, json.RawMessage(`{"topic":" "}`)); err == nil { + t.Fatal("blank topic accepted") + } + raw, err := tool.Execute(context.Background(), state{}, json.RawMessage(`{"topic":"a shared garden"}`)) + if err != nil { + t.Fatal(err) + } + var outline storymaker.Outline + if err := json.Unmarshal(raw, &outline); err != nil { + t.Fatal(err) + } + if len(outline.Beats) != 3 || !strings.Contains(outline.Beats[0], "a shared garden") { + t.Fatalf("invalid outline: %+v", outline) + } +} diff --git a/cmd/golanggraph/main.go b/cmd/golanggraph/main.go index 3be9c0e..aa9e126 100644 --- a/cmd/golanggraph/main.go +++ b/cmd/golanggraph/main.go @@ -509,6 +509,7 @@ func init() { // Add subcommands rootCmd.AddCommand(initCmd) + rootCmd.AddCommand(newPackageCommand()) rootCmd.AddCommand(buildCmd) rootCmd.AddCommand(dockerCmd) rootCmd.AddCommand(deployCmd) @@ -2194,7 +2195,7 @@ database: // agentDockerfile is the Dockerfile generated for a normal build. const agentDockerfile = `# Production Dockerfile for GoLangGraph Agent -FROM golang:1.21-alpine AS builder +FROM golang:1.27.4-alpine AS builder # Set working directory WORKDIR /app @@ -2263,7 +2264,7 @@ CMD ["serve", "--host", "0.0.0.0", "--port", "8080"] // mounted by the generated Compose or Kubernetes artifact, so it deliberately // does not COPY a local configs directory from the build context. const multiAgentDockerfile = `# Production Dockerfile for a GoLangGraph multi-agent server -FROM golang:1.25.13-alpine AS builder +FROM golang:1.27.4-alpine AS builder WORKDIR /app RUN apk add --no-cache git ca-certificates tzdata @@ -2288,7 +2289,7 @@ CMD ["serve"] // distrolessDockerfile is the Dockerfile generated for --distroless builds. const distrolessDockerfile = `# Distroless Dockerfile for GoLangGraph Agent -FROM golang:1.21-alpine AS builder +FROM golang:1.27.4-alpine AS builder # Set working directory WORKDIR /app diff --git a/cmd/golanggraph/package_command.go b/cmd/golanggraph/package_command.go new file mode 100644 index 0000000..c2bc8aa --- /dev/null +++ b/cmd/golanggraph/package_command.go @@ -0,0 +1,152 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package main + +import ( + "bytes" + "embed" + "encoding/json" + "fmt" + "go/format" + "io" + "io/fs" + "os" + "path/filepath" + "strconv" + "strings" + "text/template" + + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" + "github.com/spf13/cobra" +) + +//go:embed package_templates +var packageTemplates embed.FS + +func newPackageCommand() *cobra.Command { + command := &cobra.Command{Use: "package", Short: "Create and inspect Go-native agent packages (experimental)"} + var directory, sdkDir, sdkVersion string + init := &cobra.Command{ + Use: "init ", Short: "Create a standalone agent module in a new directory", Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + if err := scaffoldPackage(args[0], directory, sdkDir, sdkVersion); err != nil { + return err + } + cmd.Printf("Created agent module %s in %s\nRun go test ./... and go run ./cmd/manifest from that directory.\n", args[0], directory) + return nil + }, + } + init.Flags().StringVar(&directory, "dir", "", "New directory to create (required)") + init.Flags().StringVar(&sdkDir, "sdk-dir", "", "Local GoLangGraph checkout containing the agent SDK") + init.Flags().StringVar(&sdkVersion, "sdk-version", "", "Released GoLangGraph SDK version; mutually exclusive with --sdk-dir") + inspect := &cobra.Command{ + Use: "inspect ", Short: "Validate a package manifest without executing its code", Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + file, err := os.Open(args[0]) + if err != nil { + return err + } + defer file.Close() + const maximum = 4 << 20 + data, err := io.ReadAll(io.LimitReader(file, maximum+1)) + if err != nil { + return err + } + if len(data) > maximum { + return fmt.Errorf("manifest exceeds 4 MiB") + } + manifest, err := agentspec.ParseManifest(data) + if err != nil { + return err + } + encoder := json.NewEncoder(cmd.OutOrStdout()) + encoder.SetIndent("", " ") + return encoder.Encode(manifest) + }, + } + command.AddCommand(init, inspect) + return command +} + +func scaffoldPackage(module, directory, sdkDir, sdkVersion string) error { + if err := agentspec.ValidateIdentity(module, "v0.1.0"); err != nil { + return err + } + if directory == "" || (sdkDir == "") == (sdkVersion == "") { + return fmt.Errorf("provide --dir and exactly one of --sdk-dir or --sdk-version") + } + if sdkDir != "" { + absolute, err := filepath.Abs(sdkDir) + if err != nil { + return err + } + sdkDir = absolute + if _, err := os.Stat(filepath.Join(sdkDir, "pkg", "agentspec", "spec.go")); err != nil { + return fmt.Errorf("SDK directory must contain pkg/agentspec/spec.go: %w", err) + } + sdkVersion = "v0.0.0" + } else if err := agentspec.ValidateIdentity("github.com/UnicoLab/GoLangGraph", sdkVersion); err != nil { + return err + } + data := struct{ Module, ModuleQuote, SDKDirQuote, SDKVersion string }{module, strconv.Quote(module), strconv.Quote(filepath.ToSlash(sdkDir)), sdkVersion} + // Render and format everything before creating the destination. Mkdir is + // exclusive, so even a concurrent creator cannot have its files overwritten. + files := make(map[string][]byte) + err := fs.WalkDir(packageTemplates, "package_templates", func(path string, entry fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + if entry.IsDir() { + return nil + } + source, err := packageTemplates.ReadFile(path) + if err != nil { + return err + } + tmpl, err := template.New(path).Parse(string(source)) + if err != nil { + return err + } + var buffer bytes.Buffer + if renderErr := tmpl.Execute(&buffer, data); renderErr != nil { + return renderErr + } + name := strings.TrimSuffix(strings.TrimPrefix(path, "package_templates/"), ".tmpl") + content := buffer.Bytes() + if strings.HasSuffix(name, ".go") { + content, err = format.Source(content) + if err != nil { + return err + } + } + files[name] = content + return nil + }) + if err != nil { + return err + } + if err := os.Mkdir(directory, 0750); err != nil { + return fmt.Errorf("create new package directory: %w", err) + } + complete := false + defer func() { + if !complete { + _ = os.RemoveAll(directory) + } + }() + for name, content := range files { + path := filepath.Join(directory, filepath.FromSlash(name)) + if err := os.MkdirAll(filepath.Dir(path), 0750); err != nil { + return err + } + if err := os.WriteFile(path, content, 0600); err != nil { + return err + } + } + complete = true + return nil +} diff --git a/cmd/golanggraph/package_command_test.go b/cmd/golanggraph/package_command_test.go new file mode 100644 index 0000000..12113ab --- /dev/null +++ b/cmd/golanggraph/package_command_test.go @@ -0,0 +1,132 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package main + +import ( + "bytes" + "context" + "encoding/json" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" +) + +func TestScaffoldBuildsStandaloneModuleAndInspectsManifest(t *testing.T) { + sdk, err := filepath.Abs(filepath.Join("..", "..")) + if err != nil { + t.Fatal(err) + } + dir := filepath.Join(t.TempDir(), "module with spaces") + command := newPackageCommand() + var stdout bytes.Buffer + command.SetOut(&stdout) + command.SetArgs([]string{"init", "example.com/agent", "--dir", dir, "--sdk-dir", sdk}) + if err := command.Execute(); err != nil { + t.Fatal(err) + } + if !strings.Contains(stdout.String(), "Created agent module") { + t.Fatal(stdout.String()) + } + // A fresh CI toolchain also compiles the standard library for the generated + // module's non-race subprocesses. Allow cold builds on shared runners. + ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute) + defer cancel() + run := func(args ...string) []byte { + t.Helper() + cmd := exec.CommandContext(ctx, "go", args...) + cmd.Dir = dir + cmd.Env = append(os.Environ(), "GOWORK=off", "GOFLAGS=-mod=readonly") + data, err := cmd.CombinedOutput() + if err != nil { + t.Fatalf("generated module %v: %v\n%s", args, err, data) + } + return data + } + run("test", "./...") + manifest := run("run", "./cmd/manifest") + path := filepath.Join(dir, "manifest.json") + if err := os.WriteFile(path, manifest, 0600); err != nil { + t.Fatal(err) + } + inspect := newPackageCommand() + stdout.Reset() + inspect.SetOut(&stdout) + inspect.SetArgs([]string{"inspect", path}) + if err := inspect.Execute(); err != nil { + t.Fatal(err) + } + parsed, err := agentspec.ParseManifest(stdout.Bytes()) + if err != nil || parsed.Module != "example.com/agent" || len(parsed.Agents) != 2 { + t.Fatalf("bad manifest: %+v %v", parsed, err) + } + if err := scaffoldPackage("example.com/agent", dir, sdk, ""); err == nil { + t.Fatal("overwrote existing directory") + } + after, err := os.ReadFile(path) + if err != nil || !bytes.Equal(manifest, after) { + t.Fatal("existing module changed") + } +} + +func TestScaffoldRejectsInvalidOptionsWithoutCreatingDirectory(t *testing.T) { + for _, test := range []struct{ module, sdkDir, sdkVersion string }{ + {"example.com/agent", "", ""}, + {"example.com/agent", "missing", "v0.1.0"}, + {"example.com/agent", "missing", ""}, + {"example.com/agent", "", "latest"}, + {"example.com/agent\nreplace injected", "", "v0.1.0"}, + {"example.com/agent\"", "", "v0.1.0"}, + } { + dir := filepath.Join(t.TempDir(), "agent") + if err := scaffoldPackage(test.module, dir, test.sdkDir, test.sdkVersion); err == nil { + t.Fatalf("accepted %+v", test) + } + if _, err := os.Stat(dir); !os.IsNotExist(err) { + t.Fatalf("invalid scaffold wrote files: %v", err) + } + } + dir := filepath.Join(t.TempDir(), "released") + if err := scaffoldPackage("example.com/agent", dir, "", "v0.2.0"); err != nil { + t.Fatal(err) + } + mod, err := os.ReadFile(filepath.Join(dir, "go.mod")) + if err != nil || strings.Contains(string(mod), "replace") || !strings.Contains(string(mod), "v0.2.0") { + t.Fatalf("release scaffold: %s %v", mod, err) + } +} + +func TestInspectRejectsUnknownFieldsAndOversizedFiles(t *testing.T) { + for _, data := range [][]byte{[]byte(`{"contract_version":"wrong"}`), []byte(strings.Repeat(" ", (4<<20)+1)), []byte(`{"module":"a","module":"b"}`)} { + path := filepath.Join(t.TempDir(), "bad.json") + if err := os.WriteFile(path, data, 0600); err != nil { + t.Fatal(err) + } + command := newPackageCommand() + command.SetArgs([]string{"inspect", path}) + command.SetOut(&bytes.Buffer{}) + command.SetErr(&bytes.Buffer{}) + if err := command.Execute(); err == nil { + t.Fatal("invalid manifest accepted") + } + } + // Help does not require a provider or execute package code. + command := newPackageCommand() + var output bytes.Buffer + command.SetOut(&output) + command.SetArgs([]string{"--help"}) + if err := command.Execute(); err != nil { + t.Fatal(err) + } + if json.Valid(output.Bytes()) || !strings.Contains(output.String(), "inspect") { + t.Fatal("missing package help") + } +} diff --git a/cmd/golanggraph/package_templates/README.md.tmpl b/cmd/golanggraph/package_templates/README.md.tmpl new file mode 100644 index 0000000..78e4ef6 --- /dev/null +++ b/cmd/golanggraph/package_templates/README.md.tmpl @@ -0,0 +1,23 @@ +# {{.Module}} + +A Go-native agent module with two entries: `#assist` uses a model and `#echo` +runs Go code. Both use a typed tool and strict input/output validation. + +```sh +go test ./... +go run ./cmd/manifest > manifest.json +golanggraph package inspect manifest.json +``` + +Import this module into a host, call `Package()`, register it with +`agentruntime.Runtime`, then create a thread and invoke it. Configure a tool-capable +model for `#assist` through the host's `Config.Models` override. Registration of +this package requires a provider because it includes the prompt entry. + +The prompt is embedded in the binary; the manifest contains metadata, not code. +Edit the types, prompt, tools and handler to implement your domain. Keep mutable +conversation data in the supplied execution state, not package globals. + +Before publishing, replace local SDK requirements/replaces with a released SDK, +run `go mod tidy`, choose a module version matching `Version`, add a license, and +tag the release. This scaffold is not a published module or a sandbox. diff --git a/cmd/golanggraph/package_templates/agent.go.tmpl b/cmd/golanggraph/package_templates/agent.go.tmpl new file mode 100644 index 0000000..304f1b7 --- /dev/null +++ b/cmd/golanggraph/package_templates/agent.go.tmpl @@ -0,0 +1,52 @@ +package agentpkg + +import ( + "context" + _ "embed" + "encoding/json" + "strings" + + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" +) + +const Module = {{.ModuleQuote}} +const Version = "v0.1.0" + +//go:embed prompt.txt +var prompt string + +type Input struct { + Message string `json:"message" description:"The request to process" minLength:"1" maxLength:"4000"` +} + +type Output struct { + Message string `json:"message" minLength:"1"` +} + +// Package exposes both a model-driven entry and a pure Go handler. The host +// supplies provider connections, creates threads, and owns persistence. +func Package() (agentspec.Package, error) { + tool, err := agentspec.NewTool("normalize", "Trim surrounding whitespace", func(_ context.Context, _ agentspec.State, input Input) (Output, error) { + return Output{Message: strings.TrimSpace(input.Message)}, nil + }) + if err != nil { return agentspec.Package{}, err } + assistant, err := agentspec.NewAgent[Input, Output](agentspec.AgentConfig{ + Name: "assist", Description: "Answer a request with a model", + Prompt: agentspec.Prompt{System: prompt, Model: agentspec.Model{Provider: "ollama", Name: "configure-a-tool-capable-model", MaxTokens: 1024}}, + Tools: []agentspec.Tool{tool}, MaxModelCalls: 4, + }) + if err != nil { return agentspec.Package{}, err } + echo, err := agentspec.NewHandler[Input, Output](agentspec.HandlerConfig{ + Name: "echo", Description: "Normalize a message using Go code", Tools: []agentspec.Tool{tool}, + }, func(ctx context.Context, execution agentspec.Execution, input Input) (Output, error) { + data, err := json.Marshal(input) + if err != nil { return Output{}, err } + data, err = execution.InvokeTool(ctx, "normalize", data) + if err != nil { return Output{}, err } + var output Output + err = json.Unmarshal(data, &output) + return output, err + }) + if err != nil { return agentspec.Package{}, err } + return agentspec.NewPackage(Module, Version, "A reusable Go agent package", assistant, echo) +} diff --git a/cmd/golanggraph/package_templates/agent_test.go.tmpl b/cmd/golanggraph/package_templates/agent_test.go.tmpl new file mode 100644 index 0000000..61b93f5 --- /dev/null +++ b/cmd/golanggraph/package_templates/agent_test.go.tmpl @@ -0,0 +1,21 @@ +package agentpkg + +import ( + "encoding/json" + "testing" + + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" +) + +func TestPackageContract(t *testing.T) { + pkg, err := Package() + if err != nil { t.Fatal(err) } + data, err := json.Marshal(pkg.Manifest()) + if err != nil { t.Fatal(err) } + if _, err := agentspec.ParseManifest(data); err != nil { t.Fatal(err) } + for _, definition := range pkg.Definitions() { + if err := definition.ValidateInput(json.RawMessage(`{"message":"hello"}`)); err != nil { t.Fatal(err) } + if err := definition.ValidateInput(json.RawMessage(`{"message":""}`)); err == nil { t.Fatal("empty message accepted") } + if err := definition.ValidateInput(json.RawMessage(`{"unknown":true}`)); err == nil { t.Fatal("unknown field accepted") } + } +} diff --git a/cmd/golanggraph/package_templates/cmd/manifest/main.go.tmpl b/cmd/golanggraph/package_templates/cmd/manifest/main.go.tmpl new file mode 100644 index 0000000..5c1f408 --- /dev/null +++ b/cmd/golanggraph/package_templates/cmd/manifest/main.go.tmpl @@ -0,0 +1,19 @@ +package main + +import ( + "encoding/json" + "fmt" + "os" + + agentpkg {{.ModuleQuote}} +) + +func main() { + pkg, err := agentpkg.Package() + if err == nil { + encoder := json.NewEncoder(os.Stdout) + encoder.SetIndent("", " ") + err = encoder.Encode(pkg.Manifest()) + } + if err != nil { fmt.Fprintln(os.Stderr, err); os.Exit(1) } +} diff --git a/cmd/golanggraph/package_templates/go.mod.tmpl b/cmd/golanggraph/package_templates/go.mod.tmpl new file mode 100644 index 0000000..372d2a9 --- /dev/null +++ b/cmd/golanggraph/package_templates/go.mod.tmpl @@ -0,0 +1,9 @@ +module {{.Module}} + +go 1.23.0 + +require github.com/UnicoLab/GoLangGraph {{.SDKVersion}} +{{if ne .SDKDirQuote "\"\""}} +// Development only: replace with a released SDK version before publishing. +replace github.com/UnicoLab/GoLangGraph => {{.SDKDirQuote}} +{{end}} diff --git a/cmd/golanggraph/package_templates/prompt.txt.tmpl b/cmd/golanggraph/package_templates/prompt.txt.tmpl new file mode 100644 index 0000000..8227284 --- /dev/null +++ b/cmd/golanggraph/package_templates/prompt.txt.tmpl @@ -0,0 +1,2 @@ +Answer the user's request concisely. The normalize tool can trim whitespace. +Return the final answer in the required JSON shape with a non-empty message. diff --git a/docs/AGENT_PACKAGES.md b/docs/AGENT_PACKAGES.md new file mode 100644 index 0000000..88e0fa7 --- /dev/null +++ b/docs/AGENT_PACKAGES.md @@ -0,0 +1,283 @@ +# Go-native agent packages (experimental) + +An agent package contains typed contracts, Go tools, embedded prompts, model +profiles, Go handlers and declared child agents. It is distributed as a Go module +and linked into a consuming application. GoLangGraph supplies graph execution, +isolated persistent threads, dependency resolution and request deduplication. + +This is a Go-native exploration of the authoring and composition ideas in the +[Standard Agent Specification](https://standardagentspec.org/). It has its own +`golanggraph.agent/v1alpha1` contract. It does not execute TypeScript, load npm +packages or claim compatibility with that specification. + +## Run the complete example + +From the repository root: + +```sh +make demo-agent-packages +make test-agent-packages +``` + +The application imports three independently versioned agent modules: + +- `agents/designer`: adapts the sustainable habitat designer from the ideation + examples, including a material-selection tool and an embedded prompt. +- `agents/storymaker`: adapts the storyteller, including an outline tool and its + own embedded prompt. It does not import the designer. +- `agents/habitat`: a reusable Go handler that declares both agents as children + and passes the designer's typed output into the storymaker. +- `examples/11-agent-packages`: the consuming application. It supplies model + connections and storage. Its optional `-workflow graph` mode also demonstrates + application-owned composition with a two-node GoLangGraph graph. + +The default demo uses a clearly identified deterministic model double. Package +registration, input/output validation, graph execution, tool execution and +checkpointing are real. The default run needs no credentials or services and +creates no persistent files. See the example README for live Ollama and restart +commands. + +## Contract and runtime boundary + +`pkg/agentspec` depends only on the Go standard library. It defines immutable +packages, definitions, model profiles, tools, child dependencies and generated +schemas. None of the three agent modules imports the graph engine, persistence +or provider clients. Habitat imports its dependencies' exported contracts. + +`pkg/agentruntime` is the GoLangGraph adapter. It executes prompt turns as a graph: + +```text +model -> tools -> model -> ... -> done +``` + +Go handlers run as a graph node and can call their declared tools and children. +Prompt agents see declared children as tools with the child's input schema. A +child gets one persistent thread per parent thread and alias, with its own model, +history, values and run journal. Dependency cycles are rejected. A dependency tree +is limited to 128 threads and a turn to 256 tool/child invocations; prompt turns +also have a configurable model-call budget of 1–100. + +The outer application can compose packaged agents using arbitrary GoLangGraph +workflows. The existing `pkg/agent` API and its behavior remain available. + +| Package supplies | Host supplies | +| --- | --- | +| Embedded prompt and tool implementations | Model connections and credentials | +| Typed contracts, schema constraints and semantic validation | Conversation instances and storage | +| Default model profile and model-call budget | Explicit model overrides for new threads | +| Go handlers and exact child dependencies | Dependency validation and isolated child instances | +| Module/version identity and entry-point metadata | Run journal, deployment and UI | + +Agent references have the form `module/path#entry_name`. A host accepts one +version of a module at a time. Threads record both the package version and their +effective model profile. Each thread also pins a SHA-256 fingerprint of its +declarative contract: prompt, schemas, tools, model defaults and child references. +Changed versions or fingerprints fail before execution. The fingerprint cannot +detect changes inside Go callbacks; versioning executable behavior remains the +package author's responsibility. It is not an artifact signature or sandbox. + +## Author a package + +Define ordinary Go input/output structs with JSON tags. Use +`agentspec.NewTool[Input, Output]` for tools and +`agentspec.NewAgent[Input, Output]` for prompt agents. Export a `Package()` function +that returns `agentspec.NewPackage(modulePath, version, description, definition)`. + +Use `agentspec.NewHandler[Input, Output]` for a turn implemented in ordinary Go. +It receives an `agentspec.Execution` with thread-local JSON values and access to +declared tools and agents. A host containing only handler agents needs no model +provider. Declare children with `agentspec.NewSubagent[Input, Output]`, including +their qualified entry ID and exact package version. Call them through +`agentspec.CallAgent[Input, Output](ctx, execution, alias, input)`. The habitat +module demonstrates the complete pattern. + +Scaffold a new module from the repository root: + +```sh +go run ./cmd/golanggraph package init example.com/my-agent \ + --dir /tmp/my-agent --sdk-dir "$PWD" +cd /tmp/my-agent +go test ./... +go run ./cmd/manifest > manifest.json +``` + +The generator creates a prompt entry, Go handler, typed tool, embedded prompt, +tests and manifest exporter. It refuses to overwrite an existing directory. +After building the CLI, inspect the exported data with +`golanggraph package inspect manifest.json`. Inspection validates the contract +without loading code; exporting a manifest executes the module you imported. +Once an SDK release exists, use `--sdk-version ` instead of +`--sdk-dir` to scaffold without a local replace. + +The designer and storyteller modules are complete authoring examples. Their +`prompt.txt` assets are embedded with `go:embed`, so deployed binaries do not need +the source tree or a special working directory. + +Generated schemas support plain structs, slices, strings, booleans and numeric +types. Exported fields are required unless tagged `omitempty`; undeclared fields +and null values are rejected. Pointer types, maps, byte slices, embedded fields, +custom JSON encoders and JSON tag options other than `omitempty` are currently +unsupported and fail definition creation. An empty array must be a non-nil slice. + +String fields support `description`, `enum` (comma-separated values), `minLength` +and `maxLength` tags. These constraints appear in the exported schema and are +enforced at runtime; lengths count Unicode characters. Duplicate JSON keys, +unknown fields, trailing values and excessive nesting are rejected. Schemas are +limited to 32 levels and incoming JSON to 64. Invalid tags fail construction. + +For domain rules, implement `Validate() error` on an input/output type. These +rules run before invoking tools or models and before accepting outputs, but are +not automatically inferred into the structural schema. Use schema tags for rules +that a model should see and `Validate` for additional domain rules. + +Tool functions receive an invocation-scoped `agentspec.State` for JSON values. +Keep per-conversation data there. Do not capture mutable conversation data in +package globals or retain the state handle after a tool returns. Definitions and +their Go callbacks can be shared across concurrently executing threads. Handlers +must finish their work before returning; do not leave background goroutines +using an execution handle. Respect the supplied context in external operations. + +## Consume a package + +Applications import the modules, call their `Package()` functions, and register +them with `runtime.Register(...)`. Registration of a batch is atomic and resolves +dependencies against the whole batch regardless of order. Missing dependencies, +version/schema mismatches and cycles are errors. Definitions and manifests +returned to callers do not expose mutable runtime configuration. + +Create a thread with `runtime.CreateThread(ctx, agentID)`, then use +`runtime.Run(ctx, threadID, input)` or the generic +`agentruntime.RunTyped[Input, Output](...)` helper. The definition validates the +actual input/output wire data. `RunTyped` checks the exact exported Go types (or +aliases) before execution, so a wrong output type cannot trigger side effects +before failing to decode. `CallAgent` checks the declared child schemas first. + +Configure the host with a `llm.ProviderManager` or another `Completer`, a +checkpointer, and optional model overrides keyed by agent ID. Credentials never +need to be embedded in packages. `runtime.Catalog()` returns JSON-serializable +manifests containing prompts, model profiles, schemas and tool descriptions for +inspection or future Studio integration; the Studio UI is not changed here. + +## Distribution and release + +The three agents have separate `go.mod` files and may be versioned independently. +This checkout uses local `replace` directives so it works before publication. +The consumer declares all four replaces explicitly because a dependency's +replace directives are not inherited. + +These versions are local development identities, not published releases. Before +publishing: + +1. Release the root GoLangGraph module containing the SDK and adapter. +2. Replace each agent module's `v0.0.0` SDK requirement with that real release. +3. Remove development replaces, run `go mod tidy`, and test outside the checkout. +4. Match each package's `Version` constant to its release. In this monorepo, the + first agent tags would be `agents/designer/v0.1.0` and + `agents/storymaker/v0.1.0` and `agents/habitat/v0.1.0`. +5. Consumers can then select released module versions using ordinary `go get`, + import them and rebuild their application. Commit their `go.mod` and `go.sum`. + +No registry service, runtime source compiler, shared-library plugin loader or +Go workspace file is required. Custom Go code is installed at build time. The +manifest is introspection data, not a loader for executable code. Manifest +capabilities do not sandbox code linked into the host. + +## Execution guarantees and current limits + +- Each thread owns its conversation, JSON tool values and model profile. Multiple + threads may execute concurrently. Turns on one thread wait for an in-process + lock; FIFO scheduling is not promised. Waiting is cancelable. +- Tools execute sequentially in model-returned order. Only tools declared by the + agent are available. Errors become correlated tool observations so a model can + correct its arguments within the call budget. Failed tools discard value writes. +- Inputs, tool arguments/results and final model outputs are validated. A final + answer must be a JSON object; the adapter does not silently repair malformed + answers. Provider failures and cancellation propagate to the caller. +- Every request records durable intent **before** executing models, handlers or + tools. Successful turns commit their history, JSON values, result and trace + together. Storage failures are errors. File-backed tests cover reopening a + host and preserving large JSON integers. Memory storage is the default and + does not survive a process restart. +- Failed turns retain a failed journal entry but discard that thread's new + messages and values. A successful child turn remains committed if its parent + later fails. External effects also remain external: a parent/child workflow is + not a distributed transaction. +- Thread-tree creation writes separate records. A reported storage failure + triggers best-effort cleanup; a process crash can leave partial, unreachable + records. The runtime does not claim atomic creation across multiple threads. +- One runtime must own a given thread's writes. Locks are in-process, not database + leases. Multiple hosts sharing a checkpointer must route each thread to one + owner until distributed locking is implemented. +- Registration pins package versions, but updating persistent state across + versions requires an explicit future migration design. + +## Request IDs, recovery and traces + +Supply a stable request identity when callers may redeliver a request: + +```go +result, err := host.RunWithOptions(ctx, threadID, input, agentruntime.RunOptions{ + RequestID: "order-123", +}) +``` + +`RunTypedWithOptions` provides the same behavior with an exact Go type check. +`Run` and `RunTyped` generate a new identity each time, suitable for new turns. +IDs are scoped to a thread and accept 1–128 ASCII letters, digits, dots, colons, +underscores or hyphens, starting with a letter or digit. + +| Stored state for this request ID | Result of redelivery | +| --- | --- | +| Succeeded, same validated input | Return the saved result; execute nothing | +| Any state, different input | `ErrRequestConflict` | +| Failed or abandoned | `ErrRunFailed`; deliberate retry needs a new ID | +| Running after an interruption | `ErrRunIndeterminate`; further work is blocked | + +Input comparison canonicalizes object key order and preserves JSON numbers. It +does not treat every mathematically equal numeric spelling as the same input. +If a process dies or a final commit fails, the persisted running record prevents +automatic replay. Inspect external effects and the child threads, then call +`host.AbandonRun(ctx, threadID, requestID, reason)` to acknowledge the interruption. +This does not undo work. Resolve interrupted children as well before submitting a +new parent request. Use idempotent external services for stronger effect handling. + +Each thread retains up to `Config.MaxRecordedRuns` journal entries (default 1000). +The runtime refuses new requests when full; it never silently drops idempotency +keys. Existing succeeded IDs can still be read. Start a new thread deliberately +when the journal limit is reached. This bounds record count, not input/output or +history byte size; hosts must apply suitable request and storage limits. + +`ReadThread` exposes journal status and ordered execution events. Events contain +model/tool names and correlated child thread/request IDs, without raw payloads. +They are committed with the result or failure, not after every step; a crash can +leave only the initial `run_started` event. Results count direct model/tool/child +calls on that thread; descendant usage is available in the child's journal. +No live streaming transport, durable message queue or distributed lease is +implemented by this adapter. + +## Which concepts should move to Go? + +The useful transfer from the [Standard Agent Specification's overview](https://standardagentspec.org/) +is the separation between reusable definitions, running thread instances and +host infrastructure. This implementation makes those concepts ordinary Go +packages and interfaces. It does not promise specification conformance. + +| Concept | Go-native choice and current coverage | +| --- | --- | +| Providers and models | Host `Completer` port; explicit package defaults and pinned host overrides | +| Prompts and tools | Embedded assets, typed Go callbacks and validated schema boundaries | +| Handlers | Pure Go typed functions executed by a graph node | +| Agents and subagents | Immutable definitions, declared versioned dependencies, isolated persistent children | +| Threads and execution state | Checkpointer-backed history/values, bounded turns and request journal | +| Type registry | Exported Go types, generics, compiler imports and runtime boundary checks | +| Packaging and distribution | Go modules, source releases, embedded assets and host builds | +| Lifecycle hooks | Typed validation exists; a general interception/compaction hook API is deferred | +| Effects and scheduling | Deferred; requires durable delivery and retry semantics beyond turn execution | +| Files, sandboxes and remote endpoints | Deferred; these need explicit host capability and isolation designs | +| Users, streams and client UI | Host concerns; no new principal model, streaming protocol or Studio UI here | +| Decisions and sub-prompts | Can be authored as handlers/child agents; no dedicated API yet | + +The next useful extension is a durable host service with ownership leases, +recovery tooling and bounded history management. Scheduling, runtime code +loading and marketplace services should follow concrete deployment requirements, +not become mandatory dependencies of the authoring SDK. diff --git a/examples/11-agent-packages/README.md b/examples/11-agent-packages/README.md new file mode 100644 index 0000000..4bc82c4 --- /dev/null +++ b/examples/11-agent-packages/README.md @@ -0,0 +1,63 @@ +# Compose independent Go agent modules + +This application imports three independent agent modules: designer, storymaker +and habitat. The habitat package owns the composition in a Go handler; the host +supplies providers and persistence. It also includes an alternative outer graph +workflow and a deterministic model double for offline use. + +```sh +go run . +go run . -catalog +go run . -workflow graph +go test -race ./... +``` + +The default mode requires no network, model server or credentials. Its output +explicitly identifies the model double. It exercises the actual graph engine, +packaged tools, validation and thread storage. + +## Continue across process restarts + +```sh +go run . -state-dir /tmp/golanggraph-package-demo -request-id first +``` + +Copy `habitat_thread` from the output into the next command: + +```sh +go run . -state-dir /tmp/golanggraph-package-demo \ + -resume-habitat '' -request-id second \ + -brief 'Adapt the design to harvest rainwater' +``` + +`designer_tool_uses` increases from 1 to 2. Both child thread IDs stay the same and +both children preserve their own histories. Repeat the second command unchanged: +the saved result is returned and the counter remains 2. Reuse `second` with a +different brief and the runtime reports a request conflict. Use a new request ID +for a new turn. The output includes the parent trace with child request IDs. + +The optional `-workflow graph` mode uses application-owned graph nodes and accepts +`-resume-designer` instead. It creates a new storymaker thread for each workflow. +Request IDs and parent/child orchestration are demonstrated in `package` mode. + +Interrupted requests block further turns. Inspect their child/external effects, +then call the host API `AbandonRun` before deliberately submitting a new request. +There is no automatic replay of unfinished work. + +## Use a real model + +With Ollama running and a tool-capable model already installed: + +```sh +go run . -live -model '' +``` + +Use `-endpoint` to choose another Ollama endpoint. Live runs require tool calling +and schema-shaped JSON output. The package default profile retains the original +examples' `gemma3:1b` setting; support and quality depend on the model. Offline +tests do not certify a live model. Overrides apply to new threads; existing +threads retain their stored model profile. + +The [agent package guide](../../docs/AGENT_PACKAGES.md) explains authoring, +distribution, versioning and the prototype's execution guarantees. The local +replaces are explicit development wiring, not published package releases. diff --git a/examples/11-agent-packages/demo_provider.go b/examples/11-agent-packages/demo_provider.go new file mode 100644 index 0000000..0a70665 --- /dev/null +++ b/examples/11-agent-packages/demo_provider.go @@ -0,0 +1,91 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package main + +import ( + "context" + "encoding/json" + "fmt" + + "github.com/UnicoLab/GoLangGraph/agents/designer" + "github.com/UnicoLab/GoLangGraph/agents/storymaker" + "github.com/UnicoLab/GoLangGraph/pkg/llm" +) + +// demoProvider replaces model inference only. It asks the runtime to execute the +// actual packaged tools, then incorporates their results into a typed answer. +type demoProvider struct{} + +func (demoProvider) Complete(ctx context.Context, _ string, request llm.CompletionRequest) (*llm.CompletionResponse, error) { + if err := ctx.Err(); err != nil { + return nil, err + } + if len(request.Tools) != 1 || len(request.Messages) == 0 { + return nil, fmt.Errorf("offline demo expects one packaged tool and conversation history") + } + var user string + for _, message := range request.Messages { + if message.Role == "user" { + user = message.Content + } + } + last := request.Messages[len(request.Messages)-1] + name := request.Tools[0].Function.Name + var args, output any + switch name { + case "material_palette": + var input designer.Input + if err := json.Unmarshal([]byte(user), &input); err != nil { + return nil, err + } + args = designer.PaletteInput{Focus: input.Message} + if last.Role == "tool" { + var palette designer.Palette + if err := json.Unmarshal([]byte(last.Content), &palette); err != nil { + return nil, err + } + output = designer.Output{ + Description: "An imagined habitat for: " + input.Message + ". Shared outdoor space connects its residents to the landscape.", + Materials: palette.Materials, Style: palette.Style, + } + } + case "story_outline": + var input storymaker.Input + if err := json.Unmarshal([]byte(user), &input); err != nil { + return nil, err + } + args = storymaker.OutlineInput{Topic: input.StoryPrompt} + if last.Role == "tool" { + var outline storymaker.Outline + if err := json.Unmarshal([]byte(last.Content), &outline); err != nil || len(outline.Beats) == 0 { + return nil, fmt.Errorf("offline model received an invalid outline") + } + output = storymaker.Output{ + Title: "A Shared Morning", Story: input.DesignDescription + " A resident opens the door to meet the neighbors. " + outline.Beats[0] + ". Together they begin tending the garden.", + Themes: []string{"community", "sustainability"}, Moral: "Thoughtful homes connect people to their surroundings and to each other.", + } + } + default: + return nil, fmt.Errorf("unsupported offline demo tool %q", name) + } + message := llm.Message{Role: "assistant"} + if output == nil { + data, err := json.Marshal(args) + if err != nil { + return nil, err + } + message.ToolCalls = []llm.ToolCall{{ID: fmt.Sprintf("demo-%d", len(request.Messages)), Type: "function", + Function: llm.FunctionCall{Name: name, Arguments: string(data)}}} + } else { + data, err := json.Marshal(output) + if err != nil { + return nil, err + } + message.Content = string(data) + } + return &llm.CompletionResponse{Choices: []llm.Choice{{Message: message}}}, nil +} diff --git a/examples/11-agent-packages/go.mod b/examples/11-agent-packages/go.mod new file mode 100644 index 0000000..f752848 --- /dev/null +++ b/examples/11-agent-packages/go.mod @@ -0,0 +1,33 @@ +module github.com/UnicoLab/GoLangGraph/examples/11-agent-packages + +go 1.23.0 + +require ( + github.com/UnicoLab/GoLangGraph v0.0.0 + github.com/UnicoLab/GoLangGraph/agents/designer v0.1.0 + github.com/UnicoLab/GoLangGraph/agents/habitat v0.1.0 + github.com/UnicoLab/GoLangGraph/agents/storymaker v0.1.0 +) + +require ( + github.com/cespare/xxhash/v2 v2.3.0 // indirect + github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect + github.com/dlclark/regexp2 v1.10.0 // indirect + github.com/go-redis/redis/v8 v8.11.5 // indirect + github.com/google/uuid v1.6.0 // indirect + github.com/lib/pq v1.10.9 // indirect + github.com/pkoukk/tiktoken-go v0.1.8 // indirect + github.com/pkoukk/tiktoken-go-loader v0.0.2 // indirect + github.com/sashabaranov/go-openai v1.40.5 // indirect + github.com/sirupsen/logrus v1.9.3 // indirect + golang.org/x/sys v0.33.0 // indirect +) + +// Replaces are deliberately in the consumer: dependency replaces are not inherited. +replace github.com/UnicoLab/GoLangGraph => ../.. + +replace github.com/UnicoLab/GoLangGraph/agents/designer => ../../agents/designer + +replace github.com/UnicoLab/GoLangGraph/agents/habitat => ../../agents/habitat + +replace github.com/UnicoLab/GoLangGraph/agents/storymaker => ../../agents/storymaker diff --git a/examples/11-agent-packages/go.sum b/examples/11-agent-packages/go.sum new file mode 100644 index 0000000..25ae5fa --- /dev/null +++ b/examples/11-agent-packages/go.sum @@ -0,0 +1,54 @@ +github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs= +github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs= +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM= +github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78= +github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc= +github.com/dlclark/regexp2 v1.10.0 h1:+/GIL799phkJqYW+3YbOd8LCcbHzT0Pbo8zl70MHsq0= +github.com/dlclark/regexp2 v1.10.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8= +github.com/fsnotify/fsnotify v1.8.0 h1:dAwr6QBTBZIkG8roQaJjGof0pp0EeF+tNV7YBP3F/8M= +github.com/fsnotify/fsnotify v1.8.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0= +github.com/go-redis/redis/v8 v8.11.5 h1:AcZZR7igkdvfVmQTPnu9WE37LRrO/YrBH5zWyjDC0oI= +github.com/go-redis/redis/v8 v8.11.5/go.mod h1:gREzHqY1hg6oD9ngVRbLStwAWKhA0FEgq8Jd4h5lpwo= +github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= +github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw= +github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o= +github.com/nxadm/tail v1.4.8 h1:nPr65rt6Y5JFSKQO7qToXr7pePgD6Gwiw05lkbyAQTE= +github.com/nxadm/tail v1.4.8/go.mod h1:+ncqLTQzXmGhMZNUePPaPqPvBxHAIsmXswZKocGu+AU= +github.com/onsi/ginkgo v1.16.5 h1:8xi0RTUf59SOSfEtZMvwTvXYMzG4gV23XVHOZiXNtnE= +github.com/onsi/ginkgo v1.16.5/go.mod h1:+E8gABHa3K6zRBolWtd+ROzc/U5bkGt0FwiG042wbpU= +github.com/onsi/gomega v1.18.1 h1:M1GfJqGRrBrrGGsbxzV5dqM2U2ApXefZCQpkukxYRLE= +github.com/onsi/gomega v1.18.1/go.mod h1:0q+aL8jAiMXy9hbwj2mr5GziHiwhAIQpFmmtT5hitRs= +github.com/pkoukk/tiktoken-go v0.1.8 h1:85ENo+3FpWgAACBaEUVp+lctuTcYUO7BtmfhlN/QTRo= +github.com/pkoukk/tiktoken-go v0.1.8/go.mod h1:9NiV+i9mJKGj1rYOT+njbv+ZwA/zJxYdewGl6qVatpg= +github.com/pkoukk/tiktoken-go-loader v0.0.2 h1:LUKws63GV3pVHwH1srkBplBv+7URgmOmhSkRxsIvsK4= +github.com/pkoukk/tiktoken-go-loader v0.0.2/go.mod h1:4mIkYyZooFlnenDlormIo6cd5wrlUKNr97wp9nGgEKo= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U= +github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/sashabaranov/go-openai v1.40.5 h1:SwIlNdWflzR1Rxd1gv3pUg6pwPc6cQ2uMoHs8ai+/NY= +github.com/sashabaranov/go-openai v1.40.5/go.mod h1:lj5b/K+zjTSFxVLijLSTDZuP7adOgerWeFyZLUhAKRg= +github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ= +github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= +github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= +golang.org/x/net v0.40.0 h1:79Xs7wF06Gbdcg4kdCCIQArK11Z1hr5POQ6+fIYHNuY= +golang.org/x/net v0.40.0/go.mod h1:y0hY0exeL2Pku80/zKK7tpntoX23cqL3Oa6njdgRtds= +golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.33.0 h1:q3i8TbbEz+JRD9ywIRlyRAQbM0qF7hu24q3teo2hbuw= +golang.org/x/sys v0.33.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k= +golang.org/x/text v0.26.0 h1:P42AVeLghgTYr4+xUnTRKDMqpar+PtX7KWuNQL21L8M= +golang.org/x/text v0.26.0/go.mod h1:QK15LZJUUQVJxhz7wXgxSy/CJaTFjd0G+YLonydOVQA= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 h1:uRGJdciOHaEIrze2W8Q3AKkepLTh2hOroT7a+7czfdQ= +gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw= +gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= +gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/examples/11-agent-packages/main.go b/examples/11-agent-packages/main.go new file mode 100644 index 0000000..abcafd4 --- /dev/null +++ b/examples/11-agent-packages/main.go @@ -0,0 +1,246 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package main + +import ( + "context" + "encoding/json" + "flag" + "fmt" + "os" + "time" + + "github.com/UnicoLab/GoLangGraph/agents/designer" + "github.com/UnicoLab/GoLangGraph/agents/habitat" + "github.com/UnicoLab/GoLangGraph/agents/storymaker" + "github.com/UnicoLab/GoLangGraph/pkg/agentruntime" + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" + "github.com/UnicoLab/GoLangGraph/pkg/core" + "github.com/UnicoLab/GoLangGraph/pkg/llm" + "github.com/UnicoLab/GoLangGraph/pkg/persistence" +) + +func main() { + if err := run(); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } +} + +func run() error { + live := flag.Bool("live", false, "Use a running Ollama server instead of the offline model double") + endpoint := flag.String("endpoint", "http://localhost:11434", "Ollama endpoint for -live") + model := flag.String("model", "", "Override the packages' default model for new threads") + brief := flag.String("brief", "A small solar-powered habitat beside a community garden", "Design brief") + stateDir := flag.String("state-dir", "", "Directory for durable threads; omitted uses memory") + resume := flag.String("resume-designer", "", "Continue a designer thread from -state-dir") + workflow := flag.String("workflow", "package", "Composition: package (persistent children) or graph (application-owned nodes)") + resumeHabitat := flag.String("resume-habitat", "", "Continue a habitat thread from -state-dir") + requestID := flag.String("request-id", "", "Stable request ID for deduplication in package mode") + catalog := flag.Bool("catalog", false, "Print package manifests without executing agents") + flag.Parse() + if (*resume != "" || *resumeHabitat != "") && *stateDir == "" { + return fmt.Errorf("resume requires -state-dir") + } + if *workflow != "package" && *workflow != "graph" { + return fmt.Errorf("-workflow must be package or graph") + } + if (*workflow == "package" && *resume != "") || (*workflow == "graph" && (*resumeHabitat != "" || *requestID != "")) { + return fmt.Errorf("resume/request flags must match the selected workflow") + } + var providers agentruntime.Completer = demoProvider{} + mode := "offline model double; real package tools, graph and persistence" + if *live { + manager := llm.NewProviderManager() + defer manager.Close() + provider, err := llm.NewOllamaProvider(&llm.ProviderConfig{Endpoint: *endpoint, Timeout: 90 * time.Second}) + if err != nil { + return err + } + if err := manager.RegisterProvider("ollama", provider); err != nil { + return err + } + providers, mode = manager, "live Ollama" + } + var checkpointer persistence.Checkpointer = persistence.NewMemoryCheckpointer() + if *stateDir != "" { + checkpointer = persistence.NewFileCheckpointer(*stateDir) + } + defer checkpointer.Close() + config := agentruntime.Config{Providers: providers, Checkpointer: checkpointer} + if *model != "" { + config.Models = map[string]agentspec.Model{ + designer.AgentID: {Provider: "ollama", Name: *model, Temperature: 0.7, MaxTokens: 1500}, + storymaker.AgentID: {Provider: "ollama", Name: *model, Temperature: 0.7, MaxTokens: 1800}, + } + } + runtime, err := newRuntime(config) + if err != nil { + return err + } + encoder := json.NewEncoder(os.Stdout) + encoder.SetIndent("", " ") + if *catalog { + return encoder.Encode(runtime.Catalog()) + } + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute) + defer cancel() + var report *Report + if *workflow == "package" { + report, err = composePackage(ctx, runtime, *brief, *resumeHabitat, *requestID) + } else { + report, err = compose(ctx, runtime, *brief, *resume) + } + if err != nil { + return err + } + report.Mode = mode + return encoder.Encode(report) +} + +func newRuntime(config agentruntime.Config) (*agentruntime.Runtime, error) { + designPackage, err := designer.Package() + if err != nil { + return nil, err + } + storyPackage, err := storymaker.Package() + if err != nil { + return nil, err + } + habitatPackage, err := habitat.Package() + if err != nil { + return nil, err + } + runtime, err := agentruntime.New(config) + if err != nil { + return nil, err + } + if err := runtime.Register(habitatPackage, designPackage, storyPackage); err != nil { + return nil, err + } + return runtime, nil +} + +type Report struct { + Mode string `json:"mode"` + HabitatThread string `json:"habitat_thread,omitempty"` + RequestID string `json:"request_id,omitempty"` + Events []agentruntime.Event `json:"events,omitempty"` + DesignerThread string `json:"designer_thread"` + StorymakerThread string `json:"storymaker_thread"` + DesignerToolUses int `json:"designer_tool_uses"` + Design designer.Output `json:"design"` + Story storymaker.Output `json:"story"` +} + +func composePackage(ctx context.Context, runtime *agentruntime.Runtime, brief, resume, requestID string) (*Report, error) { + var thread *agentruntime.Thread + var err error + if resume == "" { + thread, err = runtime.CreateThread(ctx, habitat.AgentID) + } else { + thread, err = runtime.ReadThread(ctx, resume) + } + if err != nil { + return nil, err + } + if thread.AgentID != habitat.AgentID { + return nil, fmt.Errorf("resume thread must belong to habitat") + } + result, err := runtime.RunWithOptions(ctx, thread.ID, habitat.Input{Message: brief}, agentruntime.RunOptions{RequestID: requestID}) + if err != nil { + return nil, err + } + var output habitat.Output + if err := json.Unmarshal(result.Output, &output); err != nil { + return nil, err + } + report := &Report{HabitatThread: thread.ID, RequestID: result.RequestID, DesignerThread: thread.Children["designer"], StorymakerThread: thread.Children["storymaker"], Design: output.Design, Story: output.Story} + parent, err := runtime.ReadThread(ctx, thread.ID) + if err != nil { + return nil, err + } + report.Events = parent.Runs[result.RequestID].Events + design, err := runtime.ReadThread(ctx, report.DesignerThread) + if err != nil { + return nil, err + } + if err := json.Unmarshal(design.Values["palette_uses"], &report.DesignerToolUses); err != nil { + return nil, err + } + return report, nil +} + +// The consumer owns the workflow. Neither agent module imports the other, and +// neither module imports core.Graph. Data crosses the boundary through types. +func compose(ctx context.Context, runtime *agentruntime.Runtime, brief, resume string) (*Report, error) { + var designThread *agentruntime.Thread + var err error + if resume != "" { + designThread, err = runtime.ReadThread(ctx, resume) + if err == nil && designThread.AgentID != designer.AgentID { + return nil, fmt.Errorf("resume thread must belong to the designer") + } + } else { + designThread, err = runtime.CreateThread(ctx, designer.AgentID) + } + if err != nil { + return nil, err + } + storyThread, err := runtime.CreateThread(ctx, storymaker.AgentID) + if err != nil { + return nil, err + } + report := &Report{DesignerThread: designThread.ID, StorymakerThread: storyThread.ID} + graph := core.NewGraph("packaged-habitat-workflow") + defer graph.Close() + graph.Config.Timeout = 0 + graph.AddNode("design", "Design habitat", func(ctx context.Context, state *core.BaseState) (*core.BaseState, error) { + output, err := agentruntime.RunTyped[designer.Input, designer.Output](ctx, runtime, designThread.ID, designer.Input{Message: brief}) + if err != nil { + return nil, err + } + state.Set("design", output) + report.Design = output + return state, nil + }) + graph.AddNode("story", "Tell its story", func(ctx context.Context, state *core.BaseState) (*core.BaseState, error) { + value, _ := state.Get("design") + design, ok := value.(designer.Output) + if !ok { + return nil, fmt.Errorf("design node did not produce a typed design") + } + output, err := agentruntime.RunTyped[storymaker.Input, storymaker.Output](ctx, runtime, storyThread.ID, storymaker.Input{ + StoryPrompt: "A resident's first morning in the habitat", DesignDescription: design.Description, + }) + if err != nil { + return nil, err + } + report.Story = output + return state, nil + }) + graph.AddEdge("design", "story", nil) + if err := graph.SetStartNode("design"); err != nil { + return nil, err + } + if err := graph.AddEndNode("story"); err != nil { + return nil, err + } + if _, err := graph.Execute(ctx, core.NewBaseState()); err != nil { + return nil, err + } + snapshot, err := runtime.ReadThread(ctx, designThread.ID) + if err != nil { + return nil, err + } + if value, exists := snapshot.Values["palette_uses"]; exists { + if err := json.Unmarshal(value, &report.DesignerToolUses); err != nil { + return nil, err + } + } + return report, nil +} diff --git a/examples/11-agent-packages/main_test.go b/examples/11-agent-packages/main_test.go new file mode 100644 index 0000000..f9f50e7 --- /dev/null +++ b/examples/11-agent-packages/main_test.go @@ -0,0 +1,132 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package main + +import ( + "context" + "encoding/json" + "strings" + "sync" + "testing" + + "github.com/UnicoLab/GoLangGraph/agents/designer" + "github.com/UnicoLab/GoLangGraph/agents/storymaker" + "github.com/UnicoLab/GoLangGraph/pkg/agentruntime" + "github.com/UnicoLab/GoLangGraph/pkg/persistence" +) + +func TestIndependentlyPackagedAgentsComposeAndResume(t *testing.T) { + dir := t.TempDir() + config := func() agentruntime.Config { + return agentruntime.Config{Providers: demoProvider{}, Checkpointer: persistence.NewFileCheckpointer(dir)} + } + runtime, err := newRuntime(config()) + if err != nil { + t.Fatal(err) + } + report, err := compose(context.Background(), runtime, "solar energy garden", "") + if err != nil { + t.Fatal(err) + } + if report.DesignerToolUses != 1 || !strings.Contains(report.Story.Story, report.Design.Description) || report.Design.Style != "futuristic" { + t.Fatalf("package composition did not use design/tool results: %+v", report) + } + catalog := runtime.Catalog() + if len(catalog) != 3 || catalog[0].Module != designer.Module || catalog[2].Module != storymaker.Module { + t.Fatalf("incorrect catalog: %+v", catalog) + } + if _, err := json.Marshal(catalog); err != nil { + t.Fatal(err) + } + // Recreate the host from persisted records, without carrying live instances. + restarted, err := newRuntime(config()) + if err != nil { + t.Fatal(err) + } + next, err := compose(context.Background(), restarted, "rainwater garden", report.DesignerThread) + if err != nil { + t.Fatal(err) + } + if next.DesignerThread != report.DesignerThread || next.DesignerToolUses != 2 || next.Design.Style != "modern" { + t.Fatalf("failed continuation: %+v", next) + } + story, err := restarted.ReadThread(context.Background(), next.StorymakerThread) + if err != nil || len(story.Values) != 0 || story.CompletedRuns != 1 { + t.Fatalf("designer state leaked into storyteller: %+v, %v", story, err) + } +} + +func TestOneHostRunsIndependentCompositions(t *testing.T) { + runtime, err := newRuntime(agentruntime.Config{Providers: demoProvider{}}) + if err != nil { + t.Fatal(err) + } + var wg sync.WaitGroup + results := make(chan *Report, 6) + errors := make(chan error, 6) + for i := 0; i < 6; i++ { + wg.Add(1) + go func() { + defer wg.Done() + report, err := compose(context.Background(), runtime, "nature habitat", "") + if err != nil { + errors <- err + return + } + results <- report + }() + } + wg.Wait() + close(results) + close(errors) + for err := range errors { + t.Fatal(err) + } + seen := make(map[string]bool) + for report := range results { + if report.DesignerToolUses != 1 || seen[report.DesignerThread] { + t.Fatalf("reused mutable agent instance: %+v", report) + } + seen[report.DesignerThread] = true + } + if len(seen) != 6 { + t.Fatalf("only %d compositions completed", len(seen)) + } +} + +func TestReusableHabitatPackageResumesAndDeduplicatesAfterRestart(t *testing.T) { + dir := t.TempDir() + open := func() *agentruntime.Runtime { + r, err := newRuntime(agentruntime.Config{Providers: demoProvider{}, Checkpointer: persistence.NewFileCheckpointer(dir)}) + if err != nil { + t.Fatal(err) + } + return r + } + ctx := context.Background() + r := open() + first, err := composePackage(ctx, r, "solar garden", "", "request-1") + if err != nil { + t.Fatal(err) + } + r = open() + repeated, err := composePackage(ctx, r, "solar garden", first.HabitatThread, "request-1") + if err != nil || repeated.DesignerToolUses != 1 || repeated.StorymakerThread != first.StorymakerThread { + t.Fatalf("redelivery: %+v %v", repeated, err) + } + next, err := composePackage(ctx, r, "rainwater garden", first.HabitatThread, "request-2") + if err != nil || next.DesignerToolUses != 2 || next.Design.Style != "modern" || next.DesignerThread != first.DesignerThread { + t.Fatalf("continuation: %+v %v", next, err) + } + if !strings.Contains(next.Story.Story, next.Design.Description) || len(next.Events) != 6 { + t.Fatalf("missing composition output or trace: %+v", next) + } + story, err := r.ReadThread(ctx, next.StorymakerThread) + if err != nil || story.CompletedRuns != 2 || story.ParentID != next.HabitatThread { + t.Fatalf("child history: %+v %v", story, err) + } +} diff --git a/examples/README.md b/examples/README.md index 05529e6..11d7514 100644 --- a/examples/README.md +++ b/examples/README.md @@ -50,6 +50,15 @@ go build -o example-name *.go # For multi-file examples ## 🎯 Examples Overview +### [11-agent-packages](./11-agent-packages/) — Go-native agent distribution + +Import independently versioned designer, storymaker and habitat modules. The +habitat Go handler composes persistent child agents with validated contracts; +an alternative mode composes them directly in application-owned graph nodes. +Inspect manifests, continue across restarts, and deduplicate repeated requests. +The default demo runs offline with real tools and a deterministic model double. +From the repository root, run `make demo-agent-packages` or `make test-agent-packages`. + ### 🤖 [01-basic-chat](./01-basic-chat/) - Basic Chat Agent **Complexity: Beginner** | **Runtime: ~2 minutes** diff --git a/mkdocs.yml b/mkdocs.yml index f66516c..88a5d0d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -185,6 +185,7 @@ nav: - 🏃 Quick Start: getting-started/quick-start.md - 📚 Core Concepts: - 🧠 Core Package: CORE_PACKAGE.md + - 📦 Agent Packages: AGENT_PACKAGES.md - 💾 Persistence Guide: PERSISTENCE_GUIDE.md - 🚀 Auto Server Guide: AUTO_SERVER_GUIDE.md - 🏭 Production: diff --git a/pkg/agentruntime/composition_test.go b/pkg/agentruntime/composition_test.go new file mode 100644 index 0000000..92228fe --- /dev/null +++ b/pkg/agentruntime/composition_test.go @@ -0,0 +1,385 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package agentruntime_test + +import ( + "context" + "encoding/json" + "errors" + "strings" + "sync" + "sync/atomic" + "testing" + + "github.com/UnicoLab/GoLangGraph/pkg/agentruntime" + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" + "github.com/UnicoLab/GoLangGraph/pkg/llm" + "github.com/UnicoLab/GoLangGraph/pkg/persistence" +) + +func handlerPackage(t *testing.T, module string, children []agentspec.Subagent, fn func(context.Context, agentspec.Execution, input) (output, error)) agentspec.Package { + t.Helper() + definition, err := agentspec.NewHandler[input, output](agentspec.HandlerConfig{Name: "run", Description: "Run handler", Subagents: children}, fn) + if err != nil { + t.Fatal(err) + } + pkg, err := agentspec.NewPackage(module, "v0.1.0", "Test handler", definition) + if err != nil { + t.Fatal(err) + } + return pkg +} + +func TestHandlerCompositionPersistsIsolatedChildrenAndRejectsWrongTypes(t *testing.T) { + ctx := context.Background() + child := handlerPackage(t, "example.com/child", nil, func(_ context.Context, s agentspec.Execution, _ input) (output, error) { + count := 0 + if data, ok := s.GetValue("count"); ok { + if err := json.Unmarshal(data, &count); err != nil { + return output{}, err + } + } + count++ + data, _ := json.Marshal(count) + return output{count}, s.SetValue("count", data) + }) + ref, err := agentspec.NewSubagent[input, output]("worker", "Count independently", child.AgentID("run"), "v0.1.0") + if err != nil { + t.Fatal(err) + } + parent := handlerPackage(t, "example.com/parent", []agentspec.Subagent{ref}, func(ctx context.Context, s agentspec.Execution, i input) (output, error) { + if _, err := s.InvokeAgent(ctx, "undeclared", json.RawMessage(`{"text":"hello"}`)); err == nil { + return output{}, errors.New("undeclared child allowed") + } + return agentspec.CallAgent[input, output](ctx, s, "worker", i) + }) + dir := t.TempDir() + open := func() *agentruntime.Runtime { + r, err := agentruntime.New(agentruntime.Config{Checkpointer: persistence.NewFileCheckpointer(dir)}) // no model + if err != nil { + t.Fatal(err) + } + if err := r.Register(parent, child); err != nil { + t.Fatal(err) + } // parent-first batch works + return r + } + r := open() + a, b := createThread(t, r, parent.AgentID("run")), createThread(t, r, parent.AgentID("run")) + if a.Children["worker"] == b.Children["worker"] { + t.Fatal("shared child instance") + } + for _, thread := range []*agentruntime.Thread{a, b} { + out, err := agentruntime.RunTyped[input, output](ctx, r, thread.ID, input{"hi"}) + if err != nil || out.Count != 1 { + t.Fatalf("first run: %+v %v", out, err) + } + } + r = open() + out, err := agentruntime.RunTyped[input, output](ctx, r, a.ID, input{"again"}) + if err != nil || out.Count != 2 { + t.Fatalf("persistent child: %+v %v", out, err) + } + childState, err := r.ReadThread(ctx, a.Children["worker"]) + if err != nil || childState.ParentID != a.ID || childState.ChildName != "worker" || childState.CompletedRuns != 2 { + t.Fatalf("lineage: %+v %v", childState, err) + } + before, _ := r.ReadThread(ctx, a.ID) + if _, err := agentruntime.RunTyped[input, struct{ Wrong string }](ctx, r, a.ID, input{"bad type"}); err == nil { + t.Fatal("wrong output accepted") + } + after, _ := r.ReadThread(ctx, a.ID) + if after.CompletedRuns != before.CompletedRuns || len(after.Runs) != len(before.Runs) { + t.Fatal("wrong type executed a turn") + } + if len(after.Values) != 0 { + t.Fatal("child values leaked into parent") + } + for _, record := range after.Runs { + if record.Result.ChildCalls != 1 || record.Result.ModelCalls != 0 { + t.Fatalf("wrong counters: %+v", record.Result) + } + if len(record.Events) != 4 || record.Events[1].ChildThreadID != a.Children["worker"] { + t.Fatalf("missing trace: %+v", record.Events) + } + } +} + +func TestRegistrationRejectsUnresolvedVersionSchemaAndCyclesAtomically(t *testing.T) { + noop := func(context.Context, agentspec.Execution, input) (output, error) { return output{}, nil } + child := handlerPackage(t, "example.com/child", nil, noop) + for _, test := range []struct { + name, version string + mismatch bool + }{ + {"missing", "v0.1.0", false}, {"version", "v0.2.0", false}, {"schema", "v0.1.0", true}, + } { + t.Run(test.name, func(t *testing.T) { + ref, err := agentspec.NewSubagent[input, output]("child", "Child", child.AgentID("run"), test.version) + if test.mismatch { + ref, err = agentspec.NewSubagent[struct{ Other string }, output]("child", "Child", child.AgentID("run"), test.version) + } + if err != nil { + t.Fatal(err) + } + parent := handlerPackage(t, "example.com/parent", []agentspec.Subagent{ref}, noop) + r, _ := agentruntime.New(agentruntime.Config{}) + packages := []agentspec.Package{parent} + if test.name != "missing" { + packages = append(packages, child) + } + if err := r.Register(packages...); err == nil || len(r.Catalog()) != 0 { + t.Fatalf("registration was not rejected atomically: %v", err) + } + }) + } + ref, _ := agentspec.NewSubagent[input, output]("self", "Self", "example.com/cycle#run", "v0.1.0") + r, _ := agentruntime.New(agentruntime.Config{}) + if err := r.Register(handlerPackage(t, "example.com/cycle", []agentspec.Subagent{ref}, noop)); err == nil || !strings.Contains(err.Error(), "cyclic") { + t.Fatalf("cycle: %v", err) + } +} + +func TestDurableRequestIDsDeduplicateAcrossRestartAndConcurrentRedelivery(t *testing.T) { + var calls atomic.Int32 + pkg := handlerPackage(t, "example.com/handler", nil, func(context.Context, agentspec.Execution, input) (output, error) { + return output{int(calls.Add(1))}, nil + }) + dir := t.TempDir() + open := func() *agentruntime.Runtime { + return newRuntime(t, agentruntime.Config{Checkpointer: persistence.NewFileCheckpointer(dir)}, pkg) + } + r := open() + thread := createThread(t, r, pkg.AgentID("run")) + options := agentruntime.RunOptions{RequestID: "order-42"} + var wg sync.WaitGroup + for i := 0; i < 10; i++ { + wg.Add(1) + go func() { + defer wg.Done() + out, err := r.RunWithOptions(context.Background(), thread.ID, input{"hello"}, options) + if err != nil || string(out.Output) != `{"count":1}` { + t.Errorf("redelivery: %+v %v", out, err) + } + }() + } + wg.Wait() + r = open() + result, err := r.RunWithOptions(context.Background(), thread.ID, map[string]string{"text": "hello"}, options) + if err != nil || calls.Load() != 1 || result.RequestID != options.RequestID { + t.Fatalf("restart dedupe: %+v %v calls=%d", result, err, calls.Load()) + } + result.Output[0] = 'x' + result, err = r.RunWithOptions(context.Background(), thread.ID, input{"hello"}, options) + if err != nil || !json.Valid(result.Output) { + t.Fatal("result alias corrupted journal") + } + if _, err := r.RunWithOptions(context.Background(), thread.ID, input{"different"}, options); !errors.Is(err, agentruntime.ErrRequestConflict) { + t.Fatalf("conflict: %v", err) + } +} + +type failFinalStore struct { + persistence.Checkpointer + fail bool +} + +func (s *failFinalStore) Save(ctx context.Context, cp *persistence.Checkpoint) error { + if s.fail && cp.StepID > 0 { + return errSave + } + return s.Checkpointer.Save(ctx, cp) +} + +func TestUncertainCommitBlocksReplayUntilExplicitAbandonment(t *testing.T) { + ctx := context.Background() + var effects int + pkg := handlerPackage(t, "example.com/effects", nil, func(_ context.Context, s agentspec.Execution, _ input) (output, error) { + effects++ + return output{effects}, s.SetValue("value", json.RawMessage(`1`)) + }) + store := &failFinalStore{Checkpointer: persistence.NewMemoryCheckpointer(), fail: true} + r := newRuntime(t, agentruntime.Config{Checkpointer: store}, pkg) + thread := createThread(t, r, pkg.AgentID("run")) + options := agentruntime.RunOptions{RequestID: "first"} + if _, err := r.RunWithOptions(ctx, thread.ID, input{"go"}, options); !errors.Is(err, agentruntime.ErrRunIndeterminate) || !errors.Is(err, errSave) { + t.Fatalf("commit failure: %v", err) + } + store.fail = false + r = newRuntime(t, agentruntime.Config{Checkpointer: store}, pkg) + for _, id := range []string{"first", "another"} { + if _, err := r.RunWithOptions(ctx, thread.ID, input{"go"}, agentruntime.RunOptions{RequestID: id}); !errors.Is(err, agentruntime.ErrRunIndeterminate) { + t.Fatalf("replayed uncertain run: %v", err) + } + } + if effects != 1 { + t.Fatalf("duplicated external effects: %d", effects) + } + snapshot, _ := r.ReadThread(ctx, thread.ID) + if snapshot.CompletedRuns != 0 || len(snapshot.Values) != 0 || snapshot.Runs["first"].Status != "running" { + t.Fatalf("bad checkpoint: %+v", snapshot) + } + if err := r.AbandonRun(ctx, thread.ID, "first", ""); err == nil { + t.Fatal("empty abandonment reason accepted") + } + if err := r.AbandonRun(ctx, thread.ID, "first", "Operator inspected the external action"); err != nil { + t.Fatal(err) + } + if _, err := r.RunWithOptions(ctx, thread.ID, input{"go"}, options); !errors.Is(err, agentruntime.ErrRunFailed) { + t.Fatalf("abandoned key reused: %v", err) + } + if _, err := r.RunWithOptions(ctx, thread.ID, input{"deliberate retry"}, agentruntime.RunOptions{RequestID: "second"}); err != nil || effects != 2 { + t.Fatalf("deliberate retry: %v", err) + } +} + +func TestHandlerFailurePanicAndCancellationPersistFailureWithoutValues(t *testing.T) { + for _, failure := range []string{"error", "panic", "cancel"} { + t.Run(failure, func(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + pkg := handlerPackage(t, "example.com/failure", nil, func(_ context.Context, s agentspec.Execution, _ input) (output, error) { + if err := s.SetValue("uncommitted", json.RawMessage(`1`)); err != nil { + return output{}, err + } + switch failure { + case "panic": + panic("handler failed") + case "cancel": + cancel() + return output{}, ctx.Err() + } + return output{}, errors.New("handler failed") + }) + r := newRuntime(t, agentruntime.Config{MaxRecordedRuns: 1}, pkg) + thread := createThread(t, r, pkg.AgentID("run")) + if _, err := r.RunWithOptions(ctx, thread.ID, input{"fail"}, agentruntime.RunOptions{RequestID: "failed"}); err == nil { + t.Fatal("failure swallowed") + } + snapshot, err := r.ReadThread(context.Background(), thread.ID) + if err != nil || len(snapshot.Values) != 0 || len(snapshot.Messages) != 0 || snapshot.Runs["failed"].Status != "failed" { + t.Fatalf("failure not journaled: %+v %v", snapshot, err) + } + if _, err := r.Run(context.Background(), thread.ID, input{"again"}); !errors.Is(err, agentruntime.ErrJournalFull) { + t.Fatalf("journal evicted key: %v", err) + } + }) + } +} + +func TestManifestFingerprintPreventsSilentPromptChanges(t *testing.T) { + pkg := counterPackage(t, "example.com/pinned", "v0.1.0", 4) + store := persistence.NewMemoryCheckpointer() + r := newRuntime(t, agentruntime.Config{Checkpointer: store}, pkg) + thread := createThread(t, r, pkg.AgentID("counter")) + changed := counterPackage(t, "example.com/pinned", "v0.1.0", 5) + r = newRuntime(t, agentruntime.Config{Checkpointer: store}, changed) + if _, err := r.Run(context.Background(), thread.ID, input{"hello"}); err == nil { + t.Fatal("changed definition resumed old thread") + } +} + +func TestPromptCallsDeclaredChildAsTool(t *testing.T) { + child := handlerPackage(t, "example.com/worker", nil, func(context.Context, agentspec.Execution, input) (output, error) { return output{7}, nil }) + ref, err := agentspec.NewSubagent[input, output]("worker", "Delegate to worker", child.AgentID("run"), "v0.1.0") + if err != nil { + t.Fatal(err) + } + definition, err := agentspec.NewAgent[input, output](agentspec.AgentConfig{ + Name: "parent", Description: "Delegate", Subagents: []agentspec.Subagent{ref}, + Prompt: agentspec.Prompt{System: "Use worker", Model: agentspec.Model{Provider: "test", Name: "model", MaxTokens: 100}}, + }) + if err != nil { + t.Fatal(err) + } + parent, err := agentspec.NewPackage("example.com/parent", "v0.1.0", "Parent", definition) + if err != nil { + t.Fatal(err) + } + provider := completionFunc(func(_ context.Context, _ string, req llm.CompletionRequest) (*llm.CompletionResponse, error) { + if len(req.Tools) != 1 || req.Tools[0].Function.Name != "worker" { + t.Fatal("child not advertised to model") + } + last := req.Messages[len(req.Messages)-1] + if last.Role == "tool" { + return reply(llm.Message{Content: last.Content}), nil + } + return reply(llm.Message{ToolCalls: []llm.ToolCall{{ID: "delegate", Type: "function", Function: llm.FunctionCall{Name: "worker", Arguments: `{"text":"delegated"}`}}}}), nil + }) + r := newRuntime(t, agentruntime.Config{Providers: provider}, parent, child) + thread := createThread(t, r, parent.AgentID("parent")) + result, err := r.Run(context.Background(), thread.ID, input{"start"}) + if err != nil || string(result.Output) != `{"count":7}` || result.ChildCalls != 1 || result.ToolCalls != 0 || result.ModelCalls != 2 { + t.Fatalf("delegated result: %+v %v", result, err) + } +} + +func TestParentFailurePreservesCommittedChildAndDoesNotReplaySameRequest(t *testing.T) { + var calls int + child := handlerPackage(t, "example.com/child", nil, func(context.Context, agentspec.Execution, input) (output, error) { calls++; return output{calls}, nil }) + ref, _ := agentspec.NewSubagent[input, output]("child", "Child", child.AgentID("run"), "v0.1.0") + parent := handlerPackage(t, "example.com/parent", []agentspec.Subagent{ref}, func(ctx context.Context, s agentspec.Execution, i input) (output, error) { + if _, err := agentspec.CallAgent[input, struct{ Wrong string }](ctx, s, "child", i); err == nil { + return output{}, errors.New("mismatched child type accepted") + } + out, err := agentspec.CallAgent[input, output](ctx, s, "child", i) + if err != nil { + return output{}, err + } + return out, errors.New("parent failed after child commit") + }) + r := newRuntime(t, agentruntime.Config{}, parent, child) + thread := createThread(t, r, parent.AgentID("run")) + ctx := context.Background() + options := agentruntime.RunOptions{RequestID: "failure"} + if _, err := r.RunWithOptions(ctx, thread.ID, input{"start"}, options); err == nil { + t.Fatal("parent failure swallowed") + } + if _, err := r.RunWithOptions(ctx, thread.ID, input{"start"}, options); !errors.Is(err, agentruntime.ErrRunFailed) { + t.Fatalf("replayed parent: %v", err) + } + parentState, _ := r.ReadThread(ctx, thread.ID) + childState, _ := r.ReadThread(ctx, thread.Children["child"]) + if calls != 1 || parentState.CompletedRuns != 0 || childState.CompletedRuns != 1 { + t.Fatalf("bad partial commit semantics: calls=%d parent=%d child=%d", calls, parentState.CompletedRuns, childState.CompletedRuns) + } + if parentState.Runs[options.RequestID].Events[2].Type != "child_succeeded" { + t.Fatal("failed parent lost child trace") + } +} + +func TestCreateThreadCleansUpPartialTreeOnStorageFailure(t *testing.T) { + noop := func(context.Context, agentspec.Execution, input) (output, error) { return output{}, nil } + child := handlerPackage(t, "example.com/child", nil, noop) + ref, _ := agentspec.NewSubagent[input, output]("child", "Child", child.AgentID("run"), "v0.1.0") + parent := handlerPackage(t, "example.com/parent", []agentspec.Subagent{ref}, noop) + store := &failNthStore{Checkpointer: persistence.NewMemoryCheckpointer(), failAt: 2} + r := newRuntime(t, agentruntime.Config{Checkpointer: store}, parent, child) + if _, err := r.CreateThread(context.Background(), parent.AgentID("run")); !errors.Is(err, errSave) { + t.Fatalf("tree save: %v", err) + } + for _, cp := range store.saved { + if _, err := store.Load(context.Background(), cp.ThreadID, cp.ID); err == nil { + t.Fatal("partial tree left saved records") + } + } +} + +type failNthStore struct { + persistence.Checkpointer + failAt, calls int + saved []*persistence.Checkpoint +} + +func (s *failNthStore) Save(ctx context.Context, cp *persistence.Checkpoint) error { + s.calls++ + if s.calls == s.failAt { + return errSave + } + s.saved = append(s.saved, cp) + return s.Checkpointer.Save(ctx, cp) +} diff --git a/pkg/agentruntime/execution.go b/pkg/agentruntime/execution.go new file mode 100644 index 0000000..d308c5f --- /dev/null +++ b/pkg/agentruntime/execution.go @@ -0,0 +1,151 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package agentruntime + +import ( + "context" + "crypto/sha256" + "encoding/json" + "fmt" + "reflect" + "sync" + "time" + + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" +) + +// execution serializes handler accesses, including child invocations. Callbacks +// must finish all work before returning and must not retain this handle. +type execution struct { + mu sync.Mutex + runtime *Runtime + thread *Thread + result *Result + record *RunRecord + tools map[string]agentspec.Tool + children map[string]agentspec.SubagentManifest + invocations int +} + +func newExecution(r *Runtime, definition agentspec.Definition, thread *Thread, result *Result, record *RunRecord) *execution { + s := &execution{runtime: r, thread: thread, result: result, record: record, tools: make(map[string]agentspec.Tool), children: make(map[string]agentspec.SubagentManifest)} + for _, tool := range definition.Tools() { + s.tools[tool.Manifest().Name] = tool + } + for _, child := range definition.Manifest().Subagents { + s.children[child.Name] = child + } + return s +} + +func (s *execution) ThreadID() string { return s.thread.ID } + +func (s *execution) GetValue(key string) (json.RawMessage, bool) { + s.mu.Lock() + defer s.mu.Unlock() + value, exists := s.thread.Values[key] + return append(json.RawMessage(nil), value...), exists +} + +func (s *execution) SetValue(key string, value json.RawMessage) error { + s.mu.Lock() + defer s.mu.Unlock() + return (&toolState{values: s.thread.Values}).SetValue(key, value) +} + +func (s *execution) event(kind, name, childID, childRequestID string) { + s.record.Events = append(s.record.Events, Event{Sequence: len(s.record.Events) + 1, Type: kind, Name: name, Time: time.Now().UTC(), ChildThreadID: childID, ChildRequestID: childRequestID}) +} + +func (s *execution) budget(ctx context.Context) error { + if err := ctx.Err(); err != nil { + return err + } + if s.invocations >= 256 { + return ErrInvocationLimit + } + s.invocations++ + return nil +} + +func (s *execution) InvokeTool(ctx context.Context, name string, input json.RawMessage) (json.RawMessage, error) { + s.mu.Lock() + defer s.mu.Unlock() + if err := s.budget(ctx); err != nil { + return nil, err + } + s.result.ToolCalls++ + s.event("tool_started", name, "", "") + output, err := s.callTool(ctx, name, input) + if err != nil { + s.event("tool_failed", name, "", "") + } else { + s.event("tool_succeeded", name, "", "") + } + return output, err +} + +func (s *execution) callTool(ctx context.Context, name string, input json.RawMessage) (json.RawMessage, error) { + tool, exists := s.tools[name] + if !exists { + return nil, fmt.Errorf("tool %q is not declared by this agent", name) + } + values := make(map[string]json.RawMessage, len(s.thread.Values)) + for key, value := range s.thread.Values { + values[key] = append(json.RawMessage(nil), value...) + } + output, err := tool.Execute(ctx, &toolState{id: s.thread.ID, values: values}, input) + if err == nil { + s.thread.Values = values + } + return output, err +} + +func (s *execution) CheckAgent(name string, input, output agentspec.Schema) error { + child, exists := s.children[name] + if !exists || !reflect.DeepEqual(child.InputSchema, input) || !reflect.DeepEqual(child.OutputSchema, output) { + return fmt.Errorf("child %q is undeclared or has incompatible input/output types", name) + } + return nil +} + +func (s *execution) InvokeAgent(ctx context.Context, name string, input json.RawMessage) (json.RawMessage, error) { + s.mu.Lock() + defer s.mu.Unlock() + if err := s.budget(ctx); err != nil { + return nil, err + } + child, exists := s.children[name] + if !exists { + return nil, fmt.Errorf("child %q is not declared by this agent", name) + } + id := s.thread.Children[name] + instance, err := s.runtime.ReadThread(ctx, id) + if err != nil { + return nil, err + } + if instance.ParentID != s.thread.ID || instance.ChildName != name || instance.AgentID != child.AgentID || instance.PackageVersion != child.PackageVersion { + return nil, fmt.Errorf("child %s has invalid lineage or package identity", name) + } + s.result.ChildCalls++ + requestID := fmt.Sprintf("child-%x", sha256.Sum256([]byte(fmt.Sprintf("%s/%s/%d", s.result.RequestID, name, s.result.ChildCalls)))) + s.event("child_started", name, id, requestID) + result, err := s.runtime.RunWithOptions(ctx, id, input, RunOptions{RequestID: requestID}) + if err != nil { + s.event("child_failed", name, id, requestID) + return nil, err + } + s.event("child_succeeded", name, id, requestID) + return result.Output, nil +} + +func (s *execution) invoke(ctx context.Context, name string, input json.RawMessage) (json.RawMessage, error) { + if _, exists := s.children[name]; exists { + return s.InvokeAgent(ctx, name, input) + } + return s.InvokeTool(ctx, name, input) +} diff --git a/pkg/agentruntime/graph.go b/pkg/agentruntime/graph.go new file mode 100644 index 0000000..efb2ffa --- /dev/null +++ b/pkg/agentruntime/graph.go @@ -0,0 +1,190 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package agentruntime + +import ( + "context" + "encoding/json" + "errors" + "fmt" + + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" + "github.com/UnicoLab/GoLangGraph/pkg/core" + "github.com/UnicoLab/GoLangGraph/pkg/llm" +) + +func (r *Runtime) execute(ctx context.Context, definition agentspec.Definition, thread *Thread, input json.RawMessage, scope *execution) (*Result, error) { + manifest := definition.Manifest() + result := scope.result + graph := core.NewGraph(thread.AgentID) + defer graph.Close() + graph.Config.Timeout = 0 + if manifest.Kind == "handler" { + graph.AddNode("handler", "Execute Go handler", func(ctx context.Context, state *core.BaseState) (*core.BaseState, error) { + output, err := definition.Handle(ctx, scope, input) + if err != nil { + return nil, err + } + result.Output = output + thread.Messages = append(thread.Messages, llm.Message{Role: "assistant", Content: string(output)}) + return state, nil + }) + if err := graph.SetStartNode("handler"); err != nil { + return nil, err + } + if err := graph.AddEndNode("handler"); err != nil { + return nil, err + } + _, err := graph.Execute(ctx, core.NewBaseState()) + return result, err + } + toolDefinitions := make([]llm.ToolDefinition, 0, len(manifest.Tools)+len(manifest.Subagents)) + capabilities := append([]agentspec.ToolManifest(nil), manifest.Tools...) + for _, child := range manifest.Subagents { + capabilities = append(capabilities, agentspec.ToolManifest{Name: child.Name, Description: child.Description, InputSchema: child.InputSchema, OutputSchema: child.OutputSchema}) + } + for _, meta := range capabilities { + data, err := json.Marshal(meta.InputSchema) + if err != nil { + return nil, err + } + var parameters map[string]any + if err := json.Unmarshal(data, ¶meters); err != nil { + return nil, err + } + toolDefinitions = append(toolDefinitions, llm.ToolDefinition{ + Type: "function", Function: llm.Function{Name: meta.Name, Description: meta.Description, Parameters: parameters}, + }) + } + schema, err := json.Marshal(manifest.OutputSchema) + if err != nil { + return nil, err + } + system := manifest.Prompt.System + "\n\nReturn your final answer as one JSON object matching this schema, without markdown fences:\n" + string(schema) + var pending []llm.ToolCall + graph.Config.MaxIterations = 2*manifest.MaxModelCalls + 2 + // Caller cancellation/deadlines govern execution; the model-call budget + // bounds loops independently of wall-clock time. + graph.Config.Timeout = 0 + graph.AddNode("model", "Generate response", func(ctx context.Context, state *core.BaseState) (*core.BaseState, error) { + if result.ModelCalls >= manifest.MaxModelCalls { + return nil, ErrModelCallLimit + } + messages := make([]llm.Message, 0, len(thread.Messages)+1) + messages = append(messages, llm.Message{Role: "system", Content: system}) + messages = append(messages, thread.Messages...) + result.ModelCalls++ + scope.event("model_started", thread.Model.Name, "", "") + response, err := r.providers.Complete(ctx, thread.Model.Provider, llm.CompletionRequest{ + Model: thread.Model.Name, Temperature: thread.Model.Temperature, MaxTokens: thread.Model.MaxTokens, + Messages: messages, Tools: toolDefinitions, + }) + if err != nil { + scope.event("model_failed", thread.Model.Name, "", "") + return nil, err + } + scope.event("model_returned", thread.Model.Name, "", "") + if response == nil || len(response.Choices) != 1 { + return nil, fmt.Errorf("provider must return exactly one completion choice") + } + choice := response.Choices[0] + if choice.FinishReason == "length" || choice.FinishReason == "content_filter" { + return nil, fmt.Errorf("incomplete model response: %s", choice.FinishReason) + } + message := choice.Message + message.Role = "assistant" + pending = message.ToolCalls + if len(pending) > 256 { + return nil, ErrInvocationLimit + } + seen := make(map[string]bool) + for _, call := range pending { + if call.ID == "" || seen[call.ID] || (call.Type != "" && call.Type != "function") { + return nil, fmt.Errorf("invalid or duplicate tool call ID/type") + } + seen[call.ID] = true + } + thread.Messages = append(thread.Messages, message) + result.Usage.PromptTokens += response.Usage.PromptTokens + result.Usage.CompletionTokens += response.Usage.CompletionTokens + result.Usage.TotalTokens += response.Usage.TotalTokens + if len(pending) == 0 { + if err := definition.ValidateOutput(json.RawMessage(message.Content)); err != nil { + return nil, fmt.Errorf("agent output: %w", err) + } + result.Output = json.RawMessage(message.Content) + } + return state, nil + }) + graph.AddNode("tools", "Execute package tools", func(ctx context.Context, state *core.BaseState) (*core.BaseState, error) { + for _, call := range pending { + if err := ctx.Err(); err != nil { + return nil, err + } + output, toolErr := scope.invoke(ctx, call.Function.Name, json.RawMessage(call.Function.Arguments)) + if err := ctx.Err(); err != nil { + return nil, err + } + if errors.Is(toolErr, context.Canceled) || errors.Is(toolErr, context.DeadlineExceeded) || errors.Is(toolErr, ErrRunIndeterminate) || errors.Is(toolErr, ErrInvocationLimit) { + return nil, toolErr + } + if toolErr != nil { + // Tool errors are observations, allowing the model to correct + // arguments on its next step within the configured budget. + output, _ = json.Marshal(struct { + Error string `json:"error"` + }{toolErr.Error()}) + } + thread.Messages = append(thread.Messages, llm.Message{ + Role: "tool", Name: call.Function.Name, ToolCallID: call.ID, Content: string(output), + }) + } + return state, nil + }) + graph.AddNode("done", "Complete turn", func(_ context.Context, state *core.BaseState) (*core.BaseState, error) { + return state, nil + }) + if err := graph.AddConditionalEdges("model", func(_ context.Context, _ *core.BaseState) (string, error) { + if len(pending) > 0 { + return "tools", nil + } + return "done", nil + }, map[string]string{"tools": "tools", "done": "done"}); err != nil { + return nil, err + } + graph.AddEdge("tools", "model", nil) + if err := graph.SetStartNode("model"); err != nil { + return nil, err + } + if err := graph.AddEndNode("done"); err != nil { + return nil, err + } + if _, err := graph.Execute(ctx, core.NewBaseState()); err != nil { + return nil, err + } + return result, nil +} + +type toolState struct { + id string + values map[string]json.RawMessage +} + +func (s *toolState) ThreadID() string { return s.id } + +func (s *toolState) GetValue(key string) (json.RawMessage, bool) { + value, exists := s.values[key] + return append(json.RawMessage(nil), value...), exists +} + +func (s *toolState) SetValue(key string, value json.RawMessage) error { + if key == "" || !json.Valid(value) { + return fmt.Errorf("state requires a non-empty key and valid JSON value") + } + s.values[key] = append(json.RawMessage(nil), value...) + return nil +} diff --git a/pkg/agentruntime/journal.go b/pkg/agentruntime/journal.go new file mode 100644 index 0000000..fabd516 --- /dev/null +++ b/pkg/agentruntime/journal.go @@ -0,0 +1,204 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package agentruntime + +import ( + "bytes" + "context" + "crypto/sha256" + "encoding/json" + "errors" + "fmt" + "regexp" + "time" + + "github.com/UnicoLab/GoLangGraph/pkg/llm" + "github.com/google/uuid" +) + +var ( + ErrRequestConflict = errors.New("request ID was already used with different input") + ErrRunIndeterminate = errors.New("run outcome is indeterminate; inspect effects before abandoning it") + ErrRunFailed = errors.New("request previously failed; a new request ID is required for a deliberate retry") + ErrJournalFull = errors.New("thread run journal is full; create a new thread") + ErrInvocationLimit = errors.New("run tool/child invocation limit exceeded") +) + +type RunOptions struct { + // RequestID is unique within a thread. Empty generates a new identity. + RequestID string +} + +// Event contains execution metadata, never raw prompts, inputs or tool outputs. +// Events are saved with the final run record, not streamed or checkpointed per step. +type Event struct { + Sequence int `json:"sequence"` + Type string `json:"type"` + Name string `json:"name,omitempty"` + Time time.Time `json:"time"` + ChildThreadID string `json:"child_thread_id,omitempty"` + ChildRequestID string `json:"child_request_id,omitempty"` +} + +type RunRecord struct { + RequestID string `json:"request_id"` + InputHash string `json:"input_hash"` + Status string `json:"status"` // running, succeeded, failed or abandoned + StartedAt time.Time `json:"started_at"` + FinishedAt *time.Time `json:"finished_at,omitempty"` + Result *Result `json:"result,omitempty"` + Error string `json:"error,omitempty"` + Events []Event `json:"events"` +} + +var requestPattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$`) + +// RunWithOptions durably records intent before calling external code. Completed +// IDs return their saved result. An interrupted run blocks further work until +// explicitly abandoned; this is deduplication, not exactly-once external I/O. +func (r *Runtime) RunWithOptions(ctx context.Context, threadID string, input any, options RunOptions) (*Result, error) { + if options.RequestID == "" { + options.RequestID = uuid.NewString() + } + if !requestPattern.MatchString(options.RequestID) { + return nil, fmt.Errorf("request ID must be 1-128 ASCII letters, digits, dots, colons, underscores or hyphens, starting with a letter or digit") + } + release, err := r.acquire(ctx, threadID) + if err != nil { + return nil, err + } + defer release() + thread, err := r.load(ctx, threadID) + if err != nil { + return nil, err + } + r.mu.RLock() + registered, exists := r.agents[thread.AgentID] + r.mu.RUnlock() + if !exists || registered.version != thread.PackageVersion || registered.definition.Fingerprint() != thread.DefinitionFingerprint { + return nil, fmt.Errorf("thread requires unchanged agent %s at package version %s", thread.AgentID, thread.PackageVersion) + } + data, err := json.Marshal(input) + if err != nil { + return nil, fmt.Errorf("encode input: %w", err) + } + if validationErr := registered.definition.ValidateInput(data); validationErr != nil { + return nil, fmt.Errorf("agent input: %w", validationErr) + } + // Normalize object key order while preserving numbers, including uint64. + decoder := json.NewDecoder(bytes.NewReader(data)) + decoder.UseNumber() + var normalized any + if decodeErr := decoder.Decode(&normalized); decodeErr != nil { + return nil, decodeErr + } + canonical, err := json.Marshal(normalized) + if err != nil { + return nil, err + } + hash := fmt.Sprintf("sha256:%x", sha256.Sum256(canonical)) + if previous, ok := thread.Runs[options.RequestID]; ok { + if previous.InputHash != hash { + return nil, ErrRequestConflict + } + switch previous.Status { + case "succeeded": + if previous.Result == nil { + return nil, fmt.Errorf("corrupt completed run %s", options.RequestID) + } + return previous.Result, nil + case "running": + return nil, fmt.Errorf("%w: %s", ErrRunIndeterminate, options.RequestID) + case "failed", "abandoned": + return nil, fmt.Errorf("%w: %s: %s", ErrRunFailed, options.RequestID, previous.Error) + default: + return nil, fmt.Errorf("unsupported run status %q", previous.Status) + } + } + for id, previous := range thread.Runs { + if previous.Status == "running" { + return nil, fmt.Errorf("%w: %s", ErrRunIndeterminate, id) + } + } + if len(thread.Runs) >= r.maxRecordedRuns { + return nil, ErrJournalFull + } + record := RunRecord{RequestID: options.RequestID, InputHash: hash, Status: "running", StartedAt: time.Now().UTC()} + record.Events = []Event{{Sequence: 1, Type: "run_started", Time: record.StartedAt}} + thread.Runs[options.RequestID] = record + thread.UpdatedAt = record.StartedAt + if saveErr := r.save(ctx, thread); saveErr != nil { + return nil, saveErr + } + // Keep the intent snapshot separate from mutable execution state so a failed + // turn retains the journal but discards its messages and value writes. + before, err := json.Marshal(thread) + if err != nil { + return nil, err + } + result := &Result{ThreadID: thread.ID, RequestID: options.RequestID} + scope := newExecution(r, registered.definition, thread, result, &record) + thread.Messages = append(thread.Messages, llm.Message{Role: "user", Content: string(data)}) + _, executionErr := r.execute(ctx, registered.definition, thread, data, scope) + if executionErr == nil { + executionErr = ctx.Err() + } + finished := time.Now().UTC() + record.FinishedAt = &finished + if executionErr != nil { + var original Thread + if err := json.Unmarshal(before, &original); err != nil { + return nil, errors.Join(ErrRunIndeterminate, executionErr, err) + } + record.Status, record.Error = "failed", executionErr.Error() + scope.event("run_failed", "", "", "") + original.Runs[options.RequestID], original.UpdatedAt = record, finished + cleanup, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second) + defer cancel() + if err := r.save(cleanup, &original); err != nil { + return nil, errors.Join(ErrRunIndeterminate, executionErr, err) + } + return nil, executionErr + } + record.Status, record.Result = "succeeded", result + scope.event("run_succeeded", "", "", "") + thread.Runs[options.RequestID] = record + thread.CompletedRuns++ + thread.UpdatedAt = finished + if err := r.save(ctx, thread); err != nil { + return nil, errors.Join(ErrRunIndeterminate, err) + } + return result, nil +} + +// AbandonRun acknowledges an interrupted request after the host has inspected +// its external and child effects. It never replays work or rolls back effects. +// A retry must use a new request ID. In-process locking prevents abandoning an +// actively executing run in this Runtime; cross-process ownership is required. +func (r *Runtime) AbandonRun(ctx context.Context, threadID, requestID, reason string) error { + if len(reason) == 0 { + return fmt.Errorf("an abandonment reason is required") + } + release, err := r.acquire(ctx, threadID) + if err != nil { + return err + } + defer release() + thread, err := r.load(ctx, threadID) + if err != nil { + return err + } + record, exists := thread.Runs[requestID] + if !exists || record.Status != "running" { + return fmt.Errorf("request %s is not indeterminate", requestID) + } + now := time.Now().UTC() + record.Status, record.Error, record.FinishedAt = "abandoned", reason, &now + record.Events = append(record.Events, Event{Sequence: len(record.Events) + 1, Type: "run_abandoned", Time: now}) + thread.Runs[requestID], thread.UpdatedAt = record, now + return r.save(ctx, thread) +} diff --git a/pkg/agentruntime/runtime.go b/pkg/agentruntime/runtime.go new file mode 100644 index 0000000..e267b18 --- /dev/null +++ b/pkg/agentruntime/runtime.go @@ -0,0 +1,417 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +// Package agentruntime executes agentspec packages using GoLangGraph. It is an +// opt-in adapter; the existing agent API is unchanged. Each request has a durable +// journal entry; successful turns commit their complete thread state. Interrupted +// requests are never replayed automatically. Locks apply within one Runtime. +package agentruntime + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "reflect" + "sort" + "strings" + "sync" + "time" + + "github.com/google/uuid" + + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" + "github.com/UnicoLab/GoLangGraph/pkg/core" + "github.com/UnicoLab/GoLangGraph/pkg/llm" + "github.com/UnicoLab/GoLangGraph/pkg/persistence" +) + +// Some backends (including PostgreSQL) key checkpoints globally by ID, so the +// identifier must be unique across threads as well as stable across turns. +func checkpointID(threadID string) string { return "agent-package-" + threadID } + +var ErrModelCallLimit = errors.New("agent model call limit exceeded") + +// Completer is satisfied by llm.ProviderManager. Keeping this port narrow also +// permits an offline model double without bypassing tools, graphs or storage. +type Completer interface { + Complete(context.Context, string, llm.CompletionRequest) (*llm.CompletionResponse, error) +} + +type Config struct { + Providers Completer + Checkpointer persistence.Checkpointer + // Models overrides package defaults by fully qualified agent ID. The chosen + // profile is persisted when a thread is created and remains fixed for it. + Models map[string]agentspec.Model + // MaxRecordedRuns bounds each thread's journal. No idempotency keys are + // silently evicted. Create a new thread when this limit is reached. + MaxRecordedRuns int +} + +type entry struct { + definition agentspec.Definition + version string +} + +type threadLock struct { + token chan struct{} + refs int +} + +type Runtime struct { + providers Completer + checkpointer persistence.Checkpointer + models map[string]agentspec.Model + mu sync.RWMutex + packages map[string]agentspec.Package + agents map[string]entry + locksMu sync.Mutex + locks map[string]*threadLock + maxRecordedRuns int +} + +func New(config Config) (*Runtime, error) { + if config.MaxRecordedRuns == 0 { + config.MaxRecordedRuns = 1000 + } + if config.MaxRecordedRuns < 1 { + return nil, fmt.Errorf("max recorded runs must be positive") + } + if config.Checkpointer == nil { + config.Checkpointer = persistence.NewMemoryCheckpointer() + } + models := make(map[string]agentspec.Model, len(config.Models)) + for id, model := range config.Models { + if err := model.Validate(); err != nil { + return nil, fmt.Errorf("model override %s: %w", id, err) + } + models[id] = model + } + return &Runtime{ + providers: config.Providers, checkpointer: config.Checkpointer, models: models, + packages: make(map[string]agentspec.Package), agents: make(map[string]entry), + locks: make(map[string]*threadLock), + maxRecordedRuns: config.MaxRecordedRuns, + }, nil +} + +// Register installs already-linked Go packages. A batch is all-or-nothing; +// versions cannot be replaced underneath existing threads. +func (r *Runtime) Register(packages ...agentspec.Package) error { + r.mu.Lock() + defer r.mu.Unlock() + pending := make(map[string]bool) + entries := make(map[string]entry, len(r.agents)) + for id, registered := range r.agents { + entries[id] = registered + } + for _, pkg := range packages { + manifest := pkg.Manifest() + if manifest.Module == "" || len(manifest.Agents) == 0 || manifest.ContractVersion != agentspec.ContractVersion { + return fmt.Errorf("uninitialized or unsupported agent package") + } + if _, exists := r.packages[manifest.Module]; exists || pending[manifest.Module] { + return fmt.Errorf("package %s is already registered", manifest.Module) + } + pending[manifest.Module] = true + for _, definition := range pkg.Definitions() { + if definition.Manifest().Kind == "prompt" && r.providers == nil { + return fmt.Errorf("agent %s requires a model provider", definition.Manifest().Name) + } + entries[pkg.AgentID(definition.Manifest().Name)] = entry{definition, manifest.Version} + } + } + if err := validateDependencies(entries); err != nil { + return err + } + for _, pkg := range packages { + manifest := pkg.Manifest() + r.packages[manifest.Module] = pkg + for _, definition := range pkg.Definitions() { + r.agents[pkg.AgentID(definition.Manifest().Name)] = entry{definition, manifest.Version} + } + } + return nil +} + +func validateDependencies(entries map[string]entry) error { + visiting, visited := make(map[string]bool), make(map[string]bool) + var visit func(string) error + visit = func(id string) error { + if visiting[id] { + return fmt.Errorf("cyclic child-agent dependency at %s", id) + } + if visited[id] { + return nil + } + visiting[id] = true + for _, child := range entries[id].definition.Manifest().Subagents { + target, ok := entries[child.AgentID] + if !ok || target.version != child.PackageVersion { + return fmt.Errorf("%s requires child %s at %s", id, child.AgentID, child.PackageVersion) + } + manifest := target.definition.Manifest() + if !reflect.DeepEqual(child.InputSchema, manifest.InputSchema) || !reflect.DeepEqual(child.OutputSchema, manifest.OutputSchema) { + return fmt.Errorf("%s child %s has incompatible input/output schemas", id, child.Name) + } + if err := visit(child.AgentID); err != nil { + return err + } + } + delete(visiting, id) + visited[id] = true + return nil + } + for id := range entries { + if err := visit(id); err != nil { + return err + } + } + return nil +} + +// Catalog returns independent, JSON-serializable package manifests for tooling. +func (r *Runtime) Catalog() []agentspec.PackageManifest { + r.mu.RLock() + defer r.mu.RUnlock() + result := make([]agentspec.PackageManifest, 0, len(r.packages)) + for _, pkg := range r.packages { + result = append(result, pkg.Manifest()) + } + sort.Slice(result, func(i, j int) bool { return result[i].Module < result[j].Module }) + return result +} + +// Thread is a durable conversation instance, distinct from its reusable agent +// definition. Histories and tool values never live on shared definitions. +type Thread struct { + ID string `json:"id"` + AgentID string `json:"agent_id"` + PackageVersion string `json:"package_version"` + ContractVersion string `json:"contract_version"` + DefinitionFingerprint string `json:"definition_fingerprint"` + Kind string `json:"kind"` + ParentID string `json:"parent_id,omitempty"` + ChildName string `json:"child_name,omitempty"` + Children map[string]string `json:"children"` + Runs map[string]RunRecord `json:"runs"` + Model agentspec.Model `json:"model"` + Messages []llm.Message `json:"messages"` + Values map[string]json.RawMessage `json:"values"` + CompletedRuns int `json:"completed_runs"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` +} + +func (r *Runtime) CreateThread(ctx context.Context, agentID string) (*Thread, error) { + // Materialize the dependency tree before writing any records. A bounded, + // acyclic tree gives each parent/alias its own stable child identity. + var created []*Thread + thread, err := r.buildThread(ctx, agentID, "", "", &created) + if err != nil { + return nil, err + } + for _, item := range created { + if err := r.save(ctx, item); err != nil { + cleanup, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second) + defer cancel() + for _, saved := range created { + _ = r.checkpointer.Delete(cleanup, saved.ID, checkpointID(saved.ID)) + } + return nil, err + } + } + return thread, nil +} + +func (r *Runtime) buildThread(ctx context.Context, agentID, parentID, childName string, created *[]*Thread) (*Thread, error) { + if err := ctx.Err(); err != nil { + return nil, err + } + r.mu.RLock() + registered, exists := r.agents[agentID] + r.mu.RUnlock() + if !exists { + return nil, fmt.Errorf("agent %s is not registered", agentID) + } + if len(*created) >= 128 { + return nil, fmt.Errorf("agent dependency tree exceeds 128 threads") + } + manifest := registered.definition.Manifest() + var model agentspec.Model + if manifest.Prompt != nil { + model = manifest.Prompt.Model + if override, ok := r.models[agentID]; ok { + model = override + } + } + now := time.Now().UTC() + thread := &Thread{ + ID: uuid.NewString(), AgentID: agentID, PackageVersion: registered.version, + ContractVersion: agentspec.ContractVersion, Model: model, + DefinitionFingerprint: registered.definition.Fingerprint(), Kind: manifest.Kind, + ParentID: parentID, ChildName: childName, Children: make(map[string]string), Runs: make(map[string]RunRecord), + Messages: []llm.Message{}, Values: make(map[string]json.RawMessage), + CreatedAt: now, UpdatedAt: now, + } + *created = append(*created, thread) + for _, child := range manifest.Subagents { + instance, err := r.buildThread(ctx, child.AgentID, thread.ID, child.Name, created) + if err != nil { + return nil, err + } + thread.Children[child.Name] = instance.ID + } + return thread, nil +} + +// ReadThread reloads a snapshot from storage. File/database checkpoint backends +// allow a new Runtime with the same package versions to continue the thread. +func (r *Runtime) ReadThread(ctx context.Context, id string) (*Thread, error) { + release, err := r.acquire(ctx, id) + if err != nil { + return nil, err + } + defer release() + return r.load(ctx, id) +} + +type Result struct { + ThreadID string `json:"thread_id"` + RequestID string `json:"request_id"` + Output json.RawMessage `json:"output"` + ModelCalls int `json:"model_calls"` + ToolCalls int `json:"tool_calls"` + ChildCalls int `json:"child_calls"` + Usage llm.Usage `json:"usage"` +} + +// Run starts a new request. Use RunWithOptions with a stable RequestID when a +// caller may redeliver a request after a timeout or restart. +func (r *Runtime) Run(ctx context.Context, threadID string, input any) (*Result, error) { + return r.RunWithOptions(ctx, threadID, input, RunOptions{}) +} + +// RunTyped adds compile-time input/output types at an application's call site. +// The registered definition remains authoritative for runtime validation. +func RunTyped[I, O any](ctx context.Context, runtime *Runtime, threadID string, input I) (O, error) { + return RunTypedWithOptions[I, O](ctx, runtime, threadID, input, RunOptions{}) +} + +func RunTypedWithOptions[I, O any](ctx context.Context, runtime *Runtime, threadID string, input I, options RunOptions) (O, error) { + var output O + thread, err := runtime.ReadThread(ctx, threadID) + if err != nil { + return output, err + } + runtime.mu.RLock() + registered, exists := runtime.agents[thread.AgentID] + runtime.mu.RUnlock() + if !exists { + return output, fmt.Errorf("agent %s is not registered", thread.AgentID) + } + if typeErr := agentspec.CheckTypes[I, O](registered.definition); typeErr != nil { + return output, typeErr + } + result, err := runtime.RunWithOptions(ctx, threadID, input, options) + if err != nil { + return output, err + } + if err := json.Unmarshal(result.Output, &output); err != nil { + return output, fmt.Errorf("decode result: %w", err) + } + return output, nil +} + +func (r *Runtime) load(ctx context.Context, id string) (*Thread, error) { + if err := ctx.Err(); err != nil { + return nil, err + } + checkpoint, err := r.checkpointer.Load(ctx, id, checkpointID(id)) + if err != nil { + return nil, fmt.Errorf("load thread %s: %w", id, err) + } + if checkpoint == nil || checkpoint.State == nil { + return nil, fmt.Errorf("thread %s has no checkpoint state", id) + } + value, exists := checkpoint.State.Get("thread") + if !exists { + return nil, fmt.Errorf("thread %s has no thread record", id) + } + data, ok := value.(string) + if !ok { + return nil, fmt.Errorf("invalid thread record encoding") + } + var thread Thread + if err := json.Unmarshal([]byte(data), &thread); err != nil { + return nil, fmt.Errorf("decode stored thread: %w", err) + } + if thread.ID != id || thread.ContractVersion != agentspec.ContractVersion || thread.Values == nil || thread.Runs == nil || thread.Children == nil || thread.DefinitionFingerprint == "" { + return nil, fmt.Errorf("invalid or unsupported stored thread %s", id) + } + if thread.Kind == "prompt" { + if err := thread.Model.Validate(); err != nil { + return nil, fmt.Errorf("stored thread model: %w", err) + } + } else if thread.Kind != "handler" { + return nil, fmt.Errorf("unsupported thread kind %q", thread.Kind) + } + return &thread, nil +} + +func (r *Runtime) save(ctx context.Context, thread *Thread) error { + if err := ctx.Err(); err != nil { + return err + } + // Keep JSON in a string envelope so a checkpointer's generic map decoding + // cannot turn large integer tool values into lossy float64 values. + data, err := json.Marshal(thread) + if err != nil { + return err + } + state := core.NewBaseState() + state.Set("thread", string(data)) + if err := r.checkpointer.Save(ctx, &persistence.Checkpoint{ + ID: checkpointID(thread.ID), ThreadID: thread.ID, State: state, + CreatedAt: thread.UpdatedAt, NodeID: "agent_thread", StepID: thread.CompletedRuns, + }); err != nil { + return fmt.Errorf("persist thread %s: %w", thread.ID, err) + } + return nil +} + +func (r *Runtime) acquire(ctx context.Context, id string) (func(), error) { + if strings.TrimSpace(id) == "" { + return nil, fmt.Errorf("thread ID is required") + } + if err := ctx.Err(); err != nil { + return nil, err + } + r.locksMu.Lock() + lock := r.locks[id] + if lock == nil { + lock = &threadLock{token: make(chan struct{}, 1)} + r.locks[id] = lock + } + lock.refs++ + r.locksMu.Unlock() + drop := func() { + r.locksMu.Lock() + defer r.locksMu.Unlock() + lock.refs-- + if lock.refs == 0 { + delete(r.locks, id) + } + } + select { + case lock.token <- struct{}{}: + return func() { <-lock.token; drop() }, nil + case <-ctx.Done(): + drop() + return nil, ctx.Err() + } +} diff --git a/pkg/agentruntime/runtime_test.go b/pkg/agentruntime/runtime_test.go new file mode 100644 index 0000000..5a7e210 --- /dev/null +++ b/pkg/agentruntime/runtime_test.go @@ -0,0 +1,414 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package agentruntime_test + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "sort" + "strings" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/UnicoLab/GoLangGraph/pkg/agentruntime" + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" + "github.com/UnicoLab/GoLangGraph/pkg/llm" + "github.com/UnicoLab/GoLangGraph/pkg/persistence" +) + +type completionFunc func(context.Context, string, llm.CompletionRequest) (*llm.CompletionResponse, error) + +func (fn completionFunc) Complete(ctx context.Context, provider string, req llm.CompletionRequest) (*llm.CompletionResponse, error) { + return fn(ctx, provider, req) +} + +type input struct { + Text string `json:"text"` +} +type output struct { + Count int `json:"count"` +} + +func counterPackage(t *testing.T, module, version string, limit int) agentspec.Package { + t.Helper() + tool, err := agentspec.NewTool("increment", "Increment this thread's counter", func(_ context.Context, state agentspec.State, _ struct{}) (output, error) { + count := 0 + if data, ok := state.GetValue("count"); ok { + if err := json.Unmarshal(data, &count); err != nil { + return output{}, err + } + data[0] = '9' // GetValue must not expose the stored byte slice. + } + count++ + data, err := json.Marshal(count) + if err != nil { + return output{}, err + } + if err := state.SetValue("count", data); err != nil { + return output{}, err + } + data[0] = '9' // SetValue must also take ownership of a copy. + if err := state.SetValue("large", json.RawMessage(`18446744073709551615`)); err != nil { + return output{}, err + } + return output{count}, nil + }) + if err != nil { + t.Fatal(err) + } + definition, err := agentspec.NewAgent[input, output](agentspec.AgentConfig{ + Name: "counter", Description: "Per-thread counter", MaxModelCalls: limit, + Prompt: agentspec.Prompt{System: "Use the counter", Model: agentspec.Model{Provider: "test", Name: "test-model", MaxTokens: 100}}, + Tools: []agentspec.Tool{tool}, + }) + if err != nil { + t.Fatal(err) + } + pkg, err := agentspec.NewPackage(module, version, "Counter package", definition) + if err != nil { + t.Fatal(err) + } + return pkg +} + +func reply(message llm.Message) *llm.CompletionResponse { + return &llm.CompletionResponse{Choices: []llm.Choice{{Message: message}}} +} + +func counterProvider(_ context.Context, _ string, req llm.CompletionRequest) (*llm.CompletionResponse, error) { + last := req.Messages[len(req.Messages)-1] + if last.Role == "tool" { + return reply(llm.Message{Content: last.Content}), nil + } + return reply(llm.Message{ToolCalls: []llm.ToolCall{{ID: fmt.Sprint(len(req.Messages)), Type: "function", Function: llm.FunctionCall{Name: "increment", Arguments: `{}`}}}}), nil +} + +func newRuntime(t *testing.T, config agentruntime.Config, packages ...agentspec.Package) *agentruntime.Runtime { + t.Helper() + if config.Providers == nil { + config.Providers = completionFunc(counterProvider) + } + runtime, err := agentruntime.New(config) + if err != nil { + t.Fatal(err) + } + if err := runtime.Register(packages...); err != nil { + t.Fatal(err) + } + return runtime +} + +func createThread(t *testing.T, runtime *agentruntime.Runtime, id string) *agentruntime.Thread { + t.Helper() + thread, err := runtime.CreateThread(context.Background(), id) + if err != nil { + t.Fatal(err) + } + return thread +} + +func TestIndependentThreadsContinueAfterReopeningFileStore(t *testing.T) { + ctx := context.Background() + pkg := counterPackage(t, "example.com/counter", "v0.1.0", 4) + dir := t.TempDir() + runtime := newRuntime(t, agentruntime.Config{Checkpointer: persistence.NewFileCheckpointer(dir)}, pkg) + first := createThread(t, runtime, pkg.AgentID("counter")) + second := createThread(t, runtime, pkg.AgentID("counter")) + for _, thread := range []*agentruntime.Thread{first, second, first} { + if _, err := runtime.Run(ctx, thread.ID, input{"hello"}); err != nil { + t.Fatal(err) + } + } + // Drop the runtime and checkpoint backend; restore only from files. + restarted := newRuntime(t, agentruntime.Config{Checkpointer: persistence.NewFileCheckpointer(dir)}, pkg) + answer, err := agentruntime.RunTyped[input, output](ctx, restarted, first.ID, input{"continue"}) + if err != nil || answer.Count != 3 { + t.Fatalf("restored count=%d, err=%v", answer.Count, err) + } + snapshot, err := restarted.ReadThread(ctx, first.ID) + if err != nil { + t.Fatal(err) + } + if snapshot.CompletedRuns != 3 || len(snapshot.Messages) != 12 || string(snapshot.Values["large"]) != "18446744073709551615" { + t.Fatalf("history or state did not round-trip: %+v", snapshot) + } + snapshot.Values["count"][0] = '9' + snapshot.Messages[0].Content = "corrupted" + other, err := restarted.ReadThread(ctx, second.ID) + if err != nil || string(other.Values["count"]) != "1" || other.CompletedRuns != 1 { + t.Fatalf("thread state leaked: %+v, %v", other, err) + } + answer, err = agentruntime.RunTyped[input, output](ctx, restarted, first.ID, input{"again"}) + if err != nil || answer.Count != 4 { + t.Fatalf("snapshot mutation affected store: %+v, %v", answer, err) + } +} + +func TestConcurrentTurnsAreSerializedPerThread(t *testing.T) { + pkg := counterPackage(t, "example.com/counter", "v0.1.0", 4) + runtime := newRuntime(t, agentruntime.Config{}, pkg) + thread := createThread(t, runtime, pkg.AgentID("counter")) + var wg sync.WaitGroup + counts := make(chan int, 12) + errors := make(chan error, 12) + for i := 0; i < 12; i++ { + wg.Add(1) + go func() { + defer wg.Done() + answer, err := agentruntime.RunTyped[input, output](context.Background(), runtime, thread.ID, input{"hello"}) + if err != nil { + errors <- err + return + } + counts <- answer.Count + }() + } + wg.Wait() + close(counts) + close(errors) + for err := range errors { + t.Fatal(err) + } + var got []int + for count := range counts { + got = append(got, count) + } + sort.Ints(got) + for i, count := range got { + if count != i+1 { + t.Fatalf("lost a concurrent turn: %v", got) + } + } + if len(got) != 12 { + t.Fatalf("missing results: %v", got) + } +} + +func TestDifferentThreadsRunConcurrentlyAndWaitersCanCancel(t *testing.T) { + pkg := counterPackage(t, "example.com/counter", "v0.1.0", 4) + entered := make(chan struct{}, 2) + release := make(chan struct{}) + provider := completionFunc(func(ctx context.Context, name string, req llm.CompletionRequest) (*llm.CompletionResponse, error) { + if req.Messages[len(req.Messages)-1].Role == "user" { + entered <- struct{}{} + select { + case <-release: + case <-ctx.Done(): + return nil, ctx.Err() + } + } + return counterProvider(ctx, name, req) + }) + runtime := newRuntime(t, agentruntime.Config{Providers: provider}, pkg) + first := createThread(t, runtime, pkg.AgentID("counter")) + second := createThread(t, runtime, pkg.AgentID("counter")) + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) + defer cancel() + finished := make(chan error, 2) + for _, id := range []string{first.ID, second.ID} { + go func(id string) { _, err := runtime.Run(ctx, id, input{"hello"}); finished <- err }(id) + } + for i := 0; i < 2; i++ { + select { + case <-entered: + case <-ctx.Done(): + t.Fatal("independent threads blocked one another") + } + } + waitCtx, waitCancel := context.WithTimeout(ctx, 20*time.Millisecond) + defer waitCancel() + if _, err := runtime.Run(waitCtx, first.ID, input{"waiting"}); !errors.Is(err, context.DeadlineExceeded) { + t.Fatalf("queued caller could not cancel: %v", err) + } + close(release) + for i := 0; i < 2; i++ { + if err := <-finished; err != nil { + t.Fatal(err) + } + } +} + +type failingSaver struct { + persistence.Checkpointer + fail bool +} + +var errSave = errors.New("storage unavailable") + +func (s *failingSaver) Save(ctx context.Context, cp *persistence.Checkpoint) error { + if s.fail { + return errSave + } + return s.Checkpointer.Save(ctx, cp) +} + +func TestValidationAndStorageFailuresNeverReportCommittedTurns(t *testing.T) { + pkg := counterPackage(t, "example.com/counter", "v0.1.0", 4) + store := &failingSaver{Checkpointer: persistence.NewMemoryCheckpointer()} + var calls atomic.Int32 + runtime := newRuntime(t, agentruntime.Config{Checkpointer: store, Providers: completionFunc(func(ctx context.Context, name string, req llm.CompletionRequest) (*llm.CompletionResponse, error) { + calls.Add(1) + return counterProvider(ctx, name, req) + })}, pkg) + thread := createThread(t, runtime, pkg.AgentID("counter")) + if _, err := runtime.Run(context.Background(), thread.ID, map[string]any{"unknown": true}); err == nil || calls.Load() != 0 { + t.Fatalf("invalid input invoked provider: %v", err) + } + store.fail = true + if _, err := runtime.Run(context.Background(), thread.ID, input{"hello"}); !errors.Is(err, errSave) { + t.Fatalf("checkpoint error swallowed: %v", err) + } + store.fail = false + snapshot, err := runtime.ReadThread(context.Background(), thread.ID) + if err != nil || snapshot.CompletedRuns != 0 || len(snapshot.Messages) != 0 || len(snapshot.Values) != 0 { + t.Fatalf("failed commit changed history: %+v, %v", snapshot, err) + } + if _, err := runtime.Run(context.Background(), "missing", input{"hello"}); err == nil { + t.Fatal("missing thread silently created") + } +} + +func TestModelLimitAndInvalidOutputDoNotCommit(t *testing.T) { + pkg := counterPackage(t, "example.com/counter", "v0.1.0", 2) + for _, test := range []struct { + name string + provider completionFunc + want error + }{ + {"limit", func(_ context.Context, _ string, _ llm.CompletionRequest) (*llm.CompletionResponse, error) { + return reply(llm.Message{ToolCalls: []llm.ToolCall{{ID: "call", Function: llm.FunctionCall{Name: "increment", Arguments: `{}`}}}}), nil + }, agentruntime.ErrModelCallLimit}, + {"output", func(_ context.Context, _ string, _ llm.CompletionRequest) (*llm.CompletionResponse, error) { + return reply(llm.Message{Content: `{"wrong":"shape"}`}), nil + }, nil}, + } { + t.Run(test.name, func(t *testing.T) { + runtime := newRuntime(t, agentruntime.Config{Providers: test.provider}, pkg) + thread := createThread(t, runtime, pkg.AgentID("counter")) + _, err := runtime.Run(context.Background(), thread.ID, input{"hello"}) + if err == nil || (test.want != nil && !errors.Is(err, test.want)) { + t.Fatalf("unexpected error: %v", err) + } + snapshot, err := runtime.ReadThread(context.Background(), thread.ID) + if err != nil || snapshot.CompletedRuns != 0 || len(snapshot.Values) != 0 { + t.Fatalf("failed run persisted: %+v, %v", snapshot, err) + } + }) + } +} + +func TestUndeclaredToolsAreObservationsAndCannotAccessHostTools(t *testing.T) { + pkg := counterPackage(t, "example.com/counter", "v0.1.0", 4) + provider := completionFunc(func(_ context.Context, _ string, req llm.CompletionRequest) (*llm.CompletionResponse, error) { + last := req.Messages[len(req.Messages)-1] + if last.Role == "tool" { + if !strings.Contains(last.Content, "not declared") { + return nil, fmt.Errorf("missing tool error observation") + } + return reply(llm.Message{Content: `{"count":0}`}), nil + } + return reply(llm.Message{ToolCalls: []llm.ToolCall{{ID: "unavailable", Function: llm.FunctionCall{Name: "shell", Arguments: `{}`}}}}), nil + }) + runtime := newRuntime(t, agentruntime.Config{Providers: provider}, pkg) + thread := createThread(t, runtime, pkg.AgentID("counter")) + if _, err := runtime.Run(context.Background(), thread.ID, input{"hello"}); err != nil { + t.Fatal(err) + } + snapshot, err := runtime.ReadThread(context.Background(), thread.ID) + if err != nil || len(snapshot.Values) != 0 || snapshot.Messages[2].ToolCallID != "unavailable" { + t.Fatalf("undeclared tool affected state or lost correlation: %+v, %v", snapshot, err) + } +} + +func TestRegistrationIsAtomicAndThreadsPinPackageVersionAndModel(t *testing.T) { + pkg := counterPackage(t, "example.com/counter", "v0.1.0", 4) + other := counterPackage(t, "example.com/other", "v0.1.0", 4) + store := persistence.NewMemoryCheckpointer() + overrides := map[string]agentspec.Model{pkg.AgentID("counter"): {Provider: "test", Name: "pinned-model", MaxTokens: 200}} + runtime := newRuntime(t, agentruntime.Config{Checkpointer: store, Models: overrides}, pkg) + delete(overrides, pkg.AgentID("counter")) + if err := runtime.Register(other, pkg); err == nil || len(runtime.Catalog()) != 1 { + t.Fatal("partially installed failed package batch") + } + thread := createThread(t, runtime, pkg.AgentID("counter")) + if thread.Model.Name != "pinned-model" { + t.Fatal("caller mutated runtime model configuration") + } + newVersion := counterPackage(t, "example.com/counter", "v0.2.0", 4) + restarted := newRuntime(t, agentruntime.Config{Checkpointer: store}, newVersion) + if _, err := restarted.Run(context.Background(), thread.ID, input{"hello"}); err == nil { + t.Fatal("thread silently upgraded its package") + } + var observed string + restored := newRuntime(t, agentruntime.Config{Checkpointer: store, Providers: completionFunc(func(ctx context.Context, provider string, req llm.CompletionRequest) (*llm.CompletionResponse, error) { + observed = req.Model + return counterProvider(ctx, provider, req) + })}, pkg) + if _, err := restored.Run(context.Background(), thread.ID, input{"hello"}); err != nil { + t.Fatal(err) + } + if observed != "pinned-model" { + t.Fatalf("restored thread switched model to %s", observed) + } +} + +type globalIDStore struct { + persistence.Checkpointer + owners map[string]string +} + +func (s *globalIDStore) Save(ctx context.Context, checkpoint *persistence.Checkpoint) error { + if owner, exists := s.owners[checkpoint.ID]; exists && owner != checkpoint.ThreadID { + return fmt.Errorf("checkpoint ID collided across threads") + } + s.owners[checkpoint.ID] = checkpoint.ThreadID + return s.Checkpointer.Save(ctx, checkpoint) +} + +func TestCheckpointIDsSupportGloballyKeyedBackends(t *testing.T) { + pkg := counterPackage(t, "example.com/counter", "v0.1.0", 4) + store := &globalIDStore{Checkpointer: persistence.NewMemoryCheckpointer(), owners: make(map[string]string)} + runtime := newRuntime(t, agentruntime.Config{Checkpointer: store}, pkg) + first := createThread(t, runtime, pkg.AgentID("counter")) + second := createThread(t, runtime, pkg.AgentID("counter")) + for _, id := range []string{first.ID, second.ID, first.ID} { + if _, err := runtime.Run(context.Background(), id, input{"hello"}); err != nil { + t.Fatal(err) + } + } + if len(store.owners) != 2 { + t.Fatalf("expected one stable checkpoint per thread, got %v", store.owners) + } +} + +func TestMultipleToolsSeePriorWritesInDeclaredOrder(t *testing.T) { + pkg := counterPackage(t, "example.com/counter", "v0.1.0", 4) + provider := completionFunc(func(_ context.Context, _ string, req llm.CompletionRequest) (*llm.CompletionResponse, error) { + last := req.Messages[len(req.Messages)-1] + if last.Role == "tool" { + previous := req.Messages[len(req.Messages)-2] + if previous.Content != `{"count":1}` || last.Content != `{"count":2}` || previous.ToolCallID != "first" || last.ToolCallID != "second" { + return nil, fmt.Errorf("tool ordering/state visibility violated: %+v, %+v", previous, last) + } + return reply(llm.Message{Content: last.Content}), nil + } + return reply(llm.Message{ToolCalls: []llm.ToolCall{ + {ID: "first", Function: llm.FunctionCall{Name: "increment", Arguments: `{}`}}, + {ID: "second", Function: llm.FunctionCall{Name: "increment", Arguments: `{}`}}, + }}), nil + }) + runtime := newRuntime(t, agentruntime.Config{Providers: provider}, pkg) + thread := createThread(t, runtime, pkg.AgentID("counter")) + result, err := runtime.Run(context.Background(), thread.ID, input{"hello"}) + if err != nil || result.ToolCalls != 2 || string(result.Output) != `{"count":2}` { + t.Fatalf("tool batch failed: %+v, %v", result, err) + } +} diff --git a/pkg/agentspec/composition.go b/pkg/agentspec/composition.go new file mode 100644 index 0000000..388c776 --- /dev/null +++ b/pkg/agentspec/composition.go @@ -0,0 +1,155 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package agentspec + +import ( + "context" + "encoding/json" + "fmt" + "reflect" + "strings" +) + +// Execution grants a handler access only to its declared tools and child agents. +// The host owns identities, storage and dependency resolution. +type Execution interface { + State + InvokeTool(context.Context, string, json.RawMessage) (json.RawMessage, error) + InvokeAgent(context.Context, string, json.RawMessage) (json.RawMessage, error) + CheckAgent(string, Schema, Schema) error +} + +type SubagentManifest struct { + Name string `json:"name"` + Description string `json:"description"` + AgentID string `json:"agent_id"` + PackageVersion string `json:"package_version"` + InputSchema Schema `json:"input_schema"` + OutputSchema Schema `json:"output_schema"` +} + +type Subagent struct{ manifest SubagentManifest } + +// NewSubagent declares one persistent child per parent thread and alias. +func NewSubagent[I, O any](name, description, agentID, version string) (Subagent, error) { + module, entry, ok := strings.Cut(agentID, "#") + if !namePattern.MatchString(name) || strings.TrimSpace(description) == "" || !ok || module == "" || !namePattern.MatchString(entry) || !versionPattern.MatchString(version) { + return Subagent{}, fmt.Errorf("child requires a name, description, qualified agent ID and exact version") + } + if err := ValidateIdentity(module, version); err != nil { + return Subagent{}, err + } + input, output, err := schemas[I, O]() + if err != nil { + return Subagent{}, err + } + return Subagent{SubagentManifest{name, description, agentID, version, input, output}}, nil +} + +func (s Subagent) Manifest() SubagentManifest { + m := s.manifest + m.InputSchema, m.OutputSchema = m.InputSchema.clone(), m.OutputSchema.clone() + return m +} + +type HandlerConfig struct { + Name string + Description string + Tools []Tool + Subagents []Subagent +} + +// NewHandler defines a deterministic Go turn with no mandatory model/provider. +// It can compose declared agents and tools using the supplied Execution. +func NewHandler[I, O any](config HandlerConfig, fn func(context.Context, Execution, I) (O, error)) (Definition, error) { + if !namePattern.MatchString(config.Name) || strings.TrimSpace(config.Description) == "" || fn == nil { + return Definition{}, fmt.Errorf("handler requires a name, description and function") + } + input, output, err := schemas[I, O]() + if err != nil { + return Definition{}, err + } + m := AgentManifest{Kind: "handler", Name: config.Name, Description: config.Description, InputSchema: input, OutputSchema: output, Tools: []ToolManifest{}} + seen := make(map[string]bool) + for _, tool := range config.Tools { + if tool.execute == nil || seen[tool.manifest.Name] { + return Definition{}, fmt.Errorf("uninitialized or duplicate tool %q", tool.manifest.Name) + } + seen[tool.manifest.Name] = true + m.Tools = append(m.Tools, tool.Manifest()) + } + for _, child := range config.Subagents { + if child.manifest.AgentID == "" || seen[child.manifest.Name] { + return Definition{}, fmt.Errorf("uninitialized or duplicate child/tool %q", child.manifest.Name) + } + seen[child.manifest.Name] = true + m.Subagents = append(m.Subagents, child.Manifest()) + } + d := Definition{ + manifest: m, tools: append([]Tool(nil), config.Tools...), subagents: append([]Subagent(nil), config.Subagents...), + inputType: reflect.TypeOf((*I)(nil)).Elem(), outputType: reflect.TypeOf((*O)(nil)).Elem(), + validateInput: func(raw json.RawMessage) error { _, err := decode[I](raw, input); return err }, + validateOutput: func(raw json.RawMessage) error { _, err := decode[O](raw, output); return err }, + } + d.handler = func(ctx context.Context, state Execution, raw json.RawMessage) (json.RawMessage, error) { + value, err := decode[I](raw, input) + if err != nil { + return nil, err + } + result, err := fn(ctx, state, value) + if err != nil { + return nil, err + } + data, err := json.Marshal(result) + if err != nil { + return nil, err + } + if err := d.ValidateOutput(data); err != nil { + return nil, err + } + return data, nil + } + return d, nil +} + +func (d Definition) Handle(ctx context.Context, state Execution, input json.RawMessage) (json.RawMessage, error) { + if err := ctx.Err(); err != nil { + return nil, err + } + if state == nil { + return nil, fmt.Errorf("handler requires an execution state") + } + if d.handler == nil { + return nil, fmt.Errorf("agent is not a Go handler") + } + return d.handler(ctx, state, input) +} + +// CallAgent encodes typed input and decodes a child's validated output. Declare +// the same types with NewSubagent so registration verifies the boundary. +func CallAgent[I, O any](ctx context.Context, state Execution, name string, input I) (O, error) { + var output O + inputSchema, outputSchema, err := schemas[I, O]() + if err != nil { + return output, err + } + if typeErr := state.CheckAgent(name, inputSchema, outputSchema); typeErr != nil { + return output, typeErr + } + data, err := json.Marshal(input) + if err != nil { + return output, err + } + if _, validationErr := decode[I](data, inputSchema); validationErr != nil { + return output, validationErr + } + data, err = state.InvokeAgent(ctx, name, data) + if err != nil { + return output, err + } + return decode[O](data, outputSchema) +} diff --git a/pkg/agentspec/contract_test.go b/pkg/agentspec/contract_test.go new file mode 100644 index 0000000..531a9b7 --- /dev/null +++ b/pkg/agentspec/contract_test.go @@ -0,0 +1,158 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package agentspec_test + +import ( + "context" + "encoding/json" + "strings" + "testing" + + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" +) + +type constrained struct { + Text string `json:"text" description:"A short greeting" minLength:"1" maxLength:"3"` + Style string `json:"style" enum:"formal,casual"` +} + +func constrainedPackage(t *testing.T) agentspec.Package { + t.Helper() + d, err := agentspec.NewHandler[constrained, constrained](agentspec.HandlerConfig{Name: "echo", Description: "Echo"}, func(_ context.Context, _ agentspec.Execution, i constrained) (constrained, error) { return i, nil }) + if err != nil { + t.Fatal(err) + } + pkg, err := agentspec.NewPackage("example.com/echo", "v0.1.0", "Echo", d) + if err != nil { + t.Fatal(err) + } + return pkg +} + +func TestSchemaConstraintsAndAmbiguousJSON(t *testing.T) { + pkg := constrainedPackage(t) + d := pkg.Definitions()[0] + if err := d.ValidateInput(json.RawMessage(`{"text":"猫猫猫","style":"formal"}`)); err != nil { + t.Fatalf("length must count Unicode characters: %v", err) + } + for _, raw := range []string{ + `{"text":"","style":"formal"}`, `{"text":"long","style":"formal"}`, `{"text":"hi","style":"other"}`, + `{"text":"hi","text":"bad","style":"formal"}`, `{"text":"hi","\u0074ext":"bad","style":"formal"}`, + `{"text":"hi","style":"formal"} {}`, `{"text":"hi","style":"formal","unknown":1}`, + strings.Repeat("[", 65) + strings.Repeat("]", 65), + } { + if err := d.ValidateInput(json.RawMessage(raw)); err == nil { + t.Fatalf("accepted %s", raw) + } + } + manifest := d.Manifest() + property := manifest.InputSchema.Properties["text"] + if property.Description != "A short greeting" || *property.MaxLength != 3 { + t.Fatalf("constraints not advertised: %+v", property) + } + *property.MaxLength = 500 + style := manifest.InputSchema.Properties["style"] + style.Enum[0] = "other" + if err := d.ValidateInput(json.RawMessage(`{"text":"long","style":"formal"}`)); err == nil { + t.Fatal("manifest mutation changed validation") + } +} + +func TestManifestRoundTripAndRejectedCapabilities(t *testing.T) { + pkg := constrainedPackage(t) + data, err := json.Marshal(pkg.Manifest()) + if err != nil { + t.Fatal(err) + } + manifest, err := agentspec.ParseManifest(data) + if err != nil { + t.Fatal(err) + } + if manifest.Agents[0].Kind != "handler" || manifest.Agents[0].Prompt != nil { + t.Fatal("handler became prompt") + } + for _, mutate := range []func(*agentspec.PackageManifest){ + func(m *agentspec.PackageManifest) { m.ContractVersion = "unknown" }, + func(m *agentspec.PackageManifest) { m.Agents[0].Kind = "unknown" }, + func(m *agentspec.PackageManifest) { m.Agents[0].MaxModelCalls = 3 }, + func(m *agentspec.PackageManifest) { m.Agents[0].InputSchema.AdditionalProperties = nil }, + func(m *agentspec.PackageManifest) { m.Agents[0].InputSchema.Required = []string{"missing"} }, + func(m *agentspec.PackageManifest) { m.Agents = append(m.Agents, m.Agents[0]) }, + } { + copy, err := agentspec.ParseManifest(data) + if err != nil { + t.Fatal(err) + } + mutate(©) + if err := copy.Validate(); err == nil { + t.Fatalf("invalid manifest accepted: %+v", copy) + } + } + unknown := strings.Replace(string(data), `"kind":"handler"`, `"kind":"handler","executable":"unsafe"`, 1) + if _, err := agentspec.ParseManifest([]byte(unknown)); err == nil { + t.Fatal("unknown field accepted") + } +} + +func TestInvalidConstraintTagsFailDefinitionCreation(t *testing.T) { + check := func(err error) { + t.Helper() + if err == nil { + t.Fatal("invalid constraints accepted") + } + } + _, err := agentspec.NewHandler[struct { + N int `enum:"a,b"` + }, struct{}](agentspec.HandlerConfig{Name: "bad", Description: "Bad"}, func(context.Context, agentspec.Execution, struct { + N int `enum:"a,b"` + }) (struct{}, error) { + return struct{}{}, nil + }) + check(err) + _, err = agentspec.NewHandler[struct { + N string `minLength:"4" maxLength:"2"` + }, struct{}](agentspec.HandlerConfig{Name: "bad", Description: "Bad"}, func(context.Context, agentspec.Execution, struct { + N string `minLength:"4" maxLength:"2"` + }) (struct{}, error) { + return struct{}{}, nil + }) + check(err) + _, err = agentspec.NewSubagent[struct{}, struct{}]("child", "Child", "example.com/child#entry", "v1.0.0-01") + check(err) +} + +type hiddenFields struct { + Text string `json:"text"` +} +type encodedNumber int + +func (encodedNumber) MarshalText() ([]byte, error) { return []byte("number"), nil } + +func TestSchemaRejectsHiddenEmbeddingAndTextEncoding(t *testing.T) { + _, err := agentspec.NewHandler[struct{ hiddenFields }, struct{}](agentspec.HandlerConfig{Name: "bad", Description: "Bad"}, func(context.Context, agentspec.Execution, struct{ hiddenFields }) (struct{}, error) { + return struct{}{}, nil + }) + if err == nil { + t.Fatal("unexported embedding silently omitted exported JSON fields") + } + _, err = agentspec.NewHandler[struct{ N encodedNumber }, struct{}](agentspec.HandlerConfig{Name: "bad", Description: "Bad"}, func(context.Context, agentspec.Execution, struct{ N encodedNumber }) (struct{}, error) { + return struct{}{}, nil + }) + if err == nil { + t.Fatal("text marshaler advertised a numeric JSON type") + } + _, err = agentspec.NewHandler[struct { + N string `json:"bad\\name"` + }, struct{}](agentspec.HandlerConfig{Name: "bad", Description: "Bad"}, func(context.Context, agentspec.Execution, struct { + N string `json:"bad\\name"` + }) (struct{}, error) { + return struct{}{}, nil + }) + if err == nil { + t.Fatal("invalid JSON tag advertised a different wire name") + } +} diff --git a/pkg/agentspec/fuzz_test.go b/pkg/agentspec/fuzz_test.go new file mode 100644 index 0000000..80423ea --- /dev/null +++ b/pkg/agentspec/fuzz_test.go @@ -0,0 +1,49 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package agentspec_test + +import ( + "context" + "encoding/json" + "testing" + + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" +) + +func FuzzManifest(f *testing.F) { + definition, err := agentspec.NewHandler[constrained, constrained](agentspec.HandlerConfig{Name: "echo", Description: "Echo"}, func(_ context.Context, _ agentspec.Execution, i constrained) (constrained, error) { return i, nil }) + if err != nil { + f.Fatal(err) + } + pkg, err := agentspec.NewPackage("example.com/echo", "v0.1.0", "Echo", definition) + if err != nil { + f.Fatal(err) + } + data, err := json.Marshal(pkg.Manifest()) + if err != nil { + f.Fatal(err) + } + f.Add(data) + f.Add([]byte(`{"module":"a","module":"b"}`)) + f.Add([]byte(`{"agents":[{"input_schema":{"items":{}}}]}`)) + f.Fuzz(func(t *testing.T, data []byte) { + if len(data) > 1<<20 { + t.Skip() + } + manifest, err := agentspec.ParseManifest(data) + if err != nil { + return + } + encoded, err := json.Marshal(manifest) + if err != nil { + t.Fatal(err) + } + if _, err := agentspec.ParseManifest(encoded); err != nil { + t.Fatalf("accepted manifest cannot round-trip: %v", err) + } + }) +} diff --git a/pkg/agentspec/manifest.go b/pkg/agentspec/manifest.go new file mode 100644 index 0000000..9a3b9aa --- /dev/null +++ b/pkg/agentspec/manifest.go @@ -0,0 +1,154 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package agentspec + +import ( + "bytes" + "encoding/json" + "fmt" + "strings" +) + +// ParseManifest validates introspection data without loading executable code. +// The schema subset is deliberately closed: unknown fields are errors. +func ParseManifest(data []byte) (PackageManifest, error) { + var manifest PackageManifest + // Schemas nest properties and schema objects at each level, so their JSON + // representation needs more depth than an ordinary validated input value. + if err := validateJSON(data, 128); err != nil { + return manifest, err + } + decoder := json.NewDecoder(bytes.NewReader(data)) + decoder.DisallowUnknownFields() + if err := decoder.Decode(&manifest); err != nil { + return manifest, err + } + return manifest, manifest.Validate() +} + +func (m PackageManifest) Validate() error { + if err := ValidateIdentity(m.Module, m.Version); err != nil { + return err + } + if m.ContractVersion != ContractVersion || strings.TrimSpace(m.Description) == "" || len(m.Agents) == 0 { + return fmt.Errorf("manifest requires supported contract, description and agents") + } + seen := make(map[string]bool) + for _, agent := range m.Agents { + if !namePattern.MatchString(agent.Name) || strings.TrimSpace(agent.Description) == "" || seen[agent.Name] { + return fmt.Errorf("invalid or duplicate agent %q", agent.Name) + } + seen[agent.Name] = true + switch agent.Kind { + case "prompt": + if agent.Prompt == nil || strings.TrimSpace(agent.Prompt.System) == "" || agent.MaxModelCalls < 1 || agent.MaxModelCalls > 100 { + return fmt.Errorf("agent %s requires a prompt and model-call budget", agent.Name) + } + if err := agent.Prompt.Model.Validate(); err != nil { + return err + } + case "handler": + if agent.Prompt != nil || agent.MaxModelCalls != 0 { + return fmt.Errorf("handler %s cannot define a prompt or model-call budget", agent.Name) + } + default: + return fmt.Errorf("unsupported agent kind %q", agent.Kind) + } + if err := validateBoundary(agent.InputSchema, agent.OutputSchema); err != nil { + return fmt.Errorf("agent %s: %w", agent.Name, err) + } + capabilities := make(map[string]bool) + for _, tool := range agent.Tools { + if !namePattern.MatchString(tool.Name) || strings.TrimSpace(tool.Description) == "" || capabilities[tool.Name] { + return fmt.Errorf("invalid or duplicate tool %q", tool.Name) + } + capabilities[tool.Name] = true + if err := validateBoundary(tool.InputSchema, tool.OutputSchema); err != nil { + return fmt.Errorf("tool %s: %w", tool.Name, err) + } + } + for _, child := range agent.Subagents { + module, entry, ok := strings.Cut(child.AgentID, "#") + if !namePattern.MatchString(child.Name) || strings.TrimSpace(child.Description) == "" || capabilities[child.Name] || !ok || !namePattern.MatchString(entry) { + return fmt.Errorf("invalid or duplicate child %q", child.Name) + } + capabilities[child.Name] = true + if err := ValidateIdentity(module, child.PackageVersion); err != nil { + return err + } + if err := validateBoundary(child.InputSchema, child.OutputSchema); err != nil { + return fmt.Errorf("child %s: %w", child.Name, err) + } + } + } + return nil +} + +func validateBoundary(input, output Schema) error { + for _, schema := range []Schema{input, output} { + if schema.Type != "object" { + return fmt.Errorf("input/output schemas must be objects") + } + if err := schema.check(0); err != nil { + return err + } + } + return nil +} + +func (s Schema) check(depth int) error { + if depth > 32 { + return fmt.Errorf("schema nesting exceeds 32 levels") + } + if s.Type != "object" && (len(s.Properties) > 0 || len(s.Required) > 0 || s.AdditionalProperties != nil) { + return fmt.Errorf("object fields on non-object schema") + } + if s.Type != "array" && s.Items != nil { + return fmt.Errorf("items on non-array schema") + } + if s.Type != "string" && (len(s.Enum) > 0 || s.MinLength != nil || s.MaxLength != nil) { + return fmt.Errorf("string constraints on non-string schema") + } + switch s.Type { + case "object": + if s.AdditionalProperties == nil || *s.AdditionalProperties { + return fmt.Errorf("object schemas must disallow additional properties") + } + seen := make(map[string]bool) + for _, name := range s.Required { + if _, ok := s.Properties[name]; !ok || seen[name] { + return fmt.Errorf("invalid required field %q", name) + } + seen[name] = true + } + for _, property := range s.Properties { + if err := property.check(depth + 1); err != nil { + return err + } + } + case "array": + if s.Items == nil { + return fmt.Errorf("array schema requires items") + } + return s.Items.check(depth + 1) + case "string": + if (s.MinLength != nil && *s.MinLength < 0) || (s.MaxLength != nil && *s.MaxLength < 0) || (s.MinLength != nil && s.MaxLength != nil && *s.MinLength > *s.MaxLength) { + return fmt.Errorf("invalid string length constraints") + } + seen := make(map[string]bool) + for _, value := range s.Enum { + if seen[value] { + return fmt.Errorf("duplicate enum value") + } + seen[value] = true + } + case "boolean", "integer", "number": + default: + return fmt.Errorf("unsupported schema type %q", s.Type) + } + return nil +} diff --git a/pkg/agentspec/schema.go b/pkg/agentspec/schema.go new file mode 100644 index 0000000..b29ff4b --- /dev/null +++ b/pkg/agentspec/schema.go @@ -0,0 +1,349 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package agentspec + +import ( + "bytes" + "encoding" + "encoding/json" + "fmt" + "io" + "reflect" + "strconv" + "strings" + "unicode" + "unicode/utf8" +) + +// Schema is the JSON Schema subset generated for plain Go value types. The +// initial contract supports structs, slices, strings, booleans and numbers. +// Pointers, maps, embedded fields and custom JSON encoders are rejected rather +// than advertising a schema that differs from the actual wire representation. +type Schema struct { + Type string `json:"type"` + Properties map[string]Schema `json:"properties,omitempty"` + Required []string `json:"required,omitempty"` + Items *Schema `json:"items,omitempty"` + AdditionalProperties *bool `json:"additionalProperties,omitempty"` + Description string `json:"description,omitempty"` + Enum []string `json:"enum,omitempty"` + MinLength *int `json:"minLength,omitempty"` + MaxLength *int `json:"maxLength,omitempty"` +} + +func schemaFor(t reflect.Type, visiting map[reflect.Type]bool) (Schema, error) { + if len(visiting) > 32 { + return Schema{}, fmt.Errorf("schema nesting exceeds 32 levels") + } + if t == nil || visiting[t] { + return Schema{}, fmt.Errorf("unsupported recursive or interface type %v", t) + } + marshaler := reflect.TypeOf((*json.Marshaler)(nil)).Elem() + unmarshaler := reflect.TypeOf((*json.Unmarshaler)(nil)).Elem() + textMarshaler := reflect.TypeOf((*encoding.TextMarshaler)(nil)).Elem() + textUnmarshaler := reflect.TypeOf((*encoding.TextUnmarshaler)(nil)).Elem() + if t.Implements(marshaler) || reflect.PointerTo(t).Implements(marshaler) || reflect.PointerTo(t).Implements(unmarshaler) || + t.Implements(textMarshaler) || reflect.PointerTo(t).Implements(textMarshaler) || reflect.PointerTo(t).Implements(textUnmarshaler) { + return Schema{}, fmt.Errorf("custom JSON encoding is unsupported for %v", t) + } + visiting[t] = true + defer delete(visiting, t) + s := Schema{} + switch t.Kind() { + case reflect.String: + s.Type = "string" + case reflect.Bool: + s.Type = "boolean" + case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64, + reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64: + s.Type = "integer" + case reflect.Float32, reflect.Float64: + s.Type = "number" + case reflect.Slice: + if t.Elem().Kind() == reflect.Uint8 { + return Schema{}, fmt.Errorf("byte slices have a special JSON representation; use a string") + } + item, err := schemaFor(t.Elem(), visiting) + if err != nil { + return Schema{}, err + } + s.Type, s.Items = "array", &item + case reflect.Struct: + s.Type = "object" + allow := false + s.AdditionalProperties = &allow + s.Properties = make(map[string]Schema) + for i := 0; i < t.NumField(); i++ { + field := t.Field(i) + if field.Tag.Get("json") == "-" { + continue + } + if field.Anonymous { + return Schema{}, fmt.Errorf("embedded field %s is unsupported", field.Name) + } + if field.PkgPath != "" { + continue + } + parts := strings.Split(field.Tag.Get("json"), ",") + name := parts[0] + if name == "" { + name = field.Name + } + // Match encoding/json's accepted tag characters. It silently ignores + // invalid names; a contract must reject them instead of diverging. + for _, char := range name { + if !unicode.IsLetter(char) && !unicode.IsDigit(char) && !strings.ContainsRune("!#$%&()*+-./:;<=>?@[]^_{|}~ ", char) { + return Schema{}, fmt.Errorf("invalid JSON field name %q", name) + } + } + optional := false + for _, option := range parts[1:] { + if option != "omitempty" { + return Schema{}, fmt.Errorf("unsupported JSON option %q on %s", option, field.Name) + } + optional = true + } + if _, exists := s.Properties[name]; exists { + return Schema{}, fmt.Errorf("duplicate JSON field %q", name) + } + property, err := schemaFor(field.Type, visiting) + if err != nil { + return Schema{}, fmt.Errorf("field %s: %w", name, err) + } + property.Description = field.Tag.Get("description") + if enum, exists := field.Tag.Lookup("enum"); exists { + if property.Type != "string" || enum == "" { + return Schema{}, fmt.Errorf("enum on %s requires a string and comma-separated values", name) + } + property.Enum = strings.Split(enum, ",") + seen := make(map[string]bool) + for _, value := range property.Enum { + if seen[value] { + return Schema{}, fmt.Errorf("duplicate enum value on %s", name) + } + seen[value] = true + } + } + for tag, target := range map[string]**int{"minLength": &property.MinLength, "maxLength": &property.MaxLength} { + if raw, exists := field.Tag.Lookup(tag); exists { + value, err := strconv.Atoi(raw) + if property.Type != "string" || err != nil || value < 0 { + return Schema{}, fmt.Errorf("%s on %s requires a non-negative string length", tag, name) + } + *target = &value + } + } + if property.MinLength != nil && property.MaxLength != nil && *property.MinLength > *property.MaxLength { + return Schema{}, fmt.Errorf("minLength exceeds maxLength on %s", name) + } + s.Properties[name] = property + if !optional { + s.Required = append(s.Required, name) + } + } + default: + return Schema{}, fmt.Errorf("unsupported contract type %v", t) + } + return s, nil +} + +func (s Schema) clone() Schema { + out := s + out.Required = append([]string(nil), s.Required...) + out.Enum = append([]string(nil), s.Enum...) + if s.MinLength != nil { + value := *s.MinLength + out.MinLength = &value + } + if s.MaxLength != nil { + value := *s.MaxLength + out.MaxLength = &value + } + if s.AdditionalProperties != nil { + value := *s.AdditionalProperties + out.AdditionalProperties = &value + } + if s.Properties != nil { + out.Properties = make(map[string]Schema, len(s.Properties)) + for key, value := range s.Properties { + out.Properties[key] = value.clone() + } + } + if s.Items != nil { + item := s.Items.clone() + out.Items = &item + } + return out +} + +func (s Schema) validate(value any, path string) error { + valid := false + switch s.Type { + case "object": + object, ok := value.(map[string]any) + if !ok { + break + } + for _, name := range s.Required { + if _, exists := object[name]; !exists { + return fmt.Errorf("%s.%s is required", path, name) + } + } + for name, field := range object { + property, exists := s.Properties[name] + if !exists { + return fmt.Errorf("%s.%s is not declared", path, name) + } + if err := property.validate(field, path+"."+name); err != nil { + return err + } + } + valid = true + case "array": + values, ok := value.([]any) + if !ok { + break + } + for i, item := range values { + if err := s.Items.validate(item, fmt.Sprintf("%s[%d]", path, i)); err != nil { + return err + } + } + valid = true + case "string": + var text string + text, valid = value.(string) + if valid { + length := utf8.RuneCountInString(text) + if s.MinLength != nil && length < *s.MinLength { + return fmt.Errorf("%s is shorter than minLength %d", path, *s.MinLength) + } + if s.MaxLength != nil && length > *s.MaxLength { + return fmt.Errorf("%s exceeds maxLength %d", path, *s.MaxLength) + } + if len(s.Enum) > 0 { + found := false + for _, allowed := range s.Enum { + if text == allowed { + found = true + } + } + if !found { + return fmt.Errorf("%s must be one of %v", path, s.Enum) + } + } + } + case "boolean": + _, valid = value.(bool) + case "number": + _, valid = value.(json.Number) + case "integer": + if number, ok := value.(json.Number); ok { + _, signedErr := strconv.ParseInt(string(number), 10, 64) + _, unsignedErr := strconv.ParseUint(string(number), 10, 64) + valid = signedErr == nil || unsignedErr == nil + } + } + if !valid { + return fmt.Errorf("%s must be %s", path, s.Type) + } + return nil +} + +// Validator adds semantic validation to a typed input or output. Implement it +// on a value or pointer receiver; schemas describe structure, Validate describes +// domain rules such as non-empty requests or allowed styles. +type Validator interface { + Validate() error +} + +func decode[T any](data json.RawMessage, schema Schema) (T, error) { + var output T + if err := validateJSON(data, 64); err != nil { + return output, err + } + decoder := json.NewDecoder(bytes.NewReader(data)) + decoder.UseNumber() + var value any + if err := decoder.Decode(&value); err != nil { + return output, err + } + if err := decoder.Decode(new(any)); err != io.EOF { + return output, fmt.Errorf("expected exactly one JSON value") + } + if err := schema.validate(value, "$"); err != nil { + return output, err + } + if err := json.Unmarshal(data, &output); err != nil { + return output, err + } + if validator, ok := any(&output).(Validator); ok { + if err := validator.Validate(); err != nil { + return output, err + } + } + return output, nil +} + +// validateJSON rejects ambiguous duplicate keys (including escaped spellings), +// excessive nesting and trailing values before decoding into a Go struct. +func validateJSON(data []byte, maximumDepth int) error { + if !utf8.Valid(data) { + return fmt.Errorf("JSON must be valid UTF-8") + } + decoder := json.NewDecoder(bytes.NewReader(data)) + decoder.UseNumber() + var value func(int) error + value = func(depth int) error { + if depth > maximumDepth { + return fmt.Errorf("JSON nesting exceeds %d levels", maximumDepth) + } + token, err := decoder.Token() + if err != nil { + return err + } + delimiter, ok := token.(json.Delim) + if !ok { + return nil + } + switch delimiter { + case '{': + seen := make(map[string]bool) + for decoder.More() { + key, keyErr := decoder.Token() + if keyErr != nil { + return keyErr + } + name, ok := key.(string) + if !ok || seen[name] { + return fmt.Errorf("invalid or duplicate JSON key %q", key) + } + seen[name] = true + if nestedErr := value(depth + 1); nestedErr != nil { + return nestedErr + } + } + case '[': + for decoder.More() { + if nestedErr := value(depth + 1); nestedErr != nil { + return nestedErr + } + } + default: + return fmt.Errorf("unexpected JSON delimiter %s", delimiter) + } + _, err = decoder.Token() + return err + } + if err := value(0); err != nil { + return err + } + if _, err := decoder.Token(); err != io.EOF { + return fmt.Errorf("expected exactly one JSON value") + } + return nil +} diff --git a/pkg/agentspec/schema_internal_test.go b/pkg/agentspec/schema_internal_test.go new file mode 100644 index 0000000..d9be5fb --- /dev/null +++ b/pkg/agentspec/schema_internal_test.go @@ -0,0 +1,24 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package agentspec + +import ( + "reflect" + "testing" +) + +func TestSchemaRejectsDuplicateWireNames(t *testing.T) { + // Construct the invalid type dynamically: a literal duplicate tag is itself + // rejected by go vet before this negative contract test can run. + typeWithDuplicates := reflect.StructOf([]reflect.StructField{ + {Name: "First", Type: reflect.TypeOf(""), Tag: `json:"text"`}, + {Name: "Second", Type: reflect.TypeOf(""), Tag: `json:"text"`}, + }) + if _, err := schemaFor(typeWithDuplicates, make(map[reflect.Type]bool)); err == nil { + t.Fatal("duplicate JSON field accepted") + } +} diff --git a/pkg/agentspec/spec.go b/pkg/agentspec/spec.go new file mode 100644 index 0000000..0840a12 --- /dev/null +++ b/pkg/agentspec/spec.go @@ -0,0 +1,338 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +// Package agentspec defines the experimental Go-native agent package contract. +// It depends only on the standard library, not on GoLangGraph's graph engine. +// Definitions are immutable; mutable tool data belongs in the invocation State. +package agentspec + +import ( + "context" + "crypto/sha256" + "encoding/json" + "fmt" + "math" + "path" + "reflect" + "regexp" + "strings" +) + +const ContractVersion = "golanggraph.agent/v1alpha1" + +// Model is a package's default model profile. Credentials belong to the host. +type Model struct { + Provider string `json:"provider"` + Name string `json:"name"` + Temperature float64 `json:"temperature"` + MaxTokens int `json:"max_tokens"` +} + +func (m Model) Validate() error { + if strings.TrimSpace(m.Provider) == "" || strings.TrimSpace(m.Name) == "" { + return fmt.Errorf("model provider and name are required") + } + if math.IsNaN(m.Temperature) || math.IsInf(m.Temperature, 0) || m.Temperature < 0 || m.Temperature > 2 { + return fmt.Errorf("temperature must be between 0 and 2") + } + if m.MaxTokens <= 0 { + return fmt.Errorf("max_tokens must be positive") + } + return nil +} + +type Prompt struct { + System string `json:"system"` + Model Model `json:"model"` +} + +// State is scoped to one thread and valid only for the duration of a tool call. +// Values are JSON, copied on access and committed with a successful turn. Tool +// functions must not retain State or capture mutable per-conversation globals. +type State interface { + ThreadID() string + GetValue(key string) (json.RawMessage, bool) + SetValue(key string, value json.RawMessage) error +} + +type ToolManifest struct { + Name string `json:"name"` + Description string `json:"description"` + InputSchema Schema `json:"input_schema"` + OutputSchema Schema `json:"output_schema"` +} + +type Tool struct { + manifest ToolManifest + execute func(context.Context, State, json.RawMessage) (json.RawMessage, error) +} + +var namePattern = regexp.MustCompile(`^[a-z][a-z0-9_]{0,63}$`) + +// NewTool derives schemas from Go types and validates both arguments and results. +// Tool errors are returned to the model by the runtime; cancellation stops a run. +func NewTool[I, O any](name, description string, fn func(context.Context, State, I) (O, error)) (Tool, error) { + if !namePattern.MatchString(name) || strings.TrimSpace(description) == "" || fn == nil { + return Tool{}, fmt.Errorf("tool requires a snake_case name, description and function") + } + input, output, err := schemas[I, O]() + if err != nil { + return Tool{}, err + } + tool := Tool{manifest: ToolManifest{name, description, input, output}} + tool.execute = func(ctx context.Context, state State, raw json.RawMessage) (json.RawMessage, error) { + if err := ctx.Err(); err != nil { + return nil, err + } + args, err := decode[I](raw, input) + if err != nil { + return nil, fmt.Errorf("tool %s input: %w", name, err) + } + result, err := fn(ctx, state, args) + if err != nil { + return nil, err + } + data, err := json.Marshal(result) + if err != nil { + return nil, err + } + if _, err := decode[O](data, output); err != nil { + return nil, fmt.Errorf("tool %s output: %w", name, err) + } + return data, nil + } + return tool, nil +} + +func (t Tool) Manifest() ToolManifest { + m := t.manifest + m.InputSchema, m.OutputSchema = m.InputSchema.clone(), m.OutputSchema.clone() + return m +} + +func (t Tool) Execute(ctx context.Context, state State, input json.RawMessage) (json.RawMessage, error) { + if t.execute == nil || state == nil { + return nil, fmt.Errorf("uninitialized tool or missing invocation state") + } + return t.execute(ctx, state, input) +} + +type AgentManifest struct { + Kind string `json:"kind"` + Name string `json:"name"` + Description string `json:"description"` + InputSchema Schema `json:"input_schema"` + OutputSchema Schema `json:"output_schema"` + Prompt *Prompt `json:"prompt,omitempty"` + Tools []ToolManifest `json:"tools"` + Subagents []SubagentManifest `json:"subagents,omitempty"` + MaxModelCalls int `json:"max_model_calls"` +} + +type AgentConfig struct { + Name string + Description string + Prompt Prompt + Tools []Tool + Subagents []Subagent + MaxModelCalls int +} + +// Definition describes a prompt/tool agent without holding a live conversation. +type Definition struct { + manifest AgentManifest + tools []Tool + subagents []Subagent + handler func(context.Context, Execution, json.RawMessage) (json.RawMessage, error) + inputType reflect.Type + outputType reflect.Type + validateInput func(json.RawMessage) error + validateOutput func(json.RawMessage) error +} + +func NewAgent[I, O any](config AgentConfig) (Definition, error) { + if !namePattern.MatchString(config.Name) || strings.TrimSpace(config.Description) == "" || strings.TrimSpace(config.Prompt.System) == "" { + return Definition{}, fmt.Errorf("agent requires a snake_case name, description and system prompt") + } + if err := config.Prompt.Model.Validate(); err != nil { + return Definition{}, err + } + if config.MaxModelCalls == 0 { + config.MaxModelCalls = 8 + } + if config.MaxModelCalls < 1 || config.MaxModelCalls > 100 { + return Definition{}, fmt.Errorf("max_model_calls must be between 1 and 100") + } + input, output, err := schemas[I, O]() + if err != nil { + return Definition{}, err + } + manifest := AgentManifest{ + Kind: "prompt", Name: config.Name, Description: config.Description, Prompt: &config.Prompt, + InputSchema: input, OutputSchema: output, MaxModelCalls: config.MaxModelCalls, + Tools: make([]ToolManifest, 0, len(config.Tools)), + } + seen := make(map[string]bool) + for _, tool := range config.Tools { + if tool.execute == nil || seen[tool.manifest.Name] { + return Definition{}, fmt.Errorf("uninitialized or duplicate tool %q", tool.manifest.Name) + } + seen[tool.manifest.Name] = true + manifest.Tools = append(manifest.Tools, tool.Manifest()) + } + for _, child := range config.Subagents { + if child.manifest.AgentID == "" || seen[child.manifest.Name] { + return Definition{}, fmt.Errorf("uninitialized or duplicate child/tool %q", child.manifest.Name) + } + seen[child.manifest.Name] = true + manifest.Subagents = append(manifest.Subagents, child.Manifest()) + } + return Definition{ + manifest: manifest, tools: append([]Tool(nil), config.Tools...), + subagents: append([]Subagent(nil), config.Subagents...), + inputType: reflect.TypeOf((*I)(nil)).Elem(), outputType: reflect.TypeOf((*O)(nil)).Elem(), + validateInput: func(data json.RawMessage) error { _, err := decode[I](data, input); return err }, + validateOutput: func(data json.RawMessage) error { _, err := decode[O](data, output); return err }, + }, nil +} + +func schemas[I, O any]() (Schema, Schema, error) { + input, err := schemaFor(reflect.TypeOf((*I)(nil)).Elem(), make(map[reflect.Type]bool)) + if err != nil { + return Schema{}, Schema{}, fmt.Errorf("input schema: %w", err) + } + output, err := schemaFor(reflect.TypeOf((*O)(nil)).Elem(), make(map[reflect.Type]bool)) + if err != nil { + return Schema{}, Schema{}, fmt.Errorf("output schema: %w", err) + } + if input.Type != "object" || output.Type != "object" { + return Schema{}, Schema{}, fmt.Errorf("input and output must be structs") + } + return input, output, nil +} + +func (d Definition) Manifest() AgentManifest { + m := d.manifest + if m.Prompt != nil { + prompt := *m.Prompt + m.Prompt = &prompt + } + m.InputSchema, m.OutputSchema = m.InputSchema.clone(), m.OutputSchema.clone() + m.Tools = make([]ToolManifest, len(d.tools)) + for i, tool := range d.tools { + m.Tools[i] = tool.Manifest() + } + m.Subagents = make([]SubagentManifest, len(d.subagents)) + for i, child := range d.subagents { + m.Subagents[i] = child.Manifest() + } + return m +} + +func (d Definition) Tools() []Tool { return append([]Tool(nil), d.tools...) } + +// CheckTypes rejects mismatched typed calls before any work or state writes. +// Callers use the package's exported types (or aliases of those types). +func CheckTypes[I, O any](d Definition) error { + if d.inputType != reflect.TypeOf((*I)(nil)).Elem() || d.outputType != reflect.TypeOf((*O)(nil)).Elem() { + return fmt.Errorf("typed invocation requires input %v and output %v", d.inputType, d.outputType) + } + return nil +} + +// Fingerprint identifies the declarative behavior of an agent. It detects +// changes to prompts, schemas, models and dependencies, not changes to Go code. +func (d Definition) Fingerprint() string { + data, _ := json.Marshal(d.Manifest()) + return fmt.Sprintf("sha256:%x", sha256.Sum256(data)) +} + +func (d Definition) ValidateInput(data json.RawMessage) error { + if d.validateInput == nil { + return fmt.Errorf("uninitialized definition") + } + return d.validateInput(data) +} + +func (d Definition) ValidateOutput(data json.RawMessage) error { + if d.validateOutput == nil { + return fmt.Errorf("uninitialized definition") + } + return d.validateOutput(data) +} + +type PackageManifest struct { + ContractVersion string `json:"contract_version"` + Module string `json:"module"` + Version string `json:"version"` + Description string `json:"description"` + Agents []AgentManifest `json:"agents"` +} + +// Package contains code and metadata distributed as an ordinary Go module. +// A version is an exact identity, not a runtime dependency-resolution request. +type Package struct { + module, version, description string + definitions []Definition +} + +var versionPattern = regexp.MustCompile(`^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$`) +var modulePattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._~/-]*$`) + +// ValidateIdentity checks a portable module path and exact semantic version. +func ValidateIdentity(module, version string) error { + if !modulePattern.MatchString(module) || path.Clean(module) != module || !strings.Contains(module, "/") { + return fmt.Errorf("invalid package module %q", module) + } + for _, segment := range strings.Split(module, "/") { + if segment == "." || segment == ".." { + return fmt.Errorf("invalid package module %q", module) + } + } + if !versionPattern.MatchString(version) { + return fmt.Errorf("package version must be a v-prefixed semantic version") + } + prerelease := strings.SplitN(strings.SplitN(version, "+", 2)[0], "-", 2) + if len(prerelease) == 2 { + for _, identifier := range strings.Split(prerelease[1], ".") { + if len(identifier) > 1 && identifier[0] == '0' && strings.Trim(identifier, "0123456789") == "" { + return fmt.Errorf("numeric prerelease identifiers cannot have leading zeros") + } + } + } + return nil +} + +func NewPackage(module, version, description string, definitions ...Definition) (Package, error) { + if err := ValidateIdentity(module, version); err != nil { + return Package{}, err + } + if strings.TrimSpace(description) == "" || len(definitions) == 0 { + return Package{}, fmt.Errorf("package description and at least one agent are required") + } + seen := make(map[string]bool) + for _, definition := range definitions { + if definition.validateInput == nil || seen[definition.manifest.Name] { + return Package{}, fmt.Errorf("uninitialized or duplicate agent %q", definition.manifest.Name) + } + seen[definition.manifest.Name] = true + } + return Package{module, version, description, append([]Definition(nil), definitions...)}, nil +} + +func (p Package) Manifest() PackageManifest { + m := PackageManifest{ContractVersion, p.module, p.version, p.description, make([]AgentManifest, len(p.definitions))} + for i, definition := range p.definitions { + m.Agents[i] = definition.Manifest() + } + return m +} + +func (p Package) Definitions() []Definition { return append([]Definition(nil), p.definitions...) } + +// AgentID qualifies an entry point with its module path. One version of a module +// may be registered in a host; the thread separately pins the package version. +func (p Package) AgentID(name string) string { return p.module + "#" + name } diff --git a/pkg/agentspec/spec_test.go b/pkg/agentspec/spec_test.go new file mode 100644 index 0000000..ca1487a --- /dev/null +++ b/pkg/agentspec/spec_test.go @@ -0,0 +1,154 @@ +// Copyright (c) 2024 GoLangGraph Team +// +// Licensed under the MIT License. See LICENSE file in the project root for full license information. +// +// Package: GoLangGraph - A powerful Go framework for building AI agent workflows + +package agentspec_test + +import ( + "context" + "encoding/json" + "fmt" + "strings" + "testing" + + "github.com/UnicoLab/GoLangGraph/pkg/agentspec" +) + +type request struct { + Text string `json:"text"` + Limit int `json:"limit,omitempty"` +} + +func (r request) Validate() error { + if strings.TrimSpace(r.Text) == "" { + return fmt.Errorf("text cannot be blank") + } + return nil +} + +type response struct { + Items []string `json:"items"` +} + +func config() agentspec.AgentConfig { + return agentspec.AgentConfig{Name: "sample", Description: "Sample agent", Prompt: agentspec.Prompt{ + System: "Answer with JSON", Model: agentspec.Model{Provider: "test", Name: "model", MaxTokens: 100}, + }} +} + +func TestTypedContractValidatesActualWireValues(t *testing.T) { + definition, err := agentspec.NewAgent[request, response](config()) + if err != nil { + t.Fatal(err) + } + for _, input := range []string{`{}`, `null`, `{"text":null}`, `{"text":42}`, `{"text":" "}`, `{"text":"hi","extra":true}`, `{"text":"hi","limit":1.5}`, `{"text":"hi"} {}`} { + t.Run(input, func(t *testing.T) { + if err := definition.ValidateInput(json.RawMessage(input)); err == nil { + t.Fatalf("accepted invalid input: %s", input) + } + }) + } + if err := definition.ValidateInput(json.RawMessage(`{"text":"hello"}`)); err != nil { + t.Fatal(err) + } + if err := definition.ValidateOutput(json.RawMessage(`{"items":["hello"]}`)); err != nil { + t.Fatal(err) + } + for _, output := range []string{`{}`, `{"items":null}`, `{"items":[1]}`} { + if err := definition.ValidateOutput(json.RawMessage(output)); err == nil { + t.Fatalf("accepted invalid output: %s", output) + } + } +} + +func TestManifestMutationCannotChangeDefinition(t *testing.T) { + definition, err := agentspec.NewAgent[request, response](config()) + if err != nil { + t.Fatal(err) + } + pkg, err := agentspec.NewPackage("example.com/agents/sample", "v0.1.0", "Example package", definition) + if err != nil { + t.Fatal(err) + } + manifest := pkg.Manifest() + delete(manifest.Agents[0].InputSchema.Properties, "text") + manifest.Agents[0].InputSchema.Required[0] = "corrupted" + *manifest.Agents[0].InputSchema.AdditionalProperties = true + manifest.Agents[0].Prompt.System = "corrupted" + if err := definition.ValidateInput(json.RawMessage(`{"text":"hello"}`)); err != nil { + t.Fatal(err) + } + fresh := pkg.Manifest().Agents[0] + if fresh.InputSchema.Required[0] != "text" || *fresh.InputSchema.AdditionalProperties || fresh.Prompt.System != "Answer with JSON" { + t.Fatalf("manifest leaked mutable definition state: %+v", fresh) + } + data, err := json.Marshal(pkg.Manifest()) + if err != nil || !strings.Contains(string(data), agentspec.ContractVersion) { + t.Fatalf("manifest is not serializable: %s, %v", data, err) + } +} + +type fakeState struct{} + +func (fakeState) ThreadID() string { return "thread" } +func (fakeState) GetValue(string) (json.RawMessage, bool) { return nil, false } +func (fakeState) SetValue(string, json.RawMessage) error { return nil } + +func TestToolValidatesBeforeAndAfterExecution(t *testing.T) { + calls := 0 + tool, err := agentspec.NewTool("search", "Search documents", func(_ context.Context, _ agentspec.State, input request) (response, error) { + calls++ + return response{}, nil // A nil slice cannot satisfy the advertised array schema. + }) + if err != nil { + t.Fatal(err) + } + if _, err := tool.Execute(context.Background(), fakeState{}, json.RawMessage(`{}`)); err == nil || calls != 0 { + t.Fatalf("invalid input reached tool: calls=%d, err=%v", calls, err) + } + if _, err := tool.Execute(context.Background(), fakeState{}, json.RawMessage(`{"text":"hello"}`)); err == nil || calls != 1 { + t.Fatalf("invalid output accepted: calls=%d, err=%v", calls, err) + } + ctx, cancel := context.WithCancel(context.Background()) + cancel() + if _, err := tool.Execute(ctx, fakeState{}, json.RawMessage(`{"text":"hello"}`)); err == nil || calls != 1 { + t.Fatalf("canceled invocation reached tool: calls=%d, err=%v", calls, err) + } +} + +func TestUnsupportedSchemasAndInvalidDefinitionsFailEarly(t *testing.T) { + type pointerInput struct { + Text *string `json:"text"` + } + type binaryInput struct { + Data []byte `json:"data"` + } + if _, err := agentspec.NewAgent[pointerInput, response](config()); err == nil { + t.Fatal("accepted pointer schema") + } + if _, err := agentspec.NewAgent[binaryInput, response](config()); err == nil { + t.Fatal("accepted ambiguous binary schema") + } + bad := config() + bad.MaxModelCalls = -1 + if _, err := agentspec.NewAgent[request, response](bad); err == nil { + t.Fatal("accepted invalid loop budget") + } + definition, err := agentspec.NewAgent[request, response](config()) + if err != nil { + t.Fatal(err) + } + for _, version := range []string{"latest", "v1", "v01.0.0", "v1.0.0-01"} { + if _, err := agentspec.NewPackage("example.com/a", version, "test", definition); err == nil { + t.Fatalf("accepted invalid version %s", version) + } + } + if _, err := agentspec.NewPackage("example.com/a", "v0.1.0", "test", definition, definition); err == nil { + t.Fatal("accepted duplicate entry point") + } + if _, err := agentspec.NewPackage("example.com/a#b", "v0.1.0", "test", definition); err == nil { + t.Fatal("accepted ambiguous package namespace") + } +}