FlowCraft: A Go Workspace for AI Agents, Split Into Independently Versioned Modules

The problem FlowCraft addresses: provider lock-in inside agent code

Most agent codebases start by calling one vendor's SDK directly from business logic. The model client, the tool dispatch and the conversation state all end up in the same package, and swapping providers later means editing the call sites. FlowCraft's answer is a contracts-first layout. The README states the goal plainly: build and evaluate AI applications "without tying application code to one model provider or execution model." The unit of that decoupling is the Go module, and the README is explicit that "library layers are independently versioned Go modules; applications adopt only the layers they need." That is a real constraint on how you consume it. You are not importing one monolith. You are choosing a set of modules and wiring them, and the versioning of each layer moves on its own schedule. The intended audience is a Go team building an agent product that may need to change model vendors, add long-term memory, or expose a voice interface without rewriting the execution path. It is not aimed at someone who wants a hosted agent API or a Python notebook.

How the layering actually works: core owns contracts, everything else depends on it

The architecture section gives a one-directional rule. Execution contracts live in core/agent, which owns Engine, Host, Board, Run, Interrupt and Checkpoint, and that package is a leaf: "agent does not import graph or tool packages." core/graph sits above it and compiles declarative graphs into agent.Engine implementations, so a graph is one way to produce an engine rather than the only way. The README makes this point directly: "Graphs are one built-in option, not a required architecture." Memory follows the same shape as inference. core/memory defines the capability contracts (ContextProvider, TurnSink, DocumentSink, ContextRenderer, Scope, Turn) plus generic glue: a memory.Assembly deploy resource that dispatches to implementations by impl: name, the memory.context and memory.turn agent-lifecycle hooks, and a GoTemplate context renderer. core/inference is generic and each provider is a registered factory. Memory implementations register the same way, each under its own impl: name with its own parameters. The README notes that "the flowcraft memory module is one such app-registered implementation," which means the contracts ship in core but a working long-term memory store is a separate thing you have to bring. The module map confirms the distribution boundary: driver/* for provider adapters (Anthropic, Azure, ByteDance, DeepSeek, Kimi, MiniMax, OpenAI, Qwen), backends/* for platform implementations such as SQLite checkpoints, with the sandbox backends (bwrap, seatbelt) living inside core/sandbox rather than in backends.

Getting it running: the forge demo first, the embedded path second

There are two entry points and the README orders them. The first is the runnable demo in examples/forge, which builds workspaces from "native deploy/inference/memory scenario documents" and also offers an interactive TUI, scripted tests and raid × persona simulation. The commands are given verbatim:

cd examples/forge go run . help go run . workspace create --config werewolf --workspace ./workspace go run . test -test werewolf/opening_setup

The second command creates a workspace from the werewolf scenario; the third runs a scripted test against it. Credentials and the full command reference are not in the root README. They live in examples/forge/README.md, with a Chinese version at examples/forge/README_zh.md. That is the first thing to open, because the demo cannot reach a provider without keys.

The second entry point is embedding. You call deploy.Parse on a deploy.yaml document, hand it to a runtime builder, and open a session through core/runtime/session. The README's snippet shows the shape: deploy.Parse(deployYAML), then runtimeBuilder.Build(ctx, document) with a deferred app.Close(), then app.Sessions().Open(ctx, session.Key{AgentID: "assistant", ContextID: "conversation-1"}), then lease.Session().Start(ctx, agent.Request{Message: message.NewTextMessage(message.RoleUser, "hello")}, session.SinkSpec{ID: "console", Sink: streamSink}), then turn.Wait(ctx). Note the sink: streaming output is a SinkSpec you supply, not something the library assumes. The README points to docs/guides/deploy.md and docs/guides/runtime.md for the full assembly and session contracts, and those two files are where the config keys for a real deployment will be defined. The root README does not enumerate them.

Where the design pushes work onto you

The same laziness that keeps core small pushes obligations outward. Because core owns only memory contracts and glue, and because the README describes the flowcraft memory module as an app-registered implementation, a team that wants long-term memory must either find that module or write an implementation satisfying ContextProvider, TurnSink, DocumentSink, ContextRenderer, Scope and Turn, then register it under an impl: name so memory.Assembly can dispatch to it. That is a non-trivial surface to implement correctly, and the README does not describe a default store. The backends listing is similarly narrow: the module map mentions SQLite checkpoints for backends/*, so checkpointing has a concrete option while other persistence choices are yours. There is also a toolchain floor. The README badge states Go 1.26+, which is a recent requirement and will rule out older build images. Finally, no releases were retrieved for this repository. The quickstart tells you to run from examples/forge on the main branch, and the README does not present a tagged version to pin. For a library you embed in a service, that matters more than any feature list: you would be tracking main until tags appear, or vendoring a commit.

How this differs from Python-first agent frameworks

The obvious comparison is a Python agent framework such as LangChain or LlamaIndex, where the agent loop, the retrievers and the provider clients live in one installable package and the ecosystem of integrations is large. The difference is not feature parity, it is where the boundary sits. Those projects tend to make the framework the integration point: you write your application against their abstractions and their release cadence. FlowCraft inverts that. The contracts are small and live in core; adapters are separate modules that depend on core and never the reverse. In practice this means a Go service can define its own memory store or its own provider adapter without forking the framework, which is the property the layering rule is there to protect. The cost is the inverse of the benefit: there is no large catalogue of ready-made integrations to drop in, and the README does not claim one. If your team is Python-native and the agent is the product, a Python framework will get you to a working prototype with less assembly. If the agent is a component inside an existing Go backend, FlowCraft's module split maps onto how that codebase is probably already organised.

Maintenance, versioning and the MIT licence

Two maintenance facts are visible. First, tools/releasegate exists for release automation: changeset validation, release planning and changelog aggregation. That is a sign the project intends a release process, but the repository shows no releases retrieved, so the process has not yet produced something to pin. Second, the modules are independently versioned, which cuts both ways: you can upgrade a driver without touching core, and you can also end up resolving a set of module versions that were not tested together. The repository's last push is dated 2026-09-10 and it is not archived, so the project is active at that timestamp. On licensing, the repository is MIT, which is permissive and places few obligations on how you distribute a binary that links the modules. This is a description of the licence identifier, not legal advice; if you are redistributing in a regulated or commercial context, read the LICENSE file and get your own review. The README does not describe a support commitment, a compatibility policy across module versions, or a deprecation window, and those are the questions to settle before a production dependency.

Who should take this on, and what to check first

FlowCraft fits a Go team that has already decided the agent loop belongs in-process, next to the rest of its services, and that wants the execution contracts (Engine, Host, Board, Run, Interrupt, Checkpoint) plus the deploy and runtime assembly rather than an HTTP wrapper around them. It also fits a team that expects to swap providers, since driver/* covers Anthropic, OpenAI, DeepSeek, Qwen and others behind one generic inference layer. It fits less well if you need a batteries-included memory store today, if you cannot move to Go 1.26+, or if your release process requires pinning a tagged version and the repository has none. The concrete first step is the same for everyone: clone the repository, cd examples/forge, run go run . help, then go run . workspace create --config werewolf --workspace ./workspace and go run . test -test werewolf/opening_setup, reading examples/forge/README.md for the credential setup. If that scenario runs and the deploy.yaml path in docs/guides/deploy.md matches how your service is configured, the module split is worth the assembly. If the demo stalls on a missing credential or an unresolved impl: name, you have found the boundary of what ships in core before you have written any application code.

Editorial conclusion

Adopt FlowCraft if your application is already written in Go and you want the execution contracts, the runtime and the session lifecycle in your own process rather than behind an HTTP service. Do not adopt it if you need a stable tagged release to pin against, since no releases were retrieved for this repository and the README points at the main branch, or if your stack is Python and your team would be maintaining a Go service purely to reach these packages. Before committing, verify three things: that the Go 1.26+ toolchain requirement in the README badge is acceptable for your build images, that the memory implementation you intend to use registers under an impl: name you can actually obtain (core ships only the contracts and glue, and the flowcraft memory module is described as app-registered), and that examples/forge runs end to end on your machine with go run . test -test werewolf/opening_setup after you supply credentials. The layering rule is the part worth copying even if you do not adopt the library.

Official sources

1. GizClaw/flowcraft on GitHub
2. Issues
3. License: MIT
4. Project website
5. README