FlowCraft
Go SDK for building AI agents with long-term memory, knowledge retrieval, runtime orchestration, and voice. Source on github.com/GizClaw/flowcraft.
Guides
Runtime
- Graph Engine —
core/agent-graph: an agent as a frontier loop over nodes — declared state with merge rules, conditions compiled at build, node kinds, checkpoints and replay. - Tool System —
core/tool: LLM function-calling contract, Registry / Catalog / Executor split, middleware chain, built-in tool adapters and the MCP bridge. - Agent Skills —
core/skill: SKILL.md discovery and parsing, BM25 ranking over names and descriptions, and the per-turn## Skillssection; lifecycle and authoring stay with the caller. - Application Runtime —
core/runtime: one runtime per configuration document (provider, tools, sandbox, files, skills, journal) and everything it built. - Checkpoints —
core/agent: the store contract — a task projection plus an append-only event log, two version counters, blobs, and the SQLite backend. - Hooks —
agent.Hooks: the three host boundaries of a turn (OnSession,BeforeTurn,AfterTurn), their failure policy, and how a deployment declares its own hook kinds. - Media & Attachments —
core/message: the sealed part vocabulary, thecore/message/mediavalue types, and the budgets a payload meets on its way into a request.
State and execution boundary
- Sandbox —
core/sandbox: agent execution boundary, env / net / resources policy, backends (local / seatbelt / bwrap / windows), per-call permission, decorators, escalation, and the file journal. - Remote Sandbox —
core/sandbox-remote: the sameRunneracross a host boundary — HTTP or unix socket, cursor reads, SSE events, retry rules.
Assembly
- Inference Runtime — generate / embed / decide over one addressing scheme: the deployment block, host-supplied drivers and selectors, model declarations, routing and retry, typed extensions.
- Deployment Assembly —
core/deploy: the deployment document, the engine / protocol / hook kind tables, and oneLoaderthat validates a deployment without building it.
Delegation
- Delegation —
core/delegation: one agent handing work to another — a policy over the session table, derived child sessions, sync / async execution, and the lineage a chain keeps.
Cross-cutting
- Context Registry — the values
corecarries oncontext.Context: one row per value with its key file, its writer and readers, lifetime and override rule, the rules the set holds to, and the gate that keeps the table and the source in step.
Migrations
core/v0.10.0— panic recovery is on by default and enforced at the fan-out boundaries,concurrency.limitmust be positive, the keychain store is one handle per directory,Reloadapplies session limits with the swap, and checkpoints are written incrementally.core/v0.9.0— the typed assembly protocol:Factory[T],Dep[T], a puredeploy.Planphase, and typed reads of built resources.core/v0.1.0— the breaking cut fromsdk/sdkxto thecoreplatform module, providerdriver/*modules, and platform-specificbackends/*.- One driver per wire family —
the consolidation that folded the Azure, DeepSeek and Kimi drivers into
driver/openai, moved MiniMax's Messages surface todriver/anthropic, and removeddriver/qwen. - One driver module — the six provider
modules folded into a single
drivermodule; the import paths and theimpl:ids are unchanged and only thego.modrequirement moved. - Keychain into
core/secret— thebackends/secretmodule folded intocore; theimpl: keychaindeployment id is unchanged and only the Go import path moved.
Older sdk/sdkx migration notes remain in docs/migrations/ as
historical reference and are not part of the current core migration path.
Layered architecture
The repository is organised as independently released Go modules, and core is
layered: a package imports only from the layers below it.
| Layer | Packages | Responsibility |
|---|---|---|
| Contracts | core/message (+media), core/errdefs, core/permission, core/fsx, core/skill, core/correlation |
The vocabulary every other layer speaks: messages, error classes, permissions, file handles, skills, the run identity. |
| Inference | core/inference (+model, outcome, protocol, route), core/inference-openai, core/inference-anthropic |
Model contracts, routing, and the two protocol families that ship with the platform. |
| Tools | core/tool (+engine, middleware), core/tool-builtin/*, core/tool-mcp |
The function-calling contract, the projection, and the built-in adapters. |
| Sandbox | core/sandbox (+engine, journal, netpolicy), core/sandbox-* |
The command boundary: contract, policy decorators, backends. |
| Execution | core/agent (+checkpoint), core/agent-graph, core/agent-a2a, core/delegation |
Runs: the engine contract, the graph engine, the A2A client, delegation. |
| Assembly | core/runtime |
One runtime per configuration document, owning what it built. |
| Deployment | core/deploy (+engines/*, protocols/*, builtin), core/agent-host |
Documents and kind tables; host bindings, sessions, lifecycle. |
| Observability | core/telemetry |
Tracing, run records, attributes. |
core/internal/... holds module-private helpers and is never importable outside
core.
Repository layout
core/ Platform module (contracts, inference, tools, sandbox, runtime, deploy)
driver/ Provider adapters that are not protocol families (bytedance, dashscope, minimax)
examples/ forge (graph demo, a workspace member) · parallel (outside consumer)
skills/ flowcraft-deploy: reference cards, templates, validator
tools/ Release gate, fuzz and stress scripts
Getting started
go get github.com/GizClaw/flowcraft/core@latest
Every package carries a doc.go stating what it is and what it deliberately is
not; start there, then read the guide above for the layer you are wiring.