go-kratos/blades: a Go agent framework built around one Agent interface

What Blades solves for Go teams building agents

Most agent frameworks arrive as Python packages or hosted services. A Go service that wants an agent then has to bridge two runtimes or call out to something it does not control. Blades takes the other route: it is a Go module, github.com/go-kratos/blades, that you import into a normal Go program.

The README frames the project as "a multimodal AI Agent framework for the Go language, supporting custom models, tools, memory, middleware, etc." and lists multi-turn conversations, chain-of-thought reasoning and structured output as the intended use cases. The audience is therefore a Go engineer who already knows how to lay out a service and wants the agent parts to be ordinary packages rather than a separate platform.

The project also comes from the go-kratos organisation, and the README says the middleware design draws on Kratos's middleware philosophy. If your team already runs Kratos services, the mental model transfers. If you have never used Kratos, nothing in the README suggests you need it; the dependency list in go.mod is small, and the module requires Go 1.25.0.

One Run method behind agents, chains and model providers

The central design decision is that a single interface, Agent, defines every executable component. The README quotes it: Name, Description and Run, where Run takes a context and an Invocation and returns a Generator of Message values. Agents, Chains and ModelProviders all implement it, so they compose like the README's Lego-brick analogy rather than through separate orchestration APIs.

ModelProvider is the adapter layer. Its interface has two methods: Generate for a complete response and NewStreaming, which returns a Generator immediately so the caller can consume model output step by step. That split matters because it forces a decision at the call site: buffered responses and typewriter-style streaming are different code paths, not a flag.

Around that core sit the components named in the README: Prompt for templated input with variable substitution, Tool for external capabilities with an InputSchema that guides the model and a Handle function that executes, Memory for short-term or long-term context, and Middleware for cross-cutting control. Flow orchestrates multiple Agents so that one Agent's output becomes the next one's input. The repository layout matches this: agent.go, model.go, tool.go, middleware.go, session.go and compressor.go at the top level, with flow/, graph/, memory/, middleware/, skills/, tools/, recipe/ and evaluator/ as subpackages. The graph examples (graph-checkpoint, graph-conditional, graph-parallel, graph-retry) indicate that multi-step control flow with checkpoints and retries is exercised in code, though the README excerpt does not describe those semantics in prose.

Installing Blades and running a first example

Blades is a library, not a binary, so installation means adding the module to a Go project. The module path and Go version come from go.mod: the module is github.com/go-kratos/blades and it declares go 1.25.0, so a toolchain at least that new is required.

go get github.com/go-kratos/blades

After that, the fastest way to see the framework run is the examples module, which has its own go.mod and go.sum. The Makefile defines an examples target that runs several programs from inside that directory, including prompt-basic, prompt-invocation, prompt-instructions, streaming, tools-func and tools-streaming.

cd examples
go run ./prompt-basic/main.go

The README does not reproduce those programs inline, so the example directories are the real documentation for a first run. Expect to supply model credentials before anything produces output: the repository has examples/model-claude, examples/model-gemini and examples/model-image, and the ModelProvider interface is where a provider is wired in. The Makefile also shows the maintenance commands the project uses on itself, and they are worth copying for a fork or a vendored checkout.

make tidy
make build
make test

The test target runs go test -race across every directory containing a go.mod, which is a reasonable signal that the project treats concurrent agent execution as a first-class concern. The README does not document environment variable names or default ports for any provider, so read the example you intend to adapt before assuming a configuration shape.

Where Blades is the wrong tool

Blades gives you interfaces, not an application. There is no server binary in the repository root, no admin UI and no hosted control plane described in the README. If what you want is a running agent you can chat with after a one-line install, this is the wrong project; you would be writing the service yourself.

The abstraction has a cost. Every capability has to be expressed through the Agent and ModelProvider contracts, and anything the interfaces do not model has to be added as middleware or a new component. For a single prompt sent to a single model, the framework is more structure than the task needs. The README's own framing, chain-of-thought reasoning and multi-turn conversation, describes the scale at which the abstraction starts paying for itself.

Version maturity is the other constraint. The releases listed are v0.3.1, v0.4.0 and v0.5.0, all pre-1.0, and the last push to the repository was on 2026-08-14. Pre-1.0 Go modules are free to change exported types between minor versions, and nothing in the README promises API stability. The README also does not document a migration guide between releases, so an upgrade from v0.4.0 to v0.5.0 is something you verify against your own call sites rather than against a published changelog in the documentation available here.

Blades compared with a Python agent framework

The obvious alternative for an agent project is a Python framework such as LangChain, and the difference is not features but runtime. A Python framework assumes your agent logic lives in a Python process, with the model SDKs, the tool implementations and the orchestration all in that process. Blades assumes the opposite: your agent logic is a Go package inside the service that already handles your traffic.

That changes what a tool is. In Blades, a Tool carries an InputSchema for the model and a Handle function for execution, so a tool can call code that shares memory with the rest of your Go service rather than crossing a process boundary. The same applies to Memory and Middleware: they are Go interfaces, and middleware is described as following the Kratos pattern, so observability and guardrails attach the way they would to an HTTP handler. The repository backs this up with examples/middleware-otel, examples/middleware-retry and examples/middleware-confirmation.

The trade-off runs the other way too. Python has the larger ecosystem of model clients, integrations and examples, and a team already fluent in Python will move faster there. Choosing Blades means accepting a smaller set of ready-made integrations in exchange for one runtime and one deployment artifact. The repository's contrib/ directory exists for exactly that kind of extension, but the README does not enumerate what it contains.

Licence, upkeep and what an upgrade costs

Blades is MIT licensed, and the repository carries a LICENSE file at the root. MIT is permissive: it allows commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the general shape of the licence, not legal advice; if your organisation has a policy on dependency licences, route the LICENSE file through it rather than relying on this summary.

The dependency surface is small. go.mod requires github.com/go-kratos/kit, github.com/google/jsonschema-go, github.com/google/uuid, golang.org/x/sync and gopkg.in/yaml.v3. A short list is easier to audit than a deep tree, and it means a security review of Blades is mostly a review of this module plus the model SDKs you add yourself.

Upkeep is the part to plan for. The last push was on 2026-08-14, and the newest release, v0.5.0, was published on 2026-04-02, with v0.4.0 on 2026-03-02 and v0.3.1 on 2025-12-05. Those dates show a project that has been shipping within the past year, but the pre-1.0 version numbers mean an upgrade can touch exported interfaces. The practical cost of a bump is the number of places your code implements Agent or ModelProvider. Keeping those implementations thin, and putting provider-specific logic behind the ModelProvider adapter as the README intends, is what keeps a v0.5.0-to-v0.6.0 move small. The README does not document a deprecation policy, so treat each release's diff as the source of truth.

Editorial conclusion

Adopt Blades if your stack is Go and you want agents, chains and model providers to share one Run interface you can compose yourself. Do not adopt it if you need a hosted agent runtime, a GUI, or a framework whose API has stopped moving; the last push was 2026-08-14 and the newest release, v0.5.0, dates from 2026-04-02. Before writing production code, read agent.go, model.go and tool.go in the repository and run one example under examples/ against your own model endpoint to confirm the streaming and tool-call behaviour you depend on.

Frequently asked questions

Official sources

1. go-kratos/blades on GitHub
2. License: MIT
3. Project website
4. README
5. Releases